jstprove 2.12.0

Zero-knowledge proofs of ML inference on ONNX models

  888888  .d8888b. 88888888888
    "88b d88P  Y88b    888
     888 Y88b.         888
     888  "Y888b.      888  88888b.  888d888 .d88b.  888  888  .d88b.
     888     "Y88b.    888  888 "88b 888P"  d88""88b 888  888 d8P  Y8b
     888       "888    888  888  888 888    888  888 Y88  88P 88888888
     88P Y88b  d88P    888  888 d88P 888    Y88..88P  Y8bd8P  Y8b.
     888  "Y8888P"     888  88888P"  888     "Y88P"    Y88P    "Y8888
   .d88P                    888
 .d88P"                     888
888P"                       888

---

JSTprove

Zero-knowledge proofs of ML inference on ONNX models — powered by Polyhedra Network’s Expander (GKR/sum-check prover) and Expander Compiler Collection (ECC).

Supported ops (current): Add, BatchNormalization, Clip, Constant, Conv, Div, Flatten, Gemm, Max, MaxPool, Min, Mul, ReLU, Reshape, Squeeze, Sub, Unsqueeze. CLI details: see docs/cli.md.

Just want to see it in action? Jump to Quickstart (LeNet demo). Curious about how it works under the hood? Check out the white paper.

---

Table of Contents

Click to expand

• What is JSTprove?
  • High-level architecture
  • Design principles
• Installation
  • 0) Requirements
  • 1) System packages
  • 2) Rust toolchain
  • 3) Clone JSTprove
  • 4) Build the JSTprove binaries
  • 5) Verify the build
• Quickstart (LeNet demo)
• CLI reference
• Troubleshooting
• Contributing
• Disclaimer
• Acknowledgments

What is JSTprove?

JSTprove is a zkML toolkit/CLI that produces zero-knowledge proofs of AI inference. You provide an ONNX model and inputs; JSTprove handles quantization, circuit generation (via ECC), witness creation, proving (via Expander), and verification — with explicit, user-controlled file paths.

High-level architecture

• Python package: Thin PyO3 bindings exposing Circuit, WitnessResult, and BatchResult from Rust.
• Rust workspace: Four crates (jstprove_circuits, jstprove_io, jstprove_onnx, jstprove_remainder) plus jstprove_pyo3 (excluded from workspace). Two CLI binaries: jstprove (Expander backend) and jstprove-remainder (Remainder backend).
• Circuit frontend: ECC Rust API for arithmetic circuits.
• Prover backend: Expander (GKR/sum-check prover/verification).

ONNX model ─► Circuit via ECC (Rust) ─► Witness (Rust) ─► Proof (Rust) ─► Verify (Rust)

Design principles

• User-friendly frontend to Expander: A thin, practical, circuit-based layer that makes Expander/ECC easy to use from a simple CLI — no circuit classes, no path inference, predictable artifacts.
• Explicit & reproducible: You pass exact paths; we emit concrete artifacts (compiled circuit, witness, proof). No hidden discovery or heuristics.
• Quantization that's simple & faithful: We scale tensors, round to integers, run the model, and (where needed) rescale outputs back. Scaling keeps arithmetic cheap while remaining close to the original FP behavior.
• Small, fast circuits when possible: Where safe, we fuse common patterns (e.g., Linear + ReLU, Conv + ReLU) into streamlined circuit fragments to reduce constraints.

---

Installation

Installing from PyPI (Recommended)

Prerequisites

• UV: Fast Python package manager (install UV)

Install JSTprove

uv tool install JSTprove

Verify installation

jstprove --help

Installing from GitHub Release

Download the appropriate wheel for your platform from the latest release:

• Linux: JSTprove-*-manylinux_*.whl
• macOS (Apple Silicon): JSTprove-*-macosx_11_0_arm64.whl

Then install:

uv tool install /path/to/JSTprove-*.whl

---

Development Installation

Click to expand for development setup instructions

0) Requirements

• Python: >=3.9
• UV: Fast Python package manager (install UV)

Note: UV will automatically install and manage the correct Python version for you.

Heads-up: If you just installed uv and the command isn't found, close and reopen your terminal (or re-source your shell init file) so the uv shim is picked up onPATH.

1) System packages

Run commands from the repo root so the runner binary path (e.g., ./target/release/jstprove) resolves.

Ubuntu/Debian

sudo apt-get update && sudo apt-get install -y \
  pkg-config libclang-dev clang

macOS

brew install llvm

---

2) Rust toolchain

Install Rust via rustup (if you don't have it):

# macOS/Linux:
curl https://sh.rustup.rs -sSf | sh
# then restart your shell

Verify your install:

rustup --version
rustc --version
cargo --version

This repo includes a rust-toolchain.toml that pins the required nightly. When you run cargo in this directory, rustup will automatically download/use the correct toolchain. You do not need to run rustup override set nightly.

(Optional) If you want to prefetch nightly ahead of time:

rustup toolchain install nightly

---

3) Clone JSTprove

git clone https://github.com/inference-labs-inc/JSTprove.git
cd JSTprove

The Python package has no pip-installable dependencies. It is built with maturin from the PyO3 crate (maturin develop --release).

---

4) Build the JSTprove binaries

cargo build --release

Cargo will automatically fetch the ECC dependency from https://github.com/inference-labs-inc/ecc. No local clone of Expander or ECC is needed.

---

5) Verify the build

./target/release/jstprove --help
./target/release/jstprove-remainder --help

You can now follow the Quickstart commands (compile -> witness -> prove -> verify).

---

Quickstart (LeNet demo)

Demo paths:

• ONNX model: rust/jstprove_remainder/models/lenet.onnx
• Artifacts: artifacts/lenet/*

1. Compile (using the Expander backend) -- produces a CompiledCircuit msgpack bundle

jstprove msgpack_compile \
  --onnx rust/jstprove_remainder/models/lenet.onnx \
  -c artifacts/lenet/circuit.msgpack

2. Witness -- generate witness from compiled circuit + inputs/outputs

jstprove run_gen_witness \
  -c artifacts/lenet/circuit.msgpack \
  -i artifacts/lenet/input.json \
  -o artifacts/lenet/output.json \
  -w artifacts/lenet/witness.msgpack

3. Prove -- witness -> proof

jstprove run_prove_witness \
  -c artifacts/lenet/circuit.msgpack \
  -w artifacts/lenet/witness.msgpack \
  -p artifacts/lenet/proof.msgpack

4. Verify -- check the proof

jstprove run_gen_verify \
  -c artifacts/lenet/circuit.msgpack \
  -i artifacts/lenet/input.json \
  -o artifacts/lenet/output.json \
  -w artifacts/lenet/witness.msgpack \
  -p artifacts/lenet/proof.msgpack

If it prints Verified, you're done.

---

CLI reference

The CLI is intentionally minimal and doesn't infer paths. See docs/cli.md for subcommands, flags, and examples.

---

Troubleshooting

See docs/troubleshooting.md

---

Contributing

See docs/CONTRIBUTING.md for dev setup, pre-commit hooks, and PR guidelines.

---

Disclaimer

JSTProve is experimental and unaudited. It is provided on an open-source, “as-is” basis, without any warranties or guarantees of fitness for a particular purpose.

Use of JSTProve in production environments is strongly discouraged. The codebase may contain bugs, vulnerabilities, or incomplete features that could lead to unexpected results, failures, or security risks.

By using, modifying, or distributing this software, you acknowledge that:

• It has not undergone a formal security review or audit.
• It may change substantially over time, including breaking changes.
• You assume full responsibility for any outcomes resulting from its use.

JSTProve is made available in the spirit of research, experimentation, and community collaboration. Contributions are welcome, but please proceed with caution and do not rely on this software for systems where correctness, reliability, or security are critical.

---

Acknowledgments

We gratefully acknowledge Polyhedra Network for:

• Expander — the GKR/sumcheck proving system we build on.

• Expander Compiler Collection (ECC) — the circuit frontend used to construct arithmetic circuits for ML layers.