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

• Rust
• Git
• Docker
• yq

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.

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.

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.

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.

• 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.

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

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.

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

Support for the pq-devnet-2 spec will be ending soon (see "older devnets"). A Docker tag devnet2 is currently available for this version.

We are working on adding support for the pq-devnet-3 spec. A Docker tag devnet3 will be published for this version.

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

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

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

• Checkpoint sync for long-lived networks
• pq-devnet-3 support
• Fetching of unknown blocks referenced by attestations
• Discarding blocks with invalid signatures
• Non-finalization hardening: bound memory usage during long periods of non-finalization
• Observability: more metrics from leanMetrics
• RPC endpoints for chain data consumption