From 2da49a8f3d1372428e73694bff6ef2e10cda16c8 Mon Sep 17 00:00:00 2001 From: Shubham Gupta Date: Wed, 22 Apr 2026 04:05:25 +0530 Subject: [PATCH 1/6] fix(docs): correct factual errors in README overhaul - Fix CI badge URL: atheon/provekit -> worldfnd/provekit - Fix Rust version badge: 1.75+ -> nightly (project requires nightly toolchain) - Fix skyscraper description: M31/CM31 -> BN254 (skyscraper is a BN254 hash engine) - Fix setup tip: remove incorrect stable Rust version hint - Add gnark-skyscraper back to Related Projects (active dep in go.mod) --- README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index ae5a32a72..dd0ef4d24 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,8 @@ **The edge-native, zero-knowledge runtime and R1CS compilation toolkit.** -[![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/) +[![CI Passing](https://img.shields.io/badge/Build-Passing-2ea44f?style=for-the-badge&logo=github)](https://github.com/worldfnd/provekit/actions) +[![Rust Version](https://img.shields.io/badge/Rust-nightly-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.* @@ -22,7 +22,7 @@ Developing cutting-edge cryptography for constrained edge devices demands more t - **πŸ“± 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. +- **⚑ BN254 First:** Leverages the `skyscraper` backend β€” a custom BN254 hash engine with SIMD-accelerated field arithmetic. - **πŸ”„ Universal Recursion:** Gnark bindings allow you to take mobile-generated proofs and securely verify them on-chain via recursive rollups. --- @@ -67,7 +67,7 @@ graph TD | **Tooling** | `tooling/cli/` | The unified binary interface (`provekit-cli`). | | **Logic** | `provekit/prover/`
`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. | +| **Maths** | `skyscraper/` | Custom BN254 hash engine with SIMD-accelerated field arithmetic. | | **Interops**| `tooling/provekit-gnark/`
`gnark-whir/`| Bridges gap between Rust proofs and Go / Gnark validations. | --- @@ -83,7 +83,7 @@ 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`.* +*Tip: Ensure your Rust toolchain is on nightly (see `rust-toolchain.toml`).*
@@ -173,7 +173,8 @@ Designed in lockstep with industry leaders. Be sure to explore integrated system * [**πŸŒͺ️ 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. +* [**⬛ Noir**](https://github.com/noir-lang/noir) β€” The zero-knowledge domain specific language proving stack. +* [**gnark-skyscraper**](https://github.com/reilabs/gnark-skyscraper) β€” Gnark-compatible Skyscraper hash for recursive verification. ---
From 34d44873c83450ea15cdf602e4c5a01d867a9856 Mon Sep 17 00:00:00 2001 From: Shubham Gupta Date: Thu, 23 Apr 2026 04:20:26 +0530 Subject: [PATCH 2/6] docs(readme): polish README with quick links, code example, and acknowledgements - Add quick links row (Getting Started, Examples, Contributing, Issues) - Add end-to-end Example section using noir-examples/basic (verified locally) - Rewrite Related Projects as Acknowledgements in SP1 style, explaining what each dependency contributes to ProveKit specifically - Fix License badge to link to License.md instead of dead anchor - Strip AI-generated marketing language throughout; rewrite in direct, technical prose consistent with SP1, RISC Zero, and gnark conventions --- README.md | 149 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 77 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index dd0ef4d24..373ab1921 100644 --- a/README.md +++ b/README.md @@ -2,34 +2,19 @@ ProveKit -**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/worldfnd/provekit/actions) -[![Rust Version](https://img.shields.io/badge/Rust-nightly-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)
---- - -## ✨ 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. -- **⚑ BN254 First:** Leverages the `skyscraper` backend β€” a custom BN254 hash engine with SIMD-accelerated field arithmetic. -- **πŸ”„ Universal Recursion:** Gnark bindings allow you to take mobile-generated proofs and securely verify them on-chain via recursive rollups. +ProveKit compiles Noir circuits to R1CS and generates WHIR proofs. It targets mobile and constrained environments β€” with a custom BN254 hash engine ([Skyscraper](skyscraper/)), swap-to-disk memory management, and C FFI bindings for iOS and Android. A gnark-based recursive verifier wraps WHIR proofs in Groth16 for on-chain verification. --- -## πŸ—οΈ Architecture - -ProveKit implements a highly decoupled pipelineβ€”from constraint generation to proof verification. +## Architecture ```mermaid graph TD @@ -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/`
`provekit/verifier/` | Core ZK proving systems algorithms and verification targets. | -| **Constraints** | `provekit/r1cs-compiler/` | Translates Noir execution environments down to R1CS formats. | -| **Maths** | `skyscraper/` | Custom BN254 hash engine with SIMD-accelerated field arithmetic. | -| **Interops**| `tooling/provekit-gnark/`
`gnark-whir/`| Bridges gap between Rust proofs and Go / Gnark validations. | +| CLI | `tooling/cli/` | `provekit-cli` β€” prepare, prove, verify, inspect | +| Prover / Verifier | `provekit/prover/`
`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/`
`gnark-whir/` | Rust ↔ Go/gnark bridge for recursive verification | + +--- + +## Example + +Prove knowledge of a Poseidon hash preimage β€” a circuit from [`noir-examples/basic`](./noir-examples/basic/): + +```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 +## Getting Started -ProveKit tightly integrates with the Noir (`nargo`) development chain. Standard installation requires a strict cross-compatible version of the environment. +Requires the Noir toolchain and Rust nightly. The exact nightly version is pinned in `rust-toolchain.toml` and applied automatically by `rustup`.
-1️⃣ Setup Dependencies
+1. Install the Noir toolchain
-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 nightly (see `rust-toolchain.toml`).*
-2️⃣ Compile a Circuit
+2. Compile a circuit
-Our examples use `poseidon-rounds` as the canonical benchmark. You can use standard Noir or `mavros`. +The examples use `poseidon-rounds` as the reference 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 @@ -107,76 +113,75 @@ cargo run --release --bin provekit-cli prepare --compiler mavros ./target/basic.
-3️⃣ Prove & Verify Workflow
- -Once the constraint keys are extracted, run the high-performance prover: +3. Prove and verify
```sh -# Generate the dense ZK proof +# Generate a proof cargo run --release --bin provekit-cli prove ./prover.pkp ./Prover.toml -o ./proof.np -# Locally verify +# Verify locally 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 ```
-4️⃣ Benchmark Tooling
+4. Benchmark
-ProveKit can natively be benchmarked against alternative prover backends like [Barretenberg](https://github.com/AztecProtocol/aztec-packages/blob/master/barretenberg/bbup/README.md). +Compare against [Barretenberg](https://github.com/AztecProtocol/aztec-packages/blob/master/barretenberg/bbup/README.md) using [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:** +Run the internal benchmark suite: ```sh cargo test -p provekit-bench --bench bench ```
- --- -## πŸ› οΈ Diagnostics & Profiling +## Profiling -ProveKit exposes industry-grade telemetry specifically tuned for ensuring applications won't blow up a mobile app's RAM budget. +| 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 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 (macOS only) | `cargo instruments --template Allocations --release --bin provekit-cli prove ...` | -| Tooling Platform | Description & Command Structure | -| :--- | :--- | -| **Native Diagnostics** | Toggle internal allocators:
`cargo run --release --features profiling --bin provekit-cli prove ...` | -| **Tracy GUI** | Requires instrumented binary build:
`cargo build --release --features profiling` *(Note: Use `dsymutil` on macOS)* | -| **Samply (CPU)** | Native CPU Flamegraphs:
`samply record -r 10000 -- prove ...` | -| **Apple Instruments** | Native macOS allocation tracking:
`cargo instruments --template Allocations --release --bin provekit-cli prove ...` | +### Circuit inspection -> [!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` +```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: +ProveKit builds on several open-source projects: -* [**πŸŒͺ️ 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. -* [**gnark-skyscraper**](https://github.com/reilabs/gnark-skyscraper) β€” Gnark-compatible Skyscraper hash for recursive verification. +- [**WHIR**](https://github.com/WizardOfMenlo/whir) β€” The multilinear polynomial commitment scheme and sumcheck protocol at the core of ProveKit's proof system. `WhirR1CSScheme` wraps it to prove R1CS satisfiability over BN254. ---- -
-Driven by research, built for production. -
+- [**Spongefish**](https://github.com/arkworks-rs/spongefish) β€” A permutation-agnostic Fiat-Shamir library from arkworks. ProveKit's `TranscriptSponge` and `DuplexSponge` are built on its API, driving all challenge derivation in the proof protocol. + +- [**gnark-skyscraper**](https://github.com/reilabs/gnark-skyscraper) β€” The Go implementation of the Skyscraper hash for gnark circuits. The recursive verifier uses it to reproduce the exact Merkle tree commitments generated by the Rust prover, enabling cross-language proof verification. + +- [**Noir**](https://github.com/noir-lang/noir) β€” The ZK domain-specific language ProveKit compiles from. ProveKit ingests Noir's ACIR (Abstract Circuit Intermediate Representation) output and lowers it to R1CS. From 2a1814cad31202fdbe268658fda7035c5faec225 Mon Sep 17 00:00:00 2001 From: Shubham Gupta Date: Fri, 24 Apr 2026 04:30:20 +0530 Subject: [PATCH 3/6] =?UTF-8?q?docs(readme):=20tone=20pass=20=E2=80=94=20r?= =?UTF-8?q?emove=20formulaic=20structure=20without=20losing=20precision?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 30 ++++++++++++------------------ 1 file changed, 12 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 373ab1921..d0f9cf7ad 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ -ProveKit compiles Noir circuits to R1CS and generates WHIR proofs. It targets mobile and constrained environments β€” with a custom BN254 hash engine ([Skyscraper](skyscraper/)), swap-to-disk memory management, and C FFI bindings for iOS and Android. A gnark-based recursive verifier wraps WHIR proofs in Groth16 for on-chain verification. +ProveKit takes Noir circuits, compiles them to R1CS, and generates WHIR proofs β€” built for mobile and edge environments. The core includes a custom BN254 hash engine ([Skyscraper](skyscraper/)), swap-to-disk memory management, and C FFI bindings for iOS and Android. A gnark-based recursive verifier wraps WHIR proofs in Groth16 for on-chain verification. --- @@ -59,7 +59,7 @@ graph TD ## Example -Prove knowledge of a Poseidon hash preimage β€” a circuit from [`noir-examples/basic`](./noir-examples/basic/): +From [`noir-examples/basic`](./noir-examples/basic/) β€” proves knowledge of a Poseidon hash preimage: ```rust use dep::poseidon2; @@ -82,10 +82,10 @@ cargo run --release --bin provekit-cli verify verifier.pkv proof.np ## Getting Started -Requires the Noir toolchain and Rust nightly. The exact nightly version is pinned in `rust-toolchain.toml` and applied automatically by `rustup`. +Requires nargo `v1.0.0-beta.19` and Rust nightly. The toolchain version is pinned in `rust-toolchain.toml`.
-1. Install the Noir toolchain
+1. Install nargo
```sh noirup --version v1.0.0-beta.19 @@ -95,7 +95,7 @@ noirup --version v1.0.0-beta.19
2. Compile a circuit
-The examples use `poseidon-rounds` as the reference circuit. +Using `poseidon-rounds` as the example: **With nargo:** ```sh @@ -116,14 +116,11 @@ cargo run --release --bin provekit-cli prepare --compiler mavros ./target/basic. 3. Prove and verify
```sh -# Generate a proof cargo run --release --bin provekit-cli prove ./prover.pkp ./Prover.toml -o ./proof.np - -# Verify locally cargo run --release --bin provekit-cli verify ./verifier.pkv ./proof.np ``` -**Recursive (on-chain) verification:** +**Recursive on-chain verification:** ```sh cargo run --release --bin provekit-cli generate-gnark-inputs ./verifier.pkv ./proof.np @@ -160,12 +157,11 @@ cargo test -p provekit-bench --bench bench | 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 the binary with Tracy listening. On macOS, run `dsymutil` on the binary first to get call stacks. | +| [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 ...` | -### Circuit inspection - +Static inspection 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 @@ -176,12 +172,10 @@ provekit-cli show-inputs ./verifier.pkv ./proof.np # public input names and val ## Acknowledgements -ProveKit builds on several open-source projects: - -- [**WHIR**](https://github.com/WizardOfMenlo/whir) β€” The multilinear polynomial commitment scheme and sumcheck protocol at the core of ProveKit's proof system. `WhirR1CSScheme` wraps it to prove R1CS satisfiability over BN254. +- [**WHIR**](https://github.com/WizardOfMenlo/whir) β€” the polynomial commitment scheme and sumcheck protocol the proof system is built on. `WhirR1CSScheme` wraps it directly. -- [**Spongefish**](https://github.com/arkworks-rs/spongefish) β€” A permutation-agnostic Fiat-Shamir library from arkworks. ProveKit's `TranscriptSponge` and `DuplexSponge` are built on its API, driving all challenge derivation in the proof protocol. +- [**Spongefish**](https://github.com/arkworks-rs/spongefish) β€” Fiat-Shamir library from arkworks. ProveKit's transcript and challenge derivation run on its `DuplexSponge` API. -- [**gnark-skyscraper**](https://github.com/reilabs/gnark-skyscraper) β€” The Go implementation of the Skyscraper hash for gnark circuits. The recursive verifier uses it to reproduce the exact Merkle tree commitments generated by the Rust prover, enabling cross-language proof verification. +- [**gnark-skyscraper**](https://github.com/reilabs/gnark-skyscraper) β€” Go implementation of the Skyscraper hash. The recursive verifier relies on it to reproduce Merkle commitments from the Rust prover. -- [**Noir**](https://github.com/noir-lang/noir) β€” The ZK domain-specific language ProveKit compiles from. ProveKit ingests Noir's ACIR (Abstract Circuit Intermediate Representation) output and lowers it to R1CS. +- [**Noir**](https://github.com/noir-lang/noir) β€” the ZK DSL ProveKit compiles from. ProveKit consumes Noir's ACIR output and lowers it to R1CS. From 190535ae2aeaa5bedeeceae9b7afaf62e8b9ff55 Mon Sep 17 00:00:00 2001 From: Shubham Gupta Date: Fri, 24 Apr 2026 04:59:39 +0530 Subject: [PATCH 4/6] docs(readme): enrich acknowledgements with specific technical detail MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the terse two-sentence formula in each dependency bullet with fuller descriptions that explain what each library does and precisely how ProveKit uses it β€” closer in depth to how the project actually integrates each dependency. --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index d0f9cf7ad..8f1d66cb9 100644 --- a/README.md +++ b/README.md @@ -172,10 +172,10 @@ provekit-cli show-inputs ./verifier.pkv ./proof.np # public input names and val ## Acknowledgements -- [**WHIR**](https://github.com/WizardOfMenlo/whir) β€” the polynomial commitment scheme and sumcheck protocol the proof system is built on. `WhirR1CSScheme` wraps it directly. +- [**WHIR**](https://github.com/WizardOfMenlo/whir) β€” the multilinear polynomial commitment scheme and sumcheck protocol at the core of ProveKit's proof system. `WhirR1CSScheme` wraps it to prove R1CS satisfiability over BN254. -- [**Spongefish**](https://github.com/arkworks-rs/spongefish) β€” Fiat-Shamir library from arkworks. ProveKit's transcript and challenge derivation run on its `DuplexSponge` API. +- [**Spongefish**](https://github.com/arkworks-rs/spongefish) β€” a permutation-agnostic Fiat-Shamir library from arkworks. ProveKit's `TranscriptSponge` and `DuplexSponge` are built on its API, driving all challenge derivation in the proof protocol. -- [**gnark-skyscraper**](https://github.com/reilabs/gnark-skyscraper) β€” Go implementation of the Skyscraper hash. The recursive verifier relies on it to reproduce Merkle commitments from the Rust prover. +- [**gnark-skyscraper**](https://github.com/reilabs/gnark-skyscraper) β€” Go implementation of the Skyscraper hash for gnark circuits. The recursive verifier uses it to reproduce the exact Merkle tree commitments generated by the Rust prover, enabling cross-language proof verification. -- [**Noir**](https://github.com/noir-lang/noir) β€” the ZK DSL ProveKit compiles from. ProveKit consumes Noir's ACIR output and lowers it to R1CS. +- [**Noir**](https://github.com/noir-lang/noir) β€” the ZK domain-specific language ProveKit compiles from. Circuits are authored in Noir, compiled to ACIR via nargo, and lowered to R1CS by ProveKit's compiler. From 689fe408ec0a5c90f97a4154cbd9a32d3b416df4 Mon Sep 17 00:00:00 2001 From: Shubham Gupta Date: Fri, 24 Apr 2026 14:55:51 +0530 Subject: [PATCH 5/6] docs(readme): rewrite prose for natural developer tone --- README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 8f1d66cb9..40f56947d 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ -ProveKit takes Noir circuits, compiles them to R1CS, and generates WHIR proofs β€” built for mobile and edge environments. The core includes a custom BN254 hash engine ([Skyscraper](skyscraper/)), swap-to-disk memory management, and C FFI bindings for iOS and Android. A gnark-based recursive verifier wraps WHIR proofs in Groth16 for on-chain verification. +ProveKit takes a Noir circuit, lowers it to R1CS, and proves it with WHIR. Built for mobile and constrained environments β€” ships with a custom BN254 hash engine ([Skyscraper](skyscraper/)), swap-to-disk memory management, and C FFI for iOS and Android. There's also a gnark recursive verifier that wraps WHIR proofs in Groth16 for on-chain verification. --- @@ -59,7 +59,7 @@ graph TD ## Example -From [`noir-examples/basic`](./noir-examples/basic/) β€” proves knowledge of a Poseidon hash preimage: +[`noir-examples/basic`](./noir-examples/basic/) β€” proves knowledge of a Poseidon hash preimage: ```rust use dep::poseidon2; @@ -82,7 +82,7 @@ cargo run --release --bin provekit-cli verify verifier.pkv proof.np ## Getting Started -Requires nargo `v1.0.0-beta.19` and Rust nightly. The toolchain version is pinned in `rust-toolchain.toml`. +You need nargo `v1.0.0-beta.19` and Rust nightly. Toolchain is pinned in `rust-toolchain.toml`; rustup picks it up automatically.
1. Install nargo
@@ -134,7 +134,7 @@ go run cmd/cli/main.go \
4. Benchmark
-Compare against [Barretenberg](https://github.com/AztecProtocol/aztec-packages/blob/master/barretenberg/bbup/README.md) using [hyperfine](https://github.com/sharkdp/hyperfine): +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 @@ -144,7 +144,7 @@ hyperfine \ '../../target/release/provekit-cli prove ./prover.pkp ./Prover.toml' ``` -Run the internal benchmark suite: +Internal benchmark suite: ```sh cargo test -p provekit-bench --bench bench ``` @@ -161,7 +161,7 @@ cargo test -p provekit-bench --bench bench | [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 ...` | -Static inspection without running a proof: +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 @@ -172,10 +172,10 @@ provekit-cli show-inputs ./verifier.pkv ./proof.np # public input names and val ## Acknowledgements -- [**WHIR**](https://github.com/WizardOfMenlo/whir) β€” the multilinear polynomial commitment scheme and sumcheck protocol at the core of ProveKit's proof system. `WhirR1CSScheme` wraps it to prove R1CS satisfiability over BN254. +- [**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. -- [**Spongefish**](https://github.com/arkworks-rs/spongefish) β€” a permutation-agnostic Fiat-Shamir library from arkworks. ProveKit's `TranscriptSponge` and `DuplexSponge` are built on its API, driving all challenge derivation in the proof protocol. +- [**Spongefish**](https://github.com/arkworks-rs/spongefish) β€” Fiat-Shamir library from arkworks. All transcript construction and challenge derivation goes through its `DuplexSponge` API. -- [**gnark-skyscraper**](https://github.com/reilabs/gnark-skyscraper) β€” Go implementation of the Skyscraper hash for gnark circuits. The recursive verifier uses it to reproduce the exact Merkle tree commitments generated by the Rust prover, enabling cross-language proof verification. +- [**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 domain-specific language ProveKit compiles from. Circuits are authored in Noir, compiled to ACIR via nargo, and lowered to R1CS by ProveKit's compiler. +- [**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. From d3094df2def82c7489f0ce292ae6eb25df70793b Mon Sep 17 00:00:00 2001 From: Shubham Gupta Date: Wed, 29 Apr 2026 00:43:55 +0530 Subject: [PATCH 6/6] docs(readme): apply direct reader-facing tone --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 40f56947d..ec44db23e 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ -ProveKit takes a Noir circuit, lowers it to R1CS, and proves it with WHIR. Built for mobile and constrained environments β€” ships with a custom BN254 hash engine ([Skyscraper](skyscraper/)), swap-to-disk memory management, and C FFI for iOS and Android. There's also a gnark recursive verifier that wraps WHIR proofs in Groth16 for on-chain verification. +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. --- @@ -49,7 +49,7 @@ graph TD | Layer | Crate | Description | | :--- | :--- | :--- | -| CLI | `tooling/cli/` | `provekit-cli` β€” prepare, prove, verify, inspect | +| CLI | `tooling/cli/` | `provekit-cli`: prepare, prove, verify, inspect | | Prover / Verifier | `provekit/prover/`
`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 | @@ -59,7 +59,7 @@ graph TD ## Example -[`noir-examples/basic`](./noir-examples/basic/) β€” proves knowledge of a Poseidon hash preimage: +Here's [`noir-examples/basic`](./noir-examples/basic/), which proves knowledge of a Poseidon hash preimage: ```rust use dep::poseidon2; @@ -95,7 +95,7 @@ noirup --version v1.0.0-beta.19
2. Compile a circuit
-Using `poseidon-rounds` as the example: +The steps below use `poseidon-rounds` as the example circuit. **With nargo:** ```sh @@ -161,7 +161,7 @@ cargo test -p provekit-bench --bench bench | [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 ...` | -To inspect without running a proof: +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 @@ -172,10 +172,10 @@ provekit-cli show-inputs ./verifier.pkv ./proof.np # public input names and val ## Acknowledgements -- [**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 polynomial commitment scheme and sumcheck protocol the proof system is built on. `WhirR1CSScheme` wraps it for R1CS satisfiability over BN254. -- [**Spongefish**](https://github.com/arkworks-rs/spongefish) β€” Fiat-Shamir library from arkworks. All transcript construction and challenge derivation goes through its `DuplexSponge` API. +- [**Spongefish**](https://github.com/arkworks-rs/spongefish): Fiat-Shamir library from arkworks. All transcript construction and challenge derivation goes through its `DuplexSponge` API. -- [**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. +- [**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. +- [**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.