{"id":40818967,"url":"https://github.com/eth-act/zkevm-benchmark-workload","last_synced_at":"2026-01-21T21:44:45.496Z","repository":{"id":291429404,"uuid":"977141447","full_name":"eth-act/zkevm-benchmark-workload","owner":"eth-act","description":"zkVM benchmarking for Ethereum","archived":false,"fork":false,"pushed_at":"2026-01-20T13:38:31.000Z","size":251326,"stargazers_count":41,"open_issues_count":16,"forks_count":16,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-01-20T22:02:20.838Z","etag":null,"topics":["benchmark","ethereum","zkvm"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eth-act.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-03T14:17:56.000Z","updated_at":"2026-01-20T13:31:41.000Z","dependencies_parsed_at":"2025-07-05T20:27:39.382Z","dependency_job_id":"162403f3-4cac-42a3-a048-2b587902f8ba","html_url":"https://github.com/eth-act/zkevm-benchmark-workload","commit_stats":null,"previous_names":["eth-applied-research-group/zkevm-benchmark-workload","eth-act/zkevm-benchmark-workload"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/eth-act/zkevm-benchmark-workload","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eth-act%2Fzkevm-benchmark-workload","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eth-act%2Fzkevm-benchmark-workload/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eth-act%2Fzkevm-benchmark-workload/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eth-act%2Fzkevm-benchmark-workload/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eth-act","download_url":"https://codeload.github.com/eth-act/zkevm-benchmark-workload/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eth-act%2Fzkevm-benchmark-workload/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28644149,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T21:29:11.980Z","status":"ssl_error","status_checked_at":"2026-01-21T21:24:31.872Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["benchmark","ethereum","zkvm"],"created_at":"2026-01-21T21:44:44.355Z","updated_at":"2026-01-21T21:44:45.489Z","avatar_url":"https://github.com/eth-act.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo-white-transparent-bg.png\" alt=\"ZK-EVM Bench\" width=\"300\"/\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ezkEVM Benchmarking Workload\u003c/h1\u003e\n\nThis workspace contains code for benchmarking guest programs within different zkVMs. Although different guest programs are supported, the main use case is benchmarking the Ethereum STF by running benchmarks from the [spec tests](https://github.com/ethereum/execution-specs).\n\n## Workspace Structure\n\n- **`crates/metrics`**: Defines common data structures (`BenchmarkRun\u003cMetadata\u003e`) for storing and serializing benchmark results with generic metadata support.\n- **`crates/witness-generator`**: A library that provides functionality for generating benchmark fixture files (`BlockAndWitness`: individual block + witness pairs) required for stateless block validation by processing standard Ethereum test fixtures or RPC endpoints.\n- **`crates/witness-generator-cli`**: A standalone binary that uses the `witness-generator` library to generate fixture files. These are saved in the `zkevm-fixtures-input` folder.\n- **`crates/ere-hosts`**: A standalone binary that runs benchmarks across different zkVM platforms using pre-generated fixture files from `zkevm-fixtures-input`.\n- **`crates/benchmark-runner`**: Provides a unified framework for running benchmarks across different zkVM implementations, including guest program input generation and execution orchestration.\n- **`scripts/`**: Contains helper scripts (e.g., fetching fixtures).\n\nGuest programs are maintained in the [eth-act/ere-guests](https://github.com/eth-act/ere-guests) repository and downloaded automatically during benchmark runs.\n\n## Workflow Overview\n\nThe benchmarking process is decoupled into two distinct phases:\n\n1. **Fixture Generation** (`witness-generator-cli`): Processes Ethereum benchmark fixtures (EEST) or RPC data to generate individual `BlockAndWitness` fixtures as JSON files saved in `zkevm-fixtures-input/`.\n2. **Benchmark Execution** (`ere-hosts`): Reads from `zkevm-fixtures-input/` and runs performance benchmarks across different zkVM platforms.\n\nThis decoupling provides several benefits:\n- Independent fixture generation and benchmark execution\n- Reuse of generated fixtures across multiple benchmark runs\n\n## Prerequisites\n\n1. **Rust Toolchain:** A standard Rust installation managed by `rustup`.\n2. **Docker:** All zkVMs use EreDockerized, which means you don't need to install zkVM-specific toolchains locally. Docker handles all the compilation and execution environments.\n3. **Git:** Required for cloning the repository.\n4. **Common Shell Utilities:** The scripts require a `bash`-compatible shell and standard utilities like `curl`, `jq`, and `tar`.\n\n## Setup\n\n1. **Clone the Repository:**\n\n    ```bash\n    git clone https://github.com/eth-applied-research-group/zkevm-benchmark-workload.git\n    cd zkevm-benchmark-workload\n    ```\n\n2. **Fetch/Update Benchmark Fixtures:**\n\n    ```bash\n    ./scripts/download-and-extract-fixtures.sh\n    ```\n\n3. **Generate Benchmark Input Files (required for `stateless-validator` guest program):**\n\n    ```bash\n    cargo run --release -- tests --include 10M- --include Prague\n\n    # Or generate from local EEST fixtures\n    cargo run --release -- tests --eest-fixtures-path /path/to/local/eest/fixtures\n\n    # Or generate from RPC\n    cargo run --release -- rpc --last-n-blocks 2 --rpc-url \u003cyour-rpc-url\u003e\n\n    # Or listen for new blocks continuously\n    cargo run --release -- rpc --follow --rpc-url \u003cyour-rpc-url\u003e\n    ```\n\n    This creates individual `.json` files in the `zkevm-fixtures-input/` directory that will be consumed by the benchmark runner.\n\n4. **Run Benchmarks:**\n\n    Run benchmarks using the generated fixture files. All zkVMs are dockerized, so no additional setup is required:\n\n    ```bash\n    cd crates/ere-hosts\n\n    # Run Ethereum stateless validator benchmarks with Reth execution client\n    cargo run --release -- --zkvms risc0 stateless-validator --execution-client reth\n\n    # Run Ethereum stateless validator benchmarks with Ethrex execution client\n    cargo run --release -- --zkvms sp1 stateless-validator --execution-client ethrex\n\n    # Run empty program benchmarks (for measuring zkVM overhead)\n    cargo run --release -- empty-program\n\n    # Run block encoding length benchmarks\n    cargo run --release -- block-encoding-length --loop-count 100 --format rlp\n    \n    # Run block encoding length benchmarks (with SSZ encoding format)\n    cargo run --release -- block-encoding-length --loop-count 100 --format ssz\n    \n    # Use custom input folder for stateless validator benchmarks\n    cargo run --release -- stateless-validator --execution-client reth --input-folder my-fixtures\n\n    # Dump raw input files used in benchmarks (opt-in)\n    cargo run --release -- --zkvms sp1 --dump-inputs my-inputs stateless-validator --execution-client reth\n    ```\n\n    See the respective README files in each crate for detailed usage instructions.\n\n### Dumping Input Files\n\nThe `--dump-inputs` flag allows you to save the raw serialized input bytes used for each benchmark run. This is useful for:\n- Debugging guest programs independently\n- Analyzing input data characteristics\n- Replaying specific test cases outside the benchmark framework\n\nWhen specified, input files are saved to the designated folder with the following structure:\n```\n{dump-folder}/\n  └── {sub-folder}/       # e.g., \"reth\" for stateless-validator, empty for others\n      └── {name}.bin      # Input files (one per benchmark)\n```\n\nExample usage:\n```bash\ncd crates/ere-hosts\n\n# Dump inputs for stateless validator with Reth\ncargo run --release -- --zkvms sp1 --dump-inputs debug-inputs stateless-validator --execution-client reth\n\n# This creates files like:\n# debug-inputs/reth/block-12345.bin\n# debug-inputs/reth/block-12346.bin\n```\n\nNote: Input files are zkVM-independent (the same input is used across all zkVMs), so they're only written once even when benchmarking multiple zkVMs.\n\n## License\n\nLicensed under either of\n\n* MIT license (LICENSE‑MIT or [http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT))\n* Apache License, Version 2.0 (LICENSE‑APACHE or [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0))\n\nat your option.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feth-act%2Fzkevm-benchmark-workload","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feth-act%2Fzkevm-benchmark-workload","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feth-act%2Fzkevm-benchmark-workload/lists"}