# etclabscore/core-geth architecture

> Architecture diagram of the GitHub repository etclabscore/core-geth, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/etclabscore/core-geth
- Repository: https://github.com/etclabscore/core-geth

## Overview

##### Project type and purpose
- CoreGeth is a Go-based Ethereum protocol provider and full node implementation. It exposes CLI binaries (`geth`, `abigen`, `bootnode`, etc.) and library packages to run, extend, and interface with Ethereum and Ethereum-Classic networks.
- Its purpose is to launch a node that participates in the P2P network, maintains blockchain state, executes transactions via an EVM, offers JSON-RPC and GraphQL APIs, and manages consensus (PoW/PoA).

##### File structure
- Top-level packages:
- cmd/<tool> – each binary’s CLI entry point
- node – bootstraps and configures the node lifecycle, RPC stack, event feeds
- p2p – discovery and RLPx transport
- eth – Ethereum protocol handlers, block/tx download
- consensus – consensus algorithms (ethash, clique, beacon)
- core – chain management, block validation, state transition
- core/vm – EVM interpreter
- ethdb, trie, triedb – on-disk data storage abstractions (LevelDB, Pebble, filesystem)
- rpc, graphql – JSON-RPC and GraphQL server implementations
- accounts, signer – key management, wallet abstractions
- crypto – cryptographic primitives and cgo integrations
- Configuration files (config.go), build scripts (Makefile, Dockerfile), docs and tests are ancillary.

##### README for insights
- Emphasizes seamless compatibility with upstream go-ethereum, RPC/CLI APIs, pluggable chain configurations.
- Targets multiple networks (ETC, ETH, PoA, testnets), delivered via the same CLI binary.

##### Be detailed and complete, but avoid over-engineering
- Break the system into the components above.
- Every major package group is represented.
- Both runtime interactions (P2P, RPC) and internal integrations (state transition, consensus injection).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI_GETH["geth"]:::cli
        CLI_ABIGEN["abigen"]:::cli
    end

    %% Node Core
    NODE["Node Core & Lifecycle"]:::core

    %% Networking Layer
    subgraph "Networking" 
        P2P_DISC["P2P Discovery"]:::network
        P2P_RLPX["P2P Transport (RLPx)"]:::network
        ETH_PROTO["ETH Protocol Handler"]:::network
        SNAP_PROTO["SNAP Protocol Handler"]:::network
    end

    %% Consensus Engines
    subgraph "Consensus Engines"
        ETHASH["Ethash (PoW)"]:::consensus
        CLIQUE["Clique (PoA)"]:::consensus
        BEACON["Beacon (PoS)"]:::consensus
    end

    %% Core Logic
    subgraph "Core Logic"
        TXPOOL["Transaction Pool"]:::core
        CHAIN["Chain Manager"]:::core
        STATE["State DB & Snapshot"]:::core
        VM["EVM Execution"]:::core
    end

    %% API Layers
    subgraph "API & Tools"
        RPC["JSON-RPC Server"]:::api
        GQL["GraphQL Server"]:::api
        CONSOLE["Interactive Console"]:::api
    end

    ACCOUNTS["Accounts & Signing"]:::core
    METRICS["Metrics Service"]:::core

    %% Storage Backends
    subgraph "Storage Backends"
        LEVELDB["LevelDB"]:::storage
        PEBBLE["Pebble"]:::storage
    end

    %% Relationships
    CLI_GETH -->|"starts"| NODE
    CLI_ABIGEN -->|"uses Accounts/ABI"| ACCOUNTS

    NODE -->|"bootstraps P2P"| P2P_DISC
    NODE -->|"bootstraps P2P"| P2P_RLPX
    NODE -->|"registers"| ETH_PROTO
    NODE -->|"registers"| SNAP_PROTO

    P2P_DISC <-->|"peer discovery"| P2P_RLPX
    P2P_RLPX -->|"streams messages"| ETH_PROTO
    P2P_RLPX -->|"streams messages"| SNAP_PROTO
    ETH_PROTO -->|"blocks, txs"| CHAIN
    SNAP_PROTO -->|"snapshots"| CHAIN

    CHAIN -->|"state transition"| VM
    VM -->|"writes trie"| STATE
    CHAIN -->|"update state"| STATE
    CHAIN -->|"new block"| METRICS
    STATE -->|"persist"| LEVELDB
    STATE -->|"persist"| PEBBLE

    CHAIN -->|"provides data"| TXPOOL
    RPC -->|"queries"| NODE
    GQL -->|"queries"| NODE
    CONSOLE -->|"interactive"| NODE

    RPC -->|"submit tx"| TXPOOL
    TXPOOL -->|"broadcast tx"| P2P_RLPX

    ACCOUNTS -->|"sign tx"| TXPOOL
    ACCOUNTS -->|"key mgmt"| CONSOLE

    %% Click Events
    click CLI_GETH "https://github.com/etclabscore/core-geth/blob/master/cmd/geth/main.go"
    click CLI_ABIGEN "https://github.com/etclabscore/core-geth/blob/master/cmd/abigen/main.go"
    click NODE "https://github.com/etclabscore/core-geth/blob/master/node/node.go"
    click NODE "https://github.com/etclabscore/core-geth/blob/master/node/lifecycle.go"
    click P2P_DISC "https://github.com/etclabscore/core-geth/tree/master/p2p/discover/"
    click P2P_RLPX "https://github.com/etclabscore/core-geth/blob/master/p2p/rlpx/rlpx.go"
    click ETH_PROTO "https://github.com/etclabscore/core-geth/tree/master/eth/protocols/eth/"
    click SNAP_PROTO "https://github.com/etclabscore/core-geth/tree/master/eth/protocols/snap/"
    click ETHASH "https://github.com/etclabscore/core-geth/tree/master/consensus/ethash/"
    click CLIQUE "https://github.com/etclabscore/core-geth/tree/master/consensus/clique/"
    click BEACON "https://github.com/etclabscore/core-geth/tree/master/consensus/beacon/"
    click TXPOOL "https://github.com/etclabscore/core-geth/tree/master/core/txpool/"
    click CHAIN "https://github.com/etclabscore/core-geth/blob/master/core/blockchain.go"
    click STATE "https://github.com/etclabscore/core-geth/tree/master/core/state/"
    click STATE "https://github.com/etclabscore/core-geth/tree/master/trie/"
    click VM "https://github.com/etclabscore/core-geth/tree/master/core/vm/"
    click RPC "https://github.com/etclabscore/core-geth/tree/master/rpc/"
    click GQL "https://github.com/etclabscore/core-geth/tree/master/graphql/"
    click ACCOUNTS "https://github.com/etclabscore/core-geth/tree/master/accounts/"
    click ACCOUNTS "https://github.com/etclabscore/core-geth/tree/master/signer/"
    click LEVELDB "https://github.com/etclabscore/core-geth/tree/master/ethdb/leveldb/"
    click PEBBLE "https://github.com/etclabscore/core-geth/tree/master/ethdb/pebble/"
    click METRICS "https://github.com/etclabscore/core-geth/tree/master/metrics/"
    click CONSOLE "https://github.com/etclabscore/core-geth/tree/master/console/"

    %% Styles
    classDef network fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef storage fill:#FFD700,stroke:#333,stroke-width:1px
    classDef api fill:#FFA500,stroke:#333,stroke-width:1px
    classDef cli fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef consensus fill:#FFB6C1,stroke:#333,stroke-width:1px
```
