Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 10 additions & 29 deletions docs/benchmarks.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Weigh Benchmark Results
last_updated: 2026-09-18
last_updated: 2026-10-05
tags:
- benchmark
- consensus
Expand All @@ -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 |
|---|---:|---:|---:|
Expand All @@ -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.
Expand All @@ -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`)

Expand Down Expand Up @@ -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 <zisk>/bin/ziskemu --cargo-zisk <zisk>/bin/cargo-zisk-gpu \
--proving-key <zisk>/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
Expand Down
12 changes: 2 additions & 10 deletions docs/bootstrap.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Bootstrap Contract and Validation
last_updated: 2026-09-13
last_updated: 2026-10-05
tags:
- lean
- riscv
Expand All @@ -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
Expand Down Expand Up @@ -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).
22 changes: 7 additions & 15 deletions docs/build.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -79,9 +73,7 @@ the guest's public outputs against `<scenario>.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).
11 changes: 4 additions & 7 deletions docs/helpers.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Helper Contracts and Validation
last_updated: 2026-09-13
last_updated: 2026-10-05
tags:
- consensus
- lean
Expand Down Expand Up @@ -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.
12 changes: 4 additions & 8 deletions docs/implementation-plan.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Implementation Completion Plan
last_updated: 2026-09-17
last_updated: 2026-10-05
tags:
- consensus
- verification
Expand All @@ -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.
35 changes: 10 additions & 25 deletions docs/roadmap.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand All @@ -30,15 +25,15 @@ 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.

`weigh_justification_and_finalization` is the first target because it is the
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

Expand Down Expand Up @@ -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.

Expand All @@ -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

Expand Down
24 changes: 10 additions & 14 deletions docs/weigh.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Whole-Routine Contract and Validation
last_updated: 2026-09-13
last_updated: 2026-10-05
tags:
- consensus
- lean
Expand All @@ -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.

Expand Down Expand Up @@ -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.
Expand All @@ -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,
Expand All @@ -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).
Loading