# 0xpolygon/polygon-edge architecture

> Architecture diagram of the GitHub repository 0xpolygon/polygon-edge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0xpolygon/polygon-edge
- Repository: https://github.com/0xpolygon/polygon-edge

## Overview

##### Project Type and Purpose
- This is a full-stack, modular Ethereum‐compatible blockchain client (“Polygon Edge”) implemented in Go.
- It provides:
- A CLI (“command” package) for chain setup, genesis, bridge operations, secrets management, etc.
- A P2P network layer for block and transaction gossip (“network” package).
- A consensus engine supporting IBFT and PolyBFT (“consensus” package).
- A JSON-RPC and gRPC API server (“jsonrpc” and “server” packages).
- State execution and storage (EVM, trie, snapshot) (“state,” “blockchain,” “txpool,” “syncer”).
- Secret management and key handling (“secrets,” “bls,” “crypto”).

##### Key Architectural Components
A. CLI Layer (“command”)
- Entry point (main.go) parses user commands → calls specific sub‐commands (genesis, bridge, server, secrets, etc.).
B. API Server Layer
- JSON-RPC endpoints (jsonrpc/*) expose Eth, Net, Web3, Txpool, Bridge RPCs over HTTP.
- gRPC “system” and consensus operator services (server/proto, consensus/ibft/proto, consensus/polybft/proto).
C. P2P Network Layer (“network”)
- Discovery, Dialer, Gossip modules over libp2p.
- Bootnodes, peer management, message/event handling.
D. Consensus Engines (“consensus”)
- Pluggable backends: IBFT, PolyBFT, dummy/dev.
- Block builder, proposer calculator, state sync relayer.
E. Sync & Mempool
- Syncer fetches new blocks from peers via gRPC (syncer/proto) or P2P.
- TxPool manages pending transactions, event subscriptions, and reorg handling.
F. State & Execution (“state”)
- Immutable Merkle‐Patricia trie for state storage.
- EVM interpreter, precompiles, tracer.
- Transaction application and fork handling.
G. Blockchain Storage (“blockchain”)
- LevelDB/memory storage for blocks, receipts, validators.
- Batch writer abstraction.
H. Crypto & Validators
- BLS, ECDSA key management and signatures.
- Validator set, snapshots, contract fetchers.
I. Secrets Management (“secrets”)
- AWS SSM, GCP SSM, Vault, local keystore backends.

##### Relationships and Data Flows
- CLI invokes → API Server or direct backends (e.g., genesis builder).
- API Server ←→ Consensus Engine: to propose and seal blocks, manage state sync.
- Consensus Engine ↔ P2P Network: gossip proposals, votes, state sync commitments.
- Syncer ↔ P2P Network: request and receive block data.
- Consensus Engine & Syncer → Blockchain Storage: commit blocks.
- State Engine reads/writes State Trie → stored by storage backends.
- TxPool receives new transactions from JSON-RPC and network gossip → passes them to state/execution for validation, forwards via network.
- Secrets Manager supplies keys for signing at consensus and transaction signing.

##### Architectural Patterns & Principles
- Modular, plug-in engines (consensus, storage).
- Clear separation of concerns: CLI vs. API vs. engine vs. storage vs. network.
- Interface‐driven Go packages for easy swapping (e.g., StorageBackend interface, ConsensusBackend).
- Asynchronous event handling (network events, txpool subscriptions).
- gRPC and JSON-RPC coexist for operator and user APIs.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: CLI Layer
    subgraph "CLI Layer"
        direction TB
        Main["Entry Point (main.go)"]:::frontend
        CLI["CLI (command package)"]:::frontend
    end

    %% Layer 2: API Server Layer
    subgraph "API Server Layer"
        direction TB
        JSONRPC["JSON-RPC Server (jsonrpc/)"]:::frontend
        GRPC["gRPC Server (server/)"]:::frontend
    end

    %% Layer 3: Consensus & Sync Layer
    subgraph "Consensus & Sync Layer"
        direction TB
        IBFT["IBFT Engine (consensus/ibft/)"]:::core
        PolyBFT["PolyBFT Engine (consensus/polybft/)"]:::core
        DevDummy["Dev/Dummy Engines (consensus/dev/, dummy/)"]:::core
        Syncer["Syncer (syncer/)"]:::core
        TxPool["TxPool (txpool/)"]:::core
    end

    %% Layer 4: P2P Network Layer
    subgraph "P2P Network Layer"
        direction TB
        Network["P2P Network (network/)"]:::network
    end

    %% Layer 5: State & Execution Layer
    subgraph "State & Execution Layer"
        direction TB
        Trie["Trie & Snapshot (state/immutable-trie/)"]:::core
        EVM["EVM Interpreter (state/runtime/evm/)"]:::core
    end

    %% Layer 6: Storage & Persistence Layer
    subgraph "Storage & Persistence Layer"
        direction TB
        Storage["Blockchain Storage (blockchain/storage/)"]:::storage
        Validators["Validator Management (validators/)"]:::storage
        Crypto["Crypto & BLS (crypto/, bls/)"]:::crypto
        Secrets["Secrets Management (secrets/)"]:::crypto
    end

    %% Relationships
    Main -->|invokes| CLI
    CLI -->|starts| JSONRPC
    CLI -->|starts| GRPC
    CLI -->|direct backend| IBFT
    JSONRPC -->|calls| TxPool
    JSONRPC -->|calls| IBFT
    JSONRPC -->|calls| PolyBFT
    JSONRPC -->|calls| DevDummy
    GRPC -->|operator services| IBFT
    GRPC -->|operator services| PolyBFT

    IBFT <-->|gossip proposals/votes| Network
    PolyBFT <-->|gossip proposals| Network
    DevDummy <-->|gossip| Network

    Syncer <-->|requests blocks| Network
    Syncer -->|commits blocks| Storage

    TxPool <-->|gossip txs| Network
    TxPool -->|validate txs| EVM
    TxPool -->|store txs| Trie

    IBFT -->|commit block| Storage
    PolyBFT -->|commit block| Storage

    EVM -->|state reads/writes| Trie
    Trie -->|persist| Storage

    Crypto -->|signing keys| IBFT
    Crypto -->|signing keys| PolyBFT
    Secrets -->|supply keys| Crypto
    Secrets -->|supply keys| IBFT
    Secrets -->|supply keys| TxPool

    %% Click Events
    click Main "https://github.com/0xpolygon/polygon-edge/blob/develop/main.go"
    click CLI "https://github.com/0xpolygon/polygon-edge/tree/develop/command/"
    click JSONRPC "https://github.com/0xpolygon/polygon-edge/tree/develop/jsonrpc/"
    click GRPC "https://github.com/0xpolygon/polygon-edge/tree/develop/server/"
    click IBFT "https://github.com/0xpolygon/polygon-edge/tree/develop/consensus/ibft/"
    click PolyBFT "https://github.com/0xpolygon/polygon-edge/tree/develop/consensus/polybft/"
    click DevDummy "https://github.com/0xpolygon/polygon-edge/tree/develop/consensus/dev/"
    click Syncer "https://github.com/0xpolygon/polygon-edge/tree/develop/syncer/"
    click TxPool "https://github.com/0xpolygon/polygon-edge/tree/develop/txpool/"
    click Trie "https://github.com/0xpolygon/polygon-edge/tree/develop/state/immutable-trie/"
    click EVM "https://github.com/0xpolygon/polygon-edge/tree/develop/state/runtime/evm/"
    click Storage "https://github.com/0xpolygon/polygon-edge/tree/develop/blockchain/storage/"
    click Crypto "https://github.com/0xpolygon/polygon-edge/tree/develop/crypto/"
    click Secrets "https://github.com/0xpolygon/polygon-edge/tree/develop/secrets/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef core fill:#d4edda,stroke:#333,stroke-width:1px
    classDef network fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef storage fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef crypto fill:#f3e5ff,stroke:#333,stroke-width:1px
```
