# sigp/lighthouse architecture

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

- Interactive diagram: https://gitdiagram.com/sigp/lighthouse
- Repository: https://github.com/sigp/lighthouse

## Overview

##### Main Components and Their Roles

- Beacon Node and Beacon Chain:
– Represent the heart of the system. This module (located in directories such as “beacon_node/beacon_chain” and “beacon_node/src”) handles block production, block verification, fork choice, attestation processing, and even manages caches (e.g., proposer caches, attester caches).
– Include subcomponents such as the attestation simulator, block streamer, snapshot manager, state processing modules, and schema change handlers.

- Validator and Validator Manager:
– Modules like “account_manager”, “validator_client”, and “validator_manager” cover key management, validator registration, slashing protection, and interactions between validators and the node.
– Emphasize how validators are created, imported, managed, and how they exchange messages with the node.

- Network Layer:
– Found in “beacon_node/network”, “lighthouse_network”, and related crates. This layer covers peer discovery, gossip protocols (including the gossipsub implementation), NAT traversal, and RPC communication.

- Consensus and Cryptography:
– The “consensus” directory includes modular implementations for fork choice, merkle proofs, state processing, shuffling, and fixed bytes processing.
– The “crypto” crate (with submodules such as “bls”) provides the cryptographic primitives necessary for signatures, aggregate verification, and key management.

- Data Storage and Database Management:
– Multiple directories (like “database_manager”, “beacon_node/store”, and various “common” sub-crates) indicate the handling of node state persistence, leveldb (or other key/value store) interactions, block storage and metadata caching.
– Consider presenting these as interfaces between the consensus logic and disk storage.

- CLI / HTTP API / External Interfaces:
– NOTICE directories such as “http_api”, “lcli”, “watch”, and others.
– These components provide various external interfaces for node management, metrics reporting, block broadcasting, and monitoring.
– Indicate how user interactions, monitoring, and remote procedure calls interface with the core processing modules.

- Additional Supporting Libraries:
– Libraries for logging (“common/logging”), metrics (“common/metrics”), configuration, and even testing frameworks are spread out to provide cross-cutting concerns.
– These should be represented as areas that support the primary functions (e.g., logging feeds into every module).

##### Relationships and Interaction Flow

– Validator modules interact with the beacon node through API calls (HTTP/CLI), and these are complemented by separate modules for slashing protection and validator management.
– The crypto and consensus libraries underpin nearly every major component; represent these as shared libraries that are “used by” the core processing modules.

##### Architectural Patterns and Design Principles

– Layered Architecture: From the networking layer through to state processing and API endpoints; show the separation between external input (networking, CLI) and internal state transitions.
– Emphasis on High-Performance and Safety: Indicate that many supporting modules (cryptography, logging, error handling) enforce design principles such as safe concurrency and fault tolerance.

##### Relevant Technologies and Libraries

– Rust is the implementation language, so note the use of Cargo workspaces and many independent Cargo.toml files.
– Emphasize dependencies on crypto libraries (e.g., using BLS for signatures), network libraries (like libp2p or custom implementations for gossip), and storage engines (LevelDB or LMDB implementations).
– Clustering of “common” crates indicates reusability – show these as utility modules that feed into several layers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces Layer
    subgraph "External Interfaces"
        NLN["Network Layer: Beacon Node Network"]:::network
        LN["Network Layer: Lighthouse Network"]:::network
        API["HTTP API"]:::interface
        CLI["LCLI"]:::interface
        WATCH["Watch"]:::interface
    end

    %% Core Processing Layer
    subgraph "Beacon Node"
        BC["Beacon Chain (Beacon Node/Beacon Chain)"]:::core
        BCore["Beacon Core (Beacon Node/src)"]:::core
    end

    %% Validator Modules
    subgraph "Validator Components"
        AM["Account Manager"]:::validator
        VC["Validator Client"]:::validator
        VM["Validator Manager"]:::validator
    end

    %% Supporting Libraries: Consensus & Cryptography
    subgraph "Consensus & Cryptography"
        CONS["Consensus"]:::consensus
        CRYP["Crypto"]:::consensus
    end

    %% Data Storage and Database Management
    subgraph "Data Storage"
        DBM["Database Manager"]:::storage
        STORE["Beacon Node Store (Beacon Node/store)"]:::storage
    end

    %% Additional Supporting Libraries
    subgraph "Additional Supporting Libraries"
        LOG["Logging"]:::support
        MET["Metrics"]:::support
        COM["Common Utilities"]:::support
    end

    %% --- Connections ---
    %% External Interfaces to Core Processing
    NLN -->|"incoming_data"| BC
    LN -->|"incoming_data"| BC
    API -->|"commands"| BCore
    CLI -->|"commands"| BCore
    WATCH -->|"monitoring"| BCore

    %% Relationship within Beacon Node
    BC -->|"state_flow"| BCore

    %% Validator Modules interact with Beacon Core
    AM -->|"validator_txn"| BCore
    VC -->|"validator_txn"| BCore
    VM -->|"validator_txn"| BCore

    %% External Interfaces also interact with Validator Components (e.g., registration via API)
    API -->|"validator_ops"| VM

    %% Supporting Libraries aid Beacon Core
    CONS -->|"consensus_logic"| BCore
    CRYP -->|"crypto_ops"| BCore

    %% Beacon Core persists state to Data Storage
    BCore -->|"persist_state"| STORE
    DBM -->|"db_access"| STORE

    %% Additional Supporting Libraries support core modules (dotted arrows)
    LOG -.-> BCore
    MET -.-> BCore
    COM -.-> BCore
    LOG -.-> API
    MET -.-> API

    %% --- Click Events ---
    click BC "https://github.com/sigp/lighthouse/tree/stable/beacon_node/beacon_chain"
    click BCore "https://github.com/sigp/lighthouse/tree/stable/beacon_node/src"
    click AM "https://github.com/sigp/lighthouse/tree/stable/account_manager"
    click VC "https://github.com/sigp/lighthouse/tree/stable/validator_client"
    click VM "https://github.com/sigp/lighthouse/tree/stable/validator_manager"
    click NLN "https://github.com/sigp/lighthouse/tree/stable/beacon_node/network"
    click LN "https://github.com/sigp/lighthouse/tree/stable/beacon_node/lighthouse_network"
    click CONS "https://github.com/sigp/lighthouse/tree/stable/consensus"
    click CRYP "https://github.com/sigp/lighthouse/tree/stable/crypto"
    click DBM "https://github.com/sigp/lighthouse/tree/stable/database_manager"
    click STORE "https://github.com/sigp/lighthouse/tree/stable/beacon_node/store"
    click API "https://github.com/sigp/lighthouse/tree/stable/beacon_node/http_api"
    click CLI "https://github.com/sigp/lighthouse/tree/stable/lcli"
    click WATCH "https://github.com/sigp/lighthouse/tree/stable/watch"
    click LOG "https://github.com/sigp/lighthouse/tree/stable/common/logging"
    click MET "https://github.com/sigp/lighthouse/tree/stable/common/metrics"
    click COM "https://github.com/sigp/lighthouse/tree/stable/common"

    %% --- Styles ---
    classDef core fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef network fill:#66CCFF,stroke:#000,stroke-width:2px;
    classDef interface fill:#66FFCC,stroke:#000,stroke-width:2px;
    classDef validator fill:#FF6666,stroke:#000,stroke-width:2px;
    classDef consensus fill:#99CC66,stroke:#000,stroke-width:2px;
    classDef storage fill:#CC99FF,stroke:#000,stroke-width:2px;
    classDef support fill:#CCCCCC,stroke:#000,stroke-width:2px;
```
