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
2 changes: 1 addition & 1 deletion DESIGN.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# CL ASM v0 — Design Proposal

Last updated: 2026-09-13. This document records the v0 design. The complete 175-instruction `weigh` routine, bounded Lean contract, concrete calling witness, ELF, and official-reference differential tests are implemented; see [Whole-Routine Contract and Validation](docs/weigh.md). The [completion plan](docs/implementation-plan.md) tracks validation and benchmark evidence.
Last updated: 2026-09-13. This document records the v0 design. The complete 175-instruction `weigh` routine, bounded Lean contract, concrete calling witness, ELF, and official-reference differential tests are implemented; see [Whole-Routine Contract and Validation](docs/weigh.md). The [completion plan](docs/implementation-plan.md) tracks validation and benchmark evidence. [The roadmap](docs/roadmap.md) records why the consensus layer is being proved, the zkVM measurements' consequences, the PoC decisions, and the remaining consensus-layer work in the lean Ethereum setting.

## 1. Agreed Scope

Expand Down
99 changes: 21 additions & 78 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,87 +1,30 @@
# CL ASM

Lean proofs and RISC-V code for Ethereum consensus-layer operations.
The v0 target is `weigh_justification_and_finalization`; see [DESIGN.md](DESIGN.md).

The complete `weigh` routine has 175 RV64 instructions (700 bytes). Its Lean
contract proves the specified state transition, resource preservation, and
return within 175 steps. Seven additional ELF probes exercise its helpers.
See [the whole-routine contract](docs/weigh.md) for the ABI, admitted inputs,
concrete calling witness, official-reference tests, and trust boundaries.

## Build and validate

Install [elan](https://github.com/leanprover/elan), Python 3.12+, and GNU RISC-V
binutils. On Debian/Ubuntu the binutils package is
`binutils-riscv64-unknown-elf`. The repository pins Lean 4.33.0 and dependency
revisions in `lean-toolchain` and `lake-manifest.json`.
Lean proofs and RISC-V code for Ethereum consensus-layer operations. The v0
target is `weigh_justification_and_finalization`: a 175-instruction RV64
routine (700 bytes) whose Lean contract proves the specified state transition,
resource preservation, and return within 175 steps. The same bytes run as a
ZisK zkVM guest.

- [DESIGN.md](DESIGN.md): scope, ABI, memory layout, trust boundaries.
- [Roadmap](docs/roadmap.md): why the consensus layer is being proved, zkVM
findings, PoC decisions, and remaining work.
- [Whole-routine contract](docs/weigh.md): preconditions, calling witness,
official-reference tests.
- [Build and validate](docs/build.md): toolchain, commands, test coverage, and
the ZisK guest.
- [Benchmarks](docs/benchmarks.md): host interpreter timing and ZisK results.

```sh
lake --no-cache --wfail build
python3 -m venv .venv
.venv/bin/python -m pip install -r tests/requirements.txt
lake env lean scripts/CheckAxioms.lean
.lake/build/bin/cl-asm build
.lake/build/bin/cl-asm-test build
python3 -m venv .venv && .venv/bin/python -m pip install -r tests/requirements.txt
.lake/build/bin/cl-asm build && .lake/build/bin/cl-asm-test build
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python scripts/benchmark.py --iterations 200 --batches 21
```

`RISCV_AS` and `RISCV_LD` select assembler and linker executables when their
names differ from `riscv64-unknown-elf-as` and `riscv64-unknown-elf-ld`.
The generator produces `.s`, `.ld`, `.o`, `.elf`, and `.program.json` files under the supplied
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.

## ZisK guest

`guest/zisk` wraps the checked `weigh.elf` for the [ZisK](https://github.com/0xPolygonHermez/zisk)
zkVM. The wrapper reads the 136-byte state, three balances, and a root seed as
input, materializes all 8192 roots as the spec's in-memory `block_roots`, calls
`weigh`, and commits the inputs and the updated state as public outputs. The
generator copies the exact 700 code bytes out of `weigh.elf` into a `.text.weigh`
section, so the routine ZisK proves is byte-identical to the one Lean proves.
The C wrapper needs a `clang` with the RISC-V target; assembly and linking use
the same GNU binutils as above.

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

The compiler defaults to `clang`; set `CLANG` to another executable when the
one on `PATH` lacks the RISC-V target. The first command writes
`build/zisk/weigh-guest.elf` and, for each of the six benchmark scenarios in
`tests/weigh_cases.py`, `build/zisk/inputs/<scenario>.bin` (the guest input
record) and `build/zisk/inputs/<scenario>.public.bin` (the 64 public output
words the guest must commit, computed from the official reference).

The second command runs on a host with ZisK installed. `<zisk>` is the ZisK
installation directory (`~/.zisk` after `ziskup`); `--proving-key` names its
`provingKey` directory. Without `--prove` only `ziskemu` is needed and no GPU
is used. The script records symbol-level step counts from `ziskemu`, checks
the guest's public outputs against `<scenario>.public.bin`, and, with
`--prove`, times proof generation and verification. It writes
`build/zisk/results/report.json` and one log per tool invocation under
`build/zisk/results/logs`. `--scenarios` selects a subset by name; `--help`
lists the remaining options and defaults. `HWLOC_COMPONENTS=-gl` stops
hwloc's GL probe from waiting on an X11 socket.
Requires elan (Lean 4.33.0 is pinned), Python 3.12+, GNU RISC-V binutils, and
a `clang` with the RISC-V target for the ZisK guest.

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](docs/benchmarks.md).
The Lean proofs cover the modeled instruction sequence. ELF generation, loading,
the interpreter conversion, and the ZisK wrapper are checked by tests, not
proved.
6 changes: 3 additions & 3 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-17
last_updated: 2026-09-18
tags:
- benchmark
- consensus
Expand Down Expand Up @@ -39,7 +39,7 @@ Fixtures are `benchmark_cases()` in `tests/weigh_cases.py` at the recorded revis

## Method and reproduction

Build the measured revision using the [README instructions](../README.md),
Build the measured revision using the [build instructions](build.md),
including the pinned Python environment and RISC-V binutils. Then run:

```sh
Expand Down Expand Up @@ -142,7 +142,7 @@ same size as the 2026-09-16 GPU proof of the same scenario

### Reproduction

Build the checked ELF as in the [README](../README.md), then:
Build the checked ELF as in [the build instructions](build.md), then:

```sh
.venv/bin/python scripts/zisk_guest.py
Expand Down
87 changes: 87 additions & 0 deletions docs/build.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
---
title: Build, Validate, and Run the ZisK Guest
last_updated: 2026-09-18
tags:
- build
- testing
- zisk
---

# Build, Validate, and Run the ZisK Guest

## Build and validate

Install [elan](https://github.com/leanprover/elan), Python 3.12+, and GNU RISC-V
binutils. On Debian/Ubuntu the binutils package is
`binutils-riscv64-unknown-elf`. The repository pins Lean 4.33.0 and dependency
revisions in `lean-toolchain` and `lake-manifest.json`.

```sh
lake --no-cache --wfail build
python3 -m venv .venv
.venv/bin/python -m pip install -r tests/requirements.txt
lake env lean scripts/CheckAxioms.lean
.lake/build/bin/cl-asm build
.lake/build/bin/cl-asm-test build
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python scripts/benchmark.py --iterations 200 --batches 21
```

`RISCV_AS` and `RISCV_LD` select assembler and linker executables when their
names differ from `riscv64-unknown-elf-as` and `riscv64-unknown-elf-ld`.
The generator produces `.s`, `.ld`, `.o`, `.elf`, and `.program.json` files under the supplied
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.

## ZisK guest

`guest/zisk` wraps the checked `weigh.elf` for the [ZisK](https://github.com/0xPolygonHermez/zisk)
zkVM. The wrapper reads the 136-byte state, three balances, and a root seed as
input, materializes all 8192 roots as the spec's in-memory `block_roots`, calls
`weigh`, and commits the inputs and the updated state as public outputs. The
generator copies the exact 700 code bytes out of `weigh.elf` into a `.text.weigh`
section, so the routine ZisK proves is byte-identical to the one Lean proves.
The C wrapper needs a `clang` with the RISC-V target; assembly and linking use
the same GNU binutils as above.

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

The compiler defaults to `clang`; set `CLANG` to another executable when the
one on `PATH` lacks the RISC-V target. The first command writes
`build/zisk/weigh-guest.elf` and, for each of the six benchmark scenarios in
`tests/weigh_cases.py`, `build/zisk/inputs/<scenario>.bin` (the guest input
record) and `build/zisk/inputs/<scenario>.public.bin` (the 64 public output
words the guest must commit, computed from the official reference).

The second command runs on a host with ZisK installed. `<zisk>` is the ZisK
installation directory (`~/.zisk` after `ziskup`); `--proving-key` names its
`provingKey` directory. Without `--prove` only `ziskemu` is needed and no GPU
is used. The script records symbol-level step counts from `ziskemu`, checks
the guest's public outputs against `<scenario>.public.bin`, and, with
`--prove`, times proof generation and verification. It writes
`build/zisk/results/report.json` and one log per tool invocation under
`build/zisk/results/logs`. `--scenarios` selects a subset by name; `--help`
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).
Loading
Loading