# koma2211/go-ethereum architecture

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

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

## Overview

##### Project type and purpose
- From the README and file tree, this is “go-ethereum” (geth), a Go-based execution-layer client for the Ethereum protocol. It can run as a full/archival/light node, offers JSON-RPC, WS and IPC APIs, P2P networking, consensus engines, transaction pool, EVM execution, state DB, and command-line utilities (geth, abigen, evm, clef, etc.).

##### File structure
- Top-level directories:
- cmd – entrypoint executables (geth, clef, devp2p, abigen, evm, rlpdump, workload, etc.)
- node – core node bootstrap, lifecycle, RPC stack
- p2p – low-level peer discovery, RLPx transport, server
- eth – Ethereum protocol handlers: sync, downloader, filters, tracer interfaces
- consensus – plug-in consensus rules (ethash, clique, beacon)
- core – blockchain insertion & validation logic, gas, fork rules, chain state
- state, trie, triedb, ethdb – database layers (key/value stores, trie, history, snapshots)
- core/vm – the Ethereum Virtual Machine
- txpool – transaction pool & mempool logic
- rpc, ethclient, graphql – JSON-RPC server and client implementations
- accounts, signer, keystore – account management & signing backends
- crypto – cryptographic primitives (secp256k1, bn256, KZG, etc.)
- metrics, log – instrumentation, logging
- internal – build tooling, debug, testing helpers

##### README for additional insights
- The geth binary hosts the P2P node, downloads blocks, validates & executes them, maintains state, and exposes APIs. Other binaries wrap portions of this (abigen for contract codegen, evm for EVM sandbox, clef for signing).

##### Main components and interactions
a. Node Core (node/node.go) – initializes all submodules and ties them together
b. P2P Network (p2p/) – connects to peers, discovery, secure RLPx transport
c. Sync & Downloader (eth/downloader, eth/sync.go) – fetches blocks from peers, verifies headers & bodies
d. Consensus & Fork Rules (consensus/, core/forkid/) – determines valid forks, block acceptance
e. Chain Manager (core/, trie/, triedb/) – stores blocks, executes transactions via VM, updates Merkle trie state
f. Transaction Pool (core/txpool/) – holds pending transactions for inclusion by miner
g. Miner (miner/) – assembles blocks, signs (for proof-of-work) or payload (for proof-of-stake), injects to chain
h. RPC/API Layer (node/rpcstack.go, rpc/, eth/api_*.go, graphql/) – exposes JSON-RPC over HTTP, WS, IPC for external clients
i. Account & Signing (accounts/, signer/) – manages private keys & signs transactions
j. Utilities & CLI (cmd/) – CLI wrappers around the core node or isolated tools

- Startup: CLI → Node Core
- Node Core ↔ P2P Network
- P2P Network → Downloader → Chain Manager → State DB
- Chain Manager → VM → Execution results back into State DB
- Chain Manager emits events → Filters & Tracers → API Layer
- Transaction Pool ← API Layer ← Client → Transaction Pool → Miner
- Miner → Chain Manager to commit new block → Broadcast via P2P
- Account/Signer used by RPC & CLI for signing transactions

##### Architectural patterns and principles
- Layered architecture: network → sync → consensus → execution → storage → API
- Dependency injection via the Node package, enabling swapping consensus engines or DB backends
- Clear separation of concerns: `core` (blockchain logic), `eth` (protocol), `p2p` (network), `rpc` (interface)
- Use of interfaces for state DB, transaction sources, backends (in ethclient, accounts)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI and Core
    CLITools["CLI Tools\n(cmd/)"]:::api
    NodeCore["Node Core\n(node/node.go)"]:::api
    click CLITools "https://github.com/koma2211/go-ethereum/tree/master/cmd/"
    click NodeCore "https://github.com/koma2211/go-ethereum/blob/master/node/node.go"

    CLITools -->|"start"| NodeCore

    %% Network Layer
    subgraph "Network Layer"
        P2P["P2P Network\n(p2p/)"]:::network
        click P2P "https://github.com/koma2211/go-ethereum/tree/master/p2p/"
    end

    NodeCore <-->|"peers"| P2P

    %% Sync & Consensus Layer
    subgraph "Sync & Consensus Layer"
        Sync["Sync & Downloader\n(eth/downloader/)"]:::sync
        Consensus["Consensus Engines & Fork Rules\n(consensus/, core/forkid/)"]:::sync
        click Sync "https://github.com/koma2211/go-ethereum/tree/master/eth/downloader/"
        click Consensus "https://github.com/koma2211/go-ethereum/tree/master/consensus/"
    end

    P2P -->|"blocks"| Sync
    Sync -->|"validated blocks"| Consensus

    %% Execution Layer
    subgraph "Execution Layer"
        ChainManager["Chain Manager\n(core/)"]:::exec
        VM["EVM Interpreter\n(core/vm/)"]:::exec
        click ChainManager "https://github.com/koma2211/go-ethereum/tree/master/core/"
        click VM "https://github.com/koma2211/go-ethereum/tree/master/core/vm/"
    end

    Consensus -->|"fork rules"| ChainManager
    ChainManager -->|"execute"| VM
    VM -->|"results"| ChainManager

    %% Storage Layer
    subgraph "Storage Layer"
        Trie["Merkle Trie & TryeDB\n(trie/, triedb/)"]:::storage
        DB["Key/Value DB\n(ethdb/)"]:::storage
        click Trie "https://github.com/koma2211/go-ethereum/tree/master/trie/"
        click DB "https://github.com/koma2211/go-ethereum/tree/master/ethdb/"
    end

    ChainManager -->|"state update"| Trie
    ChainManager -->|"raw data"| DB

    %% Transaction & Mining
    subgraph "Transaction & Mining"
        TxPool["Transaction Pool\n(core/txpool/)"]:::exec
        Miner["Miner\n(miner/)"]:::exec
        click TxPool "https://github.com/koma2211/go-ethereum/tree/master/core/txpool/"
        click Miner "https://github.com/koma2211/go-ethereum/tree/master/miner/"
    end

    %% API Layer
    subgraph "API & Clients"
        RPCStack["RPC Stack\n(node/rpcstack.go)"]:::api
        RPC["RPC Server\n(rpc/)"]:::api
        EthAPI["Eth API\n(eth/api_*.go)"]:::api
        GraphQL["GraphQL API\n(graphql/)"]:::api
        Ethclient["Eth Client\n(ethclient/)"]:::api
        click RPCStack "https://github.com/koma2211/go-ethereum/blob/master/node/rpcstack.go"
        click RPC "https://github.com/koma2211/go-ethereum/tree/master/rpc/"
        click EthAPI "https://github.com/koma2211/go-ethereum/blob/master/eth/api_*.go"
        click GraphQL "https://github.com/koma2211/go-ethereum/tree/master/graphql/"
        click Ethclient "https://github.com/koma2211/go-ethereum/tree/master/ethclient/"
    end

    NodeCore -->|"initialize RPC"| RPCStack
    RPCStack --> RPC
    RPC --> EthAPI
    RPCStack --> GraphQL
    RPCStack --> Ethclient

    %% Accounts & Signing
    subgraph "Account & Signing"
        Accounts["Accounts\n(accounts/)"]:::api
        Signer["Signer\n(signer/)"]:::api
        click Accounts "https://github.com/koma2211/go-ethereum/tree/master/accounts/"
        click Signer "https://github.com/koma2211/go-ethereum/tree/master/signer/"
    end

    Accounts --> Signer
    RPCStack -->|"uses"| Accounts
    RPCStack -->|"uses"| Signer
    CLITools -->|"uses"| Accounts

    %% Data flows to TxPool and Miner
    RPCStack -->|"submit tx"| TxPool
    TxPool -->|"pending tx"| Miner
    Miner -->|"new block"| ChainManager
    ChainManager -->|"broadcast"| P2P

    %% Styles
    classDef network fill:#cce5ff,stroke:#3399ff
    classDef sync fill:#d4edda,stroke:#28a745
    classDef exec fill:#fff3cd,stroke:#ffcd39
    classDef storage fill:#e2d5f7,stroke:#9b59b6
    classDef api fill:#e6e6e6,stroke:#999999
```
