diff --git a/content/_code-samples/xrpl4j/GetAccountInfo.java b/content/_code-samples/xrpl4j/GetAccountInfo.java new file mode 100644 index 0000000000..cee418493c --- /dev/null +++ b/content/_code-samples/xrpl4j/GetAccountInfo.java @@ -0,0 +1,23 @@ +// Construct a network client +final HttpUrl rippledUrl = HttpUrl.get("https://s.altnet.rippletest.net:51234/"); +XrplClient xrplClient = new XrplClient(rippledUrl); + +// Create a Wallet using a WalletFactory + +final WalletFactory walletFactory = DefaultWalletFactory.getInstance(); +final Wallet testWallet = walletFactory.randomWallet(true).wallet(); + +// Get the Classic and X-Addresses from testWallet +final Address classicAddress = testWallet.classicAddress(); +final XAddress xAddress = testWallet.xAddress(); +System.out.println("Classic Address: " + classicAddress); +System.out.println("X-Address: " + xAddress); + +// Fund the account using the testnet Faucet +final FaucetClient faucetClient = FaucetClient.construct(HttpUrl.get("https://faucet.altnet.rippletest.net")); +faucetClient.fundAccount(FundAccountRequest.of(classicAddress)); + +// Look up your Account Info +final AccountInfoRequestParams requestParams = AccountInfoRequestParams.of(classicAddress); +final AccountInfoResult accountInfoResult = xrplClient.accountInfo(requestParams); +System.out.println(accountInfoResult); diff --git a/content/_code-samples/xrpl4j/SendPayment.java b/content/_code-samples/xrpl4j/SendPayment.java new file mode 100644 index 0000000000..fa4bff9ec5 --- /dev/null +++ b/content/_code-samples/xrpl4j/SendPayment.java @@ -0,0 +1,55 @@ +// Construct a network client +final HttpUrl rippledUrl = HttpUrl.get("https://s.altnet.rippletest.net:51234/"); +XrplClient xrplClient = new XrplClient(rippledUrl); + +// Create a Wallet using a WalletFactory +WalletFactory walletFactory = DefaultWalletFactory.getInstance(); +final Wallet testWallet = walletFactory.randomWallet(true).wallet(); +System.out.println("Generated a wallet with the following public key: " + testWallet.publicKey()); + +// Get the Classic and X-Addresses from testWallet +final Address classicAddress = testWallet.classicAddress(); +System.out.println("Classic Address: " + classicAddress); + +// Fund the account using the testnet Faucet +final FaucetClient faucetClient = FaucetClient.construct(HttpUrl.get("https://faucet.altnet.rippletest.net")); +faucetClient.fundAccount(FundAccountRequest.of(classicAddress)); +System.out.println("Funded the account using the Testnet faucet."); + +// Look up your Account Info +final AccountInfoRequestParams requestParams = AccountInfoRequestParams.of(classicAddress); +final AccountInfoResult accountInfoResult = xrplClient.accountInfo(requestParams); +final UnsignedInteger sequence = accountInfoResult.accountData().sequence(); + +// Request current fee information from rippled +final FeeResult feeResult = xrplClient.fee(); +final XrpCurrencyAmount openLedgerFee = feeResult.drops().openLedgerFee(); + +// Construct a Payment +Payment payment = Payment.builder() + .account(classicAddress) + .amount(XrpCurrencyAmount.ofXrp(BigDecimal.ONE)) + .destination(Address.of("rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe")) + .sequence(sequence) + .fee(openLedgerFee) + .signingPublicKey(testWallet.publicKey()) + .build(); + +// Print the Payment +System.out.println("Constructed Payment: " + payment); + +// Construct a SignatureService to sign the Payment +PrivateKey privateKey = PrivateKey.fromBase16EncodedPrivateKey(testWallet.privateKey().get()); +SignatureService signatureService = new SingleKeySignatureService(privateKey); + +// Sign the Payment +final SignedTransaction signedPayment = signatureService.sign(KeyMetadata.EMPTY, payment); + +// Print the signed transaction +System.out.println("Signed Payment: " + signedPayment.signedTransaction()); + +// Submit the Payment +final SubmitResult submitResult = xrplClient.submit(signedPayment); + +// Print the response +System.out.println(submitResult); diff --git a/content/tutorials/get-started/get-started-using-java.md b/content/tutorials/get-started/get-started-using-java.md new file mode 100644 index 0000000000..a1a8a52a8c --- /dev/null +++ b/content/tutorials/get-started/get-started-using-java.md @@ -0,0 +1,262 @@ +--- +html: get-started-using-java.html +funnel: Build +doc_type: Tutorials +category: Get Started +blurb: Build a simple Java app that interacts with the XRP Ledger. +cta_text: Build an XRP Ledger-connected app +filters: + - interactive_steps + - include_code +--- + +# Get Started Using Java + +This tutorial walks you through the basics of building a very simple XRP Ledger-connected application using [`xrpl4j`](https://github.com/XRPLF/xrpl4j), a pure Java library that makes it easy to interact with the XRP Ledger. + +This tutorial is intended for beginners and should take no longer than 30 minutes to complete. + +## Learning goals + +In this tutorial, you'll learn: + +* The basic building blocks of XRP Ledger-based applications. +* How to connect to the XRP Ledger using `xrpl4j`. +* How to generate a wallet on the [Testnet](xrp-testnet-faucet.html) using `xrpl4j`. +* How to use the `xrpl4j` library to look up information about an account on the XRP Ledger. +* How to put these steps together to create a simple Java app. + +## Requirements + +* The `xrpl4j` library supports Java 1.8 and later. +* A project management tool such as [Maven](https://maven.apache.org/) or [Gradle](https://gradle.org/). + + +## Installation + +The [`xrpl4j` library](https://github.com/XRPLF/xrpl4j) is available on [Maven Central](https://search.maven.org/artifact/org.xrpl/xrpl4j-parent). +`xrpl4j` is split into multiple artifacts, which can be imported as needed. + +In this tutorial, you will need the [xrpl4j-client](https://javadoc.io/doc/org.xrpl/xrpl4j-client/latest/index.html), +[xrpl4j-address-codec](https://javadoc.io/doc/org.xrpl/xrpl4j-address-codec/latest/index.html), +[xrpl4j-keypairs](https://javadoc.io/doc/org.xrpl/xrpl4j-keypairs/latest/index.html), and +[xrpl4j-model](https://javadoc.io/doc/org.xrpl/xrpl4j-model/latest/index.html) modules. + +Install with Maven: +```xml + + + org.xrpl + xrpl4j-client + 2.0.0 + + + org.xrpl + xrpl4j-address-codec + 2.0.0 + + + org.xrpl + xrpl4j-keypairs + 2.0.0 + + + org.xrpl + xrpl4j-model + 2.0.0 + + +``` + +## Start building +{% set n = cycler(* range(1,99)) %} + +When you're working with the XRP Ledger, there are a few things you'll need to manage, whether you're adding XRP into your [wallet](wallets.html), integrating with the [decentralized exchange](decentralized-exchange.html), or [issuing tokens](issued-currencies.html). This tutorial walks you through basic patterns common to getting started with all of these use cases and provides sample code for implementing them. + +Here are the basic steps you'll need to cover for almost any XRP Ledger project: + +1. [Connect to the XRP Ledger.](#1-connect-to-the-xrp-ledger) +1. [Generate a wallet.](#2-generate-wallet) +1. [Query the XRP Ledger.](#3-query-the-xrp-ledger) + + +### {{n.next()}}. Connect to the XRP Ledger + +To make queries and submit transactions, you need to establish a connection to the XRP Ledger. To do this with `xrpl4j`, +you can use an [`XrplClient`](https://javadoc.io/doc/org.xrpl/xrpl4j-client/latest/org/xrpl/xrpl4j/client/XrplClient.html): + +{{ include_code("_code-samples/xrpl4j/GetAccountInfo.java", start_with="// Construct a network client", end_before="// Create a Wallet using a WalletFactory", language="java") }} + +#### Connect to the production XRP Ledger + +The sample code in the previous section shows you how to connect to the Testnet, which is one of the available [parallel networks](parallel-networks.html). When you're ready to integrate with the production XRP Ledger, you'll need to connect to the Mainnet. You can do that in two ways: + +* By [installing the core server](install-rippled.html) (`rippled`) and running a node yourself (the core server connects to the Mainnet by default and you can [change the configuration to use an altnet](connect-your-rippled-to-the-xrp-test-net.html) ). [There are good reasons to run your own core server](the-rippled-server.html#reasons-to-run-your-own-server). If you run your own server, you can connect to it like so: + + final HttpUrl rippledUrl = HttpUrl.get("http://localhost:5005/"); + XrplClient xrplClient = new XrplClient(rippledUrl); + + See the example [core server config file](https://github.com/ripple/rippled/blob/c0a0b79d2d483b318ce1d82e526bd53df83a4a2c/cfg/rippled-example.cfg#L1562) for more information about default values. + +* By using one of the [available public servers](get-started-with-the-rippled-api.html#public-servers): + + final HttpUrl rippledUrl = HttpUrl.get("https://s2.ripple.com:51234/"); + XrplClient xrplClient = new XrplClient(rippledUrl); + +### {{n.next()}}. Generate wallet + +To store value and execute transactions on the XRP Ledger, you need to create a wallet: +a [set of keys](cryptographic-keys.html#key-components) and an [address](accounts.html#addresses) that's +been [funded with enough XRP](accounts.html#creating-accounts) to meet the [account reserve](reserves.html). +The address is the identifier of your account and you use the [private key](cryptographic-keys.html#private-key) to +sign transactions that you submit to the XRP Ledger. For production purposes, you should take care to store your keys and set up +a [secure signing method](set-up-secure-signing.html). + +For testing and development purposes, you can use the [XRP Faucets](xrp-testnet-faucet.html) to fund +an account on the Testnet or Devnet. + +To make it easy to generate a new, random Wallet, `xrpl4j` provides the [`DefaultWalletFactory`](https://javadoc.io/doc/org.xrpl/xrpl4j-keypairs/latest/org/xrpl/xrpl4j/wallet/DefaultWalletFactory.html). + +{{ include_code("_code-samples/xrpl4j/GetAccountInfo.java", start_with="// Create a Wallet using a WalletFactory", end_before="// Get the Classic and X-Addresses from testWallet", language="java") }} + + +The result of a call to `walletFactory.randomWallet(true).wallet()` is a [`Wallet` instance](https://javadoc.io/doc/org.xrpl/xrpl4j-keypairs/latest/org/xrpl/xrpl4j/wallet/Wallet.html): + +``` +System.out.println(testWallet); + +// print output +Wallet { + privateKey= -HIDDEN-, + publicKey=ED90635A6F2A5905D3D5CD2C14905FFB2D838185993576CA4CEE24A920D0D6BD6B, + classicAddress=raj5eirfEpbN9YzG9FzB8ZPNyjpFvH6ycV, + xAddress=T76mQFr9zLGi2LCjVDgJ7mEQCk4767SdEL32mZFygpdGcFf, + isTest=true +} +``` + +In order to fund the account on the XRP Ledger, you can use a `FaucetClient` connected to the XRPL Testnet: + +{{ include_code("_code-samples/xrpl4j/GetAccountInfo.java", start_with="// Fund the account using the testnet Faucet", end_before="// Look up your Account Info", language="java") }} + +#### Using the wallet + +In this tutorial we only query details about the generated account from the XRP Ledger, but you can use the values in the `Wallet` instance to prepare, sign, and submit transactions with `xrpl4j`. + +##### Prepare + +To prepare the transaction, first you'll need your account sequence: + +{{ include_code("_code-samples/xrpl4j/SendPayment.java", start_with="// Look up your Account Info", end_before="// Request current fee information from rippled", language="java") }} + +Next, you'll need up-to-date network fee information: + +{{ include_code("_code-samples/xrpl4j/SendPayment.java", start_with="// Request current fee information from rippled", end_before="// Construct a Payment", language="java") }} + +Finally, construct a `Payment` with that information: + +{{ include_code("_code-samples/xrpl4j/SendPayment.java", start_with="// Construct a Payment", end_before="// Print the Payment", language="java") }} + + +##### Sign + +To sign the transaction, you'll need an instance of [`SignatureService`](https://javadoc.io/doc/org.xrpl/xrpl4j-crypto-core/latest/org/xrpl/xrpl4j/crypto/signing/SignatureService.html). +In this case, you can construct a [`SingleKeySignatureService`](https://javadoc.io/doc/org.xrpl/xrpl4j-crypto-bouncycastle/latest/org/xrpl/xrpl4j/crypto/signing/SingleKeySignatureService.html) +using the private key from `testWallet`: + +{{ include_code("_code-samples/xrpl4j/SendPayment.java", start_with="// Construct a SignatureService to sign the Payment", end_before="// Sign the Payment", language="java") }} + +Then, sign the `Payment` using the `SignatureService`: + +{{ include_code("_code-samples/xrpl4j/SendPayment.java", start_with="// Sign the Payment", end_before="// Print the signed transaction", language="java") }} + +##### Submit + +To submit the transaction: + +{{ include_code("_code-samples/xrpl4j/SendPayment.java", start_with="// Submit the Payment", end_before="// Print the response", language="java") }} + +### {{n.next()}}. Query the XRP Ledger + +You can query the XRP Ledger to get information about [a specific account](account-methods.html), [a specific transaction](tx.html), the state of a [current or a historical ledger](ledger-methods.html), and [the XRP Ledger's decentralized exhange](path-and-order-book-methods.html). You need to make these queries, among other reasons, to look up account info to follow best practices for [reliable transaction submission](reliable-transaction-submission.html). + +Here, we'll use the [`XrplClient` we constructed](#1-connect-to-the-xrp-ledger) to look up information about the [wallet we generated](#2-generate-wallet) in the previous step. + +{{ include_code("_code-samples/xrpl4j/GetAccountInfo.java", start_with="// Look up your Account Info", language="java") }} + + +### {{n.next()}}. Putting it all together + +Using these building blocks, we can create a simple Java app that: + +1. Generates a wallet on the Testnet. +2. Connects to the XRP Ledger. +3. Looks up and prints information about the account you created. + + +```java +{% include '_code-samples/xrpl4j/GetAccountInfo.java' %} +``` + +To run the app, you can download the code from [Github](https://github.com/XRPLF/xrpl4j-sample) and run `GetAccountInfo` either +from your IDE or from the command line. + +```sh +git clone https://github.com/XRPLF/xrpl4j-sample.git +cd xrpl4j-sample +mvn compile exec:java -Dexec.mainClass="org.xrpl.xrpl4j.samples.GetAccountInfo" +``` + +You should see output similar to this example: + +```sh +Running the GetAccountInfo sample... +Constructing an XrplClient connected to https://s.altnet.rippletest.net:51234/ +Generated a wallet with the following public key: ED015D922B5EACF09DF01168141FF27FA6229B0FAB9B4CD88D2B6DA036090EFAA4 +Classic Address: rBXHGshqXu3Smy9FUsQTmo49bGpQUQEm3X +X-Address: T7yMiiJJCmgY2yg5WB2davUedDeBFAG5B8r9KHjKCxDdvv3 +Funded the account using the Testnet faucet. +AccountInfoResult{ + status=success, + accountData=AccountRootObject{ + ledgerEntryType=ACCOUNT_ROOT, + account=rBXHGshqXu3Smy9FUsQTmo49bGpQUQEm3X, + balance=1000000000, + flags=0, + ownerCount=0, + previousTransactionId=0000000000000000000000000000000000000000000000000000000000000000, + previousTransactionLedgerSequence=0, + sequence=17178149, + signerLists=[], + index=0DC1B13C73A7F3D2D82446526D0C5D08E88F89BA442D54291117F1A08E447685 + }, + ledgerCurrentIndex=17178149, + validated=false +} +``` + +#### Interpreting the response + +The response fields contained in `AccountInfoResult` that you want to inspect in most cases are: + +* `accountData.sequence` — This is the sequence number of the next valid transaction for the account. You need to specify the sequence number when you prepare transactions. With `xrpl-py`, you can use the [`get_next_valid_seq_number`](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.account.html#xrpl.account.get_next_valid_seq_number) to get this automatically from the XRP Ledger. See an example of this usage in the project [README](https://github.com/XRPLF/xrpl-py#serialize-and-sign-transactions). + +* `accountData.balance` — This is the account's balance of XRP, in drops. You can use this to confirm that you have enough XRP to send (if you're making a payment) and to meet the [current transaction cost](transaction-cost.html#current-transaction-cost) for a given transaction. + +* `validated` — Indicates whether the returned data is from a [validated ledger](ledgers.html#open-closed-and-validated-ledgers). When sending transactions, it's important to ensure that the results are in a [final](finality-of-results.html) state in a validated ledger before further processing the transaction. For more information about best practices for transaction processing, see [Reliable Transaction Submission](reliable-transaction-submission.html). + +For a detailed description of every response field, see [account_info](account_info.html#response-format). + + +## Keep on building + +Now that you know how to use `xrpl4j` to connect to the XRP Ledger, generate a wallet, and look up information about an account, you can also use `xrpl4j` to: + +* [Send XRP](send-xrp.html). +* [Set up secure signing](set-up-secure-signing.html) for your account. + + + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/dactyl-config.yml b/dactyl-config.yml index f8aeaa52e4..edd014b62b 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -1594,6 +1594,10 @@ pages: targets: - en - ja + - md: tutorials/get-started/get-started-using-java.md + targets: + - en + - ja - md: tutorials/get-started/get-started-with-the-rippled-api.md html: get-started-with-the-rippled-api.html