rippled/docs/ARCHITECTURE.md

rippled Architecture Map

Purpose: Tell agents where things are. Not why they exist. Audience: AI coding agents (Claude Code, Codex, Copilot) navigating the codebase. Principle: "Give agents a map, not an encyclopedia." — Harness Engineering

---

Layer Diagram

┌─────────────────────────────────────────────────────────────┐
│                     RPC Layer (Layer 5)                     │
│  HTTP/WebSocket → ServerHandler → 72 RPC Handlers           │
│  src/xrpld/rpc/                                             │
├─────────────────────────────────────────────────────────────┤
│                   Application Layer (Layer 4)               │
│  NetworkOPs · TxQ · PathFinding · LedgerMaster              │
│  src/xrpld/app/                                             │
├─────────────────────────────────────────────────────────────┤
│                   Consensus Layer (Layer 3)                 │
│  Consensus<Adaptor> · RCLConsensus · Validations            │
│  src/xrpld/consensus/ + src/xrpld/app/consensus/            │
├─────────────────────────────────────────────────────────────┤
│                   Overlay Layer (Layer 2)                   │
│  OverlayImpl · PeerImp · PeerFinder · Message               │
│  src/xrpld/overlay/ + src/xrpld/peerfinder/                 │
├─────────────────────────────────────────────────────────────┤
│                   Storage Layer (Layer 1)                   │
│  NodeStore (RocksDB/SQLite) · SHAMap · RDB                  │
│  src/libxrpl/nodestore/ + src/libxrpl/shamap/               │
├─────────────────────────────────────────────────────────────┤
│                   Foundation (Layer 0)                      │
│  beast:: (I/O, insight, clock) · protocol · crypto · json   │
│  src/libxrpl/ + include/xrpl/                               │
└─────────────────────────────────────────────────────────────┘

---

Module Map

xrpld (the daemon) — src/xrpld/

Directory	Purpose	Key Files
app/main/	Daemon entry point, Application lifecycle	Main.cpp, Application.h/.cpp, BasicApp.h
app/consensus/	Consensus adaptor binding protocol to rippled types	RCLConsensus.h/.cpp
app/ledger/	Ledger management, building, acquiring	LedgerMaster.h, InboundLedgers.h
app/misc/	NetworkOPs, TxQ, HashRouter, Amendments	NetworkOPs.h/.cpp, TxQ.h, HashRouter.h
app/tx/	Transaction application engine	apply.h/.cpp, applySteps.h
app/paths/	Payment path finding	Pathfinder.h, PathRequest.h
app/rdb/	Relational DB backend for state	RelationalDatabase.h
consensus/	Generic consensus protocol (template-based)	Consensus.h/.cpp, ConsensusParms.h
core/	Node configuration, time keeping	Config.h/.cpp, TimeKeeper.h
overlay/	P2P network: peer connections, message routing	Overlay.h, Peer.h, Message.h
overlay/detail/	Overlay implementation internals	OverlayImpl.h/.cpp, PeerImp.h/.cpp, Handshake.h
peerfinder/	Peer discovery and bootstrap	PeerfinderManager.h, detail/Logic.h
perflog/	Performance logging (pre-OTel telemetry)	detail/PerfLogImp.h/.cpp
rpc/	JSON-RPC server and routing	detail/Handler.h, RPCHandler.h
rpc/handlers/	72 RPC command implementations	AccountInfo.cpp, Submit.cpp, Tx.cpp, etc.
shamap/	SHAMap tree operations (daemon-side)

libxrpl (shared library) — src/libxrpl/

Directory	Purpose	Key Files
basics/	Logging, string utils, tagged integers	Log.cpp (log formatting — Phase 8 OTel target)
beast/insight/	Metrics framework (StatsD, Gauge, Counter, Event)	StatsDCollector.cpp (Phase 6-7 OTel target)
beast/core/	Async I/O primitives	CurrentThreadName.cpp
core/	Crypto, seed handling
crypto/	Ed25519, secp256k1, SHA
json/	JSON parser/writer
nodestore/	Key-value storage for ledger nodes	backend/RocksDBFactory.cpp
protocol/	XRPL protocol: serialization, STObject, STTx	STTx.cpp, STObject.cpp
server/	HTTP/WebSocket server core	ServerHandler.h
tx/transactors/	Per-transaction-type execution logic	Payment.cpp, CreateOffer.cpp, etc.
tx/invariants/	Transaction invariant checks	TransactionCheck.cpp

Public Headers — include/xrpl/

Mirrors src/libxrpl/ structure. Agent-accessible API surface for external consumers of libxrpl.

Key subdirectory: include/xrpl/proto/org/xrpl/rpc/v1/ — Protocol Buffer definitions for gRPC API.

---

Entry Points

Operation	Where execution starts	Hot path
RPC request	src/xrpld/rpc/detail/ServerHandler.cpp → handler lookup → src/xrpld/rpc/handlers/*.cpp	Layer 5 → 4
Peer message	src/xrpld/overlay/detail/PeerImp.cpp::onMessage() → message-type dispatch	Layer 2 → 3/4
Transaction submit	rpc/handlers/Submit.cpp → app/misc/NetworkOPs.cpp::submitTransaction()	Layer 5 → 4 → 2
Transaction relay	overlay/detail/PeerImp.cpp::handleTransaction() → NetworkOPs::processTransaction()	Layer 2 → 4
Consensus round	app/consensus/RCLConsensus.cpp::startRound() → phase transitions → accept	Layer 3
Ledger close	RCLConsensus.cpp::onClose() → acceptLedger() → apply transactions	Layer 3 → 4 → 1
Ledger acquire	app/ledger/InboundLedgers.cpp::acquire() → peer fetch → SHAMap	Layer 4 → 2 → 1
Startup	app/main/Main.cpp::main() → Application::setup() → start all subsystems	Layer 0-5

---

Data Flow: Transaction Lifecycle

Client
  │
  ▼
RPC Submit (Layer 5)
  │ src/xrpld/rpc/handlers/Submit.cpp
  ▼
NetworkOPs::submitTransaction() (Layer 4)
  │ src/xrpld/app/misc/NetworkOPs.cpp
  ├──▶ TxQ::apply() — queue management
  │     src/xrpld/app/misc/TxQ.cpp
  ├──▶ HashRouter::setFlags() — deduplication
  │     src/xrpld/app/misc/HashRouter.cpp
  ▼
Overlay::relay() (Layer 2)
  │ src/xrpld/overlay/detail/OverlayImpl.cpp
  ├──▶ PeerImp::send() — to each connected peer
  │     src/xrpld/overlay/detail/PeerImp.cpp
  ▼
[Remote Node] PeerImp::handleTransaction() (Layer 2)
  │ src/xrpld/overlay/detail/PeerImp.cpp
  ▼
Consensus::startRound() (Layer 3)
  │ src/xrpld/consensus/Consensus.h
  │ src/xrpld/app/consensus/RCLConsensus.cpp
  ├──▶ propose() — send position to peers
  ├──▶ onClose() — close the ledger
  ▼
acceptLedger() → applyTransactions() (Layer 3 → 1)
  │ src/xrpld/app/consensus/RCLConsensus.cpp
  ▼
NodeStore::store() (Layer 1)
  │ src/libxrpl/nodestore/

---

Build Targets

Target	Type	Source
xrpl	Shared library (libxrpl)	src/libxrpl/ + include/xrpl/
xrpld	Executable (daemon)	src/xrpld/
rippled_unit_tests	Unit test binary	src/test/
libxrpl_tests	Library integration tests	src/tests/libxrpl/

Build command: cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build --parallel With telemetry: cmake -B build -DXRPL_ENABLE_TELEMETRY=ON

---

Test Frameworks

Framework	Location	Purpose
JTx	src/test/jtx/	Transaction testing — simulates full ledger environment
CSF	src/test/csf/	Consensus Simulation Framework — multi-node consensus testing
Unit tests	src/test/app/, src/test/beast/, etc.	Per-module unit tests
Integration	src/tests/libxrpl/	Library-level integration tests

---

Telemetry Map

Links OTel instrumentation to codebase locations. See 09-data-collection-reference.md for the full inventory.

Span	Source Location	Layer
rpc.*	src/xrpld/rpc/detail/ServerHandler.cpp	5
tx.submit	src/xrpld/app/misc/NetworkOPs.cpp	4
tx.relay	src/xrpld/overlay/detail/PeerImp.cpp	2
peer.send	src/xrpld/overlay/detail/PeerImp.cpp	2
consensus.*	src/xrpld/app/consensus/RCLConsensus.cpp	3
ledger.*	src/xrpld/app/ledger/	4

Metrics Source	Code Location	Phase
beast::insight (StatsD)	src/libxrpl/beast/insight/StatsDCollector.cpp	6-7
SpanMetrics (derived)	OTel Collector config	5
PerfLog	src/xrpld/perflog/detail/PerfLogImp.cpp	9 (gap fill)

---

Key Abstractions

Abstraction	Interface	Implementation	What it does
Application	src/xrpld/app/main/Application.h	Application.cpp	Wires all subsystems together
Overlay	src/xrpld/overlay/Overlay.h	detail/OverlayImpl.cpp	Manages P2P connections
Consensus<>	src/xrpld/consensus/Consensus.h	Template, adaptor in RCLConsensus.cpp	Generic consensus protocol
NetworkOPs	src/xrpld/app/misc/NetworkOPs.h	NetworkOPs.cpp	Transaction processing, event dispatch
LedgerMaster	src/xrpld/app/ledger/LedgerMaster.h	LedgerMaster.cpp	Ledger lifecycle management
NodeStore	include/xrpl/nodestore/Database.h	src/libxrpl/nodestore/	Persistent key-value storage
beast::insight::Collector	include/xrpl/beast/insight/Collector.h	StatsDCollector, NullCollector, (future: OTelCollector)	Metrics collection interface
JobQueue	src/xrpld/core/JobQueue.h	JobQueue.cpp	Async task scheduling
SHAMap	include/xrpl/shamap/SHAMap.h	src/libxrpl/shamap/	Merkle tree for state

---

Dependency Rules

Layer 5 (RPC)        → may call → Layer 4 (App)
Layer 4 (App)        → may call → Layer 3 (Consensus), Layer 2 (Overlay), Layer 1 (Storage)
Layer 3 (Consensus)  → may call → Layer 4 (App via Adaptor), Layer 1 (Storage)
Layer 2 (Overlay)    → may call → Layer 4 (App for message handling)
Layer 1 (Storage)    → may call → Layer 0 (Foundation) only
Layer 0 (Foundation) → no upward dependencies

Never: Layer 0/1 must never depend on Layer 3/4/5. Layer 5 must never bypass Layer 4 to reach Layer 2/3 directly.

---

Configuration

File	Location	Purpose
xrpld.cfg	cfg/	Main daemon configuration
validators.txt	cfg/	Validator list
CMakeUserPresets.json	Root	Local build presets
conanfile.py	Root	Dependency versions

---

This document is a navigation aid for AI coding agents. For architectural rationale, see docs/consensus.md. For OTel plan, see OpenTelemetryPlan/. For coding conventions, see docs/CodingStyle.md.