# bnb-chain/reth-bsc architecture

> Architecture diagram of the GitHub repository bnb-chain/reth-bsc, 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-bsc
- Repository: https://github.com/bnb-chain/reth-bsc

## Overview

Reth @ BSC is a Reth-based BSC execution client. Its main workflow is to start a node for a selected chain, synchronize and import blocks, validate them with BSC-specific execution and Parlia consensus rules, persist node state, and optionally serve RPC and MEV services. The map preserves documented sync, RPC, EVN, and bid-block capabilities. Several subsystem paths are supported by the tree and README, but their internal wiring was not sampled, so those connections are omitted.

Main entry points: [`src/node/mod.rs`](https://github.com/bnb-chain/reth-bsc/blob/main/src/node/mod.rs) (BSC Node Setup), [`src/node/network/bsc_protocol/registry.rs`](https://github.com/bnb-chain/reth-bsc/blob/main/src/node/network/bsc_protocol/registry.rs) (BSC Networking), [`src/chainspec/mod.rs`](https://github.com/bnb-chain/reth-bsc/blob/main/src/chainspec/mod.rs) (Chain Specification), [`src/main.rs`](https://github.com/bnb-chain/reth-bsc/blob/main/src/main.rs) (Node CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chain["Chain Rules"]
  node_chainspec["Chain Specification<br/>[mod.rs]"]
  node_hardforks["BSC Hardforks<br/>[bsc.rs]"]
  node_system_contracts["System Contracts<br/>[mod.rs]"]
end

subgraph group_runtime["Node Runtime"]
  node_cli["Node CLI<br/>[main.rs]"]
  node_node["BSC Node Setup<br/>[mod.rs]"]
  node_evm["EVM Execution<br/>[config.rs]"]
  node_import["Block Import<br/>[service.rs]"]
  node_network["BSC Networking<br/>[registry.rs]"]
  node_storage[("Node Storage<br/>[storage.rs]")]
end

subgraph group_consensus["Consensus and Mining"]
  node_parlia["Parlia Consensus<br/>[consensus.rs]"]
  node_snapshots[("Validator Snapshots<br/>[snapshot.rs]")]
  node_votes["Vote Pool<br/>[vote_pool.rs]"]
  node_miner["Payload Mining<br/>[bid_block.rs]"]
end

subgraph group_interfaces["Client Interfaces"]
  node_rpc["RPC APIs<br/>[eth_ext.rs]"]
  node_mev_rpc["MEV RPC<br/>[mev.rs]"]
  node_mev_grpc["MEV gRPC<br/>[mev.rs]"]
  node_evn["EVN Handshake<br/>[evn.rs]"]
  node_metrics["Metrics<br/>[metrics.rs]"]
end

node_operator(("Node Operator"))

node_operator -->|"starts node"| node_cli
node_cli -->|"selects chain"| node_chainspec
node_node -->|"configures"| node_evm
node_node -.->|"configures"| node_import
node_import -->|"uses consensus"| node_parlia
node_network -->|"dispatches votes"| node_votes
node_votes -->|"checks origins"| node_snapshots
node_chainspec -->|"defines activations"| node_hardforks
node_system_contracts -->|"selects fork code"| node_hardforks
node_node -->|"configures storage"| node_storage
node_operator -->|"queries node"| node_rpc
node_operator -.->|"submits bids"| node_mev_rpc
node_mev_rpc -->|"accesses bid tools"| node_miner
node_mev_grpc -->|"uses bid blocks"| node_miner
node_network -->|"signals EVN"| node_evn
node_operator -->|"monitors node"| node_metrics

click node_cli "https://github.com/bnb-chain/reth-bsc/blob/main/src/main.rs"
click node_chainspec "https://github.com/bnb-chain/reth-bsc/blob/main/src/chainspec/mod.rs"
click node_hardforks "https://github.com/bnb-chain/reth-bsc/blob/main/src/hardforks/bsc.rs"
click node_system_contracts "https://github.com/bnb-chain/reth-bsc/blob/main/src/system_contracts/mod.rs"
click node_node "https://github.com/bnb-chain/reth-bsc/blob/main/src/node/mod.rs"
click node_evm "https://github.com/bnb-chain/reth-bsc/blob/main/src/node/evm/config.rs"
click node_import "https://github.com/bnb-chain/reth-bsc/blob/main/src/node/network/block_import/service.rs"
click node_network "https://github.com/bnb-chain/reth-bsc/blob/main/src/node/network/bsc_protocol/registry.rs"
click node_storage "https://github.com/bnb-chain/reth-bsc/blob/main/src/node/storage.rs"
click node_parlia "https://github.com/bnb-chain/reth-bsc/blob/main/src/consensus/parlia/consensus.rs"
click node_snapshots "https://github.com/bnb-chain/reth-bsc/blob/main/src/consensus/parlia/snapshot.rs"
click node_votes "https://github.com/bnb-chain/reth-bsc/blob/main/src/consensus/parlia/vote_pool.rs"
click node_miner "https://github.com/bnb-chain/reth-bsc/blob/main/src/node/miner/bid_block.rs"
click node_rpc "https://github.com/bnb-chain/reth-bsc/blob/main/src/rpc/eth_ext.rs"
click node_mev_rpc "https://github.com/bnb-chain/reth-bsc/blob/main/src/rpc/mev.rs"
click node_mev_grpc "https://github.com/bnb-chain/reth-bsc/blob/main/src/grpc/mev.rs"
click node_evn "https://github.com/bnb-chain/reth-bsc/blob/main/src/node/network/evn.rs"
click node_metrics "https://github.com/bnb-chain/reth-bsc/blob/main/src/metrics.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_chainspec,node_hardforks,node_system_contracts toneBlue
class node_cli,node_node,node_evm,node_import,node_network,node_storage toneAmber
class node_parlia,node_snapshots,node_votes,node_miner toneMint
class node_rpc,node_mev_rpc,node_mev_grpc,node_evn,node_metrics toneRose
class node_operator toneIndigo
```

## Components

### Chain Rules

- [Chain Specification](https://github.com/bnb-chain/reth-bsc/blob/main/src/chainspec/mod.rs): `src/chainspec/mod.rs`
- [BSC Hardforks](https://github.com/bnb-chain/reth-bsc/blob/main/src/hardforks/bsc.rs): `src/hardforks/bsc.rs`
- [System Contracts](https://github.com/bnb-chain/reth-bsc/blob/main/src/system_contracts/mod.rs): `src/system_contracts/mod.rs`

### Node Runtime

- [Node CLI](https://github.com/bnb-chain/reth-bsc/blob/main/src/main.rs): `src/main.rs`
- [BSC Node Setup](https://github.com/bnb-chain/reth-bsc/blob/main/src/node/mod.rs): `src/node/mod.rs`
- [EVM Execution](https://github.com/bnb-chain/reth-bsc/blob/main/src/node/evm/config.rs): `src/node/evm/config.rs`
- [Block Import](https://github.com/bnb-chain/reth-bsc/blob/main/src/node/network/block_import/service.rs): `src/node/network/block_import/service.rs`
- [BSC Networking](https://github.com/bnb-chain/reth-bsc/blob/main/src/node/network/bsc_protocol/registry.rs): `src/node/network/bsc_protocol/registry.rs`
- [Node Storage](https://github.com/bnb-chain/reth-bsc/blob/main/src/node/storage.rs): `src/node/storage.rs`

### Consensus and Mining

- [Parlia Consensus](https://github.com/bnb-chain/reth-bsc/blob/main/src/consensus/parlia/consensus.rs): `src/consensus/parlia/consensus.rs`
- [Validator Snapshots](https://github.com/bnb-chain/reth-bsc/blob/main/src/consensus/parlia/snapshot.rs): `src/consensus/parlia/snapshot.rs`
- [Vote Pool](https://github.com/bnb-chain/reth-bsc/blob/main/src/consensus/parlia/vote_pool.rs): `src/consensus/parlia/vote_pool.rs`
- [Payload Mining](https://github.com/bnb-chain/reth-bsc/blob/main/src/node/miner/bid_block.rs): `src/node/miner/bid_block.rs`

### Client Interfaces

- [RPC APIs](https://github.com/bnb-chain/reth-bsc/blob/main/src/rpc/eth_ext.rs): `src/rpc/eth_ext.rs`
- [MEV RPC](https://github.com/bnb-chain/reth-bsc/blob/main/src/rpc/mev.rs): `src/rpc/mev.rs`
- [MEV gRPC](https://github.com/bnb-chain/reth-bsc/blob/main/src/grpc/mev.rs): `src/grpc/mev.rs`
- [EVN Handshake](https://github.com/bnb-chain/reth-bsc/blob/main/src/node/network/evn.rs): `src/node/network/evn.rs`
- [Metrics](https://github.com/bnb-chain/reth-bsc/blob/main/src/metrics.rs): `src/metrics.rs`

### Other components

- **Node Operator**

## Connections

- Node Operator → Node CLI: starts node (evidence: `README.md`)
- Node CLI → Chain Specification: selects chain (evidence: `README.md`)
- BSC Node Setup → EVM Execution: configures (evidence: `src/node/mod.rs`)
- BSC Node Setup → Block Import: configures
- Block Import → Parlia Consensus: uses consensus (evidence: `src/node/network/block_import/service.rs`)
- BSC Networking → Vote Pool: dispatches votes (evidence: `src/node/network/bsc_protocol/registry.rs`)
- Vote Pool → Validator Snapshots: checks origins (evidence: `src/consensus/parlia/vote_pool.rs`)
- Chain Specification → BSC Hardforks: defines activations (evidence: `src/chainspec/mod.rs`)
- System Contracts → BSC Hardforks: selects fork code (evidence: `src/system_contracts/mod.rs`)
- BSC Node Setup → Node Storage: configures storage (evidence: `src/node/mod.rs`)
- Node Operator → RPC APIs: queries node (evidence: `README.md`)
- Node Operator → MEV RPC: submits bids
- MEV RPC → Payload Mining: accesses bid tools (evidence: `src/rpc/mev.rs`)
- MEV gRPC → Payload Mining: uses bid blocks (evidence: `src/grpc/mev.rs`)
- BSC Networking → EVN Handshake: signals EVN (evidence: `src/node/network/bsc_protocol/registry.rs`)
- Node Operator → Metrics: monitors node (evidence: `README.md`)
