This workspace contains code for executing Ethereum block validation logic within different Zero-Knowledge Virtual Machines (zkVMs) where the input is generated by the execution spec tests.
The primary goal is to measure and compare the performance (currently in cycle counts) of running a standardized benchmarking workload (including known worse-cases) with the same stateless validation logic* across various zkVM platforms.
*We cannot guarantee the logic will be the same for targets that are not supported by the Rust toolchain. An example of this currently is Cairo.
The workspace is organized into several key components:
crates/metrics: Defines common data structures (WorkloadMetrics) for storing and serializing benchmark results.crates/witness-generator: Generates the necessary inputs (ClientInput: block + witness pairs) required for stateless block validation by processing standard Ethereum test fixtures.crates/ere-hosts: Contains the host implementation that orchestrates benchmarking across different zkVM platforms.crates/benchmark-runner: Provides utilities for running benchmarks across different zkVM implementations.crates/zkevm-zkm: Contains the zkMIPS-specific implementation.ere-guests/: Directory containing guest program implementations for different zkVM platforms:ere-guests/sp1/: Succinct SP1 guest implementationere-guests/openvm/: OpenVM guest implementationere-guests/risc0/: RISC0 guest implementationere-guests/zkm/: zkMIPS guest implementationere-guests/pico/: Pico guest implementation
zkevm-fixtures: (Git submodule) Contains the Ethereum execution layer test fixtures used bywitness-generator.zkevm-metrics: Directory where benchmark results (cycle counts) are stored by the host programs, organized by zkVM type.scripts: Contains helper scripts (e.g., fetching fixtures).xtask: Cargo xtask runner for automating tasks.
Each zkVM benchmark implementation follows a common pattern:
-
Guest Program:
- Located within the
ere-guests/directory for the specific zkVM (e.g.,ere-guests/sp1/,ere-guests/openvm/). - Contains the Rust code that executes the Ethereum state transition function(
reth_stateless::validation::stateless_validation). - This code is compiled specifically for the target zkVM's architecture (e.g., RISC-V for SP1, MIPS for zkMIPS).
- It reads block/witness data from its zkVM environment's standard input.
- Uses platform-specific mechanisms (often
println!markers) to delineate code regions for cycle counting.
- Located within the
-
Host Program:
- Located within
crates/ere-hosts/with shared host logic across zkVM platforms. - A standard Rust binary that orchestrates the benchmarking.
- Uses
witness-generatorto get test data and generate input data. - Invokes the corresponding zkVM SDK to execute the compiled Guest program ELF with the necessary inputs.
- Collects cycle count metrics reported by the zkVM SDK.
- Saves the results using the
metricscrate into the appropriate subdirectory withinzkevm-metrics/.
- Located within
-
Automatic Patch Application:
- The benchmark runner includes functionality to automatically apply precompile patches for each zkVM.
- Rust Toolchain: A standard Rust installation managed by
rustup. - zkVM-Specific Toolchains: Each zkVM requires its own SDK and potentially a custom Rust toolchain/target. Please refer to the specific zkVM guest directory in
ere-guests/(e.g.,ere-guests/sp1/README.md,ere-guests/openvm/README.md) for detailed setup instructions for that platform. - Git: Required for cloning the repository :)
- Common Shell Utilities: The scripts in the
./scriptsdirectory require abash-compatible shell and standard utilities likecurl,jq, andtar.
-
Clone the Repository:
git clone <repository-url> cd zkevm-benchmark-workload
-
Fetch/Update Benchmark Fixtures:
./scripts/download-and-extract-fixtures.sh
-
(Optionally)Patching Precompiles: Each zkVM, for efficiency purposes requires particular dependencies to be patched. This repository contains an
xtaskthat will automate this process by callingcargo <zkvm-name>. See.config/cargo.tomlfor how this is setup andprecompile-patchesfor the patches that each zkVM requires.
Note: This is optional as it should be automatically done when the benchmarks are ran.
- Run benchmark: Navigate to
crates/ere-hosts/and follow the readme instructions to run benchmarks for specific zkVMs.
| zkVM | Guest Path | Host Path | Metrics Output |
|---|---|---|---|
| Succinct SP1 | ere-guests/sp1/ |
crates/ere-hosts/ |
zkevm-metrics/sp1/ |
| zkMIPS | ere-guests/zkm/ |
crates/zkevm-zkm/ |
zkevm-metrics/zkm/ |
| OpenVM | ere-guests/openvm/ |
crates/ere-hosts/ |
zkevm-metrics/openvm/ |
| RISC0 | ere-guests/risc0/ |
crates/ere-hosts/ |
zkevm-metrics/risc0/ |