# erigontech/erigon architecture

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

- Interactive diagram: https://gitdiagram.com/erigontech/erigon
- Repository: https://github.com/erigontech/erigon

## Overview

Erigon is an Ethereum execution-layer node with an optional external consensus client and an embedded consensus layer, Caplin, enabled by default. The main operator workflow is to start the node, synchronize chain data, process blocks and state, and expose node data through RPC; validators can also produce blocks. The graph includes documented networking, storage, and developer-facing services. Some subsystem links are based only on README claims or source-index references; unsampled code is not assumed to establish more specific call paths.

Main entry points: [`cmd/caplin/main.go`](https://github.com/erigontech/erigon/blob/main/cmd/caplin/main.go) (Embedded Caplin), [`execution/engineapi/engine_server.go`](https://github.com/erigontech/erigon/blob/main/execution/engineapi/engine_server.go) (Engine API server), [`cmd/erigon/main.go`](https://github.com/erigontech/erigon/blob/main/cmd/erigon/main.go) (Erigon node), [`execution/state/transient_storage.go`](https://github.com/erigontech/erigon/blob/main/execution/state/transient_storage.go) (Chain state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_node["Node and APIs"]
  node_erigon["Erigon node<br/>[main.go]"]
  node_rpcdaemon["RPC daemon<br/>[main.go]"]
  node_engine["Engine API server<br/>[engine_server.go]"]
end

subgraph group_execution["Execution and state"]
  node_vm["EVM execution<br/>[program.go]"]
  node_chainstate[("Chain state")]
  node_pruning["Pruning policy<br/>[storage_mode.go]"]
end

subgraph group_consensus["Consensus and validation"]
  node_caplin["Embedded Caplin<br/>[main.go]"]
  node_beaconapi["Beacon API<br/>[handler.go]"]
  node_validator["Validator services<br/>[service.go]"]
  node_forkchoice["Fork choice<br/>[forkchoice.go]"]
  node_syncstages["Consensus sync<br/>[clstages.go]"]
  node_executionclient["Consensus execution client"]
end

subgraph group_data["Sync and storage"]
  node_downloader["Snapshot downloader<br/>[main.go]"]
  node_snapshots[("Snapshot data<br/>[blocks.go]")]
end

subgraph group_network["Networking"]
  node_p2p["P2P networking<br/>[server.go]"]
  node_gossip["Consensus gossip<br/>[gossip_manager.go]"]
end

node_operator(("Node operator"))
node_externalcl(("External CL client"))

node_operator -->|"starts node"| node_erigon
node_erigon -.->|"offers RPC"| node_rpcdaemon
node_operator -->|"queries node"| node_rpcdaemon
node_externalcl -->|"uses Engine API"| node_engine
node_caplin -->|"uses execution client"| node_executionclient
node_executionclient -->|"calls Engine API"| node_engine
node_engine -->|"accesses chain data"| node_chainstate
node_engine -.->|"processes payloads"| node_vm
node_operator -->|"downloads snapshots"| node_downloader
node_downloader -.->|"obtains snapshot data"| node_snapshots
node_caplin -.->|"runs consensus"| node_syncstages
node_syncstages -.->|"updates head"| node_forkchoice
node_caplin -->|"exposes Beacon API"| node_beaconapi
node_validator -.->|"uses Beacon API"| node_beaconapi
node_caplin -->|"uses gossip"| node_gossip
node_erigon -.->|"uses networking"| node_p2p
node_chainstate -.->|"applies retention policy"| node_pruning

click node_erigon "https://github.com/erigontech/erigon/blob/main/cmd/erigon/main.go"
click node_rpcdaemon "https://github.com/erigontech/erigon/blob/main/cmd/rpcdaemon/main.go"
click node_engine "https://github.com/erigontech/erigon/blob/main/execution/engineapi/engine_server.go"
click node_vm "https://github.com/erigontech/erigon/blob/main/execution/vm/program/program.go"
click node_chainstate "https://github.com/erigontech/erigon/blob/main/execution/state/transient_storage.go"
click node_pruning "https://github.com/erigontech/erigon/blob/main/db/kv/prune/storage_mode.go"
click node_caplin "https://github.com/erigontech/erigon/blob/main/cmd/caplin/main.go"
click node_beaconapi "https://github.com/erigontech/erigon/blob/main/cl/beacon/handler/handler.go"
click node_validator "https://github.com/erigontech/erigon/blob/main/cl/validator/devvalidator/service.go"
click node_forkchoice "https://github.com/erigontech/erigon/blob/main/cl/phase1/forkchoice/forkchoice.go"
click node_syncstages "https://github.com/erigontech/erigon/blob/main/cl/phase1/stages/clstages.go"
click node_downloader "https://github.com/erigontech/erigon/blob/main/cmd/downloader/main.go"
click node_snapshots "https://github.com/erigontech/erigon/blob/main/cl/persistence/format/snapshot_format/blocks.go"
click node_executionclient "https://github.com/erigontech/erigon/blob/main/cl/phase1/execution_client/execution_client_engine.go"
click node_p2p "https://github.com/erigontech/erigon/blob/main/p2p/server.go"
click node_gossip "https://github.com/erigontech/erigon/blob/main/cl/phase1/network/gossip/gossip_manager.go"

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_erigon,node_rpcdaemon,node_engine,node_externalcl toneBlue
class node_vm,node_chainstate,node_pruning toneAmber
class node_caplin,node_beaconapi,node_validator,node_forkchoice,node_syncstages,node_executionclient toneMint
class node_downloader,node_snapshots toneRose
class node_p2p,node_gossip,node_operator toneIndigo
```

## Components

### Node and APIs

- [Erigon node](https://github.com/erigontech/erigon/blob/main/cmd/erigon/main.go): `cmd/erigon/main.go`
- [RPC daemon](https://github.com/erigontech/erigon/blob/main/cmd/rpcdaemon/main.go): `cmd/rpcdaemon/main.go`
- [Engine API server](https://github.com/erigontech/erigon/blob/main/execution/engineapi/engine_server.go): `execution/engineapi/engine_server.go`

### Execution and state

- [EVM execution](https://github.com/erigontech/erigon/blob/main/execution/vm/program/program.go): `execution/vm/program/program.go`
- [Chain state](https://github.com/erigontech/erigon/blob/main/execution/state/transient_storage.go): `execution/state/transient_storage.go`
- [Pruning policy](https://github.com/erigontech/erigon/blob/main/db/kv/prune/storage_mode.go): `db/kv/prune/storage_mode.go`

### Consensus and validation

- [Embedded Caplin](https://github.com/erigontech/erigon/blob/main/cmd/caplin/main.go): `cmd/caplin/main.go`
- [Beacon API](https://github.com/erigontech/erigon/blob/main/cl/beacon/handler/handler.go): `cl/beacon/handler/handler.go`
- [Validator services](https://github.com/erigontech/erigon/blob/main/cl/validator/devvalidator/service.go): `cl/validator/devvalidator/service.go`
- [Fork choice](https://github.com/erigontech/erigon/blob/main/cl/phase1/forkchoice/forkchoice.go): `cl/phase1/forkchoice/forkchoice.go`
- [Consensus sync](https://github.com/erigontech/erigon/blob/main/cl/phase1/stages/clstages.go): `cl/phase1/stages/clstages.go`
- [Consensus execution client](https://github.com/erigontech/erigon/blob/main/cl/phase1/execution_client/execution_client_engine.go): `cl/phase1/execution_client/execution_client_engine.go`

### Sync and storage

- [Snapshot downloader](https://github.com/erigontech/erigon/blob/main/cmd/downloader/main.go): `cmd/downloader/main.go`
- [Snapshot data](https://github.com/erigontech/erigon/blob/main/cl/persistence/format/snapshot_format/blocks.go): `cl/persistence/format/snapshot_format/blocks.go`

### Networking

- [P2P networking](https://github.com/erigontech/erigon/blob/main/p2p/server.go): `p2p/server.go`
- [Consensus gossip](https://github.com/erigontech/erigon/blob/main/cl/phase1/network/gossip/gossip_manager.go): `cl/phase1/network/gossip/gossip_manager.go`

### Other components

- **Node operator**
- **External CL client**

## Connections

- Node operator → Erigon node: starts node
- Erigon node → RPC daemon: offers RPC
- Node operator → RPC daemon: queries node
- External CL client → Engine API server: uses Engine API
- Embedded Caplin → Consensus execution client: uses execution client (evidence: `cmd/caplin/main.go`)
- Consensus execution client → Engine API server: calls Engine API (evidence: `cl/phase1/execution_client/execution_client_engine.go`)
- Engine API server → Chain state: accesses chain data (evidence: `execution/engineapi/engine_server.go`)
- Engine API server → EVM execution: processes payloads
- Node operator → Snapshot downloader: downloads snapshots
- Snapshot downloader → Snapshot data: obtains snapshot data
- Embedded Caplin → Consensus sync: runs consensus
- Consensus sync → Fork choice: updates head
- Embedded Caplin → Beacon API: exposes Beacon API
- Validator services → Beacon API: uses Beacon API
- Embedded Caplin → Consensus gossip: uses gossip (evidence: `cl/phase1/network/gossip/gossip_manager.go`)
- Erigon node → P2P networking: uses networking
- Chain state → Pruning policy: applies retention policy
