This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
leanMultisig is a minimal hash-based zkVM targeting recursion and aggregation of XMSS (hash-based) signatures for a Post-Quantum Ethereum. It uses a multilinear proving system with WHIR, SuperSpartan (AIR-specific), and Logup.
The base field is KoalaBear (31-bit prime field) with a degree-5 extension for 123 bits of provable security.
# Build (release, with native CPU features via .cargo/config.toml)
cargo build --release
# Run all tests (alias defined in .cargo/config.toml)
cargo testall # equivalent to: cargo test --all --release
# Run a single test
cargo test --release -p <crate_name> <test_name>
# Check all SIMD targets (neon, AVX2, AVX512)
./src/check_all_targets.sh
# Run benchmarks
cargo run --release -- xmss --n-signatures 1400
cargo run --release -- recursion --n 2
cargo run --release -- poseidon --log-n-perms 16
cargo run --release -- fancy-aggregation
# Use conjectured security (smaller proofs) via feature flag
cargo run --release --features prox-gaps-conjecture -- xmss --n-signatures 1400backend/— Cryptographic backend, re-exported as a single crate. Contains sub-crates:field/— Generic field trait and arithmetickoala-bear/— KoalaBear field implementation + Poseidon2 hashpoly/— Multilinear polynomial representations (dense, evaluations, eq-MLE)air/— AIR (Algebraic Intermediate Representation) symbolic constraintssumcheck/— Sumcheck protocolfiat-shamir/— Transcript, challenger, Merkle proofssymetric/— Symmetric crypto primitives (Merkle trees, hashing)utils/— Shared utilities (Poseidon2 helpers, multilinear ops, display)
whir/— WHIR polynomial commitment scheme (commit, open, verify)lean_compiler/— Compiles zkDSL (Python-like syntax) to VM bytecode. Pipeline: parse (pest grammar) → simplify → intermediate compile → final compilelean_vm/— Minimal VM: ISA definition, execution engine, trace tableslean_prover/— Generates execution traces and proves/verifies VM executionsub_protocols/— Logup, quotient GKR, stacked polynomial commitmentair/— Top-level AIR prove/verify orchestration (SuperSpartan for AIR)xmss/— XMSS signature scheme (WOTS+, key gen, sign, verify)rec_aggregation/— Recursive proof aggregation with tree topologies
- zkDSL source (.py files) →
lean_compiler→ bytecode - Bytecode →
lean_vmexecutes → execution trace - Trace →
lean_prover→ AIR constraints →aircrate proves via SuperSpartan + sumcheck - Polynomial commitments via
whir(WHIR PCS) - Aggregation:
rec_aggregationcomposes proofs recursively in a tree (AggregationTopology)
Programs are written in a Python-like DSL (see crates/lean_compiler/zkDSL.md). Key features: SSA memory model (write-once), unroll/range/dynamic_unroll loops, compile-time const evaluation, DynArray, precompiles for Poseidon16 and extension field ops. DSL files can also run as Python scripts via snark_lib.py.
The root crate exposes a public API for XMSS operations:
setup_prover()/setup_verifier()— one-time initializationxmss_key_gen,xmss_sign,xmss_verify— signature operationsxmss_aggregate,xmss_verify_aggregation— recursive proof aggregation
- Rust edition 2024,
max_width = 120(rustfmt) - Clippy: all + nursery + pedantic enabled (with some relaxations, see workspace
Cargo.toml) - All AIR columns use the base field only; extension field operations are done via AIR constraints
- Native CPU features enabled by default (
target-cpu=nativein.cargo/config.toml) --releaseis expected for all meaningful runs (proving is compute-intensive)- zkDSL comments: use
"""..."""multi-line strings for section separators and block explanations. Do NOT use# ── ... ──or similar#-based banner lines to section off code.
There are two conversation modes. Read the user's request carefully to determine which applies.
Used for small, well-defined changes: bug fixes, targeted features, tests, minor refactors.
- Implement directly without extensive scoping or back-and-forth
- Ask clarifying questions only if truly ambiguous and the wrong choice would waste significant effort
- Keep responses concise; skip lengthy preamble
Used for larger features, architectural decisions, or anything with significant design surface.
Phase 1 — Scoping (before any code is written):
- Present a plan/outline when asked: list components, design choices, open questions, trade-offs
- Iterate on the plan through back-and-forth; revise based on feedback
- Do NOT write implementation code until the user explicitly approves the plan
- Approval phrases to watch for: "approved", "go ahead", "implement it", "looks good, proceed", or equivalent
Phase 2 — Implementation (after approval):
- Implement according to the approved plan
- Flag deviations from the plan before making them, not after
Note: The style of slow conversations will evolve as the user becomes more proficient with the codebase. Update this section periodically to reflect the current working style.
The crates/sphincs/ crate is complete: keygen, sign, and verify are all implemented.
Parameters: KoalaBear field, 8-FE Poseidon2 digests, V=32 WOTS+ chains (w=16, TARGET_SUM=240),
9-tree FORS (height 15), 3-layer hypertree (height 11 per layer).
A provable zkDSL verifier lives in rec_aggregation/. Scope is raw SPHINCS+
signature verification only — no recursive aggregation. The architectural plan is at
docs/SPHINCS_ZKDSL_PLAN.md; all design decisions are resolved there.
Do not re-open those decisions without reading the plan first.
zkDSL implementation status:
sphincs_utils.py,sphincs_wots.py— implemented and testedsphincs_fors.py— implemented; FORS Merkle test is compile-only pending a compiler fix (runtime%onMutvariables is not yet handled in the compiler)sphincs_hypertree.py,sphincs_aggregate.py— implemented, not yet testedmain_sphincs.py— implemented (batch verifier, per-signer independent messages, public input = hash of [n_sigs | pubkeys | messages])
All test programs follow this pattern:
Python — call build_preamble_memory() first, pull all test data via hint_witness, assert internally. Do not read raw test data from pub_mem.
Rust — pass vec![F::from_usize(0); DIGEST_LEN] as public input (8 zeros), put all test data in hints: HashMap<String, Vec<Vec<F>>>, use ExecutionWitness { preamble_memory_len: PREAMBLE_MEMORY_LEN, hints }.
Why the 8-zero public input matters: hashing.py hardcodes ZERO_VEC_PTR = PUBLIC_INPUT_LEN = 8. The VM places the preamble at [public_memory_size..public_memory_size+PREAMBLE_MEMORY_LEN). Passing exactly 8 FEs aligns the preamble at [8..53), matching all preamble pointer constants. Any other size misaligns the preamble and causes MemoryAlreadySet errors.
For full (non-test) programs, the 8-FE public input is the hash of all witness data; the Python reads and verifies it at address 0. See tests/test_hashing.py and tests/test_hashing.rs for the canonical example.