Gean: Lean Ethereum consensus client

An open-source Lean Ethereum consensus client, written in Go and maintained by Gean Labs.

Overview

Gean is:

• A consensus client for Lean Ethereum, designed for fast finality, quantum-resistant security, and a simpler core protocol.
• Implementing Lean Consensus devnet-5 alongside independent client implementations.
• Built for clarity and auditability, with a deliberately small codebase.
• Quantum-resistant by design, using XMSS signatures instead of BLS signatures.

Getting started

Prerequisites

• Go 1.25+
• Rust 1.92.0
• uv
• Docker

Building and testing

make build       # Build the Rust FFI and Go binaries
make test        # Run Go unit tests
make test-ffi    # Run XMSS FFI tests
make test-spec   # Generate and run production-scheme consensus fixtures
make lint        # Run Go and Rust linters
make docker-build

Run make help for all available targets.

Running locally

For a multi-client devnet:

make run-devnet

For a three-node Gean network, run the setup once and start each node in a separate terminal:

make run-setup
make run
make run-node1
make run-node2

At least one node must run as an aggregator for the network to finalize.

Memory requirements

Block-proposal and aggregation proofs are generated by the XMSS prover, which keeps a process-wide arena resident after startup and adds a transient multi-gigabyte peak per proof. Give a validator container at least 12 GB (--memory=12g); tighter limits get the process OOM-killed mid-proving, which is silent in the application log (check docker inspect for OOMKilled or the kernel log). The image sets GOMEMLIMIT=2GiB to keep the Go heap out of the prover's headroom; override it via the environment if your budget differs.

Current status

Gean tracks Lean Consensus devnet-5. Consensus fixtures are generated from leanSpec@eca701efeb5931010fe63925cd203c9ee55b2dbc, which pins lean-multisig-py v0.0.9. The XMSS FFI builds against leanVM e2592df4e30fdddbbf8ae26a333116c68cec7026.

LEAN_SPEC_COMMIT_HASH in the Makefile is the source of truth for the spec version; the leanVM rev is pinned in xmss/rust/multisig-glue/Cargo.toml.

Philosophy

Gean treats reviewability as a consensus-safety property. Consensus-critical behavior should remain small enough to audit end to end, and disagreements between clients should be traceable to a small number of files.

License

Gean is open-source software released under the MIT license.

Donations

We are a small team of African Ethereum core developers building Gean. Gean is an open-source project and a public good. Funding public goods is hard, and our work is supported through grants, community support, and individual donations.

We work full-time to contribute to the Ethereum ecosystem. If you would like to support our work, you can find our ETH address under "Sponsor this project" on this repository.