Stwo Zig

A high-performance Zig implementation of the Stwo prover and verifier.

Protocol parity with Rust. Portable CPU execution. Resident GPU proving on Metal.

---

stwo-zig is a parity-first port of StarkWare's Stwo. It brings Stwo's circle-STARK protocol to Zig while making memory, vectorization, and device execution explicit. The result is one proving stack: pure Stwo with native examples, an official-oracle-gated Cairo CPU frontend, and independently owned GPU products.

Important

The pin ledger names a separate authority for each frontend. Native proofs use pinned Rust Stwo; RISC-V decode and retirement use pinned Sail, with Spike and the architectural tests as independent checks. The development-only SM83 frontend uses pinned gb-opcodes and SingleStepTests vectors, with SameBoy as the reference emulator, Blargg as the current flat integration gate, and focused Mooneye ROMs as machine-level timing gates.

Backends

Backend	Execution model	Focus
Zig CPU / SIMD	Portable scalar backend with hardware-native SIMD hot paths	Predictable execution and broad compatibility
Metal	Persistent resident runtime for Apple GPUs	Device-only production proofs with exact runtime identity
CUDA	Functional source retained; products distribution-deferred	No implicit selection; generated payloads stay preserved until current NVIDIA hardware requalification

Frontends

Surface	Current status
Native Stwo	Blake, Poseidon, Plonk, state-machine, wide-Fibonacci, and XOR AIRs
Cairo	Official Stwo-Cairo 1.2.2 CPU/SIMD and authenticated Metal proofs, compiled JSON and Cairo 2.20 executable execution
RISC-V	Release-gated Sail RV32IM zkVM frontend with sharded AIR components, CPU/SIMD and Metal proving, independent verification, and pinned formal evidence
SM83	Development frontend whose runner and direct AIR evaluation cover all 500 executable flat-ISA encodings plus interrupt service; representative CPU/SIMD and Metal proofs cover every family selector. All 500,000 pinned transitions, Blargg 11/11 (25,298,812 instructions), and focused Mooneye 25/25 (535,337 instructions / 535,411 machine steps) pass. The RTC-free MBC3 proof binds execution-bus accesses to mapper endpoints, the 1 MiB ROM, and ordered system/SRAM memory. Its v7 reduced-DMG-B machine transaction additionally composes actions, joypad/timer endpoints and MMIO, scheduler/HALT behavior, interrupt service, PPU timing/MMIO including scroll/window latch endpoints, DMA, IF updates, selected final RAM, and canonical intermediate RAM observations through CPU/SIMD and Metal. The ROM gates remain emulator evidence rather than claims that those complete ROM runs have been proved, and the hardware-fidelity contract names the remaining target-execution gaps.

Quick Start

Core packages require Zig 0.15.x. Repository policy and release tooling use Python 3.10 or newer; optional Rust parity/oracle tooling uses nightly-2025-07-14.

zig build test-stwo-core -Doptimize=ReleaseFast
zig build test-stwo-prover -Doptimize=ReleaseFast
zig build test-native-cpu-product -Doptimize=ReleaseFast
zig build test-native-metal -Doptimize=ReleaseFast  # macOS with Metal

For large RISC-V builds on a laptop, use the serialized build wrapper:

python3 scripts/zig_serial_build.py stwo-zig-riscv-cpu -Doptimize=ReleaseFast

It queues competing wrapper invocations, defaults to one job per build level, and forwards its RAM-based scheduling budget through the focused sub-builds. Use --maxrss BYTES or -jN to override those defaults. The RSS budget governs Zig's declared step estimates; it does not cap a compiler process's actual memory. These build settings do not change prover worker policy or proof identities.

Product support

Product	Host	State
stwo-core / stwo-prover	Zig-supported hosts	Released focused libraries
stwo-native-cpu	Zig-supported hosts	Released CPU/SIMD CLI
stwo-native-metal	macOS with Apple Metal	Parity-gated, source-JIT, device-only CLI
stwo-zig	Zig-supported hosts	Released CPU aggregate; Metal only with -Daggregate-metal=true on macOS
stwo-zig-riscv-cpu	Native host; static x86_64 Linux artifact	Release-gated RV32IM prove, verify, and benchmark CLI
stwo-zig-riscv-metal	macOS with Apple Metal	Parity-gated authenticated-AOT RV32IM CLI with resident-AIR and zero-fallback evidence
stwo-cairo-cpu	Zig-supported hosts with Rust build tooling	Released CPU/SIMD CLI; complete admitted corpus accepted by official Rust
stwo-cairo-metal	macOS with Apple Metal	Parity-gated authenticated-AOT CLI; exact CPU parity, zero-fallback telemetry, and official Rust acceptance across the release corpus
stwo-circuit-recursion-cpu	Zig-supported hosts	Parity-gated recursive tree (fold-tree) and registry generation (circuit-params) CLI; byte-identical to StarkWare's proving@5a7c5ed binaries on the canonical_small test registries
CUDA products	Current NVIDIA qualification host pending	Working source retained, distribution deferred, and no fallback or placeholder execution

The checked four-PIE Cairo coverage record is proof-independent: PIE bytes select decoding and component coverage only, never component semantics or correctness authority. Validate its source reconciliation with python3 scripts/cairo_four_pie_source_coverage.py check-record; add --require-coverage-ready to fail on every recorded source-coverage blocker. Source-semantic packs themselves are generated separately with scripts/generate_cairo_source_semantic_pack.py from an authenticated checkout.

Library consumers can select the smallest public module they need:

Import	Contract
stwo_core	Fields, circle domains, transcript, proof types, and verification
stwo_prover	core, backend contracts, and the backend-generic prover
stwo	Aggregate compatibility SDK

const stwo_zig = b.dependency("stwo_zig", .{ .target = target, .optimize = optimize });
root.addImport("stwo_core", stwo_zig.module("stwo_core"));
root.addImport("stwo_prover", stwo_zig.module("stwo_prover"));

zig build stwo-core and zig build stwo-prover compile the focused library surfaces without installing unrelated executables. Their corresponding test-stwo-* steps include transitive purity and external-consumer gates.

Build deterministic dependency-closed source archives for all publishable Zig packages with:

zig build package-dist

The archives, index.json, and SHA256SUMS are written to zig-out/packages/. They exclude autoresearch, Rust tools, Lean workspaces, vectors, and deferred CUDA payloads while retaining every source and device asset required by the selected package closure. See the package release policy.

The root build is a compatibility dispatcher. Product construction lives under build_support/products/, backend integration under build_support/backends/, benchmarks under build_support/benchmarks/, and policy under build_support/gates/. The default install contains only the CPU aggregate CLI; Metal enters that aggregate only with -Daggregate-metal=true. Machine-readable build contracts are available through product-matrix-identity, identity-stwo-{core,prover,zig}, and build-configure-closure.

Package owner guides

Every first-party package has an owner guide tied to its machine-readable contract. Start with the smallest package that owns the behavior being changed. The source package index includes the circuit-recursion packages, additional integrations, and command-line product guides omitted from this quick list:

Layer	Package guides
Protocol and contracts	stwo_core, stwo_backend_contracts, stwo_prover_api, stwo_prover_engine, stwo_proof_wire
Backends	stwo_cpu_backend, stwo_metal_backend, stwo_cuda_backend
Frontends and services	stwo_riscv_frontend, stwo_cairo_frontend, stwo_sm83_frontend, stwo_native_examples, stwo_metal_session
CPU integrations	stwo_riscv_cpu_integration, stwo_cairo_cpu_integration, stwo_circuit_cpu_integration, stwo_sm83_cpu_integration
Metal integrations	stwo_riscv_metal_integration, stwo_cairo_metal_integration, stwo_sm83_metal_integration
CUDA integrations	stwo_native_cuda_integration, stwo_cairo_cuda_integration

The workspace checker rejects a missing or contract-stale package README. The two-pass documentation review records the technical and editorial acceptance criteria.

Prove

Build the focused CPU product, produce one self-verified proof, then verify its versioned Rust-compatible artifact in a separate invocation:

zig build stwo-native-cpu -Doptimize=ReleaseFast

zig-out/bin/stwo-zig-native-cpu prove \
  --example xor --log-size 12 --protocol secure \
  --proof-artifact-out proof.json

zig-out/bin/stwo-zig-native-cpu verify \
  --artifact proof.json --protocol secure

bench uses the same proving transaction and verifies every warmup and timed sample. stwo-zig-native-metal admits only its exact source-JIT identity and fails rather than entering a CPU commitment path. Run applications on any CLI for its compiled capability registry.

Native workloads default to the conservative standard resource profile (2^25 committed cells, 512 MiB admission-accounted memory). Large evidence is an explicit opt-in: pass --resource-profile large to admit at most 2^27 committed cells and 2 GiB accounted memory. The large profile admits wide Fibonacci --log-n-rows 20 --sequence-len 100, but still rejects log22 x100 and maximum-width shapes. Report schema v7 records the selected profile, checked geometry, accounting factor, and both budgets so benchmark evidence is independently auditable.

Cairo frontend

The focused CPU product accepts an official ProverInput, a compiled Cairo JSON program, or a modern Cairo 2.20 executable. Its adjacent identity-bound Cairo VM adapter executes programs under all_cairo_stwo; Zig owns every proving and verification stage.

zig build stwo-cairo-cpu -Doptimize=ReleaseFast

zig-out/bin/stwo-cairo-cpu run-and-prove \
  --program program.executable.json \
  --program-type executable \
  --arguments arguments.json \
  --proof proof.json \
  --verify

Run zig build test-cairo-cpu-oracle -Doptimize=ReleaseFast to replay the serial corpus and require acceptance from the exact official Rust verify_cairo.

The focused Metal product admits only an authenticated offline core library. On a full-Xcode host the build produces, probes, retains, installs, and consumes that bundle automatically:

zig build stwo-cairo-metal -Doptimize=ReleaseFast
zig build test-cairo-metal-oracle -Doptimize=ReleaseFast

Another macOS host can consume the retained directory without installing Xcode:

zig build stwo-cairo-metal -Doptimize=ReleaseFast \
  -Dmetal-core-aot-bundle=/absolute/path/to/native-metal-core-aot

The bundle path is not trusted. Its canonical manifest digest is embedded in the product identity, and runtime admission remeasures the manifest, shader library, ABI, exports, and compiler artifacts before creating the Metal runtime. The serial Metal oracle gate covers both official inputs, all released proof transports, the builtin/opcode program corpus, and a Cairo 2.20 executable. Focused product tests additionally require deterministic missing-device failure, repeated authenticated sessions, allocation rollback, and resident-buffer-safe teardown.

RISC-V frontend

The release-gated frontend accepts an rv32im-zkvm-v1 ELF, executes it, builds the sharded witness, proves it through the same PCS/FRI core, self-verifies before publication, and emits a bounded schema-v4 artifact. A separate process must verify that artifact against the original ELF and a caller-supplied expected-statement digest. The exact pinned Sail RISC-V model is the semantic authority; Spike is an independent executor and Stark-V is retained only as legacy proof-layout provenance. Published artifacts carry the immutable release_gated status.

zig build stwo-zig -Doptimize=ReleaseFast

zig-out/bin/stwo-zig prove \
  --elf vectors/riscv_elfs/branch_fib.elf \
  --backend cpu --protocol functional \
  --output riscv-proof.json --report-out riscv-report.json

STATEMENT_DIGEST=$(python3 -c \
  'import json; print(json.load(open("riscv-report.json"))["statement_sha256"])')
zig-out/bin/stwo-zig verify \
  --artifact riscv-proof.json \
  --elf vectors/riscv_elfs/branch_fib.elf \
  --protocol functional \
  --expect-statement-digest "$STATEMENT_DIGEST"

functional is the fast development profile. Use secure when collecting release evidence.

zig build test-riscv -Doptimize=ReleaseFast         # runner + trace suites
zig build test-riscv-prover -Doptimize=ReleaseFast  # prove + verify roundtrips
zig build test-riscv-metal -Doptimize=ReleaseFast   # macOS, no CPU fallback
zig build riscv-bench -Doptimize=ReleaseFast        # CPU benchmark CLI
zig build riscv-metal-bench -Doptimize=ReleaseFast  # Metal commitments CLI (macOS)
zig build riscv-csp-bench -Doptimize=ReleaseFast    # full CPU EthProofs CSP matrix
zig build riscv-csp-bench-metal -Doptimize=ReleaseFast # full resident Metal CSP matrix
zig build riscv-trace-dump -Doptimize=ReleaseFast   # trace dumper for equivalence runs
zig build riscv-recursion-csp-producer -Doptimize=ReleaseFast # canonical verified outer-child producer
zig build riscv-recursion-shape-inspector -Doptimize=ReleaseFast # proof-independent CSP profile audit

python3 scripts/riscv_recursion_csp_benchmark.py --help # sealed native/recursive cohort workflow

python3 scripts/riscv_formal_tools.py verify \
  --workspace /tmp/stwo-riscv-formal
python3 scripts/riscv_trace_vectors.py \
  --sail-bin /tmp/stwo-riscv-formal/source/sail-riscv/build/c_emulator/sail_riscv_sim \
  --spike-bin /tmp/stwo-riscv-formal/install/spike/bin/spike

Run the same standard gate used by hosted CI:

python3 scripts/ci.py

For release evidence, use python3 scripts/ci.py --strict. Enable the versioned fast pre-commit and product-scoped pre-push checks once per checkout with:

python3 scripts/install_hooks.py

Explore

Conformance	Pinned oracle revisions, API parity ledger, and the source-conformance baseline
RISC-V Sail contract	Normative executable ISA authority and fail-closed evidence contract
RISC-V verification status	Normative theorem boundary, claim ledger, and remaining FV roadmap
Soundness evidence log	Dated adversarial findings, fixes, and supporting engineering evidence
Independent proof validation	Second-verifier, mutation-corpus, and external PCS/FRI/Fiat–Shamir review scope
Production repository scope	Published Zig boundary and staged Rust, Lean, CUDA, and research extraction policy
Package publishing	Deterministic source archives, clean-room gates, checksums, and release workflow
Benchmark dashboard	Formal CPU/SIMD and Metal results with commit, machine, capture time, and oracle provenance
Benchmark history	Immutable judged runs, deltas, and bundles under human-readable run ids
Local autoresearch tooling	Optional owner-operated performance harness; not installed in production CI
Design archive	Prose architecture and history live in the sibling stwo-zig-og-docs directory
Contributing	Zig, SIMD, Metal, correctness, and engineering standards
Security	Private reporting scope and supported product surfaces

The compatibility target is pinned to upstream commit a8fcf4bd. Claims of equivalence apply to that revision and the committed conformance matrices.

License

Licensed under Apache 2.0, matching upstream Stwo.