How ethpandaops/ethereum-package works
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.