xrpl4j: A 100% Java SDK for the XRP Ledger

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.

Documentation

• 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.

Usage

Requirements

• JDK 1.8 or higher
• A Java project manager such as Maven or Gradle

Maven Installation

You can use one or more xrpl4j modules in your Maven project by using the current BOM like this:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.xrpl</groupId>
            <artifactId>xrpl4j-bom</artifactId>
            <version>4.0.2</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>

Core Objects

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"
}

Public/Private Key Material

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.

In-Memory Private Keys (PrivateKey)

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.keys.KeyPair;
import org.xrpl.xrpl4j.crypto.keys.PrivateKey;
import org.xrpl.xrpl4j.crypto.keys.PublicKey;
import org.xrpl.xrpl4j.crypto.keys.Seed;
import org.xrpl.xrpl4j.model.transactions.Address;

Seed seed = Seed.ed25519Seed(); // <-- Generates a random seed.
KeyPair keyPair = seed.deriveKeyPair(); // <-- Derive a KeyPair from the seed.
PrivateKey privateKey = keyPair.privateKey(); // <-- Derive a privateKey from the KeyPair.
PublicKey publicKey = keyPair.publicKey(); // <-- Derive a publicKey from the KeyPair.
Address address = publicKey.deriveAddress(); // <-- Derive an address from the publicKey

Private Key References (PrivateKeyReference)

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.

Signing and Verifying Transactions

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).

Construct and Sign an XRP Payment:

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.client.XrplClient;
import org.xrpl.xrpl4j.crypto.keys.PrivateKey;
import org.xrpl.xrpl4j.crypto.keys.Seed;
import org.xrpl.xrpl4j.crypto.signing.SignatureService;
import org.xrpl.xrpl4j.crypto.signing.SingleSignedTransaction;
import org.xrpl.xrpl4j.model.client.transactions.SubmitResult;
import org.xrpl.xrpl4j.model.transactions.Address;

import org.xrpl.xrpl4j.crypto.signing.bc.BcSignatureService;
import org.xrpl.xrpl4j.model.transactions.Payment;

// Construct a SignatureService that uses in-memory Keys (see SignatureService.java for alternatives).
SignatureService signatureService = new BcSignatureService();

// Sender (using ed25519 key)
Seed seed = Seed.ed25519Seed(); // <-- Generates a random seed.
PrivateKey senderPrivateKey = seed.deriveKeyPair().privateKey();
  
// 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);
assert result.engineResult().equals("tesSUCCESS");

Codecs

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:

• Binary Codec
• Address Codec

Development

Project Structure

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.
• xrpl4j-client:
  • Provides an example rippled JSON RPC client which can be used to communicate with a rippled node
• 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