go-xrpl

go-xrpl

Go implementation of the XRP Ledger protocol.

go-xrpl is an XRPL client written in Go. It provides the goxrpl node daemon, an importable set of protocol libraries, and developer tools for working with ledger data. The client can participate in the peer network, process transactions, maintain ledger state, take part in consensus, and expose JSON-RPC, WebSocket, and optional gRPC services.

The release branch targets private rippled v3.4.1. Release sign-off remains open until the merged candidate passes every required evidence gate. go-xrpl has its own architecture and software version policy.

[!IMPORTANT] go-xrpl is under active development. Review the operator guide and current generated capability catalogs before deploying it in production.

Building from source

Building goxrpl requires Go 1.24 or later, a C compiler, OpenSSL 3, libsecp256k1, and pkg-config. The examples use just as the task runner, with a raw Go command shown for environments where it is not installed.

On macOS:

brew install openssl@3 secp256k1 pkg-config just
export PKG_CONFIG_PATH="$(brew --prefix openssl@3)/lib/pkgconfig:$(brew --prefix secp256k1)/lib/pkgconfig"

On Debian or Ubuntu:

sudo apt install -y build-essential libssl-dev libsecp256k1-dev pkg-config

Build the node from the repository root:

just build

# Without just
go build -o ../tmp/goxrpl ./cmd/goxrpl

The binary is written to ../tmp/goxrpl. To compile every package without producing the node binary, run just build-all.

The daemon requires CGO. Its peer TLS handshake uses the OpenSSL C shim, and all secp256k1 operations — key derivation, signing, public-key operations, and verification — use the libsecp256k1 C shim. There is no supported pure-Go secp256k1 backend. CGO_ENABLED=0 remains useful only for leaves whose production and test dependency graph avoids addresscodec, including Ed25519, SHA-512Half, RFC 1751, drops, protocol, amendments, SHAMap, the key-value/node stores, and binarycodec definitions, serdes, and decimal internals. Binarycodec, relational storage, keylet, and ledger packages reach the native shim transitively.

Executable

The repository builds one executable, goxrpl, with the following primary commands:

Run ../tmp/goxrpl --help or ../tmp/goxrpl <command> --help for the complete command-line reference.

Running a node

Generate a configuration first:

../tmp/goxrpl generate-config --network main --output goxrpl.toml

Start a networked node and acquire its initial ledger from peers:

../tmp/goxrpl server --conf goxrpl.toml --net

For a local standalone node instead:

../tmp/goxrpl server --conf goxrpl.toml --standalone --start

The configuration controls peer discovery, validation, storage, logging, and the listening addresses for JSON-RPC, WebSocket, gRPC, and peer traffic. See the operator guide for startup modes, endpoint security, storage backends, validator configuration, and the full configuration reference.

Accurate host time is required for peer connections. Run a synchronized system time service before joining a network.

Go packages

go-xrpl also exposes reusable Go packages for applications and tooling:

• amendment — amendment registry and rules
• codec — XRPL address and binary encoding
• crypto — Ed25519, secp256k1, and protocol hashing
• drops — XRP amount handling
• keylet — ledger key derivation
• ledger/entry — serialized ledger entry types
• protocol — protocol constants and primitives
• shamap — authenticated ledger state maps
• storage — node and relational storage backends

Internal node services include transaction execution, the transaction queue, ledger acquisition and lifecycle, consensus, peer networking, JSON-RPC, WebSocket subscriptions, and gRPC. API documentation for public packages is available on pkg.go.dev.

Testing

The justfile groups local checks in the same way as CI:

just test             # all Go tests
just test-integration # transaction conformance suites
just test-tx          # transaction engine and handlers
just test-core        # ledger, consensus, RPC, queue, and peer subsystems
just test-libs        # public libraries and storage
just vet
just lint

To inspect the required private 3.4.1 corpus:

just conformance --corpus internal/testing/conformance/testdata/rippled-3.4.1-v4
just conformance --corpus internal/testing/conformance/testdata/rippled-3.4.1-v4 --failing

The committed signed corpus pins private rippled 3.4.1 source and recorder provenance. Missing, stale, mixed, empty, or zero-executed corpora fail closed. See the corpus coverage limits and the release evidence matrix before interpreting a pass as a release claim.

Documentation

Contributing

Contributions are welcome. Changes to protocol-visible behavior must preserve XRPL compatibility, while implementation choices should remain idiomatic Go. Read CONTRIBUTING.md for the development workflow, test layout, and review requirements.

License

go-xrpl is licensed under the ISC License.