Skip to content

fix(docs): correct factual errors and polish README overhaul #420

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wryonik wants to merge 6 commits into
base: px/docs-readme
Choose a base branch
from
Open

fix(docs): correct factual errors and polish README overhaul #420

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2da49a8
fix(docs): correct factual errors in README overhaul
wryonik Apr 21, 2026
34d4487
docs(readme): polish README with quick links, code example, and ackno…
wryonik Apr 22, 2026
2a1814c
docs(readme): tone pass — remove formulaic structure without losing p…
wryonik Apr 23, 2026
190535a
docs(readme): enrich acknowledgements with specific technical detail
wryonik Apr 23, 2026
689fe40
docs(readme): rewrite prose for natural developer tone
wryonik Apr 24, 2026
d3094df
docs(readme): apply direct reader-facing tone
wryonik Apr 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 73 additions & 73 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,34 +2,19 @@

<img src="./assets/banner.png" alt="ProveKit" width="100%" />

**The edge-native, zero-knowledge runtime and R1CS compilation toolkit.**
[![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)

[![CI Passing](https://img.shields.io/badge/Build-Passing-2ea44f?style=for-the-badge&logo=github)](https://github.com/atheon/provekit/actions)
[![Rust Version](https://img.shields.io/badge/Rust-1.75+-e32828?style=for-the-badge&logo=rust)](https://rustup.rs/)
[![License MIT/Apache](https://img.shields.io/badge/License-MIT%20/%20Apache_2.0-blue.svg?style=for-the-badge)](#)

*Empowering developers to build lightweight, mobile-optimized cryptographic applications within the Noir and Gnark ecosystems.*

[Explore the Docs](#-getting-started) · [Report Bug](../../issues) · [Request Feature](../../issues)
[Getting Started](#getting-started) · [Examples](./noir-examples/) · [Contributing](./CONTRIBUTING.md) · [Issues](https://github.com/worldfnd/provekit/issues)

</div>

---

## ✨ Why ProveKit?

Developing cutting-edge cryptography for constrained edge devices demands more than generic tooling. **ProveKit** bridges the gap between high-level ZK languages and high-performance, mobile-first execution.

- **📱 Edge-Optimized:** Zero compromises. ProveKit features bespoke memory management, custom allocators, and integrates natively with macOS `instruments`, `samply`, and `tracy` to guarantee an ultra-low footprint.
- **⬛ Noir Native:** Built heavily on the [Noir](https://noir-lang.org/) stack. ProveKit consumes native Noir circuits, providing immediate interoperability.
- **⚡ M31/CM31 First:** Leverages the `skyscraper` backend for ruthlessly efficient field arithmetic.
- **🔄 Universal Recursion:** Gnark bindings allow you to take mobile-generated proofs and securely verify them on-chain via recursive rollups.
ProveKit lets you take a Noir circuit, compile it to R1CS, and generate a WHIR proof. It's built for mobile and constrained environments and ships with a custom BN254 hash engine ([Skyscraper](skyscraper/)), swap-to-disk memory management, and C FFI for iOS and Android. If you need on-chain verification, there's a gnark recursive verifier that wraps proofs in Groth16.

---

## 🏗️ Architecture

ProveKit implements a highly decoupled pipeline—from constraint generation to proof verification.
## Architecture

```mermaid
graph TD
Expand Down Expand Up @@ -60,45 +45,66 @@ graph TD
V -->|Validates| G
```

### Module Landscape
### Crates

| Layer | Component | Description |
| Layer | Crate | Description |
| :--- | :--- | :--- |
| **Tooling** | `tooling/cli/` | The unified binary interface (`provekit-cli`). |
| **Logic** | `provekit/prover/`<br>`provekit/verifier/` | Core ZK proving systems algorithms and verification targets. |
| **Constraints** | `provekit/r1cs-compiler/` | Translates Noir execution environments down to R1CS formats. |
| **Maths** | `skyscraper/` | Hand-optimized CM31/M31 field implementations. |
| **Interops**| `tooling/provekit-gnark/`<br>`gnark-whir/`| Bridges gap between Rust proofs and Go / Gnark validations. |
| CLI | `tooling/cli/` | `provekit-cli`: prepare, prove, verify, inspect |
| Prover / Verifier | `provekit/prover/`<br>`provekit/verifier/` | WHIR sumcheck, witness solving, commitment |
| Compiler | `provekit/r1cs-compiler/` | Noir ACIR → R1CS with constraint optimizations |
| Hash engine | `skyscraper/` | Custom BN254 hash with SIMD-accelerated field arithmetic |
| Interop | `tooling/provekit-gnark/`<br>`gnark-whir/` | Rust ↔ Go/gnark bridge for recursive verification |

---

## 🚀 Getting Started
## Example

Here's [`noir-examples/basic`](./noir-examples/basic/), which proves knowledge of a Poseidon hash preimage:

ProveKit tightly integrates with the Noir (`nargo`) development chain. Standard installation requires a strict cross-compatible version of the environment.
```rust
use dep::poseidon2;

fn main(plains: [Field; 2], result: Field) {
let hash = poseidon2::bn254::hash_2(plains);
assert(hash == result);
}
```

```sh
cd noir-examples/basic
nargo compile
cargo run --release --bin provekit-cli prepare ./target/basic.json --pkp prover.pkp --pkv verifier.pkv
cargo run --release --bin provekit-cli prove prover.pkp Prover.toml -o proof.np
cargo run --release --bin provekit-cli verify verifier.pkv proof.np
```

---

## Getting Started

You need nargo `v1.0.0-beta.19` and Rust nightly. Toolchain is pinned in `rust-toolchain.toml`; rustup picks it up automatically.

<details>
<summary><strong>1️⃣ Setup Dependencies</strong></summary><br>
<summary><strong>1. Install nargo</strong></summary><br>

Install the exact Noir version required by our bridging components:
```sh
noirup --version v1.0.0-beta.19
```
*Tip: Ensure your Rust toolchain is on at least `1.75`.*
</details>

<details>
<summary><strong>2️⃣ Compile a Circuit</strong></summary><br>
<summary><strong>2. Compile a circuit</strong></summary><br>

Our examples use `poseidon-rounds` as the canonical benchmark. You can use standard Noir or `mavros`.
The steps below use `poseidon-rounds` as the example circuit.

**A. Using nargo:**
**With nargo:**
```sh
cd noir-examples/poseidon-rounds
nargo compile
cargo run --release --bin provekit-cli prepare ./target/basic.json --pkp ./prover.pkp --pkv ./verifier.pkv
```

**B. Using mavros:**
**With mavros** ([install instructions](https://github.com/reilabs/mavros)):
```sh
cd noir-examples/poseidon-rounds
mavros compile
Expand All @@ -107,75 +113,69 @@ cargo run --release --bin provekit-cli prepare --compiler mavros ./target/basic.
</details>

<details open>
<summary><strong>3️⃣ Prove & Verify Workflow</strong></summary><br>

Once the constraint keys are extracted, run the high-performance prover:
<summary><strong>3. Prove and verify</strong></summary><br>

```sh
# Generate the dense ZK proof
cargo run --release --bin provekit-cli prove ./prover.pkp ./Prover.toml -o ./proof.np

# Locally verify
cargo run --release --bin provekit-cli verify ./verifier.pkv ./proof.np
```

**Generate inputs for the Gnark circuit & Recursively Verify:**
**Recursive on-chain verification:**
```sh
cargo run --release --bin provekit-cli generate-gnark-inputs ./verifier.pkv ./proof.np

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
go run cmd/cli/main.go \
--config ../noir-examples/poseidon-rounds/params_for_recursive_verifier \
--r1cs ../noir-examples/poseidon-rounds/r1cs.json
```
</details>

<details>
<summary><strong>4️⃣ Benchmark Tooling</strong></summary><br>
<summary><strong>4. Benchmark</strong></summary><br>

ProveKit can natively be benchmarked against alternative prover backends like [Barretenberg](https://github.com/AztecProtocol/aztec-packages/blob/master/barretenberg/bbup/README.md).
Benchmark against [Barretenberg](https://github.com/AztecProtocol/aztec-packages/blob/master/barretenberg/bbup/README.md) with [hyperfine](https://github.com/sharkdp/hyperfine):

```sh
cd noir-examples/poseidon-rounds
cargo run --release --bin provekit-cli prepare ./target/basic.json --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 ./prover.pkp ./Prover.toml'
hyperfine \
'nargo execute && bb prove -b ./target/basic.json -w ./target/basic.gz -o ./target' \
'../../target/release/provekit-cli prove ./prover.pkp ./Prover.toml'
```

**Run internal benchmarks:**
Internal benchmark suite:
```sh
cargo test -p provekit-bench --bench bench
```
</details>


---

## 🛠️ Diagnostics & Profiling

ProveKit exposes industry-grade telemetry specifically tuned for ensuring applications won't blow up a mobile app's RAM budget.
## Profiling

| Tooling Platform | Description & Command Structure |
| :--- | :--- |
| **Native Diagnostics** | Toggle internal allocators: <br>`cargo run --release --features profiling --bin provekit-cli prove ...` |
| **Tracy GUI** | Requires instrumented binary build: <br>`cargo build --release --features profiling` *(Note: Use `dsymutil` on macOS)* |
| **Samply (CPU)** | Native CPU Flamegraphs: <br>`samply record -r 10000 -- <binary_path> prove ...` |
| **Apple Instruments** | Native macOS allocation tracking: <br>`cargo instruments --template Allocations --release --bin provekit-cli prove ...` |
| Tool | Measures | Command |
| :--- | :--- | :--- |
| Built-in allocator stats | Memory | `cargo run --release --features profiling --bin provekit-cli prove ...` |
| [Tracy](https://github.com/wolfpld/tracy) | CPU + memory (interactive GUI) | `cargo build --release --features profiling`, then run with Tracy listening. On macOS run `dsymutil` on the binary first for 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 (macOS only) | `cargo instruments --template Allocations --release --bin provekit-cli prove ...` |

> [!TIP]
> **Static Analysis & Inspection:** You can bypass execution to statically measure proof density and investigate logic utilization using our CLI tools:
> - `provekit-cli circuit_stats ./target/basic.json`
> - `provekit-cli analyze-pkp ./prover.pkp`
> - `provekit-cli show-inputs ./verifier.pkv ./proof.np`
If you want to inspect without running a proof:
```sh
provekit-cli circuit_stats ./target/basic.json # constraint count and R1CS structure
provekit-cli analyze-pkp ./prover.pkp # proving key size breakdown
provekit-cli show-inputs ./verifier.pkv ./proof.np # public input names and values
```

---

## 📚 Related Projects
## Acknowledgements

Designed in lockstep with industry leaders. Be sure to explore integrated systems:
- [**WHIR**](https://github.com/WizardOfMenlo/whir): the polynomial commitment scheme and sumcheck protocol the proof system is built on. `WhirR1CSScheme` wraps it for R1CS satisfiability over BN254.

* [**🌪️ WHIR**](https://github.com/WizardOfMenlo/whir) — The underlying cryptography implementations.
* [**🧽 Spongefish**](https://github.com/arkworks-rs/spongefish) — Core primitives from the `arkworks-rs` team.
* [**⬛ Noir**](https://github.com/noir-lang/noir) — The zero-knowledge domain specific language proving stack.
- [**Spongefish**](https://github.com/arkworks-rs/spongefish): Fiat-Shamir library from arkworks. All transcript construction and challenge derivation goes through its `DuplexSponge` API.

---
<div align="center">
<i>Driven by research, built for production.</i>
</div>
- [**gnark-skyscraper**](https://github.com/reilabs/gnark-skyscraper): Go implementation of the Skyscraper hash. The recursive verifier needs it to reproduce the same Merkle commitments as the Rust prover.

- [**Noir**](https://github.com/noir-lang/noir): the ZK DSL we compile from. Write your circuit in Noir, run nargo to get ACIR, and ProveKit handles the rest.
Loading