How paradigmxyz/reth works
1. What this repository is
- reth is a modular Ethereum execution client written in Rust.
- The workspace is split into many crates so the node, RPC layer, sync pipeline, storage engine, trie logic, networking, and payload building can be reused independently.
2. Top-level runtime entry points
- The main binary is bin/reth, which assembles a full node from the library crates.
- bin/reth-bb is a separate benchmarking/build-bundle style tool focused on EVM execution.
- Most of the actual node wiring lives under crates/node/* and crates/ethereum/*.
3. Node assembly boundary
- crates/node/builder and crates/node/core are the orchestration layer.
- node/core handles CLI args, config, datadir layout, logging, and process utilities.
- node/builder composes the major subsystems: consensus-facing services, execution, networking, transaction pool, RPC, and optional extensions.
4. Ethereum-specific protocol layer
- crates/ethereum/* contains the Ethereum domain model and adapters:
- chain specs and hardfork definitions
- payload validation
- EVM configuration and receipt types
- node/engine glue for Ethereum semantics
- This layer isolates chain-specific rules from the more generic node infrastructure.
5. Execution and payload production
- Execution is built around crates/evm/* and crates/revm, with crates/ethereum/evm adapting Ethereum config into the execution engine.
- Payload building for Engine API is handled by crates/payload/* and node-facing wrappers in crates/ethereum/node.
- The flow is: transactions and parent state are gathered, the EVM executes them, receipts/state roots are computed, and a sealed execution payload is produced for consensus.
6. Consensus boundary and Engine API
- Reth is an execution-layer client: it talks to a consensus client through the Engine API.
- crates/rpc/rpc-engine-api and the engine-related code in crates/rpc/rpc expose the execution-side Engine API endpoints.
- The node exposes forkchoice updates, new payload handling, and payload retrieval to the consensus layer, but does not implement consensus itself.
7. Networking and peer-to-peer sync
- crates/net/* contains the networking stack:
- discovery (discv4, discv5, DNS)
- encrypted transport and Ethereum wire protocols
- peer/session management
- block, body, receipt, header, snap, and transaction fetchers
- crates/p2p and crates/net/network coordinate network behavior and downloader policy.
- Data flows from remote peers into fetchers/downloader queues, then into the sync and import pipeline.
8. Staged synchronization and chain progress
- crates/stages/* and crates/stages/api implement the staged sync pipeline.
- The pipeline breaks sync into explicit steps such as headers, bodies, sender recovery, execution, hashing, Merkle/state-root generation, and pruning.
- This is a key architectural boundary: chain progress is not a single monolithic loop, but a staged state machine with checkpoints and unwind support.
9. Storage model and persistence
- crates/storage/* is the persistence layer.
- MDBX is the primary database backend, wrapped by storage/db and exposed through storage/provider and storage/storage-api.
- Static files are a first-class storage tier: crates/static-file/* manages append-only, segment-based persisted data separate from the primary DB.
- The architectural flow is: execution/import writes hot data to MDBX, durable historical data may be moved into static files, and providers read from both sources through consistent abstractions.
10. Trie, state, and proofs
- crates/trie/* holds the state-trie machinery:
- sparse trie structures
- trie DB and proof generation
- parallel root/proof computation
- witness and hashed-state helpers
- These crates sit between execution/state changes and storage, turning account/storage updates into Merkle roots and proofs used by sync, validation, and RPC.
11. Transaction pool and block building
- crates/transaction-pool manages incoming transactions, ordering, validation, blob handling, eviction, and pending/best-pool state.
- The payload builder consumes the pool to assemble candidate blocks.
- RPC, networking, and payload production all interact with the pool: the node accepts txs, gossips them, and uses them when creating execution payloads.
12. RPC surface
- crates/rpc/* provides the external API surface:
- standard Ethereum JSON-RPC modules
- debug/trace/admin/net/web3/txpool endpoints
- middleware, auth, compression, rate limiting, and IPC support
- rpc-eth-api contains the higher-level Ethereum RPC logic and helpers that read from storage, state, the pool, and execution data.
- This layer is read-heavy and depends on providers rather than directly mutating core state.
13. Extensions and auxiliary services
- crates/exex/* implements “execution extensions” that can subscribe to node events and maintain their own write-ahead log/backfill state.
- crates/node/metrics and crates/metrics publish operational metrics.
- crates/node/ethstats adds ethstats-style remote reporting.
- These are optional sidecar-like capabilities rather than core chain logic.
14. Import/export, era data, and data pipelines
- crates/era*, crates/etl, crates/chain-state, and CLI download/import commands support snapshot-era formats, bulk data movement, and chain-state tooling.
- crates/cli/commands contains operational commands for database inspection, pruning, import/export, downloads, and staged sync control.
- These tools sit around the main runtime and operate on the same storage formats and sync checkpoints.
15. Testing, examples, and ops footprint
- The repository includes extensive integration/e2e testing crates, Ethereum Foundation test runners, and many examples showing how to customize node components, RPC, EVM, networking, and payload building.
- etc/, Dockerfiles, GitHub workflows, and docs define the deployment, monitoring, and CI environment around the node, but they are not part of the runtime data path.
Main entry points: node/builder Builder · payload/builder Payloads · provider Provider · node Eth Node
Components 27
Runtime
Primary binaries and top-level launch points.
Node Orchestration
Node assembly, configuration, and optional services.
- Core · CLI args, config, datadir layout, logging, and process utilities.
crates/node/core - Builder · Composes consensus-facing services, execution, network, pool, RPC, and extensions.
crates/node/builder - Metrics · Node-level operational metrics and recording.
crates/node/metrics - Ethstats · Remote ethstats-style node reporting.
crates/node/ethstats
Ethereum Protocol
Ethereum-specific chain, payload, and EVM adapters.
Execution & Sync
Execution engine, staged sync, trie, and payload production.
- Payloads · Builds execution payloads for Engine API.
crates/payload/builder - Validator · Validates fork-specific payload constraints.
crates/payload/validator - Stages API · Pipeline control, progress, metrics, and stage interfaces.
crates/stages/api - Stages · Headers, bodies, sender recovery, execution, hashing, merkle, prune, and era stages.
crates/stages/stages - Trie · Trie, proof, sparse-trie, and parallel root computation machinery.
crates/trie/trie - Tx Pool · Validates, orders, evicts, and serves pending/best transactions.
crates/transaction-pool
Storage
Database, providers, and static-file persistence.
- Provider · Consistent read/write access across hot DB and static files.
crates/storage/provider - MDBX · Primary MDBX database implementation and transaction handling.
crates/storage/db - Static Files · Append-only persisted historical segments separate from the primary DB.
crates/static-file/static-file
Networking
Peer discovery, wire protocols, downloaders, and sync networking.
RPC
External JSON-RPC and Engine API surfaces.
- RPC API · Ethereum JSON-RPC, admin/debug/trace/net/web3, and Engine API modules.
crates/rpc/rpc - Engine API · Execution-side Engine API endpoints for forkchoice and payload exchange.
crates/rpc/rpc-engine-api - RPC Builder · RPC server construction, auth, compression, middleware, and limits.
crates/rpc/rpc-builder
Ops & Tooling
CLI commands, import/export, extensions, and auxiliary tooling.
- CLI Commands · Operational commands for node control, DB inspection, import/export, prune, and stages.
crates/cli/commands - ExEx · Execution extensions with notifications and WAL/backfill state.
crates/exex/exex - Era Tools · Era formats, downloader utilities, and bulk data movement tooling.
crates/era
Connections 39
- reth → Core: uses · Parses CLI and runtime configuration.
- reth → Builder: assembles · Builds the full node from reusable components.
- reth-bb → Eth EVM: benchmarks · Drives EVM execution and configuration.
- Builder → Chainspec: loads · Selects chain rules and hardfork behavior.
- Builder → Eth Node: wires · Connects Ethereum semantics into the node.
- Builder → Network: starts · Brings up peer-to-peer networking.
- Builder → Tx Pool: attaches · Integrates transaction validation and pending state.
- Builder → Payloads: attaches · Configures payload production for consensus.
- Builder → RPC Builder: exposes · Creates the RPC server stack.
- Builder → ExEx: optionally runs · Loads execution extensions when enabled.
- Builder → Metrics: publishes · Emits node operational metrics.
- Builder → Ethstats: reports · Sends ethstats-style status updates.
- Eth Node → Eth EVM: adapts · Binds Ethereum config into execution.
- Eth Node → Validator: validates · Applies fork-specific payload checks.
- Eth Node → Engine API: serves · Connects Ethereum node state to Engine API.
- Payloads → Eth EVM: executes · Runs transactions through the EVM.
- Payloads → Tx Pool: consumes · Selects transactions from the pool.
- Payloads → Trie: finalizes · Computes state roots and proofs for payload output.
- Payloads → Validator: checks · Applies protocol rules before sealing.
- Stages → Stages API: implements · Provides the staged sync pipeline implementation.
- Stages → Trie: uses · Hashes state and generates trie roots.
- Stages → Provider: reads/writes · Persists checkpoints, headers, bodies, and execution results.
- Trie → Provider: reads · Consumes state and proof data from storage abstractions.
- Provider → MDBX: backs · Uses MDBX as the primary hot store.
- Provider → Static Files: extends · Reads historical data from static-file segments.
- Network → Wire: speaks · Uses wire protocol and session transport.
- Network → P2P: coordinates · Delegates downloader and sync policy.
- P2P → Tx Pool: gossips · Feeds transaction propagation and pool requests.
- P2P → Stages: feeds · Supplies headers, bodies, receipts, and snap data into sync.
- RPC API → Provider: reads · Serves data from provider-backed state and history.
- RPC API → Tx Pool: reads · Exposes pending and txpool-related views.
- RPC API → Eth Node: delegates · Uses Ethereum-specific helpers and node glue.
- Engine API → Payloads: requests · Obtains new payloads and payload attributes.
- RPC Builder → RPC API: hosts · Mounts modules behind HTTP/WS/IPCs.
- RPC Builder → Engine API: hosts · Exposes Engine API endpoints.
- CLI Commands → Stages API: controls · Runs and unwinds staged sync operations.
- CLI Commands → Provider: inspects · Performs DB and static-file administration.
- CLI Commands → Era Tools: imports/exports · Handles era downloads, conversion, and bulk data movement.
- ExEx → Builder: hooks into · Subscribes to node events and lifecycle hooks.