# paradigmxyz/reth architecture

> Architecture diagram of the GitHub repository paradigmxyz/reth, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paradigmxyz/reth
- Repository: https://github.com/paradigmxyz/reth

## Overview

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: [`crates/node/builder`](https://github.com/paradigmxyz/reth/tree/main/crates/node/builder) (Builder), [`crates/payload/builder`](https://github.com/paradigmxyz/reth/tree/main/crates/payload/builder) (Payloads), [`crates/storage/provider`](https://github.com/paradigmxyz/reth/tree/main/crates/storage/provider) (Provider), [`crates/ethereum/node`](https://github.com/paradigmxyz/reth/tree/main/crates/ethereum/node) (Eth Node)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_runtime["Runtime"]
  node_bin_reth["reth<br/>binary"]
  node_bin_reth_bb["reth-bb<br/>binary"]
end

subgraph group_g_node["Node Orchestration"]
  node_node_core["Core<br/>node config"]
  node_node_builder["Builder<br/>node assembly"]
  node_node_metrics["Metrics<br/>node ops"]
  node_node_ethstats["Ethstats<br/>reporting"]
end

subgraph group_g_protocol["Ethereum Protocol"]
  node_chainspec["Chainspec<br/>chain spec"]
  node_ethereum_node["Eth Node<br/>ethereum glue"]
  node_ethereum_evm["Eth EVM<br/>evm adapter"]
end

subgraph group_g_exec["Execution & Sync"]
  node_payload_builder["Payloads<br/>block builder"]
  node_payload_validator["Validator<br/>payload rules"]
  node_stages_api["Stages API<br/>pipeline api"]
  node_stages_impl["Stages<br/>sync pipeline"]
  node_trie["Trie"]
  node_transaction_pool["Tx Pool<br/>txpool"]
end

subgraph group_g_storage["Storage"]
  node_storage_provider["Provider"]
  node_storage_db["MDBX<br/>database backend"]
  node_static_file["Static Files<br/>historical store"]
end

subgraph group_g_network["Networking"]
  node_net_network["Network<br/>p2p swarm"]
  node_net_p2p["P2P<br/>download sync"]
  node_net_wire["Wire<br/>eth protocol"]
end

subgraph group_g_rpc["RPC"]
  node_rpc_api["RPC API<br/>rpc surface"]
  node_rpc_engine["Engine API<br/>consensus rpc"]
  node_rpc_builder["RPC Builder<br/>server stack"]
end

subgraph group_g_tools["Ops & Tooling"]
  node_cli_commands["CLI Commands<br/>ops cli"]
  node_exex["ExEx<br/>extensions"]
  node_era_tools["Era Tools<br/>data pipeline"]
end

node_bin_reth -->|"uses"| node_node_core
node_bin_reth -->|"assembles"| node_node_builder
node_bin_reth_bb -->|"benchmarks"| node_ethereum_evm
node_node_builder -->|"loads"| node_chainspec
node_node_builder -->|"wires"| node_ethereum_node
node_node_builder -->|"starts"| node_net_network
node_node_builder -->|"attaches"| node_transaction_pool
node_node_builder -->|"attaches"| node_payload_builder
node_node_builder -->|"exposes"| node_rpc_builder
node_node_builder -->|"optionally runs"| node_exex
node_node_builder -->|"publishes"| node_node_metrics
node_node_builder -->|"reports"| node_node_ethstats
node_ethereum_node -->|"adapts"| node_ethereum_evm
node_ethereum_node -->|"validates"| node_payload_validator
node_ethereum_node -->|"serves"| node_rpc_engine
node_payload_builder -->|"executes"| node_ethereum_evm
node_payload_builder -->|"consumes"| node_transaction_pool
node_payload_builder -->|"finalizes"| node_trie
node_payload_builder -->|"checks"| node_payload_validator
node_stages_impl -->|"implements"| node_stages_api
node_stages_impl -->|"uses"| node_trie
node_stages_impl -->|"reads/writes"| node_storage_provider
node_trie -->|"reads"| node_storage_provider
node_storage_provider -->|"backs"| node_storage_db
node_storage_provider -->|"extends"| node_static_file
node_net_network -->|"speaks"| node_net_wire
node_net_network -->|"coordinates"| node_net_p2p
node_net_p2p -->|"gossips"| node_transaction_pool
node_net_p2p -->|"feeds"| node_stages_impl
node_rpc_api -->|"reads"| node_storage_provider
node_rpc_api -->|"reads"| node_transaction_pool
node_rpc_api -->|"delegates"| node_ethereum_node
node_rpc_engine -->|"requests"| node_payload_builder
node_rpc_builder -->|"hosts"| node_rpc_api
node_rpc_builder -->|"hosts"| node_rpc_engine
node_cli_commands -->|"controls"| node_stages_api
node_cli_commands -->|"inspects"| node_storage_provider
node_cli_commands -->|"imports/exports"| node_era_tools
node_exex -->|"hooks into"| node_node_builder

click node_bin_reth "https://github.com/paradigmxyz/reth/tree/main/bin/reth"
click node_bin_reth_bb "https://github.com/paradigmxyz/reth/tree/main/bin/reth-bb"
click node_node_core "https://github.com/paradigmxyz/reth/tree/main/crates/node/core"
click node_node_builder "https://github.com/paradigmxyz/reth/tree/main/crates/node/builder"
click node_node_metrics "https://github.com/paradigmxyz/reth/tree/main/crates/node/metrics"
click node_node_ethstats "https://github.com/paradigmxyz/reth/tree/main/crates/node/ethstats"
click node_chainspec "https://github.com/paradigmxyz/reth/tree/main/crates/chainspec"
click node_ethereum_node "https://github.com/paradigmxyz/reth/tree/main/crates/ethereum/node"
click node_ethereum_evm "https://github.com/paradigmxyz/reth/tree/main/crates/ethereum/evm"
click node_payload_builder "https://github.com/paradigmxyz/reth/tree/main/crates/payload/builder"
click node_payload_validator "https://github.com/paradigmxyz/reth/tree/main/crates/payload/validator"
click node_stages_api "https://github.com/paradigmxyz/reth/tree/main/crates/stages/api"
click node_stages_impl "https://github.com/paradigmxyz/reth/tree/main/crates/stages/stages"
click node_trie "https://github.com/paradigmxyz/reth/tree/main/crates/trie/trie"
click node_transaction_pool "https://github.com/paradigmxyz/reth/tree/main/crates/transaction-pool"
click node_storage_provider "https://github.com/paradigmxyz/reth/tree/main/crates/storage/provider"
click node_storage_db "https://github.com/paradigmxyz/reth/tree/main/crates/storage/db"
click node_static_file "https://github.com/paradigmxyz/reth/tree/main/crates/static-file/static-file"
click node_net_network "https://github.com/paradigmxyz/reth/tree/main/crates/net/network"
click node_net_p2p "https://github.com/paradigmxyz/reth/tree/main/crates/net/p2p"
click node_net_wire "https://github.com/paradigmxyz/reth/tree/main/crates/net/eth-wire"
click node_rpc_api "https://github.com/paradigmxyz/reth/tree/main/crates/rpc/rpc"
click node_rpc_engine "https://github.com/paradigmxyz/reth/tree/main/crates/rpc/rpc-engine-api"
click node_rpc_builder "https://github.com/paradigmxyz/reth/tree/main/crates/rpc/rpc-builder"
click node_cli_commands "https://github.com/paradigmxyz/reth/tree/main/crates/cli/commands"
click node_exex "https://github.com/paradigmxyz/reth/tree/main/crates/exex/exex"
click node_era_tools "https://github.com/paradigmxyz/reth/tree/main/crates/era"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bin_reth,node_bin_reth_bb,node_rpc_api,node_rpc_engine,node_rpc_builder toneBlue
class node_node_core,node_node_builder,node_node_metrics,node_node_ethstats,node_cli_commands,node_exex,node_era_tools toneAmber
class node_chainspec,node_ethereum_node,node_ethereum_evm toneMint
class node_payload_builder,node_payload_validator,node_stages_api,node_stages_impl,node_trie,node_transaction_pool toneRose
class node_storage_provider,node_storage_db,node_static_file toneIndigo
class node_net_network,node_net_p2p,node_net_wire toneTeal
```

## Components

### Runtime

Primary binaries and top-level launch points.

- [reth](https://github.com/paradigmxyz/reth/tree/main/bin/reth): binary · Main node executable assembling the full client. · `bin/reth`
- [reth-bb](https://github.com/paradigmxyz/reth/tree/main/bin/reth-bb): binary · Benchmarking/build-bundle tool focused on EVM execution. · `bin/reth-bb`

### Node Orchestration

Node assembly, configuration, and optional services.

- [Core](https://github.com/paradigmxyz/reth/tree/main/crates/node/core): node config · CLI args, config, datadir layout, logging, and process utilities. · `crates/node/core`
- [Builder](https://github.com/paradigmxyz/reth/tree/main/crates/node/builder): node assembly · Composes consensus-facing services, execution, network, pool, RPC, and extensions. · `crates/node/builder`
- [Metrics](https://github.com/paradigmxyz/reth/tree/main/crates/node/metrics): node ops · Node-level operational metrics and recording. · `crates/node/metrics`
- [Ethstats](https://github.com/paradigmxyz/reth/tree/main/crates/node/ethstats): reporting · Remote ethstats-style node reporting. · `crates/node/ethstats`

### Ethereum Protocol

Ethereum-specific chain, payload, and EVM adapters.

- [Chainspec](https://github.com/paradigmxyz/reth/tree/main/crates/chainspec): chain spec · Ethereum chain specs, constants, and hardfork definitions. · `crates/chainspec`
- [Eth Node](https://github.com/paradigmxyz/reth/tree/main/crates/ethereum/node): ethereum glue · Ethereum-specific node wiring and engine integration. · `crates/ethereum/node`
- [Eth EVM](https://github.com/paradigmxyz/reth/tree/main/crates/ethereum/evm): evm adapter · Adapts Ethereum config into execution and receipt handling. · `crates/ethereum/evm`

### Execution & Sync

Execution engine, staged sync, trie, and payload production.

- [Payloads](https://github.com/paradigmxyz/reth/tree/main/crates/payload/builder): block builder · Builds execution payloads for Engine API. · `crates/payload/builder`
- [Validator](https://github.com/paradigmxyz/reth/tree/main/crates/payload/validator): payload rules · Validates fork-specific payload constraints. · `crates/payload/validator`
- [Stages API](https://github.com/paradigmxyz/reth/tree/main/crates/stages/api): pipeline api · Pipeline control, progress, metrics, and stage interfaces. · `crates/stages/api`
- [Stages](https://github.com/paradigmxyz/reth/tree/main/crates/stages/stages): sync pipeline · Headers, bodies, sender recovery, execution, hashing, merkle, prune, and era stages. · `crates/stages/stages`
- [Trie](https://github.com/paradigmxyz/reth/tree/main/crates/trie/trie): state trie · Trie, proof, sparse-trie, and parallel root computation machinery. · `crates/trie/trie`
- [Tx Pool](https://github.com/paradigmxyz/reth/tree/main/crates/transaction-pool): txpool · Validates, orders, evicts, and serves pending/best transactions. · `crates/transaction-pool`

### Storage

Database, providers, and static-file persistence.

- [Provider](https://github.com/paradigmxyz/reth/tree/main/crates/storage/provider): storage provider · Consistent read/write access across hot DB and static files. · `crates/storage/provider`
- [MDBX](https://github.com/paradigmxyz/reth/tree/main/crates/storage/db): database backend · Primary MDBX database implementation and transaction handling. · `crates/storage/db`
- [Static Files](https://github.com/paradigmxyz/reth/tree/main/crates/static-file/static-file): historical store · Append-only persisted historical segments separate from the primary DB. · `crates/static-file/static-file`

### Networking

Peer discovery, wire protocols, downloaders, and sync networking.

- [Network](https://github.com/paradigmxyz/reth/tree/main/crates/net/network): p2p swarm · Peer management, discovery, sessions, import, and fetch orchestration. · `crates/net/network`
- [P2P](https://github.com/paradigmxyz/reth/tree/main/crates/net/p2p): download sync · Block/header/body/receipt/snap downloaders and sync coordination. · `crates/net/p2p`
- [Wire](https://github.com/paradigmxyz/reth/tree/main/crates/net/eth-wire): eth protocol · RLPx, handshake, multiplexing, and Ethereum wire protocols. · `crates/net/eth-wire`

### RPC

External JSON-RPC and Engine API surfaces.

- [RPC API](https://github.com/paradigmxyz/reth/tree/main/crates/rpc/rpc): rpc surface · Ethereum JSON-RPC, admin/debug/trace/net/web3, and Engine API modules. · `crates/rpc/rpc`
- [Engine API](https://github.com/paradigmxyz/reth/tree/main/crates/rpc/rpc-engine-api): consensus rpc · Execution-side Engine API endpoints for forkchoice and payload exchange. · `crates/rpc/rpc-engine-api`
- [RPC Builder](https://github.com/paradigmxyz/reth/tree/main/crates/rpc/rpc-builder): server stack · RPC server construction, auth, compression, middleware, and limits. · `crates/rpc/rpc-builder`

### Ops & Tooling

CLI commands, import/export, extensions, and auxiliary tooling.

- [CLI Commands](https://github.com/paradigmxyz/reth/tree/main/crates/cli/commands): ops cli · Operational commands for node control, DB inspection, import/export, prune, and stages. · `crates/cli/commands`
- [ExEx](https://github.com/paradigmxyz/reth/tree/main/crates/exex/exex): extensions · Execution extensions with notifications and WAL/backfill state. · `crates/exex/exex`
- [Era Tools](https://github.com/paradigmxyz/reth/tree/main/crates/era): data pipeline · Era formats, downloader utilities, and bulk data movement tooling. · `crates/era`

## Connections

- 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.
