consensus-clients

name	consensus-clients
description	Use when comparing Ethereum consensus client implementations, looking up how a specific client implements a spec feature, checking client activity (PRs, issues, releases), or understanding architectural differences between Lodestar, Lighthouse, Prysm, Teku, Nimbus, and Grandine.

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 scripts/clone-repos.sh [base-dir]  # default: ~/ethereum-repos

Once cloned, use grep, find, and cat to navigate codebases directly:

# 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/