A contract you can check.

zkVM host service

What's real vs. what's pitched, for "zkvm.host"

The "zkvm.host" pitch describes a company: a multi-VM router (SP1/RISC Zero/Jolt/ ZKWASM), a serverless pay-per-proof API, CI/CD integration, an edge/WASM proving SDK, AI-agent-execution verification, and a four-tier business model. This repo cannot honestly claim to have built that. What it *can* claim, and does, is the one piece that's directly buildable on top of the real zkVM already in this repo: "push a program, get a proof" as an actual HTTP call.

What exists: ZZTOKEN0ZZ

• POST /v1/proofs — body {"program": "<.zkasm text>"}, returns the STARK proof

(base64) and public inputs. This *is* the core mechanic of "no circuits, no prover clusters, no infra" — the caller doesn't link against zkvm-stark or run a prover locally, they make one HTTP call.

• POST /v1/verify — checks a proof against a program. The server re-executes the

program itself (cheap) to know what public inputs to check against; it never needs the caller's execution trace.

• GET /healthz.
• ZZTOKEN0ZZ's deploy subcommand: reads a .zkasm file,

POSTs it to a running server, saves the returned proof locally. Verification stays local and CLI-driven — deliberately: you should never have to trust a proving service's own claim that a proof is valid, only the (cheap, fast) verification you ran yourself. Tested end to end: the CLI's deploy → verify round-trip is a real HTTP request against a real running server, not a mock.

• A ProverBackend trait (src/backend.rs) and ProverRouter (src/router.rs):

GET /v1/backends lists what's registered, POST /v1/backends/{name}/proofs and /verify dispatch to a named backend. Two are registered: stark (the real prover above, reachable this way too) and mock-echo — a routing stub that is explicit about doing nothing cryptographic (its verify always returns an error, never valid: true; see backends/mock_echo.rs). This makes "multi-VM router" an architecturally real, tested claim — adding SP1 or RISC Zero later is one new file plus one router.register() call, not an HTTP-layer rewrite — while being explicit that no second *real* backend exists yet. Deliberately not named sp1 / risc-zero: naming a stub after a project it doesn't implement would misrepresent it, the same mistake contracts/'s original verifyProof() { return true; } draft made in the other direction.

• ZZTOKEN0ZZ closes the loop this doc

used to list as missing: it deploys contracts/, gets a *real* proof from a *real* running server, verifies it locally, attests it on-chain, and confirms the prover is actually paid — see the "On-chain settlement" section below.

• ZZTOKEN0ZZ: on every PR

touching .zkasm examples, the server/CLI crates, or contracts/, it builds the workspace, runs every Rust and Solidity test, then boots the real server and runs zkvm deploy + zkvm verify against every example program — the PR fails if any of them don't actually verify. "Proof as a CI check," for real, not just described.

• ZZTOKEN0ZZ: prove and verify exposed

as real MCP tools (via the ZZTOKEN0ZZ crate), so any MCP client (Claude, Cursor, or anything else speaking the protocol) can call this server directly. Verified with an actual MCP initialize → tools/list → tools/call handshake over HTTP, not just written and assumed to work — see the "MCP" section below for why it runs on its own port instead of nested onto /v1/*.

That's genuinely the demand-side developer-experience mechanic the pitch describes, architecturally extended to more than one backend, with the on-chain and CI pieces that used to be listed below as gaps now closed.

MCP: why it's a separate port, not nest_service

rmcp's StreamableHttpService implements tower::Service, but its Response body type doesn't line up with axum::Router::nest_service without an adapter layer — and rmcp's own examples serve it via a raw hyper accept loop rather than mounting it on an existing axum::Router, which is a strong signal that isn't a supported plug-and-play path. mcp::serve follows the same verified pattern the upstream examples use, on its own listener (port 4478 by default), rather than asserting an untested "just nest it" integration.

A second real backend: investigated, not built

SP1 (sp1-sdk) was checked for real, not assumed:

• The crate and its API are real (confirmed against the succinctlabs/sp1

source at the exact released tag) — ProverClient::from_env().await, .setup(elf).await and .prove(&pk, stdin).groth16().await all exist. Two API details from an earlier draft were wrong, though: setup() returns a single SP1ProvingKey, not a (pk, vk) tuple, and prove() takes stdin by value, not by reference.

• A bare "hello world" depending on sp1-sdk resolves 518 crates — more

than 3x this entire workspace's current dependency count — and includes a Go-based FFI dependency (sp1-recursion-gnark-ffi) for its Groth16/PLONK wrapping step, on top of Rust.

• cargo check on that bare project ran for **~4 minutes of wall time (861s of

CPU time)** before failing on a missing system dependency (protoc), having not yet reached the RISC-V guest toolchain, network-fetched proving parameters, or an actual proof.

• More fundamentally: SP1 proves compiled RISC-V ELF binaries from Rust guest

programs via its own build toolchain. It has no relationship to this repo's .zkasm accumulator ISA — integrating it as "just another ProverBackend" would mean either compiling .zkasm programs down to a RISC-V guest binary (a real compiler that doesn't exist) or changing the trait to accept an entirely different input type for this one backend, breaking the shared Program abstraction the other two backends rely on.

None of this makes SP1 a bad choice eventually — it's the opposite of the mock-echo problem, a backend that's *too* real to fake a quick integration of. But "one file + one register() call" undersells it substantially, and attempting it blind risked repeating the exact category of error (guessed APIs, untested toolchains) this whole exercise has been about catching. Not pursued further this session.

What's explicitly not here

• A second real proving backend. mock-echo proves the *router* works; it is

not, and is not trying to be, SP1/RISC Zero/Jolt/ZKWASM. See above for what investigating SP1 specifically turned up.

• Trustless on-chain verification. scripts/onchain_demo.sh pays a prover for a

real proof, but only after an AttestedVerifier attestation — a trusted bridge, not a cryptographic check of the STARK proof itself. See ZZTOKEN1ZZ for exactly what closing that gap for real requires.

• Multi-tenant serverless infrastructure, billing, usage tiers. The server here

is a single process with no auth, no rate limiting, no persistence, no queuing — it's meant to be run locally or in a trusted network, not exposed as a public paid API. "Free / $49/mo / usage-based / Enterprise" implies a whole billing and account system that doesn't exist.

• Edge/WASM proving SDK. Nothing runs the prover in-browser or on an edge

runtime; zkvm-stark's dependencies (and STARK proving in general) are not scoped for that today.

• AI agent verification. No integration with any agent framework, and no AIR

designed around "did this agent follow a policy" — that would need its own instruction-set/constraint design, not a wrapper around the existing accumulator machine.

If this were actually going further

In rough order of "most directly extends what's real, least new infrastructure":

1. Add auth (even something as simple as a static API key) and per-key rate

limiting to the server — the minimum needed before it could be exposed beyond a trusted network.

1. Persist submitted proofs/tasks (currently everything is synchronous, in-memory,

request-scoped) so a GET /v1/proofs/:id style status check is meaningful for proofs that take longer than an HTTP request timeout.

1. Replace scripts/onchain_demo.sh's manual cast calls with a zkvm-cli attest

(or similar) subcommand once the attestation flow needs to run somewhere other than a developer's terminal — e.g. as the CI job's own follow-up step.

1. Only after those: a second *real* backend, to prove the abstraction actually

generalizes rather than assuming it does from one mock.

zkVM scope and roadmap

Roadmap

This repo started from a five-phase, 36-month strategy document envisioning a "universal zero-knowledge layer" (zkVM.host): a security-audited proving foundation, a sub-second proving stack, a full developer platform, a token-based proving economy, and eventually cross-chain network effects.

That document is a business strategy, not an engineering spec. This repo is the first real engineering artifact underneath it: a genuine, working, tested zkVM MVP — an interpreter, a from-scratch AIR (algebraic constraint system), a real STARK prover and verifier (via Winterfell), and soundness tests that actually try to break it. Everything below is honest about what's real today versus what the strategy doc aspires to.

Decided direction: this is a zkVM, not a multi-VM router. The SP1 investigation (see below) surfaced a real fork: keep extending this repo's own .zkasm ISA and own that stack end to end (this option), or treat .zkasm as a demo fixture and make the ProverBackend router the actual product, routing to whatever proving backend a user brings. The router abstraction (crates/zkvm-host-server/src/router.rs) stays — future backends aren't ruled out — but they'd need to speak this ISA's semantics or a from-scratch equivalent maintained in this repo, not "plug in SP1 as-is." The practical consequence: trustless on-chain verification means building recursive STARK compression *for this specific AIR* eventually — a genuine research undertaking (see ZZTOKEN4ZZ) — not something inherited for free from an external prover's existing recursion pipeline.

What exists today (Phase 0 → Phase 1, first slice)

• ZZTOKEN0ZZ: the VM itself. An accumulator machine

(ADD/SUB/MUL) with real conditional control flow (JZ/JNZ, forward-only — see below), a small fixed register file (LOAD/STORE, 4 registers — see below), a real interpreter, and a tiny assembly format (.zkasm, with labels) for writing programs.

• ZZTOKEN0ZZ: arithmetization. Defines the AIR

(transition constraints + boundary assertions) that binds a STARK proof to one specific program *and* its actual control-flow outcome — not just "some valid trace" — and a prover/verifier built on Winterfell.

• ZZTOKEN0ZZ: a zkvm binary — run, prove, verify,

and demo (which also runs two tamper attempts to show they get rejected).

• Tests at both layers, including negative tests: a proof must be rejected if the

claimed result or the claimed program is tampered with after the fact. This is the actual soundness property a zkVM needs — not a slogan, a thing the test suite checks.

• ZZTOKEN0ZZ: an on-chain task/reward orchestrator (Foundry/Solidity,

tested with forge test) that delegates every accept/reject decision to a pluggable IProofVerifier. The two verifiers that exist are deliberately honest about not being a real cryptographic verifier yet — see ZZTOKEN2ZZ for exactly what one would require and why that's a separate, large undertaking (not shipped as a "close enough" stub).

• ZZTOKEN0ZZ: an HTTP "push a program, get

a proof" service wrapping the one real proving backend in this repo, plus a zkvm deploy CLI command that drives it end to end (tested with a real HTTP round-trip, not mocked). It also exposes a ProverBackend-trait /v1/backends* surface so "multi-VM router" is an architecturally real, tested claim rather than a promise — today with one real backend (stark) and one honestly-labeled routing stub (mock-echo, which refuses to verify anything rather than faking success). See ZZTOKEN5ZZ for how this relates to the much larger "zkvm.host" multi-VM/serverless/CI-CD/edge-proving pitch it grew out of — most of that pitch has no code here on purpose.

• ZZTOKEN0ZZ: the previously-missing

wiring between the server and contracts/ — deploys both contracts to a local chain, gets a real proof from the real server, verifies it locally, attests it on-chain, and confirms the prover is actually paid. Run and passing.

• ZZTOKEN0ZZ: "proof as a CI

check" for real — every PR touching the VM, server, CLI, or contracts builds, runs every test, then deploys and locally verifies every example program against a live server, failing the PR if any proof doesn't check out.

• MCP tools (ZZTOKEN0ZZ): prove/verify exposed to any MCP client

(Claude Desktop, Cursor, ...), verified with a real initialize → tools/call transcript against a running server, not just written.

• ZZTOKEN0ZZ: states plainly what's trustless (the

proof itself) versus what isn't (the on-chain payment, which trusts one attester key) — a documented design decision rather than a silent gap.

• Conditional branching (JZ/JNZ). Proof of a program whose result genuinely

depends on runtime data, not just straight-line arithmetic — examples/branching.zkasm, tested both branches taken and not, plus a negative test that tampering with the claimed control-flow outcome (which row actually executed) is rejected. Sound without a lookup/permutation argument specifically because this system has no private witness: the verifier already re-executes the program to know the correct per-row active flag, the same way it already knew the correct opcode selectors — see the doc comment at the top of zkvm-stark/src/lib.rs for the full argument. Jumps are forward-only (no loops yet — see "Suggested next slice" below).

• A small fixed register file (LOAD/STORE, 4 registers). examples/counter.zkasm

stores a value, does unrelated arithmetic, then loads it back — the first program this VM can write that needs to hold more than one live value at once. The same "no secret witness" trick that made branching sound without a gadget extends here too: which register a LOAD/STORE addresses is a one-hot column asserted per row (like the opcode selectors), not derived via an algebraic mux — see the updated doc comment in zkvm-stark/src/lib.rs. Tested including a negative test that claiming a different register was addressed is rejected.

Why this scope, specifically

Building a real STARK-based VM with unconstrained branching, memory, and a full RISC-V-compatible instruction set is a multi-year effort for a team, not a single session. Rather than fake that scope with stubs, this MVP picks the smallest slice that still has the essential hard part: an AIR whose transition constraints correctly gate multiple instruction types via opcode selectors, with per-row assertions that bind the proof to an exact program. That's the same core technique (generalized) that real STARK-based VMs — RISC Zero, SP1, Cairo, Miden — use to prove arbitrary programs. Once this pattern is validated, extending it is additive work, not a redesign.

What's explicitly NOT here yet

Mapped against the original roadmap's phases, so it's clear what's aspirational:

• Loops. JZ/JNZ are forward-only; nothing revisits a static instruction twice.

Real loops need a dynamically-sized execution trace (padded/truncated based on how many iterations actually ran, not the fixed program length) — a bigger change than adding control flow to a fixed-length trace was.

• Memory (addressable RAM, distinct from the fixed register file). The register

file is 4 fixed, statically-named slots — addressing is entirely static (which register is baked into the instruction). Real memory means a *dynamic* address (computed at runtime, e.g. LD r0, [r1] where r1 holds the address), which is a materially different problem: the verifier can still re-execute and know the correct value at every access (see docs/ROADMAP.md's note on this below), but proving *which* address was accessed, when that address is itself a trace value rather than a constant baked into the instruction, is closer to the branching problem (a dynamic pc) than to the register file (static slots) — worth designing deliberately rather than assuming either pattern extends for free.

• RISC-V compatibility. The instruction set here is custom and minimal, not RV32I.

Real ELF-binary execution is future work.

• **Formal verification, fuzzing, external audits, a public "Soundness Shield"

dashboard.** None of this exists. The only soundness evidence right now is the unit test suite in zkvm-stark.

• Performance work (GPU/ASIC proving, recursion, aggregation, sub-second proving

targets). Not started; Blake3_256 + a 128-bit field with default parameters is a correctness-first, not performance-first, configuration.

• Trustless on-chain proof verification. contracts/'s AttestedVerifier is a

trusted bridge (an off-chain party attests a proof checked out), not a cryptographic verifier. Making that trustless means porting FRI/Merkle/field-arithmetic verification into Solidity (or wrapping the STARK in a SNARK) — see ZZTOKEN0ZZ.

• Everything economic/network-effect-related — the $ZKVM token, a proving

marketplace, decentralized prover network, cross-chain bridges, DAO/alliance formation. None of that has a code artifact, and several of those items (running a token launch, executing trades) are outside what an engineering session like this one should be doing regardless of implementation status.

• A second real proving backend — SP1, specifically investigated and not pursued.

Confirmed real crate, real API, but: 518 resolved dependencies for a bare "hello world" (>3x this whole workspace), a Go-based FFI dependency for Groth16 wrapping, and a cargo check that took ~4 minutes before failing on a missing system dependency without yet reaching the RISC-V toolchain or an actual proof. More fundamentally, SP1 proves compiled RISC-V ELF binaries — unrelated to this repo's .zkasm ISA — so integrating it isn't "one file," it's a compiler project first. See ZZTOKEN2ZZ for the full writeup.

Suggested next slice

In rough order of "smallest change with the biggest validation value":

1. Loops: a dynamically-sized trace (bounded by a max-cycle count, padded/truncated

based on actual execution length) so JZ/JNZ can jump backward too. This is a materially bigger change than forward-only branching — the "verifier re-executes and asserts everything" trick still works (the verifier can still just run the loop itself), but trace-length selection and the resulting proof-size variability need real design.

1. Addressable memory (dynamic addresses, distinct from the static register file --

see above). Worth checking first whether the "verifier re-executes and asserts everything" trick extends here too before assuming a full permutation/lookup argument is required — the trick has held for everything so far specifically *because* there's no secret witness anywhere in this system; that's also the open question docs/RECURSION.md flags about whether hiding data is ever added later.

1. Only after 1–2 are solid: consider RV32I compatibility.

zkVM threat model

Threat model: what you're trusting, and why

This is the one-page version. For the underlying cryptographic detail, see ZZTOKEN0ZZ; for what's built versus pitched overall, see ZZTOKEN1ZZ.

The proof itself: trustless

A zkvm-stark proof (produced by prove_program, checked by verify_program) is a real STARK. Verifying it — locally via zkvm verify, over HTTP via /v1/verify, or via the verify MCP tool — requires no trust in whoever generated it. This is standard, load-bearing cryptography: zkvm-stark's test suite includes negative tests (rejects_tampered_result, rejects_tampered_program) that confirm a proof manufactured for one claim is rejected against a different one.

This is the only trustless part of the system end to end. Everything below is about what happens once that proof needs to affect something outside a local process — specifically, an on-chain payment.

The on-chain path: an attested bridge, not a cryptographic verifier

contracts/'s ProofOrchestrator pays a prover once a proof is "accepted." What "accepted" means depends entirely on which IProofVerifier it's configured with:

• UnimplementedStarkVerifier — accepts nothing. Every submitProof call

reverts. No trust required because no payment is possible.

• AttestedVerifier (the one scripts/onchain_demo.sh actually uses) — accepts

a proof once a designated attester address calls attest(publicInputsHash, proofHash). You are trusting that this one key only attests to proofs it (or whoever holds it) actually ran zkvm verify against and got Ok(()).

Concretely, the trust assumption is: *the attester key is not compromised, and whoever controls it always verifies locally before attesting, never on faith.* If that assumption fails — key theft, or a careless/malicious attester — a false attestation pays out a real reward for a proof that either doesn't exist or doesn't verify. The contract has no way to detect this; it only checks that the attester's signature is present, not that the underlying math is sound.

This is the same trust model a centralized sequencer has before its fraud/validity proofs go live (e.g. early-stage optimistic rollups): a known, single point of trust, acceptable because it's explicit and small, not because it's absent.

Key management, honestly

There is currently no key management story beyond "a private key exists and someone runs cast send ... --private-key." Concretely, for anything beyond a local demo, at minimum:

• The attester key should never be the same key used for anything else (deploying

contracts, holding funds) — a compromise of one shouldn't compromise the other.

• It should live in whatever secrets store the deployment environment already has

(not a .env file, not shell history — scripts/onchain_demo.sh's hardcoded Anvil test keys are demo-only and must never be reused anywhere real funds could reach them).

• Rotation means deploying a new AttestedVerifier with the new attester address —

there's no in-place key-rotation function on the current contract. That's a real gap if this ever needs to run continuously.

None of this is implemented. It's written here so the gap is a documented decision, not a silent omission.

When does this stop being true?

Only when a real cryptographic verifier replaces AttestedVerifier — porting FRI/Merkle/field-arithmetic verification into Solidity, or wrapping the STARK in a SNARK cheap enough to verify on-chain. Both are described, with why they're substantial independent undertakings, in ZZTOKEN1ZZ. Until one of those exists, "the proof is trustless, the payment is not" is the accurate description of this system, and should be stated in exactly those terms to anyone relying on it.

dh/v1 conformance

dh/v1 conformance

The conformance suite checks that an implementation produces and accepts exactly the bytes the protocol specifies. It has three parts:

Running

go build -o bin/ ./cmd/dh-conformance
./bin/dh-conformance run -self                                          # Go reference, in process
./bin/dh-conformance run -adapter "./bin/dh-conformance adapter"         # Go reference over stdio
./bin/dh-conformance run -adapter "python3 conformance/python/adapter.py" # independent implementation
DH_PY_PURE_ED25519=1 ./bin/dh-conformance run -adapter "python3 conformance/python/adapter.py"
./bin/dh-conformance check      # vectors still match the reference (drift guard)

Useful flags for run: -ops canon,verify selects a subset, -report out.json writes a machine-readable report, and -allow-skip lets an adapter that does not implement some ops still pass on the rest. go test ./pkg/conformance runs the drift guard, the reference and the Python implementation.

Adapter protocol

An adapter is any executable. It reads one JSON request per line on stdin and writes one JSON response per line on stdout, in order:

→ {"id":"verify/wrong-kind","op":"verify","input":{…}}
← {"id":"verify/wrong-kind","ok":true,"output":{"valid":false,"error":"kind-mismatch"}}
← {"id":"canon/reject-float","ok":false,"error":"reject"}
← {"id":"x","ok":false,"error":"unsupported"}        (op not implemented → skipped)

The runner compares canonical({"output": output}) or canonical({"error": code}) with the vector's expect, so key order and whitespace in responses do not matter. Binary data is standard base64 with padding in fields ending _b64. Wire keys and signatures are unpadded base64url, as in the protocol.

Vectors for chunk store data_gen: {alg, seed, length} instead of the bytes, and the runner expands it to data_b64 before sending:

• xorshift64*: x ^= x>>12; x ^= x<<25; x ^= x>>27, then emit

x·0x2545F4914F6CDD1D mod 2^64 as 8 little-endian bytes, truncated to length;

• zero: length zero bytes;
• pattern: byte *i* is i mod 251.

Test identities use seed *n* = BLAKE3("decentralized.host/conformance-seed/v1" || n).

What the vectors cover

• canon (42): key order by UTF-8 bytes; every escape rule; raw U+2028

and <>&; surrogate pairs; -0; the ±(2^53−1) boundary; and rejection of floats, exponents, out-of-range and huge integers, duplicate keys (also via escapes and nesting), trailing data, NaN/Infinity, leading zeros, lone and reversed surrogates, invalid and overlong UTF-8, a BOM, raw controls and an empty document.

• identity (9): seeds, arbitrary keys, and malformed, padded or

standard-alphabet keys.

• digest / domain-hash (9), including rejection of non-canonical values.
• sign (5), including HTML characters, Unicode and a rotated signer.
• verify (14):
• valid envelopes, with self-certifying keys, allowed sets and rotated keys;
• one of each error code;
• transport re-encoding (reordered keys, \u003c), which must still verify;
• duplicate and float payloads (not-canonical);
• truncated or padded signatures, and key substitution.
• audit (14): hashes, intact chains and suffixes, and every break reason,

including all four checkpoint failures.

• capability (29): minting, and each caveat at its boundary

(now == expires is expired). Also:

• narrowing across blocks;
• wildcard, prefix and path.Match resource rules;
• an untrusted root, a wrong delegate and a sealed chain;
• tampered encodings and blocks, and the 16-block limit.
• chunk (8): empty input, 1 byte, exactly and just over the minimum,

random data, all-zero data (cut at the maximum) and a repeating pattern.

• merkle (6): the empty set, odd promotion, and de-duplication with

sorting.

Changing the protocol

Vectors are generated from the Go reference implementation, and TestVectorsMatchReference fails if the committed file is stale. A change that alters vector bytes is a protocol change: regenerate with dh-conformance gen, review the diff, update dh-v1.md, update the Python implementation to match, and bump SuiteVersion. Anything that breaks an existing vector's meaning needs dh/v2.