docs: fix CLI snippets that don't match the z6m_prover source - #20
Draft
bloxster wants to merge 6 commits into
Draft
docs: fix CLI snippets that don't match the z6m_prover source#20bloxster wants to merge 6 commits into
bloxster wants to merge 6 commits into
Conversation
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) <noreply@anthropic.com>
4 tasks
There was a problem hiding this comment.
Pull request overview
Updates the docs site to ensure CLI and build-command snippets match the current z6m_prover interface and zilkworm QEMU runner Makefile targets, and regenerates the LLM export to stay in sync with docs pages.
Changes:
- Fixes the landing-page hero CLI snippet to use a runnable
setup → prove → verifyflow with correct flags. - Updates the RISC-V QEMU EEST make target to
eest-rv32in the guide. - Regenerates
static/llms-full.txtto reflect the docs change.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| docs/testing/riscv-testing-eests-on-rv32im-via-qemu.md | Updates the documented QEMU runner make target to the correct one. |
| src/pages/index.tsx | Makes the homepage “hero” CLI example runnable and consistent with documented defaults/flags. |
| static/llms-full.txt | Regenerated aggregate output reflecting the updated docs page. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: bloxster <40316187+bloxster@users.noreply.github.com>
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: <data-dir>/<N>/proof<N>.bin, with no `blocks/` segment (unlike the witness input path). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
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 <data-dir>/<block>/proof<block>.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) <noreply@anthropic.com>
bloxster
marked this pull request as draft
August 13, 2026 08:16
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes documented commands that don't work against
erigontech/zilkwormmaster. Verified against the source.Proving examples pointed at a subcommand that writes nothing. Both the landing hero and the "Proving a block on GPU" example in
running-the-prover.mdused the one-shotprove, which keeps the proof in memory, ignores--proof-path, and exits 0 even on failure (cli-reference.mdalready documents all three). The hero additionally chainedsetupandverify— both no-op stubs — so it named avk.binnothing creates. Both now use service mode, the one path that persists a proof, with the output path stated.Two flags there are load-bearing and easy to omit:
SP1_PROVER=cuda(any other value, or unset, silently selects the CPU prover) and--prove-every 1(a modulo on the block number, defaulting to never).riscv-…-qemu.md—make rv32im_eest_blockchain_testsnames a target that exists in no file; the real one iseest-rv32(qemu_runner/Makefile:76). Also corrects thecd, since the page alreadycds intozilkworm.ethereum-execution-tests-eests.md— addedrust/cargoto prerequisites. The page never mentioned either, yeteest-blockchain-tests→eest-rlp-buildbuilds the fixture converter withcargo.static/llms-full.txt— regenerated. This is what was making the PR red: an earlier commit edited a docs page without regenerating the artifact, failing thegenerate-llms.py --checkdrift guard.Gates run locally before each push: drift guard, unit tests,
tsc --noEmit, full build withonBrokenLinks: throw.Not in scope: the docs also describe the internal tree (
--is-test,--download-only, andflatWitnessBundle<N>.mfbdvs the publicunifiedBlockAndStateRlp<N>.bin), and recommend a mutable:latestimage last pushed 2026-04-04. Both need a call on what these docs should track — the public repo, a pinned image digest, or internal HEAD — so they're left alone here.🤖 Generated with Claude Code