Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ This implementation is designed for Plutus v3, leveraging its built-in BLS12-381

## Status

All three verifiers are functional, unit-tested, and build cleanly (`aiken check` / `aiken build`, 37/37 tests passing as of this writing). Each is **verification-only**: proof generation, circuit compilation, and (for Groth16/PLONK) trusted setup are assumed to happen off-chain, using external tooling this library does not provide. Full architecture, security arguments, and known limitations for each are written up in [`zkp/docs/`](./zkp/docs).
All three verifiers are functional, covered by unit and property-based tests, and build cleanly (`aiken check` / `aiken build`, 64/64 tests passing). Known input-validation issues are tracked as [open issues](https://github.com/ADAOcommunity/zk/issues) and pinned by `known_issue_*` tests. Each is **verification-only**: proof generation, circuit compilation, and (for Groth16/PLONK) trusted setup are assumed to happen off-chain, using external tooling this library does not provide. Full architecture, security arguments, and known limitations for each are written up in [`zkp/docs/`](./zkp/docs).

### Groth16

Expand Down Expand Up @@ -60,7 +60,7 @@ Wishlist:
### Helper Functions

- Affine point operations - conversion to/from native types (`zkp/lib/common/blst_affine.ak`)
- Field arithmetic utilities (`zkp/lib/common/common.ak`) — largely superseded by native BLS12-381 builtins inside the three verifiers above; see the implementation reports for where and why
- Field arithmetic utilities (`zkp/lib/common/common.ak`) — largely superseded by native BLS12-381 builtins inside the three verifiers above; see the implementation reports for where and why. The verifiers use only its BLS12-381 constants and three small helpers (tested in `zkp/lib/tests/common_tests.ak`); the rest is legacy code with known defects ([#20](https://github.com/ADAOcommunity/zk/issues/20))

## Aspirational ZKP Systems

Expand Down
8 changes: 4 additions & 4 deletions specification.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,21 +30,21 @@ The library's scope has been carefully defined through a systematic evaluation p

### Delivered Features

All three verifiers below are implemented, unit-tested (37/37 tests passing, both positive and negative cases), and build cleanly under `aiken check`/`aiken build`. Each is **verification-only**: none of the three includes a proof-generation toolchain, and Groth16/Plonk additionally require a trusted-setup ceremony (circuit-specific and universal, respectively) that this library does not run or provide. Full architecture, design rationale, and security arguments for each are written up in `zkp/docs/`.
All three verifiers below are implemented, covered by unit and property-based tests (64/64 tests passing, both positive and negative cases), and build cleanly under `aiken check`/`aiken build`. Each is **verification-only**: none of the three includes a proof-generation toolchain, and Groth16/Plonk additionally require a trusted-setup ceremony (circuit-specific and universal, respectively) that this library does not run or provide. Full architecture, design rationale, and security arguments for each are written up in `zkp/docs/`.

#### Groth16
- A generic Groth16 proof verifier in Aiken (`zkp/lib/groth`) that accepts any circuit-specific verification key and proof — including ones produced by an external circom + SnarkJS toolchain — without this library needing any knowledge of the circuit itself
- A test suite verifying real, externally-generated Groth16 proofs, and correctly rejecting a tampered one
- A test suite verifying real, externally-generated Groth16 proofs, and correctly rejecting a tampered one, plus property-based tests that any changed public input or replaced proof point is rejected
- See `zkp/docs/groth16-implementation-report.md`

#### Plonk
- A generic Plonk proof verifier in Aiken (`zkp/lib/plonk`), including a batched KZG opening and a Keccak-256 Fiat–Shamir transcript compatible with SnarkJS's Plonk verifier convention
- A test suite verifying a real, externally-generated Plonk proof, and correctly rejecting both a tampered proof and a mismatched public-input list
- A test suite verifying a real, externally-generated Plonk proof, and correctly rejecting both a tampered proof and a mismatched public-input list, plus property-based tests that any changed public input or evaluation scalar is rejected
- See `zkp/docs/plonk-implementation-report.md`

#### Bulletproofs
- A generic Bulletproofs range-proof verifier *and* reference prover in Aiken (`zkp/lib/bullet`) — the only one of the three with no trusted setup, so this library implements and tests both sides directly, with no external fixtures required
- A test suite covering valid proofs, boundary values (0 and `2^n - 1`), and multiple tampering/rejection cases
- A test suite covering valid proofs, boundary values (0 and `2^n - 1`), and multiple tampering/rejection cases, plus property-based tests that every in-range value can be proven and that tampered proofs and other commitments are rejected
- See `zkp/docs/bulletproofs-implementation-report.md`

### Non-Committed / Aspirational Features
Expand Down
6 changes: 4 additions & 2 deletions zkp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,9 @@ lib/
bullet/ Bulletproofs range-proof verifier and reference prover
common/ Shared field/point scaffolding (legacy; superseded by native BLS12-381
builtins inside groth/plonk/bullet — see docs/ for details)
tests/ Test suites for groth and plonk (bullet's tests live alongside bullet.ak)
tests/ Unit tests for groth and plonk (bullet's unit tests live alongside
bullet.ak), property-based tests for all three (*_props.ak),
and tests for the common helpers (common_tests.ak)
docs/
step-by-step.md Protocol-level walkthrough of all three systems
groth16-implementation-report.md Architecture, design decisions, security argument
Expand All @@ -22,7 +24,7 @@ docs/
## Working with this package

```sh
aiken check # run the test suite
aiken check # run the unit and property tests
aiken build # compile and generate plutus.json
aiken fmt # format .ak source
```
Expand Down
11 changes: 11 additions & 0 deletions zkp/aiken.lock
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,21 @@ name = "aiken-lang/stdlib"
version = "3.0.0"
source = "github"

[[requirements]]
name = "aiken-lang/fuzz"
version = "v2.2.0"
source = "github"

[[packages]]
name = "aiken-lang/stdlib"
version = "3.0.0"
requirements = []
source = "github"

[[packages]]
name = "aiken-lang/fuzz"
version = "v2.2.0"
requirements = []
source = "github"

[etags]
5 changes: 5 additions & 0 deletions zkp/aiken.toml
Original file line number Diff line number Diff line change
Expand Up @@ -15,4 +15,9 @@ name = "aiken-lang/stdlib"
version = "3.0.0"
source = "github"

[[dependencies]]
name = "aiken-lang/fuzz"
version = "v2.2.0"
source = "github"

[config]
10 changes: 7 additions & 3 deletions zkp/docs/bulletproofs-implementation-report.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
- **Module:** `zkp/lib/bullet/bullet.ak`
- **Status:** Functional, tested, unaudited
- **Test results:**
- `aiken check` 13/13
- `aiken check` 10/10 in `bullet/bullet`, plus 4/4 property and known-issue tests in `tests/bullet_props` (part of 64/64 across the package)
- `aiken fmt` clean
- `aiken build` succeeds

Expand Down Expand Up @@ -90,7 +90,7 @@ The `u` generator is present in `BulletproofVerificationKey` but unused by `veri

## 7. Testing and verification

Ten tests exercise the module, alongside the three pre-existing Groth16 tests in the same package:
Ten unit tests in `bullet.ak` exercise the module:

| Test | Verifies |
|---|---|
Expand All @@ -107,6 +107,8 @@ Ten tests exercise the module, alongside the three pre-existing Groth16 tests in

Because this module owns both prover and verifier, every test constructs a real proof in-language and checks it against a real verification run - no hardcoded external fixtures are required, unlike the Groth16 tests in this package, which depend on proofs generated by an external circuit toolchain.

`tests/bullet_props.ak` adds property-based tests (using `aiken-lang/fuzz`, 100 random cases each). `prop_*` tests state behaviour that must hold for any input. `known_issue_*` tests pin a filed bug: they pass while the bug exists and fail once it's fixed, at which point they're replaced by the property named in their comment. At `n = 8`, its properties: every value in `[0, 2^n)` verifies with any blinding and seed; a proof doesn't verify against a commitment to a different value; and changing `tau_x`, `mu`, or the first entry of `l_vec` or `r_vec` is rejected. Its known-issue test covers [#16](https://github.com/ADAOcommunity/zk/issues/16) (`commit_value` reduces mod `r`).

At `n = 8`, a full `verify` call measures approximately 5.2M memory units and 14.2B CPU units - comfortably within Cardano's per-transaction execution budget. This has not yet been benchmarked at larger `n`; see §8.

**Implementation note.** During development, an anonymous lambda with a multi-statement body (`fn(b) { expect Some(s) = scalar.new(b); s }`) passed directly to `list.map` was found to crash the Aiken v1.1.21 compiler silently, with no diagnostic output. The identical logic as a named top-level function compiles and runs correctly. Every inline lambda in this module is single-expression; the one case that needed a multi-statement body was extracted into a named helper (`scalar_from_bit`) instead. This is recorded here as a toolchain finding relevant to future work on this and other modules in the package, not a defect in the protocol implementation itself.
Expand All @@ -117,7 +119,9 @@ At `n = 8`, a full `verify` call measures approximately 5.2M memory units and 14
- **Execution-unit cost is unbenchmarked past `n = 8`.** The `max_n = 64` bound limits worst-case cost, but actual figures at `n = 32`/`64` should be measured before either is used in a real deployment.
- **No on-chain entry point yet.** This module covers the cryptographic core; how a validator obtains and trusts a given `V` (datum/redeemer wiring) is separate, follow-on work.
- **No external cryptographic audit.** This implementation has had internal design review and one external review pass; neither is a substitute for a formal audit before any mainnet or high-value use.
- **The deterministic prover is a test fixture, not a production prover.** Aiken has no RNG, so `generate_proof` requires the caller to supply every blinding factor; `generate_proof_deterministic` exists only to make self-contained tests possible and is documented as such. A production integration must source genuine entropy for these values itself.
- **`commit_value` reduces the value mod `r`**, so a commitment to `v + k·r`, including a negative amount, matches a valid proof for `v` ([#16](https://github.com/ADAOcommunity/zk/issues/16)). Callers must check the committed value's range themselves until this is fixed.
- **`verify` trusts the generator vectors in the key it's given** ([#17](https://github.com/ADAOcommunity/zk/issues/17)); a validator must fix the key rather than accept one from a redeemer.
- **The deterministic prover is a test fixture, not a production prover.** Aiken has no RNG, so `generate_proof` requires the caller to supply every blinding factor; `generate_proof_deterministic` exists only to make self-contained tests possible and is documented as such, though it is still public ([#18](https://github.com/ADAOcommunity/zk/issues/18)). A production integration must source genuine entropy for these values itself.

## 9. Conclusion

Expand Down
10 changes: 6 additions & 4 deletions zkp/docs/groth16-implementation-report.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
- **Module:** `zkp/lib/groth/groth.ak`
- **Status:** Functional, tested, unaudited
- **Test results:**
- `aiken check` 3/3 (part of 37/37 across the package)
- `aiken check` 3/3 in `tests/groth_tests`, plus 6/6 property and known-issue tests in `tests/groth_props` (part of 64/64 across the package)
- `aiken fmt` clean
- `aiken build` succeeds

Expand Down Expand Up @@ -72,21 +72,23 @@ Because decompression goes through the native builtins, every `G1Element`/`G2Ele

## 7. Testing and verification

Three tests exercise this module, alongside the Bulletproofs and PLONK suites in the same package:
Three unit tests in `tests/groth_tests.ak` exercise this module against external fixtures:

| Test | Verifies |
|---|---|
| `groth_verify_pass_1` | A genuine proof against a 2-public-input circuit verifies |
| `groth_verify_fail_1` | A proof with `A` and `C` swapped is rejected (`test ... fail`) |
| `groth_verify_pass_2` | A second genuine proof, different public inputs, same verification key, verifies |

All three tests measure identically: ~66.9K memory units and ~2.79B CPU units per `verify_compressed` call - comfortably inside Cardano's per-transaction execution budget, and the cheapest of this package's three verifiers by a wide margin, as expected given Groth16's constant-size, pairing-only verification equation.
`tests/groth_props.ak` adds property-based tests (using `aiken-lang/fuzz`, 100 random cases each). `prop_*` tests state behaviour that must hold for any input. `known_issue_*` tests pin a filed bug: they pass while the bug exists and fail once it's fixed, at which point they're replaced by the property named in their comment. Its properties: changing any public input to another value in `[0, r)` is rejected; replacing any of `A`, `B` or `C` with an unrelated valid curve point is rejected; and too few public inputs fail. Its known-issue tests cover [#11](https://github.com/ADAOcommunity/zk/issues/11) (extra inputs) and [#12](https://github.com/ADAOcommunity/zk/issues/12) (inputs not range-checked).

All three unit tests measure identically: ~66.9K memory units and ~2.79B CPU units per `verify_compressed` call - comfortably inside Cardano's per-transaction execution budget, and the cheapest of this package's three verifiers by a wide margin, as expected given Groth16's constant-size, pairing-only verification equation.

## 8. Known limitations and roadmap

- **No trusted-setup tooling.** This module consumes a `VerifierKey` but has no way to generate or attest to one; that must come from an external, circuit-specific ceremony this package neither runs nor audits.
- **No on-chain prover, by design (§5).** Proof generation is out of scope; a production integration needs its own off-chain Groth16 prover (e.g. `snarkjs`, `arkworks`, or a `gnark` toolchain) feeding this verifier.
- **`derive`'s length-mismatch handling is asymmetric.** Too few public inputs traps (safe); too many are silently truncated rather than rejected (also safe today, but worth tightening to an explicit length check before this function is exposed to less-trusted callers).
- **Public inputs aren't fully validated.** Too few public inputs traps, but extra inputs beyond `vkIC` are ignored ([#11](https://github.com/ADAOcommunity/zk/issues/11)), and inputs aren't checked to lie in `[0, r)`, so `x` and `x + r` verify with the same proof ([#12](https://github.com/ADAOcommunity/zk/issues/12)). A validator that reads inputs by position or value can be given values the proof doesn't bind. Both are pinned by `known_issue_*` tests in `tests/groth_props.ak`.
- **Only two verification-key shapes have been exercised in tests**, both with `n_public = 2`. Larger `vkIC` vectors (more public inputs) are structurally supported by `derive`'s recursion but are unbenchmarked for execution-unit cost.
- **No on-chain entry point yet.** Like the other two modules in this package, how a validator obtains and trusts a given `VerifierKey`/proof pair (datum/redeemer wiring) is separate, follow-on work.
- **No external cryptographic audit.** As with the rest of this package, internal design review only; not a substitute for a formal audit before mainnet or high-value use.
Expand Down
Loading