From 86be43562d70df03a7335fabb39b33863c1a325e Mon Sep 17 00:00:00 2001 From: Bloxster Date: Mon, 3 Aug 2026 16:57:51 +0200 Subject: [PATCH 1/6] docs: fix CLI snippets that don't match the z6m_prover source Replaces #2, which was opened 2026-05-29 and has since gone stale: one of its three fixes landed independently in the July docs restructure, and it hand-edited a generated artifact. Verification below is fresh, against erigontech/zilkworm origin/master today. 1. docs/testing/riscv-testing-eests-on-rv32im-via-qemu.md `make rv32im_eest_blockchain_tests` names a target that exists in no file on zilkworm master. The real target is `eest-rv32` (qemu_runner/Makefile:76), and the doc already `cd`s into qemu_runner immediately above, so it is runnable as written. 2. src/pages/index.tsx (landing hero) Three problems, only the first of which #2 addressed: - `z6m_prover verify proof.json` would clap-error. Verify declares only long args -- `proof_path` (default proof.bin) and `vk_path` (default vk.bin), prover_turbo/src/main.rs:146 -- and takes no positional. - The demo did not compose. Nothing in Prove emits a verifying key, so verifying against vk.bin referenced a file the example never created. The missing step is `setup`, which writes pk.bin and vk.bin (main.rs:70, service.rs:204-206); prove then consumes pk.bin. Adding it makes the sequence runnable end to end. - The block is shell but opened with a `//` comment. Filenames now use the documented defaults (proof.bin, vk.bin) so the hero matches docs/getting-started/cli-reference.md:149, which already had the correct form -- the site was contradicting itself. The caption changes from "Create block proofs in one command" to "Prove and verify an Ethereum block", since the flow is three commands. That is a copy change; reword freely. static/llms-full.txt is regenerated via scripts/generate-llms.py rather than hand-edited. It picks up exactly the one make-target line; the hero is not mirrored there because llms only covers docs pages. Verified: tsc --noEmit clean, npm run build clean, built HTML shows the three-command hero. Co-Authored-By: Claude Opus 5 (1M context) --- docs/testing/riscv-testing-eests-on-rv32im-via-qemu.md | 2 +- src/pages/index.tsx | 7 ++++--- static/llms-full.txt | 2 +- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/testing/riscv-testing-eests-on-rv32im-via-qemu.md b/docs/testing/riscv-testing-eests-on-rv32im-via-qemu.md index da1a3db..5a4da8e 100644 --- a/docs/testing/riscv-testing-eests-on-rv32im-via-qemu.md +++ b/docs/testing/riscv-testing-eests-on-rv32im-via-qemu.md @@ -54,7 +54,7 @@ git submodule foreach 'git lfs pull' ```bash cd zilkworm/qemu_runner -make rv32im_eest_blockchain_tests +make eest-rv32 ``` That would build the project for rv32im and invoke `ctest` to launch a bunch of `qemu-system-riscv32` instances in the background. Each of these instances is passed with a JSON file to run as a test.\ diff --git a/src/pages/index.tsx b/src/pages/index.tsx index f4f70bd..d521dcc 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -102,9 +102,10 @@ const capabilities: Card[] = [ }, ]; -const exampleCommand = `// Create block proofs in one command -z6m_prover prove --block-number 23456789 --proof-path proof.json -z6m_prover verify proof.json`; +const exampleCommand = `# Prove and verify an Ethereum block +z6m_prover setup +z6m_prover prove --block-number 23456789 --proof-path proof.bin +z6m_prover verify --proof-path proof.bin --vk-path vk.bin`; export default function Home(): React.ReactElement { return ( diff --git a/static/llms-full.txt b/static/llms-full.txt index cfd12c8..4c3dcc1 100644 --- a/static/llms-full.txt +++ b/static/llms-full.txt @@ -935,7 +935,7 @@ git submodule foreach 'git lfs pull' ```bash cd zilkworm/qemu_runner -make rv32im_eest_blockchain_tests +make eest-rv32 ``` That would build the project for rv32im and invoke `ctest` to launch a bunch of `qemu-system-riscv32` instances in the background. Each of these instances is passed with a JSON file to run as a test.\ From 95d91a1ea175186b99c781b93ee77cd838f20e26 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 5 Aug 2026 12:32:19 +0000 Subject: [PATCH 2/6] fix: use relative path for qemu_runner cd command Co-authored-by: bloxster <40316187+bloxster@users.noreply.github.com> --- docs/testing/riscv-testing-eests-on-rv32im-via-qemu.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/testing/riscv-testing-eests-on-rv32im-via-qemu.md b/docs/testing/riscv-testing-eests-on-rv32im-via-qemu.md index 5a4da8e..2b5b119 100644 --- a/docs/testing/riscv-testing-eests-on-rv32im-via-qemu.md +++ b/docs/testing/riscv-testing-eests-on-rv32im-via-qemu.md @@ -53,7 +53,7 @@ git submodule foreach 'git lfs pull' #### **Run EEST blockchain tests on RV32IM (via QEMU)** ```bash -cd zilkworm/qemu_runner +cd qemu_runner make eest-rv32 ``` From 7d0b4806f708f11ae19259ebde7f21d5d513c82f Mon Sep 17 00:00:00 2001 From: Bloxster Date: Tue, 11 Aug 2026 16:41:36 +0200 Subject: [PATCH 3/6] fix(home): hero advertised a command sequence that produces no proof The hero showed `setup` -> `prove --proof-path` -> `verify --vk-path`, but on the current prover all three are inert: `setup` and `verify` are no-op stubs (handler bodies commented out), `--proof-path` is ignored, and `prove` never persists a proof -- it exits 0 having written nothing. `vk.bin` is never created either, since `setup` writes nothing. So the landing page's headline example could not produce the artifact it named. Replace it with service mode, the one path that actually writes a proof to disk: prover_hypercube/src/service.rs does an unconditional File::create + bincode encode before the (optional) Ethproofs hook. `--service` fetches the block and witness itself, so the command is self-contained. `--prove-every` is a modulo on the block number and defaults to "never", so `--prove-every 1` is required to prove one specific block. Output path verified against the source: //proof.bin, with no `blocks/` segment (unlike the witness input path). Co-Authored-By: Claude Opus 5 (1M context) --- src/pages/index.tsx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/pages/index.tsx b/src/pages/index.tsx index d521dcc..6c3cb0d 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -102,10 +102,10 @@ const capabilities: Card[] = [ }, ]; -const exampleCommand = `# Prove and verify an Ethereum block -z6m_prover setup -z6m_prover prove --block-number 23456789 --proof-path proof.bin -z6m_prover verify --proof-path proof.bin --vk-path vk.bin`; +const exampleCommand = `# Prove an Ethereum mainnet block on GPU +z6m_prover --service --rpc-url $RPC_URL --data-dir ./data \\ + --start-block 23456789 --end-block 23456789 --prove-every 1 +# → ./data/23456789/proof23456789.bin`; export default function Home(): React.ReactElement { return ( From 0bcc23870f555407bce392682651f6b0c4d2566c Mon Sep 17 00:00:00 2001 From: Bloxster Date: Tue, 11 Aug 2026 16:42:28 +0200 Subject: [PATCH 4/6] fix(llms): regenerate artifacts after the qemu_runner cd fix 95d91a1 changed the qemu page's `cd` target but left static/llms-full.txt holding the old line, so `generate-llms.py --check` -- the drift guard docs-pr-build.yml runs on every PR -- fails on this branch. Regenerated with scripts/generate-llms.py; the only delta is that one line. Co-Authored-By: Claude Opus 5 (1M context) --- static/llms-full.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/static/llms-full.txt b/static/llms-full.txt index 4c3dcc1..36fa5cd 100644 --- a/static/llms-full.txt +++ b/static/llms-full.txt @@ -934,7 +934,7 @@ git submodule foreach 'git lfs pull' #### **Run EEST blockchain tests on RV32IM (via QEMU)** ```bash -cd zilkworm/qemu_runner +cd qemu_runner make eest-rv32 ``` From a70203835592c3f306035dd0890eb6565d2bb8e0 Mon Sep 17 00:00:00 2001 From: Bloxster Date: Tue, 11 Aug 2026 16:43:58 +0200 Subject: [PATCH 5/6] fix(home): hero omitted SP1_PROVER=cuda, so it would prove on CPU DynamicProver::new (prover_hypercube/src/service.rs) selects the CUDA prover only when SP1_PROVER == "cuda", and falls back to the in-process CPU prover for any other value or when unset. A hero labelled "on GPU" that omits the variable therefore describes a CPU run, which a mainnet block will not survive: the prove call is wrapped in two hardcoded 30-minute timeouts (service.rs:409-410 and :734-735) with no override on this branch. Matches the quickstart, which already passes -e SP1_PROVER=cuda. Co-Authored-By: Claude Opus 5 (1M context) --- src/pages/index.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/index.tsx b/src/pages/index.tsx index 6c3cb0d..e16c081 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -103,7 +103,7 @@ const capabilities: Card[] = [ ]; const exampleCommand = `# Prove an Ethereum mainnet block on GPU -z6m_prover --service --rpc-url $RPC_URL --data-dir ./data \\ +SP1_PROVER=cuda z6m_prover --service --rpc-url $RPC_URL --data-dir ./data \\ --start-block 23456789 --end-block 23456789 --prove-every 1 # → ./data/23456789/proof23456789.bin`; From e219cce7571a254c767b230799a6bf0535b01745 Mon Sep 17 00:00:00 2001 From: Bloxster Date: Tue, 11 Aug 2026 17:23:02 +0200 Subject: [PATCH 6/6] docs: recommended GPU example wrote no proof; add Rust to EEST prereqs running-the-prover.md: the "Proving a block on GPU" example invoked the one-shot `prove` subcommand, which keeps the proof in memory and never writes it, ignores `--proof-path`, and exits 0 even when proving fails (cli-reference.md already documents all three). So the page's headline proving example could not produce a proof, and failed silently. Replaced with service mode bounded to a single block via --start-block/--end-block, which does persist to //proof.bin, and stated the output path. Called out the two load-bearing flags, both easy to omit: SP1_PROVER=cuda (DynamicProver::new selects CUDA only on an exact "cuda" match and otherwise falls back to the CPU prover) and --prove-every 1 (a modulo on the block number, defaulting to never -- omit it and the service proves nothing). Also noted that the pre-existing --prove-every 100 continuous example only proves blocks divisible by 100. ethereum-execution-tests-eests.md: added rust/cargo to the prerequisites. The page had no mention of either, yet eest-blockchain-tests depends on eest-rlp-build, which builds z6m_eest_convert with cargo -- so the documented command cannot run without it. llms artifacts regenerated for both pages. Co-Authored-By: Claude Opus 5 (1M context) --- docs/getting-started/running-the-prover.md | 23 +++++++++++++-- .../testing/ethereum-execution-tests-eests.md | 5 ++++ static/llms-full.txt | 28 +++++++++++++++++-- 3 files changed, 50 insertions(+), 6 deletions(-) diff --git a/docs/getting-started/running-the-prover.md b/docs/getting-started/running-the-prover.md index 32bfe00..09826a9 100644 --- a/docs/getting-started/running-the-prover.md +++ b/docs/getting-started/running-the-prover.md @@ -75,18 +75,35 @@ docker run --rm -v "$PWD:/work" somnergy/z6m_prover \ execute --block-number 23100000 --data-dir /work/data ``` -Proving a block on GPU for a single block can be initiated as follows: +Proving a single block on GPU is done with service mode, bounded to one block: + ```bash docker run --rm --gpus all --network host \ -v /var/run/docker.sock:/var/run/docker.sock \ -v "$PWD:/work" \ -e SP1_PROVER=cuda \ somnergy/z6m_prover:latest \ - prove --block-number 23100000 --data-dir /work/data + --service --rpc-url "$RPC_URL" --data-dir /work/data \ + --start-block 23100000 --end-block 23100000 \ + --prove-every 1 --proof-type compressed ``` +The proof is written to `//proof.bin` — here +`/work/data/23100000/proof23100000.bin`. Service mode fetches the block and its witness itself, so no separate +`fetch` run is needed. + +:::warning +Use service mode, not the one-shot `prove` subcommand, whenever you need the proof **on disk**. `prove` keeps the +proof in memory and never writes it, ignores `--proof-path`, and exits 0 even when proving fails — see +[`prove` in the CLI reference](cli-reference.md#prove). Two flags above are load-bearing: `SP1_PROVER=cuda` (any +other value, or unset, silently selects the CPU prover) and `--prove-every 1` (it is a modulo on the block number +and defaults to *never*, so omitting it proves nothing). +::: + The docker image builds with `CUDA_ARCHS="89,90,100"` so it already bakes in support for the latest NVIDIA GPU architectures for SP1-GPU. -To prove the blocks in a continuous fashion, you can use the `--service` mode as follows: + +To keep proving continuously instead, drop the block bounds and widen the interval — with `--prove-every 100`, only +blocks whose number is divisible by 100 are proved: ```bash z6m_prover --service --rpc-url "$RPC_URL" --data-dir /mnt/data \ diff --git a/docs/testing/ethereum-execution-tests-eests.md b/docs/testing/ethereum-execution-tests-eests.md index 6c2b68b..b83f150 100644 --- a/docs/testing/ethereum-execution-tests-eests.md +++ b/docs/testing/ethereum-execution-tests-eests.md @@ -36,9 +36,14 @@ Before running the tests, make sure the following tools are installed: * `git,git-lfs` * `python3,python3-pip,pipx` * `ctest` (usually shipped with CMake, but ensure it’s available on your PATH) +* `rust/cargo` — see [rustup.rs](https://rustup.rs) > `git-lfs` is required because some test fixtures have very large files. +> Rust is required even though the tests themselves are C++: `eest-blockchain-tests` depends on `eest-rlp-build`, +> which builds the `z6m_eest_convert` fixture converter with `cargo build --release`. That build also resolves the +> `erigontech/sp1` git dependency, so the first run takes a while. + #### Clone the repository Get the latest source for Zilkworm diff --git a/static/llms-full.txt b/static/llms-full.txt index 36fa5cd..f3d0b7a 100644 --- a/static/llms-full.txt +++ b/static/llms-full.txt @@ -710,18 +710,35 @@ docker run --rm -v "$PWD:/work" somnergy/z6m_prover \ execute --block-number 23100000 --data-dir /work/data ``` -Proving a block on GPU for a single block can be initiated as follows: +Proving a single block on GPU is done with service mode, bounded to one block: + ```bash docker run --rm --gpus all --network host \ -v /var/run/docker.sock:/var/run/docker.sock \ -v "$PWD:/work" \ -e SP1_PROVER=cuda \ somnergy/z6m_prover:latest \ - prove --block-number 23100000 --data-dir /work/data + --service --rpc-url "$RPC_URL" --data-dir /work/data \ + --start-block 23100000 --end-block 23100000 \ + --prove-every 1 --proof-type compressed ``` +The proof is written to `//proof.bin` — here +`/work/data/23100000/proof23100000.bin`. Service mode fetches the block and its witness itself, so no separate +`fetch` run is needed. + +:::warning +Use service mode, not the one-shot `prove` subcommand, whenever you need the proof **on disk**. `prove` keeps the +proof in memory and never writes it, ignores `--proof-path`, and exits 0 even when proving fails — see +[`prove` in the CLI reference](cli-reference.md#prove). Two flags above are load-bearing: `SP1_PROVER=cuda` (any +other value, or unset, silently selects the CPU prover) and `--prove-every 1` (it is a modulo on the block number +and defaults to *never*, so omitting it proves nothing). +::: + The docker image builds with `CUDA_ARCHS="89,90,100"` so it already bakes in support for the latest NVIDIA GPU architectures for SP1-GPU. -To prove the blocks in a continuous fashion, you can use the `--service` mode as follows: + +To keep proving continuously instead, drop the block bounds and widen the interval — with `--prove-every 100`, only +blocks whose number is divisible by 100 are proved: ```bash z6m_prover --service --rpc-url "$RPC_URL" --data-dir /mnt/data \ @@ -853,9 +870,14 @@ Before running the tests, make sure the following tools are installed: * `git,git-lfs` * `python3,python3-pip,pipx` * `ctest` (usually shipped with CMake, but ensure it’s available on your PATH) +* `rust/cargo` — see [rustup.rs](https://rustup.rs) > `git-lfs` is required because some test fixtures have very large files. +> Rust is required even though the tests themselves are C++: `eest-blockchain-tests` depends on `eest-rlp-build`, +> which builds the `z6m_eest_convert` fixture converter with `cargo build --release`. That build also resolves the +> `erigontech/sp1` git dependency, so the first run takes a while. + #### Clone the repository Get the latest source for Zilkworm