This project is a pure Java implementation of an SDK that works with the XRP Ledger. This library supports XRPL key
and address generation, transaction serialization and signing, provides useful Java bindings for XRP Ledger objects and
rippled
request/response objects, and also provides a JSON-RPC client for interacting with XRPL nodes.
- Get Started Using Java: a tutorial for building a very simple XRP Ledger-connected app.
- Example usage can be found in the
xrpl4j-integration-tests
module here.
- JDK 1.8 or higher
- A Java project manager such as Maven or Gradle
You can use one or more xrpl4j modules in your Maven project by using the current BOM like this:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.xrpl4j</groupId>
<artifactId>xrpl4j-bom</artifactId>
<version>3.0.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
Then you can add one or both of the xrpl4j-core
and xrpl4j-client
modules
found in the BOM to your pom.xml
. For example:
<dependencies>
...
<dependency>
<groupId>org.xrpl</groupId>
<artifactId>xrpl4j-core</artifactId>
</dependency>
<dependency>
<groupId>org.xrpl</groupId>
<artifactId>xrpl4j-client</artifactId>
</dependency>
...
</dependencies>
This library provides Java objects modeling XRP Ledger Objects, Transactions, and request parameters/response results for the rippled API.
The objects in this module are annotated with @Value.Immutable
from
the immutables library, which generates immutable implementations with builders, copy
constructors, and other useful boilerplate code.
For example, the following code constructs an EscrowCreate
object, which represents
an EscrowCreate Transaction:
EscrowCreate escrowCreate = EscrowCreate.builder()
.account(Address.of("rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"))
.fee(XrpCurrencyAmount.ofDrops(12))
.sequence(UnsignedInteger.ONE)
.amount(XrpCurrencyAmount.ofDrops(10000))
.destination(Address.of("rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW"))
.destinationTag(UnsignedInteger.valueOf(23480))
.cancelAfter(UnsignedLong.valueOf(533257958))
.finishAfter(UnsignedLong.valueOf(533171558))
.condition(CryptoConditionReader.readCondition(
BaseEncoding.base16()
.decode("A0258020E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855810100"))
)
.sourceTag(UnsignedInteger.valueOf(11747))
.build();
These objects can be serialized to, and deserialized from, rippled
JSON representations using the provided
Jackson ObjectMapper
, which can be instantiated
using ObjectMapperFactory
.
Using the EscrowCreate
object created above, it is then possible to use the supplied ObjectMapper
to serialize to
JSON like this:
ObjectMapper objectMapper = ObjectMapperFactory.create();
String json = objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(escrowCreate);
System.out.println(json);
Which produces the following output:
{
"Account" : "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee" : "12",
"Sequence" : 1,
"SourceTag" : 11747,
"Flags" : 2147483648,
"Amount" : "10000",
"Destination" : "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"DestinationTag" : 23480,
"CancelAfter" : 533257958,
"FinishAfter" : 533171558,
"Condition" : "A0258020E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855810100",
"TransactionType" : "EscrowCreate"
}
Most operations using this library require some sort of private key material. Broadly speaking, the library supports
two mechanisms: (1) in-memory private keys, and (2) in-memory references to private keys where the actual private key
material lives in an external system (e.g., keys in a Hardware Security Module, or HSM). In Java, this is modeled
using the PrivateKeyable
interface, which has two subclasses: PrivateKey
and PrivateKeyReference
.
PrivateKey
represents a private key held in memory, existing in the same JVM that is executing xrpl4j code. This key
variant can be useful in the context of an android or native application, but is likely not suitable for server-side
application because private key material is held in-memory (for these scenarios, consider using a remote service like
an HSM).
For use-cases that require private keys to exist inside the running JVM, the following examples shows how to generate a keypair, and also how to derive an XRPL address from there:
import org.xrpl.xrpl4j.crypto.core.keys.Seed;
import org.xrpl.xrpl4j.crypto.core.keys.PrivateKey;
import org.xrpl.xrpl4j.crypto.core.keys.PublicKey;
import org.xrpl.xrpl4j.model.transactions.Address;
...
Seed seed = Seed.ed255519Seed(); // <-- Generates a random seed.
PrivateKey privateKey = seed.derivePrivateKey(); // <-- Derive a private key from the seed.
PublicKey publicKey = privateKey.derivePublicKey(); // <-- Derive a public key from the private key.
Address address = publicKey.deriveAddress(); // <-- Derive an address from the public key.
For applications with higher-security requirements, private-key material can be stored outside the JVM
using an external system that can simultaneously manage the key material and also perform critical signing operations
without exposing key material to the outside world (e.g., an HSM or cloud service provider). For these scenarios,
PrivateKeyReference
can be used.
This library does not provide an implementation that interacts with any particular external signing service or HSM.
However, developers wishing to support such interactions should extend PrivateKeyReference
for the particular external service, and implement
SignatureService for their PrivateKeyReference
type.
interface. In
addition, FauxGcpKmsSignatureServiceTest
and FauxAwsKmsSignatureServiceTest
illustrate faux variants of a simulated external key provider that can also be used for further guidance.
The main interface used to sign and verify transactions
is SignatureService,
which has two concrete implementations: BcSignatureService
and BcDerivedKeySignatureService
. The first uses
in-memory private key material to perform signing and validation operations, while the latter can be used to derive
multiple private keys using a single entropy source combined with differing unique key identifiers (e.g., User Ids).
The following example illustrates how to construct a payment transaction, sign it using an in-memory private key, and then submit that transaction to the XRP Ledger for processing and validation:
import org.xrpl.xrpl4j.crypto.core.keys.Seed;
import org.xrpl.xrpl4j.crypto.core.keys.KeyPair;
import org.xrpl.xrpl4j.crypto.core.keys.PrivateKey;
import org.xrpl.xrpl4j.crypto.core.keys.PublicKey;
import org.xrpl.xrpl4j.model.transactions.Address;
import org.xrpl.xrpl4j.crypto.core.signing.SignatureService;
import org.xrpl.xrpl4j.crypto.signing.bc.BcSignatureService;
// Construct a SignatureService that uses in-memory Keys (see SignatureService.java for alternatives).
SignatureService signatureService = new BcSignatureService();
// Sender (using ed25519 key)
Seed senderSeed = Seed.ed255519Seed();
PrivateKey senderPrivateKey = senderSeed.derivePrivateKey();
PublicKey senderPublicKey = senderPrivateKey.derivePublicKey();
Address senderAddress = senderPublicKey.deriveAddress();
// Receiver (using secp256k1 key)
Address receiverAddress = Address.of("r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59");
// Construct a Payment
Payment payment = ...; // See V3 ITs for examples.
SingleSignedTransaction<Payment> signedTransaction = signatureService.sign(sourcePrivateKey,payment);
SubmitResult<Payment> result = xrplClient.submit(signedTransaction);
assertThat(result.result()).isEqualTo("tesSUCCESS");
This library relies upon two important sub-modules called Codecs (One for the XRPL binary encoding, and one for XRPL canonical JSON encoding). Read more about each here:
Xrpl4j is structured as a Maven multi-module project, with the following modules:
- xrpl4j-core:
- Provides core primitives like seeds, public/private keys definitions (supports secp256k1 and ed25519 key types
and signing algorithms), signature interfaces, address and binary codecs etc. Also provides Java objects which model XRP Ledger objects,
as well as request parameters and response results for the
rippled
websocket and JSON RPC APIs. - Provides a Jackson
ObjectMapper
with JSON bindings that serialize and deserialize to and from the JSON representation of XRPL Transactions; this is used to move to and from the canonical binary format of the XRP Ledger.
- Provides core primitives like seeds, public/private keys definitions (supports secp256k1 and ed25519 key types
and signing algorithms), signature interfaces, address and binary codecs etc. Also provides Java objects which model XRP Ledger objects,
as well as request parameters and response results for the
- xrpl4j-client:
- Provides an example
rippled
JSON RPC client which can be used to communicate with arippled
node
- Provides an example
- xrpl4j-integration-tests:
- Contains the project's integration tests, which also serve as valuable xrpl4j usage examples for common XRPL flows.
You can build and test the entire project locally using maven from the command line:
mvn clean install
To build the project while skipping Integration tests, use the following command:
mvn clean install -DskipITs
To build the project while skipping Unit and Integration tests, use the following command:
mvn clean install -DskipITs -DskipTests