# status-im/nimbus-eth1 architecture

> Architecture diagram of the GitHub repository status-im/nimbus-eth1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/status-im/nimbus-eth1
- Repository: https://github.com/status-im/nimbus-eth1

## Overview

##### Main Components Identification

The system should be divided into these major components:
- Core Execution Client
- Network Layer
- Database Layer
- EVM (Ethereum Virtual Machine)
- RPC Interface
- Beacon Chain Integration
- Fluffy Portal Network Client

**External Layer:**
- RPC API endpoints
- GraphQL interface
- Engine API (for consensus layer)
- Network P2P connections

**Core Layer:**
- Transaction Pool
- Block Processing
- State Management
- Chain Management
- Beacon Chain Sync

**Infrastructure Layer:**
- Database (RocksDB/SQLite/LMDB)
- EVM Implementation
- Core Utilities

##### Component Details

a) Core Components:
- Transaction Pool (/nimbus/core/tx_pool/)
- Block Processing (/nimbus/core/block_import.nim)
- Chain Management (/nimbus/core/chain/)
- State Management (/nimbus/core/executor/)
- EVM Implementation (/nimbus/evm/)

b) Network Components:
- P2P Communication (/nimbus/sync/)
- Protocol Handlers (/nimbus/sync/protocol/)
- Peer Management (/nimbus/sync/peers.nim)

c) API Layer:
- RPC Server (/nimbus/rpc/)
- GraphQL Interface (/nimbus/graphql/)
- Engine API (/nimbus/beacon/api_handler/)

##### Connection Types

- Event propagation (wavy lines)

##### Key Interactions

Important flows:

##### Specific Implementation Details

Technical details like:
- RocksDB as the default database backend
- Support for multiple DB backends
- Integration with consensus layer
- Metrics export capability
- Portal Network integration

##### Additional Elements

- Configuration management
- Metrics/Monitoring
- Testing infrastructure
- Build system

##### Notes Section

A notes section describing:
- Key architectural decisions
- Important dependencies
- Configuration options
- Scaling considerations

Remember to indicate the relationship with the consensus layer client and the Portal Network integration through Fluffy, as these are unique aspects of the architecture.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph External
        RPC["RPC API"]:::api
        GAPI["GraphQL API"]:::api
        EAPI["Engine API"]:::api
        P2P["P2P Network"]:::network
    end

    subgraph Core
        TX["Transaction Pool"]:::core
        BP["Block Processing"]:::core
        CM["Chain Management"]:::core
        SM["State Management"]:::core
        EVM["EVM Implementation"]:::core
    end

    subgraph Network
        SYNC["P2P Communication"]:::network
        PH["Protocol Handlers"]:::network
        PM["Peer Management"]:::network
    end

    subgraph Database
        DB["Core Database"]:::db
        ROCKS["RocksDB Backend"]:::db
        LED["Ledger"]:::db
        STATE["State Implementation"]:::db
    end

    subgraph "Beacon Integration"
        BS["Beacon Chain Sync"]:::beacon
        BE["Beacon Engine"]:::beacon
    end

    subgraph "Portal Network"
        FLF["Fluffy Core"]:::portal
        FLN["Network Protocol"]:::portal
        FLD["Portal Database"]:::portal
    end

    subgraph "Transaction Processing"
        TH["Transaction Handler"]:::tx
        HS["Host Services"]:::tx
        EC["EVM Call Interface"]:::tx
    end

    %% Connections
    RPC --> TX
    GAPI --> SM
    EAPI --> BE
    P2P --> SYNC

    TX --> BP
    BP --> CM
    CM --> SM
    SM --> EVM

    SYNC --> PH
    PH --> PM

    SM --> DB
    DB --> ROCKS
    DB --> LED
    DB --> STATE

    BE --> BS
    BE --> CM

    FLF --> FLN
    FLN --> FLD
    FLF --> P2P

    TH --> HS
    HS --> EC
    EC --> EVM

    %% Click Events
    click TX "https://github.com/status-im/nimbus-eth1/tree/master//nimbus/core/tx_pool/"
    click BP "https://github.com/status-im/nimbus-eth1/blob/master//nimbus/core/block_import.nim"
    click CM "https://github.com/status-im/nimbus-eth1/tree/master//nimbus/core/chain/"
    click SM "https://github.com/status-im/nimbus-eth1/tree/master//nimbus/core/executor/"
    click EVM "https://github.com/status-im/nimbus-eth1/tree/master//nimbus/evm/"
    click SYNC "https://github.com/status-im/nimbus-eth1/tree/master//nimbus/sync/"
    click PH "https://github.com/status-im/nimbus-eth1/tree/master//nimbus/sync/protocol/"
    click PM "https://github.com/status-im/nimbus-eth1/blob/master//nimbus/sync/peers.nim"
    click RPC "https://github.com/status-im/nimbus-eth1/tree/master//nimbus/rpc/"
    click GAPI "https://github.com/status-im/nimbus-eth1/tree/master//nimbus/graphql/"
    click EAPI "https://github.com/status-im/nimbus-eth1/tree/master//nimbus/beacon/api_handler/"
    click DB "https://github.com/status-im/nimbus-eth1/tree/master//nimbus/db/"
    click ROCKS "https://github.com/status-im/nimbus-eth1/blob/master//nimbus/db/kvstore_rocksdb.nim"
    click BS "https://github.com/status-im/nimbus-eth1/tree/master//nimbus/sync/beacon/"
    click BE "https://github.com/status-im/nimbus-eth1/blob/master//nimbus/beacon/beacon_engine.nim"
    click FLF "https://github.com/status-im/nimbus-eth1/tree/master//fluffy/"
    click FLN "https://github.com/status-im/nimbus-eth1/tree/master//fluffy/network/"
    click FLD "https://github.com/status-im/nimbus-eth1/tree/master//fluffy/database/"
    click TH "https://github.com/status-im/nimbus-eth1/tree/master//nimbus/transaction/"
    click HS "https://github.com/status-im/nimbus-eth1/blob/master//nimbus/transaction/host_services.nim"
    click EC "https://github.com/status-im/nimbus-eth1/blob/master//nimbus/transaction/call_evm.nim"
    click STATE "https://github.com/status-im/nimbus-eth1/tree/master//nimbus/db/aristo/"
    click LED "https://github.com/status-im/nimbus-eth1/blob/master//nimbus/db/ledger.nim"

    %% Styles
    classDef core fill:#2374ab
    classDef network fill:#45b7d1
    classDef api fill:#ffb703
    classDef db fill:#8338ec
    classDef beacon fill:#fb8500
    classDef portal fill:#06d6a0
    classDef tx fill:#ef476f
```
