# bnb-chain/reth architecture

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

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

## Overview

Reth is a modular Ethereum execution-layer client. Its principal workflow is to configure and launch a node, receive consensus-layer Engine API payloads, validate and execute them, and maintain chain state for synchronization and queries. The map also includes networking, staged storage maintenance, pruning, and execution extensions. Relationships are limited to those shown in the README or sampled source/index; dashed links mark important runtime connections not verified by the excerpts.

Main entry points: [`crates/engine/tree/src/engine.rs`](https://github.com/bnb-chain/reth/blob/main/crates/engine/tree/src/engine.rs) (Engine tree), [`crates/net/network/src/manager.rs`](https://github.com/bnb-chain/reth/blob/main/crates/net/network/src/manager.rs) (Network manager), [`crates/storage/storage-api/src/storage.rs`](https://github.com/bnb-chain/reth/blob/main/crates/storage/storage-api/src/storage.rs) (Storage interfaces), [`crates/cli/commands/src/node.rs`](https://github.com/bnb-chain/reth/blob/main/crates/cli/commands/src/node.rs) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_node["Node and API"]
  node_cli["CLI commands<br/>[node.rs]"]
  node_engine_args["Engine options<br/>[engine.rs]"]
  node_node_config["Node configuration<br/>[node_config.rs]"]
  node_node_launch["Node launch<br/>[engine.rs]"]
  node_engine_rpc["Engine API RPC<br/>[engine.rs]"]
end

subgraph group_engine["Execution and payloads"]
  node_eth_validator["Ethereum payload validation<br/>[engine.rs]"]
  node_engine_tree["Engine tree<br/>[engine.rs]"]
  node_evm_engine["Payload execution<br/>[engine.rs]"]
  node_evm_execute["Transaction execution<br/>[execute.rs]"]
  node_payload_service["Payload building<br/>[service.rs]"]
end

subgraph group_network["Peer networking"]
  node_network_manager["Network manager<br/>[manager.rs]"]
  node_network_state["Peer and chain state<br/>[state.rs]"]
  node_eth_requests["Peer data requests<br/>[eth_requests.rs]"]
end

subgraph group_storage["Chain data"]
  node_storage_api["Storage interfaces<br/>[storage.rs]"]
  node_hashed_storage["Storage hashing stage<br/>[hashing_storage.rs]"]
  node_storage_history_index["Storage history index"]
  node_storage_pruning["Storage history pruning<br/>[storage_history.rs]"]
  node_trie_storage["Trie storage roots<br/>[storage.rs]"]
end

subgraph group_extensions["Extensions"]
  node_exex_manager["Execution extensions<br/>[manager.rs]"]
  node_exex_wal[("Extension event log<br/>[storage.rs]")]
end

node_operator(("Node operator"))
node_consensus(("Consensus client"))

node_operator -->|"runs"| node_cli
node_cli -.->|"launches"| node_node_launch
node_engine_args -->|"configures"| node_node_config
node_node_config -.->|"configures"| node_node_launch
node_consensus -->|"sends payloads"| node_engine_rpc
node_engine_rpc -.->|"dispatches to"| node_engine_tree
node_engine_tree -.->|"validates payloads"| node_eth_validator
node_engine_tree -.->|"executes payloads"| node_evm_engine
node_evm_engine -->|"uses"| node_evm_execute
node_engine_tree -.->|"requests builds"| node_payload_service
node_network_manager -->|"updates"| node_network_state
node_network_manager -->|"uses"| node_eth_requests
node_network_manager -->|"configures via builder"| node_network_manager
node_storage_api -.->|"provides reads"| node_trie_storage
node_hashed_storage -.->|"reads changesets"| node_storage_api
node_storage_history_index -.->|"indexes history"| node_storage_api
node_storage_pruning -.->|"prunes history"| node_storage_api
node_exex_manager -.->|"persists notifications"| node_exex_wal

click node_cli "https://github.com/bnb-chain/reth/blob/main/crates/cli/commands/src/node.rs"
click node_engine_args "https://github.com/bnb-chain/reth/blob/main/crates/node/core/src/args/engine.rs"
click node_node_config "https://github.com/bnb-chain/reth/blob/main/crates/node/core/src/node_config.rs"
click node_node_launch "https://github.com/bnb-chain/reth/blob/main/crates/node/builder/src/launch/engine.rs"
click node_engine_rpc "https://github.com/bnb-chain/reth/blob/main/crates/rpc/rpc/src/engine.rs"
click node_eth_validator "https://github.com/bnb-chain/reth/blob/main/crates/ethereum/node/src/engine.rs"
click node_engine_tree "https://github.com/bnb-chain/reth/blob/main/crates/engine/tree/src/engine.rs"
click node_evm_engine "https://github.com/bnb-chain/reth/blob/main/crates/evm/evm/src/engine.rs"
click node_evm_execute "https://github.com/bnb-chain/reth/blob/main/crates/evm/evm/src/execute.rs"
click node_payload_service "https://github.com/bnb-chain/reth/blob/main/crates/payload/builder/src/service.rs"
click node_network_manager "https://github.com/bnb-chain/reth/blob/main/crates/net/network/src/manager.rs"
click node_network_state "https://github.com/bnb-chain/reth/blob/main/crates/net/network/src/state.rs"
click node_eth_requests "https://github.com/bnb-chain/reth/blob/main/crates/net/network/src/eth_requests.rs"
click node_storage_api "https://github.com/bnb-chain/reth/blob/main/crates/storage/storage-api/src/storage.rs"
click node_hashed_storage "https://github.com/bnb-chain/reth/blob/main/crates/stages/stages/src/stages/hashing_storage.rs"
click node_storage_history_index "https://github.com/bnb-chain/reth/blob/main/crates/stages/stages/src/stages/index_storage_history.rs"
click node_storage_pruning "https://github.com/bnb-chain/reth/blob/main/crates/prune/prune/src/segments/user/storage_history.rs"
click node_trie_storage "https://github.com/bnb-chain/reth/blob/main/crates/trie/db/src/storage.rs"
click node_exex_manager "https://github.com/bnb-chain/reth/blob/main/crates/exex/exex/src/manager.rs"
click node_exex_wal "https://github.com/bnb-chain/reth/blob/main/crates/exex/exex/src/wal/storage.rs"

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_cli,node_engine_args,node_node_config,node_node_launch,node_engine_rpc,node_consensus toneBlue
class node_eth_validator,node_engine_tree,node_evm_engine,node_evm_execute,node_payload_service toneAmber
class node_network_manager,node_network_state,node_eth_requests toneMint
class node_storage_api,node_hashed_storage,node_storage_history_index,node_storage_pruning,node_trie_storage toneRose
class node_exex_manager,node_exex_wal,node_operator toneIndigo
```

## Components

### Node and API

- [CLI commands](https://github.com/bnb-chain/reth/blob/main/crates/cli/commands/src/node.rs): `crates/cli/commands/src/node.rs`
- [Engine options](https://github.com/bnb-chain/reth/blob/main/crates/node/core/src/args/engine.rs): `crates/node/core/src/args/engine.rs`
- [Node configuration](https://github.com/bnb-chain/reth/blob/main/crates/node/core/src/node_config.rs): `crates/node/core/src/node_config.rs`
- [Node launch](https://github.com/bnb-chain/reth/blob/main/crates/node/builder/src/launch/engine.rs): `crates/node/builder/src/launch/engine.rs`
- [Engine API RPC](https://github.com/bnb-chain/reth/blob/main/crates/rpc/rpc/src/engine.rs): `crates/rpc/rpc/src/engine.rs`

### Execution and payloads

- [Ethereum payload validation](https://github.com/bnb-chain/reth/blob/main/crates/ethereum/node/src/engine.rs): `crates/ethereum/node/src/engine.rs`
- [Engine tree](https://github.com/bnb-chain/reth/blob/main/crates/engine/tree/src/engine.rs): `crates/engine/tree/src/engine.rs`
- [Payload execution](https://github.com/bnb-chain/reth/blob/main/crates/evm/evm/src/engine.rs): `crates/evm/evm/src/engine.rs`
- [Transaction execution](https://github.com/bnb-chain/reth/blob/main/crates/evm/evm/src/execute.rs): `crates/evm/evm/src/execute.rs`
- [Payload building](https://github.com/bnb-chain/reth/blob/main/crates/payload/builder/src/service.rs): `crates/payload/builder/src/service.rs`

### Peer networking

- [Network manager](https://github.com/bnb-chain/reth/blob/main/crates/net/network/src/manager.rs): `crates/net/network/src/manager.rs`
- [Peer and chain state](https://github.com/bnb-chain/reth/blob/main/crates/net/network/src/state.rs): `crates/net/network/src/state.rs`
- [Peer data requests](https://github.com/bnb-chain/reth/blob/main/crates/net/network/src/eth_requests.rs): `crates/net/network/src/eth_requests.rs`

### Chain data

- [Storage interfaces](https://github.com/bnb-chain/reth/blob/main/crates/storage/storage-api/src/storage.rs): `crates/storage/storage-api/src/storage.rs`
- [Storage hashing stage](https://github.com/bnb-chain/reth/blob/main/crates/stages/stages/src/stages/hashing_storage.rs): `crates/stages/stages/src/stages/hashing_storage.rs`
- [Storage history index](https://github.com/bnb-chain/reth/blob/main/crates/stages/stages/src/stages/index_storage_history.rs): `crates/stages/stages/src/stages/index_storage_history.rs`
- [Storage history pruning](https://github.com/bnb-chain/reth/blob/main/crates/prune/prune/src/segments/user/storage_history.rs): `crates/prune/prune/src/segments/user/storage_history.rs`
- [Trie storage roots](https://github.com/bnb-chain/reth/blob/main/crates/trie/db/src/storage.rs): `crates/trie/db/src/storage.rs`

### Extensions

- [Execution extensions](https://github.com/bnb-chain/reth/blob/main/crates/exex/exex/src/manager.rs): `crates/exex/exex/src/manager.rs`
- [Extension event log](https://github.com/bnb-chain/reth/blob/main/crates/exex/exex/src/wal/storage.rs): `crates/exex/exex/src/wal/storage.rs`

### Other components

- **Node operator**
- **Consensus client**

## Connections

- Node operator → CLI commands: runs (evidence: `README.md`)
- CLI commands → Node launch: launches
- Engine options → Node configuration: configures (evidence: `crates/node/core/src/args/engine.rs`)
- Node configuration → Node launch: configures
- Consensus client → Engine API RPC: sends payloads (evidence: `README.md`)
- Engine API RPC → Engine tree: dispatches to
- Engine tree → Ethereum payload validation: validates payloads
- Engine tree → Payload execution: executes payloads
- Payload execution → Transaction execution: uses (evidence: `crates/evm/evm/src/engine.rs`)
- Engine tree → Payload building: requests builds
- Network manager → Peer and chain state: updates (evidence: `crates/net/network/src/manager.rs`)
- Network manager → Peer data requests: uses (evidence: `crates/net/network/src/manager.rs`)
- Network manager → Network manager: configures via builder (evidence: `crates/net/network/src/manager.rs`)
- Storage interfaces → Trie storage roots: provides reads
- Storage hashing stage → Storage interfaces: reads changesets
- Storage history index → Storage interfaces: indexes history
- Storage history pruning → Storage interfaces: prunes history
- Execution extensions → Extension event log: persists notifications
