ethrex-replay

A tool for executing and proving Ethereum blocks, transactions, and L2 batches — inspired by starknet-replay. Currently ethrex replay only works against ethrex nodes with the debug_executionWitness RPC endpoint.

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

✅: supported. ⚠️: supported, but flaky. 🔜: to be supported.

Client	Hoodi	Sepolia	Mainnet	Public ethrex L2s
ethrex	✅	✅	✅	✅
reth	✅	✅	✅	-
geth	✅	✅	✅	-
Nethermind	⚠️	⚠️	⚠️	-
erigon	🔜	🔜	🔜	-

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

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

Execute a single block from a public network
Prove a single block
Execute an L2 batch
Prove an L2 batch
Execute a transaction
Plot block composition

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>

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 ethrex-replay <COMMAND> [ARGS]

Execution without zkVMs

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
samply record target/release-with-debug/ethrex-replay <COMMAND> [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.

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

Ethrex

ethrex-replay

Features

L1

L2

Supported Clients

Supported zkVM Replays (execution & proving)

Getting Started

Dependencies

RISC0

SP1

Installation

From Cargo

Run from Source

Features

Running Examples

Examples ToC

Execute a single block from a public network

Prove a single block

Execute an L2 batch

Prove an L2 batch

Execute a transaction

Plot block composition

Benchmarking & Profiling

Run Samply

On zkVMs

Execution without zkVMs

Run Bytehound

Run Heaptrack

Check All Available Commands

Keyboard shortcuts

Ethrex