Gean - Go Lean Ethereum Client

A Go implementation of the Lean Ethereum consensus protocol.

Overview

Gean is the first Go-based Lean Ethereum consensus client, implementing the next-generation Ethereum consensus layer with post-quantum security, fast finality, and enhanced decentralization.

Getting Started

cd cmd/gean
go build
./gean

Philosophy

We follow a lean development approach inspired by ethlambda:

References

• leanSpec - Python reference specification
• ethlambda - Rust implementation

Roadmap

Milestone 1: Foundation (Types & Serialization) - COMPLETE

Core type system and SSZ serialization - the bedrock everything else builds on.

• Core primitive types (Slot, Epoch, Root, ValidatorIndex)
• Byte array types (Bytes4, Bytes20, Bytes32, Bytes48, Bytes52, Bytes96, Bytes3116)
• SSZ collections (Bitlist, Bitvector)
• SSZ serialization and merkleization
• HashTreeRoot() implementation
• Slot.IsJustifiableAfter() for 3SF-mini finality rules

Milestone 2: Consensus Containers - COMPLETE

Data structures for blocks, state, and attestations.

• Checkpoint, Validator containers
• Attestation, AttestationData, SignedAttestation, AggregatedAttestation
• BlockHeader, BlockBody, Block, BlockWithAttestation, SignedBlockWithAttestation
• State container with full validator registry
• Chain configuration (Config with GenesisTime)
• HashTreeRoot for all containers

Milestone 3: Clock & Genesis

Time management and chain initialization.

• SlotClock with 4-second slots
• Interval timing (sub-slot)
• Genesis state generation
• Genesis block creation
• Validator config loading

Milestone 4: Storage & Fork Choice

Persistent storage and chain head selection.

• Block and state storage interface
• LevelDB/Pebble backend
• Fork choice store (LMD-GHOST)
• Justification and finalization tracking
• Latest message tracking per validator

Milestone 5: P2P Networking

Peer-to-peer communication layer.

• libp2p host setup
• discv5 peer discovery
• Peer manager
• GossipSub for blocks and attestations
• Request-response protocols (Status, BlocksByRoot, BlocksByRange)

Milestone 6: Synchronization

Chain sync from peers.

• Range sync (batch block download)
• Head sync (follow chain tip)
• Block cache for pending blocks
• Peer scoring for sync

Milestone 7: State Transition

Block validation and state processing.

• Slot processing
• Block header validation
• Attestation processing
• Epoch boundary processing
• Justification and finalization updates

Milestone 8: XMSS Signatures

Post-quantum cryptography.

• XMSS signature verification
• Signature aggregation
• Integration with block/attestation validation

Milestone 9: Validator Client

Block production and attestation duties.

• Proposer duty calculation
• Attester duty calculation
• Block production
• Attestation creation and signing

Milestone 10: Full Node

Complete integrated client.

• Node orchestrator wiring all services
• CLI with run/genesis/keys commands
• Prometheus metrics
• HTTP API endpoints
• Docker support

Current Status

Milestone 1: Foundation - Complete

Milestone 2: Consensus Containers - Complete

All consensus data structures and their SSZ HashTreeRoot implementations are complete. Run go test ./... to verify (35 tests passing).

Next: Milestone 3 - Clock & Genesis

License

MIT