README
¶
XRPL Client Implementation Specification
Overview
This document outlines the architectural design of a blockchain client implementation for XRPL in GoLang. The design emphasizes concurrent processing, data consistency, and efficient storage management through careful separation of concerns.
Core Architecture
Concurrent Processing Components
The system operates through multiple concurrent goroutines, each responsible for a specific aspect of the blockchain client:
The Mempool Handler operates as an independent goroutine managing pending transactions. It continuously processes incoming transactions, validates them according to network rules, and maintains them until they are included in blocks or expire.
The Consensus Engine runs in its own goroutine and serves as the heart of the blockchain client. It implements the consensus protocol, coordinates block creation, and ensures network-wide agreement on the blockchain state.
The JSON-RPC Server provides the primary interface for external interaction. Running in a dedicated goroutine, it handles API requests for blockchain data, transaction submission, and queries about network state.
The WebSocket Server maintains persistent connections with clients, running separately from the JSON-RPC server. It enables real-time updates about network events, new blocks, and transaction status changes.
Storage Architecture
The system employs multiple specialized databases, each optimized for specific data access patterns:
The Mempool Database serves as temporary storage for pending transactions. It requires high-throughput write operations and quick read access for transaction validation and block creation.
The State Database maintains the current blockchain state. It stores account balances, smart contract states, and other mutable blockchain data. This database must support atomic updates during block processing while allowing concurrent reads for query operations.
The Block Database stores the immutable history of all blocks. It maintains block headers, block bodies, and the relationships between blocks, supporting chain reorganizations when necessary.
The Transaction Database maintains a comprehensive record of all processed transactions. It enables efficient querying of transaction history, status, and receipts without needing to scan through blocks.
Data Flow and Interaction
All components interact through Go channels, ensuring thread-safe communication. The system maintains data consistency through strategic use of read-write mutexes (sync.RWMutex), allowing concurrent reads while protecting write operations.
Future Considerations
The architecture allows for future implementation of additional indexes to optimize specific query patterns. These indexes would enhance performance for common operations while maintaining the system's core functionality.
Implementation Notes
This specification intentionally omits implementation details of the XRPL consensus protocol, focusing instead on the architectural framework that will support it. The actual consensus implementation will need to adhere to the XRPL protocol specifications while fitting within this architectural design.
The use of separate databases should not be confused with separate physical storage - these may be implemented as separate namespaces within a single database engine, provided the chosen engine can maintain the required performance characteristics for each data type.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package consensus defines the interface and types for XRPL consensus algorithms.
|
Package consensus defines the interface and types for XRPL consensus algorithms. |
|
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. |
|
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. |
|
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. |
|
csf
Package csf provides a Consensus Simulation Framework for testing consensus algorithms.
|
Package csf provides a Consensus Simulation Framework for testing consensus algorithms. |
|
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. |
|
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. |
|
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. |
|
rcl
Package rcl implements the Ripple Consensus Ledger algorithm.
|
Package rcl implements the Ripple Consensus Ledger algorithm. |
|
inbound
Package inbound provides lightweight ledger acquisition from peers.
|
Package inbound provides lightweight ledger acquisition from peers. |
|
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. |
|
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. |
|
openledger
Package openledger implements rippled's OpenLedger semantics for goXRPL.
|
Package openledger implements rippled's OpenLedger semantics for goXRPL. |
|
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. |
|
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. |
|
Package observability hosts process-level metrics surfaced to RPC.
|
Package observability hosts process-level metrics surfaced to RPC. |
|
Package peermanagement implements XRPL peer-to-peer networking.
|
Package peermanagement implements XRPL peer-to-peer networking. |
|
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]. |
|
message
Package message implements XRPL peer protocol message types and serialization.
|
Package message implements XRPL peer protocol message types and serialization. |
|
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. |
|
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. |
|
handlers/v1
Package v1 provides API v1 response formatters for RPC handlers.
|
Package v1 provides API v1 response formatters for RPC handlers. |
|
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. |
|
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. |
|
Package testing provides test infrastructure for XRPL transaction testing.
|
Package testing provides test infrastructure for XRPL transaction testing. |
|
amm
Package amm provides test builders for AMM transactions.
|
Package amm provides test builders for AMM transactions. |
|
batch
Package batch provides test builder helpers for Batch transactions.
|
Package batch provides test builder helpers for Batch transactions. |
|
conformance
Package conformance provides a test runner for xrpl-fixtures test vectors.
|
Package conformance provides a test runner for xrpl-fixtures test vectors. |
|
consensus
Package consensus provides integration test utilities for multi-node consensus testing.
|
Package consensus provides integration test utilities for multi-node consensus 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. |
|
metadata
Package metadata provides test helpers for validating transaction metadata.
|
Package metadata provides test helpers for validating transaction metadata. |
|
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. |
|
payment
Package builders provides fluent transaction builder helpers for testing.
|
Package builders provides fluent transaction builder helpers for testing. |
|
permissioneddex
Package permissioneddex provides test helpers for PermissionedDEX tests.
|
Package permissioneddex provides test helpers for PermissionedDEX tests. |
|
ticket
Package ticket provides test helpers for Ticket transaction testing.
|
Package ticket provides test helpers for Ticket transaction testing. |
|
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. |
|
escrow
Package escrow implements EscrowCreate, EscrowFinish, and EscrowCancel transactions.
|
Package escrow implements EscrowCreate, EscrowFinish, and EscrowCancel transactions. |
|
offer
Reference: rippled CreateOffer.cpp, CancelOffer.cpp
|
Reference: rippled CreateOffer.cpp, CancelOffer.cpp |