Skip to content

Commit 87c96b7

Browse files
Bisht13Bisht13
authored
Merge pull request #421 from worldfnd/us/v1-readme-overhaul
docs(readme): overhaul README for v1 branch
2 parents 19d851d + 8e62f80 commit 87c96b7

2 files changed

Lines changed: 101 additions & 158 deletions

File tree

‎README.md‎

Lines changed: 101 additions & 158 deletions
Original file line numberDiff line numberDiff line change
@@ -1,207 +1,150 @@
11
# ProveKit
22

3-
A modular zero-knowledge proof toolkit optimized for mobile devices.
3+
<div align="center">
44

5-
## Requirements
5+
<img src="./assets/banner.png" alt="ProveKit" width="100%" />
66

7-
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.
7+
[![CI](https://img.shields.io/badge/build-passing-2ea44f?style=flat-square&logo=github)](https://github.com/worldfnd/provekit/actions)
8+
[![Rust](https://img.shields.io/badge/rust-nightly-e32828?style=flat-square&logo=rust)](https://rustup.rs/)
9+
[![License](https://img.shields.io/badge/license-MIT%20%2F%20Apache_2.0-blue?style=flat-square)](./License.md)
810

9-
```sh
10-
noirup --version v1.0.0-beta.11
11-
```
11+
[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Examples](./noir-examples/) · [Repository Map](#repository-map) · [Contributing](./CONTRIBUTING.md)
1212

13-
## Demo instructions
13+
</div>
1414

15-
> _NOTE:_ The example below is being run for single example `poseidon-rounds`. You can use different example to run same commands.
15+
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.
1616

17-
Compile the Noir circuit and generate prover/verifier files:
17+
## Why ProveKit
1818

19-
```sh
20-
cd noir-examples/poseidon-rounds
21-
cargo run --release --bin provekit-cli prepare
22-
```
19+
- **Noir frontend:** write circuits in Noir and use ProveKit to compile, prepare keys, prove, and verify with one CLI.
20+
- **Post-quantum secure proofs:** produce WHIR proofs designed around post-quantum security assumptions.
21+
- **Integration-ready surface:** use ProveKit from Rust or from C-compatible FFI hosts such as Swift, Kotlin, Python, and JavaScript.
22+
- **Recursive verifier for on-chain Groth16:** export prover-key/proof data for the gnark recursive verifier when an on-chain Groth16 wrapper is required.
2323

24-
This compiles the package in the current directory and writes `<circuit>.pkp` and `<circuit>.pkv` next to it. You can also pass an explicit project directory and override the output paths:
24+
## Quick Start
2525

26-
```sh
27-
cargo run --release --bin provekit-cli prepare ./noir-examples/poseidon-rounds --pkp ./prover.pkp --pkv ./verifier.pkv
28-
```
26+
### Prerequisites
2927

30-
Generate the Noir Proof using the input Toml:
28+
Install Rust with `rustup`. This repository includes `rust-toolchain.toml`, so Cargo picks the pinned nightly automatically.
29+
30+
Install the Noir toolchain version used by v1 examples:
3131

3232
```sh
33-
cargo run --release --bin provekit-cli prove
33+
noirup --version v1.0.0-beta.11
3434
```
3535

36-
This reads `<circuit>.pkp` and `./Prover.toml` from the current directory and writes `./proof.np`. Override any of these with `-p`/`--prover`, `-i`/`--input`, or `-o`/`--out`.
36+
### Run a proof
3737

38-
Verify the Noir Proof:
38+
The smallest v1 end-to-end path is the [`noir-examples/basic-4`](./noir-examples/basic-4/) package:
3939

4040
```sh
41+
cd noir-examples/basic-4
42+
cargo run --release --bin provekit-cli prepare
43+
cargo run --release --bin provekit-cli prove
4144
cargo run --release --bin provekit-cli verify
4245
```
4346

44-
This reads `<circuit>.pkv` and `./proof.np` from the current directory. Override with `-v`/`--verifier` or `--proof`.
47+
`prepare` compiles the Noir package in the current directory and writes `<circuit>.pkp` and `<circuit>.pkv`. `prove` reads `<circuit>.pkp` plus `./Prover.toml` and writes `./proof.np`. `verify` reads `<circuit>.pkv` and `./proof.np`.
4548

46-
Generate inputs for Gnark circuit:
49+
### Command reference
4750

48-
```sh
49-
cargo run --release --bin provekit-cli generate-gnark-inputs ./prover.pkp ./proof.np
50-
```
51+
| Command | Purpose | Key options |
52+
| :--- | :--- | :--- |
53+
| `prepare [program-dir]` | Compile a Noir package and write prover/verifier keys | `--package`, `--workspace`, `--target-dir`, `--pkp`/`-p`, `--pkv`/`-v`, `--force` |
54+
| `prove` | Produce `proof.np` from a prover key and inputs | `--prover`/`-p`, `--input`/`-i`, `--out`/`-o` |
55+
| `verify` | Verify a proof against a verifier key | `--verifier`/`-v`, `--proof` |
56+
| `generate-gnark-inputs` | Export recursive-verifier inputs | positional prover key, positional proof, `--params`, `--r1cs` |
57+
| `circuit-stats` | Inspect ACIR and R1CS structure | positional compiled circuit JSON |
58+
| `analyze-pkp` | Inspect prover-key size breakdown | positional `.pkp` file |
59+
| `show-inputs` | Display public inputs from a proof | positional `.pkv` file, positional proof, `--hex` |
5160

52-
Analyze circuit statistics and R1CS complexity:
61+
Read the table per command: the short `-p` flag changes meaning between `prepare` and `prove`.
5362

54-
```sh
55-
cargo run --release --bin provekit-cli circuit_stats ./target/basic.json
56-
```
57-
58-
Analyze PKP file size breakdown:
63+
## How It Works
5964

60-
```sh
61-
cargo run --release --bin provekit-cli analyze-pkp ./prover.pkp
65+
```mermaid
66+
graph LR
67+
Noir[Noir package<br/>Nargo.toml + .nr] -->|provekit-cli prepare| ACIR[ACIR artifact<br/>target/*.json]
68+
ACIR -->|r1cs-compiler| R1CS[R1CS<br/>+ witness builders]
69+
R1CS --> PKP[(.pkp<br/>prover key)]
70+
R1CS --> PKV[(.pkv<br/>verifier key)]
71+
Inputs[Prover.toml] --> Prover((Prover))
72+
PKP --> Prover
73+
Prover --> Proof[proof.np]
74+
PKV --> Verifier((Verifier))
75+
Proof --> Verifier
76+
PKP -.-> GnarkInputs[generate-gnark-inputs]
77+
Proof -.-> GnarkInputs
78+
GnarkInputs -.-> Recursive[Go/gnark<br/>recursive verifier]
79+
Recursive --> Groth16[Groth16 proof]
6280
```
6381

64-
Show public inputs with variable names:
82+
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.
6583

66-
```sh
67-
cargo run --release --bin provekit-cli show-inputs ./verifier.pkv ./proof.np
68-
```
84+
## Example Circuit
6985

70-
Recursively verify in a Gnark proof:
86+
[`noir-examples/basic-4`](./noir-examples/basic-4/) proves knowledge of inputs `(a, b)` satisfying `(a + b) * (a - b) == result`:
7187

72-
```sh
73-
cd ../../recursive-verifier
74-
go run cmd/cli/main.go --config ../noir-examples/poseidon-rounds/params_for_recursive_verifier --r1cs ../noir-examples/poseidon-rounds/r1cs.json
88+
```rust
89+
fn main(a: Field, b: Field) -> pub Field {
90+
let sum = a + b;
91+
let diff = a - b;
92+
sum * diff
93+
}
7594
```
7695

77-
### Benchmarking
96+
For larger circuits and integration experiments, see [`noir-examples/`](./noir-examples/).
7897

79-
Benchmark against Barretenberg:
98+
## Repository Map
8099

81-
> _Note_: You can install Barretenberg from [here](https://github.com/AztecProtocol/aztec-packages/blob/master/barretenberg/bbup/README.md).
100+
| Layer | Path | Crate/package | Purpose |
101+
| :--- | :--- | :--- | :--- |
102+
| Common types | `provekit/common/` | `provekit-common` | Shared R1CS, witness, proof, key, serialization, and transcript utilities |
103+
| Compiler | `provekit/r1cs-compiler/` | `provekit-r1cs-compiler` | Noir ACIR → R1CS with constraint optimizations |
104+
| Prover | `provekit/prover/` | `provekit-prover` | WHIR proving, witness solving, R1CS compression, and commitments |
105+
| Verifier | `provekit/verifier/` | `provekit-verifier` | WHIR verification, transcript replay, sumcheck checks, and public input binding |
106+
| CLI | `tooling/cli/` | `provekit-cli` | Commands for prepare, prove, verify, inspection, and gnark input generation |
107+
| Benchmarks | `tooling/provekit-bench/` | `provekit-bench` | Benchmark utilities and regression coverage for proving workflows |
108+
| FFI | `tooling/provekit-ffi/` | `provekit-ffi` | C-compatible bindings for Swift/iOS, Kotlin/Android, Python, JavaScript, and other FFI hosts |
109+
| Gnark export | `tooling/provekit-gnark/` | `provekit-gnark` | Rust-side export/config bridge for recursive verification artifacts |
110+
| Verifier server | `tooling/verifier-server/` | `verifier-server` | HTTP server that orchestrates Rust proof handling and Go verifier execution |
111+
| NTT | `ntt/` | `provekit-ntt` | Number Theoretic Transform implementation for BN254 polynomial evaluation paths |
112+
| Hash engine | `skyscraper/` | first-party Skyscraper crates | Custom BN254 hash and SIMD-accelerated field arithmetic support |
113+
| Recursive verifier | `recursive-verifier/` | Go module | Go + gnark recursive verifier for on-chain Groth16 wrappers |
114+
| Examples | `noir-examples/` | Noir packages | Noir example circuits and R1CS compiler test programs |
82115

83-
> _Note_: You can install [hyperfine](https://github.com/sharkdp/hyperfine) using brew on OSX: `brew install hyperfine`.
116+
## Advanced Usage
84117

85-
```sh
86-
cd noir-examples/poseidon-rounds
87-
cargo run --release --bin provekit-cli prepare --pkp ./prover.pkp --pkv ./verifier.pkv
88-
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'
89-
```
118+
- **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.
119+
- **Recursive verifier inputs:** `provekit-cli generate-gnark-inputs <prover.pkp> <proof.np>` writes `params_for_recursive_verifier` and `r1cs.json` by default; use `--params` and `--r1cs` to override those paths.
120+
- **Inspection commands:** use `circuit-stats` for ACIR/R1CS structure, `analyze-pkp` for prover-key size breakdowns, and `show-inputs` for public inputs.
121+
- **FFI integration:** start in [`tooling/provekit-ffi/`](tooling/provekit-ffi/) for C ABI headers, mobile build targets, and host-language examples.
122+
- **Benchmarking:** use [`tooling/provekit-bench/`](tooling/provekit-bench/) for internal benchmark coverage, or compare CLI proof generation with external tools using `hyperfine`.
90123

91124
### Profiling
92125

93-
#### Custom built-in profile (Memory usage)
94-
95-
The `provekit-cli` application has written custom memory profiler that prints basic info about memory usage when application
96-
runs. To run binary with profiling enabled run it with cargo `--features profiling` param or compile with it.
97-
98-
```sh
99-
cargo run --release --bin provekit-cli --features profiling prove -p ./prover.pkp -i ./Prover.toml -o ./proof.np
100-
```
101-
102-
#### Using tracy (CPU and Memory usage)
103-
104-
Tracy tool [website](https://github.com/wolfpld/tracy). To install tracy tool on OSX use brew: `brew install tracy`.
105-
106-
> **Important**: integration is done with `Tracy Profiler 0.11.1`. It is newest version available from brew. Newer
107-
> version may require updating dependencies as tracy is using its own protocol between app and tracy tool that changes
108-
> with each major version.
109-
110-
TLDR; Tracy is an interactive tool to profile application. There is integration plugin for rust that works with
111-
standard tracing annotation. For now it is integrated into `provekit-cli` binary only. Collecting profiling data requires
112-
tracy to run during application profiling. You may noticed that it makes application to run much longer but mostly
113-
due to data transfer between the application and the tracy running along.
114-
115-
Usage:
116-
117-
1. Start tracy from command line
118-
```sh
119-
tracy
120-
```
121-
2. Leave all fields with defaults and just click `Connect` button. It will cause tracy to start listening on the
122-
localhost for incoming data.
123-
3. Compile `noir-r1cs-profiled` binary.
124-
```sh
125-
cargo build --release --bin provekit-cli --features profiling
126-
```
127-
4. (OSX only) If you want to check call stacks additional command needs to be run (base on tracy instruction). The
128-
command must be run against each binary that is being profiled by tracy. This will create directory next to the
129-
binary provided with `.dSYM` suffix (ex. `../../target/profiled-cli.dSYM`). Directory will contain the
130-
debug symbols and paths extracted with different format that is compatible with tracy tool. It must be rerun after
131-
each changes made to `provekit-cli` app.
132-
```sh
133-
dsymutil ../../target/release/provekit-cli
134-
```
135-
5. Now start the application to profile:
136-
```sh
137-
../../target/release/provekit-cli prove -p ./prover.pkp -i ./Prover.toml -o ./proof.np
138-
```
139-
6. Go back to tracy tool. You should see that it receives data. App is interactive.
140-
141-
#### Using samply (CPU usage)
142-
143-
Samply tool [website](https://github.com/mstange/samply/) with instructions to install. It will start local server and
144-
open a webpage with interactive app to view results. This does not require to run binary
145-
with profiling enabled.
146-
147-
```sh
148-
samply record -r 10000 -- ./../../target/release/provekit-cli prove -p ./prover.pkp -i ./Prover.toml -o ./proof.np
149-
```
150-
151-
#### Using instruments (Memory usage) - OSX only
152-
153-
Cargo instruments tool [website](https://crates.io/crates/cargo-instruments) with instructions to install. It will open
154-
results using built-in Instruments app. Results are interactive.
155-
156-
```sh
157-
cargo instruments --template Allocations --release --bin provekit-cli prove -p ./prover.pkp -i ./Prover.toml -o ./proof.np
158-
```
159-
160-
Samply tool [website](https://github.com/mstange/samply/) with instructions to install. It will start local server and
161-
open a webpage with interactive app to view results. This does not require to run binary
162-
with profiling enabled.
163-
164-
```sh
165-
samply record -r 10000 -- ./../../target/release/provekit-cli prove -p ./prover.pkp -i ./Prover.toml -o ./proof.np
166-
```
167-
168-
## Benchmarking
169-
170-
Run the benchmark suite:
171-
172-
```sh
173-
cargo test -p provekit-bench --bench bench
174-
```
175-
176-
## Architecture
126+
| Tool | Measures | Command |
127+
| :--- | :--- | :--- |
128+
| Built-in allocator stats | Memory | `cargo run --release --features profiling --bin provekit-cli prove ...` |
129+
| [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. |
130+
| [Samply](https://github.com/mstange/samply) | CPU flamegraphs | `samply record -r 10000 -- ./target/release/provekit-cli prove ...` |
131+
| [Instruments](https://crates.io/crates/cargo-instruments) | Allocations on macOS | `cargo instruments --template Allocations --release --bin provekit-cli prove ...` |
177132

178-
ProveKit follows a modular architecture with clear separation of concerns:
133+
## Project Status
179134

180-
### Core Modules
181-
- **`provekit/common/`** - Shared utilities, core types, and R1CS abstractions
182-
- **`provekit/r1cs-compiler/`** - R1CS compilation logic and Noir integration
183-
- **`provekit/prover/`** - Proving functionality with witness generation
184-
- **`provekit/verifier/`** - Verification functionality
135+
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.
185136

186-
### Tooling
187-
- **`tooling/cli/`** - Command-line interface (`provekit-cli`)
188-
- **`tooling/provekit-bench/`** - Benchmarking infrastructure
189-
- **`tooling/provekit-gnark/`** - Gnark integration utilities
137+
## Contributing
190138

191-
### High-Performance Components
192-
- **`skyscraper/`** - Optimized field arithmetic for M31/CM31 fields
193-
- **`playground/`** - Research and experimental implementations
139+
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.
194140

195-
### Examples & Tests
196-
- **`noir-examples/`** - Example circuits and test programs
197-
- **`gnark-whir/`** - Go-based recursive verification using Gnark
141+
## Acknowledgements
198142

199-
## Dependencies
143+
- [**WHIR**](https://github.com/WizardOfMenlo/whir) — polynomial commitment scheme and sumcheck protocol used by the proof system.
144+
- [**Spongefish**](https://github.com/arkworks-rs/spongefish) — Fiat–Shamir transcript library used for challenge derivation.
145+
- [**gnark-skyscraper**](https://github.com/reilabs/gnark-skyscraper) — Go implementation used by the recursive verifier to reproduce Skyscraper commitments.
146+
- [**Noir**](https://github.com/noir-lang/noir) — ZK DSL compiled by ProveKit.
200147

201-
This project depends on the following libraries, which are developed in lockstep:
148+
## License
202149

203-
- [🌪️ WHIR](https://github.com/WizardOfMenlo/whir)
204-
- [Spongefish](https://github.com/arkworks-rs/spongefish)
205-
- [gnark-skyscraper](https://github.com/reilabs/gnark-skyscraper)
206-
- [recursive-verifier](./recursive-verifier/README.md)
207-
- [noir](https://github.com/noir-lang/noir)
150+
Released under the [MIT / Apache 2.0 licenses](./License.md). Copyright (c) 2026 World Foundation.

‎assets/banner.png‎

21.8 KB
Loading

0 commit comments

Comments
 (0)