# ethpandaops/ethereum-package architecture

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

- Interactive diagram: https://gitdiagram.com/ethpandaops/ethereum-package
- Repository: https://github.com/ethpandaops/ethereum-package

## Overview

##### Project Type and Purpose
- This is a full-stack network orchestration package (a Kurtosis package) for spinning up private or public Ethereum testnets/devnets over Docker or Kubernetes. It orchestrates multiple microservices (Execution Layer clients, Consensus Layer clients, Validator clients, metrics stacks, MEV infrastructure, explorers, fuzzers, etc.) into a cohesive network for testing and development.

A. Kurtosis Orchestrator
- **Kurtosis CLI** (user-facing)
- **Kurtosis Engine** (runs on Docker or Kubernetes)
- **Package IO & Config Parser** (`src/package_io`, `network_params.yaml`)
- **Network Launcher** (`src/network_launcher/*.star`)
- **Static‐files & Templates** (`static_files/…`)

B. Core Ethereum Network
1. **Execution Layer (EL) Nodes**
- Geth, Nethermind, Erigon, Besu, Reth, Nimbus‐Eth1, EthereumJS
- Each runs in its own container; connects to CL via Engine API
2. **Consensus Layer (CL) Nodes**
- Lighthouse, Prysm, Teku, Nimbus, Lodestar, Grandine
- Beacon + optional integrated validator (or separate VC)
3. **Validator Clients (VC)**
- Vero, Lighthouse, Teku, Prysm, Lodestar, Nimbus
- Either sidecar containers or integrated

C. Optional / Auxiliary Services
- **Genesis Generator** (EL & CL genesis data)
- **Transaction Spammer** (`tx_fuzz`, `spamoor`)
- **Testnet Verifier** (`assertoor`)
- **Prometheus** (metrics scraper) + **Grafana** (dashboard)
- **Blobscan** (EIP-4844 analysis)
- **BlockScout** or **Dora** explorers
- **Remote Signer** (Web3Signer)
- **Apache** (static file sharing)
- **MEV Infrastructure**
- MEV-Boost middleware
- Relay API (relay, housekeeper, website)
- Builder services (Flashbots, mev-rs, commit-boost)
- Flooders (`mev_flood`, `custom_flood`)

D. External Integrations
- **Snapshot Repo** (network sync)
- **Beacon Metrics Gazer**
- **JSON-RPC Snooper**

- User → CLI → Kurtosis Engine
- Engine reads `network_params.yaml` + static file templates → launches containers
- EL nodes ↔ CL nodes via Engine API (HTTP)
- CL nodes ↔ EL via Engine API callbacks
- CL nodes ↔ VC nodes (gRPC or HTTP)
- All nodes export metrics → Prometheus → Grafana
- Transaction Spammer → EL nodes (JSON-RPC)
- Testnet Verifier → CL / EL nodes (API calls)
- Blobscan → EL nodes (subscribe to blocks/transactions)
- MEV-Boost (sidecar) sits between EL & CL for PBS flows:
- EL→mev-boost→Relay→Builder & back
- Validator picks headers via mev-boost
- Remote Signer ↔ VC nodes

##### Architectural Patterns & Design Principles
- **Microservices / Sidecars**: Each client or tool is its own container; sidecars for metrics, snooping, MEV-Boost.
- **Template-Driven Configuration**: Static files + `network_params.yaml` drive container startup.
- **Composability & Reproducibility**: Identical over Docker & Kubernetes via Kurtosis abstractions.
- **Pluggable Client Matrix**: Participants matrix defines arbitrary combinations of EL/CL/VC.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Kurtosis Orchestrator
    subgraph "Kurtosis Control Plane"
        direction TB
        CLI["Kurtosis CLI"]:::control
        Engine["Kurtosis Engine"]:::control
        Parser["Package IO & Config Parser"]:::control
        Launcher["Network Launcher"]:::control
        Templates["Static-files & Templates"]:::control
    end

    %% Core Network Layers
    subgraph "Execution Layer" 
        direction TB
        EL_Geth["EL: Geth"]:::core
        EL_Nethermind["EL: Nethermind"]:::core
        EL_Erigon["EL: Erigon"]:::core
        EL_Besu["EL: Besu"]:::core
        EL_Reth["EL: Reth"]:::core
        EL_NimbusEth1["EL: Nimbus-Eth1"]:::core
        EL_EthereumJS["EL: EthereumJS"]:::core
    end

    subgraph "Consensus Layer"
        direction TB
        CL_Lighthouse["CL: Lighthouse"]:::core
        CL_Prysm["CL: Prysm"]:::core
        CL_Teku["CL: Teku"]:::core
        CL_Nimbus["CL: Nimbus"]:::core
        CL_Lodestar["CL: Lodestar"]:::core
        CL_Grandine["CL: Grandine"]:::core
    end

    subgraph "Validator Layer"
        direction TB
        VC_Core["VC Core"]:::core
        VC_Lighthouse["VC: Lighthouse"]:::core
        VC_Prysm["VC: Prysm"]:::core
        VC_Teku["VC: Teku"]:::core
        VC_Lodestar["VC: Lodestar"]:::core
        VC_Nimbus["VC: Nimbus"]:::core
        VC_Vero["VC: Vero"]:::core
    end

    %% Auxiliary Services
    subgraph "Auxiliary Services"
        direction TB
        Genesis["Genesis Generator"]:::aux
        Spammer["Transaction Spammer"]:::aux
        Verifier["Testnet Verifier"]:::aux
        Snooper["JSON-RPC Snooper"]:::aux
        ForkMon["Block Metrics Gazer"]:::aux
        Tracoor["Tracing Coord (Tracoor)"]:::aux
        Broadcaster["Broadcaster"]:::aux
        RemoteSigner["Remote Signer"]:::aux
        Apache["Apache"]:::aux
    end

    %% Metrics & Explorers
    subgraph "Monitoring & Explorers"
        direction TB
        Prom["Prometheus"]:::aux
        Graf["Grafana"]:::aux
        Blobscan["Blobscan"]:::aux
        ExplorerBS["BlockScout"]:::aux
        ExplorerDora["Dora"]:::aux
    end

    %% MEV Infrastructure
    subgraph "MEV Infrastructure" 
        direction TB
        MEVBoost["MEV-Boost"]:::mev
        Relay["MEV Relay"]:::mev
        Builder["MEV Builder"]:::mev
        Flood["MEV Flooders"]:::mev
    end

    %% User Flow
    User["User"]:::external -->|"uses"| CLI
    CLI -->|"invokes"| Engine
    Engine -->|"reads config"| Parser
    Engine -->|"reads templates"| Templates
    Engine -->|"launches"| EL_Geth
    Engine -->|"launches"| EL_Nethermind
    Engine -->|"launches"| EL_Erigon
    Engine -->|"launches"| EL_Besu
    Engine -->|"launches"| EL_Reth
    Engine -->|"launches"| EL_NimbusEth1
    Engine -->|"launches"| EL_EthereumJS

    Engine -->|"launches"| CL_Lighthouse
    Engine -->|"launches"| CL_Prysm
    Engine -->|"launches"| CL_Teku
    Engine -->|"launches"| CL_Nimbus
    Engine -->|"launches"| CL_Lodestar
    Engine -->|"launches"| CL_Grandine

    Engine -->|"launches"| VC_Core
    Engine -->|"launches"| VC_Lighthouse
    Engine -->|"launches"| VC_Prysm
    Engine -->|"launches"| VC_Teku
    Engine -->|"launches"| VC_Lodestar
    Engine -->|"launches"| VC_Nimbus
    Engine -->|"launches"| VC_Vero

    %% Core Interactions
    EL_Geth <-->|"Engine API (HTTP)"| CL_Lighthouse
    EL_Nethermind <-->|"Engine API (HTTP)"| CL_Prysm
    EL_Erigon <-->|"Engine API (HTTP)"| CL_Teku
    CL_Lighthouse <-->|"gRPC/HTTP"| VC_Lighthouse
    CL_Prysm <-->|"gRPC/HTTP"| VC_Prysm

    %% Metrics flows
    EL_Geth -.->|"metrics"| Prom
    EL_Nethermind -.->|"metrics"| Prom
    CL_Lighthouse -.->|"metrics"| Prom
    VC_Core -.->|"metrics"| Prom
    Prom -->|"scrapes"| Graf

    %% Auxiliary flows
    Spammer -->|"JSON-RPC"| EL_Geth
    Verifier -->|"API Calls"| CL_Lighthouse
    Verifier -->|"API Calls"| EL_Geth
    Blobscan -->|"subscribe blocks"| EL_Geth
    RemoteSigner <-->|"signing"| VC_Core

    %% MEV PBS flows
    EL_Geth -->|"block proposals"| MEVBoost
    MEVBoost -->|"relay pbss"| Relay
    Relay -->|"builder bids"| Builder
    Builder -->|"proposals"| MEVBoost
    MEVBoost -->|"feeds headers"| CL_Lighthouse
    Flood -->|"floods requests"| Relay

    %% Click Events
    click CLI "https://github.com/ethpandaops/ethereum-package/blob/main/main.star"
    click Engine "https://github.com/ethpandaops/ethereum-package/blob/main/src/network_launcher/kurtosis.star"
    click Parser "https://github.com/ethpandaops/ethereum-package/blob/main/src/package_io/input_parser.star"
    click Parser "https://github.com/ethpandaops/ethereum-package/blob/main/src/package_io/constants.star"
    click Templates "https://github.com/ethpandaops/ethereum-package/tree/main/static_files/"
    click Templates "https://github.com/ethpandaops/ethereum-package/blob/main/src/static_files/static_files.star"
    click EL_Geth "https://github.com/ethpandaops/ethereum-package/blob/main/src/el/geth/geth_launcher.star"
    click EL_Nethermind "https://github.com/ethpandaops/ethereum-package/blob/main/src/el/nethermind/nethermind_launcher.star"
    click EL_Erigon "https://github.com/ethpandaops/ethereum-package/blob/main/src/el/erigon/erigon_launcher.star"
    click EL_Besu "https://github.com/ethpandaops/ethereum-package/blob/main/src/el/besu/besu_launcher.star"
    click EL_Reth "https://github.com/ethpandaops/ethereum-package/blob/main/src/el/reth/reth_launcher.star"
    click EL_NimbusEth1 "https://github.com/ethpandaops/ethereum-package/blob/main/src/el/nimbus-eth1/nimbus_launcher.star"
    click EL_EthereumJS "https://github.com/ethpandaops/ethereum-package/blob/main/src/el/ethereumjs/ethereumjs_launcher.star"
    click CL_Lighthouse "https://github.com/ethpandaops/ethereum-package/blob/main/src/cl/lighthouse/lighthouse_launcher.star"
    click CL_Prysm "https://github.com/ethpandaops/ethereum-package/blob/main/src/cl/prysm/prysm_launcher.star"
    click CL_Teku "https://github.com/ethpandaops/ethereum-package/blob/main/src/cl/teku/teku_launcher.star"
    click CL_Nimbus "https://github.com/ethpandaops/ethereum-package/blob/main/src/cl/nimbus/nimbus_launcher.star"
    click CL_Lodestar "https://github.com/ethpandaops/ethereum-package/blob/main/src/cl/lodestar/lodestar_launcher.star"
    click CL_Grandine "https://github.com/ethpandaops/ethereum-package/blob/main/src/cl/grandine/grandine_launcher.star"
    click VC_Core "https://github.com/ethpandaops/ethereum-package/blob/main/src/vc/vc_launcher.star"
    click VC_Lighthouse "https://github.com/ethpandaops/ethereum-package/blob/main/src/vc/lighthouse.star"
    click VC_Prysm "https://github.com/ethpandaops/ethereum-package/blob/main/src/vc/prysm.star"
    click VC_Teku "https://github.com/ethpandaops/ethereum-package/blob/main/src/vc/teku.star"
    click VC_Lodestar "https://github.com/ethpandaops/ethereum-package/blob/main/src/vc/lodestar.star"
    click VC_Nimbus "https://github.com/ethpandaops/ethereum-package/blob/main/src/vc/nimbus.star"
    click VC_Vero "https://github.com/ethpandaops/ethereum-package/blob/main/src/vc/vero.star"
    click Genesis "https://github.com/ethpandaops/ethereum-package/blob/main/src/prelaunch_data_generator/el_cl_genesis/el_cl_genesis_generator.star"
    click Spammer "https://github.com/ethpandaops/ethereum-package/blob/main/src/tx_fuzz/tx_fuzz.star"
    click Spammer "https://github.com/ethpandaops/ethereum-package/blob/main/src/spamoor/spamoor.star"
    click Verifier "https://github.com/ethpandaops/ethereum-package/blob/main/src/assertoor/assertoor_launcher.star"
    click Prom "https://github.com/ethpandaops/ethereum-package/blob/main/src/prometheus/prometheus_launcher.star"
    click Graf "https://github.com/ethpandaops/ethereum-package/blob/main/src/grafana/grafana_launcher.star"
    click Blobscan "https://github.com/ethpandaops/ethereum-package/blob/main/src/blobscan/blobscan_launcher.star"
    click ExplorerBS "https://github.com/ethpandaops/ethereum-package/blob/main/src/blockscout/blockscout_launcher.star"
    click ExplorerDora "https://github.com/ethpandaops/ethereum-package/blob/main/src/dora/dora_launcher.star"
    click RemoteSigner "https://github.com/ethpandaops/ethereum-package/blob/main/src/remote_signer/remote_signer_launcher.star"
    click Apache "https://github.com/ethpandaops/ethereum-package/blob/main/src/apache/apache_launcher.star"
    click MEVBoost "https://github.com/ethpandaops/ethereum-package/blob/main/src/mev/commit-boost/mev_boost/mev_boost_launcher.star"
    click MEVBoost "https://github.com/ethpandaops/ethereum-package/blob/main/src/mev/flashbots/mev_boost/mev_boost_launcher.star"
    click Relay "https://github.com/ethpandaops/ethereum-package/blob/main/src/mev/flashbots/mev_relay/mev_relay_launcher.star"
    click Builder "https://github.com/ethpandaops/ethereum-package/blob/main/src/mev/flashbots/mev_builder/mev_builder_launcher.star"
    click Flood "https://github.com/ethpandaops/ethereum-package/blob/main/src/mev/flashbots/mev_flood/mev_flood_launcher.star"
    click Flood "https://github.com/ethpandaops/ethereum-package/blob/main/src/mev/flashbots/mev_custom_flood/mev_custom_flood_launcher.star"

    %% Styles
    classDef control fill:#f9f,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    classDef core fill:#bbdefb,stroke:#0d47a1,stroke-width:1px;
    classDef aux fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px;
    classDef mev fill:#ffe0b2,stroke:#e65100,stroke-width:1px;
    classDef external fill:#ffffff,stroke:#000,stroke-width:1px;
    class User external
```
