consensus-clients

# Ethereum Consensus Client Cross-Reference You have detailed maps of all 6 Ethereum consensus clients. Use this to find implementations, compare approaches, and track activity. ## Local Clone Strategy (Preferred) **Clone client repos locally for fast code navigation.** Run the setup script from the plugin repo: ```bash bash scripts/clone-repos.sh [base-dir] # default: ~/ethereum-repos ``` Once cloned, use `grep`, `find`, and `cat` to navigate codebases directly: ```bash # Find how each client implements a spec function grep -rn "process_attestation\|processAttestation\|ProcessAttestation" \ ~/ethereum-repos/lodestar/packages/ \ ~/ethereum-repos/lighthouse/consensus/ \ ~/ethereum-repos/prysm/beacon-chain/core/ \ ~/ethereum-repos/teku/ethereum/spec/ \ ~/ethereum-repos/nimbus-eth2/beacon_chain/spec/ \ ~/ethereum-repos/grandine/transition_functions/ \ --include="*.ts" --include="*.rs" --include="*.go" --include="*.java" --include="*.nim" # Compare fork choice implementations find ~/ethereum-repos/*/ -path "*/fork*choice*" -name "*.ts" -o -name "*.rs" -o -name "*.go" | head -20 # Search for a specific type across all clients grep -rn "ExecutionPayloadEnvelope" ~/ethereum-repos/{lodestar,lighthouse,prysm,teku,nimbus-eth2,grandine}/ \ --include="*.ts" --include="*.rs" --include="*.go" --include="*.java" --include="*.nim" | head -30 ``` **Why local clones are better than WebFetch:** - Cross-client grep finds implementations in seconds - No URL guessing or 404s on wrong file paths - Can search across all clients simultaneously - Works offline, no rate limits **Fallback:** If repos aren't cloned locally, use WebFetch with the raw GitHub URLs listed for each client below. ## Client Overview | Client | Language | Repo | Build | Branch strategy | |---|---|---|---|---| | Lodestar | TypeScript | `ChainSafe/lodestar` | pnpm monorepo | `unstable` (dev), tags for releases | | Lighthouse | Rust | `sigp/lighthouse` | Cargo workspace | `unstable` (dev), `stable` (releases) | | Prysm | Go | `prysmaticlabs/prysm` | Bazel + Go modules | `develop` (dev), `master` (stable) | | Teku | Java | `Consensys/teku` | Gradle | `master` (dev), tags for releases | | Nimbus | Nim | `status-im/nimbus-eth2` | Nimble + Make | `unstable` (dev), `stable` (releases) | | Grandine | Rust | `grandinetech/grandine` | Cargo workspace | `develop` (dev), tags for releases | --- ## Lodestar (TypeScript) **Repo:** `ChainSafe/lodestar` **Package structure** (`packages/`): | Package | Purpose | |---|---| | `beacon-node` | Beacon chain client — block processing, sync, networking, API server | | `validator` | Validator client — duties, signing, slashing protection | | `state-transition` | Beacon state transition — epoch/block processing, per-fork logic | | `fork-choice` | LMD-GHOST + Casper FFG fork choice | | `types` | SSZ type definitions for all forks | | `params` | Consensus parameters and constants | | `config` | Network configuration (mainnet, testnet presets) | | `api` | REST client for beacon API | | `light-client` | Light client sync protocol | | `db` | Database layer (LevelDB) | | `reqresp` | libp2p req/resp protocol handlers | | `cli` | Command-line interface | | `logger` | Logging infrastructure | | `utils` | Shared utilities | | `prover` | Light client JSON-RPC proxy | | `era` | ERA file handling (historical data) | | `flare` | Debugging/testing tool | | `spec-test-util` | Spec test runner utilities | | `test-utils` | Shared test helpers | **Key code paths:** - State transition: `packages/state-transition/src/` - Per-fork logic: `packages/state-transition/src/slot/` - Epoch processing: `packages/state-transition/src/epoch/` - Block processing: `packages/state-transition/src/block/` - Networking: `packages/beacon-node/src/network/` - Sync: `packages/beacon-node/src/sync/` - API server: `packages/beacon-node/src/api/` - Fork choice: `packages/fork-choice/src/` - SSZ types: `packages/types/src/` **How to fetch code:** ``` https://raw.githubusercontent.com/ChainSafe/lodestar/unstable/packages/{package}/src/{path}.ts ``` **Key secondary repos:** | Repo | What | How to fetch | |---|---|---| | `ChainSafe/lodestar-z` | Zig libraries for Lodestar — actively developed, integrated into main client for performance-critical paths | `https://raw.githubusercontent.com/ChainSafe/lodestar-z/main/{path}` | | `ChainSafe/ssz` | SSZ TypeScript implementation (tree-backed persistent data structures) — `@chainsafe/ssz` on npm. Monorepo with packages: `ssz`, `persistent-merkle-tree`, `as-sha256`, `persistent-ts` | `https://raw.githubusercontent.com/ChainSafe/ssz/master/packages/ssz/src/{path}.ts` | | `ChainSafe/discv5` | Discovery v5 TypeScript implementation — used by Lodestar for peer discovery. Monorepo with `@chainsafe/discv5` and `@chainsafe/enr` packages | `https://raw.githubusercontent.com/ChainSafe/discv5/master/packages/discv5/src/{path}.ts` | --- ## Lighthouse (Rust) **Repo:** `sigp/lighthouse` **Directory structure:** | Directory | Purpose | |---|---| | `beacon_node/` | Beacon node — contains sub-crates for each component | | `beacon_node/beacon_chain/` | Core chain logic — block processing, head tracking | | `beacon_node/store/` | Database (hot + cold storage, LevelDB) | | `beacon_node/network/` | libp2p networking, sync | | `beacon_node/http_api/` | REST API server | | `beacon_node/execution_layer/` | Engine API client (EL communication) | | `beacon_node/eth1/` | Deposit contract interface | | `consensus/` | Spec implementation crates | | `consensus/types/` | SSZ types and containers | | `consensus/state_processing/` | State transition logic | | `consensus/fork_choice/` | Fork choice (proto-array) | | `consensus/cached_tree_hash/` | Optimized tree hashing | | `validator_client/` | Validator client | | `crypto/` | BLS, KZG, and other crypto | | `slasher/` | Slashing detection | | `lcli/` | CLI development tools | | `boot_node/` | Discovery bootstrap node | | `common/` | Shared libraries (logging, filesystem, etc.) | | `testing/` | Test utilities, simulator | **Key code paths:** - State transition: `consensus/state_processing/src/` - Per-slot: `consensus/state_processing/src/per_slot_processing.rs` - Per-block: `consensus/state_processing/src/per_block_processing/` - Per-epoch: `consensus/state_processing/src/per_epoch_processing/` - Types: `consensus/types/src/` - Fork choice: `consensus/fork_choice/src/` - Networking: `beacon_node/network/src/` - Sync: `beacon_node/network/src/sync/` - REST API: `beacon_node/http_api/src/` **How to fetch code:** ``` https://raw.githubusercontent.com/sigp/lighthouse/unstable/{path}.rs ``` **Key secondary repos:** | Repo | What | How to fetch | |---|---|---| | `sigp/ethereum_ssz` | SSZ serialization crate, optimized for speed and security | `https://raw.githubusercontent.com/sigp/ethereum_ssz/main/ssz/src/{path}.rs` | | `sigp/discv5` | Discovery v5 Rust implementation | `https://raw.githubusercontent.com/sigp/discv5/master/src/{path}.rs` | | `sigp/milhouse` | Persistent binary merkle tree — used for efficient state storage | `https://raw.githubusercontent.com/sigp/milhouse/main/src/{path}.rs` | | `sigp/enr` | Ethereum Node Records implementation | `https://raw.githubusercontent.com/sigp/enr/master/src/{path}.rs` | --- ## Prysm (Go) **Repo:** `prysmaticlabs/prysm` **Directory structure:** | Directory | Purpose | |---|---| | `beacon-chain/` | Beacon node implementation | | `beacon-chain/core/` | Core spec logic (blocks, epoch, validators) | | `beacon-chain/state/` | Beacon state management | | `beacon-chain/blockchain/` | Chain processing, head tracking | | `beacon-chain/sync/` | Sync protocols (initial, regular) | | `beacon-chain/p2p/` | libp2p networking | | `beacon-chain/rpc/` | gRPC + REST API | | `beacon-chain/execution/` | Engine API client | | `beacon-chain/forkchoice/` | Fork choice implementation | | `beacon-chain/db/` | Database (BoltDB) | | `validator/` | Validator client | | `consensus-types/` | Shared consensus data types | | `proto/` | Protobuf definitions | | `encoding/` | SSZ encoding, bytesutil | | `config/` | Network config, feature flags | | `crypto/` | BLS, hash utilities | | `network/` | High-level network utilities | | `monitoring/` | Metrics, tracing | | `contracts/deposit/` | Deposit contract bindings | | `cmd/` | CLI entry points (beacon-chain, validator, etc.) | | `tools/` | Development tools | **Key code paths:** - Block processing: `beacon-chain/core/blocks/` - Epoch processing: `beacon-chain/core/epoch/` - State transition: `beacon-chain/core/transition/` - Validator logic: `beacon-chain/core/validators/` - Fork choice: `beacon-chain/forkchoice/` - Types: `consensus-types/` - Networking: `beacon-chain/p2p/` - Sync: `beacon-chain/sync/` **How to fetch code:** ``` https://raw.githubusercontent.com/prysmaticlabs/prysm/develop/{path}.go ``` **Key secondary repos:** | Repo | What | How to fetch | |---|---|---| | `prysmaticlabs/gohashtree` | SHA256 library optimized for Merkle trees (Go + Assembly) | `https://raw.githubusercontent.com/prysmaticlabs/gohashtree/main/{path}.go` | Prysm is largely self-contained — most dependencies are vendored or in the main repo. --- ## Teku (Java) **Repo:** `Consensys/teku` **Directory structure:** | Directory | Purpose | |---|---| | `beacon/` | Core beacon chain logic | | `beacon/validator/` | Validator duties management | | `ethereum/` | Ethereum protocol modules | | `ethereum/spec/` | Spec types, logic, and milestones | | `ethereum/statetransition/` | State transition implementation | | `ethereum/executionlayer/` | Engine API client | | `networking/` | libp2p and discovery | | `networking/eth2/` | Eth2 gossip/reqresp protocols | | `storage/` | Database layer (RocksDB) | | `validator/` | Validator client modules | | `services/` | Service layer modules | | `infrastructure/` | Logging, metrics, async, IO | | `data/` | Data serialization, API types | | `eth-tests/` | Ethereum spec test integration | | `eth-reference-tests/` | Reference test runners | | `fork-choice-tests/` | Fork choice test vectors | | `acceptance-tests/` | End-to-end integration tests | | `teku/` | Main application entry point | **Key code paths:** - Spec logic: `ethereum/spec/src/main/java/tech/pegasys/teku/spec/` - Per-fork logic: `ethereum/spec/src/main/java/tech/pegasys/teku/spec/logic/versions/` - Types: `ethereum/spec/src/main/java/tech/pegasys/teku/spec/datastructures/`