# status-im/nimbus-eth2 architecture

> Architecture diagram of the GitHub repository status-im/nimbus-eth2, 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-eth2
- Repository: https://github.com/status-im/nimbus-eth2

## Overview

##### Main Components

a) Core Components:
- Beacon Node (beacon_chain/beacon_node.nim)
- Validator Client (beacon_chain/validator_client/)
- Light Client (beacon_chain/light_client.nim)
- Database Layer (beacon_chain/beacon_chain_db*.nim)

b) Consensus Components:
- Fork Choice Implementation (beacon_chain/fork_choice/)
- State Transition Logic (beacon_chain/spec/state_transition*.nim)
- Block Processing (beacon_chain/gossip_processing/)
- Attestation Pool (beacon_chain/consensus_object_pools/attestation_pool.nim)

c) Network Layer:
- P2P Networking (beacon_chain/networking/)
- Discovery Protocol (eth2_discovery.nim)
- Gossip Protocol (gossip_processing/)
- REST API (beacon_chain/rpc/)

d) External Interfaces:
- Execution Layer Interface (beacon_chain/el/)
- Key Management System
- Metrics and Monitoring

##### Relationship Flows

a) Data Flow:
**External Network <-> Network Layer <-> Consensus Layer <-> Database**
- <-> State Processing
- <-> Fork Choice

b) Client Interactions:
**Validator Client <-> Beacon Node <-> Execution Layer**
**Light Client <-> Beacon Node**

##### Component Details

- Core Services (rectangles, blue)
- Network Components (hexagons, green)
- Processing Units (rounded rectangles, orange)
- External Interfaces (clouds, gray)

##### Specific Implementation Notes

a) Specialized subsystems:
- Slashing Protection (validators/slashing_protection/)
- Sync Committee Management (consensus_object_pools/sync_committee_msg_pool.nim)
- Block DAG Management (consensus_object_pools/block_dag.nim)

b) Configuration points:
- Network Preset Configurations
- Chain Specification Parameters
- Validator Management Options

##### Architectural Patterns

Following patterns:
- Event-driven architecture for consensus
- Pipeline processing for blocks and attestations
- Modular design with clear component separation
- Concurrent processing capabilities

##### System Boundaries

Clearly delineate:
- Internal vs. External Components
- Trust Boundaries
- Network Interfaces
- Storage Boundaries

##### Additional Elements

Annotations for:
- Version compatibility
- Fork support (Phase 0, Altair, Bellatrix, etc.)
- Scaling considerations
- Resource optimization points

##### External system interfaces

Use a hierarchical layout with:
- Top level: External interfaces
- Middle level: Core processing
- Bottom level: Storage and persistence

This design should reflect both the current implementation and extension points for future development, while maintaining clarity about the system's primary purpose as a resource-efficient consensus client.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and Classes
    classDef core fill:#3498db,stroke:#2980b9,color:white
    classDef network fill:#2ecc71,stroke:#27ae60,color:white
    classDef storage fill:#e67e22,stroke:#d35400,color:white
    classDef processing fill:#e74c3c,stroke:#c0392b,color:white
    classDef external fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef consensus fill:#9b59b6,stroke:#8e44ad,color:white

    %% External Interfaces Layer
    subgraph External
        EL["Execution Layer"]
        KMS["Key Management System"]
        REST["REST API Interface"]
    end

    %% Core Components Layer
    subgraph Core
        BN["Beacon Node"]:::core
        VC["Validator Client"]:::core
        LC["Light Client"]:::core
    end

    %% Network Layer
    subgraph Network
        P2P["P2P Network"]:::network
        DISC["Discovery Protocol"]:::network
        GOSSIP["Gossip Protocol"]:::network
    end

    %% Consensus Layer
    subgraph Consensus
        FC["Fork Choice"]:::consensus
        ST["State Transition"]:::consensus
        BP["Block Processing"]:::consensus
        AP["Attestation Pool"]:::consensus
        SYNC["Sync Committee"]:::consensus
        BDAG["Block DAG"]:::consensus
    end

    %% Storage Layer
    subgraph Storage
        DB["Database"]:::storage
        SP["Slashing Protection"]:::storage
    end

    %% Relationships
    EL --> BN
    KMS --> VC
    REST --> BN

    BN --> P2P
    BN --> DISC
    BN --> GOSSIP

    P2P --> FC
    P2P --> ST
    P2P --> BP

    VC --> BN
    LC --> BN

    BP --> AP
    BP --> BDAG
    BP --> SYNC

    FC --> DB
    ST --> DB
    BP --> DB
    AP --> DB
    SP --> DB

    %% Click Events
    click BN "https://github.com/status-im/nimbus-eth2/blob/stable/beacon_chain/beacon_node.nim"
    click VC "https://github.com/status-im/nimbus-eth2/tree/stable/beacon_chain/validator_client/"
    click LC "https://github.com/status-im/nimbus-eth2/blob/stable/beacon_chain/light_client.nim"
    click DB "https://github.com/status-im/nimbus-eth2/blob/stable/beacon_chain/beacon_chain_db.nim"
    click FC "https://github.com/status-im/nimbus-eth2/tree/stable/beacon_chain/fork_choice/"
    click ST "https://github.com/status-im/nimbus-eth2/blob/stable/beacon_chain/spec/state_transition.nim"
    click BP "https://github.com/status-im/nimbus-eth2/blob/stable/beacon_chain/gossip_processing/block_processor.nim"
    click AP "https://github.com/status-im/nimbus-eth2/blob/stable/beacon_chain/consensus_object_pools/attestation_pool.nim"
    click P2P "https://github.com/status-im/nimbus-eth2/blob/stable/beacon_chain/networking/eth2_network.nim"
    click DISC "https://github.com/status-im/nimbus-eth2/blob/stable/beacon_chain/networking/eth2_discovery.nim"
    click GOSSIP "https://github.com/status-im/nimbus-eth2/tree/stable/beacon_chain/gossip_processing/"
    click REST "https://github.com/status-im/nimbus-eth2/blob/stable/beacon_chain/rpc/rest_api.nim"
    click EL "https://github.com/status-im/nimbus-eth2/tree/stable/beacon_chain/el/"
    click KMS "https://github.com/status-im/nimbus-eth2/blob/stable/beacon_chain/validators/keystore_management.nim"
    click SP "https://github.com/status-im/nimbus-eth2/blob/stable/beacon_chain/validators/slashing_protection.nim"
    click SYNC "https://github.com/status-im/nimbus-eth2/blob/stable/beacon_chain/consensus_object_pools/sync_committee_msg_pool.nim"
    click BDAG "https://github.com/status-im/nimbus-eth2/blob/stable/beacon_chain/consensus_object_pools/block_dag.nim"

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Network Components"]:::network
        L3["Storage Components"]:::storage
        L4["Consensus Components"]:::consensus
        L5["External Interfaces"]:::external
    end
```
