README
¶
go-xrpl
An idiomatic Go implementation of an XRP Ledger node.
go-xrpl is not a line-by-line port of rippled (the C++ reference implementation). It is a native Go implementation that follows Go conventions and concurrency patterns while maintaining full protocol compatibility with the XRP Ledger network. rippled serves as the de facto specification — there is no formal XRPL spec — so behavioral parity with rippled is the correctness bar.
Status: actively developed, building in public. Core transaction processing, ledger state management, and RPC are functional. See Current Status for details.
Getting Started
Prerequisites
- Go 1.24+
- PostgreSQL (optional, for relational storage)
Build
go build -o ./tmp/main ./cmd/xrpld
Run
# Start the node
./tmp/main
# Or with hot reload during development
cd cmd/xrpld && air
The server exposes:
http://localhost:8080/— JSON-RPC 2.0ws://localhost:8080/ws— WebSocket subscriptionshttp://localhost:8080/health— Health check
Test
# All tests
go test ./...
# Specific transaction type
go test ./internal/tx/offer/...
# Specific test suite
go test ./internal/testing/amm/...
# Single test
go test ./internal/testing/offer/... -run TestOfferCreateValidation
# Conformance summary
./scripts/conformance-summary.sh
./scripts/conformance-summary.sh --failing
Building
goxrpl uses CGO to call OpenSSL for the peer-to-peer TLS handshake — required to compute the
session-signature shared value matching rippled's SSL_get_finished / SSL_get_peer_finished
flow. You need OpenSSL development headers installed on the build host.
macOS
brew install openssl@3 pkg-config
export PKG_CONFIG_PATH="$(brew --prefix openssl@3)/lib/pkgconfig"
go build ./cmd/xrpld
Ubuntu / Debian
sudo apt install -y libssl-dev pkg-config
go build ./cmd/xrpld
Alpine (or static-linked Linux build)
apk add --no-cache gcc musl-dev pkgconf openssl-dev openssl-libs-static
CGO_ENABLED=1 go build -ldflags="-linkmode external -extldflags '-static'" ./cmd/xrpld
CGO-disabled builds
CGO_ENABLED=0 go build ./cmd/xrpld is supported. The resulting binary cannot
connect to or accept peers (peertls returns ErrSessionSigUnsupported), but RPC,
WebSocket, tx, codec, and all other subsystems work unchanged. Useful for contributors
without an OpenSSL toolchain.
Running interop tests
A docker-based interop test against a real rippled instance lives at
internal/peermanagement/peertls/tls_interop_test.go. It is gated by a build tag and
an env var so CI never runs it:
PEERTLS_DOCKER_INTEROP=1 go test -tags 'docker' \
./internal/peermanagement/peertls/ \
-run TestHandshake_Interop_RippledDocker
Architecture
cmd/xrpld/ CLI entry point (Cobra)
── Public packages ──────────────────────────────
amendment/ Amendment/feature registry
codec/ Binary & address encoding
addresscodec/ Address encode/decode
binarycodec/ XRPL binary serialization
config/ Configuration
crypto/ ED25519, secp256k1, SHA-512 Half
drops/ XRP amount utilities
keylet/ Ledger object key derivation
ledger/entry/ Serializable Ledger Entries (40+ types)
protocol/ Protocol constants
shamap/ SHAMap (SHA-512 tree) for state hashing
storage/ Persistence layer
kvstore/ KV interface (memory, Pebble)
nodestore/ Blockchain state storage
relationaldb/ PostgreSQL
── Internal packages ────────────────────────────
internal/tx/ Transaction engine & processing
engine.go Validate → Preflight → Preclaim → Apply
account/ amm/ batch/ check/ clawback/ credential/
delegate/ depositpreauth/ did/ escrow/ ledgerstatefix/
mpt/ nftoken/ offer/ oracle/ paychan/ payment/
permissioneddomain/ pseudo/ signerlist/ ticket/
trustset/ vault/ xchain/
invariants/ Transaction invariant checks
internal/ledger/ Ledger management
genesis/ header/ manager/ service/ state/ store/
internal/consensus/ Consensus protocol
csf/ Consensus Simulation Framework
rcl/ Ripple Consensus Ledger
internal/txq/ Transaction queue
internal/rpc/ JSON-RPC server (60+ methods)
handlers/ Per-method handler implementations
internal/grpc/ gRPC server
internal/peermanagement/ Peer networking
internal/testing/ Test suites (one directory per feature)
Transaction Flow
Every transaction follows the same pipeline:
- Validate — Structural validation (well-formed fields, valid types)
- Preflight — Context-free checks (flags, field constraints)
- Preclaim — Ledger-aware checks (account exists, sufficient balance)
- Apply — Execute against ledger state
Transaction types self-register via init() + tx.Register() in their respective subpackages.
Current Status
What works
The client currently targets standalone mode (single-node, no network peers), with rippled v2.6.2 as the first release target.
- 26 transaction types — Full pipeline (validate through apply) with behavioral parity to rippled
- 60+ RPC methods — JSON-RPC 2.0 and WebSocket interfaces
- Ledger state — SHAMap-backed state tree with Pebble storage
- Pathfinding — DFS-based path discovery matching rippled's algorithm
- Codec — Full binary serialization/deserialization
- Cryptography — ED25519 and secp256k1 signing/verification
- 34 test suites — Conformance tests validating behavior against rippled
What's in progress
- Consensus — CSF and RCL implementations exist but are not yet tested
- Peer-to-peer networking
- Full ledger sync / history
- WebSocket
path_findsubscriptions - Admin authentication
Design Decisions
Why Go? Go's concurrency model (goroutines, channels) is a natural fit for a blockchain node that juggles peer connections, transaction processing, consensus rounds, and RPC serving concurrently. The language's simplicity and strong standard library reduce the surface area for bugs in critical financial infrastructure.
Why not a direct port? rippled's C++ idioms (templates, RAII, complex inheritance hierarchies) don't translate well to Go. Instead, go-xrpl uses Go interfaces, composition, and table-driven designs while preserving the same protocol semantics. The result is more readable and maintainable while remaining behaviorally equivalent.
rippled as spec. Every transaction type, ledger entry, and edge case is validated against rippled's behavior. The local rippled/ source tree is the reference for any ambiguity.
Contributing
Contributions are welcome. The general workflow:
- Pick a transaction type, RPC method, or test gap
- Check the corresponding rippled implementation in
rippled/src/xrpld/app/tx/detail/ - Implement or fix the Go equivalent, matching rippled's behavior
- Add or update tests in
internal/testing/<feature>/ - Run
go test ./...and the conformance summary
When in doubt about expected behavior, rippled is the source of truth.
License
ISC License — see LICENSE for details.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package amendment implements the XRPL amendment system for managing protocol feature activation.
|
Package amendment implements the XRPL amendment system for managing protocol feature activation. |
|
cmd
|
|
|
xrpld
command
|
|
|
codec
|
|
|
addresscodec
Package addresscodec provides base58 encoding and decoding functionality for XRPL addresses and keys.
|
Package addresscodec provides base58 encoding and decoding functionality for XRPL addresses and keys. |
|
binarycodec
Package binarycodec implements binary serialization and deserialization of XRPL objects using the canonical field ordering defined by the XRPL protocol.
|
Package binarycodec implements binary serialization and deserialization of XRPL objects using the canonical field ordering defined by the XRPL protocol. |
|
binarycodec/definitions
Package definitions contains XRPL binary codec field and type definitions.
|
Package definitions contains XRPL binary codec field and type definitions. |
|
binarycodec/serdes
Package serdes provides utilities to parse and serialize XRPL binary data fields.
|
Package serdes provides utilities to parse and serialize XRPL binary data fields. |
|
binarycodec/serdes/interfaces
Package interfaces defines interfaces for binary serialization and deserialization of XRPL fields.
|
Package interfaces defines interfaces for binary serialization and deserialization of XRPL fields. |
|
binarycodec/serdes/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
binarycodec/types
Package types contains data structures for binary codec operations.
|
Package types contains data structures for binary codec operations. |
|
binarycodec/types/interfaces
Package interfaces defines the BinaryParser interface for binary codec parsing operations.
|
Package interfaces defines the BinaryParser interface for binary codec parsing operations. |
|
binarycodec/types/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
Package crypto provides cryptographic operations for the XRPL protocol.
|
Package crypto provides cryptographic operations for the XRPL protocol. |
|
rfc1751
Package rfc1751 implements RFC 1751 (S/KEY) encoding/decoding of binary data as human-readable English words.
|
Package rfc1751 implements RFC 1751 (S/KEY) encoding/decoding of binary data as human-readable English words. |
|
Package drops provides type-safe XRP amount arithmetic using uint64 drops.
|
Package drops provides type-safe XRP amount arithmetic using uint64 drops. |
|
internal
|
|
|
consensus
Package consensus defines the interface and types for XRPL consensus algorithms.
|
Package consensus defines the interface and types for XRPL consensus algorithms. |
|
consensus/adaptor
Package adaptor provides the concrete implementation of the consensus.Adaptor interface, bridging the consensus engine to the ledger service, P2P overlay, and transaction queue.
|
Package adaptor provides the concrete implementation of the consensus.Adaptor interface, bridging the consensus engine to the ledger service, P2P overlay, and transaction queue. |
|
consensus/amendmentvote
Package amendmentvote ports rippled's AmendmentTableImpl::doVoting (src/xrpld/app/misc/detail/AmendmentTable.cpp:847-941) — the producer side that decides whether to inject EnableAmendment pseudo-txs into the consensus tx set on a flag-ledger boundary.
|
Package amendmentvote ports rippled's AmendmentTableImpl::doVoting (src/xrpld/app/misc/detail/AmendmentTable.cpp:847-941) — the producer side that decides whether to inject EnableAmendment pseudo-txs into the consensus tx set on a flag-ledger boundary. |
|
consensus/archive
Package archive persists stale validations to the relational DB via a batched async writer hooked into ValidationTracker.SetOnStale.
|
Package archive persists stale validations to the relational DB via a batched async writer hooked into ValidationTracker.SetOnStale. |
|
consensus/csf
Package csf provides a Consensus Simulation Framework for testing consensus algorithms.
|
Package csf provides a Consensus Simulation Framework for testing consensus algorithms. |
|
consensus/feevote
Package feevote ports rippled's FeeVoteImpl (src/xrpld/app/misc/FeeVoteImpl.cpp) — the producer side that decides whether to inject a SetFee pseudo-tx into the consensus tx set on a flag-ledger boundary, based on trusted validators' fee votes from the prior voting ledger.
|
Package feevote ports rippled's FeeVoteImpl (src/xrpld/app/misc/FeeVoteImpl.cpp) — the producer side that decides whether to inject a SetFee pseudo-tx into the consensus tx set on a flag-ledger boundary, based on trusted validators' fee votes from the prior voting ledger. |
|
consensus/ledgertrie
Package ledgertrie ports rippled's LedgerTrie<Ledger> (src/xrpld/consensus/LedgerTrie.h): branchSupport-based preferred- ledger selection over a compressed ancestry trie.
|
Package ledgertrie ports rippled's LedgerTrie<Ledger> (src/xrpld/consensus/LedgerTrie.h): branchSupport-based preferred- ledger selection over a compressed ancestry trie. |
|
consensus/negativeunlvote
Package negativeunlvote ports rippled's NegativeUNLVote (src/xrpld/app/misc/NegativeUNLVote.{h,cpp}) — the producer side that decides whether to inject a UNLModify pseudo-tx into the consensus tx set on a flag-ledger boundary, based on per-validator participation in the last FlagLedgerInterval ledgers.
|
Package negativeunlvote ports rippled's NegativeUNLVote (src/xrpld/app/misc/NegativeUNLVote.{h,cpp}) — the producer side that decides whether to inject a UNLModify pseudo-tx into the consensus tx set on a flag-ledger boundary, based on per-validator participation in the last FlagLedgerInterval ledgers. |
|
consensus/rcl
Package rcl implements the Ripple Consensus Ledger algorithm.
|
Package rcl implements the Ripple Consensus Ledger algorithm. |
|
ledger/inbound
Package inbound provides lightweight ledger acquisition from peers.
|
Package inbound provides lightweight ledger acquisition from peers. |
|
ledger/inbound/inboundtest
Package inboundtest provides shared test utilities for the internal/ledger/inbound package and its sibling-package consumers.
|
Package inboundtest provides shared test utilities for the internal/ledger/inbound package and its sibling-package consumers. |
|
ledger/localtxs
Package localtxs is goxrpl's port of rippled's app/ledger/LocalTxs.
|
Package localtxs is goxrpl's port of rippled's app/ledger/LocalTxs. |
|
ledger/openledger
Package openledger implements rippled's OpenLedger semantics for goXRPL.
|
Package openledger implements rippled's OpenLedger semantics for goXRPL. |
|
ledger/service/svcerr
Package svcerr defines the typed sentinel errors returned by the ledger service.
|
Package svcerr defines the typed sentinel errors returned by the ledger service. |
|
manifest
Package manifest implements validator manifest parsing, verification, and caching — the equivalent of rippled's ValidatorManifests service.
|
Package manifest implements validator manifest parsing, verification, and caching — the equivalent of rippled's ValidatorManifests service. |
|
observability
Package observability hosts process-level metrics surfaced to RPC.
|
Package observability hosts process-level metrics surfaced to RPC. |
|
peermanagement
Package peermanagement implements XRPL peer-to-peer networking.
|
Package peermanagement implements XRPL peer-to-peer networking. |
|
peermanagement/cluster
Package cluster maintains the registry of cluster-trusted node identities — operators run a small set of nodes that they configure to know about each other via [cluster_nodes].
|
Package cluster maintains the registry of cluster-trusted node identities — operators run a small set of nodes that they configure to know about each other via [cluster_nodes]. |
|
peermanagement/message
Package message implements XRPL peer protocol message types and serialization.
|
Package message implements XRPL peer protocol message types and serialization. |
|
peermanagement/peertls
Package peertls is the TLS 1.2 transport for XRPL peer connections.
|
Package peertls is the TLS 1.2 transport for XRPL peer connections. |
|
peermanagement/peertls/shim
Package shim is the cgo binding for the OpenSSL TLS shim used by peertls.
|
Package shim is the cgo binding for the OpenSSL TLS shim used by peertls. |
|
rpc/handlers/v1
Package v1 provides API v1 response formatters for RPC handlers.
|
Package v1 provides API v1 response formatters for RPC handlers. |
|
rpc/loadtrack
Package loadtrack implements a per-client-IP load tracker that mirrors rippled's Resource::Manager / LoadFeeTrack approach: each inbound RPC method is assigned a Charge (a numeric cost), the cost accumulates against a per-IP balance, balances decay exponentially over time, and a balance crossing a warning / drop threshold causes the next request to be slowed or rejected.
|
Package loadtrack implements a per-client-IP load tracker that mirrors rippled's Resource::Manager / LoadFeeTrack approach: each inbound RPC method is assigned a Charge (a numeric cost), the cost accumulates against a per-IP balance, balances decay exponentially over time, and a balance crossing a warning / drop threshold causes the next request to be slowed or rejected. |
|
statecompare
Package statecompare provides a client for reading from the xrpl-state-compare PostgreSQL database.
|
Package statecompare provides a client for reading from the xrpl-state-compare PostgreSQL database. |
|
testing
Package testing provides test infrastructure for XRPL transaction testing.
|
Package testing provides test infrastructure for XRPL transaction testing. |
|
testing/amm
Package amm provides test builders for AMM transactions.
|
Package amm provides test builders for AMM transactions. |
|
testing/batch
Package batch provides test builder helpers for Batch transactions.
|
Package batch provides test builder helpers for Batch transactions. |
|
testing/conformance
Package conformance provides a test runner for xrpl-fixtures test vectors.
|
Package conformance provides a test runner for xrpl-fixtures test vectors. |
|
testing/consensus
Package consensus provides integration test utilities for multi-node consensus testing.
|
Package consensus provides integration test utilities for multi-node consensus testing. |
|
testing/depositpreauth
Package depositpreauth provides fluent transaction builder helpers for DepositPreauth testing, plus integration tests matching rippled's DepositAuth_test.cpp and DepositPreauth_test sections.
|
Package depositpreauth provides fluent transaction builder helpers for DepositPreauth testing, plus integration tests matching rippled's DepositAuth_test.cpp and DepositPreauth_test sections. |
|
testing/metadata
Package metadata provides test helpers for validating transaction metadata.
|
Package metadata provides test helpers for validating transaction metadata. |
|
testing/mpt
Package mpt provides test helpers for MPT (Multi-Purpose Token) transaction testing.
|
Package mpt provides test helpers for MPT (Multi-Purpose Token) transaction testing. |
|
testing/payment
Package builders provides fluent transaction builder helpers for testing.
|
Package builders provides fluent transaction builder helpers for testing. |
|
testing/permissioneddex
Package permissioneddex provides test helpers for PermissionedDEX tests.
|
Package permissioneddex provides test helpers for PermissionedDEX tests. |
|
testing/ticket
Package ticket provides test helpers for Ticket transaction testing.
|
Package ticket provides test helpers for Ticket transaction testing. |
|
tx/all
Package all aggregates all transaction sub-packages and exposes a single RegisterAll() entry point that registers every transaction type with the tx registry.
|
Package all aggregates all transaction sub-packages and exposes a single RegisterAll() entry point that registers every transaction type with the tx registry. |
|
tx/escrow
Package escrow implements EscrowCreate, EscrowFinish, and EscrowCancel transactions.
|
Package escrow implements EscrowCreate, EscrowFinish, and EscrowCancel transactions. |
|
tx/offer
Reference: rippled CreateOffer.cpp, CancelOffer.cpp
|
Reference: rippled CreateOffer.cpp, CancelOffer.cpp |
|
Package keylet provides functions to compute the 256-bit SHA-512Half keys that uniquely identify ledger entries in the XRPL state tree.
|
Package keylet provides functions to compute the 256-bit SHA-512Half keys that uniquely identify ledger entries in the XRPL state tree. |
|
ledger
|
|
|
entry
Package entry defines the Serializable Ledger Entry (SLE) types for all XRPL ledger objects.
|
Package entry defines the Serializable Ledger Entry (SLE) types for all XRPL ledger objects. |
|
Package log provides structured logging for goXRPL.
|
Package log provides structured logging for goXRPL. |
|
Package protocol defines XRPL protocol constants used throughout the codebase.
|
Package protocol defines XRPL protocol constants used throughout the codebase. |
|
Package shamap implements the SHAMap, a Merkle-like radix tree used by the XRPL for ledger state and transaction storage.
|
Package shamap implements the SHAMap, a Merkle-like radix tree used by the XRPL for ledger state and transaction storage. |
|
storage
|
|
|
kvstore
Package kvstore defines a generic key-value storage interface for persistent data backends.
|
Package kvstore defines a generic key-value storage interface for persistent data backends. |
|
kvstore/memorydb
Package memorydb implements the kvstore.KeyValueStore interface using an in-memory map.
|
Package memorydb implements the kvstore.KeyValueStore interface using an in-memory map. |
|
kvstore/pebble
Package pebble implements the kvstore.KeyValueStore interface using CockroachDB/Pebble.
|
Package pebble implements the kvstore.KeyValueStore interface using CockroachDB/Pebble. |
|
nodestore
Package nodestore provides blockchain state storage for XRPL node data.
|
Package nodestore provides blockchain state storage for XRPL node data. |
Click to show internal directories.
Click to hide internal directories.