zkEVM Benchmarking Workload

This repository benchmarks Ethereum stateless-validator guests across multiple zkVMs. The normal workflow has two phases:

1. Obtain canonical EEST blockchain_tests fixtures containing statelessInputBytes and statelessOutputBytes.
2. Pass a fixture file, fixture directory, or EEST fixture checkout to ere-hosts and write execution metrics, proofs, or verification results.

Workspace At a Glance

• crates/ere-hosts: benchmark CLI for execution, proving, and verification jobs.
• crates/benchmark-runner: shared orchestration for canonical fixture loading, guest resolution, execution, proof flow, and verification.
• crates/metrics: serializable result types such as BenchmarkRun.
• crates/witness-generator-spec-cli: separate CLI and library for producing and publishing benchmark-ready EEST stateless fixtures from CL/EL RPC endpoints.

Reth and Ethrex are enabled across the supported zkVMs. Zesu remains a valid CLI execution-client value and its routing is retained, but it is temporarily gated until ere-guests publishes a tests-zkevm v0.6.2-compatible artifact. Enabled guest programs are maintained in eth-act/ere-guests and are downloaded automatically from the resolved release or commit artifacts unless --bin-path or --guest-artifact-base-url is provided.

Prerequisites

• Rust via rustup
• Docker
• Canonical EEST blockchain_tests fixtures

Quickstart

Inspect both maintained CLIs:

cargo run -p ere-hosts -- --help
cargo run -p witness-generator-spec-cli -- --help

The witness generator produces benchmark-ready EEST fixtures from live CL/EL networks. Use generate for one block or collect for continuous per-block collection. Exported live batches contain a blockchain_tests/ tree and can be passed to ere-hosts immediately after extraction.

Obtain an EEST fixture bundle from ethereum/execution-specs whose blockchain_tests cases contain canonical stateless bytes. Then benchmark either the checkout's fixture root, a directory of EEST JSON files, or one EEST JSON file:

cargo run -p ere-hosts --release -- --zkvms sp1 \
    stateless-validator --execution-client reth \
    --input-folder /path/to/execution-specs/fixtures

Execute and prove actions require --input-folder. Verification reads saved proofs and may omit it.

Guides

• Documentation map
• Benchmark execution, proofs, and verification guide
• Benchmark input reference
• Benchmark output reference
• Stateless input publication guide

The root README is intentionally short. Detailed workflow documentation lives under docs/.

License

Licensed under either of

• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

at your option.