zkvm - Zero-Knowledge Virtual Machine

BigInt-native ZK VM with hash-chain proving. Heavy prover on server; lightweight verifier runs anywhere. Permanent audit trail on Arweave base layer — no staking, no TEE, no trusted hardware.

Architecture

┌── Prover (Server Only) ──┐        ┌── Verifier (WASM, Anywhere) ──┐
│                          │        │                                │
│  ZkVmProver              │        │  Browser    CLI       AO       │
│  (native Rust)           │        │  ┌────┐    ┌────┐    ┌──────┐  │
│                          │        │  │ npm│    │zkvm│    │verify│  │
│  create_proof ───────────┼───────▶│  │ pkg│    │CLI │    │.wasm │  │
│  (Halo2, heavy)    proof │        │  └────┘    └────┘    └──────┘  │
│                          │        │                                │
│  Runs on: server only    │        │  Runs on: any platform          │
│  NOT in WASM, NOT on AO  │        │  Lightweight verify_proof      │
└──────────┬───────────────┘        └────────────────────────────────┘
           │
           │  hash chain
           ▼
┌── Arweave Base Layer (Permanent Audit Log) ──┐
│                                               │
│  Immutable, permanent storage                 │
│  Anyone can replay prover, verify chain       │
│  Independent of AO — works without it         │
└───────────────────────────────────────────────┘

What Makes zkvm Different

Different ZK VMs optimise for different things. zkvm trades per-instruction constraints for broader computation and a simpler verifier.

| | Per-opcode ZK VMs | zkvm | |---|---|---| | Verification | Per-instruction (each opcode constrained) | Per-program (hash chain of inputs → outputs) | | Arithmetic | Fixed-width, constrained in circuit | Arbitrary-precision BigInt, unconstrained | | Circuit size | Grows with program complexity | Constant (hash only) | | Verifier | Heavy (checks all constraints) | Lightweight WASM (checks hash chain) | | Server trust | None (proof covers each step) | Mitigated by deterministic replay + Arweave audit trail | | Audit trail | The chain itself | Arweave base layer — permanent, independent | | Best for | Trustless on-chain execution, per-step guarantees | Broad computation, audit trails, privacy, settlement |

Prover vs Verifier

| | Prover | Verifier | |---|---|---| | Function | generate_proof (create_proof) | verify_proof | | Weight | Heavy (Halo2 polynomial commitments) | Lightweight (crypto primitives) | | Runtime | Native Rust only | WASM (browser, CLI, AO) | | Runs on | Server only | Anywhere | | On AO? | Never | Yes (optional) |

The prover generates; the verifier checks. Proof generation requires a server. Verification runs in a browser tab, a CLI tool, or an AO process.

Three Flows

Standard Flow

Client → Server → Client

Client executes program (BigInt-native VM), sends witness to server. Server generates proof via create_proof (heavy, native Rust). Server posts hash chain to Arweave base layer. Client verifies proof with lightweight WASM verifier.

AO-Verified Flow (Optional)

Client → Server → AO Network
                  (verifier WASM only)
         │
         ▼
  Arweave Base Layer
  (hash chain audit log)

Server generates proof off-chain, posts hash chain to Arweave base layer. Optionally sends proof to AO process running the verifier WASM. Anyone can replay the deterministic prover against the hash chain — independent of AO.

Privacy-Preserving Flow

Code + data encrypted → only hashes on Arweave base layer

Client encrypts program and data. Only blake3 commitment goes on-chain. Server decrypts via secure channel, executes, records result hash. ZK proof verifies correctness without revealing code or inputs.

Features

• BigInt-native VM — arbitrary-precision arithmetic, no overflow possible
• Hash-chain proving — no per-opcode constraints, constant circuit size
• Heavy prover, lightweight verifier — verifier WASM runs in browser, CLI, or AO
• Arweave base layer audit log — permanent, immutable, one-time cost
• AO integration (optional) — decentralized verification, verifier WASM only
• Privacy-preserving execution — encrypted code and inputs, only hashes on-chain
• Deterministic prover — anyone can replay and verify the hash chain

Use Cases

| Problem | Solution | |---------|----------| | Regulatory audits — prove computation was correct without revealing proprietary code | Client-side execution + ZK proof, only proof and hashes go public | | Cross-party settlement — two banks verify trade logic without exposing internal systems | Encrypted execution, verifier checks proof, Arweave base layer provides permanent audit | | ML model IP protection — prove inference ran correctly without exposing model weights | Model stays encrypted, client executes and proves correct execution to third party | | Supply chain audit — tamper-proof record that specific code processed specific input | Hash chain on Arweave base layer creates immutable audit trail, routing logic stays private | | Clinical trial privacy — verify analysis was correct without exposing patient data | Patient data never leaves client, proof satisfies regulators | | TEE alternative — software-based attestation when hardware TEEs aren't available | ZK proofs provide cryptographic soundness without hardware trust assumptions |

Quick Links

| For | See | |-----|-----| | What makes zkvm different | docs/UNIQUE.md | | npm package usage | pkg/README.md or npm install zkvm | | Architecture deep-dive | docs/ARCHITECTURE.md | | AO integration (optional) | docs/ao.md | | CLI usage | docs/cli.md | | Plain-English intro | docs/INTRODUCTION.md |

Installation

npm:

npm install zkvm

CLI from source:

git clone https://codeberg.org/PatrickM123/zkvm
cd zkvm/cli
cargo build --release

Documentation

• UNIQUE.md — What differentiates zkvm from other ZK VMs
• ARCHITECTURE.md — Technical deep-dive
• INTRODUCTION.md — Plain-English overview
• ao.md — Optional decentralized verification on AO
• cli.md — CLI usage
• api.md — JS/TypeScript API reference
• HOWTO.md — Step-by-step tutorial

DarkFi

zkvm is extracted from DarkFi — an anonymous, uncensored, sovereign Layer 1 blockchain with zero-knowledge contracts.

• DarkFi Website
• DarkFi Book
• Source Codeberg

License

AGPL-3.0-only — See LICENSE for details.