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 canonical stateless inputs from CL/EL RPC endpoints.

The benchmark supports the Reth, Ethrex, and Zesu execution clients. 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

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.