Getting started

Ethrex is a minimalist, stable, modular and fast implementation of the Ethereum protocol in Rust. The 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".

Quickstart L1

Follow these steps to sync an ethrex node on the Hoodi testnet.

MacOS

Install ethrex and lighthouse:

# install lightouse and ethrex
brew install lambdaclass/tap/ethrex
brew install lighthouse

# create secrets directory and jwt secret
mkdir -p ethereum/secrets/
cd ethereum/
openssl rand -hex 32 | tr -d "\n" | tee ./secrets/jwt.hex

On one terminal:

ethrex --authrpc.jwtsecret ./secrets/jwt.hex --network hoodi

and on another one:

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

Linux x86

Install ethrex and lighthouse:

# create secrets directory and jwt secret
mkdir -p ethereum/secrets/
cd ethereum/
openssl rand -hex 32 | tr -d "\n" | tee ./secrets/jwt.hex

# install lightouse and ethrex
curl -L https://github.com/lambdaclass/ethrex/releases/latest/download/ethrex-linux-x86_64 -o ethrex
chmod +x ethrex
curl -LO https://github.com/sigp/lighthouse/releases/download/v7.1.0/lighthouse-v7.1.0-x86_64-unknown-linux-gnu.tar.gz
tar -xvf lighthouse-v7.1.0-x86_64-unknown-linux-gnu.tar.gz

On one terminal:

./ethrex --authrpc.jwtsecret ./secrets/jwt.hex --network hoodi

and on another one:

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

For other CPU architectures, see the releases page.

Quickstart L2

Follow these steps to quickly launch a local L2 node. For advanced options and real deployments, see the links at the end.

MacOS

# install ethrex
brew install lambdaclass/tap/ethrex
ethrex l2 --dev

Linux x86

# install ethrex
curl -L https://github.com/lambdaclass/ethrex/releases/latest/download/ethrex-linux-x86_64 -o ethrex
chmod +x ethrex
./ethrex l2 --dev

For other CPU architectures, see the releases page.

Where to Start

Want to run ethrex in production as an execution client?

See Node operation for setup, configuration, monitoring, and best practices.
Interested in deploying your own L2?

See L2 rollup deployment for launching your own rollup, deploying contracts, and interacting with your L2.
Looking to contribute or develop?

Visit the Developer resources for local dev mode, testing, debugging, advanced CLI usage, and the CLI reference.
Want to understand how ethrex works?

Explore L1 fundamentals and L2 Architecture for deep dives into ethrex's design, sync modes, networking, and more.

Installation

Ethrex is designed to run on Linux and macOS.

There are 4 supported methods to install ethrex:

After following the installation steps you should have a binary that can run an L1 client or a multi-prover ZK-rollup with support for SP1, RISC Zero and TEEs.

Install ethrex (binary distribution)

This guide explains how to quickly install the latest pre-built ethrex binary for your operating system.

Download the latest release

Download the latest ethrex release for your OS from the GitHub Releases page.

Linux x86_64

curl -L https://github.com/lambdaclass/ethrex/releases/latest/download/ethrex-linux-x86_64 -o ethrex

Linux x86_64 with GPU support (for L2 prover)

If you want to run an L2 prover with GPU acceleration, download the GPU-enabled binary:

curl -L https://github.com/lambdaclass/ethrex/releases/latest/download/ethrex-linux-x86_64-gpu -o ethrex

Linux ARM (aarch64)

curl -L https://github.com/lambdaclass/ethrex/releases/latest/download/ethrex-linux-aarch64 -o ethrex

Linux ARM (aarch64) with GPU support (for L2 prover)

If you want to run an L2 prover with GPU acceleration, download the GPU-enabled binary:

curl -L https://github.com/lambdaclass/ethrex/releases/latest/download/ethrex-linux-aarch64-gpu -o ethrex

macOS (Apple Silicon, aarch64)

curl -L https://github.com/lambdaclass/ethrex/releases/latest/download/ethrex-macos-aarch64 -o ethrex

Set execution permissions

Make the binary executable:

chmod +x ethrex

(Optional) Move to a directory in your `$PATH`

To run ethrex from anywhere, move it to a directory in your $PATH (e.g., /usr/local/bin):

sudo mv ethrex /usr/local/bin/

Verify the installation

Check that Ethrex is installed and working:

ethrex --version

Install ethrex (package manager)

Coming soon.

Installing ethrex (docker)

Run Ethrex easily using Docker containers. This guide covers pulling and running official images.

Running the Docker Image

Check the Image

Verify the image is working:

docker run --rm ghcr.io/lambdaclass/ethrex --version

Start an ethrex Node

Run the following command to start a node in the background:

docker run \
    --rm \
    -d \
    -v ethrex:/root/.local/share/ethrex \
    -p 8545:8545 \
    -p 8551:8551 \
    -p 30303:30303 \
    -p 30303:30303/udp \
    -p 9090:9090 \
    --name ethrex \
    ghcr.io/lambdaclass/ethrex \
    --authrpc.addr 0.0.0.0

What this does:

Starts a container named ethrex
Publishes ports:
- 8545: JSON-RPC server (TCP)
- 8551: Auth JSON-RPC server (TCP)
- 30303: P2P networking (TCP/UDP)
- 9090: Metrics (TCP)
Mounts the Docker volume ethrex to persist blockchain data

Tip: You can add more Ethrex CLI arguments at the end of the command as needed.

Managing the Container

View logs:

docker logs -f ethrex

Stop the node:

docker stop ethrex

Building ethrex from source

Build ethrex yourself for maximum flexibility and experimental features.

Prerequisites

Rust toolchain (use rustup for easiest setup)
libclang (for RocksDB)
Git
solc (for L2 development)

L2 contracts

If you want to install ethrex for L2 development, you may set the COMPILE_CONTRACTS env var, so the binary have the necessary contract code.

export COMPILE_CONTRACTS=true

Install via `cargo install`

The fastest way to install ethrex from source:

cargo install --locked ethrex --git https://github.com/lambdaclass/ethrex.git

Optional features:

Add --features sp1,risc0 to enable SP1 and/or RISC0 provers
Add --features gpu for CUDA GPU support

Install a specific version:

cargo install --locked ethrex --git https://github.com/lambdaclass/ethrex.git --tag <version-tag>

Find available tags in the GitHub repo.

Verify installation:

ethrex --version

Build manually with `cargo build`

Clone the repository (replace <version-tag> with the desired version):

git clone --branch <version-tag> --depth 1 https://github.com/lambdaclass/ethrex.git
cd ethrex

Build the binary:

cargo build --bin ethrex --release

Optional features:

Add --features sp1,risc0 to enable SP1 and/or RISC0 provers
Add --features gpu for CUDA GPU support

The built binary will be in target/release/ethrex.

Verify the build:

./target/release/ethrex --version

(Optional) Move the binary to your $PATH:

sudo mv ./target/release/ethrex /usr/local/bin/

Running an Ethereum Node with ethrex

This section explains how to run an Ethereum L1 node using ethrex. Here you'll find:

Requirements for running a node (including the need for a consensus client)
Step-by-step instructions for setup and configuration
Guidance for both new and experienced users

If you already have a consensus client running, you can skip directly to the node startup instructions. Otherwise, continue to the next section for help setting up a consensus client.

Connecting to a consensus client

Ethrex is an execution client built for Ethereum networks after the merge. As a result, ethrex must operate together with a consensus client to fully participate in the network.

Consensus clients

There are several consensus clients and all of them work with ethrex. When choosing a consensus client we suggest you keep in mind client diversity.

Consensus clients and execution clients communicate through an authenticated JSON-RPC API. The authentication is done through a jwt secret. Ethrex automatically generates the jwt secret and saves it to the current working directory by default. You can also use your own previously generated jwt secret by using the --authrpc.jwtsecret flag or JWTSECRET_PATH environment variable. If the jwt secret at the specified path does not exist ethrex will create it.

Auth RPC server

By default the server is exposed at http://localhost:8551 but both the address and the port can be modified using the --authrpc.addr and --authrpc.port flags respectively.

Example

ethrex --authrpc.jwtsecret path/to/jwt.hex  --authrpc.addr localhost --authrpc.port 8551

Node startup

Supported networks

Ethrex is designed to support Ethereum mainnet and its testnets

Network	Chain id	Supported sync modes
mainnet	1	snap
sepolia	11155111	snap
holesky	17000	full, snap
hoodi	560048	full, snap

For more information about sync modes please read the sync modes document. Full syncing is the default, to switch to snap sync use the flag --syncmode snap

Run an Ethereum node

This guide will assume that you already installed ethrex and you know how to set up a consensus client to communicate with ethrex.

To sync with mainnet

ethrex --syncmode snap

To sync with sepolia

ethrex --network sepolia --syncmode snap

To sync with holesky

ethrex --network holesky

To sync with hoodi

ethrex --network hoodi

Once started, you should be able to check the sync status with:

curl http://localhost:8545 \
    -H 'content-type: application/json' \
    -d '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}'

The answer should be:

{"id":1,"jsonrpc":"2.0","result":{"startingBlock":"0x0","currentBlock":"0x0","highestBlock":"0x0"}}

Run an Ethereum node with Docker

You can simply start a node with a Consensus client and ethrex as Execution client with Docker using the docker-compose.yaml

curl -L -o docker-compose.yaml https://raw.githubusercontent.com/lambdaclass/ethrex/refs/heads/main/docker-compose.yaml
docker compose up

Or you can set a different network:

ETHREX_NETWORK=hoodi docker compose up

For more details and configuration options:

Configuration

This page covers the basic configuration options for running an L1 node with ethrex. Full list of options can be found at the CLI reference

Sync Modes

Ethrex supports different sync modes for node operation:

full: Downloads and verifies the entire chain.
snap: Fast sync using state snapshots (recommended for most users).

Set the sync mode with:

ethrex --sync <mode>

File Locations

By default, ethrex stores its data in:

Linux: ~/.local/share/ethrex
macOS: ~/Library/Application Support/ethrex

You can change the data directory with:

ethrex --datadir <path>

Ports

Default ports used by ethrex:

8545: JSON-RPC (HTTP)
8551: Auth JSON-RPC
30303: P2P networking (TCP/UDP)
9090: Metrics

You can change ports with the corresponding flags: --http.port, --authrpc.port, --p2p.port, --discovery.port, --metrics.port.

All services listen on 0.0.0.0 by default, except for the auth RPC, which listens on 127.0.0.1. This can also be changed with flags (e.g., --http.addr).

Log Levels

Control log verbosity with:

ethrex --log.level <level>

Levels: error, warn, info (default), debug, trace

Dev Mode (Localnet)

For local development and testing, you can use dev mode:

ethrex --dev

This runs a local network with block production and no external peers. This network has a list of predefined accounts with funds for testing purposes.

Monitoring and Metrics

Ethrex exposes metrics in Prometheus format on port 9090 by default. The easiest way to monitor your node is to use the provided Docker Compose stack, which includes Prometheus and Grafana preconfigured.

Quickstart: Monitoring Stack with Docker Compose

Clone the repository:

git clone https://github.com/lambdaclass/ethrex.git
cd ethrex/metrics

Start the monitoring stack:

docker compose -f docker-compose-metrics.yaml -f docker-compose-metrics-l1.overrides.yaml up -d

This will launch Prometheus and Grafana, already set up to scrape ethrex metrics.

Accessing Metrics and Dashboards

Prometheus: http://localhost:9091
Grafana: http://localhost:3001
- Default login: admin / admin
- Prometheus is preconfigured as a data source
- Example dashboards are included in the repo

Metrics from ethrex will be available at http://localhost:9090/metrics in Prometheus format.

Custom Configuration

Your ethrex setup may differ from the default configuration. Check your endpoints at provisioning/prometheus/prometheus_l1_sync_docker.yaml.

For manual setup or more details, see the Prometheus documentation and Grafana documentation.

Fundamentals

This section covers the core concepts and technical details behind ethrex as an Ethereum execution client. Here you'll find explanations about sync modes, networking, databases, security, and more.

note

This section is a work in progress and will be updated with more content and examples soon.

Networking

The network crate handles the ethereum networking protocols. This involves:

Discovery protocol: built on top of udp and it is how we discover new nodes.
devP2P: sits on top of tcp and is where the actual blockchain information exchange happens.

Implementation follows the official spec which can be found here. Also, we've inspired in some geth code.

Discovery protocol

In the next section, we'll be looking at the discovery protocol (discv4 to be more specific) and the way we have it set up. There are many points for improvement and here we discuss some possible solutions to them.

At startup, the discovery server launches three concurrent tokio tasks:

The listen loop for incoming requests.
A revalidation loop to ensure peers remain responsive.
A recursive lookup loop to request new peers and keep our table filled.

Before starting these tasks, we run a startup process to connect to an array of initial nodes.

Before diving into what each task does, first, we need to understand how we are storing our nodes. Nodes are stored in an in-memory matrix which we call a Kademlia table, though it isn't really a Kademlia table as we don't thoroughly follow the spec but we take it as a reference, you can read more here. This table holds:

Our node_id: The node's unique identifier computed by obtaining the keccak hash of the 64 bytes starting from index 1 of the encoded pub key.
A vector of 256 buckets which holds:
- peers: a vector of 16 elements of type PeersData where we save the node record and other related data that we'll see later.
- replacements: a vector of 16 elements of PeersData that are not connected to us, but we consider them as potential replacements for those nodes that have disconnected from us.

Peers are not assigned to any bucket but they are assigned based on its $0 \leq distance \leq 255$ to our node_id. Distance is defined by:

#![allow(unused)]
fn main() {
pub fn distance(node_id_1: H512, node_id_2: H512) -> usize {
    let xor = node_id_1 ^ node_id_2;
    let distance = U256::from_big_endian(xor.as_bytes());
    distance.bits().saturating_sub(1)
}
}

Startup

Before starting the server, we do a startup where we connect to an array of seeders or bootnodes. This involves:

Receiving bootnodes via CLI params
Inserting them into our table
Pinging them to notify our presence, so they acknowledge us.

This startup is far from being completed. The current state allows us to do basic tests and connections. Later, we want to do a real startup by first trying to connect to those nodes we were previously connected. For that, we'd need to store nodes on the database. If those nodes aren't enough to fill our table, then we also ping some bootnodes, which could be hardcoded or received through the cli. Current issues are opened regarding startup and nodes db.

Listen loop

The listen loop handles messages sent to our socket. The spec defines 6 types of messages:

Ping: Responds with a pong message. If the peer is not in our table we add it, if the corresponding bucket is already filled then we add it as a replacement for that bucket. If it was inserted we send a `ping from our end to get an endpoint proof.
Pong: Verifies that the pong corresponds to a previously sent ping, if so we mark the peer as proven.
FindNodes: Responds with a neighbors message that contains as many as the 16 closest nodes from the given target. A target is a pubkey provided by the peer in the message. The response can't be sent in one packet as it might exceed the discv4 max packet size. So we split it into different packets.
Neighbors: First we verify that we have sent the corresponding find_node message. If so, we receive the peers, store them, and ping them. Also, every find_node request may have a tokio Sender attached, if that is the case, we forward the nodes from the message through the channel. This becomes useful when waiting for a find_node response, something we do in the lookups.
ENRRequest: currently not implemented see here.
ENRResponse: same as above.

Re-validations

Re-validations are tasks that are implemented as intervals, that is: they run an action every x wherever unit of time (currently configured to run every 30 seconds). The current flow of re-validation is as follows

Every 30 seconds (by default) we ping the three least recently pinged peers: this may be fine now to keep simplicity, but we might prefer to choose three random peers instead to avoid the search which might become expensive as our buckets start to fill with more peers.
In the next iteration we check if they have answered
- if they have: we increment the liveness field by one.
- otherwise: we decrement the liveness by a third of its value.
If the liveness field is 0, we delete it and insert a new one from the replacements table.

Liveness checks are not part of the spec but are taken from geth, see here. This field is useful because it provides us with good criteria of which nodes are connected and we "trust" more. This trustiness is useful when deciding if we want to store this node in the database to use it as a future seeder or when establishing a connection in p2p.

Re-validations are another point of potential improvement. While it may be fine for now to keep simplicity at max, pinging the last recently pinged peers becomes quite expensive as the number of peers in the table increases. And it also isn't very "just" in selecting nodes so that they get their liveness increased so we trust them more and we might consider them as a seeder. A possible improvement could be:

Keep two lists: one for nodes that have already been pinged, and another one for nodes that have not yet been revalidated. Let's call the former "a" and the second "b".
In the beginning, all nodes would belong to "a" and whenever we insert a new node, they would be pushed to "a".
We would have two intervals: one for pinging "a" and another for pinging to nodes in "b". The "b" would be quicker, as no initial validation has been done.
When picking a node to ping, we would do it randomly, which is the best form of justice for a node to become trusted by us.
When a node from b responds successfully, we move it to a, and when one from a does not respond, we move it to b.

This improvement follows somewhat what geth does, see here.

Recursive Lookups

Recursive lookups are as with re-validations implemented as intervals. Their current flow is as follows:

Every 30min we spawn three concurrent lookups: one closest to our pubkey and three others closest to randomly generated pubkeys.
Every lookup starts with the closest nodes from our table. Each lookup keeps track of:
- Peers that have already been asked for nodes
- Peers that have been already seen
- Potential peers to query for nodes: a vector of up to 16 entries holding the closest peers to the pubkey. This vector is initially filled with nodes from our table.
We send a find_node to the closest 3 nodes (that we have not yet asked) from the pubkey.
We wait for the neighbors' response and push or replace those who are closer to the potential peers.
We select three other nodes from the potential peers vector and do the same until one lookup has no node to ask.

The way to do lookups aren't part of the spec. Our implementation aligns with geth approach, see here.

An example of how you might build a network

Finally, here is an example of how you could build a network and see how they connect each other:

We'll have three nodes: a, b, and c, we'll start a, then b setting a as a bootnode, and finally we'll start c with b as bootnode we should see that c connects to both a and b and so all the network should be connected.

node a:

cargo run --release -- --network ./fixtures/genesis/kurtosis.json

We get the enode by querying the node_info and using jq:

curl -s http://localhost:8545 \
-X POST \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"admin_nodeInfo","params":[],"id":1}' \
| jq '.result.enode'

node b:

We start a new server passing the enode from node a as an argument. Also changing the database dir and the ports is needed to avoid conflicts.

cargo run --release -- --network ./fixtures/genesis/kurtosis.json --bootnodes=`NODE_A_ENODE` \
--datadir=ethrex_b --authrpc.port=8552 --http.port=8546 --p2p.port=30305 --discovery.port=30306

node c Finally, with node_c we connect to node_b. When the lookup runs, node_c should end up connecting to node_a:

cargo run --release -- --network ./fixtures/genesis/kurtosis.json --bootnodes=`NODE_B_ENODE` \
--datadir=ethrex_c --authrpc.port=8553 --http.port=8547 --p2p.port=30308 --discovery.port=30310

We get the enode by querying the node_info and using jq:

curl -s http://localhost:8546 \
-X POST \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"admin_nodeInfo","params":[],"id":1}' \
| jq '.result.enode'

You could also spawn nodes from other clients and it should work as well.

Sync Modes

Full sync

Full syncing works by downloading and executing every block from genesis. This means that full syncing will only work for networks that started after The Merge, as ethrex only supports post merge execution.

Snap sync

Snap syncing is a much faster alternative to full sync that works by downloading and executing only the latest blocks from the network.

A snap sync cycle begins by fetching all the block headers (via eth p2p) between the current head (latest canonical block) and the sync head (block hash sent by a forkChoiceUpdate).

We will then fetch the block bodies from each header and at the same time select a pivot block (sync head - 64) and start rebuilding its state via snap p2p requests, if the pivot were to become stale during this rebuild we will select a newer pivot (sync head) and restart it.

After we fully rebuilt the pivot state and fetched all the block bodies we will fetch and store the receipts for the range between the current head and the pivot (including it), and at the same time store all blocks in the same range and execute all blocks after the pivot (like in full sync).

Snap State Rebuild

During snap sync we need to fully rebuild the pivot block's state. We can divide snap sync into 3 core processes: State Sync, Trie Rebuild, and Healing. The State Sync consists of downloading the plain state of the pivot block, aka the values on the leafs of the state & storage tries. For this process we will divide the state trie into segments and fetch each segment in parallel. We will also be relying on two side processes, the bytecode_fetcher and the storage_fetcher which will both remain active throughout the state sync, and fetch the bytecodes and storages of each account downloaded during the state sync. The Trie Rebuild process works in the background while State Sync is active. It consists of two processes running in parallel, one to rebuild the state trie and one to rebuild the storage tries. Both will read the data downloaded by the State Sync but while the state rebuild works independently, the storage rebuild will wait for the storage_fetcher to advertise which storages have been fully downloaded before attempting to rebuild them. The Healing process consists of fixing any inconsistencies leftover from the State Sync & Trie Rebuild processes after they finish. As state sync can spawn across multiple cycles with different pivot blocks the state will not be consistent with the latest pivot block, so we need to fetch all the nodes that the pivot's tries have and ours don't. The bytecode_fetcher and storage_healer processes will be involved to heal the bytecodes & storages of each account healed by the main state heal process. Also, the storage_healer will be spawned earlier, during state sync so that it can begin healing the storages that couldn't be fetched due to pivot staleness.

This diagram illustrates all the processes involved in snap sync:

SnapSync .

And this diagram shows the interaction between the different processes involved in State Sync, Trie Rebuild and Healing: StateSyncAndHealing .

To exemplify how queue-like processes work we will explain how the bytecode_fetcher works:

The bytecode_fetcher has its own channel where it receives code hashes from an active rebuild_state_trie process. Once a code hash is received, it is added to a pending queue. When the queue has enough messages for a full batch it will request a batch of bytecodes via snap p2p and store them. If a bytecode could not be fetched by the request (aka, we reached the response limit) it is added back to the pending queue. After the whole state is synced fetch_snap_state will send an empty list to the bytecode_fetcher to signal the end of the requests so it can request the last (incomplete) bytecode batch and end gracefully.

This diagram illustrates the process described above:

snap_sync

Healing Algorithm Explanation and Documentation (Before Path Based)

Healing is the last step of Snap Sync. Snap begins the downloading of the state and storage tries by downloading the leaves (account states and storage slots), and from those leaves we reconstruct the intermediate nodes (branches and extension). Afterwards we may be left with a malformed trie, as that step will resume the download of leaves with a new state root if the old one times out.

The purpose of the healing algorithm is “heal” that trie so that it ends up in a consistent state.

Healing Conceptually

The malformed trie is going to have large sections of the trie which are in a correct state, as we had all of the leaves in that sections and those accounts haven’t been modified in the blocks that happened concurrently to the snapsync algorithm.

Image of a trie, where the root node is in red, indicating that it’s in an incorrect state. It points to two branches, one is correct and one was computed from faulty data, and such doesn’t exist in the latest block

Example of a trie where 3 leaves where downloaded in block 1 and 1 was downloaded in block 2. The trie root is different from the state root of block 2, as one of the leaf nodes was modified in block 2.

The algorithm attempts to rebuild the trie through downloading the missing nodes, starting from the top. If the node is present in the database that means that we have that and all of their child nodes present in the database. If not, we download the node and check if the children of the root are present, applying the algorithm recursively.

Iteration 1 of algorithm

Iteration 2 of algorithm

Iteration 3 of algorithm

Final state of trie after healing

Implementation

The algorithm is implemented in ethrex currently in crates/networking/p2p/sync/state_healings.rs and crates/networking/p2p/sync/storage_healing.rs. All of our code examples are from the account state trie.

API

The API used is the ethereum capability snap/1, documented at https://github.com/ethereum/devp2p/blob/master/caps/snap.md and for healing the only method used is GetTrieNodes. This method allows us to ask our peers for nodes in a trie. We ask the nodes by path to the node, not by hash.

#![allow(unused)]
fn main() {
pub struct GetTrieNodes {    
    pub id: u64,    
    pub root_hash: H256,    
    // [[acc_path, slot_path_1, slot_path_2,...]...]    
    // The paths can be either full paths (hash) or 
    // only the partial path (compact-encoded nibbles)    
    pub paths: Vec<Vec<Bytes>>,    
    pub bytes: u64,
}
}

Staleness

The spec allows the nodes to stop responding if the request is older than 128 blocks. In that case, the response to the GetTrieNodes will be empty. As such, our algorithm checks periodically if the block is stale, and stops executing. In that scenario, we must be sure that the we leave the storage in a consistent state at any given time and doesn’t break our invariants.

#![allow(unused)]
fn main() {
// Current Staleness logic code
// We check with a clock if we are stale        
if !is_stale && current_unix_time() > staleness_timestamp {
    info!("state healing is stale");            
    is_stale = true;       
}
// We make sure that we have stored everything that we need to the database
if is_stale && nodes_to_heal.is_empty() && inflight_tasks == 0 {
  info!("Finished inflight tasks");            
  db_joinset.join_all().await;            
  break;
}
}

Membatch

Currently, our algorithm has an invariant, which is that if we have a node in storage we have its and all of its children are present. Therefore, when we download for a node if some of it’s children are missing we can’t immediately store it on disk. Our implementation currently stores the nodes in temporary structure called membatch, which stores the node and how many of it’s children are missing. When a child gets stored, we reduce the counter of missing children of the parent. If that numbers reaches 0, we write the parent to the database.

In code, the membatch is current HashMap<Nibbles, MembatchEntryValue> with the value being the following struct

#![allow(unused)]
fn main() {
pub struct MembatchEntryValue {
    /// The node to be flushed into storage
    node: Node,
    /// How many of the nodes that are child of this are not in storage
    children_not_in_storage_count: u64,
    /// Which is the parent of this node
    parent_path: Nibbles,
}
}

Known Optimization Issues

Membatch gets cleared between iterations, while it could be preserved and the hash checked.
When checking if a child is present in storage, we can also check if it’s in the membatch. If it is, we can skip that download and act like we have immediately downloaded that node.
Membatch is currently a HashMap, a BTreeMap or other structures may be faster in real use.
Storage healing receives as a parameter a list of accounts that need to be healed and it has get their state before it can run. Doing those reads could be more efficient.

Can you delete accounts in Ethereum? Yes

How it happens

Ethereum accounts are broadly divided into two categories:

Externally Owned Accounts (EOA): accounts for general users to transfer eth and call contracts.
Contracts: which execute code and store data.

Creating EOA is done through sending ETH into a new address, at which point the account is created and added into the state trie.

Creating a contract can be done through the CREATE and CREATE2 opcode. Notably, those opcodes check that the account is created at an address where the code is empty and the nonce is zero, but it doesn't check balance. As such, a contract can be created through taking over an existing account.

During the creating of a contract, the init_code is run which can include the self destruct opcode that deletes the contract in the same transaction it was created. Normally, this deletes an account that was created in the same transaction (because contracts are usually created over empty accounts) but in this case the account already existed because it already had some balance. This is the only edge case in which an account can go from existing to non-existing from one block to another after the Cancun fork.

How we found it

Snap-sync is broadly divided into two stages:

Downloading the leaves of the state (account states) and storage tries (storage slots)
Healing (reconciling the state).

Healing is needed because the leaves can be downloaded from disparate blocks, and to "fix" only the nodes of the trie that changed between nodes. In depth explanation.

We were working under the assumption that accounts were never deleted, so we adopted some specific optimizations. During the state healing stage every account that was "healed" was added into a list of accounts that needed to be checked for storage healing. When healing the storage of those accounts the algorithm requested their account states and expected them to be there to see if they had any storage that needed healing. This lead to the storage healing threads panicking when they failed to find the account that was deleted.

During the test of snapsync mainnet, we started seeing that storage healing was panicking, so we added some logs to see what account hashes were being accessed and when where they healed vs accessed. Exploring the database we saw that the offending account was present in a previous state and missing in the next one, with the corresponding merkle proof matching the block state root. Originally we suspected a reorg, but searching the blocks we saw they were finalized in the chain.

The account state present indicated an account with nonce 0, no code and no storage but with balance. We didn't have access to the account address, as the state trie only stores the hash of the account address so we turned to another strategy to find it. Using etherscan's API allowing to search internal transactions from a block range, we explored the range where we knew the account existed in the state trie. Hashing all of the to and from of the transactions we found the transaction that deleted the account with a self destruct. Despite the account becoming a contract just during that transaction, we saw that 900 blocks before it was created with a transfer. The result of the self destruct was the transfer of 0.044 ETH from one account to another.

The specific transaction that created the contract: https://etherscan.io/tx/0xf23b2c233410141cda0c6d24f21f0074c494565bfd54ce008c5ce1b30b23b0da

Introduction

Layer 2 (L2) solutions are protocols built on top of Ethereum to increase scalability and reduce transaction costs. L2s process transactions off-chain and periodically post data or proofs back to Ethereum mainnet, inheriting its security.

Ethrex is a framework that lets you launch your own L2 rollup or blockchain. With ethrex, you can deploy, run, and experiment with custom L2 networks, taking advantage of Ethereum's security while enabling high throughput and low fees.

Get started with your L2

Check out the Quickstart L2 guide to start your rollup in just a command, or jump right into the Deploy an L2 for more detailed instructions.

Deploy an L2

Prerequisites

This guide assumes that you have ethrex installed. If you haven't done so, follow one of the installation methods in the installation guide.

Deploy the contracts

The first step is to deploy the rollup's core contracts to your chosen L1 network.

1. Download the contracts

You can get the contracts in two ways:

From GitHub Releases:
- Download the latest release from GitHub Releases.

From source code (latest version):

Clone the repository:

git clone https://github.com/lambdaclass/ethrex.git
cd ethrex/crates/l2/contracts/src/l1

2. Deploy the contracts

You can deploy the contracts manually or using the built-in tool:

ethrex l2 deploy \
    --eth-rpc-url <L1_RPC_URL> \
    --private-key <DEPLOYER_PRIVATE_KEY> \
    --genesis-l2-path <GENESIS_L2_PATH> \
    --risc0.verifier-address <RISC0_VERIFIER_ADDRESS> \
    --sp1.verifier-address <SP1_VERIFIER_ADDRESS> \
    --tdx.verifier-address <TDX_VERIFIER_ADDRESS> \
    --aligned.aggregator-address <ALIGNED_AGGREGATOR_ADDRESS> \
    --on-chain-proposer-owner <OWNER_ADDRESS> \
    --bridge-owner <BRIDGE_OWNER_ADDRESS> \
    --randomize-contract-deployment

You can find a genesis example in the repo.

--bridge-owner must point to the address that will ultimately control the CommonBridge upgrades.
If you also need the deployer to accept the transfer on that owner’s behalf, pass --bridge-owner-pk <PRIVATE_KEY> in the same command; otherwise the owner can accept later.

Verifier addresses can be set to 0x00000000000000000000000000000000000000AA in case you don't want to use some prover. The same applies to Aligned.

tip

You can start a local development L1 network with ethrex l1 --dev and use its RPC URL for testing.

Run the sequencer

Next step is to start the sequencer. This command will start all necessary components for the L2 network except the prover.

ethrex l2 \
	--network <GENESIS_L2_PATH> \
	--l1.on-chain-proposer-address <ON_CHAIN_PROPOSER_ADDRESS> \
	--l1.bridge-address <BRIDGE_ADDRESS> \
	--rpc_url <L1_RPC_URL> \
	--committer.l1-private-key <COMMITTER_PRIVATE_KEY> \
    --proof-coordinator.l1-private-key <PROOF_COORDINATOR_PRIVATE_KEY> \
	--block-producer.coinbase-address <L2_COINBASE_ADDRESS> \

OnChainProposer and CommonBridge addresses can be found in the .env file, generated during the deployment process. Committer and Proof coordinator accounts must have L1 funds, as they will need to pay for gas fees on the L1 network.

For further configuration take a look at the CLI document

Run the prover

Lastly, you need to start the prover. This command will start the prover component for the L2 network.

ethrex l2 prover --proof-coordinators tcp://localhost:3900 --backend exec

In this example, the exec backend is used, which means the prover will only execute the transactions but not generate proofs. This is fine for development as it's faster. You may look for other backends like SP1 and RISC0 in production.

For further configuration take a look at the CLI document

Checking that everything is running

After starting the sequencer and prover, you can verify that your L2 node is running correctly:

Check the sequencer RPC:

You can request the latest block number:

curl http://localhost:1729 \
	-H 'content-type: application/json' \
	-d '{"jsonrpc":"2.0","method":"eth_blockNumber","id":"1","params":[]}'

The answer should be like this, and advance every 5 seconds:

{"id":"1","jsonrpc":"2.0","result":"0x1"}

Check logs:
- Review the terminal output or log files for any errors or warnings.
- After some time (1 minute by default) there should be a log from the L1 Committer informing a new batch is being sent to L1.

Monitoring and Metrics

Quickstart: Monitoring Stack with Docker Compose

Clone the repository:

git clone https://github.com/lambdaclass/ethrex.git
cd ethrex/metrics

Start the monitoring stack:

docker compose -f docker-compose-metrics.yaml -f docker-compose-metrics-l2.overrides.yaml up -d

This will launch Prometheus and Grafana, already set up to scrape ethrex metrics.

Accessing Metrics and Dashboards

Prometheus: http://localhost:9091
Grafana: http://localhost:3001
- Default login: admin / admin
- Prometheus is preconfigured as a data source
- Example dashboards are included in the repo

Metrics from ethrex will be available at http://localhost:9090/metrics in Prometheus format.

Custom Configuration

Your ethrex setup may differ from the default configuration. Check your endpoints at provisioning/prometheus/prometheus_l2.yaml.

For manual setup or more details, see the Prometheus documentation and Grafana documentation.

Admin API

This API exposes endpoints to manage the Sequencer.

Base URL

By default the server is listening on 127.0.0.1:5555 but can be configured with --admin-server.addr <address> --admin-server.port <port>

Endpoints

Health

Sequencer Health

Description

Performs a healthcheck on all the components of the sequencer returning a json with the status

Endpoint

GET /health

Example

curl -X GET http://localhost:5555/health

Admin server health

Description

Performs a healthcheck on the http admin server

Endpoint

GET /admin/health

Example

curl -X GET http://localhost:5555/admin/health

L1 Committer

Start Committer immediately

Description

Starts the committer immediately (with a delay of 0).

Endpoint

GET /committer/start

Example

curl -X GET http://localhost:5555/committer/start

Start Committer (with delay)

Description

Starts the committer with a configurable delay.

Endpoint

GET /committer/start/{delay}

Example

curl -X GET http://localhost:5555/committer/start/60000

Parameters

Name	Type	Description
delay	number	Delay in milliseconds before starting the committer.

Stop Committer

Description

Stops the committer.

Endpoint

GET /committer/stop

Example

curl -X GET http://localhost:5555/committer/stop

Architecture

This section provides an overview of the architecture of an L2 rollup built with ethrex. Here you'll find:

High-level diagrams and explanations of the main components
Details on how the sequencer, prover, and other modules interact
Information about aligned mode, the prover, the sequencer, and more

Use this section to understand how the different parts of an ethrex L2 fit together.

General overview of the ethrex L2 stack

This document aims to explain how the Lambda ethrex L2 and all its moving parts work.

Intro

At a high level, the way an L2 works is as follows:

There is a contract in L1 that tracks the current state of the L2. Anyone who wants to know the current state of the chain need only consult this contract.
Every once in a while, someone (usually the sequencer, but could be a decentralized network, or even anyone at all in the case of a based contestable rollup) builds a batch of new L2 blocks and publishes it to L1. We will call this the commit L1 transaction.
For L2 batches to be considered finalized, a zero-knowledge proof attesting to the validity of the batch needs to be sent to L1, and its verification needs to pass. If it does, everyone is assured that all blocks in the batch were valid and thus the new state is. We call this the verification L1 transaction.

We ommited a lot of details in this high level explanation. Some questions that arise are:

What does it mean for the L1 contract to track the state of L2? Is the entire L2 state kept on it? Isn't it really expensive to store a bunch of state on an Ethereum smart contract?
What does the ZK proof prove exactly?
How do we make sure that the sequencer can't do anything malicious if it's the one proposing blocks and running every transaction?
How does someone go in and out of the L2, i.e., how do you deposit money from L1 into L2 and then withdraw it? How do you ensure this can't be tampered with? Bridges are by far the most vulnerable part of blockchains today and going in and out of the L2 totally sounds like a bridge.

Below some answers to these questions, along with an overview of all the moving parts of the system.

How do you prove state?

Now that general purpose zkVMs exist, most people have little trouble with the idea that you can prove execution. Just take the usual EVM code you wrote in Rust, compile to some zkVM target instead and you're mostly done. You can now prove it.

What's usually less clear is how you prove state. Let's say we want to prove a new L2 batch of blocks that were just built. Running the ethrex execute_block function on a Rust zkVM for all the blocks in the batch does the trick, but that only proves that you ran the VM correctly on some previous state/batch. How do you know it was the actual previous state of the L2 and not some other, modified one?

In other words, how do you ensure that:

Every time the EVM reads from some storage slot (think an account balance, some contract's bytecode), the value returned matches the actual value present on the previous state of the chain.

For this, the VM needs to take as a public input the previous state of the L2, so the prover can show that every storage slot it reads is consistent with it, and the verifier contract on L1 can check that the given public input is the actual previous state it had stored. However, we can't send the entire previous state as public input because it would be too big; this input needs to be sent on the verification transaction, and the entire L2 state does not fit on it.

To solve this, we do what we always do: instead of having the actual previous state be the public input, we build a Merkle Tree of the state and use its root as the input. Now the state is compressed into a single 32-byte value, an unforgeable representation of it; if you try to change a single bit, the root will change. This means we now have, for every L2 batch, a single hash that we use to represent it, which we call the batch commitment (we call it "commitment" and not simply "state root" because, as we'll see later, this won't just be the state root, but rather the hash of a few different values including the state root).

The flow for the prover is then roughly as follows:

Take as public input the previous batch commitment and the next (output) batch commitment.
Execute all blocks in the batch to prove its execution is valid. Here "execution" means more than just transaction execution; there's also header validation, transaction validation, etc. (essentially all the logic ethrex needs to follow when executing and adding a new block to the chain).
For every storage slot read, present and verify a merkle path from it to the previous state root (i.e. previous batch commitment).
For every storage slot written, present and verify a merkle path from it to the next state root (i.e. next batch commitment).

As a final note, to keep the public input a 32 byte value, instead of passing the previous and next batch commitments separately, we hash the two of them and pass that. The L1 contract will then have an extra step of first taking both commitments and hashing them together to form the public input.

These two ideas will be used extensively throughout the rest of the documentation:

Whenever we need to add some state as input, we build a merkle tree and use its root instead. Whenever we use some part of that state in some way, the prover provides merkle paths to the values involved. Sometimes, if we don't care about efficient inclusion proofs of parts of the state, we just hash the data altogether and use that instead.
To keep the batch commitment (i.e. the value attesting to the entire state of the chain) a 32 byte value, we hash the different public inputs into one. The L1 contract is given all the public inputs on commit, checks their validity and then squashes them into one through hashing.

Reconstructing state/Data Availability

warning

The state diff mechanism is retained here for historical and conceptual reference.
Ethrex now publishes RLP-encoded blocks (with fee configs) in blobs.
The principles of verification and compression described below still apply conceptually to this new model.

While using a merkle root as a public input for the proof works well, there is still a need to have the state on L1. If the only thing that's published to it is the state root, then the sequencer could withhold data on the state of the chain. Because it is the one proposing and executing blocks, if it refuses to deliver certain data (like a merkle path to prove a withdrawal on L1), people may not have any place to get it from and get locked out of the chain or some of their funds.

This is called the Data Availability problem. As discussed before, sending the entire state of the chain on every new L2 batch is impossible; state is too big. As a first next step, what we could do is:

For every new L2 batch, send as part of the commit transaction the list of transactions in the batch. Anyone who needs to access the state of the L2 at any point in time can track all commit transactions, start executing them from the beginning and recontruct the state.

This is now feasible; if we take 200 bytes as a rough estimate for the size of a single transfer between two users (see this post for the calculation on legacy transactions) and 128 KB as a reasonable transaction size limit we get around ~650 transactions at maximum per commit transaction (we are assuming we use calldata here, blobs can increase this limit as each one is 128 KB and we could use multiple per transaction).

Going a bit further, instead of posting the entire transaction, we could just post which accounts have been modified and their new values (this includes deployed contracts and their bytecode of course). This can reduce the size a lot for most cases; in the case of a regular transfer as above, we only need to record balance updates of two accounts, which requires sending just two (address, balance) pairs, so (20 + 32) * 2 = 104 bytes, or around half as before. Some other clever techniques and compression algorithms can push down the publishing cost of this and other transactions much further.

This is called state diffs. Instead of publishing entire transactions for data availability, we only publish whatever state they modified. This is enough for anyone to reconstruct the entire state of the chain.

Detailed documentation on the state diffs spec.

How do we prevent the sequencer from publishing the wrong state diffs?

Once again, state diffs have to be part of the public input. With them, the prover can show that they are equal to the ones returned by the VM after executing all blocks in the batch. As always, the actual state diffs are not part of the public input, but their hash is, so the size is a fixed 32 bytes. This hash is then part of the batch commitment. The prover then assures us that the given state diff hash is correct (i.e. it exactly corresponds to the changes in state of the executed blocks).

There's still a problem however: the L1 contract needs to have the actual state diff for data availability, not just the hash. This is sent as part of calldata of the commit transaction (actually later as a blob, we'll get to that), so the sequencer could in theory send the wrong state diff. To make sure this can't happen, the L1 contract hashes it to make sure that it matches the actual state diff hash that is included as part of the public input.

With that, we can be sure that state diffs are published and that they are correct. The sequencer cannot mess with them at all; either it publishes the correct state diffs or the L1 contract will reject its batch.

Compression

Because state diffs are compressed to save space on L1, this compression needs to be proven as well. Otherwise, once again, the sequencer could send the wrong (compressed) state diffs. This is easy though, we just make the prover run the compression and we're done.

EIP 4844 (a.k.a. Blobs)

warning

The explanations below originally refer to state diffs, but the same blob-based mechanism now carries RLP-encoded block data and their associated fee configs.

While we could send state diffs through calldata, there is a (hopefully) cheaper way to do it: blobs. The Ethereum Cancun upgrade introduced a new type of transaction where users can submit a list of opaque blobs of data, each one of size at most 128 KB. The main purpose of this new type of transaction is precisely to be used by rollups for data availability; they are priced separately through a blob_gas market instead of the regular gas one and for all intents and purposes should be much cheaper than calldata.

Using EIP 4844, our state diffs would now be sent through blobs. While this is cheaper, there's a new problem to address with it. The whole point of blobs is that they're cheaper because they are only kept around for approximately two weeks and ONLY in the beacon chain, i.e. the consensus side. The execution side (and thus the EVM when running contracts) does not have access to the contents of a blob. Instead, the only thing it has access to is a KZG commitment of it.

This is important. If you recall, the way the L1 ensured that the state diff published by the sequencer was correct was by hashing its contents and ensuring that the hash matched the given state diff hash. With the contents of the state diff now no longer accesible by the contract, we can't do that anymore, so we need another way to ensure the correct contents of the state diff (i.e. the blob).

The solution is through a proof of equivalence between polynomial commitment schemes. The idea is as follows: proofs of equivalence allow you to show that two (polynomial) commitments point to the same underlying data. In our case, we have two commitments:

The state diff commitment calculated by the sequencer/prover.
The KZG commitment of the blob sent on the commit transaction (recall that the blob should just be the state diff).

If we turn the first one into a polynomial commitment, we can take a random evaluation point through Fiat Shamir and prove that it evaluates to the same value as the KZG blob commitment at that point. The commit transaction then sends the blob commitment and, through the point evaluation precompile, verifies that the given blob evaluates to that same value. If it does, the underlying blob is indeed the correct state diff.

Our proof of equivalence implementation follows Method 1 here. What we do is the following:

Prover side

Take the state diff being commited to as 4096 32-byte chunks (these will be interpreted as field elements later on, but for now we don't care). Call these chunks $d_{i}$ , with i ranging from 0 to 4095.
Build a merkle tree with the $d_{i}$ as leaves. Note that we can think of the merkle root as a polynomial commitment, where the i-th leaf is the evaluation of the polynomial on the i-th power of $ω$ , the 4096-th root of unity on $F_{q}$ , the field modulus of the BLS12-381 curve. Call this polynomial $f$ . This is the same polynomial that the L1 KZG blob commits to (by definition). Call the L1 blob KZG commitment $C_{1}$ and the merkle root we just computed $C_{2}$ .
Choose x as keccak( $C_{1}$ , $C_{2}$ ) and calculate the evaluation $f (x)$ ; call it y. To do this calculation, because we only have the $d_{i}$ , the easiest way to do it is through the barycentric formula. IMPORTANT: we are taking the $d_{i}$ , x, y, and $ω$ as elements of $F_{q}$ , NOT the native field used by our prover. The evaluation thus is:

$y = f (x) = \frac{x ^{4096} - 1}{4096} i = 0 \sum 4095 d_{i} \frac{ω ^{i}}{x - ω ^{i}}$
Set x and y as public inputs. All the above shows the verifier on L1 that we made a polynomial commitment to the state diff, that its evaluation on x is y, and that x was chosen through Fiat-Shamir by hashing the two commitments.

Verifier side

When commiting to the data on L1 send, as part of the calldata, a kzg blob commitment along with an opening proving that it evaluates to y on x. The contract, through the point evaluation precompile, checks that both:
- The commitment's hash is equal to the versioned hash for that blob.
- The evaluation is correct.

Transition to RLP-encoded Blocks

The state diff approach has been deprecated. While it provided a more compact representation, it only guaranteed the availability of the modified state, not the original transactions themselves. To ensure that transactions are also publicly available, Ethrex now publishes RLP-encoded blocks, together with their corresponding fee configurations, directly in blobs (see Transaction fees).

This new approach guarantees both transaction and state availability, at the cost of higher data size. According to our internal measurements (block_vs_state_diff_measurements.md), sending block lists in blobs instead of state diffs decreases the number of transactions that can fit in a single blob by approximately 2× for ETH transfers and 3× for ERC20 transfers.

L1<->L2 communication

To communicate between L1 and L2, we use two mechanisms called Privileged transactions, and L1 messages. In this section we talk a bit about them, first going through the more specific use cases for Deposits and Withdrawals.

Deposits

The mechanism for depositing funds to L2 from L1 is explained in detail in "Deposits".

Withdrawals

The mechanism for withdrawing funds from L2 back to L1 is explained in detail in "Withdrawals".

Recap

Batch Commitment

An L2 batch commitment is the hash of the following things:

The new L2 state root.
The state diff hash or polynomial commitments, depending on whether we are using calldata or blobs.
The Withdrawal logs merkle root.

The public input to the proof is then the hash of the previous batch commitment and the new one.

L1 contract checks

Commit transaction

For the commit transaction, the L1 verifier contract receives the following things from the sequencer:

The L2 batch number to be commited.
The new L2 state root.
The Withdrawal logs merkle root.
The state diffs hash or polynomial commitment scheme accordingly.

The contract will then:

Check that the batch number is the immediate successor of the last batch processed.
Check that the state diffs are valid, either through hashing or the point evaluation precompile.
Calculate the new batch commitment and store it.

Verify transaction

On a verification transaction, the L1 contract receives the following:

The batch number.
The batch proof.

The contract will then:

Compute the proof public input from the new and previous batch commitments (both are already stored in the contract).
Pass the proof and public inputs to the verifier and assert the proof passes.
If the proof passes, finalize the L2 state, setting the latest batch as the given one and allowing any withdrawals for that batch to occur.

What the sequencer cannot do

Forge Transactions: Invalid transactions (e.g. sending money from someone who did not authorize it) are not possible, since part of transaction execution requires signature verification. Every transaction has to come along with a signature from the sender. That signature needs to be verified; the L1 verifier will reject any block containing a transaction whose signature is not valid.
Withhold State: Every L1 commit transaction needs to send the corresponding state diffs for it and the contract, along with the proof, make sure that they indeed correspond to the given batch. TODO: Expand with docs on how this works.
Mint money for itself or others: The only valid protocol transaction that can mint money for a user is an L1 deposit. Every one of these mint transactions is linked to exactly one deposit transaction on L1. TODO: Expand with some docs on the exact details of how this works.

What the sequencer can do

The main thing the sequencer can do is CENSOR transactions. Any transaction sent to the sequencer could be arbitrarily dropped and not included in blocks. This is not completely enforceable by the protocol, but there is a big mitigation in the form of an escape hatch.

TODO: Explain this in detail.

Ethrex L2 sequencer

Components

The L2 Proposer is composed of the following components:

Block Producer

Creates Blocks with a connection to the auth.rpc port.

L1 Watcher

This component monitors the L1 for new deposits made by users. For that, it queries the CommonBridge contract on L1 at regular intervals (defined by the config file) for new DepositInitiated() events. Once a new deposit event is detected, it creates the corresponding deposit transaction on the L2. It also periodically fetches the BlobBaseFee from L1 (at a configured interval), which is used to compute the L1 fees.

L1 Transaction Sender (a.k.a. L1 Committer)

As the name suggests, this component sends transactions to the L1. But not any transaction, only commit and verify transactions.

Commit transactions are sent when the Proposer wants to commit to a new batch of blocks. These transactions contain the batch data to be committed in the L1.

Verify transactions are sent by the Proposer after the prover has successfully generated a proof of block execution to verify it. These transactions contains the new state root of the L2, the hash of the state diffs produced in the block, the root of the withdrawals logs merkle tree and the hash of the processed deposits.

Proof Coordinator

The Proof Coordinator is a simple TCP server that manages communication with a component called the Prover. The Prover acts as a simple TCP client that makes requests to prove a block to the Coordinator. It responds with the proof input data required to generate the proof. Then, the Prover executes a zkVM, generates the Groth16 proof, and sends it back to the Coordinator.

The Proof Coordinator centralizes the responsibility of determining which block needs to be proven next and how to retrieve the necessary data for proving. This design simplifies the system by reducing the complexity of the Prover, it only makes requests and proves blocks.

For more information about the Proof Coordinator, the Prover, and the proving process itself, see the Prover Docs.

L1 Proof Sender

The L1 Proof Sender is responsible for interacting with Ethereum L1 to manage proof verification. Its key functionalities include:

Connecting to Ethereum L1 to send proofs for verification.
Dynamically determine required proof types based on active verifier contracts (REQUIRE_<prover>_PROOF).
Ensure blocks are verified in the correct order by invoking the verify(..) function in the OnChainProposer contract. Upon successful verification, an event is emitted to confirm the block's verification status.
Operating on a configured interval defined by proof_send_interval_ms.

Configuration

Configuration is done either by CLI flags or through environment variables. Run cargo run --release --bin ethrex -- l2 --help in the repository's root directory to see the available CLI flags and envs.

Ethrex L2 prover

note

The shipping/deploying process and the Prover itself are under development.

Intro

The prover consists of two main components: handling incoming proving data from the L2 proposer, specifically from the ProofCoordinator component, and the zkVM. The Prover is responsible for this first part, while the zkVM serves as a RISC-V emulator executing code specified in crates/l2/prover/src/guest_program/guest/src. Before the zkVM code (or guest), there is a directory called interface, which indicates that we access the zkVM through the "interface" crate.

In summary, the Prover manages the inputs from the ProofCoordinator and then "calls" the zkVM to perform the proving process and generate the groth16 ZK proof.

Workflow

The ProofCoordinator monitors requests for new jobs from the Prover, which are sent when the prover is available. Upon receiving a new job, the Prover generates the proof, after which the Prover sends the proof back to the ProofCoordinator.

sequenceDiagram
    participant zkVM
    participant Prover
    participant ProofCoordinator
    Prover->>+ProofCoordinator: ProofData::Request
    ProofCoordinator-->>-Prover: ProofData::Response(batch_number, ProverInputs)
    Prover->>+zkVM: Prove(ProverInputs)
    zkVM-->>-Prover: Creates zkProof
    Prover->>+ProofCoordinator: ProofData::Submit(batch_number, zkProof)
    ProofCoordinator-->>-Prover: ProofData::SubmitAck(batch_number)

How

Dependencies:

RISC0
1. curl -L https://risczero.com/install | bash
2. rzup install cargo-risczero 3.0.3
3. rzup install risc0-groth16
4. rzup install rust
SP1
1. curl -L https://sp1up.succinct.xyz | bash
2. sp1up --version 5.0.8
SOLC

After installing the toolchains, a quick test can be performed to check if we have everything installed correctly.

L1 block proving

ethrex-prover is able to generate execution proofs of Ethereum Mainnet/Testnet blocks. An example binary was created for this purpose in crates/l2/prover/bench. Refer to its README for usage.

Dev Mode

To run the blockchain (proposer) and prover in conjunction, start the Prover, use the following command:

make init-prover-<sp1/risc0> # optional: GPU=true

Run the whole system with the prover - In one Machine

note

Used for development purposes.

cd crates/l2
make rm-db-l2 && make down
- It will remove any old database, if present, stored in your computer. The absolute path of SQL is defined by datadir.
make init
- Make sure you have the solc compiler installed in your system.
- Init the L1 in a docker container on port 8545.
- Deploy the needed contracts for the L2 on the L1.
- Start the L2 locally on port 1729.
In a new terminal → make init-prover-<sp1/risc0> # GPU=true.

After this initialization we should have the prover running in dev_mode → No real proofs.

GPU mode

Steps for Ubuntu 22.04 with Nvidia A4000:

Install docker → using the Ubuntu apt repository
- Add the user you are using to the docker group → command: sudo usermod -aG docker $USER. (needs reboot, doing it after CUDA installation)
- id -nG after reboot to check if the user is in the group.
Install Rust
Install RISC0
Install CUDA for Ubuntu
- Install CUDA Toolkit Installer first. Then the nvidia-open drivers.
Reboot
Run the following commands:

sudo apt-get install libssl-dev pkg-config libclang-dev clang
echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc

Run the whole system with a GPU Prover

Two servers are required: one for the Prover and another for the sequencer. If you run both components on the same machine, the Prover may consume all available resources, leading to potential stuttering or performance issues for the sequencer/node.

The number 1 simbolizes a machine with GPU for the Prover.
The number 2 simbolizes a machine for the sequencer/L2 node itself.

Prover/zkvm → prover with gpu, make sure to have all the required dependencies described at the beginning of Gpu Mode section.
1. cd ethrex/crates/l2
2. You can set the following environment variables to configure the prover:
  - PROVER_CLIENT_PROVER_SERVER_ENDPOINT: The address of the server where the client will request the proofs from
  - PROVER_CLIENT_PROVING_TIME_MS: The amount of time to wait before requesting new data to prove

Finally, to start the Prover/zkvm, run:
- make init-prover-<sp1/risc0> # optional: GPU=true

ProofCoordinator/sequencer → this server just needs rust installed.

cd ethrex/crates/l2

Create a .env file with the following content:

// Should be the same as ETHREX_COMMITTER_L1_PRIVATE_KEY and ETHREX_WATCHER_L2_PROPOSER_PRIVATE_KEY
ETHREX_DEPLOYER_L1_PRIVATE_KEY=<private_key>
// Should be the same as ETHREX_COMMITTER_L1_PRIVATE_KEY and ETHREX_DEPLOYER_L1_PRIVATE_KEY
ETHREX_WATCHER_L2_PROPOSER_PRIVATE_KEY=<private_key>
// Should be the same as ETHREX_WATCHER_L2_PROPOSER_PRIVATE_KEY and ETHREX_DEPLOYER_L1_PRIVATE_KEY
ETHREX_COMMITTER_L1_PRIVATE_KEY=<private_key>
// Should be different from ETHREX_COMMITTER_L1_PRIVATE_KEY and ETHREX_WATCHER_L2_PROPOSER_PRIVATE_KEY
ETHREX_PROOF_COORDINATOR_L1_PRIVATE_KEY=<private_key>
// Used to handle TCP communication with other servers from any network interface.
ETHREX_PROOF_COORDINATOR_LISTEN_ADDRESS=0.0.0.0
// Set to true to randomize the salt.
ETHREX_DEPLOYER_RANDOMIZE_CONTRACT_DEPLOYMENT=true
// Set to true if you want SP1 proofs to be required
ETHREX_L2_SP1=true
// Check the if the verification contract is present on your preferred network. Don't define this if you want it to be deployed automatically.
ETHREX_DEPLOYER_SP1_VERIFIER_ADDRESS=<address>
// Set to true if you want proofs to be required
ETHREX_L2_RISC0=true
// Check the if the contract is present on your preferred network. You shall deploy it manually if not.
ETHREX_DEPLOYER_RISC0_VERIFIER_ADDRESS=<address>
// Set to any L1 endpoint.
ETHREX_ETH_RPC_URL=<url>

source .env

note

Make sure to have funds, if you want to perform a quick test 0.2[ether] on each account should be enough.

Finally, to start the proposer/l2 node, run:
- make rm-db-l2 && make down
- make deploy-l1 && make init-l2 (if running a risc0 prover, see the next step before invoking the L1 contract deployer)
If running with a local L1 (for development), you will need to manually deploy the risc0 contracts by following the instructions here.
For a local L1 running with ethrex, we do the following:
1. clone the risc0-ethereum repo
2. edit the risc0-ethereum/contracts/deployment.toml file by adding
```
[chains.ethrex]
name = "Ethrex local devnet"
id = 9
```
3. export env. variables (we are using an ethrex's rich L1 account)
```
export VERIFIER_ESTOP_OWNER="0x4417092b70a3e5f10dc504d0947dd256b965fc62"
export DEPLOYER_PRIVATE_KEY="0x941e103320615d394a55708be13e45994c7d93b932b064dbcb2b511fe3254e2e"
export DEPLOYER_ADDRESS="0x4417092b70a3e5f10dc504d0947dd256b965fc62"
export CHAIN_KEY="ethrex"
export RPC_URL="http://localhost:8545"

export ETHERSCAN_URL="dummy"
export ETHERSCAN_API_KEY="dummy"
```
  the last two variables need to be defined with some value even if not used, else the deployment script fails.
4. cd into risc0-ethereum/
5. run the deployment script
```
bash contracts/script/manage DeployEstopGroth16Verifier --broadcast
```
6. if the deployment was successful you should see the contract address in the output of the command, you will need to pass this as an argument to the L2 contract deployer, or via the ETHREX_DEPLOYER_RISC0_VERIFIER_ADDRESS=<address> env. variable. if you get an error like risc0-ethereum/contracts/../lib/forge-std/src/Script.sol": No such file or directory (os error 2), try to update the git submodules (foundry dependencies) with git submodule update --init --recursive.

Configuration

Configuration is done through environment variables or CLI flags. You can see a list of available flags by passing --help to the CLI.

The following environment variables are available to configure the Prover:

CONFIGS_PATH: The path where the PROVER_CLIENT_CONFIG_FILE is located at.
PROVER_CLIENT_CONFIG_FILE: The .toml that contains the config for the Prover.
PROVER_ENV_FILE: The name of the .env that has the parsed .toml configuration.
PROVER_CLIENT_PROVER_SERVER_ENDPOINT: Prover Server's Endpoint used to connect the Client to the Server.

The following environment variables are used by the ProverServer:

PROVER_SERVER_LISTEN_IP: IP used to start the Server.
PROVER_SERVER_LISTEN_PORT: Port used to start the Server.
PROVER_SERVER_VERIFIER_ADDRESS: The address of the account that sends the zkProofs on-chain and interacts with the OnChainProposer verify() function.
PROVER_SERVER_VERIFIER_PRIVATE_KEY: The private key of the account that sends the zkProofs on-chain and interacts with the OnChainProposer verify() function.

note

The PROVER_SERVER_VERIFIER account must differ from the COMMITTER_L1 account.

How it works

The prover's sole purpose is to generate a block (or batch of blocks) execution proof. For this, ethrex-prover implements a blocks execution program and generates a proof of it using different RISC-V zkVMs (SP1, Risc0).

The prover runs a process that polls another for new jobs. The job must provide the program inputs. A proof of the program's execution with the provided inputs is generated by the prover and sent back.

Program inputs

The inputs for the blocks execution program (also called program inputs or prover inputs) are:

the blocks to prove (header and body)
the first block's parent header
an execution witness
the blocks' deposits hash
the blocks' withdrawals Merkle root
the blocks' state diff hash

The last three inputs are L2 specific.

These inputs are required for proof generation, but not all of them are committed as public inputs, which are needed for proof verification. The proof's public inputs (also called program outputs) will be:

the initial state hash (from the first block's parent header)
the final state hash (from the last block's header)
the blocks' deposits hash
the blocks' withdrawals Merkle root
the blocks' state diff hash

Execution witness

The purpose of the execution witness is to allow executing the blocks without having access to the whole Ethereum state, as it wouldn't fit in a zkVM program. It contains only the state values needed during the execution.

An execution witness contains all the initial state values (state nodes, codes, storage keys, block headers) that will be read or written to during the blocks' execution.

An execution witness is created from a prior execution of the blocks. Before proving, we need to:

execute the blocks (also called "pre-execution") to identify which state values will be accessed.
log every initial state value accessed or updated during this execution.
retrieve an MPT proof for each value, linking it (or its non-existence) to the initial state root hash.

Steps 1 and 2 are data collection steps only - no validation is performed at this stage. The actual validation happens later inside the zkVM guest program. Step 3 involves more complex logic due to potential issues when restructuring the pruned state trie after value removals. In sections initial state validation and final state validation we explain what are pruned tries and in which case they get restructured.

If a value is removed during block execution (meaning it existed initially but not finally), two pathological cases can occur where the witness lacks sufficient information to update the trie structure correctly:

Case 1

Image showing restructuration for case 1

Here, only leaf 1 is part of the execution witness, so we lack the proof (and thus the node data) for leaf 2. After removing leaf 1, branch 1 becomes redundant. During trie restructuring, it's replaced by leaf 3, whose path is the path of leaf 2 concatenated with a prefix nibble (k) representing the choice taken at the original branch 1, and keeping leaf 2's value.

branch1 = {c_1, c_2, ..., c_k, ..., c_16} # Only c_k = hash(leaf2) is non-empty
leaf2 = {value, path}
leaf3 = {value, concat(k, path)} # New leaf replacing branch1 and leaf2

Without leaf 2's data, we cannot construct leaf 3. The solution is to fetch the final state proof for the key of leaf 2. This yields an exclusion proof containing leaf 3. By removing the prefix nibble k, we can reconstruct the original path and value of leaf 2. This process might need to be repeated if similar restructuring occurred at higher levels of the trie.

Case 2

Image showing restructuration for case 2

In this case, restructuring requires information about branch/ext 2 (which could be a branch or extension node), but this node might not be in the witness. Checking the final extension node might seem sufficient to deduce branch/ext 2 in simple scenarios. However, this fails if similar restructuring occurred at higher trie levels involving more removals, as the final extension node might combine paths from multiple original branches, making it ambiguous to reconstruct the specific missing branch/ext 2 node.

The solution is to fetch the missing node directly using a debug JSON-RPC method, like debug_dbGet (or debug_accountRange and debug_storageRangeAt if using a Geth node).

note

These problems arise when creating the execution witness solely from state proofs fetched via standard JSON-RPC. In the L2 context, where we control the sequencer, we could develop a protocol to easily retrieve all necessary data more directly. However, the problems remain relevant when proving L1 blocks (e.g., for testing/benchmarking).

Blocks execution program

The program leverages ethrex-common primitives and ethrex-vm methods. ethrex-prover implements a program that uses the existing execution logic and generates a proof of its execution using a zkVM. Some L2-specific logic and input validation are added on top of the basic blocks execution.

The following sections outline the steps taken by the execution program.

Prelude 1: state trie basics

We recommend learning about Merkle Patricia Tries (MPTs) to better understand this section.

Each executed block transitions the Ethereum state from an initial state to a final state. State values are stored in MPTs:

Each account has a Storage Trie containing its storage values.
The World State Trie contains all account information, including each account's storage root hash (linking storage tries to the world trie).

Hashing the root node of the world state trie generates a unique identifier for a particular Ethereum state, known as the "state hash".

There are two kinds of MPT proofs:

Inclusion proofs: Prove that key: value is a valid entry in the MPT with root hash h.
Exclusion proofs: Prove that key does not exist in the MPT with root hash h. These proofs allow verifying that a value is included (or its key doesn't exist) in a specific state.

Prelude 2: deposits, withdrawals and state diffs

These three components are specific additions for ethrex's L2 protocol, layered on top of standard Ethereum execution logic. They each require specific validation steps within the program.

For more details, refer to Overview, Withdrawals, and State diffs.

Step 1: initial state validation

The program validates the initial state by converting the ExecutionWitness into a GuestProgramState and verifying that its trie structure correctly represents the expected state. This involves checking that the calculated state trie root hash matches the initial state hash (obtained from the first block's parent block header).

The validation happens in several steps:

The ExecutionWitness (collected during pre-execution) is converted to GuestProgramState
A GuestProgramStateWrapper is created to provide database functionality
The state trie root is calculated and compared against the parent block header's state root

This validation ensures that all state values needed for execution are properly linked to the initial state via their MPT proofs. Having the initial state proofs (paths from the root to each relevant leaf) is equivalent to having a relevant subset of the world state trie and storage tries - a set of "pruned tries". This allows operating directly on these pruned tries (adding, removing, modifying values) during execution.

Step 2: blocks execution

After validating the initial state, the program executes the blocks. This leverages the existing ethrex execution logic used by the L2 client itself.

Step 3: final state validation

During execution, state values are updated (modified, created, or removed). After execution, the program calculates the final state by applying these state updates to the initial pruned tries.

Applying the updates results in a new world state root node for the pruned tries. Hashing this node yields the calculated final state hash. The program then verifies that this calculated hash matches the expected final state hash (from the last block header), thus validating the final state.

As mentioned earlier, removing values can sometimes require information not present in the initial witness to correctly restructure the pruned tries. The Execution witness section details this problem and its solution.

Step 4: deposit hash calculation

After execution and final state validation, the program calculates a hash encompassing all deposits made within the blocks (extracting deposit info from PrivilegedL2Transaction type transactions). This hash is committed as a public input, required for verification on the L1 bridge contract.

Step 5: withdrawals Merkle root calculation

Similarly, the program constructs a binary Merkle tree of all withdrawals initiated in the blocks and calculates its root hash. This hash is also committed as a public input. Later, L1 accounts can claim their withdrawals by providing a Merkle proof of inclusion that validates against this root hash on the L1 bridge contract.

Step 6: state diff calculation and commitment

Finally, the program calculates the state diffs (changes between initial and final state) intended for publication to L1 as blob data. It creates a commitment to this data (a Merkle root hash), which is committed as a public input. Using proof of equivalence logic within the L1 bridge contract, this Merkle commitment can be verified against the KZG commitment of the corresponding blob data.

Running Ethrex in Aligned Mode

This document explains how to run an Ethrex L2 node in Aligned mode and highlights the key differences in component behavior compared to the default mode.

Check How to Run (local devnet) for a development or testing.
Check How to Run (testnet) for a prod-like environment.

How to run (testnet)

important

For this guide we assumed that there is an L1 running with all Aligned environment set.

1. Generate the prover ELF/VK

Run:

cd ethrex/crates/l2
make build-prover-<sp1/risc0> # optional: GPU=true

This will generate the SP1 ELF program and verification key under:

crates/l2/prover/src/guest_program/src/sp1/out/riscv32im-succinct-zkvm-elf
crates/l2/prover/src/guest_program/src/sp1/out/riscv32im-succinct-zkvm-vk

2. Deploying L1 Contracts

In a console with ethrex/crates/l2 as the current directory, run the following command:

COMPILE_CONTRACTS=true \
ETHREX_L2_ALIGNED=true \
ETHREX_DEPLOYER_ALIGNED_AGGREGATOR_ADDRESS=<ALIGNED_AGGREGATOR_ADDRESS> \
ETHREX_L2_SP1=true \
ETHREX_DEPLOYER_RANDOMIZE_CONTRACT_DEPLOYMENT=true \
cargo run --release --features l2,l2-sql --manifest-path "../../Cargo.toml" -- l2 deploy \
        --eth-rpc-url <ETH_RPC_URL> \
        --private-key <YOUR_PRIVATE_KEY> \
        --on-chain-proposer-owner <ON_CHAIN_PROPOSER_OWNER>  \
        --bridge-owner <BRIDGE_OWNER_ADDRESS>  \
        --genesis-l2-path "../../fixtures/genesis/l2.json" \
        --proof-sender.l1-address <PROOF_SENDER_L1_ADDRESS>

note

This command requires the COMPILE_CONTRACTS env variable to be set, as the deployer needs the SDK to embed the proxy bytecode. In this step we are initiallizing the OnChainProposer contract with the ALIGNED_PROOF_AGGREGATOR_SERVICE_ADDRESS and skipping the rest of verifiers, you can find the address for the aligned aggegator service here Save the addresses of the deployed proxy contracts, as you will need them to run the L2 node. Accounts for the deployer, on-chain proposer owner, bridge owner, and proof sender must have funds. Add --bridge-owner-pk <PRIVATE_KEY> if you want the deployer to immediately call acceptOwnership on behalf of that owner; otherwise, they can accept later.

3. Deposit funds to the `AlignedBatcherPaymentService` contract from the proof sender

aligned deposit-to-batcher \
--network <NETWORK> \
--private_key <PROOF_SENDER_PRIVATE_KEY> \
--rpc_url <RPC_URL> \
--amount <DEPOSIT_AMOUNT>

important

Using the Aligned CLI

4. Running a node

In a console with ethrex/crates/l2 as the current directory, run the following command:

cargo run --release --manifest-path ../../Cargo.toml --bin ethrex --features "l2,sp1" -- \
	l2 \
	--watcher.block-delay 0 \
	--network "../../fixtures/genesis/l2.json" \
	--l1.bridge-address <BRIDGE_ADDRESS> \
	--l1.on-chain-proposer-address <ON_CHAIN_PROPOSER_ADDRESS> \
	--eth.rpc-url <ETH_RPC_URL> \
	--aligned \
    --aligned-network <ALIGNED_NETWORK>  \
    --block-producer.coinbase-address <COINBASE_ADDRESS>  \
    --committer.l1-private-key <COMMITER_PRIVATE_KEY>  \
    --proof-coordinator.l1-private-key <PROOF_COORDINATOR_PRIVATE_KEY>  \
    --aligned.beacon-url <ALIGNED_BEACON_URL> \
	--datadir ethrex_l2 \
    --no-monitor

Both commiter and proof coordinator should have funds.

Aligned params explanation:

--aligned: Enables aligned mode, enforcing all required parameters.
--aligned.beacon-url: URL of the beacon client used by the Aligned SDK to verify proof aggregations, it has to support /eth/v1/beacon/blobs
--aligned-network: Parameter used by the Aligned SDK.

If you can't find a beacon client URL which supports that endpoint, you can run your own with lighthouse and ethrex:

Create secrets directory and jwt secret

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

lighthouse bn --network <NETWORK> --execution-endpoint http://localhost:8551 --execution-jwt <PATH_TO_SECRET> --checkpoint-sync-url <CHECKPOINT_URL> --http --purge-db-force --supernode

cargo run --release --manifest-path ../../Cargo.toml --bin ethrex -- --authrpc.jwtsecret <PATH_TO_SECRET> --network <NETWORK>

4. Running the Prover

In a console with ethrex/crates/l2 as the current directory, run the following command:

make init-prover-<sp1/risc0> GPU=true # The GPU parameter is optional

Then you should wait until aligned aggregates your proof

How to run (local devnet)

important

This guide assumes you have already generated the prover ELF/VK. See: Generate the prover ELF/VK

Set Up the Aligned Environment

Clone the Aligned repository and checkout the currently supported release:

git clone git@github.com:yetanotherco/aligned_layer.git
cd aligned_layer
git checkout tags/v0.19.1

Edit the aligned_layer/network_params.rs file to send some funds to the committer and integration_test addresses:

prefunded_accounts: '{
    "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266": { "balance": "100000000000000ETH" },
    "0x70997970C51812dc3A010C7d01b50e0d17dc79C8": { "balance": "100000000000000ETH" },

    ...
    "0xa0Ee7A142d267C1f36714E4a8F75612F20a79720": { "balance": "100000000000000ETH" },
+   "0x4417092B70a3E5f10Dc504d0947DD256B965fc62": { "balance": "100000000000000ETH" },
+   "0x3d1e15a1a55578f7c920884a9943b3b35d0d885b": { "balance": "100000000000000ETH" },
     }'

You can also decrease the seconds per slot in aligned_layer/network_params.rs:

# Number of seconds per slot on the Beacon chain
  seconds_per_slot: 4

Change ethereum-genesis-generator to 5.0.8

ethereum_genesis_generator_params:
  # The image to use for ethereum genesis generator
  image: ethpandaops/ethereum-genesis-generator:5.0.8

Make sure you have the latest version of kurtosis installed and start the ethereum-package:

cd aligned_layer
make ethereum_package_start

If you need to stop it run make ethereum_package_rm

Start the batcher:

First, increase the max_proof_size in aligned_layer/config-files/config-batcher-ethereum-package.yaml max_proof_size: 104857600 # 100 MiB for example.

cd aligned_layer
make batcher_start_ethereum_package

This is the Aligned component that receives the proofs before sending them in a batch.

warning

If you see the following error in the batcher: [ERROR aligned_batcher] Unexpected error: Space limit exceeded: Message too long: 16940713 > 16777216 modify the file aligned_layer/batcher/aligned-batcher/src/lib.rs at line 433 with the following code:

use tokio_tungstenite::tungstenite::protocol::WebSocketConfig;

let mut stream_config = WebSocketConfig::default();
stream_config.max_frame_size = None;

let ws_stream_future =
    tokio_tungstenite::accept_async_with_config(raw_stream, Some(stream_config));

Initialize L2 node

In another terminal let's deploy the L1 contracts, specifying the AlignedProofAggregatorService contract address, and adding the required prover types (Risc0 or SP1):

cd ethrex/crates/l2
COMPILE_CONTRACTS=true \
ETHREX_L2_ALIGNED=true \
ETHREX_DEPLOYER_ALIGNED_AGGREGATOR_ADDRESS=0xcbEAF3BDe82155F56486Fb5a1072cb8baAf547cc \
ETHREX_L2_SP1=true \
ETHREX_L2_RISC0=true \
make deploy-l1

Both ETHREX_L2_SP1 and ETHREX_L2_RISC0 are optional

note

This command requires the COMPILE_CONTRACTS env variable to be set, as the deployer needs the SDK to embed the proxy bytecode.

You will see that some deposits fail with the following error:

2025-10-13T19:44:51.600047Z ERROR ethrex::l2::deployer: Failed to deposit address=0x0002869e27c6faee08cca6b765a726e7a076ee0f value_to_deposit=0
2025-10-13T19:44:51.600114Z  WARN ethrex::l2::deployer: Failed to make deposits: Deployer EthClient error: eth_sendRawTransaction request error: insufficient funds for gas * price + value: have 0 want 249957710190063

This is because not all the accounts are pre-funded from the genesis.

Send some funds to the Aligned batcher payment service contract from the proof sender:

cd aligned_layer/crates/cli
cargo run deposit-to-batcher \
--network devnet \
--private_key 0x39725efee3fb28614de3bacaffe4cc4bd8c436257e2c8bb887c4b5c4be45e76d \
--amount 1ether

Start our l2 node:

cd ethrex/crates/l2
ETHREX_ALIGNED_MODE=true \
ETHREX_ALIGNED_BEACON_URL=http://127.0.0.1:58801 \
ETHREX_ALIGNED_NETWORK=devnet \
ETHREX_PROOF_COORDINATOR_DEV_MODE=false \
SP1=true \
RISC0=true \
make init-l2

Suggestion: When running the integration test, consider increasing the --committer.commit-time to 2 minutes. This helps avoid having to aggregate the proofs twice. You can do this by adding the following flag to the init-l2-no-metrics target:

--committer.commit-time 120000

Start prover(s) in different terminals:

cd ethrex/crates/l2
make init-prover-<sp1/risc0> GPU=true # The GPU flag is optional

Aggregate proofs:

After some time, you will see that the l1_proof_verifier is waiting for Aligned to aggregate the proofs. You can trigger an aggregation (for either sp1 or risc0 proofs) by running:

cd aligned_layer
make proof_aggregator_start AGGREGATOR=<sp1/risc0>

# or with gpu acceleration
make proof_aggregator_start_gpu AGGREGATOR=<sp1/risc0>

If successful, the l1_proof_verifier will print the following logs:

INFO ethrex_l2::sequencer::l1_proof_verifier: Proof for batch 1 aggregated by Aligned with commitment 0xa9a0da5a70098b00f97d96cee43867c7aa8f5812ca5388da7378454580af2fb7 and Merkle root 0xa9a0da5a70098b00f97d96cee43867c7aa8f5812ca5388da7378454580af2fb7
INFO ethrex_l2::sequencer::l1_proof_verifier: Batches verified in OnChainProposer, with transaction hash 0x731d27d81b2e0f1bfc0f124fb2dd3f1a67110b7b69473cacb6a61dea95e63321

Behavioral Differences in Aligned Mode

Prover

Generates Compressed proofs instead of Groth16.
Required because Aligned currently only accepts SP1 compressed proofs.

Proof Sender

Sends proofs to the Aligned Batcher instead of the OnChainProposer contract.
Tracks the last proof sent using the rollup store.

Proof Sender Aligned Mode

Proof Verifier

Spawned only in Aligned mode.
Monitors whether the next proof has been aggregated by Aligned.
Once verified, collects all already aggregated proofs and triggers the advancement of the OnChainProposer contract by sending a single transaction.

Aligned Mode Proof Verifier

OnChainProposer

Uses verifyBatchesAligned() instead of verifyBatch().
Receives an array of proofs to verify.
Delegates proof verification to the AlignedProofAggregatorService contract.

TDX execution module

This document has documentation related to proving ethrex blocks using TDX.

Usage

note

Running the following without an L2 running will continuously throw the error: Error sending quote: Failed to get ProverSetupAck: Connection refused (os error 111). If you want to run this in a proper setup go to the Running section.
The quote generator runs in a QEMU, to quit it press CTRL+A X.

On a machine with TDX support with the required setup go to quote-gen and run

make run

What is TDX?

TDX is an Intel technology implementing a Trusted Execution Environment. Such an environment allows verifying certain code was executed without being tampered with or observed.

These verifications (attestations) are known as "quotes" and contain signatures verifying the attestation was generated by a genuine processor, the measurements at the time, and a user-provided piece of data binding the proof.

The measurements are saved to four Run Time Measurement Registers (RTMR), with each RTMR respresenting a boot stage. This is analogous to how PCRs work.

Usage considerations

Do not hardcode quote verification parameters as they might change.

It's easy to silently overlook non-verified areas such as accidentally leaving login enabled, or not verifying the integrity of the state.

Boot sequence

Firmware (OVMF here) is loaded (and hashed into RTMR[0])
UKI is loaded (and hashed into a RTMR)
kernel and initrd are extracted from the UKI and executed
root partition is verified using the roothash= value provided on the kernel cmdline and the hash partition with the dm-verity merkle tree
root partition is mounted read-only
(WIP) systemd executes the payload

Image build components

For reproducibility of images and hypervisor runtime we use Nix.

hypervisor.nix

This builds the modified (with patches for TDX support) qemu, and TDX-specific VBIOS (OVMF) and exports a script to run a given image (the parameters, specifically added devices, affect the measurements).

service.nix

This contains the quote-gen service. It's hash changes every time a non-gitignored file changes.

image.nix

Exports an image that uses UKI and dm-verity to generate an image where changing any component changes the hash of the bootloader (the UKI image), which is measured by the BIOS.

Running

You can enable the prover by setting ETHREX_L2_TDX=true.

For development purposes, you can use the flag ETHREX_TDX_DEV_MODE=true to disable quote verification. This allows you to run the quote generator even without having TDX-capable hardware.

Ensure the proof coordinator is reachable at 172.17.0.1. You can bring up the network by first starting the L2 components:

// cd crates/l2
make init ETHREX_L2_TDX=true PROOF_COORDINATOR_ADDRESS=0.0.0.0

And in another terminal, running the VM:

// cd crates/l2
make -C tee/quote-gen run

Troubleshooting

`unshare: write failed /proc/self/uid_map: Operation not permitted`

If you get this error when building the image, it's probably because your OS has unprivileged userns restricted by default. You can undo this by running the following commands as root, or running the build as root while disabling sandboxing.

sysctl kernel.unprivileged_userns_apparmor_policy=0
sysctl kernel.apparmor_restrict_unprivileged_userns=0

RTMR/MRTD mismatch

If any code or dependencies changed, the measurements will change.

To obtain the new measurements, first you obtain the quote by running the prover (you don't need to have the l2 running). It's output will contain Sending quote <very long hex string>.

This usually causes a RTMR1 mismatch. The easiest way to obtain the new RTMR values is by looking at the printed quote for the next 96 bytes after the RTMR0, corresponding to RTMR1||RTMR2 (48 bytes each).

More generally, you can generate a report with DCAP.verifyAndAttestOnChain(quote) which validates and extracts the report.

Look at bytes 341..485 of the output for RTMRs and bytes 149..197 for the MRTD.

For example, the file quote.example contains a quote, which can be turned into the following report:

00048100000000b0c06f000000060103000000000000000000000000005b38e33a6487958b72c3c12a938eaa5e3fd4510c51aeeab58c7d5ecee41d7c436489d6c8e4f92f160b7cad34207b00c100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000000000e702060000000000

91eb2b44d141d4ece09f0c75c2c53d247a3c68edd7fafe8a3520c942a604a407de03ae6dc5f87f27428b2538873118b7 # MRTD

000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

4f3d617a1c89bd9a89ea146c15b04383b7db7318f41a851802bba8eace5a6cf71050e65f65fd50176e4f006764a42643 # RTMR0
53827a034d1e4c7f13fd2a12aee4497e7097f15a04794553e12fe73e2ffb8bd57585e771951115a13ec4d7e6bc193038 # RTMR1
2ca1a728ff13c36195ad95e8f725bf00d7f9c5d6ed730fb8f50cccad692ab81aefc83d594819375649be934022573528 # RTMR2
000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 # RTMR3

39618efd10b14136ab416d6acfff8e36b23533a90000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

Interacting with the L2

This section explains how to interact with your L2 rollup built with ethrex. Here you'll find guides for:

Depositing and withdrawing assets
Connecting wallets like MetaMask
Deploying smart contracts
Maintaining and operating the sequencer

Use these guides to perform common actions and manage your L2 network.

Deposit assets into the L2

To transfer ETH from Ethereum L1 to your L2 account, you need to use the CommonBridge as explained in this section.

Prerequisites for L1 deposit

An L1 account with sufficient ETH balance, for developing purposes you can use:
- Address: 0x8943545177806ed17b9f23f0a21ee5948ecaa776
- Private Key: 0xbcdf20249abf0ed6d944c0288fad489e33f66b3960d9e6229c1cd214ed3bbe31
The address of the deployed CommonBridge contract.
An Ethereum utility tool like Rex

Making a deposit

Making a deposit in the Bridge, using Rex, is as simple as:

# Format: rex l2 deposit <AMOUNT> <PRIVATE_KEY> <BRIDGE_ADDRESS> [L1_RPC_URL]
rex l2 deposit 50000000 0xbcdf20249abf0ed6d944c0288fad489e33f66b3960d9e6229c1cd214ed3bbe31 0x65dd6dc5df74b7e08e92c910122f91d7b2d5184f

Verifying the updated L2 balance

Once the deposit is made you can verify the balance has increase with:

# Format: rex l2 balance <ADDRESS> [RPC_URL]
rex l2 balance 0x8943545177806ed17b9f23f0a21ee5948ecaa776

For more information on what you can do with the CommonBridge see Ethrex L2 contracts.

Withdraw assets from the L2

This section explains how to withdraw funds from the L2 through the native bridge.

Prerequisites for L2 withdrawal

An L2 account with sufficient ETH balance, for developing purpose you can use:
- Address: 0x8943545177806ed17b9f23f0a21ee5948ecaa776
- Private Key: 0xbcdf20249abf0ed6d944c0288fad489e33f66b3960d9e6229c1cd214ed3bbe31
The address of the deployed CommonBridge L2 contract (note here that we are calling the L2 contract instead of the L1 as in the deposit case). If not specified, You can use:
- CommonBridge L2: 0x000000000000000000000000000000000000ffff
An Ethereum utility tool like Rex.

Making a withdrawal

Using Rex, we simply run the rex l2 withdraw command, which uses the default CommonBridge address.

# Format: rex l2 withdraw <AMOUNT> <PRIVATE_KEY> [RPC_URL]
rex l2 withdraw 5000 0xbcdf20249abf0ed6d944c0288fad489e33f66b3960d9e6229c1cd214ed3bbe31

If the withdrawal is successful, the hash will be printed like this:

Withdrawal sent: <L2_WITHDRAWAL_TX_HASH>
...

Claiming the withdrawal

After making a withdrawal, it has to be claimed in the L1, through the L1 CommonBridge contract. For that, we can use the Rex command rex l2 claim-withdraw, with the tx hash obtained in the previous step. But first, it is necessary to wait for the block that includes the withdraw to be verified.

# Format: rex l2 claim-withdraw <L2_WITHDRAWAL_TX_HASH> <PRIVATE_KEY> <BRIDGE_ADDRESS> [L1_RPC_URL] [RPC_URL]
rex l2 claim-withdraw <L2_WITHDRAWAL_TX_HASH> 0xbcdf20249abf0ed6d944c0288fad489e33f66b3960d9e6229c1cd214ed3bbe31 0x65dd6dc5df74b7e08e92c910122f91d7b2d5184f

Verifying the withdrawal

Once the withdrawal is made you can verify the balance has decreased in the L2 with:

rex l2 balance 0x8943545177806ed17b9f23f0a21ee5948ecaa776

And also increased in the L1:

rex balance 0x8943545177806ed17b9f23f0a21ee5948ecaa776

Connect a Wallet

You can connect your L2 network to MetaMask to interact with your rollup using a familiar wallet interface.

Add Your L2 Network to MetaMask

Open MetaMask and click the network dropdown.
Select "Add custom network".
Enter your L2 network details:
- Network Name: (choose any name, e.g. "My L2 Rollup")
- RPC URL: http://localhost:1729 (or your L2 node's RPC endpoint)
- Chain ID: (use the chain ID from your L2 genesis config)
- Currency Symbol: (e.g. ETH)
- Block Explorer URL: (optional, can be left blank)
Save the network.

You can now use MetaMask to send transactions and interact with contracts on your L2.

Tip: If you are running the L2 node on a remote server, replace localhost with the server's IP or domain.

Deploy a Contract to L2

You can deploy smart contracts to your L2 using rex, a simple CLI tool for interacting with Ethereum-compatible networks.

1. Generate the Contract Bytecode

First, compile your Solidity contract to get the deployment bytecode. You can use solc for this:

solc --bin MyContract.sol -o out/

The bytecode will be in out/MyContract.bin

2. Deploy with rex

Use the following command to deploy your contract:

rex deploy --rpc-url http://localhost:1729 <BYTECODE> 0 <PRIVATE_KEY>

Replace <BYTECODE> with the hex string from your compiled contract (e.g., contents of MyContract.bin)
Replace <PRIVATE_KEY> with your wallet's private key. It must have funds in L2
Adjust the --rpc-url if your L2 node is running elsewhere

For more details and advanced usage, see the rex repository.

Fundamentals

In L2 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 chain. 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 chain 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.

Ethrex L2 documentation

For general documentation, see:

Architecture overview for a high-level view of the ethrex L2 stack.
Smart contracts has information on L1 and L2 smart contracts.
Based sequencing contains ethrex's roadmap for becoming based.

State diffs

warning

Data availability through state diffs has been deprecated in #5135.
See the Transition to RLP encoded blocks section here for more details.

This architecture was inspired by MatterLabs' ZKsync pubdata architecture.

To provide data availability for our blockchain, we need to publish enough information on every commit transaction to be able to reconstruct the entire state of the L2 from the beginning by querying the L1.

The data needed is:

The nonce and balance of every EOA.
The nonce, balance, and storage of every contract account. Note that storage here is a mapping (U256 → U256), so there are a lot of values inside it.
The bytecode of every contract deployed on the chain.
All withdrawal Logs.

After executing a batch of L2 blocks, the EVM will return the following data:

A list of every storage slot modified in the batch, with their previous and next values. A storage slot is a mapping (address, slot) -> value. Note that, in a batch, there could be repeated writes to the same slot. In that case, we keep only the latest write; all the others are discarded since they are not needed for state reconstruction.
The bytecode of every newly deployed contract. Every contract deployed is then a pair (address, bytecode).
A list of withdrawal logs (as explained in milestone 1 we already collect these and publish a merkle root of their values as calldata, but we still need to send them as the state diff).
A list of triples (address, nonce_increase, balance) for every modified account. The nonce_increase is a value that says by how much the nonce of the account was increased in the batch (this could be more than one as there can be multiple transactions for the account in the batch). The balance is just the new balance value for the account.

The full state diff sent for each batch will then be a sequence of bytes encoded as follows. We use the notation un for a sequence of n bits, so u16 is a 16-bit sequence and u96 a 96-bit one, we don't really care about signedness here; if we don't specify it, the value is of variable length and a field before it specifies it.

The first byte is a u8: the version header. For now it should always be one, but we reserve it for future changes to the encoding/compression format.
Next come the block header info of the last block in the batch:
- The tx_root, receipts_root and parent_hash are u256 values.
- The gas_limit, gas_used, timestamp, block_number and base_fee_per_gas are u64 values.
Next the ModifiedAccounts list. The first two bytes (u16) are the amount of element it has, followed by its entries. Each entry correspond to an altered address and has the form:
- The first byte is the type of the modification. The value is a u8, constrained to the range [1; 23], computed by adding the following values:
  - 1 if the balance of the EOA/contract was modified.
  - 2 if the nonce of the EOA/contract was modified.
  - 4 if the storage of the contract was modified.
  - 8 if the contract was created and the bytecode is previously unknown.
  - 16 if the contract was created and the bytecode is previously known.
- The next 20 bytes, a u160, is the address of the modified account.
- If the balance was modified (i.e. type & 0x01 == 1), the next 32 bytes, a u256, is the new balance of the account.
- If the nonce was modified (i.e. type & 0x02 == 2), the next 2 bytes, a u16, is the increase in the nonce.
- If the storage was modified (i.e. type & 0x04 == 4), the next 2 bytes, a u16, is the number of storage slots modified. Then come the sequence of (key_u256, new_value_u256) key value pairs with the modified slots.
- If the contract was created and the bytecode is previously unknown (i.e. type & 0x08 == 8), the next 2 bytes, a u16, is the length of the bytecode in bytes. Then come the bytecode itself.
- If the contract was created and the bytecode is previously known (i.e. type & 0x10 == 16), the next 32 bytes, a u256, is the hash of the bytecode of the contract.
- Note that values 8 and 16 are mutually exclusive, and if type is greater or equal to 4, then the address is a contract. Each address can only appear once in the list.
Next the WithdrawalLogs field:
- First two bytes are the number of entries, then come the tuples (to_u160, amount_u256, tx_hash_u256).
Next the PrivilegedTransactionLogs field:
- First two bytes are the number of entries, then come the tuples (to_u160, value_u256).
In case of the only changes on an account are produced by withdrawals, the ModifiedAccounts for that address field must be omitted. In this case, the state diff can be computed by incrementing the nonce in one unit and subtracting the amount from the balance.

To recap, using || for byte concatenation and [] for optional parameters, the full encoding for state diffs is:

version_header_u8 ||
// Last Block Header info
tx_root_u256 || receipts_root_u256 || parent_hash_u256 ||
gas_limit_u64 || gas_used_u64 || timestamp_u64 ||
block_number_u64 || base_fee_per_gas_u64
// Modified Accounts
number_of_modified_accounts_u16 ||
(
  type_u8 || address_u160 || [balance_u256] || [nonce_increase_u16] ||
  [number_of_modified_storage_slots_u16 || (key_u256 || value_u256)... ] ||
  [bytecode_len_u16 || bytecode ...] ||
  [code_hash_u256]
)...
// Withdraw Logs
number_of_withdraw_logs_u16 ||
(to_u160 || amount_u256 || tx_hash_u256) ...
// Privileged Transactions Logs
number_of_privileged_transaction_logs_u16 ||
(to_u160 || value_u256) ...

The sequencer will then make a commitment to this encoded state diff (explained in the EIP 4844 section how this is done) and send on the commit transaction:

Through calldata, the state diff commitment (which is part of the public input to the proof).
Through the blob, the encoded state diff.

note

As the blob is encoded as 4096 BLS12-381 field elements, every 32-bytes chunk cannot be greater than the subgroup r size: 0x73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001. i.e., the most significant byte must be less than 0x73. To avoid conflicts, we insert a 0x00 byte before every 31-bytes chunk to ensure this condition is met.

Comparative Analysis: Transaction Volume in Blobs Using State Diffs and Transaction Lists

The following are results from measurements conducted to understand the efficiency of blob utilization in an ethrex L2 network through the simulation of different scenarios with varying transaction complexities (e.g., ETH transfers, ERC20 transfers, and other complex smart contract interactions) and data encoding strategies, with the final goal of estimating the approximate number of transactions that can be packed into a single blob using state diffs versus full transaction lists, thereby optimizing calldata costs and achieving greater scalability.

Measurements (Amount of transactions per batch)

ETH Transfers

Blob Payload	Batch 2	Batch 3	Batch 4	Batch 5	Batch 6	Batch 7	Batch 8	Batch 9	Batch 10	Batch 11
State Diff	2373	2134	2367	2141	2191	2370	2309	2361	2375	2367
Block List	913	871	886	935	1019	994	1002	1011	1012	1015

ERC20 Transfers

Blob Payload	Batch 2	Batch 3	Batch 4	Batch 5	Batch 6	Batch 7	Batch 8	Batch 9	Batch 10	Batch 11
State Diff	1942	1897	1890	1900	1915	1873	1791	1773	1867	1858
Block List	655	661	638	638	645	644	615	530	532	532

Summary

Blob Payload	Avg. ETH Transfers per Batch	Avg. ERC20 Transfers per Batch
State Diff	2298	1870
Block List	965	609

Conclusion

Sending block lists in blobs instead of state diffs decreases the number of transactions that can fit in a single blob by approximately 2x for ETH transfers and 3x for ERC20 transfers.

How this measurements were done

Prerequisites

Fresh cloned ethrex repository
The spammer and measurer code provided in the appendix set up for running (you can create a new cargo project and copy the code there)

Steps

1. Run an L2 ethrex:

For running the measurements, we need to run an ethrex L2 node. For doing that, change your current directory to ethrex/crates/l2 in your fresh-cloned ethrex and run the following in a terminal:

ETHREX_COMMITTER_COMMIT_TIME=120000 MEMPOOL_MAX_SIZE=1000000 make init-l2-dev

This will set up and run an ethrex L2 node in dev mode with a mempool size big-enough to be able to handle the spammer transactions. And after this you should see the ethrex L2 monitor running.

2. Run the desired transactions spammer

important

Wait a few seconds after running the L2 node to make sure it's fully up and running before starting the spammer, and to ensure that the rich account used by the spammer has funds.

In another terminal, change your current directory to the spammer code you want to run (either ETH or ERC20) and run:

cargo run

It's ok not to see any logs or prints as output, since the spammer code doesn't print anything.

If you go back to the terminal where the L2 node is running, you should start seeing the following:

The mempool table growing in size as transactions are being sent to the L2 node.
In the L2 Blocks table, new blocks with #Txs greater than 0 being created as the spammer transactions are included in blocks.
Every 2 minutes (or the time you set in ETHREX_COMMITTER_COMMIT_TIME), new batches being created in the L2 Batches table.

3. Run the measurer

important

Wait until enough batches are created before running the measurer.
Ignore the results of the first 2/3 batches, since they contain other transactions created during the L2 node initialization.

In another terminal, change your current directory to the measurer code and run:

cargo run

This will start printing the total number of transactions included in each batch until the last committed one.

note

The measurer will query batches starting from batch 1 and will continue indefinitely until it fails to find a batch (e.g. because the L2 node hasn't created it yet), so it is ok to see an error at the end of the output once the measurer reaches a batch that hasn't been created yet.

Appendix

ETH Transactions Spammer

note

This is using ethrex v6.0.0

`main.rs`

use ethrex_common::{
    Address, U256,
    types::{EIP1559Transaction, Transaction, TxKind},
};
use ethrex_l2_rpc::signer::{LocalSigner, Signable, Signer};
use ethrex_l2_sdk::send_generic_transaction;
use ethrex_rpc::EthClient;
use tokio::time::sleep;
use url::Url;

#[tokio::main]
async fn main() {
    let chain_id = 65536999;
    let senders = vec![
        "7a738a3a8ee9cdbb5ee8dfc1fc5d97847eaba4d31fd94f89e57880f8901fa029",
        "8cfe380955165dd01f4e33a3c68f4e08881f238fbbea71a2ab407f4a3759705b",
        "5bb463c0e64039550de4f95b873397b36d76b2f1af62454bb02cf6024d1ea703",
        "3c0924743b33b5f06b056bed8170924ca12b0d52671fb85de1bb391201709aaf",
        "6aeeda1e7eda6d618de89496fce01fb6ec685c38f1c5fccaa129ec339d33ff87",
    ]
    .iter()
    .map(|s| Signer::Local(LocalSigner::new(s.parse().expect("invalid private key"))))
    .collect::<Vec<Signer>>();
    let eth_client: EthClient =
        EthClient::new(Url::parse("http://localhost:1729").expect("Invalid URL"))
            .expect("Failed to create EthClient");
    let mut nonce = 0;
    loop {
        for sender in senders.clone() {
            let signed_tx = generate_signed_transaction(nonce, chain_id, &sender).await;
            send_generic_transaction(&eth_client, signed_tx.into(), &sender)
                .await
                .expect("Failed to send transaction");
            sleep(std::time::Duration::from_millis(10)).await;
        }
        nonce += 1;
    }
}

async fn generate_signed_transaction(nonce: u64, chain_id: u64, signer: &Signer) -> Transaction {
    Transaction::EIP1559Transaction(EIP1559Transaction {
        nonce,
        value: U256::one(),
        gas_limit: 250000,
        max_fee_per_gas: u64::MAX,
        max_priority_fee_per_gas: 10,
        chain_id,
        to: TxKind::Call(Address::random()),
        ..Default::default()
    })
    .sign(&signer)
    .await
    .expect("failed to sign transaction")
}

`Cargo.toml`

[package]
name = "tx_spammer"
version = "0.1.0"
edition = "2024"

[dependencies]
ethrex-sdk = { git = "https://github.com/lambdaclass/ethrex.git", tag = "v6.0.0" }
ethrex-common = { git = "https://github.com/lambdaclass/ethrex.git", tag = "v6.0.0" }
ethrex-l2-rpc = { git = "https://github.com/lambdaclass/ethrex.git", tag = "v6.0.0" }
ethrex-rpc = { git = "https://github.com/lambdaclass/ethrex.git", tag = "v6.0.0" }

tokio = { version = "1", features = ["full"] }
url = "2"
hex = "0.4"

Measurer

A simple program that queries the L2 node for batches and blocks, counting the number of transactions in each block, and summing them up per batch.

`main.rs`

use reqwest::Client;
use serde_json::{Value, json};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut batch = 1;

    loop {
        let (first, last) = fetch_batch(batch).await;
        let mut txs = 0u64;
        for number in first as u64..=last as u64 {
            txs += fetch_block(number).await;
        }
        println!("Total transactions in batch {}: {}", batch, txs);

        batch += 1;
    }
}

async fn fetch_batch(number: u64) -> (i64, i64) {
    // Create the JSON body equivalent to the --data in curl
    let body = json!({
        "method": "ethrex_getBatchByNumber",
        "params": [format!("0x{:x}", number), false],
        "id": 1,
        "jsonrpc": "2.0"
    });

    // Create a blocking HTTP client
    let client = Client::new();

    // Send the POST request
    let response = client
        .post("http://localhost:1729")
        .header("Content-Type", "application/json")
        .json(&body)
        .send()
        .await
        .expect("Failed to send request")
        .json::<Value>()
        .await
        .unwrap();

    let result = &response["result"];
    let first_block = &result["first_block"].as_i64().unwrap();
    let last_block = &result["last_block"].as_i64().unwrap();
    (*first_block, *last_block)
}

async fn fetch_block(number: u64) -> u64 {
    // Create the JSON body equivalent to the --data in curl
    let body = json!({
        "method": "eth_getBlockByNumber",
        "params": [format!("0x{:x}", number), false],
        "id": 1,
        "jsonrpc": "2.0"
    });

    // Create a blocking HTTP client
    let client = Client::new();

    // Send the POST request
    let response = client
        .post("http://localhost:1729")
        .header("Content-Type", "application/json")
        .json(&body)
        .send()
        .await
        .expect("Failed to send request")
        .json::<Value>()
        .await
        .unwrap();

    let result = &response["result"];
    let transactions = &result["transactions"];
    transactions.as_array().unwrap().len() as u64
}

`Cargo.toml`

[package]
name = "measurer"
version = "0.1.0"
edition = "2024"

[dependencies]
reqwest = { version = "0.11", features = ["json"] }
serde_json = "1.0"
tokio = { version = "1", features = ["full"] }

ERC20 Transactions Spammer

`main.rs`

use ethrex_blockchain::constants::TX_GAS_COST;
use ethrex_common::{
    Address, U256,
    types::{EIP1559Transaction, GenericTransaction, Transaction, TxKind, TxType},
};
use ethrex_l2_rpc::signer::{LocalSigner, Signable, Signer};
use ethrex_l2_sdk::{
    build_generic_tx, calldata::encode_calldata, create_deploy, send_generic_transaction,
    wait_for_transaction_receipt,
};
use ethrex_rpc::{EthClient, clients::Overrides};
use tokio::time::sleep;
use url::Url;

// ERC20 compiled artifact generated from this tutorial:
// https://medium.com/@kaishinaw/erc20-using-hardhat-a-comprehensive-guide-3211efba98d4
// If you want to modify the behaviour of the contract, edit the ERC20.sol file,
// and compile it with solc.
const ERC20: &str = include_str!("./TestToken.bin").trim_ascii();

#[tokio::main]
async fn main() {
    let chain_id = 65536999;
    let signer = Signer::Local(LocalSigner::new(
        "39725efee3fb28614de3bacaffe4cc4bd8c436257e2c8bb887c4b5c4be45e76d"
            .parse()
            .expect("invalid private key"),
    ));
    let eth_client: EthClient =
        EthClient::new(Url::parse("http://localhost:1729").expect("Invalid URL"))
            .expect("Failed to create EthClient");
    let contract_address = erc20_deploy(eth_client.clone(), &signer)
        .await
        .expect("Failed to deploy ERC20 contract");

    let senders = vec![
        "7a738a3a8ee9cdbb5ee8dfc1fc5d97847eaba4d31fd94f89e57880f8901fa029",
        "8cfe380955165dd01f4e33a3c68f4e08881f238fbbea71a2ab407f4a3759705b",
        "5bb463c0e64039550de4f95b873397b36d76b2f1af62454bb02cf6024d1ea703",
        "3c0924743b33b5f06b056bed8170924ca12b0d52671fb85de1bb391201709aaf",
        "6aeeda1e7eda6d618de89496fce01fb6ec685c38f1c5fccaa129ec339d33ff87",
    ]
    .iter()
    .map(|s| Signer::Local(LocalSigner::new(s.parse().expect("invalid private key"))))
    .collect::<Vec<Signer>>();
    claim_erc20_balances(contract_address, eth_client.clone(), senders.clone())
        .await
        .expect("Failed to claim ERC20 balances");
    let mut nonce = 1;
    loop {
        for sender in senders.clone() {
            let signed_tx =
                generate_erc20_transaction(nonce, chain_id, &sender, &eth_client, contract_address)
                    .await;
            send_generic_transaction(&eth_client, signed_tx.into(), &sender)
                .await
                .expect("Failed to send transaction");
            println!(
                "Sent transaction with nonce {} for address {}",
                nonce,
                sender.address()
            );
            sleep(std::time::Duration::from_millis(10)).await;
        }
        nonce += 1;
    }
}

// Given an account vector and the erc20 contract address, claim balance for all accounts.
async fn claim_erc20_balances(
    contract_address: Address,
    client: EthClient,
    accounts: Vec<Signer>,
) -> eyre::Result<()> {
    for account in accounts {
        let claim_balance_calldata = encode_calldata("freeMint()", &[]).unwrap();

        let claim_tx = build_generic_tx(
            &client,
            TxType::EIP1559,
            contract_address,
            account.address(),
            claim_balance_calldata.into(),
            Default::default(),
        )
        .await
        .unwrap();
        let tx_hash = send_generic_transaction(&client, claim_tx, &account)
            .await
            .unwrap();
        wait_for_transaction_receipt(tx_hash, &client, 1000)
            .await
            .unwrap();
    }

    Ok(())
}

async fn deploy_contract(
    client: EthClient,
    deployer: &Signer,
    contract: Vec<u8>,
) -> eyre::Result<Address> {
    let (_, contract_address) =
        create_deploy(&client, deployer, contract.into(), Overrides::default()).await?;

    eyre::Ok(contract_address)
}

async fn erc20_deploy(client: EthClient, deployer: &Signer) -> eyre::Result<Address> {
    let erc20_bytecode = hex::decode(ERC20).expect("Failed to decode ERC20 bytecode");
    deploy_contract(client, deployer, erc20_bytecode).await
}

async fn generate_erc20_transaction(
    nonce: u64,
    chain_id: u64,
    signer: &Signer,
    client: &EthClient,
    contract_address: Address,
) -> GenericTransaction {
    let send_calldata = encode_calldata(
        "transfer(address,uint256)",
        &[
            ethrex_l2_common::calldata::Value::Address(Address::random()),
            ethrex_l2_common::calldata::Value::Uint(U256::one()),
        ],
    )
    .unwrap();

    let tx = build_generic_tx(
        client,
        TxType::EIP1559,
        contract_address,
        signer.address(),
        send_calldata.into(),
        Overrides {
            chain_id: Some(chain_id),
            value: None,
            nonce: Some(nonce),
            max_fee_per_gas: Some(i64::MAX as u64),
            max_priority_fee_per_gas: Some(10_u64),
            gas_limit: Some(TX_GAS_COST * 100),
            ..Default::default()
        },
    )
    .await
    .unwrap();

    tx
}

`Cargo.toml`

[package]
name = "tx_spammer"
version = "0.1.0"
edition = "2024"

[dependencies]
ethrex-sdk = { git = "https://github.com/lambdaclass/ethrex.git", tag = "v6.0.0" }
ethrex-common = { git = "https://github.com/lambdaclass/ethrex.git", tag = "v6.0.0" }
ethrex-l2-rpc = { git = "https://github.com/lambdaclass/ethrex.git", tag = "v6.0.0" }
ethrex-rpc = { git = "https://github.com/lambdaclass/ethrex.git", tag = "v6.0.0" }
tokio = { version = "1", features = ["full"] }
ethrex-l2-common = { git = "https://github.com/lambdaclass/ethrex.git", tag = "v6.0.0" }
ethrex-blockchain = { git = "https://github.com/lambdaclass/ethrex.git", tag = "v6.0.0" }
url = "2"
hex = "0.4"
eyre = "0.6"

`TestToken.bin`

608060405234801561000f575f5ffd5b506040518060400160405280600881526020017f46756e546f6b656e0000000000000000000000000000000000000000000000008152506040518060400160405280600381526020017f46554e0000000000000000000000000000000000000000000000000000000000815250816003908161008b9190610598565b50806004908161009b9190610598565b5050506100b83369d3c21bcecceda10000006100bd60201b60201c565b61077c565b5f73ffffffffffffffffffffffffffffffffffffffff168273ffffffffffffffffffffffffffffffffffffffff160361012d575f6040517fec442f0500000000000000000000000000000000000000000000000000000000815260040161012491906106a6565b60405180910390fd5b61013e5f838361014260201b60201c565b5050565b5f73ffffffffffffffffffffffffffffffffffffffff168373ffffffffffffffffffffffffffffffffffffffff1603610192578060025f82825461018691906106ec565b92505081905550610260565b5f5f5f8573ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020019081526020015f205490508181101561021b578381836040517fe450d38c0000000000000000000000000000000000000000000000000000000081526004016102129392919061072e565b60405180910390fd5b8181035f5f8673ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020019081526020015f2081905550505b5f73ffffffffffffffffffffffffffffffffffffffff168273ffffffffffffffffffffffffffffffffffffffff16036102a7578060025f82825403925050819055506102f1565b805f5f8473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020019081526020015f205f82825401925050819055505b8173ffffffffffffffffffffffffffffffffffffffff168373ffffffffffffffffffffffffffffffffffffffff167fddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef8360405161034e9190610763565b60405180910390a3505050565b5f81519050919050565b7f4e487b71000000000000000000000000000000000000000000000000000000005f52604160045260245ffd5b7f4e487b71000000000000000000000000000000000000000000000000000000005f52602260045260245ffd5b5f60028204905060018216806103d657607f821691505b6020821081036103e9576103e8610392565b5b50919050565b5f819050815f5260205f209050919050565b5f6020601f8301049050919050565b5f82821b905092915050565b5f6008830261044b7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff82610410565b6104558683610410565b95508019841693508086168417925050509392505050565b5f819050919050565b5f819050919050565b5f61049961049461048f8461046d565b610476565b61046d565b9050919050565b5f819050919050565b6104b28361047f565b6104c66104be826104a0565b84845461041c565b825550505050565b5f5f905090565b6104dd6104ce565b6104e88184846104a9565b505050565b5b8181101561050b576105005f826104d5565b6001810190506104ee565b5050565b601f82111561055057610521816103ef565b61052a84610401565b81016020851015610539578190505b61054d61054585610401565b8301826104ed565b50505b505050565b5f82821c905092915050565b5f6105705f1984600802610555565b1980831691505092915050565b5f6105888383610561565b9150826002028217905092915050565b6105a18261035b565b67ffffffffffffffff8111156105ba576105b9610365565b5b6105c482546103bf565b6105cf82828561050f565b5f60209050601f831160018114610600575f84156105ee578287015190505b6105f8858261057d565b86555061065f565b601f19841661060e866103ef565b5f5b8281101561063557848901518255600182019150602085019450602081019050610610565b86831015610652578489015161064e601f891682610561565b8355505b6001600288020188555050505b505050505050565b5f73ffffffffffffffffffffffffffffffffffffffff82169050919050565b5f61069082610667565b9050919050565b6106a081610686565b82525050565b5f6020820190506106b95f830184610697565b92915050565b7f4e487b71000000000000000000000000000000000000000000000000000000005f52601160045260245ffd5b5f6106f68261046d565b91506107018361046d565b9250828201905080821115610719576107186106bf565b5b92915050565b6107288161046d565b82525050565b5f6060820190506107415f830186610697565b61074e602083018561071f565b61075b604083018461071f565b949350505050565b5f6020820190506107765f83018461071f565b92915050565b610e8c806107895f395ff3fe608060405234801561000f575f5ffd5b506004361061009c575f3560e01c80635b70ea9f116100645780635b70ea9f1461015a57806370a082311461016457806395d89b4114610194578063a9059cbb146101b2578063dd62ed3e146101e25761009c565b806306fdde03146100a0578063095ea7b3146100be57806318160ddd146100ee57806323b872dd1461010c578063313ce5671461013c575b5f5ffd5b6100a8610212565b6040516100b59190610b05565b60405180910390f35b6100d860048036038101906100d39190610bb6565b6102a2565b6040516100e59190610c0e565b60405180910390f35b6100f66102c4565b6040516101039190610c36565b60405180910390f35b61012660048036038101906101219190610c4f565b6102cd565b6040516101339190610c0e565b60405180910390f35b6101446102fb565b6040516101519190610cba565b60405180910390f35b610162610303565b005b61017e60048036038101906101799190610cd3565b610319565b60405161018b9190610c36565b60405180910390f35b61019c61035e565b6040516101a99190610b05565b60405180910390f35b6101cc60048036038101906101c79190610bb6565b6103ee565b6040516101d99190610c0e565b60405180910390f35b6101fc60048036038101906101f79190610cfe565b610410565b6040516102099190610c36565b60405180910390f35b60606003805461022190610d69565b80601f016020809104026020016040519081016040528092919081815260200182805461024d90610d69565b80156102985780601f1061026f57610100808354040283529160200191610298565b820191905f5260205f20905b81548152906001019060200180831161027b57829003601f168201915b5050505050905090565b5f5f6102ac610492565b90506102b9818585610499565b600191505092915050565b5f600254905090565b5f5f6102d7610492565b90506102e48582856104ab565b6102ef85858561053e565b60019150509392505050565b5f6012905090565b6103173369d3c21bcecceda100000061062e565b565b5f5f5f8373ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020019081526020015f20549050919050565b60606004805461036d90610d69565b80601f016020809104026020016040519081016040528092919081815260200182805461039990610d69565b80156103e45780601f106103bb576101008083540402835291602001916103e4565b820191905f5260205f20905b8154815290600101906020018083116103c757829003601f168201915b5050505050905090565b5f5f6103f8610492565b905061040581858561053e565b600191505092915050565b5f60015f8473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020019081526020015f205f8373ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020019081526020015f2054905092915050565b5f33905090565b6104a683838360016106ad565b505050565b5f6104b68484610410565b90507fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff8110156105385781811015610529578281836040517ffb8f41b200000000000000000000000000000000000000000000000000000000815260040161052093929190610da8565b60405180910390fd5b61053784848484035f6106ad565b5b50505050565b5f73ffffffffffffffffffffffffffffffffffffffff168373ffffffffffffffffffffffffffffffffffffffff16036105ae575f6040517f96c6fd1e0000000000000000000000000000000000000000000000000000000081526004016105a59190610ddd565b60405180910390fd5b5f73ffffffffffffffffffffffffffffffffffffffff168273ffffffffffffffffffffffffffffffffffffffff160361061e575f6040517fec442f050000000000000000000000000000000000000000000000000000000081526004016106159190610ddd565b60405180910390fd5b61062983838361087c565b505050565b5f73ffffffffffffffffffffffffffffffffffffffff168273ffffffffffffffffffffffffffffffffffffffff160361069e575f6040517fec442f050000000000000000000000000000000000000000000000000000000081526004016106959190610ddd565b60405180910390fd5b6106a95f838361087c565b5050565b5f73ffffffffffffffffffffffffffffffffffffffff168473ffffffffffffffffffffffffffffffffffffffff160361071d575f6040517fe602df050000000000000000000000000000000000000000000000000000000081526004016107149190610ddd565b60405180910390fd5b5f73ffffffffffffffffffffffffffffffffffffffff168373ffffffffffffffffffffffffffffffffffffffff160361078d575f6040517f94280d620000000000000000000000000000000000000000000000000000000081526004016107849190610ddd565b60405180910390fd5b8160015f8673ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020019081526020015f205f8573ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020019081526020015f20819055508015610876578273ffffffffffffffffffffffffffffffffffffffff168473ffffffffffffffffffffffffffffffffffffffff167f8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b9258460405161086d9190610c36565b60405180910390a35b50505050565b5f73ffffffffffffffffffffffffffffffffffffffff168373ffffffffffffffffffffffffffffffffffffffff16036108cc578060025f8282546108c09190610e23565b9250508190555061099a565b5f5f5f8573ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020019081526020015f2054905081811015610955578381836040517fe450d38c00000000000000000000000000000000000000000000000000000000815260040161094c93929190610da8565b60405180910390fd5b8181035f5f8673ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020019081526020015f2081905550505b5f73ffffffffffffffffffffffffffffffffffffffff168273ffffffffffffffffffffffffffffffffffffffff16036109e1578060025f8282540392505081905550610a2b565b805f5f8473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020019081526020015f205f82825401925050819055505b8173ffffffffffffffffffffffffffffffffffffffff168373ffffffffffffffffffffffffffffffffffffffff167fddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef83604051610a889190610c36565b60405180910390a3505050565b5f81519050919050565b5f82825260208201905092915050565b8281835e5f83830152505050565b5f601f19601f8301169050919050565b5f610ad782610a95565b610ae18185610a9f565b9350610af1818560208601610aaf565b610afa81610abd565b840191505092915050565b5f6020820190508181035f830152610b1d8184610acd565b905092915050565b5f5ffd5b5f73ffffffffffffffffffffffffffffffffffffffff82169050919050565b5f610b5282610b29565b9050919050565b610b6281610b48565b8114610b6c575f5ffd5b50565b5f81359050610b7d81610b59565b92915050565b5f819050919050565b610b9581610b83565b8114610b9f575f5ffd5b50565b5f81359050610bb081610b8c565b92915050565b5f5f60408385031215610bcc57610bcb610b25565b5b5f610bd985828601610b6f565b9250506020610bea85828601610ba2565b9150509250929050565b5f8115159050919050565b610c0881610bf4565b82525050565b5f602082019050610c215f830184610bff565b92915050565b610c3081610b83565b82525050565b5f602082019050610c495f830184610c27565b92915050565b5f5f5f60608486031215610c6657610c65610b25565b5b5f610c7386828701610b6f565b9350506020610c8486828701610b6f565b9250506040610c9586828701610ba2565b9150509250925092565b5f60ff82169050919050565b610cb481610c9f565b82525050565b5f602082019050610ccd5f830184610cab565b92915050565b5f60208284031215610ce857610ce7610b25565b5b5f610cf584828501610b6f565b91505092915050565b5f5f60408385031215610d1457610d13610b25565b5b5f610d2185828601610b6f565b9250506020610d3285828601610b6f565b9150509250929050565b7f4e487b71000000000000000000000000000000000000000000000000000000005f52602260045260245ffd5b5f6002820490506001821680610d8057607f821691505b602082108103610d9357610d92610d3c565b5b50919050565b610da281610b48565b82525050565b5f606082019050610dbb5f830186610d99565b610dc86020830185610c27565b610dd56040830184610c27565b949350505050565b5f602082019050610df05f830184610d99565b92915050565b7f4e487b71000000000000000000000000000000000000000000000000000000005f52601160045260245ffd5b5f610e2d82610b83565b9150610e3883610b83565b9250828201905080821115610e5057610e4f610df6565b5b9291505056fea2646970667358221220c2ace90351a6254148d1d6fc391d67d42f65e41f9290478674caf67a0ec34ec964736f6c634300081b0033

Deposits

This document contains a detailed explanation of how asset deposits work.

Native ETH deposits

This section explains step by step how native ETH deposits work.

On L1:

The user sends ETH to the CommonBridge contract. Alternatively, they can also call deposit and specify the address to receive the deposit in (the l2Recipient).
The bridge adds the deposit's hash to the pendingTxHashes. We explain how to compute this hash in "Generic L1->L2 messaging"

The bridge emits a PrivilegedTxSent event:

bytes memory callData = abi.encodeCall(ICommonBridgeL2.mintETH, (l2Recipient));

emit PrivilegedTxSent(
    0xffff,         // sender in L2 (the L2 bridge)
    0xffff,         // to (the L2 bridge)
    transactionId,
    msg.value,      // value
    gasLimit,
    callData
);

Off-chain:

On each L2 node, the L1 watcher processes PrivilegedTxSent events, each adding a PrivilegedL2Transaction to the L2 mempool.
The privileged transaction is an EIP-2718 typed transaction, somewhat similar to an EIP-1559 transaction, but with some changes. For this case, the important difference is that the sender of the transaction is set by our L1 bridge. This enables our L1 bridge to "forge" transactions from any sender, even arbitrary addresses like the L2 bridge.
Privileged transactions sent by the L2 bridge don't deduct from the bridge's balance their value. In practice, this means ETH equal to the transactions value is minted.

On L2:

The privileged transaction calls mintETH on the CommonBridgeL2 with the intended recipient as parameter.
The bridge verifies the sender is itself, which can only happen for deposits sent through the L1 bridge.
The bridge sends the minted ETH to the recipient. In case of failure, it initiates an ETH withdrawal for the same amount.

Back on L1:

A sequencer commits a batch on L1 including the privileged transaction.
The OnChainProposer asserts the included privileged transactions exist and are included in order.
The OnChainProposer notifies the bridge of the consumed privileged transactions and they are removed from pendingTxHashes.

---
title: User makes an ETH deposit
---
sequenceDiagram
    box rgb(33,66,99) L1
        actor L1Alice as Alice
        participant CommonBridge
        participant OnChainProposer
    end

    actor Sequencer

    box rgb(139, 63, 63) L2
        actor CommonBridgeL2
        actor L2Alice as Alice
    end

    L1Alice->>CommonBridge: sends 42 ETH
    CommonBridge->>CommonBridge: pendingTxHashes.push(txHash)
    CommonBridge->>CommonBridge: emit PrivilegedTxSent

    CommonBridge-->>Sequencer: receives event
    Sequencer-->>CommonBridgeL2: mints 42 ETH and<br>starts processing tx
    CommonBridgeL2->>CommonBridgeL2: calls mintETH
    CommonBridgeL2->>L2Alice: sends 42 ETH

    Sequencer->>OnChainProposer: publishes batch
    OnChainProposer->>CommonBridge: consumes pending deposits
    CommonBridge-->>CommonBridge: pendingTxHashes.pop()

ERC20 deposits through the native bridge

This section explains step by step how native ERC20 deposits work.

On L1:

The user gives the CommonBridge allowance via an approve call to the L1 token contract.
The user calls depositERC20 on the bridge, specifying the L1 and L2 token addresses, the amount to deposit, along with the intended L2 recipient.
The bridge locks the specified L1 token amount in the bridge, updating the mapping with the amount locked for the L1 and L2 token pair. This ensures that L2 token withdrawals don't consume L1 tokens that weren't deposited into that L2 token (see "Why store the provenance of bridged tokens?" for more information).

The bridge emits a PrivilegedTxSent event:

emit PrivilegedTxSent(
    0,            // amount (unused)
    0xffff,       // to (the L2 bridge)
    depositId,
    0xffff,       // sender in L2 (the L2 bridge)
    gasLimit,
    callData
);

Off-chain:

On each L2 node, the L1 watcher processes PrivilegedTxSent events, each adding a PrivilegedL2Transaction to the L2 mempool.
The privileged transaction is an EIP-2718 typed transaction, somewhat similar to an EIP-1559 transaction, but with some changes. For this case, the important differences is that the sender of the transaction is set by our L1 bridge. This enables our L1 bridge to "forge" transactions from any sender, even arbitrary addresses like the L2 bridge.

On L2:

The privileged transaction performs a call to mintERC20 on the CommonBridgeL2 from the L2 bridge's address, specifying the address of the L1 and L2 tokens, along with the amount and recipient.
The bridge verifies the sender is itself, which can only happen for deposits sent through the L1 bridge.
The bridge calls l1Address() on the L2 token, to verify it matches the received L1 token address.
The bridge calls crosschainMint on the L2 token, minting the specified amount of tokens and sending them to the L2 recipient. In case of failure, it initiates an ERC20 withdrawal for the same amount.

Back on L1:

A sequencer commits a batch on L1 including the privileged transaction.
The OnChainProposer asserts the included privileged transactions exist and are included in order.
The OnChainProposer notifies the bridge of the consumed privileged transactions and they are removed from pendingTxHashes.

---
title: User makes an ERC20 deposit
---
sequenceDiagram
    box rgb(33,66,99) L1
        actor L1Alice as Alice
        participant L1Token
        participant CommonBridge
        participant OnChainProposer
    end

    actor Sequencer

    box rgb(139, 63, 63) L2
        participant CommonBridgeL2
        participant L2Token
        actor L2Alice as Alice
    end

    L1Alice->>L1Token: approves token transfer
    L1Alice->>CommonBridge: calls depositERC20
    CommonBridge->>CommonBridge: pendingTxHashes.push(txHash)
    CommonBridge->>CommonBridge: emit PrivilegedTxSent

    CommonBridge-->>Sequencer: receives event
    Sequencer-->>CommonBridgeL2: starts processing tx
    CommonBridgeL2->>CommonBridgeL2: calls mintERC20

    CommonBridgeL2->>L2Token: calls l1Address
    L2Token->>CommonBridgeL2: returns address of L1Token

    CommonBridgeL2->>L2Token: calls crosschainMint
    L2Token-->>L2Alice: mints 42 tokens

    Sequencer->>OnChainProposer: publishes batch
    OnChainProposer->>CommonBridge: consumes pending deposits
    CommonBridge-->>CommonBridge: pendingTxHashes.pop()

Why store the provenance of bridged tokens?

As said before, storing the provenance of bridged tokens or, in other words, how many tokens were sent from each L1 token to each L2 token, ensures that L2 token withdrawals don't unlock L1 tokens that weren't deposited into another L2 token.

This can be better understood with an example:

---
title: Attacker exploits alternative bridge without token provenance
---
sequenceDiagram
    box rgb(33,66,99) L1
        actor L1Eve as Eve
        actor L1Alice as Alice
        participant CommonBridge
    end

    box rgb(139, 63, 63) L2
        participant CommonBridgeL2
        actor L2Alice as Alice
        actor L2Eve as Eve
    end

    Note over L1Eve,L2Eve: Alice does a normal deposit
    L1Alice ->> CommonBridge: Deposits 100 Foo tokens into FooL2
    CommonBridge -->> CommonBridgeL2: Notifies deposit
    CommonBridgeL2 ->> L2Alice: Sends 100 FooL2 tokens

    Note over L1Eve,L2Eve: Eve does a deposit to ensure the L2 token they control is registered with the bridge
    L1Eve ->> CommonBridge: Deposits 1 Foo token into Bar
    CommonBridge -->> CommonBridgeL2: Notifies deposit
    CommonBridgeL2 ->> L2Eve: Sends 1 Bar token

    Note over L1Eve,L2Eve: Eve does a malicious withdawal of Alice's funds
    L2Eve ->> CommonBridgeL2: Withdraws 101 Bar tokens into Foo
    CommonBridgeL2 -->> CommonBridge: Notifies withdrawal
    CommonBridge ->> L1Eve: Sends 101 Foo tokens

Generic L1->L2 messaging

Privileged transactions are signaled by the L1 bridge through PrivilegedTxSent events. These events are emitted by the CommonBridge contract on L1 and processed by the L1 watcher on each L2 node.

event PrivilegedTxSent (
    address indexed from,
    address indexed to,
    uint256 indexed transactionId,
    uint256 value,
    uint256 gasLimit,
    bytes data
);

As seen before, this same event is used for native deposits, but with the from artificially set to the L2 bridge address, which is also the to address.

For tracking purposes, we might want to know the hash of the L2 transaction. We can compute it as follows:

keccak256(
    bytes.concat(
        bytes20(from),
        bytes20(to),
        bytes32(transactionId),
        bytes32(value),
        bytes32(gasLimit),
        keccak256(data)
    )
)

Address Aliasing

To prevent attacks where a L1 impersonates an L2 contract, we implement Address Aliasing like Optimism (albeit with we a different constant, to prevent confusion).

The attack prevented would've looked like this:

An L2 contract gets deployed at address A
Someone malicious deploys a contract at the same address (through deterministic deployments, etc)
The malicious contract sends a privileged transaction, which can steal A's resourced on the L2

By modifying the address of L1 contracts by adding a constant, we prevent this attack since both won't have the same address.

Forced Inclusion

Each transaction is given a deadline for processing. If the sequencer is unwilling to include a privileged transaction before this timer expires, batches stop being processed and the chain halts until the sequencer processes every expired transaction.

After an extended downtime, the sequencer can catch up by sending batches made solely out of privileged transactions.

---
title: Sequencer goes offline
---
sequenceDiagram
    box rgb(33,66,99) L1
        actor L1Alice
        actor Sequencer
        participant CommonBridge
        participant OnChainProposer
    end

    L1Alice ->> CommonBridge: Sends a privileged transaction

    Note over Sequencer: Sequencer goes offline for a long time
    Sequencer ->> OnChainProposer: Sends batch as usual
    OnChainProposer ->> Sequencer: Error
    Note over Sequencer: Operator configures the sequencer to catch up
    Sequencer ->> OnChainProposer: Sends batch of only privileged transactions
    OnChainProposer ->> Sequencer: OK
    Sequencer ->> OnChainProposer: Sends batch with remaining expired privileged transactions, along with other transactions
    OnChainProposer ->> Sequencer: OK
    Note over Sequencer: Sequencer is now catched up
    Sequencer ->> OnChainProposer: Sends batch as usual
    OnChainProposer ->> Sequencer: OK

Limitations

Due to the gas cost of computing rolling hashes, there is a limit to how many deposits can be handled in a single batch.
To prevent the creation of invalid batches, we enforce a maximum cap on deposits per batch in the l1_committer.
We also enforce the same maximum cap per block in the block_producer, to avoid situations where the l1_committer could get stuck if a single block contains more deposits than the configured batch cap.

Withdrawals

This document contains a detailed explanation of how asset withdrawals work.

Native ETH withdrawals

This section explains step by step how native ETH withdrawals work.

On L2:

The user sends a transaction calling withdraw(address _receiverOnL1) on the CommonBridgeL2 contract, along with the amount of ETH to be withdrawn.
The bridge sends the withdrawn amount to the burn address.
The bridge calls sendMessageToL1(bytes32 data) on the L2ToL1Messenger contract, with data being:
```
bytes32 data = keccak256(abi.encodePacked(ETH_ADDRESS, ETH_ADDRESS, _receiverOnL1, msg.value))
```
The ETH_ADDRESS is an arbitrary address we use, meaning the "token" to transfer is ETH.
L2ToL1Messenger emits an L1Message event, with the address of the L2 bridge contract and data as topics, along with a unique message ID.

Off-chain:

On each L2 node, the L1 watcher extracts L1Message events, generating a merkle tree with the hashed messages as leaves. The merkle tree format is explained in the "L1Message Merkle tree" section below.

On L1:

A sequencer commits the batch on L1, publishing the merkle tree's root with publishWithdrawals on the L1 CommonBridge.
The user submits a withdrawal proof when calling claimWithdrawal on the L1 CommonBridge. The proof can be obtained by calling ethrex_getWithdrawalProof in any L2 node, after the batch containing the withdrawal transaction was verified in the L1.
The bridge asserts the proof is valid and wasn't previously claimed.
The bridge sends the locked funds specified in the L1Message to the user.

---
title: User makes an ETH withdrawal
---
sequenceDiagram
    box rgb(139, 63, 63) L2
        actor L2Alice as Alice
        participant CommonBridgeL2
        participant L2ToL1Messenger
    end

    actor Sequencer

    box rgb(33,66,99) L1
        participant OnChainProposer
        participant CommonBridge
        actor L1Alice as Alice
    end

    L2Alice->>CommonBridgeL2: withdraws 42 ETH
    CommonBridgeL2->>CommonBridgeL2: burns 42 ETH
    CommonBridgeL2->>L2ToL1Messenger: calls sendMessageToL1
    L2ToL1Messenger->>L2ToL1Messenger: emits L1Message event

    L2ToL1Messenger-->>Sequencer: receives event

    Sequencer->>OnChainProposer: publishes batch
    OnChainProposer->>CommonBridge: publishes L1 message root

    L1Alice->>CommonBridge: submits withdrawal proof
    CommonBridge-->>CommonBridge: asserts proof is valid
    CommonBridge->>L1Alice: sends 42 ETH

ERC20 withdrawals through the native bridge

This section explains step by step how native ERC20 withdrawals work.

On L2:

The user calls approve on the L2 tokens to allow the bridge to transfer the asset.
The user sends a transaction calling withdrawERC20(address _token, address _receiverOnL1, uint256 _value) on the CommonBridgeL2 contract.
The bridge calls crosschainBurn on the L2 token, burning the amount to be withdrawn by the user.
The bridge fetches the address of the L1 token by calling l1Address() on the L2 token contract.

The bridge calls sendMessageToL1(bytes32 data) on the L2ToL1Messenger contract, with data being:

bytes32 data = keccak256(abi.encodePacked(_token.l1Address(), _token, _receiverOnL1, _value))

L2ToL1Messenger emits an L1Message event, with the address of the L2 bridge contract and data as topics, along with a unique message ID.

Off-chain:

On each L2 node, the L1 watcher extracts L1Message events, generating a merkle tree with the hashed messages as leaves. The merkle tree format is explained in the "L1Message Merkle tree" section below.

On L1:

A sequencer commits the batch on L1, publishing the L1Message with publishWithdrawals on the L1 CommonBridge.
The user submits a withdrawal proof when calling claimWithdrawalERC20 on the L1 CommonBridge. The proof can be obtained by calling ethrex_getWithdrawalProof in any L2 node, after the batch containing the withdrawal transaction was verified in the L1.
The bridge asserts the proof is valid and wasn't previously claimed, and that the locked tokens mapping contains enough balance for the L1 and L2 token pair to cover the transfer.
The bridge transfers the locked tokens specified in the L1Message to the user and discounts the transferred amount from the L1 and L2 token pair in the mapping.

---
title: User makes an ERC20 withdrawal
---
sequenceDiagram
    box rgb(139, 63, 63) L2
        actor L2Alice as Alice
        participant L2Token
        participant CommonBridgeL2
        participant L2ToL1Messenger
    end

    actor Sequencer

    box rgb(33,66,99) L1
        participant OnChainProposer
        participant CommonBridge
        participant L1Token
        actor L1Alice as Alice
    end

    L2Alice->>L2Token: approves token transfer
    L2Alice->>CommonBridgeL2: withdraws 42 of L2Token
    CommonBridgeL2->>L2Token: burns the 42 tokens
    CommonBridgeL2->>L2ToL1Messenger: calls sendMessageToL1
    L2ToL1Messenger->>L2ToL1Messenger: emits L1Message event

    L2ToL1Messenger-->>Sequencer: receives event

    Sequencer->>OnChainProposer: publishes batch
    OnChainProposer->>CommonBridge: publishes L1 message root

    L1Alice->>CommonBridge: submits withdrawal proof
    CommonBridge->>L1Token: transfers tokens
    L1Token-->>L1Alice: sends 42 tokens

Generic L2->L1 messaging

First, we need to understand the generic mechanism behind it:

`L1Message`

To allow generic L2->L1 messages, a system contract is added which allows sending arbitrary data. This data is emitted as L1Message events, which nodes automatically extract from blocks.

#![allow(unused)]
fn main() {
struct L1Message {
    tx_hash: H256,    // L2 transaction where it was included
    from: Address,    // Who sent the message in L2
    data_hash: H256,  // Hashed payload
    message_id: U256, // Unique message ID
}
}

`L1Message` Merkle tree

When sequencers commit a new batch, they include the merkle root of all the L1Messages inside the batch. That way, L1 contracts can verify some data was sent from a specific L2 sender.

---
title: L1Message Merkle tree
---
flowchart TD
    
    Msg2[L1Message<sub>2</sub>]
    Root([Root])
    Node1([Node<sub>1</sub>])
    Node2([Node<sub>2</sub>])

    Root --- Node1
    Root --- Node2

    subgraph Msg1["L1Message<sub>1</sub>"]
        direction LR

        txHash1["txHash<sub>1</sub>"]
        from1["from<sub>1</sub>"]
        dataHash1["hash(data<sub>1</sub>)"]
        messageId1["messageId<sub>1</sub>"]

        txHash1 --- from1
        from1 --- dataHash1
        dataHash1 --- messageId1
    end

    Node1 --- Msg1
    Node2 --- Msg2

As shown in the diagram, the leaves of the tree are the hash of each encoded L1Message. Messages are encoded by packing, in order:

the transaction hash that generated it in the L2
the address of the L2 sender
the hashed data attached to the message
the unique message ID

Bridging

On the L2 side, for the case of asset bridging, a contract burns some assets. It then sends a message to the L1 containing the details of this operation:

From: L2 token address that was burnt
To: L1 token address that will be withdrawn
Destination: L1 address that can claim the deposit
Amount: how much was burnt

When the batch is committed on the L1, the OnChainProposer notifies the bridge which saves the message tree root. Once the batch containing this transaction is verified, the user can claim their funds on the L1. To do this, they compute a merkle proof for the included batch and call the L1 CommonBridge contract.

This contract then:

Checks that the batch is verified
Ensures the withdrawal wasn't already claimed
Computes the expected leaf
Validates that the proof leads from the leaf to the root of the message tree
Gives the funds to the user
Marks the withdrawal as claimed

Ethrex L2 contracts

There are two L1 contracts: OnChainProposer and CommonBridge. Both contracts are deployed using UUPS proxies, so they are upgradeables.

L1 Contracts

`CommonBridge`

The CommonBridge is an upgradeable smart contract that facilitates cross-chain transfers between L1 and L2.

State Variables

pendingTxHashes: Array storing hashed pending privileged transactions
batchWithdrawalLogsMerkleRoots: Mapping of L2 batch numbers to merkle roots of withdrawal logs
deposits: Tracks how much of each L1 token was deposited for each L2 token (L1 → L2 → amount)
claimedWithdrawalIDs: Tracks which withdrawals have been claimed by message ID
ON_CHAIN_PROPOSER: Address of the contract that can commit and verify batches
L2_BRIDGE_ADDRESS: Constant address (0xffff) representing the L2 bridge

Core Functionality

Deposits (L1 → L2)
- deposit(): Allows users to deposit ETH to L2
- depositERC20(): Allows users to deposit ERC20 tokens to L2
- receive(): Fallback function for ETH deposits, forwarding to the sender's address on the L2
- sendToL2(): Sends arbitrary data to L2 via privileged transaction
Internally the deposit functions will use the SendValues struct defined as:
```
struct SendValues {
    address to; // Target address on L2
    uint256 gasLimit; // Maximum gas for L2 execution
    uint256 value; // The value of the transaction
    bytes data; // Calldata to execute on the target L2 contract
}
```
This expresivity allows for arbitrary cross-chain actions, e.g., depositing ETH then interacting with an L2 contract.
Withdrawals (L2 → L1)
- claimWithdrawal(): Withdraw ETH from CommonBridge via Merkle proof
- claimWithdrawalERC20(): Withdraw ERC20 tokens from CommonBridge via Merkle proof
- publishWithdrawals(): Priviledged function to add merkle root of L2 withdrawal logs to batchWithdrawalLogsMerkleRoots mapping to make them claimable
Transaction Management
- getPendingTransactionHashes(): Returns pending privileged transaction hashes
- removePendingTransactionHashes(): Removes processed privileged transactions (only callable by OnChainProposer)
- getPendingTransactionsVersionedHash(): Returns a versioned hash of the first number of pending privileged transactions

`OnChainOperator`

The OnChainProposer is an upgradeable smart contract that ensures the advancement of the L2. It's used by sequencers to commit batches of L2 blocks and verify their proofs.

State Variables

batchCommitments: Mapping of batch numbers to submitted BatchCommitmentInfo structs
lastVerifiedBatch: The latest verified batch number (all batches ≤ this are considered verified)
lastCommittedBatch: The latest committed batch number (all batches ≤ this are considered committed)
authorizedSequencerAddresses: Mapping of authorized sequencer addresses that can commit and verify batches

Core Functionality

Batch Commitment
- commitBatch(): Commits a batch of L2 blocks by storing its commitment data and publishing withdrawals
- revertBatch(): Removes unverified batches (only callable when paused)
Proof Verification
- verifyBatch(): Verifies a single batch using RISC0, SP1, or TDX proofs
- verifyBatchesAligned(): Verifies multiple batches in sequence using aligned proofs with Merkle verification
State Validation
- _verifyPublicData(): Internal function used during verifyBatch() or verifyBatchesAligned() that validates public proof inputs match previous data from commitBatch()

L2 Contracts

`CommonBridgeL2`

The CommonBridgeL2 is an L2 smart contract that facilitates cross-chain transfers between L1 and L2.

State Variables

L1_MESSENGER: Constant address (0x000000000000000000000000000000000000FFFE) representing the L2-to-L1 messenger contract
BURN_ADDRESS: Constant address (0x0000000000000000000000000000000000000000) used to burn ETH during withdrawals
ETH_TOKEN: Constant address (0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE) representing ETH as a token

Core Functionality

ETH Operations
- withdraw(): Initiates ETH withdrawal to L1 by burning ETH on L2 and sending a message to L1
- mintETH(): Transfers ETH to a recipient (called by privileged L1 bridge transactions). If it fails a withdrawal is queued.
ERC20 Token Operations
- mintERC20(): Attempts to mint ERC20 tokens on L2 (only callable by the bridge itself via privileged transactions). If it fails a withdrawal is queued.
- tryMintERC20(): Internal function that validates token L1 address and performs a cross-chain mint
- withdrawERC20(): Initiates ERC20 token withdrawal to L1 by burning tokens on L2 and sending a message to L1
Cross-Chain Messaging
- _withdraw(): Private function that sends withdrawal messages to L1 via the L2-to-L1 messenger
- Uses keccak256 hashing to encode withdrawal data for L1 processing
Access Control
- onlySelf: Modifier ensuring only the bridge contract itself can call privileged functions
- Validates that privileged operations (like minting) are only performed by the bridge

`L2ToL1Messenger`

The L2ToL1Messenger is a simple L2 smart contract that enables communication from L2 to L1 by emitting the data as L1Message events for sequencers to pick up.

State Variables

lastMessageId: Counter that tracks the ID of the last emitted message (incremented before each message is sent)

Core Functionality

Message Sending
- sendMessageToL1(): Sends a message to L1 by emitting an L1Message event with the sender, data, and lastMessageId

Upgrade the contracts

To upgrade a contract, you have to create the new contract and, as the original one, inherit from OpenZeppelin's UUPSUpgradeable. Make sure to implement the _authorizeUpgrade function and follow the proxy pattern restrictions.

Once you have the new contract, you need to do the following three steps:

Deploy the new contract

rex deploy <NEW_IMPLEMENTATION_BYTECODE> 0 <DEPLOYER_PRIVATE_KEY>

Upgrade the proxy by calling the method upgradeToAndCall(address newImplementation, bytes memory data). The data parameter is the calldata to call on the new implementation as an initialization, you can pass an empty stream.
```
rex send <PROXY_ADDRESS> 'upgradeToAndCall(address,bytes)' <NEW_IMPLEMENTATION_ADDRESS> <INITIALIZATION_CALLDATA> --private-key <PRIVATE_KEY>
```

Check the proxy updated the pointed address to the new implementation. It should return the address of the new implementation:

curl http://localhost:8545 -d '{"jsonrpc": "2.0", "id": "1", "method": "eth_getStorageAt", "params": [<PROXY_ADDRESS>, "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc", "latest"]}'

Transfer ownership

The contracts are Ownable2Step, that means that whenever you want to transfer the ownership, the new owner have to accept it to effectively apply the change. This is an extra step of security, to avoid accidentally transfer ownership to a wrong account. You can make the transfer in these steps:

Start the transfer:

rex send <PROXY_ADDRESS> 'transferOwnership(address)' <NEW_OWNER_ADDRESS> --private-key <CURRENT_OWNER_PRIVATE_KEY>

Accept the ownership:

rex send <PROXY_ADDRESS> 'acceptOwnership()' --private-key <NEW_OWNER_PRIVATE_KEY>

Based sequencing

This section covers the fundamentals of "based" rollups in the context of L2s built with ethrex.

What is a Based Rollup?

A based rollup is a type of Layer 2 (L2) rollup that relies on the Ethereum mainnet (L1) for sequencing and ordering transactions, instead of using its own independent sequencer. This design leverages Ethereum's security and neutrality for transaction ordering, making the rollup more trust-minimized and censorship-resistant.

important

This documentation is about the current state of the based feature development and not about the final implementation. It is subject to change as the feature evolves and their still could be unmitigated issues.

note

This is an extension of the ethrex-L2-Sequencer documentation and is intended to be merged with it in the future.

Components

In addition to the components outlined in the ethrex-L2-Sequencer documentation, the based feature introduces new components to enable decentralized L2 sequencing. These additions enhance the system's ability to operate across multiple nodes, ensuring resilience, scalability, and state consistency.

Sequencer State

note

While not a traditional component, the Sequencer State is a fundamental element of the based feature and deserves its own dedicated section.

The based feature decentralizes L2 sequencing, moving away from a single, centralized Sequencer to a model where multiple nodes can participate, with only one acting as the lead Sequencer at any time. This shift requires nodes to adapt their behavior depending on their role, leading to the introduction of the Sequencer State. The Sequencer State defines two possible modes:

Sequencing: The node is the lead Sequencer, responsible for proposing and committing new blocks to the L2 chain.
Following: The node is not the lead Sequencer and must synchronize with and follow the blocks proposed by the current lead Sequencer.

To keep the system simple and avoid intricate inter-process communication, the Sequencer State is implemented as a global state, accessible to all Sequencer components. This design allows each component to check the state and adjust its operations accordingly. The State Updater component manages this global state.

State Updater

The State Updater is a new component tasked with maintaining and updating the Sequencer State. It interacts with the Sequencer Registry contract on L1 to determine the current lead Sequencer and adjusts the node’s state based on this information and local conditions. Its responsibilities include:

Periodic Monitoring: The State Updater runs at regular intervals, querying the SequencerRegistry contract to identify the current lead Sequencer.
State Transitions: It manages transitions between Sequencing and Following states based on these rules:
- If the node is designated as the lead Sequencer, it enters the Sequencing state.
- If the node is not the lead Sequencer, it enters the Following state.
- When a node ceases to be the lead Sequencer, it transitions to Following and reverts any uncommitted state to ensure consistency with the network.
- When a node becomes the lead Sequencer, it transitions to Sequencing only if it is fully synced (i.e., has processed all blocks up to the last committed batch). If not, it remains in Following until it catches up.

This component ensures that the node’s behavior aligns with its role, preventing conflicts and maintaining the integrity of the L2 state across the network.

Block Fetcher

Decentralization poses a risk: a lead Sequencer could advance the L2 chain without sharing blocks, potentially isolating other nodes. To address this, the OnChainProposer contract (see ethrex-L2-Contracts documentation) has been updated to include an RLP-encoded list of blocks committed in each batch. This makes block data publicly available on L1, enabling nodes to reconstruct the L2 state if needed.

The Block Fetcher is a new component designed to retrieve these blocks from L1 when the node is in the Following state. Its responsibilities include:

Querying L1: It queries the OnChainProposer contract to identify the last committed batch.
Scouting Transactions: Similar to how the L1 Watcher monitors deposit transactions, the Block Fetcher scans L1 for commit transactions containing the RLP-encoded block list.
State Reconstruction: It uses the retrieved blocks to rebuild the L2 state, ensuring the node remains synchronized with the network.

note

Currently, the Block Fetcher is the primary mechanism for nodes to sync with the lead Sequencer. Future enhancements will introduce P2P gossiping to enable direct block sharing between nodes, improving efficiency.

Contracts

In addition to the components described above, the based feature introduces new contracts and modifies existing ones to enhance decentralization, security, and transparency. Below are the key updates and additions:

note

This is an extension of the ethrex-L2-Contracts documentation and is intended to be merged with it in the future.

OnChainProposer (Modified)

The OnChainProposer contract, which handles batch proposals and management on L1, has been updated with the following modifications:

New Constant: A public constant SEQUENCER_REGISTRY has been added. This constant holds the address of the SequencerRegistry contract, linking the two contracts for sequencer management.
Modifier Update: The onlySequencer modifier has been renamed to onlyLeadSequencer. It now checks whether the caller is the current lead Sequencer, as determined by the SequencerRegistry contract. This ensures that only the designated leader can commit batches.
Initialization: The initialize method now accepts the address of the SequencerRegistry contract as a parameter. During initialization, this address is set to the SEQUENCER_REGISTRY constant, establishing the connection between the contracts.
Batch Commitment: The commitBatch method has been revised to improve data availability and streamline sequencer validation:
- It now requires an RLP-encoded list of blocks included in the batch. This list is published on L1 to ensure transparency and enable verification.
- The list of sequencers has been removed from the method parameters. Instead, the SequencerRegistry contract is now responsible for tracking and validating sequencers.
Event Modification: The BatchCommitted event has been updated to include the batch number of the committed batch. This addition enhances traceability and allows external systems to monitor batch progression more effectively.
Batch Verification: The verifyBatch method has been made more flexible and decentralized:
- The onlySequencer modifier has been removed, allowing anyone—not just the lead Sequencer—to verify batches.
- The restriction preventing multiple verifications of the same batch has been lifted. While multiple verifications are now permitted, only one valid verification is required to advance the L2 state. This change improves resilience and reduces dependency on a single actor.

SequencerRegistry (New Contract)

The SequencerRegistry is a new contract designed to manage the pool of Sequencers and oversee the leader election process in a decentralized manner.

Registration:
- Anyone can register as a Sequencer by calling the register method and depositing a minimum collateral of 1 ETH. This collateral serves as a Sybil resistance mechanism, ensuring that only committed participants join the network.
- Sequencers can exit the registry by calling the unregister method, which refunds their 1 ETH collateral upon successful deregistration.
Leader Election: The leader election process operates on a round-robin basis to fairly distribute the lead Sequencer role:
- Single Sequencer Case: If only one Sequencer is registered, it remains the lead Sequencer indefinitely.
- Multiple Sequencers: When two or more Sequencers are registered, the lead Sequencer rotates every 32 batches. This ensures that no single Sequencer dominates the network for an extended period.
Future Leader Prediction: The futureLeaderSequencer method allows querying the lead Sequencer for a batch n batches in the future. The calculation is based on the following logic:

Inputs:
- sequencers: An array of registered Sequencer addresses.
- currentBatch: The next batch to be committed, calculated as lastCommittedBatch() + 1 from the OnChainProposer contract.
- nBatchesInTheFuture: A parameter specifying how many batches ahead to look.
- targetBatch: Calculated as currentBatch + nBatchesInTheFuture.
- BATCHES_PER_SEQUENCER: A constant set to 32, representing the number of batches each lead Sequencer gets to commit.
Logic:
```
uint256 _currentBatch = IOnChainProposer(ON_CHAIN_PROPOSER).lastCommittedBatch() + 1;
uint256 _targetBatch = _currentBatch + nBatchesInTheFuture;
uint256 _id = _targetBatch / BATCHES_PER_SEQUENCER;
address _leader = sequencers[_id % sequencers.length];
```
Example: Assume 3 Sequencers are registered: [S0, S1, S2], and the current committed batch is 0:
- For batches 0–31: _id = 0 / 32 = 0, 0 % 3 = 0, lead Sequencer = S0.
- For batches 32–63: _id = 32 / 32 = 1, 1 % 3 = 1, lead Sequencer = S1.
- For batches 64–95: _id = 64 / 32 = 2, 2 % 3 = 2, lead Sequencer = S2.
- For batches 96–127: _id = 96 / 32 = 3, 3 % 3 = 0, lead Sequencer = S0.
This round-robin rotation repeats every 96 committed batches (32 committed batches per Sequencer × 3 Sequencers), ensuring equitable distribution of responsibilities.

Roadmap

Special thanks to Lorenzo and Kubi, George, and Louis from Gattaca, Jason from Fabric, and Matthew from Spire Labs for their feedback and suggestions.

note

This document is still under development, and everything stated in it is subject to change after feedback and iteration. Feedback is more than welcome.

important

We believe that Gattaca's model—permissionless with preconfs using L1 proposers (either directly or through delegations) as L2 sequencers—is the ideal approach. However, this model cannot achieve permissionlessness until the deterministic lookahead becomes available after Fusaka. In the meantime, we consider the Spire approach, based on a Dutch auction, to be the most suitable for our current needs. It is important to note that Rogue cannot implement a centralized mechanism for offering preconfs, so we have chosen to prioritize a permissionless structure before enabling preconfirmations. This initial approach is decentralized and permissionless but not based yet. Although sequencing rights aren't currently guaranteed to the L1 proposer, there will be incentives for L1 proposers to eventually participate in the L2, moving toward Justin Drake's definition.

From the beginning, ethrex was conceived not just as an Ethereum L1 client, but also as an L2 (ZK Rollup). This means anyone will be able to use ethrex to deploy an EVM-equivalent, multi-prover (supporting SP1, RISC Zero, and TEEs) based rollup with just one command. We recently wrote a blog post where we expand this idea more in depth.

The purpose of this document is to provide a high-level overview of how ethrex will implement its based rollup feature.

State of the art

Members of the Ethereum Foundation are actively discussing and proposing EIPs to integrate based sequencing into the Ethereum network. Efforts are also underway to coordinate and standardize the components required for these based rollups; one such initiative is FABRIC.

The following table provides a high-level comparison of different based sequencing approaches, setting the stage for our own proposal.

note

This table compares the different based rollups in the ecosystem based on their current development state, not their final form.

Based Rollup	Protocol	Sequencer Election	Proof System	Preconfs	Additional Context
Taiko Alethia (Taiko Labs)	Permissioned	Fixed Deterministic Lookahead	Multi-proof (sgxGeth (TEE), and sgxReth (ZK/TEE))	Yes	-
Gattaca's Based OP (Gattaca + Lambdaclass)	Permissioned	Round Robin	Single Proof (optimistic)	Yes	For phase 1, the Sequencer/Gateway was centralized. For phase 2 (current phase) the Sequencer/Gateway is permissioned.
R1	Permissionless	Total Anarchy	Multi-proof (ZK, TEE, Guardian)	No	R1 is yet to be specified but plans are for it to be built on top of Surge and Taiko's Stack. They're waiting until Taiko is mature enough to have preconfs
Surge (Nethermind)	Permissionless	Total Anarchy	Multi-proof (ZK, TEE, Guardian)	No	Surge is built on top of Taiko Alethia but it's tuned enough to be a Stage 2 rollup. Surge is not designed to compete with existing rollups for users or market share. Instead, it serves as a technical showcase, experimentation platform, and reference implementation.
Spire (Spire Labs)	Permissionless	Dutch Auction	Single Proof (optimistic)	Yes	-
Rogue (LambdaClass)	Permissionless	Dutch Auction	Multi-Proof (ZK + TEE)	Not Yet	We are prioritizing decentralization and permissionlessness at the expense of preconfirmations until the deterministic lookahead is available after Fusaka

Other based rollups not mentioned will be added later.

Ethrex proposal for based sequencing

According to Justin Drake's definition of "based", being "based" implies that the L1 proposers are the ones who, at the end of the day, sequence the L2, either directly or by delegating the responsibility to a third party.

However, today, the "based" ecosystem is very immature. Despite the constant efforts of various teams, no stack is fully prepared to meet this definition. Additionally, L1 proposers do not have sufficient economic incentives to be part of the protocol.

But there's a way out. As mentioned in Spire's "What is a based rollup?"

The key to this definition is that sequencing is "driven" by a base layer and not controlled by a completely external party.

Following this, our proposal's main focus is decentralization and low operation cost, and we don't want to sacrifice them in favor of preconfirmations or composability.

Considering this, after researching existing approaches, we concluded that a decentralized, permissionless ticket auction is the most practical first step for ethrex's based sequencing solution.

Ultimately, we aim to align with Gattaca's model for based sequencing and collaborate with FABRIC efforts to standardize based rollups and helping interoperability.

Rogue and many upcoming rollups will be following this approach.

Benefits of our approach

The key benefits of our approach to based sequencing are:

Decentralization and Permissionlessness from the Get-Go: We've decentralized ethrex L2 by allowing anyone to participate in the L2 block proposal; actors willing to participate on it can do this permissionlessly, as the execution ticket auction approach we are taking provides a governance free leader election mechanism.
Robust Censorship Resistance: By being decentralized and permissionless, and with the addition of Sequencer challenges, we increased the cost of censorship in the protocol.
Low Operational Cost: We strived to make the sequencer operating costs as low as possible by extending the sequencing window, allowing infrequent L1 finalization for low traffic periods.
Configurability: We intentionally designed our protocol to be configurable at its core. This allows different rollup setups to be tailored based on their unique needs, ensuring optimal performance, efficiency, and UX.

Key points

Terminology

Ticket: non-transferable right of a Sequencer to build and commit an L2 batch. One or more are auctioned during each auction period.
Sequencing Period: the period during which a ticket holder has sequencing rights.
Auction Period: the period during which the auction is performed.
Auction Challenge: instance within a sequencing period where lead Sequencer sequencing rights can be challenged.
Challenge Period: the period during which a lead sequencer can be challenged.
Allocated Period: the set of contiguous sequencing periods allocated among the winners of the corresponding auctioning period -during an auctioning period, multiple sequencing periods are auctioned, the set of these is the allocated period.
L2 batch: A collection of L2 blocks submitted to L1 in a single transaction.
Block/Batch Soft-commit Message: A signed P2P message from the Lead Sequencer publishing a new block or sealed batch.
Commit Transaction: An L1 transaction submitted by the Lead Sequencer to commit to an L2 batch execution. It is also called Batch Commitment.
Sequencer: An L2 node registered in the designated L1 contract.
Lead Sequencer: The Sequencer currently authorized to build L2 blocks and post L2 batches during a specific L1 block.
Follower: Non-Lead Sequencer nodes, which may be Sequencers awaiting leadership or passive nodes.

How it will work

As outlined earlier, sequencing rights for future blocks are allocated through periodic ticket auctions. To participate, sequencers must register and provide collateral. Each auction occurs during a designated auction period, which spans a defined range of L1 blocks. These auctions are held a certain number of blocks in advance of the allocated period.

During each auction period, a configurable number of tickets are auctioned off. Each ticket grants its holder the right to sequence transactions during one sequencing period within the allocated period. However, at the time of the auction, the specific sequencing period assigned to each ticket remains undetermined. Once the auction period ends, the sequencing periods are randomly assigned (shuffled) among the ticket holders, thereby determining which sequencing period each ticket corresponds to.

Parameters like the amount of tickets auctioned (i.e. amount of sequencing periods per allocated period), the duration of the auction periods, the duration of the sequencing periods, and more, are configurable. This configurability is not merely a feature but a deliberate and essential design choice. The complete list of all configurable parameters can be found under the “Protocol details” section.

Diagram showing leader election process

Sequencers individually opt in before auction period n ends, providing collateral via an L1 contract. This registration is a one-time process per Sequencer.
During the auction, registered Sequencers bid for sequencing rights for a yet-to-be-revealed sequencing period within the allocated period.
At the auction's conclusion, sequencing rights for the sequencing periods within the allocated period are assigned among the ticket holders.
Finally, Sequencers submit L2 batch transactions to L1 during their assigned sequencing period (note: this step does not immediately follow step 3, as additional auctions and sequencing might occur in-between).

In each sequencing period, the Lead Sequencer is initially determined through a bidding process. However, this position can be contested by other Sequencers who are willing to pay a higher price than the winning bid. The number of times such challenges can occur within a single sequencing period is configurable, allowing for control over the stability of the leadership. Should a challenge succeed, the challenging Sequencer takes over as the Lead Sequencer for the remainder of the period, and the original Lead Sequencer is refunded a portion of their bid corresponding to the time left in the period. For example, if a challenge is successful at the midpoint of the sequencing period, the original Lead Sequencer would be refunded half of their bid.

The following example assumes a sequencing period of 1 day, 1 auction challenge per hour with challenge periods of 1 hour.

Diagram showing how challenges work

Auction winner (Sequencer green) starts as the lead Sequencer of the sequencing period.
No one can challenge the lead in the first hour.
During the second hour, the first auction challenge starts, and multiple Sequencers bid to challenge the lead. Finally, the lead Sequencer is overthrown and the new lead (Sequencer blue) starts sequencing.
In the third hour a new auction challenge opens and the former lead Sequencer takes back the lead.
Until the last hour of the sequencing period, the same cycle repeats having many leader changes.

To ensure L2 liveness in this decentralized protocol, Sequencers must participate in a peer-to-peer (P2P) network. The diagram below illustrates this process:

Diagram showing the end-to-end flow of a transaction in the ethrex L2 P2P layer

A User: sends a transaction to the network.
Any node: Gossips in the P2P a received transaction. So every transaction lives in a public distributed mempool
The Lead Sequencer: Produces an L2 block including that transaction.
The Lead Sequencer: Broadcasts the L2 block, including the transaction, to the network via P2P.
Any node: Executes the block, gossips it, and keeps its state up to date.
The Lead Sequencer: Seals the batch in L2.
The Lead Sequencer: Posts the batch to the L1 in a single transaction.
The Lead Sequencer: Broadcasts the "batch sealed" message to the network via P2P.
Any node: Seals the batch locally and gossips the message.
A User: Receives a non-null receipt for the transaction.

Protocol details

Additional Terminology

Next Batch: The L2 batch being built by the lead Sequencer.
Up-to-date Nodes: Nodes that have the last committed batch in their storage and only miss the next batch.
Following: We say that up-to-date nodes are following the lead Sequencer.
Syncing: Nodes are syncing if they are not up-to-date. They’ll stop syncing after they reach the following state.
Verify Transaction: An L1 transaction submitted by anyone to verify a ZK proof to an L2 batch execution.

Network participants

Sequencer Nodes: Nodes that have opted in to serve as Sequencers.
Follower Nodes: State or RPC Nodes.
Prover Nodes:

By default, every ethrex L2 node begins as a Follower Node. A process will periodically query the L1 smart contract registry for the Lead Sequencer's address and update each node's state accordingly.

Network parameters

A list of all the configurable parameters of the network.

Sequencing period duration
Auction period duration
Number of sequencing periods in an allocated period
Time between auction and allocated period
L2 block time
Minimum collateral in ETH for Sequencers registration
Withdrawal delay for Sequencers that quit the protocol
Initial ticket auction price multiplier
Batch verification time limit
Amount of auction challenges within a sequencing period
Challenge period duration
Time between auction challenges
Challenge price multiplier

Lead Sequencer election

Aspiring Lead Sequencers must secure sequencing rights through a Dutch auction in advance, enabling them to post L2 batches to L1.
Sequencing rights are tied to tickets: one ticket grants the right to sequence and post batches during a specific sequencing period.
For each sequencing period within an allocated period, sequencing rights are randomly assigned from the pool of ticket holders.
Each auction period determines tickets for the nth epoch ahead (configurable).
Once Ethereum incorporates deterministic lookahead (e.g., EIP-7917), the Lead Sequencer for a given L1 slot will be the current proposer, provided they hold a ticket.

Auction challenges

During a sequencing period, other Sequencers can pay a higher price than the winning bid to challenge the Lead Sequencer.
This can only happen a configurable number of times per sequencing period.
After a successful challenge, the current Lead Sequencer is replaced by the challenging sequencer for the rest of the Sequencing Period and is refunded the portion of its bid corresponding to the remaining sequencing period (e.g. half of its bid if it loses half of its sequencing period).

Sequencers registry

L1 contract that manages Sequencer registration and ticket auctions for sequencing rights.
Sequencers can register permissionlessly by providing a minimum collateral in ETH.
Sequencers may opt out of an allocated period by not purchasing tickets for that period.
Sequencers can unregister and withdraw their collateral after a delay.

Lead Sequencers role

Build L2 blocks and post L2 batches to the L1 within the sequencing period.
Broadcast to the network:
- Transactions.
- Sequenced blocks as they are built.
- Batch seal messages to prompt the network to seal the batch locally.
Serve state.

Follower nodes role

Broadcast to the network:
- Transactions.
- Sequenced blocks.
- Batch seal messages.
Store incoming blocks sequentially.
Seal batches upon receiving batch seal messages (after storing all batch blocks).
Serve state.
Monitor the L1 contract for batch updates and reorgs.

Prover nodes role

For this stage, it is the Sequencers' responsibility to prove their own batches.
The prover receives the proof generation inputs of a batch from another node and returns a proof.

Batch commitment/proposal

tip

To enrich the understanding of this part, we suggest reading ethrex L2 High-Level docs as this only details the diff with what we already have.

Only lead Sequencer can post batches.
Lead Sequencer batches are accepted during their sequencing period and rejected outside this period.
Batch commitment now includes posting the list of blocks in the batch to the L1 for data availability.

Batch verification

tip

To enrich the understanding of this part, we suggest reading ethrex L2 High-Level docs as this only details the diff with what we already have.

Anyone can verify batches.
Only one valid verification is required to advance the network.
Valid proofs include the blocks of the batch being verified.
In this initial version, the lead Sequencer is penalized if they fail to correctly verify the batches they post.

P2P

Ethrex's L1 P2P network will be used to gossip transactions and for out-of-date nodes to sync.
A new capability will be added for gossipping L2 blocks and batch seal messages (NewBlock and BatchSealed).
The NewBlock message includes an RLP-encoded list of transactions in the block, along with metadata for re-execution and validation. It is signed, and receivers must verify the signature (additional data may be required in practice).
The SealedBatch message specifies the batch number and the number of blocks it contains (additional data may be needed in practice).
Follower Nodes must validate all messages. They add NewBlocks to storage sequentially and seal the batch when the SealedBatch message arrives. If a node's current block is n and it receives block n + 2, it queues n + 2, waits for n + 1, adds it, then processes n + 2. Similarly, a SealedBatch message includes block numbers, and the node delays sealing until all listed blocks are stored.

Syncing

Nodes that join a live network will need to sync up to the latest state.

For this we'll divide nodes into two different states:

Following nodes: These will keep up-to-date via the based P2P.
Syncing nodes: These will sync via 2 different mechanisms:
- P2P Syncing: This is the same as full-sync and snap-sync on L1, but with some changes.
- L1 Syncing: Also used by provers to download batches from the L1.
- In practice, these methods will compete to sync the node.

Downsides

Below we list some of the risks and known issues we are aware of that this protocol introduces. Some of them were highlighted thanks to the feedback of different teams that took the time to review our first draft.

Inconsistent UX: If a Sequencer fails to include its batch submit transaction in the L1, the blocks it contains will simply be reorged out once the first batch of the next sequencer is published. Honest sequencers can avoid this by not building new batches some slots before their turn ends. The next Sequencer can, in turn, start building their first batch earlier to avoid dead times. This is similar to Taiko’s permissioned network, where sequencers coordinate to stop proposing 4 slots before their turn ends to avoid reorgs.
Batch Stealing: Lead Sequencers that fail to publish their batches before their sequencing period ends might have their batches "stolen" by the next Lead Sequencer, which can republish those batches as their own. We can mitigate in the same way as the last point.
Long Finalization Times: Since publishing batches to L1 is infrequent, users might experience long finalization times during low traffic periods. We can solve this by assuming a transaction in an L2 block transmitted through P2P will eventually be published to L1, and punishing Sequencers that don't include some of their blocks in a batch.
Temporary Network Blinding: A dishonest Sequencer may blind the network if they don't gossip blocks nor publish the batches to the L1 as part of the commit transactions' calldata. While the first case alone is mitigated through an L1 syncing mechanism, if the necessary data to sync is not available we can't rely on it. In this case, the prover ensures this doesn't happen by requiring the batch as a public input to the proof verification. That way, the bad batch can't be verified, and will be reverted.
High-Fee Transactions Hoarding: A dishonest Sequencer might not share high-fee transactions with the Lead Sequencer with the hope of processing them once it's their turn to be Lead Sequencer. This is a non-issue, since transaction senders can simply propagate their transaction themselves, either by sending it to multiple RPC providers, or to their own node.
Front-running and Sandwiching Attacks: Lead Sequencers have the right to reorder transactions as they like and we expect they'll use this to extract MEV, including front-running and sandwiching attacks, which impact user experience. We don't have plans to address this at the protocol level, but we expect solutions to appear at the application level, same as in L1.
No Sequencers Scenario: If a sequencing period has no elected Lead Sequencer, we establish Full Anarchy during that period, so anyone can advance the chain. This is a last resort, and we don't expect this happening in practice.

Conclusion

To preserve decentralization and permissionlessness, we chose ticket auctions for leader election, at the expense of preconfirmations and composability.

As mentioned at the beginning, this approach does not fully align with Justin Drake's definition of "based" rollups but is "based enough" to serve as a starting point. Although the current design cannot guarantee that sequencing rights are assigned exclusively to the L1 proposer for each slot, we're interested in achieving this, and will do so once the conditions are met, namely, that L1 proposer lookahead is available.

So what about "based" Ethrex tomorrow? Eventually, there will be enough incentives for L1 proposers to either run their own L2 Sequencers or delegate their L1 rights to an external one. At that stage, the auction and assignment of L2 sequencing rights will be linked to the current L1 proposer or their delegated Sequencer. Periods may also adjust as lookahead tables, such as the Deterministic Lookahead Proposal or RAID, become viable.

This proposal is intentionally minimalistic and adaptable for future refinements. How this will change and adapt to future necessities is something we don't know right now, and we don't care about it until those necessities arrive; this is Lambda's engineering philosophy.

Further considerations

The following are things we are looking to tackle in the future, but which are not blockers for our current work.

Ticket Pricing Strategies.
Delegation Processes.
Preconfirmations.
Bonding.
L1 Reorgs Handling.

References and acknowledgements

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

Context

Intro to based rollups

Based rollups benefits

Based Preconfirmations

Based rollups + extra steps

Misc

Execution tickets

Current based rollups

Rogue (LambdaClass)
Surge (Nethermind)
Taiko Alethia (Taiko Labs)
- Whitelisted preconfers:
Based OP (Gattaca + Lambdaclass)
R1
Minimal Rollup (OpenZeppelin)

Educational sources

Transaction Fees

This page describes the different types of transaction fees that the Ethrex L2 rollup can charge and how they can be configured.

note

Privileged transactions are exempt from all fees.

Priority Fee

The priority fee works exactly the same way as on Ethereum L1.
It is an additional tip paid by the transaction sender to incentivize the sequencer to prioritize the inclusion of their transaction.
The priority fee is always forwarded directly to the sequencer’s coinbase address.

Base Fee

The base fee follows the same rules as the Ethereum L1 base fee. It adjusts dynamically depending on network congestion to ensure stable transaction pricing.
By default, base fees are burned. However, a sequencer can configure a base fee vault address to receive the collected base fees instead of burning them.

ethrex l2 --block-producer.base-fee-vault-address <l2-base-fee-vault-address>

caution

If the base fee vault and coinbase addresses are the same, its balance will change in a way that differs from the standard L1 behavior, which may break assumptions about EVM compatibility.

Operator Fee

The operator fee represents an additional per-gas cost charged by the sequencer to cover the operational costs of maintaining the L2 infrastructure.

This fee works similarly to the base fee — it is multiplied by the gas used for each transaction.
All collected operator fees are deposited into a dedicated operator fee vault address.

To set the operator fee amount:

ethrex l2 --block-producer.operator-fee-per-gas <amount-in-wei>

To set the operator fee vault address:

ethrex l2 --block-producer.operator-fee-vault-address <operator-fee-vault-address>

caution

If the operator fee vault and coinbase addresses are the same, its balance will change in a way that differs from the standard L1 behavior, which may break assumptions about EVM compatibility.

Fee Calculation

When executing a transaction, all gas-related fees are subject to the max_fee_per_gas value defined in the transaction.
This value acts as an absolute cap over the sum of all fee components.

This means that the effective priority fee is capped to ensure the total does not exceed max_fee_per_gas.
Specifically:

effective_priority_fee_per_gas = min(
    max_priority_fee_per_gas,
    max_fee_per_gas - base_fee_per_gas - operator_fee_per_gas
)

Then, the total fees are calculated as:

total_fees = (base_fee_per_gas + operator_fee_per_gas + priority_fee_per_gas) * gas_used

This behavior ensures that transaction senders never pay more than max_fee_per_gas * gas_used, even when the operator fee is enabled.

important

The current effective_gas_price field in the transaction receipt does not include the operator fee component.
Therefore, effective_gas_price * gas_used will only reflect the base + priority portions of the total cost.

important

The eth_gasPrice RPC endpoint has been modified to include the operator_fee_per_gas value when the operator fee mechanism is active.
This means that the value returned by eth_gasPrice corresponds to base_fee_per_gas + operator_fee_per_gas + estimated_gas_tip.

L1 Fees

L1 fees represent the cost of posting data from the L2 to the L1.
Each transaction is charged based on the amount of L1 Blob space it occupies (the size of the transaction when RLP-encoded).

Each time a transaction is executed, the sequencer calculates its RLP-encoded size. Then, the L1 fee for that transaction is computed as:

l1_fee = blob_base_fee_per_byte * tx_encoded_size

An additional amount of gas (l1_gas) is added to the transaction execution so that:

l1_gas * gas_price = l1_fee

This guarantees that the total amount charged to the user never exceeds gas_limit * gas_price, while transparently accounting for the L1 posting cost.
Importantly, this process happens automatically — users do not need to perform any additional steps.
Calls to eth_estimateGas already inherit this behavior and will include the extra gas required for the L1 fee.

The computed L1 fee is deducted from the sender’s balance and transferred to the L1 Fee Vault address.

The blob base fee per byte is derived from the L1 BlobBaseFee.
The L1Watcher periodically fetches the BlobBaseFee from L1 (at a configured interval) and uses it to compute:

blob_base_fee_per_byte = (l1_fee_per_blob_gas * GAS_PER_BLOB) / SAFE_BYTES_PER_BLOB

See the Data availability section here for more information about how data availability works.

L1 fee is deactivated by default. To activate it, configure the L1 fee vault address:

ethrex l2 --block-producer.l1-fee-vault-address <l1-fee-vault-address>

To configure the interval at which the BlobBaseFee is fetched from L1:

ethrex l2 --block-producer.blob-base-fee-update-interval <milliseconds>

caution

If the L1 fee vault and coinbase addresses are the same, its balance will change in a way that differs from the standard L1 behavior, which may break assumptions about EVM compatibility.

Useful RPC Methods

The following custom RPC methods are available to query fee-related parameters directly from the L2 node.
Each method accepts a single argument: the block_number to query historical or current values.

Method Name	Description	Example
`ethrex_getBaseFeeVaultAddress`	Returns the address configured to receive the base fees collected in the specified block.	`ethrex_getBaseFeeVaultAddress {"block_number": 12345}`
`ethrex_getOperatorFeeVaultAddress`	Returns the address configured as the operator fee vault in the specified block.	`ethrex_getOperatorFeeVaultAddress {"block_number": 12345}`
`ethrex_getOperatorFee`	Returns the operator fee per gas value active at the specified block.	`ethrex_getOperatorFee {"block_number": 12345}`
`ethrex_getL1BlobBaseFee`	Returns the L1 blob base fee per gas fetched from L1 and used for L1 fee computation at the specified block.	`ethrex_getL1BlobBaseFee {"block_number": 12345}`

Developer docs

Welcome to the ethrex developer docs!

This section contains documentation on the internals of the project.

To get started first, read the developer installation guide to learn about ethrex and its features. Then you can look into the L1 developer docs or the L2 developer docs

Setting up a development environment for ethrex

Prerequisites

Cloning the repo

The full code of ethrex is available at GitHub and can be cloned using git

git clone https://github.com/lambdaclass/ethrex && cd ethrex

Building the ethrex binary

Ethrex can be built using cargo

To build the client run

cargo build --release --bin ethrex

the following feature can be enable with --features <features>

Feature	Description
default	Enables "rocksdb", "c-kzg", "rollup_storage_sql", "dev", "metrics" features
debug	Enables debug mode for LEVM
dev	Makes the --dev flag available
metrics	Enables metrics gathering for use with a monitoring stack
c-kzg	Enables the c-kzg crate instead of kzg-rs
rocksdb	Enables rocksdb as the database for the ethereum state
rollup_storage_sql	Enables sql as the database for the L2 batch data
sp1	Enables the sp1 backend for the L2 prover
risc0	Enables the risc0 backend for the L2 prover
gpu	Enables CUDA support for the zk backends risc0 and sp1

Bolded are features enabled by default

Additionally the environment variable COMPILE_CONTRACTS can be set to true to enable embedding the solidity contracts used by the rollup, into the binary to enable the L2 dev mode.

Building the docker image

The Dockerfile is located at the root of the repository and can be built by running

docker build -t ethrex .

The BUILD_FLAGS argument can be used to pass flags to cargo, for example

docker build -t ethrex --build-arg BUILD_FLAGS="--features <features>" .

L1 Developer Docs

Welcome to the ethrex L1 developer documentation!

This section provides information about the internals of the L1 side of the project.

Ethrex as a local development node

Prerequisites

This guide assumes you've read the dev installation guide

Dev mode

In dev mode ethrex acts as a local Ethereum development node it can be run with the following command

ethrex --dev

Then you can use a tool like rex to make sure that the network is advancing

rex block-number

Rich account private keys are listed at the folder fixtures/keys/private_keys_l1.txt located at the root of the repo. You can then use these keys to deploy contracts and send transactions in the localnet.

Importing blocks

The simplest task a node can do is import blocks offline. We would do so like this:

Prerequisites

This guide assumes you've read the dev installation guide

Import blocks

# Execute the import
# Notice that the .rlp file is stored with Git LFS, it needs to be downloaded before importing
ethrex --network fixtures/genesis/perf-ci.json import  fixtures/blockchain/l2-1k-erc20.rlp

The network argument is common to all ethrex commands. It specifies the genesis file, or a public network like holesky. This is the starting state of the blockchain.
The import command means that this node will not start rpc endpoints or peer to peer communication. It will just read a file, parse the blocks, execute them, and save the EVM state (accounts info and storage) after each execution.
The file is an RLP encoded file with a list of blocks.

Block execution

The CLI import subcommand executes cmd/ethrex/cli.rs:import_blocks, which can be summarized as:

#![allow(unused)]
fn main() {
let store = init_store(&datadir, network).await;
let blockchain = init_blockchain(evm, store.clone());
for block in parse(rlp_file) {
    blockchain.add_block(block)
}
}

The blockchain struct is our main point of interaction with our data. It contains references to key structures like our store (key-value db) and the EVM engine (knows how to execute transactions).

Adding a block is performed in crates/blockchain/blockchain.rs:add_block, and performs several tasks:

Block execution (execute_block).
1. Pre-validation. Checks that the block parent is present, that the base fee matches the parent's expectations, timestamps, header number, transaction root and withdrawals root.
2. VM execution. The block contains all the transactions, which is all needed to perform a state transition. The VM has a reference to the store, so it can get the current state to apply transactions on top of it.
3. Post execution validations: gas used, receipts root, requets hash.
4. The VM execution does not mutate the store itself. It returns a list of all changes that happened in execution so they can be applied in any custom way.
Post-state storage (store_block)
1. apply_account_updates gets the pre-state from the store, applies the updates to get an updated post-transition-state, calculates the root and commits the new state to disk.
2. The state root is a merkle root, a cryptographic summary of a state. The one we just calculated is compared with the one in the block header. If it matches, it proves that your node's post-state is the same as the one the block producer reached after executing that same block.
3. The block and the receipts are saved to disk.

States

In ethereum the first state is determined by the genesis file. After that, each block represents a state transition. To be formal about it, if we have a state $S$ and a block $B$ , we can define $B^{'} = f (S, B)$ as the application of a state transition function.

This means that a blockchain, internally, looks like this.

flowchart LR
    Sg["Sg (genesis)"]
    S1a["S1"]
    S2a["S2"]
    S3a["S3"]

    Sg -- "f(Sg, B1)" --> S1a
    S1a -- "f(S1, B2)" --> S2a
    S2a -- "f(S2, B3)" --> S3a

We start from a genesis state, and each time we add a block we generate a new state. We don't only save the current state ( $S_{3}$ ), we save all of them in the DB after execution. This seems wasteful, but the reason will become more obvious very soon. This means that we can get the state for any block number. We say that if we get the state for block number one, we actually are getting the state right after applying B1.

Due to the highly available nature of ethereum, sometimes multiple different blocks can be proposed for a single state. This creates what we call "soft forks".

flowchart LR
    Sg["Sg (genesis)"]
    S1a["S1"]
    S2a["S2"]
    S3a["S3"]
    S1b["S1'"]
    S2b["S2'"]
    S3b["S3'"]

    Sg -- "f(Sg, B1)" --> S1a
    S1a -- "f(S1, B2)" --> S2a
    S2a -- "f(S2, B3)" --> S3a

    Sg -- "f(Sg, B1')" --> S1b
    S1b -- "f(S1', B2')" --> S2b
    S2b -- "f(S2', B3')" --> S3b

This means that for a single block number we actually have different post-states, depending on which block we executed. In turn, this means that using a block number is not a reliable way of getting a state. To fix this, what we do is calculate the hash of a block, which is unique, and use that as an identifier for both the block and its corresponding block state. In that way, if I request the DB the state for hash(B1) it understands that I'm looking for S1, whereas if I request the DB the state for hash(B1') I'm looking for S1'.

How we determine which is the right fork is called Fork choice, which is not done by the execution client, but by the consensus client. What concerns to us is that if we currently think we are on S3 and the consensus client notifies us that actually S3' is the current fork, we need to change our current state to that one. That means that we need to save every post-state in case we need to change forks. This changing of the nodes perception of the correct soft fork to a different one is called reorg.

VM - State interaction

As mentioned in the previous point, the VM execution doesn't directly mutate the store. It just calculates all necessary updates. There's an important clarification we need to go through about the starting point for that calculation.

This is a key piece of code in Blockchain.execute_block:

#![allow(unused)]
fn main() {
let vm_db = StoreVmDatabase::new(self.storage.clone(), parent_header);
let mut vm = Evm::new(vm_db);
let execution_result = vm.execute_block(block)?;
let account_updates = vm.get_state_transitions()?;
}

The VM is a transient object. It is created with an engine/backend (LEVM or REVM) and a db reference. It is discarded after executing each block.

The StoreVmDatabase is just an implementation of the VmDatabase trait, using our Store (reference to a key-value store). It's an adapter between the store and the vm and allows the VM to not depend on a concrete DB.

The main piece of context a VM DB needs to be created is the parent_hash, which is the hash of the parent's block. As we mentioned previously, this hash uniquely identifies an ethereum state, so we are basically telling the VM what it's pre-state is. If we give it that, plus the block, the VM can execute the state-transition function $S^{'} = f (S, B)$ previously mentioned.

The VmDatabase context just requires the implementation of the following methods:

#![allow(unused)]
fn main() {
fn get_account_info(&self, address: Address) -> Result<Option<AccountInfo>, EvmError>;
fn get_storage_slot(&self, address: Address, key: H256) -> Result<Option<U256>, EvmError>;
fn get_block_hash(&self, block_number: u64) -> Result<H256, EvmError>;
fn get_chain_config(&self) -> Result<ChainConfig, EvmError>;
fn get_account_code(&self, code_hash: H256) -> Result<Bytes, EvmError>;
}

That is, it needs to know how to get information about accounts, about storage, get a block hash according to a specific number, get the config, and the account code for a specific hash.

Internally, the StoreVmDatabase implementation just calls the db for this. For example:

#![allow(unused)]
fn main() {
fn get_account_info(&self, address: Address) -> Result<Option<AccountInfo>, EvmError> {
    self.store
        .get_account_info_by_hash(self.block_hash, address)
        .map_err(|e| EvmError::DB(e.to_string()))
}
}

You may note that the get_account_info_by_hash receives not only the address, but also the block hash. That is because it doesn't get the account state for the "current" state, it gets it for the post-state of the parent block. That is, the pre-state for the state transition. And this makes sense: we don't want to apply a transaction anywhere, we want to apply it precisely on top of the parent's state, so that's where we'll be getting all of our state.

What is state anyway

The ethereum state is, logically, two things: accounts and their storage slots. If we were to represent them in memory, they would be something like:

#![allow(unused)]
fn main() {
pub struct VmState {
    accounts: HashMap<H256, Option<AccountState>>,
    storage: HashMap<H256, HashMap<H256, Option<U256>>>,
}
}

The accounts are indexed by the hash of their address. The storage has a two level lookup: an index by account address hash, and then an index by hashed slot. The reasons why we use hashes of the addresses and slots instead of using them directly is an implementation detail.

This flat key-value representation is what we usually call a snapshot. To write and get state, it would be enough and efficient to have a table in the db with some snapshot in the past and then the differences in each account and storage each block. This are precisely the account updates, and this is precisely what we do in our snapshots implementation.

However, we also need to be able to efficiently summarize a state, which is done using a structure called the Merkle Patricia Trie (MPT). This is a big topic, not covered by this document. A link to an in-detail document will be added soon. The most important part of it is that it's a merkle tree and we can calculate it's root/hash to summarize a whole state. When a node proposes a block, the root of the post-state is included as metadata in the header. That means that after executing a block, we can calculate the root of the resulting post-state MPT and compare it with the metadata. If it matches, we have a cryptographic proof that both nodes arrived at the same conclusion.

This means that we will need to maintain both a snapshot (for efficient reads) and a trie (for efficient summaries) for every state in the blockchain. Here's an interesting blogpost by the go ethereum (geth) team explaning this need in detail: https://blog.ethereum.org/2020/07/17/ask-about-geth-snapshot-acceleration

TODO

Imports

Add references to our code for MPT and snapshots.
What account updates are. What does it mean to apply them.

Live node block execution

Engine api endpoints (fork choice updated with no attrs, new payload).
applying fork choice and reorg.
JSON RPC endpoints to get state.

Block building

Mempool and P2P.
Fork choice updated with attributes and get_payload.
Payload building.

Syncing on node startup

Discovery.
Getting blocks and headers via p2p.
Snap sync.

Quick Start (L1 localnet)

This page will show you how to quickly spin up a local development network with ethrex.

Prerequisites

Starting a local devnet

make localnet

This make target will:

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

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

Stopping a local devnet

To stop everything, simply run:

make stop-localnet

Metrics

Ethereum Metrics Exporter

We use the Ethereum Metrics Exporter, a Prometheus metrics exporter for Ethereum execution and consensus nodes, to gather metrics during syncing for L1. The exporter uses the prometheus data source to create a Grafana dashboard and display the metrics. For the syncing to work there must be a consensus node running along with the execution node.

Currently we have two make targets to easily start an execution node and a consensus node on either hoodi or holesky, and display the syncing metrics. In both cases we use a lighthouse consensus node.

Quickstart guide

Make sure you have your docker daemon running.

Code Location: The targets are defined in tooling/sync/Makefile.

How to Run:

# Navigate to tooling/sync directory
cd tooling/sync

# Run target for hoodi
make start-hoodi-metrics-docker

 # Run target for holesky
make start-holesky-metrics-docker

To see the dashboards go to http://localhost:3001. Use “admin” for user and password. Select the Dashboards menu and go to Ethereum Metrics Exporter (Single) to see the exported metrics.

To see the prometheus exported metrics and its respective requests with more detail in case you need to debug go to http://localhost:9093/metrics.

Running the execution node on other networks with metrics enabled

A docker-compose is used to bundle prometheus and grafana services, the *overrides files define the ports and mounts the prometheus' configuration file. If a new dashboard is designed, it can be mounted only in that *overrides file. A consensus node must be running for the syncing to work.

To run the execution node on any network with metrics, the next steps should be followed:

Build the ethrex binary for the network you want (see node options in CLI Commands) with the metrics feature enabled.
Enable metrics by using the --metrics flag when starting the node.
Set the --metrics.port cli arg of the ethrex binary to match the port defined in metrics/provisioning/prometheus/prometheus_l1_sync_docker.yaml

Run the docker containers:

cd metrics

docker compose -f docker-compose-metrics.yaml -f docker-compose-metrics-l1.overrides.yaml up

For more details on running a sync go to tooling/sync/readme.md.

Ethrex L1 Performance Dashboard (Oct 2025)

Our Grafana dashboard provides a comprehensive overview of key metrics to help developers and operators ensure optimal performance and reliability of their Ethrex nodes. The only configured datasource today is prometheus, and the job variable defaults to ethrex L1, which is the job configured by default in our provisioning.

Overview

How to use it

Use the network variable (discovered via the consensus config metric) to scope the view by network, then pick one or more instance entries. Every panel honors these selectors. Tip: several panels rely on Grafana transforms such as Organize fields, Join by field, Filter by value, and Group by—keep those in mind if you customize the layout.

dashboard variables

Execution and consensus summary

Execution Client

Confirms the execution client name and build that each monitored instance is running so you can spot mismatched deployments quickly.

Execution Client

Consensus Config

Shows the consensus configuration reported by ethereum-metrics-exporter, helping you verify which network the node is running.

Consensus Config

Consensus Fork

Highlights the active fork reported by ethereum-metrics-exporter, which is a useful signal during planned upgrades.

Consensus Fork

Block processing

Row panels showing key block processing metrics across all selected instances.

Block Processing row

Gas Used %

Tracks how much of the block gas limit is consumed across instances, surfacing heavy traffic or underfilled blocks at a glance.

Gas Used %

Ggas/s

Charts gigagas per second to compare execution throughput between nodes and reveal sustained load versus isolated spikes.

Ggas/s

Block Height

Plots the head block seen by each instance so you can immediately detect stalled sync or lagging nodes.

Block Height

Ggas/s by Block

Scatter view that ties throughput to the specific block number once all selected instances agree on the same head, making block-level investigations straightforward.

Ggas by Block

Limitations: This panel only shows data when all selected instances agree on the same head block, and it doesn't handle reorgs gracefully. Here are a couple of things to have in mind when looking at it:

During reorgs, we might see weird shapes in the data, with lines at a certain block connected to past ones when more than one slot reorgs happen.
We could see double measurements for the same block number if reorgs on the same block occur.
Mean could vary when adding or removing instances, as only blocks agreed upon by all selected instances are shown.

Block Time

Estimates per-block execution time and lines it up with block numbers, helping you correlate latency spikes with particular blocks.

Block Time

Limitations: This panel has the same limitations as the "Ggas/s by Block" panel above, as it relies on the same logic to align blocks across instances.

Block execution breakdown

This row repeats a pie chart for each instance showing how execution time splits between storage reads, account reads, and non-database work so you can confirm performance tuning effects.

Block Execution Breakdown

Process and server info

Row panels showing process-level and host-level metrics to help you monitor resource usage and spot potential issues.

Process & Server info row

Uptime

Displays time since the Ethrex process started. [need proper instance labels]

Uptime

Threads

Shows the number of tokio process threads in use. [need proper instance labels]

Threads

Open FDs

Reports current file descriptor usage so you can compare against limits. [need proper instance labels]

Open FDs

Open FDs Historic

Time-series view of descriptor usage to spot gradual leaks or sudden bursts tied to workload changes.

Open FDs Historic

Datadir Size

Tracks database footprint growth, helping you plan disk needs and confirming pruning/compaction behavior. Datadir Size

Node CPU (avg. cores used)

Shows effective CPU cores consumed by each instance, separating sustained computation from short-lived bursts.

Node CPU

Node Memory (RSS)

Follows the resident memory footprint of the Ethrex process so you can investigate leaks or pressure.

Node Memory

Host CPU Utilization (%)

Uses node exporter metrics to track whole-host CPU load and distinguish client strain from other processes on the server.

Host CPU Utilization

Host RAM (GiB) - Used vs Total

Compares used versus total RAM to highlight when machines approach memory limits and need attention.

Host RAM

Block building (WIP)

This collapsed row offers a combined view of the block building base fee, gigagas per second during payload construction, and the time the builder spends assembling blocks. These panels are works in progress, collapsed by default, and may be refined over time.

Block building wip

Testing

The ethrex project runs several suites of tests to ensure proper protocol implementation

Ethereum foundation tests

These are the official execution spec tests there two kinds state tests and blockchain tests, you can execute them with:

State tests

The state tests are individual transactions not related one to each other that test particular behavior of the EVM. Tests are usually run for multiple forks and the result of execution may vary between forks. See docs.

To run the test first:

cd tooling/ef_tests/state

then download the test vectors:

make download-evm-ef-tests

then run the tests:

make run-evm-ef-tests

Blockchain tests

The blockchain tests test block validation and the consensus rules of the Ethereum blockchain. Tests are usually run for multiple forks. See docs.

To run the tests first:

cd tooling/ef_tests/blockchain

then run the tests:

make test-levm

Hive tests

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 set 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.90.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 tests

We run some assertoor 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

eoa-transaction-test

assertoor-blob

blob-transaction-test
Custom el-stability-check

For reference on each individual check see the assertoor-wiki

Run

Example run:

cargo run --bin ethrex -- --network fixtures/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.

Rust tests

Crate Specific Tests

Rust unit tests that you can run like this:

make test CRATE=<crate>

For example:

make test CRATE="ethrex-blockchain"

Load tests

Before starting, consider increasing the maximum amount of open files for the current shell with the following command:

ulimit -n 65536

To run a load test, first run the node using a command like the following in the root folder:

cargo run --bin ethrex --release -- --network fixtures/genesis/load-test.json --dev

There are currently three different load tests you can run:

The first one sends regular transfers between accounts, the second runs an EVM-heavy contract that computes fibonacci numbers, the third a heavy IO contract that writes to 100 storage slots per transaction.

# Eth transfer load test
make load-test

# ERC 20 transfer load test
make load-test-erc20

# Tests a contract that executes fibonacci (high cpu)
make load-test-fibonacci

# Tests a contract that makes heavy access to storage slots
make load-test-io

L2 Developer Docs

Welcome to the ethrex L2 developer documentation!

This section provides information about the internals of the L2 side of the project.

Ethrex as a local L2 development node

Prerequisites

This guide assumes you've read the dev installation guide
An Ethereum utility tool like rex

Dev mode

In dev mode ethrex acts as a local Ethereum development node and a local layer 2 rollup

ethrex l2 --dev

after running the command the ethrex monitor will open with information about the status of the local L2.

The default port of the L1 JSON-RPC is 8545 you can test it by running

rex block-number http://localhost:8545

The default port of the L2 JSON-RPC is 1729 you can test it by running

rex block-number http://localhost:1729

Guides

For more information on how to perform certain operations, go to Guides.

Running integration tests

In this section, we will explain how to run integration tests for ethrex L2 with the objective of validating the correct functioning of our stack in our releases. For this, we will use ethrex as a local L2 dev node.

Prerequisites

Install the latest ethrex release or pre-release binary following the instructions in the Install ethrex (binary distribution) section.
For running the tests, you'll need a fresh clone of ethrex.
(Optional for troubleshooting)
- An Ethereum utility tool like rex.
- jq for JSON processing.
- curl for making HTTP requests.

Setting up the environment

Our integration tests assume that there is an ethrex L1 node, an ethrex L2 node, and an ethrex L2 prover up and running. So before running them, we need to start the nodes.

Running ethrex L2 dev node

For this, we are using the ethrex l2 --dev command, which does this job for us. In one console, run the following:

./ethrex l2 --dev \
--committer.commit-time 150000 \
--block-producer.block-time 1000 \
--block-producer.base-fee-vault-address 0x000c0d6b7c4516a5b274c51ea331a9410fe69127 \
--block-producer.operator-fee-vault-address 0xd5d2a85751b6F158e5b9B8cD509206A865672362 \
--block-producer.l1-fee-vault-address 0x45681AE1768a8936FB87aB11453B4755e322ceec \
--block-producer.operator-fee-per-gas 1000000000 \
--no-monitor

Read the note below for explanations about the flags used.

note

ethrex's MPT implementation is path-based, and the database commit threshold is set to 128. In simple words, the latter implies that the database only stores the state 128 blocks before the current one (e.g., if the current block is block 256, then the database stores the state at block 128), while the state of the blocks within lives in in-memory diff layers (which are lost during node shutdowns). In ethrex L2, this has a direct impact since if our sequencer seals batches with more than 128 blocks, it won't be able to retrieve the state previous to the first block of the batch being sealed because it was pruned; therefore, it won't be able to create new batches to send to L1. To solve this, after a batch is sealed, we create a checkpoint of the database at that point to ensure the state needed at the time of commitment is available for the sequencer. For this test to be valuable, we need to ensure this edge case is covered. To do so, we set up an L2 with batches of approximately 150 blocks. We achieve this by setting the flag --block-producer.block-time to 1 second, which specifies the interval in milliseconds for our builder to build an L2 block. This means the L2 block builder will build blocks every 1 second. We also set the flag --committer.commit-time to 150 seconds (2 minutes and 30 seconds), which specifies the interval in milliseconds in which we want to commit to the L1. This ensures that enough blocks are included in each batch. The L2's gas pricing mechanism is tested in the integration tests, so we need to set the following flags to ensure the L2 gas pricing mechanism is active:

--block-producer.base-fee-vault-address
--block-producer.operator-fee-vault-address
--block-producer.l1-fee-vault-address
--block-producer.operator-fee-per-gas

Read more about ethrex L2 gas pricing mechanism here. We set the flag --no-monitor to disable the built-in monitoring dashboard since it is not needed for running the integration tests.

So far, we have an ethrex L1 and an ethrex L2 node up and running. We only miss the ethrex L2 prover, which we are going to spin up in exec mode, meaning that it won't generate ZK proofs.

Running ethrex L2 prover

In another terminal, run the following to spin up an ethrex L2 prover in exec mode:

./ethrex l2 prover \
--backend exec \
--proof-coordinators http://localhost:3900

note

The flag --proof-coordinators is used to specify one or more proof coordinator URLs. This is so because the prover is capable of proving ethrex L2 batches from multiple sequencers. We are particularly setting it to localhost:3900 because the ethrex l2 --dev command uses the port 3900 for the proof coordinator by default.
To see more about the proof coordinator, read the ethrex L2 sequencer and ethrex L2 prover sections.

Running the integration tests

During the execution of ethrex l2 --dev, a .env file is created and filled with environment variables containing contract addresses. This .env file is always needed for dev environments, so we need it for running the integration tests. Therefore, before running the integration tests, copy the .env file into ethrex/cmd:

cp .env ethrex/cmd

Finally, in another terminal (should be a third one at this point), change your current directory to ethrex/crates/l2 and run:

make test

FAQ

What should I expect?

Once you run make test, you should see the output of the tests being executed one after another. The tests will interact with the ethrex L2 node and the ethrex L2 prover that you started previously. If everything is set up correctly, all tests should pass successfully.

How long do the tests take to run?

The current configuration of the L2 node (with a block time of 1 second and a commit time of 150 seconds) means that each batch will contain approximately 150 blocks. Given this setup, the integration tests typically take around 30 to 45 minutes to complete, depending the timing in which you performed the steps.

I think my tests are taking too long, how can I debug this?

If your tests are taking significantly longer than expected, you are likely watching the Retrying to get message proof for tx ... counter in the tests terminal increase without progressing. Let's unveil what is happening here. This message indicates that the transaction has been included in an L2 block, but that block has not yet been included in a batch. There's no current way to fairly estimate when the block including the transaction will be included in a batch, but we can see how far is the block from being included.

Using the hash of the transaction shown in the log message, you can check the status of the transaction using an Ethereum utility tool like rex. Run the following commands in a new terminal:

Get the block number where the transaction was included (replace <TX_HASH> with the actual transaction hash):
```
rex l2 tx <TX_HASH>
```
As the block is assumed to not be included in a batch yet, we need to check which blocks have been included in the latest batch. rex does not have a command for this yet, so we will use curl to make a JSON-RPC call to the ethrex L2 node. Run the following command:
```
curl -X POST http://localhost:1729 \
-H "Content-Type: application/json" \
-d '{
"jsonrpc":"2.0",
"method":"ethrex_batchNumber",
"params": [],
"id":1
}' | jq .result
```

Once you have the batch number, you can get the range of blocks included in that batch by running the following command (replace <BATCH_NUMBER> with the actual batch number obtained in the previous step, in hex format, e.g., 0x1):

curl -X POST http://localhost:1729 \
-H "Content-Type: application/json" \
-d '{
    "jsonrpc":"2.0",
    "method":"ethrex_getBatchByNumber",
    "params": ["<BATCH_NUMBER>", false],
    "id":1
}' | jq .result.first_block,.result.last_block

Compare the block number obtained in step 1 with the range of blocks obtained in step 3 to see how far the block is from being included in a batch. To have a rough estimate, take into account the mean of blocks that are being included into the batches and consider that a batch is sealed approximately every 150 seconds (2 minutes and 30 seconds) based on the current configuration.

Should I worry about the periodic warning logs of the L2 prover?

Logs are being constantly improved to provide better clarity. However, during the execution of the integration tests, you might notice periodic warning logs from the L2 prover indicating that there are no new batches to prove. These warnings are expected behavior in this testing scenario and can be safely ignored.

The tests are failing, what should I do?

If the tests are failing, first ensure that both the ethrex L2 node and the ethrex L2 prover are running correctly without any errors. Check their logs for any issues. If everything seems fine, try restarting both services and rerun the tests. Ensure that your configuration files (e.g., .env) are correctly set up and that all required environment variables are defined. If the problem persists, consider reaching out to the ethrex community or support channels for further assistance.

Troubleshooting

note

This is a placeholder for future troubleshooting tips. Please report any issues you encounter while running the integration tests to help us improve this section.

Debug Mode

Debug mode currently enables printing in solidity by using a print() function that does an MSTORE with a specific offset to toggle the "print mode". If the VM is in debug mode it will recognize the offset as the "key" for enabling/disabling print mode. If print mode is enabled, MSTORE opcode stores into a buffer the data that the user wants to print, and when there is no more data left to read it prints it and disables the print mode so that execution continues normally. You can find the solidity code in the fixtures of this repository. It can be tested with the PrintTest contract and it can be imported into another contracts.

ethrex-replay

A tool for executing and proving Ethereum blocks, transactions, and L2 batches — inspired by starknet-replay.

Features

L1

Feature	Description
`ethrex-replay block`	Replay a single block.
`ethrex-replay blocks`	Replay a list of specific block numbers, a range of blocks, or from a specific block to the latest (see `ethrex-replay blocks --help`)
`ethrex-replay block-composition`
`ethrex-replay custom`	Build your block before to replay it.
`ethrex-replay transaction`	Replay a single transaction of a block.
`ethrex-replay cache`	Generate witness data prior to block replay (see `ethrex-replay cache --help`)

L2

Feature	Description
`ethrex-replay l2 batch`
`ethrex-replay l2 block`
`ethrex-replay l2 custom`
`ethrex-replay l2 transaction`

Supported Clients

Client	`ethrex-replay block`	notes
ethrex	✅	`debug_executionWitness`
reth	✅	`debug_executionWitness`
geth	✅	`eth_getProof`
nethermind	✅	`eth_getProof`
erigon	❌	V3 supports `eth_getProof` only for latest block
besu	❌	Doesn't return proof for non-existing accounts

We support any other client that is compliant with eth_getProof or debug_executionWitness endpoints. You can set the max requests per second to the RPC url with the environment variable REPLAY_RPC_RPS. This is particularly useful when using eth_getProof. Default is 10.

Execution of some particular blocks with the eth_getProof method won't work with zkVMs. But without using these it should work for any block. Read more about this in FAQ. Also, when running against a full node using eth_getProof if for some reason information retrieval were to take longer than 25 minutes it would probably fail because the node may have pruned its state (128 blocks * 12 seconds = 25,6 min), normally it doesn't take that much but be wary of that.

Supported zkVM Replays (execution & proving)

✅: supported. ⚠️: supported, but flaky. 🔜: to be supported.

zkVM	Hoodi	Sepolia	Mainnet	Public ethrex L2s
RISC0	✅	✅	✅	✅
SP1	✅	✅	✅	✅
OpenVM	⚠️	🔜	🔜	🔜
ZisK	🔜	🔜	⚠️	🔜
Jolt	🔜	🔜	🔜	🔜
Nexus	🔜	🔜	🔜	🔜
Pico	🔜	🔜	🔜	🔜
Ziren	🔜	🔜	🔜	🔜

Getting Started

Dependencies

These dependencies are optional, install them only if you want to run with the features risc0 or sp1 respectively. Make sure to use the correct versions of these.

RISC0

curl -L https://risczero.com/install | bash
rzup install cargo-risczero 3.0.3
rzup install risc0-groth16
rzup install rust

SP1

curl -L https://sp1up.succinct.xyz | bash
sp1up --version 5.0.8

Installation

From Cargo

# L1 Replay

## Install without features for vanilla execution (no prover backend)
cargo install --locked --git https://github.com/lambdaclass/ethrex.git ethrex-replay

## Install for CPU execution/proving with SP1
cargo install --locked --git https://github.com/lambdaclass/ethrex.git ethrex-replay --features sp1

## Install for CPU execution/proving with RISC0
cargo install --locked --git https://github.com/lambdaclass/ethrex.git ethrex-replay --features risc0

## Install for GPU execution/proving with SP1
cargo install --locked --git https://github.com/lambdaclass/ethrex.git ethrex-replay --features sp1,gpu

## Install for GPU execution/proving with RISC0
cargo install --locked --git https://github.com/lambdaclass/ethrex.git ethrex-replay --features risc0,gpu

# L2 Replay

## Install without features for vanilla execution (no prover backend)
cargo install --locked --git https://github.com/lambdaclass/ethrex.git ethrex-replay --features l2

## Install for CPU execution/proving with SP1
cargo install --locked --git https://github.com/lambdaclass/ethrex.git ethrex-replay --features l2,sp1

## Install for CPU execution/proving with RISC0
cargo install --locked --git https://github.com/lambdaclass/ethrex.git ethrex-replay --features l2,risc0

## Install for GPU execution/proving with SP1
cargo install --locked --git https://github.com/lambdaclass/ethrex.git ethrex-replay --features l2,sp1,gpu

## Install for GPU execution/proving with RISC0
cargo install --locked --git https://github.com/lambdaclass/ethrex.git ethrex-replay --features l2,risc0,gpu

Run from Source

git clone git@github.com:lambdaclass/ethrex.git

cd ethrex

# L1 replay

## Vanilla execution (no prover backend)
cargo r -r -p ethrex-replay -- <COMMAND> [ARGS]

## SP1 backend
cargo r -r -p ethrex-replay --features sp1 -- <COMMAND> [ARGS]

## SP1 backend + GPU
cargo r -r -p ethrex-replay --features sp1,gpu -- <COMMAND> [ARGS]

## RISC0 backend
cargo r -r -p ethrex-replay --features risc0 -- <COMMAND> [ARGS]

## RISC0 backend + GPU
cargo r -r -p ethrex-replay --features risc0,gpu -- <COMMAND> [ARGS]

# L2 replay

## Vanilla execution (no prover backend)
cargo r -r -p ethrex-replay --features l2 -- <COMMAND> [ARGS]

## SP1 backend
cargo r -r -p ethrex-replay --features l2,sp1 -- <COMMAND> [ARGS]

## SP1 backend + GPU
SP1_PROVER=cuda cargo r -r -p ethrex-replay --features l2,sp1,gpu -- <COMMAND> [ARGS]

## RISC0 backend
cargo r -r -p ethrex-replay --features l2,risc0 -- <COMMAND> [ARGS]

## RISC0 backend + GPU
cargo r -r -p ethrex-replay --features l2,risc0,gpu -- <COMMAND> [ARGS]

Features

The following table lists the available features for ethrex-replay. To enable a feature, use the --features flag with cargo install, specifying a comma-separated list of features.

Feature	Description
`gpu`	Enables GPU support with SP1 or RISC0 backends (must be combined with one of each features, e.g. `sp1,gpu` or `risc0,gpu`)
`risc0`	Execution and proving is done with RISC0 backend
`sp1`	Execution and proving is done with SP1 backend
`l2`	Enables L2 batch execution and proving (can be combined with SP1 or RISC0 and GPU features, e.g. `sp1,l2,gpu`, `risc0,l2,gpu`, `sp1,l2`, `risc0,l2`)
`jemalloc`	Use jemalloc as the global allocator. This is useful to combine with tools like Bytehound and Heaptrack for memory profiling
`profiling`	Useful to run with tools like Samply.

Running Examples

Examples ToC

important

The following instructions assume that you've installed ethrex-replay as described in the Getting Started section.

Execute a single block from a public network

note

If BLOCK_NUMBER is not provided, the latest block will be executed.
If ZKVM is not provided, no zkVM will be used for execution.
If RESOURCE is not provided, CPU will be used for execution.
If ACTION is not provided, only execution will be performed.

ethrex-replay block <BLOCK_NUMBER> --zkvm <ZKVM> --resource <RESOURCE> --action <ACTION> --rpc-url <RPC_URL>

Prove a single block

note

If BLOCK_NUMBER is not provided, the latest block will be executed and proved.
Proving requires a prover backend to be enabled during installation (e.g., sp1 or risc0).
Proving with GPU requires the gpu feature to be enabled during installation.
If proving with SP1, add SP1_PROVER=cuda to the command to enable GPU support.

ethrex-replay block <BLOCK_NUMBER> --zkvm <ZKVM> --resource gpu --action prove --rpc-url <RPC_URL>

Execute an L2 batch

ethrex-replay l2 batch --batch <BATCH_NUMBER> --execute --rpc-url <RPC_URL>

Prove an L2 batch

note

Proving requires a prover backend to be enabled during installation (e.g., sp1 or risc0). Proving with GPU requires the gpu feature to be enabled during installation.
If proving with SP1, add SP1_PROVER=cuda to the command to enable GPU support.
Batch replay requires the binary to be run/compiled with the l2 feature.

ethrex-replay l2 batch --batch <BATCH_NUMBER> --prove --rpc-url <RPC_URL>

Execute a transaction

note

L2 transaction replay requires the binary to be run/compiled with the l2 feature.

ethrex-replay transaction <TX_HASH> --execute --rpc-url <RPC_URL>

ethrex-replay l2 transaction <TX_HASH> --execute --rpc-url <RPC_URL>

Plot block composition

ethrex-replay block-composition --start-block <START_BLOCK> --end-block <END_BLOCK> --rpc-url <RPC_URL> --network <NETWORK>

Benchmarking & Profiling

Run Samply

We recommend building in release-with-debug mode so that the flamegraph is the most accurate.

cargo build -p ethrex-replay --profile release-with-debug --features <FEATURES>

On zkVMs

important

For profiling zkVMs like SP1 the ethrex-replay binary must be built with the profiling feature enabled.
The TRACE_SAMPLE_RATE environment variable controls the sampling rate (in milliseconds). Adjust it according to your needs.

TRACE_FILE=output.json TRACE_SAMPLE_RATE=1000 target/release-with-debug/ethrex-replay <COMMAND> [ARGS]

Execution without zkVMs

samply record target/release-with-debug/ethrex-replay <COMMAND> --no-zkvm [OTHER_ARGS]

Run Bytehound

important

The following requires Jemalloc and Bytehound to be installed.
The ethrex-replay binary must be built with the jemalloc feature enabled.

export MEMORY_PROFILER_LOG=warn
LD_PRELOAD=/path/to/bytehound/preload/target/release/libbytehound.so:/path/to/libjemalloc.so  ethrex-replay <COMMAND> [ARGS]

Run Heaptrack

important

The following requires Jemalloc and Heaptrack to be installed.
The ethrex-replay binary must be built with the jemalloc feature enabled.
Note that Heaptrack is a Linux profiler, so it won't work natively on macOS.

LD_PRELOAD=/path/to/libjemalloc.so heaptrack ethrex-replay <COMMAND> [ARGS]
heaptrack_print heaptrack.<program>.<pid>.gz > heaptrack.stacks

Check All Available Commands

Run:

cargo r -r -p ethrex-replay -- --help

FAQ

What's the difference between `eth_getProof` and `debug_executionWitness`?

eth_getProof gets the proof for a particular account and the chosen storage slots. debug_executionWitness gets the whole execution witness necessary to execute a block in a stateless manner.

The former endpoint is implemented by all execution clients and you can even find it in RPC Providers like Alchemy, the latter is only implemented by some execution clients and you can't find it in RPC Providers.

When wanting to execute a historical block we tend to use the eth_getProof method with an RPC Provider because it will be the most reliable, other way is using it against a Hash-Based Archive Node but this would be too heavy to host ourselves (20TB at least). This method is slow because it performs many requests but it's very flexible.

If instead we want to execute a recent block we use it against synced ethrex or reth nodes that expose the debug_executionWitness endpoint, this way retrieval of data will be instant and it will be way faster than the other method, because it won't be doing thousands of RPC requests, just one.

More information regarding the execution witness in the prover docs.

Why stateless execution of some blocks doesn't work with `eth_getProof`

With this method of execution we get the proof of all the accounts and storage slots accessed during execution, but the problem arises when we want to delete a node from the Merkle Patricia Trie (MPT) when applying the account updates of the block. This is for a particular case in which a tree restructuring happens and we have a missing node that wasn't accessed but we need to know in order to restructure the trie.

The problem can be explained with a simple example: a Branch node has 2 child nodes and only one was accessed and removed, this branch node should stop existing because they shouldn't have only one child. It will be either replaced by a leaf node or by an extension node, this depends on its child.

This problem is wonderfully explained in zkpig docs, they also have a very good intro to the MPT. Here they mention two different solutions that we have to implement in order to fix this. The first one works when the missing node is a Leaf or Extension and the second one works then the missing node is a Branch.

In our code we only applied the first solution by injecting all possible nodes to the execution witness that we build when using eth_getProof, that's why the witness when using this method will be larger than the witness obtained with debug_executionWitness.

We didn't apply the second change because it needs a change to the MPT that we don't want in our code. However we were able to solve it for execution without using a zkVM by injecting some "fake nodes" to the trie just before execution that have the expected hash but their RLP content doesn't match to it. This way we can "trick" the Trie into thinking that it has the branch nodes when in fact, it doesn't.

CLI Commands

ethrex

ethrex Execution client

Usage: ethrex [OPTIONS] [COMMAND]

Commands:
  removedb            Remove the database
  import              Import blocks to the database
  import-bench        Import blocks to the database for benchmarking
  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. If not specified, defaults to mainnet.

          [env: ETHREX_NETWORK=]

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

          [env: ETHREX_DATADIR=]
          [default: /home/runner/.local/share/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`. If `--network` is not specified, it will default to a custom local devnet. The Binary has to be built with the `dev` feature enabled.

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

          [default: INFO]

      --log.color <LOG_COLOR>
          Possible values: auto, always, never

          [default: auto]

      --mempool.maxsize <MEMPOOL_MAX_SIZE>
          Maximum size of the mempool in number of transactions

          [default: 10000]

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

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

          [default: snap]

      --p2p.disabled


      --p2p.port <PORT>
          TCP port for P2P protocol.

          [default: 30303]

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

          [default: 30303]

      --p2p.tx-broadcasting-interval <INTERVAL_MS>
          Transaction Broadcasting Time Interval (ms) for batching transactions before broadcasting them.

          [default: 1000]

      --target.peers <MAX_PEERS>
          Max amount of connected peers.

          [default: 100]

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

          [env: ETHREX_HTTP_ADDR=]
          [default: 0.0.0.0]

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

          [env: ETHREX_HTTP_PORT=]
          [default: 8545]

      --ws.enabled
          Enable websocket rpc server. Disabled by default.

          [env: ETHREX_ENABLE_WS=]

      --ws.addr <ADDRESS>
          Listening address for the websocket rpc server.

          [env: ETHREX_WS_ADDR=]
          [default: 0.0.0.0]

      --ws.port <PORT>
          Listening port for the websocket rpc server.

          [env: ETHREX_WS_PORT=]
          [default: 8546]

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

          [default: 127.0.0.1]

      --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]

Block building options:
      --builder.extra-data <EXTRA_DATA>
          Block extra data message.

          [default: "ethrex 6.0.0"]

      --builder.gas-limit <GAS_LIMIT>
          Target block gas limit.

          [default: 30000000]

ethrex l2

Usage: ethrex l2 [OPTIONS]
       ethrex l2 <COMMAND>

Commands:
  prover        Initialize an ethrex prover [aliases: p]
  removedb      Remove the database [aliases: rm, clean]
  blobs-saver   Launch a server that listens for Blobs submissions and saves them offline.
  reconstruct   Reconstructs the L2 state from L1 blobs.
  revert-batch  Reverts unverified batches.
  pause         Pause L1 contracts
  unpause       Unpause L1 contracts
  deploy        Deploy in L1 all contracts needed by an L2.
  help          Print this message or the help of the given subcommand(s)

Options:
  -t, --tick-rate <TICK_RATE>
          time in ms between two ticks

          [default: 1000]

      --batch-widget-height <BATCH_WIDGET_HEIGHT>


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

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. If not specified, defaults to mainnet.

          [env: ETHREX_NETWORK=]

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

          [env: ETHREX_DATADIR=]
          [default: "/home/runner/.local/share/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`. If `--network` is not specified, it will default to a custom local devnet. The Binary has to be built with the `dev` feature enabled.

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

          [default: INFO]

      --log.color <LOG_COLOR>
          Possible values: auto, always, never

          [default: auto]

      --mempool.maxsize <MEMPOOL_MAX_SIZE>
          Maximum size of the mempool in number of transactions

          [default: 10000]

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

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

          [default: snap]

      --p2p.disabled


      --p2p.port <PORT>
          TCP port for P2P protocol.

          [default: 30303]

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

          [default: 30303]

      --p2p.tx-broadcasting-interval <INTERVAL_MS>
          Transaction Broadcasting Time Interval (ms) for batching transactions before broadcasting them.

          [default: 1000]

      --target.peers <MAX_PEERS>
          Max amount of connected peers.

          [default: 100]

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

          [env: ETHREX_HTTP_ADDR=]
          [default: 0.0.0.0]

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

          [env: ETHREX_HTTP_PORT=]
          [default: 8545]

      --ws.enabled
          Enable websocket rpc server. Disabled by default.

          [env: ETHREX_ENABLE_WS=]

      --ws.addr <ADDRESS>
          Listening address for the websocket rpc server.

          [env: ETHREX_WS_ADDR=]
          [default: 0.0.0.0]

      --ws.port <PORT>
          Listening port for the websocket rpc server.

          [env: ETHREX_WS_PORT=]
          [default: 8546]

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

          [default: 127.0.0.1]

      --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]

Block building options:
      --builder.extra-data <EXTRA_DATA>
          Block extra data message.

          [default: "ethrex 6.0.0"]

      --builder.gas-limit <GAS_LIMIT>
          Target block gas limit.

          [default: 30000000]

Eth options:
      --eth.rpc-url <RPC_URL>...
          List of rpc urls to use.

          [env: ETHREX_ETH_RPC_URL=]

      --eth.maximum-allowed-max-fee-per-gas <UINT64>
          [env: ETHREX_MAXIMUM_ALLOWED_MAX_FEE_PER_GAS=]
          [default: 10000000000]

      --eth.maximum-allowed-max-fee-per-blob-gas <UINT64>
          [env: ETHREX_MAXIMUM_ALLOWED_MAX_FEE_PER_BLOB_GAS=]
          [default: 10000000000]

      --eth.max-number-of-retries <UINT64>
          [env: ETHREX_MAX_NUMBER_OF_RETRIES=]
          [default: 10]

      --eth.backoff-factor <UINT64>
          [env: ETHREX_BACKOFF_FACTOR=]
          [default: 2]

      --eth.min-retry-delay <UINT64>
          [env: ETHREX_MIN_RETRY_DELAY=]
          [default: 96]

      --eth.max-retry-delay <UINT64>
          [env: ETHREX_MAX_RETRY_DELAY=]
          [default: 1800]

L1 Watcher options:
      --l1.bridge-address <ADDRESS>
          [env: ETHREX_WATCHER_BRIDGE_ADDRESS=]

      --watcher.watch-interval <UINT64>
          How often the L1 watcher checks for new blocks in milliseconds.

          [env: ETHREX_WATCHER_WATCH_INTERVAL=]
          [default: 12000]

      --watcher.max-block-step <UINT64>
          [env: ETHREX_WATCHER_MAX_BLOCK_STEP=]
          [default: 5000]

      --watcher.block-delay <UINT64>
          Number of blocks the L1 watcher waits before trusting an L1 block.

          [env: ETHREX_WATCHER_BLOCK_DELAY=]
          [default: 10]

Block producer options:
      --block-producer.block-time <UINT64>
          How often does the sequencer produce new blocks to the L1 in milliseconds.

          [env: ETHREX_BLOCK_PRODUCER_BLOCK_TIME=]
          [default: 5000]

      --block-producer.coinbase-address <ADDRESS>
          [env: ETHREX_BLOCK_PRODUCER_COINBASE_ADDRESS=]

      --block-producer.base-fee-vault-address <ADDRESS>
          [env: ETHREX_BLOCK_PRODUCER_BASE_FEE_VAULT_ADDRESS=]

      --block-producer.operator-fee-vault-address <ADDRESS>
          [env: ETHREX_BLOCK_PRODUCER_OPERATOR_FEE_VAULT_ADDRESS=]

      --operator-fee-per-gas <UINT64>
          Fee that the operator will receive for each unit of gas consumed in a block.

          [env: ETHREX_BLOCK_PRODUCER_OPERATOR_FEE_PER_GAS=]

      --block-producer.block-gas-limit <UINT64>
          Maximum gas limit for the L2 blocks.

          [env: ETHREX_BLOCK_PRODUCER_BLOCK_GAS_LIMIT=]
          [default: 30000000]

Proposer options:
      --elasticity-multiplier <UINT64>
          [env: ETHREX_PROPOSER_ELASTICITY_MULTIPLIER=]
          [default: 2]

L1 Committer options:
      --committer.l1-private-key <PRIVATE_KEY>
          Private key of a funded account that the sequencer will use to send commit txs to the L1.

          [env: ETHREX_COMMITTER_L1_PRIVATE_KEY=]

      --committer.remote-signer-url <URL>
          URL of a Web3Signer-compatible server to remote sign instead of a local private key.

          [env: ETHREX_COMMITTER_REMOTE_SIGNER_URL=]

      --committer.remote-signer-public-key <PUBLIC_KEY>
          Public key to request the remote signature from.

          [env: ETHREX_COMMITTER_REMOTE_SIGNER_PUBLIC_KEY=]

      --l1.on-chain-proposer-address <ADDRESS>
          [env: ETHREX_COMMITTER_ON_CHAIN_PROPOSER_ADDRESS=]

      --committer.commit-time <UINT64>
          How often does the sequencer commit new blocks to the L1 in milliseconds.

          [env: ETHREX_COMMITTER_COMMIT_TIME=]
          [default: 60000]

      --committer.batch-gas-limit <UINT64>
          Maximum gas limit for the batch

          [env: ETHREX_COMMITTER_BATCH_GAS_LIMIT=]

      --committer.first-wake-up-time <UINT64>
          Time to wait before the sequencer seals a batch when started. After committing the first batch, `committer.commit-time` will be used.

          [env: ETHREX_COMMITTER_FIRST_WAKE_UP_TIME=]

      --committer.arbitrary-base-blob-gas-price <UINT64>
          [env: ETHREX_COMMITTER_ARBITRARY_BASE_BLOB_GAS_PRICE=]
          [default: 1000000000]

Proof coordinator options:
      --proof-coordinator.l1-private-key <PRIVATE_KEY>
          Private key of of a funded account that the sequencer will use to send verify txs to the L1. Has to be a different account than --committer-l1-private-key.

          [env: ETHREX_PROOF_COORDINATOR_L1_PRIVATE_KEY=]

      --proof-coordinator.tdx-private-key <PRIVATE_KEY>
          Private key of of a funded account that the TDX tool that will use to send the tdx attestation to L1.

          [env: ETHREX_PROOF_COORDINATOR_TDX_PRIVATE_KEY=]

      --proof-coordinator.qpl-tool-path <QPL_TOOL_PATH>
          Path to the QPL tool that will be used to generate TDX quotes.

          [env: ETHREX_PROOF_COORDINATOR_QPL_TOOL_PATH=]
          [default: ./tee/contracts/automata-dcap-qpl/automata-dcap-qpl-tool/target/release/automata-dcap-qpl-tool]

      --proof-coordinator.remote-signer-url <URL>
          URL of a Web3Signer-compatible server to remote sign instead of a local private key.

          [env: ETHREX_PROOF_COORDINATOR_REMOTE_SIGNER_URL=]

      --proof-coordinator.remote-signer-public-key <PUBLIC_KEY>
          Public key to request the remote signature from.

          [env: ETHREX_PROOF_COORDINATOR_REMOTE_SIGNER_PUBLIC_KEY=]

      --proof-coordinator.addr <IP_ADDRESS>
          Set it to 0.0.0.0 to allow connections from other machines.

          [env: ETHREX_PROOF_COORDINATOR_LISTEN_ADDRESS=]
          [default: 127.0.0.1]

      --proof-coordinator.port <UINT16>
          [env: ETHREX_PROOF_COORDINATOR_LISTEN_PORT=]
          [default: 3900]

      --proof-coordinator.send-interval <UINT64>
          How often does the proof coordinator send proofs to the L1 in milliseconds.

          [env: ETHREX_PROOF_COORDINATOR_SEND_INTERVAL=]
          [default: 5000]

Based options:
      --state-updater.sequencer-registry <ADDRESS>
          [env: ETHREX_STATE_UPDATER_SEQUENCER_REGISTRY=]

      --state-updater.check-interval <UINT64>
          [env: ETHREX_STATE_UPDATER_CHECK_INTERVAL=]
          [default: 1000]

      --block-fetcher.fetch_interval_ms <UINT64>
          [env: ETHREX_BLOCK_FETCHER_FETCH_INTERVAL_MS=]
          [default: 5000]

      --fetch-block-step <UINT64>
          [env: ETHREX_BLOCK_FETCHER_FETCH_BLOCK_STEP=]
          [default: 5000]

      --based
          [env: ETHREX_BASED=]

Aligned options:
      --aligned
          [env: ETHREX_ALIGNED_MODE=]

      --aligned-verifier-interval-ms <ETHREX_ALIGNED_VERIFIER_INTERVAL_MS>
          [env: ETHREX_ALIGNED_VERIFIER_INTERVAL_MS=]
          [default: 5000]

      --aligned.beacon-url <BEACON_URL>...
          List of beacon urls to use.

          [env: ETHREX_ALIGNED_BEACON_URL=]

      --aligned-network <ETHREX_ALIGNED_NETWORK>
          L1 network name for Aligned sdk

          [env: ETHREX_ALIGNED_NETWORK=]
          [default: devnet]

      --aligned.fee-estimate <FEE_ESTIMATE>
          Fee estimate for Aligned sdk

          [env: ETHREX_ALIGNED_FEE_ESTIMATE=]
          [default: instant]

Admin server options:
      --admin-server.addr <IP_ADDRESS>
          [env: ETHREX_ADMIN_SERVER_LISTEN_ADDRESS=]
          [default: 127.0.0.1]

      --admin-server.port <UINT16>
          [env: ETHREX_ADMIN_SERVER_LISTEN_PORT=]
          [default: 5555]

L2 options:
      --validium
          If true, L2 will run on validium mode as opposed to the default rollup mode, meaning it will not publish blobs to the L1.

          [env: ETHREX_L2_VALIDIUM=]

      --sponsorable-addresses <SPONSORABLE_ADDRESSES_PATH>
          Path to a file containing addresses of contracts to which ethrex_SendTransaction should sponsor txs

      --sponsor-private-key <SPONSOR_PRIVATE_KEY>
          The private key of ethrex L2 transactions sponsor.

          [env: SPONSOR_PRIVATE_KEY=]
          [default: 0xffd790338a2798b648806fc8635ac7bf14af15425fed0c8f25bcc5febaa9b192]

Monitor options:
      --no-monitor
          [env: ETHREX_NO_MONITOR=]

ethrex l2 prover

Initialize an ethrex prover

Usage: ethrex l2 prover [OPTIONS] --proof-coordinators <URL>...

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

Prover client options:
      --backend <BACKEND>
          [env: PROVER_CLIENT_BACKEND=]
          [default: exec]
          [possible values: exec, sp1, risc0]

      --proof-coordinators <URL>...
          URLs of all the sequencers' proof coordinator

          [env: PROVER_CLIENT_PROOF_COORDINATOR_URL=]

      --proving-time <PROVING_TIME>
          Time to wait before requesting new data to prove

          [env: PROVER_CLIENT_PROVING_TIME=]
          [default: 5000]

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

          [default: INFO]

      --aligned
          Activate aligned proving system

          [env: PROVER_CLIENT_ALIGNED=]

      --sp1-server <URL>
          Url to the moongate server to use when using sp1 backend

          [env: ETHREX_SP1_SERVER=]

How to Release an ethrex version

Releases are prepared from dedicated release branches and tagged using versioning.

1st - Create release branch

Branch name must follow the format release/vX.Y.Z.

Examples:

release/v1.2.0
release/v3.0.0
release/v3.2.0

2nd - Bump version

The version must be updated to X.Y.Z in the release branch. There are multiple Cargo.toml and Cargo.lock files that need to be updated.

First, we need to update the version of the workspace package. You can find it in the Cargo.toml file in the root directory, under the [workspace.package] section.

Then, we need to update three more Cargo.toml files that are not part of the workspace but fulfill the role of packages in the monorepo. These are located in the following paths:

crates/l2/prover/src/guest_program/src/sp1/Cargo.toml
crates/l2/prover/src/guest_program/src/risc0/Cargo.toml
crates/l2/tee/quote-gen/Cargo.toml

After updating the version in the Cargo.toml files, we need to update the Cargo.lock files to reflect the new versions. Run cargo tree in their respective directories:

In the root directory
crates/l2/prover/src/guest_program/src/sp1
crates/l2/prover/src/guest_program/src/risc0
crates/l2/tee/quote-gen

Then, go to the CLI.md file located in docs/ and update the version of the --builder.extra-data flag default value to match the new version (for both ethrex and ethrex l2 sections).

Finally, stage and commit the changes to the release branch.

An example of a PR that bumps the version can be found here.

3rd - Create & Push Tag

Create a tag with a format vX.Y.Z-rc.W where X.Y.Z is the semantic version and W is a release candidate version. Other names for subversions are also accepted. Example of valid tags:

v0.1.3-rc.1
v0.0.2-alpha

git tag <release_version>
git push origin <release_version>

After pushing the tag, a CI job will compile the binaries for different architectures and create a pre-release with the version specified in the tag name. Along with the binaries, a tar file is uploaded with the contracts and the verification keys. The following binaries are built:

name	L2 stack	Provers	CUDA support
ethrex-linux-x86-64	❌	-	-
ethrex-linux-aarch64	❌	-	-
ethrex-linux-macos-aarch64	❌	-	-
ethrex-l2-linux-x86-64	✅	SP1 - RISC0 - Exec	❌
ethrex-l2-linux-x86-64-gpu	✅	SP1 - RISC0 - Exec	✅
ethrex-l2-linux-aarch64	✅	SP1 - Exec	❌
ethrex-l2-linux-aarch64-gpu	✅	SP1 - Exec	✅
ethrex-l2-macos-aarch64	✅	Exec	❌

Also, two docker images are built and pushed to the Github Container registry:

ghcr.io/lambdaclass/ethrex:X.Y.Z-rc.W
ghcr.io/lambdaclass/ethrex:X.Y.Z-rc.W-l2

A changelog will be generated based on commit names (using conventional commits) from the last stable tag.

4th - Test & Publish Release

When you are sure all the binaries and docker images work as expected, you can proceed to publish the release. To do so, edit the last pre-release with the following changes:

Change the name to ethrex: vX.Y.Z
Change the tag to a new one vX.Y.Z. IMPORTANT: Make sure to select the release/vX.Y.Z branch when changing the tag.
Set the release as the latest release (you will need to uncheck the pre-release first).

Once done, the CI will publish new tags for the already compiled docker images:

ghcr.io/lambdaclass/ethrex:X.Y.Z, ghcr.io/lambdaclass/ethrex:latest
ghcr.io/lambdaclass/ethrex:X.Y.Z-l2, ghcr.io/lambdaclass/ethrex:l2

5th - Update Homebrew

Disclaimer: We should automate this

Commit a change in https://github.com/lambdaclass/homebrew-tap/ bumping the ethrex version (like this one).
- The first SHA is the hash of the .tar.gz from the release. You can get it by downloading the Source code (tar.gz) from the ethrex release and running
```
shasum -a 256 ethrex-v3.0.0.tar.gz
```
- For the second one:
  - First download the ethrex-l2-macos-aarch64 binary from the ethrex release
  - Give exec permissions to binary
```
chmod +x ethrex-l2-macos-aarch64
```
  - Create a dir ethrex/3.0.0/bin (replace the version as needed)
  - Move (and rename) the binary to ethrex/3.0.0/bin/ethrex (the last ethrex is the binary)
  - Remove quarantine flags (in this case, ethrex is the root dir mentioned before):
```
xattr -dr com.apple.metadata:kMDItemWhereFroms ethrex
xattr -dr com.apple.quarantine ethrex
```
  - Tar the dir with the following name (again, ethrex is the root dir):
```
tar -czf ethrex-3.0.0.arm64_sonoma.bottle.tar.gz ethrex
```
  - Get the checksum:
```
shasum -a 256 ethrex-3.0.0.arm64_sonoma.bottle.tar.gz
```
  - Use this as the second hash (the one in the bottle section)
Push the commit
Create a new release with tag v3.0.0. IMPORTANT: attach the ethrex-3.0.0.arm64_sonoma.bottle.tar.gz to the release

6th - Merge the release branch via PR

Once the release is verified, merge the branch via PR.

Dealing with hotfixes

If hotfixes are needed before the final release, commit them to release/vX.Y.Z, push, and create a new pre-release tag. The final tag vX.Y.Z should always point to the exact commit you will merge via PR.

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
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
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
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
Validiums & DACs	Enhance Validium mode with Data Availability Committees.	Planned
Gas & Fees	Set up a fee token model to price deposits or any forced-included transaction, including data availability costs.	Planned

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
Chain Syncing	Verify the execution of all blocks across all chains. For Proof-of-Stake (PoS) chains (Holesky, Hoodi), verify all blocks since genesis. For chains with a pre-Merge genesis (Sepolia, Mainnet), verify all blocks after the Merge.	In Progress
Snap Sync	Improve Snap Sync implementation to make it more reliable and efficient.	Planned
Client Stability	Increase client resilience to adverse scenarios and network disruptions. Improve observability and logging.	Planned

Contributing to the Documentation

We welcome contributions to the documentation! If you want to help improve or expand the docs, please follow these guidelines:

How to Edit the Docs

All documentation lives in this docs/ directory and its subfolders.
The documentation is written in Markdown and rendered using mdBook.
To preview your changes locally, install the dependencies and run:
```
make docs-serve
```
This will start a local server and open the docs in your browser.

Adding or Editing Content

To add a new page, create a new .md file in the appropriate subdirectory and add a link to it in SUMMARY.md.
To edit an existing page, simply modify the relevant .md file.
For style and formatting, try to keep a consistent tone and structure with the rest of the documentation.

Documentation dependencies

We use some mdBook preprocessors and backends for extra features:

mdbook-alerts for custom markdown syntax.
mdbook-mermaid for diagrams.
mdbook-linkcheck for checking broken links (optional).

You can install mdBook and all dependencies with:

make docs-deps

Submitting Changes

Please open a Pull Request with your proposed changes.
If you are adding new content, update SUMMARY.md so it appears in the navigation.
If you have questions, open an issue or ask in the community chat.

Thank you for helping improve the documentation!

Recommended lectures

Disclaimer: This section is under development. We’ll continue to expand it with more up-to-date materials over time.

For those interested in deepening their understanding of Ethereum internals, execution clients, and related zero-knowledge and distributed systems topics, we recommend the following materials:

Keyboard shortcuts

Ethrex