The easiest zkVM to understand.
An educational STARK proving framework with an interactive zkVM reference implementation.
Every stage of the proving pipeline—from CPU execution to proof verification—is implemented from scratch, documented, and visualized.
This project is intended to answer one question:
"How does a zkVM actually work internally?"
Unlike production zkVMs, this project intentionally avoids hiding the cryptographic pipeline behind black-box abstractions.
Every algorithm is implemented from scratch and exposed for inspection.
- CPU simulator — step through a toy program instruction by instruction
- Execution trace viewer — the table of register/memory state per cycle
- AIR visualizer — the constraint polynomials that make a trace "valid"
- Polynomial viewer — interpolation, low-degree extension, degree bounds
- FRI step visualizer — the folding protocol that proves low degree
- Proof explorer — Merkle paths, query openings, verifier checks
There are production zkVMs with far more features (RISC Zero, SP1, Cairo VM). This project optimizes for a different thing: opening the hood so the whole mechanism is legible, end to end, in one sitting.
Program
│
▼
CPU Simulator
│
▼
Execution Trace
│
▼
AIR Constraints
│
▼
Trace Polynomial Interpolation
│
▼
Low Degree Extension
│
▼
Composition Polynomial
│
▼
Merkle Commitments
│
▼
FRI
│
▼
Fiat–Shamir
│
▼
STARK Proof
│
▼
Verifier
STARKs need no trusted setup — the whole system is built from two primitives: hash functions and polynomial arithmetic over a finite field. That makes them unusually teachable compared to SNARK constructions that route through pairing-based cryptography.
program
│
▼
CPU simulator ──▶ execution trace ──▶ AIR constraints
│
▼
polynomials ──▶ composition poly ──▶ FRI folding
│
▼
proof object ──▶ verifier
Every stage writes a JSON artifact (trace.json, air.json, lde.json,
fri_rounds.json, proof.json) consumed by a matching visualizer in web/.
This keeps "the math" and "the visualization" cleanly decoupled — you can
read or test any stage in isolation.
Six tabs walk the exact same run — 3^4 mod 97, computed by repeated
multiplication — through every stage of the pipeline, reading real JSON
artifacts exported by viz-export (not mocked data). A seventh tab compiles
the actual prover and verifier to WASM and proves live in the browser.
Step through the toy program instruction by instruction and watch registers update each cycle.
Every cycle of the same run, all at once — the table air::build_rows turns
into columns for interpolation.
The same run through the AIR's eyes: one-hot opcode/register selectors and every named transition constraint, evaluated row by row.
The trace interpolated to coefficients, then low-degree-extended onto a
coset — the same poly::interpolate + poly::lde pipeline used by the
prover itself.
Folding the composition polynomial in half each round until it's small
enough to send outright, with a Merkle root committed before each round's
β challenge is revealed.
The full proof object — trace Merkle root, FRI layer roots, final polynomial, and randomly-sampled query openings, each a Merkle authentication path from an opened trace value up to the committed root.
The real prover and verifier, compiled to WebAssembly, proving a genuine STARK — interpolation, low-degree extension, Merkle commitments, FRI folding, Fiat–Shamir — entirely in-browser, no server round trip.
- Finite field arithmetic
- FFT / IFFT
- Polynomial interpolation
- Low-degree extensions
- AIR generation
- Composition polynomials
- Merkle commitments
- Fiat–Shamir transcript
- FRI prover and verifier
- STARK proof generation
- Minimal instruction set
- CPU simulator
- Execution trace generation
- CPU simulator
- Execution trace viewer
- AIR visualizer
- Polynomial viewer
- FRI visualizer
- Proof explorer
- Live in-browser prover (WASM)
- Explain how STARK-based zkVMs work internally.
- Build a reusable STARK proving framework.
- Make zero-knowledge proofs easier to understand.
- Provide interactive educational tooling.
Building in order:
[✔] Phase 0 — field arithmetic + polynomial ops (crates/field, crates/poly)
[✔] Phase 1 — toy STARK for a trivial statement (no CPU yet), validating the full pipeline: interpolate → LDE → constraints → FRI → verify
[✔] Phase 2 — minimal ISA + CPU simulator (crates/isa)
[✔] Phase 3 — AIR for that ISA (crates/air)
[✔] Phase 4 — Merkle commitments (crates/merkle)
[✔] Phase 5 — FRI protocol (crates/fri)
[✔] Phase 6 — Fiat–Shamir transcript, non-interactive proofs (crates/transcript)
[✔] Phase 7 — prover + verifier assembly (crates/prover, crates/verifier)
[✔] Phase 8 — the six web visualizers (web/)
[✔] Phase 9 — WASM build so visualizers run a live prover in-browser
See docs/ for a write-up per stage as each one lands.
crates/ one crate per pipeline stage (field, poly, merkle, isa, air,
fri, transcript, prover, verifier, viz-export)
bin/zkvm-cli/ command-line entry point: run / prove / verify
examples/ toy programs (fibonacci, squares, collatz)
docs/ one explainer per pipeline stage
web/ the six interactive visualizers (React/TypeScript)
wasm/ compiles the real prover to WASM for live in-browser proving
tests/ integration + conformance tests
.
|-- Cargo.toml
|-- LICENSE
|-- README.md
|-- bin
| `-- zkvm-cli
| `-- src
| `-- main.rs
|-- crates
| |-- air
| | `-- src
| | |-- air_for_isa.rs
| | |-- constraints.rs
| | `-- lib.rs
| |-- field
| | `-- src
| | |-- goldilocks.rs
| | |-- lib.rs
| | `-- field.rs
| |-- fri
| | `-- src
| | |-- fold.rs
| | |-- layers.rs
| | `-- lib.rs
| |-- isa
| | `-- src
| | |-- cpu.rs
| | |-- lib.rs
| | |-- opcodes.rs
| | `-- trace.rs
| |-- merkle
| |-- poly
| | `-- src
| | |-- fft.rs
| | |-- interpolate.rs
| | |-- lde.rs
| | `-- lib.rs
| |-- prover
| | `-- src
| | |-- lib.rs
| | `-- proof.rs
| |-- src
| |-- transcript
| | `-- src
| | `-- lib.rs
| |-- verifier
| | `-- src
| | `-- lib.rs
| `-- viz-export
| `-- src
| |-- air_json.rs
| |-- fri_json.rs
| |-- lib.rs
| |-- poly_json.rs
| |-- proof_json.rs
| `-- trace_json.rs
|-- docs
|-- examples
|-- frontend
| `-- src
| |-- lib.rs
| `-- trace.json.rs
|-- test
| |-- conformance
| `-- integration
|-- wasm
| `-- src
| `-- lib.rs
`-- web
|-- package.json
`-- src
|-- App.tsx
|-- data
| `-- artifacts.ts
`-- viewers
38 directories, 37 files
# core pipeline
cargo run -p zkvm-cli -- run examples/fibonacci/program.zkasm
cargo run -p zkvm-cli -- prove examples/fibonacci/program.zkasm
cargo run -p zkvm-cli -- verify examples/fibonacci/proof.json
# regenerate the static JSON artifacts the visualizers read
cargo run -p viz-export --bin export
# visualizers (tabs 1-6 read the static artifacts above)
cd web && npm install && npm run dev
# Live prover tab: builds the real prover to WASM
./scripts/build-wasm.sh- Field mode. Real STARK fields (e.g. Goldilocks,
2^64 - 2^32 + 1) are too large to display meaningfully. A small prime field (mod 97) with a tiny domain (8–16 elements) is used by default so every number in the polynomial/FRI viewers is human-graspable. A "real mode" toggle switches to the production-size field to show the same code scales. - Minimal Instruction Set, not RISC-V. A handful of opcodes (add, mul, jump, load, store, halt) — enough to be interesting, not so much that AIR constraints for memory consistency and byte range-checks drown out the core ideas.
- JSON artifacts as the seam. The Rust core and the web frontend never share code directly; they share a JSON schema. This makes every stage independently testable and keeps the "explain it" layer from leaking into the "prove it" layer.
This project stands on the shoulders of excellent existing work:
- STARK 101 (StarkWare) — the tutorial this project's Phase 1 "toy STARK" is modeled after
- Winterfell — a well-documented Rust STARK library, useful as a reference for AIR/FRI structuring
- RISC Zero, SP1, Cairo VM — production zkVMs worth studying once the toy pipeline works end to end
This project is licensed under the MIT License. See the LICENSE file for details.