ethlambda

Minimalist, fast and modular implementation of the Lean Ethereum client written in Rust.

🌐 Visit our website at ethlambda.xyz to learn more about the project.

Getting started

Prerequisites

• Rust
• Git
• Docker
• yq

Building and testing

We use cargo as our build system, but prefer make as a convenient wrapper for common tasks. These are some common targets:

# Formats all code
make fmt
# Checks and lints the code
make lint
# Runs all tests
make test
# Builds a docker image tagged as "ghcr.io/lambdaclass/ethlambda:local"
make docker-build DOCKER_TAG=local

Run make help or take a look at our Makefile for other useful commands.

Running in a devnet

To run a local devnet with multiple clients using lean-quickstart:

# This will clone lean-quickstart, build the docker image, and start a local devnet
make run-devnet

This generates fresh genesis files and starts all configured clients with metrics enabled. Press Ctrl+C to stop all nodes.

Note: On Linux, QUIC performance benefits from larger UDP receive buffers. If you see warnings about buffer sizes, increase the kernel limit:

sudo sysctl -w net.core.rmem_max=7340032
sudo sysctl -w net.core.wmem_max=7340032

To persist across reboots, add to /etc/sysctl.conf. For Docker, pass --sysctl net.core.rmem_max=7340032 --sysctl net.core.wmem_max=7340032.

Important: When running nodes manually (outside make run-devnet), at least one node must be started with --is-aggregator for attestations to be aggregated and included in blocks. Without this flag, the network will produce blocks but never finalize.

For custom devnet configurations, go to lean-quickstart/local-devnet/genesis/validator-config.yaml and edit the file before running the command above. See lean-quickstart's documentation for more details on how to configure the devnet.

Philosophy

Many long-established clients accumulate bloat over time. This often occurs due to the need to support legacy features for existing users or through attempts to implement overly ambitious software. The result is often complex, difficult-to-maintain, and error-prone systems.

In contrast, our philosophy is rooted in simplicity. We strive to write minimal code, prioritize clarity, and embrace simplicity in design. We believe this approach is the best way to build a client that is both fast and resilient. By adhering to these principles, we will be able to iterate fast and explore next-generation features early.

Read more about our engineering philosophy in this post of our blog.

Design principles

• Ensure effortless setup and execution across all target environments.
• Be vertically integrated. Have the minimal amount of dependencies.
• Be structured in a way that makes it easy to build on top of it.
• Have a simple type system. Avoid having generics leaking all over the codebase.
• Have few abstractions. Do not generalize until you absolutely need it. Repeating code two or three times can be fine.
• Prioritize code readability and maintainability over premature optimizations.
• Avoid concurrency split all over the codebase. Concurrency adds complexity. Only use where strictly necessary.

📚 References and acknowledgements

The following links, repos, companies and projects have been important in the development of this repo, we have learned a lot from them and want to thank and acknowledge them.

• Ethereum
• LeanEthereum
• Zeam
• Lantern

If we forgot to include anyone, please file an issue so we can add you. We always strive to reference the inspirations and code we use, but as an organization with multiple people, mistakes can happen, and someone might forget to include a reference.

📖 Documentation

Full documentation is available in the docs/ directory. Please refer to it for setup, usage, and development details. For better viewing, we have it hosted in docs.ethlambda.xyz.

Current status

The client implements the core features of a Lean Ethereum consensus client:

• Networking — libp2p peer connections, STATUS message handling, gossipsub for blocks and attestations
• State management — genesis state generation, state transition function, block processing
• Fork choice — 3SF-mini fork choice rule implementation with attestation-based head selection
• Validator duties — attestation production and broadcasting, block building

Additional features:

• leanMetrics support for monitoring and observability
• lean-quickstart integration for easier devnet running

Container Releases

Docker images are published to ghcr.io/lambdaclass/ethlambda with the following tags:

RELEASE.md has more details on our release process and how to tag new images.

pq-devnet-5

We are running the pq-devnet-5 spec. A Docker tag devnet5 is available for this version.

pq-devnet-6

pq-devnet-6 is in a planning phase; no features have been specified yet. Likely candidates are replacing LMD-GHOST and 3SF-mini, or execution layer integration.

Older devnets

Docker tags for each devnet are released, with format devnetX (i.e. devnet1, devnet2, devnet3, devnet4).

Support for older devnet releases is discontinued when the next devnet version is released.

Incoming features / Roadmap

We wrote a blogpost about what we think should be included in the near future.

Some features we are looking to implement in the near future, in order of priority:

• Optimize block building
• Use state-diffs for storing states in the database
• Prototype Goldfish + RLMD GHOST + BFT — devnet-6
• Integrate with execution clients, in particular ethrex — devnet-7
• Replace libp2p with the experimental ethp2p, which we are porting to Rust
• Add a guest program and ZK proving of the STF
• Rewrite the STF in the concrete programming language to enable formal verification

Experimental features

We have a proof-of-concept formalization of a part of the state transition function in Lean4 in PR #269.

Community

• Telegram: ethlambda group, where we post daily updates; drop by to ask questions or chat about anything Lean-related.
• X (Twitter): @ethlambda_lean for occasional updates.
• Weekly community call: every Friday, streamed live on @class_lambda; the call link is posted on Telegram beforehand.
• Ecosystem coordination: the PQ Interop calls on ethereum/pm cover cross-client Lean Ethereum work and related updates; the meeting links are posted on each issue.

Security

We take security seriously. If you discover a vulnerability in this project, please report it responsibly.

• You can report vulnerabilities directly via the GitHub "Report a Vulnerability" feature.
• Alternatively, send an email to security@lambdaclass.com.

For more details, please refer to our Security Policy.

Contributing

We welcome contributions! Please read our CONTRIBUTING.md for guidelines on how to get involved.