Skip to content

lambdaclass/ethrex

BranchesTags

Repository files navigation

ethrex

Minimalist, stable, modular and fast implementation of the Ethereum protocol in Rust.

Telegram Chat license

L1 and L2 support

This client supports running in two different modes:

  • As a regular Ethereum execution client
  • As a multi-prover ZK-Rollup (supporting SP1, RISC Zero and TEEs), where block execution is proven and the proof sent to an L1 network for verification, thus inheriting the L1's security. Support for based sequencing is currently in the works.

We call the first one ethrex L1 and the second one ethrex L2.

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, either from the Ethereum roadmap or from innovations from the L2s.

Read more about our engineering philosophy here

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, i.e rollups, vms, etc.
  • 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.

🗺️ Roadmap

This project is under active development. Over the next two months, our primary objective is to finalize and audit the first version of the stack.
This means every component — from L1 syncing to L2 bridging and prover integration — must meet stability, performance, and security standards.

The roadmap below outlines the remaining work required to achieve this milestone, organized into three major areas: L2, DevOps & Performance, and L1.

L2 Roadmap

Feature Description Status
Native Bridge Secure and trust-minimized ERC-20 bridge between Ethereum L1 and L2 using canonical messaging and smart contracts. In Progress
Shared Bridge Direct bridging between multiple L2s to improve UX and avoid L1 costs. Planned
Custom Native Token Define a native token (non-ETH) for gas, staking, incentives, and governance. Fully integrated into fee mechanics and bridging. Planned
Based Rollup Launch the rollup as a based permissionless rollup. Leverages Ethereum for sequencing and DA. For more information check ethrex roadmap for becoming based In Progress
Validiums & DACs Enhance Validium mode with Data Availability Committees. Planned
Gas & Fees Set up a custom fee model to price deposits or any forced-included transaction, including data availability costs. Planned
Aligned Integration Optimize integration with Aligned’s aggregation mode. In Progress
Risc0 Support Integrate RISC Zero as an alternative zkVM to SP1, enabling configurable proving backends. In Progress
Battle-Test the Prover Ensure the prover (e.g., SP1, Risc0) is robust, correct, and performant under production-level conditions. In Progress
One-Click L2 Deployment Deploy a fully operational rollup with a single command. Includes TDX, Prover, integrated Grafana metrics, alerting system, block explorer, bridge hub, backups and default configuration for rapid developer spin-up. In Progress

DevOps & Performance

Initiative Description Status
Performance Benchmarking Continuous ggas/s measurement, client comparison, and reproducible load tests. In Progress
DB Optimizations Snapshots, background trie commits, parallel Merkle root calculation, and exploratory DB design. In Progress
EVM Profiling Identify and optimize execution bottlenecks in the VM. In Progress
Deployment & Dev Experience One-command L2 launch, localnet spam testing, and L1 syncing on any network. In Progress

L1 Roadmap

Feature Description Status
P2P Improvements Use spawned to improve peer discovery, sync reliability, and connection handling. In Progress
SnapSync Stabilization Improve state healing under Mainnet load while using SnapSync. Planned
Block Processing Stability Full sync is actively running on Holesky and Hoodi networks, with continuous fixes applied. Additionally, while SnapSync isn’t fully reliable yet, archive sync will be supported to process post-Merge Mainnet and Sepolia blocks. The goal is to fix issues as they arise and stabilize the node across environments. In Progress

Documentation

We have markdown documentation under docs/, rendered using mdbook. You can render and serve it locally by running make docs-serve, after installing it as explained in their documentation, or with cargo install mdbook. We also use some mdbook preprocessors and backends for additional features, which can be installed running make docs-deps, or manually:

ethrex L1

Quick Start (L1 localnet)

Prerequisites

make localnet

This make target will:

  1. Build our node inside a docker image.
  2. Fetch our fork ethereum package, a private testnet on which multiple ethereum clients can interact.
  3. Start the localnet with kurtosis.

If everything went well, you should be faced with our client's logs (ctrl-c to leave)

To stop everything, simply run:

make stop-localnet

Dev Setup

Build

Rust

To build the node, you will need the rust toolchain. To do so, use rustup following this link

Database

Currently, the database is libmdbx, it will be set up when you start the client. The location of the db's files will depend on your OS:

  • Mac: ~/Library/Application Support/ethrex
  • Linux: ~/.config/ethrex

You can delete the db with:

cargo run --bin ethrex -- removedb

Dev Mode

In order to run ethrex without a Consensus Client and with the InMemory engine, to start from scratch each time we fire it up, the following make target can be used:

make dev
  • RPC endpoint: localhost:8545
  • Genesis file: ./test_data/genesis-l1.json

Test

For testing, we're using three kinds of tests.

Ethereum Foundation Tests

These are the official execution spec tests, you can execute them with:

make test

This will download the test cases from the official execution spec tests repo and run them with our glue code under cmd/ef_tests/tests.

Crate Specific Tests

The second kind are each crate's tests, you can run them like this:

make test CRATE=<crate>

For example:

make test CRATE="ethrex-blockchain"

Load tests

More information in the load test documentation.

Hive Tests

Finally, we have End-to-End tests with hive. Hive is a system which simply sends RPC commands to our node, and expects a certain response. You can read more about it here.

Prereqs

We need to have go installed for the first time we run hive, an easy way to do this is adding the asdf go plugin:

asdf plugin add golang https://github.com/asdf-community/asdf-golang.git

# If you need to se GOROOT please follow: https://github.com/asdf-community/asdf-golang?tab=readme-ov-file#goroot

And uncommenting the golang line in the asdf .tool-versions file:

rust 1.87.0
golang 1.23.2
Running Simulations

Hive tests are categorized by "simulations', and test instances can be filtered with a regex:

make run-hive-debug SIMULATION=<simulation> TEST_PATTERN=<test-regex>

This is an example of a Hive simulation called ethereum/rpc-compat, which will specificaly run chain id and transaction by hash rpc tests:

make run-hive SIMULATION=ethereum/rpc-compat TEST_PATTERN="/eth_chainId|eth_getTransactionByHash"

If you want debug output from hive, use the run-hive-debug instead:

make run-hive-debug SIMULATION=ethereum/rpc-compat TEST_PATTERN="*"

This example runs every test under rpc, with debug output

Assertoor

We run some assertoot checks on our CI, to execute them locally you can run the following:

make localnet-assertoor-tx
# or
make localnet-assertoor-blob

Those are two different set of assertoor checks the details are as follows:

assertoor-tx

assertoor-blob

For reference on each individual check see the assertoor-wiki

Run

Example run:

cargo run --bin ethrex -- --network test_data/genesis-kurtosis.json

The network argument is mandatory, as it defines the parameters of the chain. For more information about the different cli arguments check out the next section.

CLI Commands

ethrex Execution client

Usage: ethrex [OPTIONS] [COMMAND]

Commands:
  removedb  Remove the database
  import    Import blocks to the database
  export    Export blocks in the current chain into a file in rlp encoding
  compute-state-root  Compute the state root from a genesis file
  help                Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Node options:
      --network <GENESIS_FILE_PATH>
          Alternatively, the name of a known network can be provided instead to use its preset genesis file and include its preset bootnodes. The networks currently supported include holesky, sepolia, hoodi and mainnet.

          [env: ETHREX_NETWORK=]
          [default: mainnet]

      --datadir <DATABASE_DIRECTORY>
          If the datadir is the word `memory`, ethrex will use the `InMemory Engine`.

          [env: ETHREX_DATADIR=]
          [default: ethrex]

      --force
          Delete the database without confirmation.

      --metrics.addr <ADDRESS>
          [default: 0.0.0.0]

      --metrics.port <PROMETHEUS_METRICS_PORT>
          [env: ETHREX_METRICS_PORT=]
          [default: 9090]

      --metrics
          Enable metrics collection and exposition

      --dev
          If set it will be considered as `true`. The Binary has to be built with the `dev` feature enabled.

      --evm <EVM_BACKEND>
          Has to be `levm` or `revm`

          [env: ETHREX_EVM=]
          [default: levm]

      --log.level <LOG_LEVEL>
          Possible values: info, debug, trace, warn, error

          [default: INFO]

P2P options:
      --bootnodes <BOOTNODE_LIST>...
          Comma separated enode URLs for P2P discovery bootstrap.

      --syncmode <SYNC_MODE>
          Can be either "full" or "snap" with "full" as default value.

          [default: full]

      --p2p.enabled


      --p2p.addr <ADDRESS>
          [default: 0.0.0.0]

      --p2p.port <PORT>
          [default: 30303]

      --discovery.addr <ADDRESS>
          UDP address for P2P discovery.

          [default: 0.0.0.0]

      --discovery.port <PORT>
          UDP port for P2P discovery.

          [default: 30303]

RPC options:
      --http.addr <ADDRESS>
          Listening address for the http rpc server.

          [env: ETHREX_HTTP_ADDR=]
          [default: localhost]

      --http.port <PORT>
          Listening port for the http rpc server.

          [env: ETHREX_HTTP_PORT=]
          [default: 8545]

      --authrpc.addr <ADDRESS>
          Listening address for the authenticated rpc server.

          [default: localhost]

      --authrpc.port <PORT>
          Listening port for the authenticated rpc server.

          [default: 8551]

      --authrpc.jwtsecret <JWTSECRET_PATH>
          Receives the jwt secret used for authenticated rpc requests.

          [default: jwt.hex]

Syncing with Holesky

Step 1: Set up a jwt secret for both clients

As an example, we put the secret in a secrets directory in the home folder.

mkdir -p ~/secrets
openssl rand -hex 32 | tr -d "\n" | tee ~/secrets/jwt.hex

We will pass this new file’s path as an argument for both clients.

Step 2: Launch Ethrex

Pass holesky as a network and the jwt secret we set in the previous step. This will launch the node in full sync mode, in order to test out snap sync you can add the flag --syncmode snap.

cargo run --release --bin ethrex -- --http.addr 0.0.0.0 --network holesky --authrpc.jwtsecret ~/secrets/jwt.hex

Step 3: Set up a Consensus Node

For this quick tutorial we will be using lighthouse, but you can learn how to install and run any consensus node by reading their documentation.

You can choose your preferred installation method from lighthouse's installation guide and then run the following command to launch the node and sync it from a public endpoint

lighthouse bn --network holesky --execution-endpoint http://localhost:8551 --execution-jwt ~/secrets/jwt.hex --http --checkpoint-sync-url https://checkpoint-sync.holesky.ethpandaops.io

When using lighthouse directly from its repository, replace lighthouse bn with cargo run --bin lighthouse -- bn

Aside from holesky, these steps can also be used to connect to other supported networks by replacing the --network argument by another supported network and looking up a checkpoint sync endpoint for that network here

If you have a running execution node that you want to connect to your ethrex node you can do so by passing its enode as a bootnode using the --bootnodes flag

Once the node is up and running you will be able to see logs indicating the start of each sync cycle along with from which block hash to which block hash we are syncing. You will also get regular logs with the completion rate and estimated finish time for state sync and state rebuild processes during snap sync. This will look something like this:

INFO ethrex_p2p::sync: Syncing from current head 0xb5f7…bde4 to sync_head 0xce96…fa5e
INFO ethrex_p2p::sync::state_sync: Downloading state trie, completion rate: 68%, estimated time to finish: 1h20m14s
INFO ethrex_p2p::sync::trie_rebuild: State Trie Rebuild Progress: 68%, estimated time to finish: 1h5m45s

If you want to restart the sync from the very start you can do so by wiping the database using the following command:

cargo run --bin ethrex -- removedb

ethrex L2

In this mode, the ethrex code is repurposed to run a rollup that settles on Ethereum as the L1.

The main differences between this mode and regular ethrex are:

  • In regular rollup mode, there is no consensus; the node is turned into a sequencer that proposes blocks for the network. In based rollup mode, consensus is achieved by a mechanism that rotates sequencers, enforced by the L1.
  • Block execution is proven using a RISC-V zkVM (or attested to using TDX, a Trusted Execution Environment) and its proofs (or signatures/attestations) are sent to L1 for verification.
  • A set of Solidity contracts to be deployed to the L1 are included as part of network initialization.
  • Two new types of transactions are included: deposits (native token mints) and withdrawals.

At a high level, the following new parts are added to the node:

  • A proposer component, in charge of continually creating new blocks from the mempool transactions. This replaces the regular flow that an Ethereum L1 node has, where new blocks come from the consensus layer through the forkChoiceUpdate -> getPayload -> NewPayload Engine API flow in communication with the consensus layer.
  • A prover subsystem, which itself consists of two parts:
    • A proverClient that takes new blocks from the node, proves them, then sends the proof back to the node to send to the L1. This is a separate binary running outside the node, as proving has very different (and higher) hardware requirements than the sequencer.
    • A proverServer component inside the node that communicates with the prover, sending witness data for proving and receiving proofs for settlement on L1.
  • L1 contracts with functions to commit to new state and then verify the state transition function, only advancing the state of the L2 if the proof verifies. It also has functionality to process deposits and withdrawals to/from the L2.
  • The EVM is lightly modified with new features to process deposits and withdrawals accordingly.

Prerequisites

How to run

Initialize the network

Important

Before this step:

  1. Make sure you are inside the crates/l2 directory.
  2. Make sure the Docker daemon is running.
make init

This will setup a local Ethereum network as the L1, deploy all the needed contracts on it, then start an ethrex L2 node pointing to it.

Restarting the network

Warning

This command will cleanup your running L1 and L2 nodes.

make restart

Local L1 Rich Wallets

Most of them are here, but there's an extra one:

{
    "address": "0x3d1e15a1a55578f7c920884a9943b3b35d0d885b",
    "private_key": "0x385c546456b6a603a1cfcaa9ec9494ba4832da08dd6bcf4de9a71e4a01b74924"
}

ethrex L2 Docs

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

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.

Security

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

For more details, please refer to our Security Policy.

About

Minimalist, stable, modular and fast implementation of the Ethereum protocol in Rust

Topics

rust distributed-systems ethereum blockchain rollup p2p zero-knowledge rollups execution-layer

Resources

Readme

License

Apache-2.0 license

Security policy

Security policy
Activity
Custom properties

Stars

381 stars

Watchers

7 watching

Forks

69 forks
Report repository

Packages

 
 
 

Contributors 58
+ 44 contributors

Languages