Skip to content

docs: fix CLI snippets that don't match the z6m_prover source - #20

Draft
bloxster wants to merge 6 commits into
mainfrom
docs/fix-cli-snippets
Draft

bloxster wants to merge 6 commits into
mainfrom
docs/fix-cli-snippets

Conversation

@bloxster

@bloxster bloxster commented Aug 3, 2026 •

Copy link
Copy Markdown
Contributor

Fixes documented commands that don't work against erigontech/zilkworm master. 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.md used the one-shot prove, which keeps the proof in memory, ignores --proof-path, and exits 0 even on failure (cli-reference.md already documents all three). The hero additionally chained setup and verify — both no-op stubs — so it named a vk.bin nothing 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_tests names a target that exists in no file; the real one is eest-rv32 (qemu_runner/Makefile:76). Also corrects the cd, since the page already cds into zilkworm.

ethereum-execution-tests-eests.md — added rust/cargo to prerequisites. The page never mentioned either, yet eest-blockchain-tests → eest-rlp-build builds the fixture converter with cargo.

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 the generate-llms.py --check drift guard.

Gates run locally before each push: drift guard, unit tests, tsc --noEmit, full build with onBrokenLinks: throw.

Not in scope: the docs also describe the internal tree (--is-test, --download-only, and flatWitnessBundle<N>.mfbd vs the public unifiedBlockAndStateRlp<N>.bin), and recommend a mutable :latest image 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

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>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 → verify flow with correct flags.
  • Updates the RISC-V QEMU EEST make target to eest-rv32 in the guide.
  • Regenerates static/llms-full.txt to 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>
bloxster and others added 4 commits August 11, 2026 16:42
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
bloxster marked this pull request as draft August 13, 2026 08:16
:::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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Contradicts the SP1_PROVER modes table below: mock and network also fall back to the CPU prover.


:::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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The bounded service run also exits 0 when fetching or proving fails, so this is no contrast with prove.

* `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)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On master eest-blockchain-tests builds z6m_eest_convert with CMake; there is no eest-rlp-build target and no cargo step.

somnergy added a commit that referenced this pull request Oct 26, 2026
Rebuilds the documentation site around what Zilkworm ships. The marketing landing page and the collaboration page are gone; the docs are served at `/` and the Overview is the home page.

Structure: Overview, Provers (Choosing a prover, Airbender, Hypercube, ZisK, Ethproofs posting), Inside the guest (Execution pipeline, Witness formats, Precompiles and syscalls, Proof guarantees), Testing (Execution spec tests, RISC-V tests under QEMU, ERE validation), Reference (CLI reference, Releases and assets, Building from source, Benchmarks and CI). 17 pages.

Every fact traces to a path in zilkworm main (311749c99) or a release tag. Performance numbers appear only on Releases and assets. The Hypercube page states the current `prove`, `verify` and `setup` behaviour plainly. The rollups essay is removed from the site.

Chrome: section index pages render as terminal frames, sidebar sections start collapsed, footer keeps the brand lockup and the four social icons, navbar has Blog and GitHub. Client redirects cover every old `/documentation/...` URL and `/collaboration`.

Supersedes the CLI snippet fixes in #20, whose landing-page, GPU docker example and `cd qemu_runner` corrections are folded in here.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants