jolt: Instructions file for Claude Code

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.

Agent Workflow

• Carry an authorized request through implementation and verification. Resolve routine choices from repository conventions; ask only when missing information would materially change correctness or scope. Continue independent work while an answer is pending.
• User instructions take precedence over skill guidance. Reuse authorization and answers already supplied. If a skill blocks requested work, cite its exact file and instruction and explain the conflict.
• Read relevant code before asking about repository facts. Use rg for searches; batch independent reads when supported, and wait for required results before dependent work. Run Cargo commands sequentially, including across agents.
• Treat follow-up messages as updates to the active task unless the user cancels or replaces it.
• Lead with the result. Keep explanations concise and concrete; report checks actually run, their results, and any remaining blocker. Preserve required output formats in automated workflows.

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

# Guest x mode acceptance matrix (crates/jolt-prover/tests/e2e_matrix.rs): one
# table per instruction profile, proven in clear, ZK, and Akita modes in CI.
# Ordinary profile: ten guest cases.
cargo nextest run -p jolt-prover --features prover-fixtures -E 'binary(e2e_matrix)' --cargo-quiet
cargo nextest run -p jolt-prover --features prover-fixtures,zk -E 'binary(e2e_matrix)' --cargo-quiet
cargo nextest run -p jolt-prover --features akita,prover-fixtures -E 'binary(e2e_matrix)' --cargo-quiet

# Field-inline profile: field_ops, field_limbs, and muldiv.
cargo nextest run -p jolt-prover --features prover-fixtures,field-inline -E 'binary(e2e_matrix)' --cargo-quiet
cargo nextest run -p jolt-prover --features prover-fixtures,field-inline,zk -E 'binary(e2e_matrix)' --cargo-quiet
cargo nextest run -p jolt-prover --features prover-fixtures,field-inline,akita -E 'binary(e2e_matrix)' --cargo-quiet

# Full prover suites and the verifier fixtures (mirror CI)
cargo nextest run -p jolt-verifier standard_muldiv --features prover-fixtures --cargo-quiet
cargo nextest run -p jolt-prover --features prover-fixtures --cargo-quiet
cargo nextest run -p jolt-prover --features prover-fixtures,zk --cargo-quiet
cargo nextest run -p jolt-prover --features akita,prover-fixtures --cargo-quiet