# ethereum/go-ethereum architecture

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

- Interactive diagram: https://gitdiagram.com/ethereum/go-ethereum
- Repository: https://github.com/ethereum/go-ethereum

## Overview

Go Ethereum is an Ethereum execution-layer client and protocol implementation. The principal workflow is to start geth, connect and synchronize with peers, validate and execute chain data, persist chain/state, and expose node services through RPC for users and other processes. Its runtime also includes transaction-pool admission, account/key management, consensus and Engine API integration, and contract-binding tools. The README documents the node, sync, console/RPC and developer utilities; sampled source confirms selected RPC, account-manager, and Engine API behaviors, but not all subsystem call wiring.

Main entry points: [`eth/backend.go`](https://github.com/ethereum/go-ethereum/blob/master/eth/backend.go) (Ethereum backend), [`cmd/geth/main.go`](https://github.com/ethereum/go-ethereum/blob/master/cmd/geth/main.go) (geth CLI), [`core/blockchain.go`](https://github.com/ethereum/go-ethereum/blob/master/core/blockchain.go) (Blockchain), [`rpc/server.go`](https://github.com/ethereum/go-ethereum/blob/master/rpc/server.go) (JSON-RPC server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_node["Node runtime"]
  node_geth["geth CLI<br/>[main.go]"]
  node_backend["Ethereum backend<br/>[backend.go]"]
  node_p2p["P2P server<br/>[server.go]"]
  node_ethprotocol["ETH protocol<br/>[handler.go]"]
  node_downloader["Chain downloader<br/>[downloader.go]"]
  node_txpool["Transaction pool<br/>[txpool.go]"]
  node_engineapi["Beacon Engine API<br/>[api.go]"]
end

subgraph group_chain["Execution and storage"]
  node_blockchain["Blockchain<br/>[blockchain.go]"]
  node_state["Execution state<br/>[statedb.go]"]
  node_evm["EVM<br/>[evm.go]"]
  node_consensus["Consensus engines<br/>[consensus.go]"]
  node_rawdb[("Chain database<br/>[database.go]")]
end

subgraph group_interfaces["User interfaces"]
  node_rpc["JSON-RPC server<br/>[server.go]"]
  node_console["JavaScript console<br/>[console.go]"]
  node_accounts["Account manager<br/>[manager.go]"]
  node_keystore["Keystore<br/>[keystore.go]"]
  node_client["Ethereum client library<br/>[ethclient.go]"]
end

subgraph group_developer["Developer tools"]
  node_abigen["Binding generator<br/>[main.go]"]
  node_abi["ABI processing<br/>[abi.go]"]
  node_evmtool["EVM utility<br/>[main.go]"]
end

node_operator(("Node operator"))
node_rpcuser(("RPC user"))
node_peer(("Ethereum peers"))
node_enginepeer(("Consensus client"))

node_operator -->|"starts node"| node_geth
node_geth -->|"configures"| node_backend
node_backend -->|"starts networking"| node_p2p
node_p2p -->|"connects to"| node_peer
node_ethprotocol -->|"exchanges chain data"| node_peer
node_backend -->|"registers protocol"| node_ethprotocol
node_backend -->|"coordinates sync"| node_downloader
node_downloader -->|"requests data"| node_ethprotocol
node_downloader -->|"delivers chain data"| node_blockchain
node_blockchain -->|"validates blocks"| node_consensus
node_blockchain -->|"executes transactions"| node_state
node_state -->|"runs contract code"| node_evm
node_blockchain -->|"persists chain state"| node_rawdb
node_backend -->|"manages transactions"| node_txpool
node_geth -->|"exposes APIs"| node_rpc
node_rpcuser -->|"sends requests"| node_rpc
node_console -->|"issues requests"| node_rpc
node_client -->|"calls APIs"| node_rpc
node_geth -->|"starts console"| node_console
node_geth -->|"manages accounts"| node_accounts
node_accounts -->|"uses key storage"| node_keystore
node_backend -->|"serves Engine API"| node_engineapi
node_enginepeer -->|"sends engine calls"| node_engineapi
node_abigen -->|"parses contract ABI"| node_abi
node_operator -->|"runs isolated execution"| node_evmtool

click node_geth "https://github.com/ethereum/go-ethereum/blob/master/cmd/geth/main.go"
click node_backend "https://github.com/ethereum/go-ethereum/blob/master/eth/backend.go"
click node_p2p "https://github.com/ethereum/go-ethereum/blob/master/p2p/server.go"
click node_ethprotocol "https://github.com/ethereum/go-ethereum/blob/master/eth/protocols/eth/handler.go"
click node_downloader "https://github.com/ethereum/go-ethereum/blob/master/eth/downloader/downloader.go"
click node_txpool "https://github.com/ethereum/go-ethereum/blob/master/core/txpool/txpool.go"
click node_blockchain "https://github.com/ethereum/go-ethereum/blob/master/core/blockchain.go"
click node_state "https://github.com/ethereum/go-ethereum/blob/master/core/state/statedb.go"
click node_evm "https://github.com/ethereum/go-ethereum/blob/master/core/vm/evm.go"
click node_consensus "https://github.com/ethereum/go-ethereum/blob/master/consensus/consensus.go"
click node_rawdb "https://github.com/ethereum/go-ethereum/blob/master/core/rawdb/database.go"
click node_engineapi "https://github.com/ethereum/go-ethereum/blob/master/eth/catalyst/api.go"
click node_rpc "https://github.com/ethereum/go-ethereum/blob/master/rpc/server.go"
click node_console "https://github.com/ethereum/go-ethereum/blob/master/console/console.go"
click node_accounts "https://github.com/ethereum/go-ethereum/blob/master/accounts/manager.go"
click node_keystore "https://github.com/ethereum/go-ethereum/blob/master/accounts/keystore/keystore.go"
click node_client "https://github.com/ethereum/go-ethereum/blob/master/ethclient/ethclient.go"
click node_abigen "https://github.com/ethereum/go-ethereum/blob/master/cmd/abigen/main.go"
click node_abi "https://github.com/ethereum/go-ethereum/blob/master/accounts/abi/abi.go"
click node_evmtool "https://github.com/ethereum/go-ethereum/blob/master/cmd/evm/main.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_geth,node_backend,node_p2p,node_ethprotocol,node_downloader,node_txpool,node_engineapi,node_rpcuser,node_enginepeer toneBlue
class node_blockchain,node_state,node_evm,node_consensus,node_rawdb toneAmber
class node_rpc,node_console,node_accounts,node_keystore,node_client toneMint
class node_abigen,node_abi,node_evmtool toneRose
class node_operator,node_peer toneIndigo
```

## Components

### Node runtime

- [geth CLI](https://github.com/ethereum/go-ethereum/blob/master/cmd/geth/main.go): `cmd/geth/main.go`
- [Ethereum backend](https://github.com/ethereum/go-ethereum/blob/master/eth/backend.go): `eth/backend.go`
- [P2P server](https://github.com/ethereum/go-ethereum/blob/master/p2p/server.go): `p2p/server.go`
- [ETH protocol](https://github.com/ethereum/go-ethereum/blob/master/eth/protocols/eth/handler.go): `eth/protocols/eth/handler.go`
- [Chain downloader](https://github.com/ethereum/go-ethereum/blob/master/eth/downloader/downloader.go): `eth/downloader/downloader.go`
- [Transaction pool](https://github.com/ethereum/go-ethereum/blob/master/core/txpool/txpool.go): `core/txpool/txpool.go`
- [Beacon Engine API](https://github.com/ethereum/go-ethereum/blob/master/eth/catalyst/api.go): `eth/catalyst/api.go`

### Execution and storage

- [Blockchain](https://github.com/ethereum/go-ethereum/blob/master/core/blockchain.go): `core/blockchain.go`
- [Execution state](https://github.com/ethereum/go-ethereum/blob/master/core/state/statedb.go): `core/state/statedb.go`
- [EVM](https://github.com/ethereum/go-ethereum/blob/master/core/vm/evm.go): `core/vm/evm.go`
- [Consensus engines](https://github.com/ethereum/go-ethereum/blob/master/consensus/consensus.go): `consensus/consensus.go`
- [Chain database](https://github.com/ethereum/go-ethereum/blob/master/core/rawdb/database.go): `core/rawdb/database.go`

### User interfaces

- [JSON-RPC server](https://github.com/ethereum/go-ethereum/blob/master/rpc/server.go): `rpc/server.go`
- [JavaScript console](https://github.com/ethereum/go-ethereum/blob/master/console/console.go): `console/console.go`
- [Account manager](https://github.com/ethereum/go-ethereum/blob/master/accounts/manager.go): `accounts/manager.go`
- [Keystore](https://github.com/ethereum/go-ethereum/blob/master/accounts/keystore/keystore.go): `accounts/keystore/keystore.go`
- [Ethereum client library](https://github.com/ethereum/go-ethereum/blob/master/ethclient/ethclient.go): `ethclient/ethclient.go`

### Developer tools

- [Binding generator](https://github.com/ethereum/go-ethereum/blob/master/cmd/abigen/main.go): `cmd/abigen/main.go`
- [ABI processing](https://github.com/ethereum/go-ethereum/blob/master/accounts/abi/abi.go): `accounts/abi/abi.go`
- [EVM utility](https://github.com/ethereum/go-ethereum/blob/master/cmd/evm/main.go): `cmd/evm/main.go`

### Other components

- **Node operator**
- **RPC user**
- **Ethereum peers**
- **Consensus client**

## Connections

- Node operator → geth CLI: starts node
- geth CLI → Ethereum backend: configures
- Ethereum backend → P2P server: starts networking
- P2P server → Ethereum peers: connects to
- ETH protocol → Ethereum peers: exchanges chain data
- Ethereum backend → ETH protocol: registers protocol
- Ethereum backend → Chain downloader: coordinates sync
- Chain downloader → ETH protocol: requests data
- Chain downloader → Blockchain: delivers chain data
- Blockchain → Consensus engines: validates blocks
- Blockchain → Execution state: executes transactions
- Execution state → EVM: runs contract code
- Blockchain → Chain database: persists chain state
- Ethereum backend → Transaction pool: manages transactions
- geth CLI → JSON-RPC server: exposes APIs
- RPC user → JSON-RPC server: sends requests
- JavaScript console → JSON-RPC server: issues requests
- Ethereum client library → JSON-RPC server: calls APIs
- geth CLI → JavaScript console: starts console
- geth CLI → Account manager: manages accounts
- Account manager → Keystore: uses key storage
- Ethereum backend → Beacon Engine API: serves Engine API
- Consensus client → Beacon Engine API: sends engine calls
- Binding generator → ABI processing: parses contract ABI
- Node operator → EVM utility: runs isolated execution
