jolt CLAUDE.md

CLAUDE.md

Project Overview

Jolt is a zkVM (zero-knowledge virtual machine) for RISC-V (RV64IMAC) that efficiently proves and verifies program execution. It uses sumcheck-based protocols, multilinear polynomial commitments (Dory), and the Twist/Shout lookup argument.

Essential Commands

Linting and Formatting

# Must pass in both standard and ZK modes
cargo clippy --all --features host -q --all-targets -- -D warnings
cargo clippy --all --features host,zk -q --all-targets -- -D warnings
cargo fmt -q

Testing

# Always cargo nextest, never cargo test
cargo nextest run --cargo-quiet

# Run specific test in specific package
cargo nextest run -p [package_name] [test_name] --cargo-quiet

# Primary correctness check — run muldiv e2e test in both modes
cargo nextest run -p jolt-prover-legacy muldiv --cargo-quiet --features host
cargo nextest run -p jolt-prover-legacy muldiv --cargo-quiet --features host,zk

# Modular prover acceptance suites (mirror CI): clear-mode byte-diff ratchets
# vs the legacy prover, and the modular ZK e2e (muldiv accept, tamper reject,
# advice, committed program)
cargo nextest run -p jolt-prover --features prover-fixtures --cargo-quiet
cargo nextest run -p jolt-prover --features prover-fixtures,zk --cargo-quiet

Building

# Prefer clippy over build for validation. Only build when preparing to execute a binary.
cargo build -p jolt-prover-legacy -q

# After pulling changes, reinstall the jolt CLI or guest builds may fail.
cargo install --path . --locked

Profiling

# Modular prover (primary): emits benchmark-runs/{timestamp}_modular_{name}_{scale}/ containing trace.json
# (Perfetto UI / trace_processor SQL), summary.json (machine-queryable), and memory.html,
# with benchmark-runs/latest_modular_{name}_{scale} symlinked to the newest successful run.
cargo run --release -p jolt-prover --features profiling -- profile --name fibonacci --format chrome
# --name options (default scale): fibonacci (16), sha2-chain (22), sha3-chain (22), btreemap (20)
# --scale <log2 trace length> overrides; --format none = no-subscriber Instant baseline
# --backend reference (default, naive test oracle) | optimized (performance tier, legacy-parity);
# optimized artifacts get an _optimized suffix on the run dir and latest_ symlink

# Canonical summary queries (no Perfetto UI needed) — see book/src/usage/profiling/zkvm_profiling.md
jq '.stages | map({label, s: (.wall_time_ns/1e9)})' benchmark-runs/latest_modular_fibonacci_16/summary.json
jq '.spans | to_entries | sort_by(-.value.total_ns) | .[:10]' benchmark-runs/latest_modular_fibonacci_16/summary.json

# Multi-scale sweep (one profile subprocess per run; results in benchmark-runs/modular_timings.csv,
# rendered by scripts/benchmark_summary.py, plot_benchmarks.py, plot_memory_usage.py)
cargo run --release -p jolt-prover --features profiling -- benchmark --min-scale 18 --max-scale 21 --resume

# Per-batch heap snapshots (*.folded in the run directory, exact bytes; totals in summary.json's .heap; rendered by memory.html)
cargo run --release -p jolt-prover --features profiling,allocative -- profile --name fibonacci --format chrome

# jolt-eval telemetry objectives over the same summary (grammar: telemetry:<workload>:<metric>)
cargo run -p jolt-eval --bin measure-objectives -- --objective telemetry:fibonacci:prover_time_s

# Legacy prover
cargo run --release -p jolt-prover-legacy profile --name sha3 --format chrome
# --name options: sha2, sha3, sha2-chain, sha3-chain, fibonacci, btreemap
RUST_LOG=debug cargo run --release --features allocative -p jolt-prover-legacy profile --name sha3 --format chrome