diff --git a/README.md b/README.md index 87819e487..2fc0d5c36 100644 --- a/README.md +++ b/README.md @@ -1,207 +1,150 @@ # ProveKit -A modular zero-knowledge proof toolkit optimized for mobile devices. +
-## Requirements +ProveKit -This project makes use of Noir's `nargo` to compile circuits and generate test artifacts. Make sure to walk through the [Quick Start](https://noir-lang.org/docs/getting_started/quick_start#noir) section to install the noir toolchain. Note that we require a specific version of the toolchain, so make sure to override the version with the following command. +[![CI](https://img.shields.io/badge/build-passing-2ea44f?style=flat-square&logo=github)](https://github.com/worldfnd/provekit/actions) +[![Rust](https://img.shields.io/badge/rust-nightly-e32828?style=flat-square&logo=rust)](https://rustup.rs/) +[![License](https://img.shields.io/badge/license-MIT%20%2F%20Apache_2.0-blue?style=flat-square)](./License.md) -```sh -noirup --version v1.0.0-beta.11 -``` +[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Examples](./noir-examples/) · [Repository Map](#repository-map) · [Contributing](./CONTRIBUTING.md) -## Demo instructions +
-> _NOTE:_ The example below is being run for single example `poseidon-rounds`. You can use different example to run same commands. +ProveKit is a zero-knowledge proof system toolkit that compiles [Noir](https://noir-lang.org/) programs to R1CS constraints and generates and verifies [WHIR](https://github.com/WizardOfMenlo/whir) proofs using a Spartan-based protocol. It includes custom SIMD-accelerated field arithmetic, memory-efficient algorithms for resource-constrained environments, C-compatible FFI, and recursive verification support for on-chain Groth16 applications. -Compile the Noir circuit and generate prover/verifier files: +## Why ProveKit -```sh -cd noir-examples/poseidon-rounds -cargo run --release --bin provekit-cli prepare -``` +- **Noir frontend:** write circuits in Noir and use ProveKit to compile, prepare keys, prove, and verify with one CLI. +- **Post-quantum secure proofs:** produce WHIR proofs designed around post-quantum security assumptions. +- **Integration-ready surface:** use ProveKit from Rust or from C-compatible FFI hosts such as Swift, Kotlin, Python, and JavaScript. +- **Recursive verifier for on-chain Groth16:** export prover-key/proof data for the gnark recursive verifier when an on-chain Groth16 wrapper is required. -This compiles the package in the current directory and writes `.pkp` and `.pkv` next to it. You can also pass an explicit project directory and override the output paths: +## Quick Start -```sh -cargo run --release --bin provekit-cli prepare ./noir-examples/poseidon-rounds --pkp ./prover.pkp --pkv ./verifier.pkv -``` +### Prerequisites -Generate the Noir Proof using the input Toml: +Install Rust with `rustup`. This repository includes `rust-toolchain.toml`, so Cargo picks the pinned nightly automatically. + +Install the Noir toolchain version used by v1 examples: ```sh -cargo run --release --bin provekit-cli prove +noirup --version v1.0.0-beta.11 ``` -This reads `.pkp` and `./Prover.toml` from the current directory and writes `./proof.np`. Override any of these with `-p`/`--prover`, `-i`/`--input`, or `-o`/`--out`. +### Run a proof -Verify the Noir Proof: +The smallest v1 end-to-end path is the [`noir-examples/basic-4`](./noir-examples/basic-4/) package: ```sh +cd noir-examples/basic-4 +cargo run --release --bin provekit-cli prepare +cargo run --release --bin provekit-cli prove cargo run --release --bin provekit-cli verify ``` -This reads `.pkv` and `./proof.np` from the current directory. Override with `-v`/`--verifier` or `--proof`. +`prepare` compiles the Noir package in the current directory and writes `.pkp` and `.pkv`. `prove` reads `.pkp` plus `./Prover.toml` and writes `./proof.np`. `verify` reads `.pkv` and `./proof.np`. -Generate inputs for Gnark circuit: +### Command reference -```sh -cargo run --release --bin provekit-cli generate-gnark-inputs ./prover.pkp ./proof.np -``` +| Command | Purpose | Key options | +| :--- | :--- | :--- | +| `prepare [program-dir]` | Compile a Noir package and write prover/verifier keys | `--package`, `--workspace`, `--target-dir`, `--pkp`/`-p`, `--pkv`/`-v`, `--force` | +| `prove` | Produce `proof.np` from a prover key and inputs | `--prover`/`-p`, `--input`/`-i`, `--out`/`-o` | +| `verify` | Verify a proof against a verifier key | `--verifier`/`-v`, `--proof` | +| `generate-gnark-inputs` | Export recursive-verifier inputs | positional prover key, positional proof, `--params`, `--r1cs` | +| `circuit-stats` | Inspect ACIR and R1CS structure | positional compiled circuit JSON | +| `analyze-pkp` | Inspect prover-key size breakdown | positional `.pkp` file | +| `show-inputs` | Display public inputs from a proof | positional `.pkv` file, positional proof, `--hex` | -Analyze circuit statistics and R1CS complexity: +Read the table per command: the short `-p` flag changes meaning between `prepare` and `prove`. -```sh -cargo run --release --bin provekit-cli circuit_stats ./target/basic.json -``` - -Analyze PKP file size breakdown: +## How It Works -```sh -cargo run --release --bin provekit-cli analyze-pkp ./prover.pkp +```mermaid +graph LR + Noir[Noir package
Nargo.toml + .nr] -->|provekit-cli prepare| ACIR[ACIR artifact
target/*.json] + ACIR -->|r1cs-compiler| R1CS[R1CS
+ witness builders] + R1CS --> PKP[(.pkp
prover key)] + R1CS --> PKV[(.pkv
verifier key)] + Inputs[Prover.toml] --> Prover((Prover)) + PKP --> Prover + Prover --> Proof[proof.np] + PKV --> Verifier((Verifier)) + Proof --> Verifier + PKP -.-> GnarkInputs[generate-gnark-inputs] + Proof -.-> GnarkInputs + GnarkInputs -.-> Recursive[Go/gnark
recursive verifier] + Recursive --> Groth16[Groth16 proof] ``` -Show public inputs with variable names: +The v1 CLI compiles Noir packages during `prepare`, saves the ACIR artifact under the package target directory, lowers ACIR into R1CS, constructs witness builders, and writes `.pkp`/`.pkv` key files. Recursive verification exports use the `.pkp` prover key plus `proof.np` because v1 needs prover-side WHIR/R1CS parameters to create the gnark input files. -```sh -cargo run --release --bin provekit-cli show-inputs ./verifier.pkv ./proof.np -``` +## Example Circuit -Recursively verify in a Gnark proof: +[`noir-examples/basic-4`](./noir-examples/basic-4/) proves knowledge of inputs `(a, b)` satisfying `(a + b) * (a - b) == result`: -```sh -cd ../../recursive-verifier -go run cmd/cli/main.go --config ../noir-examples/poseidon-rounds/params_for_recursive_verifier --r1cs ../noir-examples/poseidon-rounds/r1cs.json +```rust +fn main(a: Field, b: Field) -> pub Field { + let sum = a + b; + let diff = a - b; + sum * diff +} ``` -### Benchmarking +For larger circuits and integration experiments, see [`noir-examples/`](./noir-examples/). -Benchmark against Barretenberg: +## Repository Map -> _Note_: You can install Barretenberg from [here](https://github.com/AztecProtocol/aztec-packages/blob/master/barretenberg/bbup/README.md). +| Layer | Path | Crate/package | Purpose | +| :--- | :--- | :--- | :--- | +| Common types | `provekit/common/` | `provekit-common` | Shared R1CS, witness, proof, key, serialization, and transcript utilities | +| Compiler | `provekit/r1cs-compiler/` | `provekit-r1cs-compiler` | Noir ACIR → R1CS with constraint optimizations | +| Prover | `provekit/prover/` | `provekit-prover` | WHIR proving, witness solving, R1CS compression, and commitments | +| Verifier | `provekit/verifier/` | `provekit-verifier` | WHIR verification, transcript replay, sumcheck checks, and public input binding | +| CLI | `tooling/cli/` | `provekit-cli` | Commands for prepare, prove, verify, inspection, and gnark input generation | +| Benchmarks | `tooling/provekit-bench/` | `provekit-bench` | Benchmark utilities and regression coverage for proving workflows | +| FFI | `tooling/provekit-ffi/` | `provekit-ffi` | C-compatible bindings for Swift/iOS, Kotlin/Android, Python, JavaScript, and other FFI hosts | +| Gnark export | `tooling/provekit-gnark/` | `provekit-gnark` | Rust-side export/config bridge for recursive verification artifacts | +| Verifier server | `tooling/verifier-server/` | `verifier-server` | HTTP server that orchestrates Rust proof handling and Go verifier execution | +| NTT | `ntt/` | `provekit-ntt` | Number Theoretic Transform implementation for BN254 polynomial evaluation paths | +| Hash engine | `skyscraper/` | first-party Skyscraper crates | Custom BN254 hash and SIMD-accelerated field arithmetic support | +| Recursive verifier | `recursive-verifier/` | Go module | Go + gnark recursive verifier for on-chain Groth16 wrappers | +| Examples | `noir-examples/` | Noir packages | Noir example circuits and R1CS compiler test programs | -> _Note_: You can install [hyperfine](https://github.com/sharkdp/hyperfine) using brew on OSX: `brew install hyperfine`. +## Advanced Usage -```sh -cd noir-examples/poseidon-rounds -cargo run --release --bin provekit-cli prepare --pkp ./prover.pkp --pkv ./verifier.pkv -hyperfine 'nargo execute && bb prove -b ./target/basic.json -w ./target/basic.gz -o ./target' '../../target/release/provekit-cli prove -p ./prover.pkp -i ./Prover.toml' -``` +- **Explicit project paths:** run `provekit-cli prepare ./noir-examples/poseidon-rounds --pkp ./prover.pkp --pkv ./verifier.pkv` when preparing a package outside the current directory or when you want fixed key names. +- **Recursive verifier inputs:** `provekit-cli generate-gnark-inputs ` writes `params_for_recursive_verifier` and `r1cs.json` by default; use `--params` and `--r1cs` to override those paths. +- **Inspection commands:** use `circuit-stats` for ACIR/R1CS structure, `analyze-pkp` for prover-key size breakdowns, and `show-inputs` for public inputs. +- **FFI integration:** start in [`tooling/provekit-ffi/`](tooling/provekit-ffi/) for C ABI headers, mobile build targets, and host-language examples. +- **Benchmarking:** use [`tooling/provekit-bench/`](tooling/provekit-bench/) for internal benchmark coverage, or compare CLI proof generation with external tools using `hyperfine`. ### Profiling -#### Custom built-in profile (Memory usage) - -The `provekit-cli` application has written custom memory profiler that prints basic info about memory usage when application -runs. To run binary with profiling enabled run it with cargo `--features profiling` param or compile with it. - -```sh -cargo run --release --bin provekit-cli --features profiling prove -p ./prover.pkp -i ./Prover.toml -o ./proof.np -``` - -#### Using tracy (CPU and Memory usage) - -Tracy tool [website](https://github.com/wolfpld/tracy). To install tracy tool on OSX use brew: `brew install tracy`. - -> **Important**: integration is done with `Tracy Profiler 0.11.1`. It is newest version available from brew. Newer -> version may require updating dependencies as tracy is using its own protocol between app and tracy tool that changes -> with each major version. - -TLDR; Tracy is an interactive tool to profile application. There is integration plugin for rust that works with -standard tracing annotation. For now it is integrated into `provekit-cli` binary only. Collecting profiling data requires -tracy to run during application profiling. You may noticed that it makes application to run much longer but mostly -due to data transfer between the application and the tracy running along. - -Usage: - -1. Start tracy from command line -```sh -tracy -``` -2. Leave all fields with defaults and just click `Connect` button. It will cause tracy to start listening on the - localhost for incoming data. -3. Compile `noir-r1cs-profiled` binary. -```sh -cargo build --release --bin provekit-cli --features profiling -``` -4. (OSX only) If you want to check call stacks additional command needs to be run (base on tracy instruction). The - command must be run against each binary that is being profiled by tracy. This will create directory next to the - binary provided with `.dSYM` suffix (ex. `../../target/profiled-cli.dSYM`). Directory will contain the - debug symbols and paths extracted with different format that is compatible with tracy tool. It must be rerun after - each changes made to `provekit-cli` app. -```sh - dsymutil ../../target/release/provekit-cli -``` -5. Now start the application to profile: -```sh -../../target/release/provekit-cli prove -p ./prover.pkp -i ./Prover.toml -o ./proof.np -``` -6. Go back to tracy tool. You should see that it receives data. App is interactive. - -#### Using samply (CPU usage) - -Samply tool [website](https://github.com/mstange/samply/) with instructions to install. It will start local server and -open a webpage with interactive app to view results. This does not require to run binary -with profiling enabled. - -```sh -samply record -r 10000 -- ./../../target/release/provekit-cli prove -p ./prover.pkp -i ./Prover.toml -o ./proof.np -``` - -#### Using instruments (Memory usage) - OSX only - -Cargo instruments tool [website](https://crates.io/crates/cargo-instruments) with instructions to install. It will open -results using built-in Instruments app. Results are interactive. - -```sh -cargo instruments --template Allocations --release --bin provekit-cli prove -p ./prover.pkp -i ./Prover.toml -o ./proof.np -``` - -Samply tool [website](https://github.com/mstange/samply/) with instructions to install. It will start local server and -open a webpage with interactive app to view results. This does not require to run binary -with profiling enabled. - -```sh -samply record -r 10000 -- ./../../target/release/provekit-cli prove -p ./prover.pkp -i ./Prover.toml -o ./proof.np -``` - -## Benchmarking - -Run the benchmark suite: - -```sh -cargo test -p provekit-bench --bench bench -``` - -## Architecture +| Tool | Measures | Command | +| :--- | :--- | :--- | +| Built-in allocator stats | Memory | `cargo run --release --features profiling --bin provekit-cli prove ...` | +| [Tracy](https://github.com/wolfpld/tracy) | CPU and memory | `cargo build --release --features profiling` then run the binary with Tracy listening. On macOS, run `dsymutil` on the binary first to get call stacks. | +| [Samply](https://github.com/mstange/samply) | CPU flamegraphs | `samply record -r 10000 -- ./target/release/provekit-cli prove ...` | +| [Instruments](https://crates.io/crates/cargo-instruments) | Allocations on macOS | `cargo instruments --template Allocations --release --bin provekit-cli prove ...` | -ProveKit follows a modular architecture with clear separation of concerns: +## Project Status -### Core Modules -- **`provekit/common/`** - Shared utilities, core types, and R1CS abstractions -- **`provekit/r1cs-compiler/`** - R1CS compilation logic and Noir integration -- **`provekit/prover/`** - Proving functionality with witness generation -- **`provekit/verifier/`** - Verification functionality +This README documents the `v1` branch, the current stable ProveKit interface. The `main` branch may differ while new proof and key formats are being developed. -### Tooling -- **`tooling/cli/`** - Command-line interface (`provekit-cli`) -- **`tooling/provekit-bench/`** - Benchmarking infrastructure -- **`tooling/provekit-gnark/`** - Gnark integration utilities +## Contributing -### High-Performance Components -- **`skyscraper/`** - Optimized field arithmetic for M31/CM31 fields -- **`playground/`** - Research and experimental implementations +Contributions are welcome. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for development guidelines and use the [issue tracker](https://github.com/worldfnd/provekit/issues) for bugs, feature requests, and design discussion. -### Examples & Tests -- **`noir-examples/`** - Example circuits and test programs -- **`gnark-whir/`** - Go-based recursive verification using Gnark +## Acknowledgements -## Dependencies +- [**WHIR**](https://github.com/WizardOfMenlo/whir) — polynomial commitment scheme and sumcheck protocol used by the proof system. +- [**Spongefish**](https://github.com/arkworks-rs/spongefish) — Fiat–Shamir transcript library used for challenge derivation. +- [**gnark-skyscraper**](https://github.com/reilabs/gnark-skyscraper) — Go implementation used by the recursive verifier to reproduce Skyscraper commitments. +- [**Noir**](https://github.com/noir-lang/noir) — ZK DSL compiled by ProveKit. -This project depends on the following libraries, which are developed in lockstep: +## License -- [🌪️ WHIR](https://github.com/WizardOfMenlo/whir) -- [Spongefish](https://github.com/arkworks-rs/spongefish) -- [gnark-skyscraper](https://github.com/reilabs/gnark-skyscraper) -- [recursive-verifier](./recursive-verifier/README.md) -- [noir](https://github.com/noir-lang/noir) +Released under the [MIT / Apache 2.0 licenses](./License.md). Copyright (c) 2026 World Foundation. diff --git a/assets/banner.png b/assets/banner.png new file mode 100644 index 000000000..abe02d24c Binary files /dev/null and b/assets/banner.png differ