diff --git a/docs/benchmarks.md b/docs/benchmarks.md index 0212b63..59107a5 100644 --- a/docs/benchmarks.md +++ b/docs/benchmarks.md @@ -1,6 +1,6 @@ --- title: Weigh Benchmark Results -last_updated: 2026-09-18 +last_updated: 2026-10-05 tags: - benchmark - consensus @@ -10,10 +10,8 @@ tags: # Weigh Benchmark Results -The complete checked `weigh.elf` uses 99–147 modeled RV64 instructions across -these scenarios. On the host below, the median batch-average interpreter time -was 2.212–4.999 ms per call. The proved static bound is 175 instructions and the -executable code is 700 bytes. +The proved static bound and executable size are in +[the whole-routine contract](weigh.md). | Scenario | RV64 steps | Median ms/call | Min–max batch average ms/call | |---|---:|---:|---:| @@ -39,15 +37,10 @@ Fixtures are `benchmark_cases()` in `tests/weigh_cases.py` at the recorded revis ## Method and reproduction -Build the measured revision using the [build instructions](build.md), -including the pinned Python environment and RISC-V binutils. Then run: - -```sh -.venv/bin/python scripts/benchmark.py --iterations 200 --batches 21 -``` - -`RISCV_AS` and `RISCV_LD` can select explicit binutils paths. The script validates -the independently assembled ELF bytes and compares scenario results with the +Build the measured revision using the +[build instructions](build.md#build-and-validate), including the pinned Python +environment and RISC-V binutils. `scripts/benchmark.py` validates the +independently assembled ELF bytes and compares scenario results with the official function. Each scenario runs 100 warmup calls and 21 batches of 200 calls. Timings use `IO.monoNanosNow`; the table reports the median and range of the 21 batch averages, rather than individual-call latency percentiles. @@ -70,8 +63,6 @@ same 700 code bytes (SHA-256 `a147a194…3c9cb8`) as `weigh.elf`, and every loadable code and data section of `weigh-guest.elf` is byte-identical to the guest measured on 2026-09-16, so both measurement dates below describe the same program. All scenarios are the same `benchmark_cases()` fixtures as above. -The guest wrapper materializes all 8192 `block_roots` in memory, as the spec's -in-memory `BeaconState` does; `weigh` itself reads two of them. ### Steps and cost model (2026-09-17, `ziskemu -X -S`) @@ -142,19 +133,9 @@ same size as the 2026-09-16 GPU proof of the same scenario ### Reproduction -Build the checked ELF as in [the build instructions](build.md), then: - -```sh -.venv/bin/python scripts/zisk_guest.py -HWLOC_COMPONENTS=-gl .venv/bin/python scripts/benchmark_zisk.py --prove --gpu \ - --ziskemu /bin/ziskemu --cargo-zisk /bin/cargo-zisk-gpu \ - --proving-key /provingKey -``` - -Without `--prove` the script only runs the emulator, which needs no GPU. Every -tool invocation's output is written under `build/zisk/results/logs`, and -`report.json` records stage timings parsed from `cargo-zisk prove -vv`, the -trace-table instances, proof sizes and hashes, and verification wall time. +Commands are in [the ZisK guest instructions](build.md#zisk-guest). `report.json` records +stage timings parsed from `cargo-zisk prove -vv`, the trace-table instances, +proof sizes and hashes, and verification wall time. These numbers show where proving time goes for a routine far below one segment. Instruction-count reductions in `weigh` cannot change GPU proof time diff --git a/docs/bootstrap.md b/docs/bootstrap.md index 8b0fe8d..0cdcc80 100644 --- a/docs/bootstrap.md +++ b/docs/bootstrap.md @@ -1,6 +1,6 @@ --- title: Bootstrap Contract and Validation -last_updated: 2026-09-13 +last_updated: 2026-10-05 tags: - lean - riscv @@ -9,11 +9,6 @@ tags: # Bootstrap Contract and Validation -The foundation establishes the build, proof, code-generation, and execution -path for `epochAtSlot`. The [helper stage](helpers.md) extends that path to six -more callable probes. The [whole-routine contract](weigh.md) documents the -complete `weigh` implementation built on this foundation. - ## Callable probe `EpochAtSlot.program state dst` is the inline two-instruction helper: load the @@ -93,7 +88,4 @@ loader, and consistency checks also remain outside the formal proof. ## Whole routine -The helper stage now supplies checkpoint/root ownership, arithmetic macros, -root addressing, copying, bounded callable proofs, and ELF tests. These are -composed into the [complete `weigh` contract](weigh.md), including the state, -root-array ownership, arithmetic conditions, and ordered conditional updates. +See the [complete `weigh` contract](weigh.md). diff --git a/docs/build.md b/docs/build.md index 29d736b..e69b7fb 100644 --- a/docs/build.md +++ b/docs/build.md @@ -1,6 +1,6 @@ --- title: Build, Validate, and Run the ZisK Guest -last_updated: 2026-09-18 +last_updated: 2026-10-05 tags: - build - testing @@ -34,14 +34,8 @@ output directory. Compression and linker relaxation are disabled; the image uses RV64IM with LP64 and contains only 4-byte instructions. Each probe has its own ELF entry point. `weigh.elf` uses the internal ABI from the design. -The tests execute 1,747 helper cases and 4,796 full-routine cases against the -pinned official Python function and its actual SSZ integer types. Coverage -includes genesis, all four-bit patterns, threshold equality and integer limits, -root-index wraparound, and ordered checkpoint overwrites. They check independent -instruction encodings, state results, preserved registers and initialized memory, -return, and fuel bounds. -Additional tests reject wrong arithmetic, register corruption, misplaced -stores, traps, infinite execution, altered ELF metadata/bytes, and tool failures. +Helper cases are in [the helper contracts](helpers.md). Full-routine cases are in +[the whole-routine contract](weigh.md). ## ZisK guest @@ -79,9 +73,7 @@ the guest's public outputs against `.public.bin`, and, with lists the remaining options and defaults. `HWLOC_COMPONENTS=-gl` stops hwloc's GL probe from waiting on an X11 socket. -The Lean proofs cover the modeled instruction sequence. ELF generation, -decoding, loading, execution-state conversion, and the ZisK wrapper are checked -by tests and are not formally proved. Benchmarks report RV64 instruction counts -separately from host interpreter time, and ZisK step counts separately from -GPU proving time; they do not measure native RV64 execution. -See [the recorded results and reproduction steps](benchmarks.md). +Trust boundaries are in +[the bootstrap contract](bootstrap.md#validation-and-trust-boundaries). Scope is in +[the completion plan](implementation-plan.md). +See [the recorded results](benchmarks.md). diff --git a/docs/helpers.md b/docs/helpers.md index c5f4dec..2039bb1 100644 --- a/docs/helpers.md +++ b/docs/helpers.md @@ -1,6 +1,6 @@ --- title: Helper Contracts and Validation -last_updated: 2026-09-13 +last_updated: 2026-10-05 tags: - consensus - lean @@ -99,12 +99,9 @@ operands, a corrupted return in every probe, and assembler failure. The axiom audit covers all new proofs and their imported RV64 dependencies, including private declarations recovered from Lean's internal name prefix. Negative tests inject unused public and private axioms and require rejection. -Only `propext`, `Classical.choice`, and `Quot.sound` are permitted. ELF generation -and interpreter conversion retain the [bootstrap trust boundaries](bootstrap.md). +The permitted axioms, ELF generation, and interpreter conversion retain the +[bootstrap trust boundaries](bootstrap.md#validation-and-trust-boundaries). ## Whole routine -The [complete `weigh` contract](weigh.md) composes these helpers with both -justification updates and all four finalization checks. It includes the state -and root-array ownership, arithmetic and temporal preconditions, a bounded -return proof, a concrete calling witness, and official Python differential tests. +The [complete `weigh` contract](weigh.md) composes these helpers. diff --git a/docs/implementation-plan.md b/docs/implementation-plan.md index 57091e6..768c912 100644 --- a/docs/implementation-plan.md +++ b/docs/implementation-plan.md @@ -1,6 +1,6 @@ --- title: Implementation Completion Plan -last_updated: 2026-09-17 +last_updated: 2026-10-05 tags: - consensus - verification @@ -25,10 +25,6 @@ benchmarks. Helper proofs and passing helper tests alone do not complete it. | ZisK guest and zkVM measurements | Byte-identical embedded routine, reference-checked public outputs, symbol-level steps separated from GPU proving time and fixed overheads | Complete: [ZisK section](benchmarks.md#zisk-zkvm-measurements); stateless root access deferred to [issue #4](https://github.com/NyxFoundation/cl-asm/issues/4) | | Final review | Requirement audit, source build, tests, axiom audit, workflow lint | Complete locally; [PR #2 checks](https://github.com/NyxFoundation/cl-asm/pull/2/checks) gate delivery | -The [whole-routine contract](weigh.md) records the input mapping, preservation, -proof composition, inhabited witness, official-reference extraction, and trust -boundaries. The final benchmark must identify a clean source revision and ELF -hash, retain raw batch times, and separate modeled RV64 steps from host timing. -Cases outside the calling preconditions are reported separately from successful -differential cases. Formal ELF correspondence remains outside the approved v0 scope; zkVM execution -proofs are measured but not part of the Lean contract. +Formal ELF correspondence remains outside the approved v0 scope; zkVM execution +proofs are measured but not part of the Lean contract. Cases outside the calling +preconditions are reported separately from successful differential cases. diff --git a/docs/roadmap.md b/docs/roadmap.md index 4eef364..e25cfce 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,6 +1,6 @@ --- title: Purpose and Roadmap for Proving the Consensus Layer -last_updated: 2026-09-18 +last_updated: 2026-10-05 tags: - consensus - zkvm @@ -9,13 +9,8 @@ tags: # Purpose and Roadmap for Proving the Consensus Layer -This document records why `weigh_justification_and_finalization` was chosen, -where it sits in the beacon chain's state transition, what the 2026-09-17 -ZisK measurements established, which decisions were taken for the PoC, and -which parts of the consensus layer remain candidates for zkVM proving as -Ethereum moves to a proven execution layer and hash-based signatures. It is a -statement of direction, not a specification; the contracts and measurements -it cites live in [the whole-routine contract](weigh.md) and +This document is a statement of direction, not a specification; the contracts +and measurements it cites live in [the whole-routine contract](weigh.md) and [the benchmark record](benchmarks.md). ## 1. Why prove the consensus-layer state transition @@ -30,7 +25,7 @@ re-executes" with "one prover executes, everyone verifies a proof", and it makes the verified claim "the specification's transition" rather than "what client X computed", provided the proved program is itself shown equivalent to the specification. That is the role of the Lean proof in this repository: the -zkVM proves that the 175-instruction program ran, and Lean proves that this +zkVM proves that the program ran, and Lean proves that this program implements the specified transition, so neither trust assumption depends on a client implementation. @@ -38,7 +33,7 @@ depends on a client implementation. consensus conclusion (which checkpoint is final) while containing no hashing and no signature checks, so the whole pipeline (Lean contract, ELF emission, byte checking, official-reference differential tests, zkVM execution and -proof) can be exercised end to end on a 700-byte program. +proof) can be exercised end to end. ## 2. Where the routine sits @@ -70,20 +65,10 @@ opaque 32-byte values. ## 3. What the zkVM measurements established -The [ZisK measurements](benchmarks.md#zisk-zkvm-measurements) on an RTX 5090 -gave, per scenario, 99–147 ZisK steps for `weigh` (equal to the modeled RV64 -step counts), about 74,400 steps for the guest wrapper that materializes the -8192-entry root array, and 1.8–2.0 s of GPU proof generation that does not -vary with the scenario. ZisK proves fixed 2^22-row trace tables per segment; -this workload fills under 2% of the main table, so 97.6% of ZisK's own cost -model is the fixed base cost of one segment. Consequences: - -- Instruction-count reductions in `weigh` cannot change proof time until a - workload exceeds one segment. The figure to track is steps by symbol, not - wall time. -- Per-process overheads (about 6.7 s of proving-key loading, a one-time GPU - cache build) dominate the measured wall time. They are deployment costs, to - be removed by a resident prover, not properties of the routine. +Consequences of the [ZisK measurements](benchmarks.md#zisk-zkvm-measurements): + +- Per-process overheads dominate the measured wall time. They are deployment + costs, to be removed by a resident prover, not properties of the routine. - Meaningful cost measurement starts when loops over validators enter the guest. The wrapper's root initialization is already 500 times the routine. @@ -94,7 +79,7 @@ model is the fixed base cost of one segment. Consequences: | State access model | Follow the beacon spec's in-memory `BeaconState`: pass all 8192 roots as input | The PoC conforms to the spec as written. Stateless access with SSZ Merkle proofs is recorded in [issue #4](https://github.com/NyxFoundation/cl-asm/issues/4) for later | | Headline metric | `weigh` steps by symbol and ZisK's internal proof-generation time; wall time, key loading, and setup reported as separate overheads | The user's criterion is practical usability of the whole STF; one-time and per-process costs do not bear on it | | Resident prover | Future work | ZisK ships coordinator and worker binaries; not needed to judge the routine | -| GPU re-measurement | Not repeated for this revision | The guest built from the repository is byte-identical in every code and data section to the one measured on 2026-09-16 | +| GPU re-measurement | Not repeated for this revision | The guest built from the repository is byte-identical in every code and data section to the one measured on 2026-09-16 ([ZisK measurements](benchmarks.md#zisk-zkvm-measurements)) | ## 5. Remaining consensus-layer work for a zkVM diff --git a/docs/weigh.md b/docs/weigh.md index 76467e1..43c091e 100644 --- a/docs/weigh.md +++ b/docs/weigh.md @@ -1,6 +1,6 @@ --- title: Whole-Routine Contract and Validation -last_updated: 2026-09-13 +last_updated: 2026-10-05 tags: - consensus - lean @@ -11,7 +11,7 @@ tags: # Whole-Routine Contract and Validation `ClAsm.Weigh.program` implements `weigh_justification_and_finalization` with -175 uncompressed RV64 instructions, including its return. It implements the +175 uncompressed RV64 instructions (700 bytes), including its return. It implements the inner routine; the caller's first-two-epochs skip is not part of this operation. `SLOTS_PER_EPOCH = 32` and `SLOTS_PER_HISTORICAL_ROOT = 8192` are fixed. @@ -75,7 +75,7 @@ Each block is connected to a checked contiguous slice of the exact `Program`. `Weigh.Meaning.executionResult_correct` identifies its word-level result with the mathematical state transition. `Weigh.Correctness.program_spec` combines these into the full frame-preserving bounded contract, with a limit of 175 steps. -This is a conservative static bound; measured paths use 99–147 steps. +This is a conservative static bound; measured paths are in [the benchmark results](benchmarks.md). `Weigh.Witness` constructs a complete inhabited call: code, all ABI registers, 136-byte state, all 8192 roots, 80-byte scratch, and an outside-code return. @@ -100,7 +100,7 @@ finalization rule and competing overwrites, ring-buffer boundaries, genesis, and deterministic random inputs. Out-of-contract range/time cases and malformed input are rejected separately. The harness checks preserved registers and initialized memory, both saved scratch checkpoints, successful return, and failure with one fewer than the -actually consumed steps. The seven helper probes add 1,747 cases. +actually consumed steps. The seven helper probes are in [the helper contracts](helpers.md). The generator emits `weigh.program.json` from the proved instruction sequence. An independent Python encoder assembles its raw instruction words separately, @@ -112,13 +112,9 @@ inject public/private axioms, and exercise invalid executions and tool failures. The Lean theorem covers the pinned RV64 model and reference-condition translation. Translation from official Python semantics is reviewed and tested, -not machine-proved. The emitter, GNU assembler/linker, ELF loader, byte checker, -and efficient interpreter state conversion are also tested boundaries. -The dependency's decoding-to-Sail and execution-state simulation gaps remain -as documented in [the bootstrap contract](bootstrap.md). - -The axiom audit includes imported and private declarations and permits only -`propext`, `Classical.choice`, and `Quot.sound`. No `sorryAx` or compiler-trusting -proof axioms are accepted. ELF output is generated from proved model code and -validated by tests; it is not itself formally certified. zkVM integration and -individual execution proofs remain outside the v0 scope. +not machine-proved. The byte checker and efficient interpreter state conversion +are tested boundaries. Other tested boundaries, the permitted axioms, and the +dependency's decoding-to-Sail and execution-state simulation gaps are in +[the bootstrap contract](bootstrap.md#validation-and-trust-boundaries). +ELF output is generated from proved model code and validated by tests; it is not +itself formally certified. Scope is in [the completion plan](implementation-plan.md).