Skip to content

CLAUDE.md

Latest commit

 

History

History
204 lines (163 loc) · 9.08 KB

CLAUDE.md

File metadata and controls

204 lines (163 loc) · 9.08 KB

STWO Cairo — Circle STARK Prover & Verifier for the Cairo CPU

STWO Cairo is StarkWare's production Circle STARK prover and verifier for the Cairo CPU architecture. The stwo core library provides generic, AIR-agnostic proving and verification logic. This repo adds the Cairo-specific AIR and builds the full prover and verifier in both Rust and Cairo — the Cairo verifier enables recursive proof verification on-chain. Soundness bugs are catastrophic and irreversible — an accepted invalid proof or rejected valid proof is a protocol failure with no recovery path.

See the Cairo paper for the CPU architecture specification.

Priority Contract

All agent behavior is governed by this hierarchy. No exception, no override.

  1. SOUNDNESS & SECURITY — Cryptographic correctness is absolute.
  2. PRODUCTION QUALITY — All tests pass. All gates hold. No guardrail bypassed.
  3. PERFORMANCE — Prover performance is a correctness property. Regressions block.

Stack

Layer Technology Notes
Prover language Rust nightly-2025-06-23 See stwo_cairo_prover/rust-toolchain.toml
Cairo verifier language Cairo (2024_07 edition) Scarb 2.15.0, for recursive verification
Field Mersenne31 (M31) CM31, QM31 extension tower. p = 2^31 - 1
Proof system Circle STARKs (via stwo) FRI-based, circle group C(F_p)
Cairo VM cairo-vm 3.2.0 Trace extraction from Cairo CPU execution
Test runner (Rust) nextest Custom profiles in .config/nextest.toml
Test runner (Cairo) scarb test Feature-matrix tested in CI
CI GitHub Actions See .github/workflows/cairo-ci.yaml
Hash functions Blake2s, Blake2sM31, Poseidon252 Configurable via verifier features

Workspace Structure

stwo_cairo_prover/                 Rust workspace — prover side
  crates/
    prover/                        Core STARK prover for Cairo CPU traces
      src/witness/components/      [AIR-GENERATED] 50+ opcode/builtin witness generators
    adapter/                       Converts Cairo VM traces → Stwo prover format
      src/opcodes.rs               Opcode state transitions
      src/builtins.rs              Builtin segment handling
      src/memory.rs                Memory trace management
    cairo-air/                     [SOUNDNESS-CRITICAL] Generated AIR-specific logic for the Cairo CPU
      src/components/              Component constraint definitions
      src/relations.rs             Relation IDs (generated hashes)
    common/                        Shared types, preprocessed columns
    cairo-serialize/               Proof serialization/deserialization
    cairo-serialize-derive/        Derive macros for serialization
    utils/                         Utility functions
    dev_utils/                     Dev tools: prove, verify, run_and_prove, etc.
  scripts/
    clippy.sh                      Clippy (all crates, all features)
    rust_fmt.sh                    Rust formatting
    bump_stwo_deps.sh              Update stwo dependency revision
    fetch_large_files.sh           Download test data
  test_data/                       16+ test directories with proof fixtures

stwo_cairo_verifier/               Cairo workspace — verifier side (recursive proving)
  crates/
    cairo_verifier/                Main verifier entry point
    cairo_air/                     [SOUNDNESS-CRITICAL] Generated AIR-specific logic in Cairo
    verifier_core/                 [SOUNDNESS-CRITICAL] Core verification logic
      src/fields/                  [SOUNDNESS-CRITICAL] M31, CM31, QM31 field arithmetic
      src/vcs/                     [SECURITY-CRITICAL] Vector commitment schemes
      src/channel/                 [SECURITY-CRITICAL] Fiat-Shamir channels
      src/pcs.cairo                [SOUNDNESS-CRITICAL] PCS verification
    constraint_framework/          Constraint framework in Cairo
    bounded_int/                   Bounded integer operations
    verifier_utils/                Verifier utility functions
    cairo_verifier_mock/           Mock verifier for testing

Auto-Generated Code

Many files in stwo_cairo_prover/crates/prover/src/witness/components/, parts of cairo-air/, and parts of stwo_cairo_verifier/ are generated by the stwo-air-infra repository (private). These files are marked with // This file was created by the AIR team. Do not manually modify generated files — changes will be overwritten on next generation.

Commands

Prover (Rust) — run from stwo_cairo_prover/

# Build
cargo build --release

# Test (standard)
cargo nextest run --cargo-profile witness-opt-1 --features=slow-tests -j 1
# Environment required for tests:
#   RUST_MIN_STACK=4194304
#   RUSTFLAGS="-C target-cpu=native"

# Clippy
scripts/clippy.sh

# Format
scripts/rust_fmt.sh --check          # Check only
scripts/rust_fmt.sh                  # Auto-format

# Wasm check (prover)
RUSTFLAGS='--cfg getrandom_backend="custom"' cargo check \
  --target wasm64-unknown-unknown -Z build-std=std,panic_abort \
  --package stwo-cairo-prover --release

# Wasm check (cairo-air, no_std)
cargo check --package cairo-air --no-default-features \
  --target wasm32-unknown-unknown --release

Verifier (Cairo) — run from stwo_cairo_verifier/

# Format
scarb fmt --check

# Lint (use any valid feature flag combination)
scarb lint --features=<feature> --deny-warnings
# Feature flags: poseidon252_verifier, qm31_opcode,
#   blake_outputs_packing, poseidon_outputs_packing

# Test (per-package, per-feature)
scarb test --features=<feature> --package <package>

# Execute verifier with proof
scarb --profile proving execute --package stwo_cairo_verifier \
  --features <feature> --print-resource-usage --output none \
  --arguments-file <proof_file>

CI

See .github/workflows/cairo-ci.yaml for the full list of CI jobs.

Mathematical Context

This project includes the handwritten and generated AIR-specific logic for the Cairo CPU. It includes both the constraint evaluation and witness generation. It also includes logic for converting Cairo VM execution to prover input. The AIR is generated by stwo-air-infra (private). The core cryptographic proving primitives live in the stwo repository. The Cairo verifier enables recursive proving — a Cairo program can verify a STARK proof of another Cairo execution.

Note: "Cairo" is overloaded — it refers to both a CPU architecture and a programming language (sometimes called Cairo1). This repo includes a Cairo1 verifier for recursive proving.

Key references:

Operation Boundaries

Forbidden (NEVER do these)

  • Modify constraint definitions, field arithmetic, FRI parameters, Fiat-Shamir channel, verifier logic, or commitment scheme without human approval
  • Disable, bypass, or weaken any test, lint, or CI gate
  • Manually edit files marked // This file was created by the AIR team. — use stwo-air-infra
  • Accept a paper-code divergence as "probably fine" without documentation and review
  • Reduce security parameters (blowup factor, query count, grinding bits)

Supervised (state intent, get approval)

Before modifying ANY [SOUNDNESS-CRITICAL] or [SECURITY-CRITICAL] file:

  1. Identify the paper section or stwo core component governing the logic
  2. State the mathematical invariant the change must preserve
  3. State how the change preserves it
  4. Identify the test that will verify this
  5. Get explicit human approval
  6. After the change: verify all tests pass

Autonomous (proceed freely)

  • Read any file
  • Add/modify/remove tests
  • Fix lint, clippy, formatting
  • Add documentation
  • Add benchmarks
  • Refactor within a module without changing external interface or math behavior
  • Modify dev_utils, scripts, CI configuration

Key Architectural Decisions

  1. Dual-language architecture: Rust prover and verifier + Cairo verifier. The Cairo verifier enables recursive proving — verifying Cairo proofs inside Cairo execution.
  2. Feature-gated hash functions: The verifier supports multiple hash backends (Blake2s, Poseidon252) via Scarb features. Tests run a matrix of feature combinations.
  3. AIR code generation: Component witness generators and constraint definitions are generated by stwo-air-infra. Manual edits to generated files will be lost.
  4. Wasm compatibility: Both the prover (wasm64) and cairo-air (wasm32) must compile to WebAssembly. This is enforced by CI.
  5. Stable Rust compatibility: All crates except stwo-cairo-prover and stwo-cairo-dev-utils must compile on stable Rust (1.89.0).
  6. Optimization profiles: witness-opt-1 (opt-level 1 for prover/stwo) balances compile time with runtime performance for testing. adapter-release (opt-level 3) optimizes the adapter.