From bb9b454cbe885d7f0d7f05015b741b89a23853ff Mon Sep 17 00:00:00 2001 From: samdelaney Date: Wed, 11 Nov 2026 09:23:40 -0800 Subject: [PATCH 1/4] Add property-based tests with aiken-lang/fuzz Adds aiken-lang/fuzz v2.2.0 (v3 needs stdlib v4) and four test modules: - groth_props, plonk_props: changed public inputs, replaced or tampered proof elements are rejected. - point_props: g1_affine_compress matches blst's encoding for random points. - bullet_props: valid range proofs verify for any in-range value, blinding and seed; other values and tampered proofs are rejected. known_issue_* tests pin #11, #12, #14, #15 and #16: they pass because the bug exists, so each fix turns one red and it should then be replaced by the property named in its comment. Co-Authored-By: Claude Opus 5.5 --- zkp/aiken.lock | 11 +++ zkp/aiken.toml | 5 ++ zkp/lib/tests/bullet_props.ak | 108 +++++++++++++++++++++++++++ zkp/lib/tests/groth_props.ak | 136 ++++++++++++++++++++++++++++++++++ zkp/lib/tests/plonk_props.ak | 112 ++++++++++++++++++++++++++++ zkp/lib/tests/point_props.ak | 101 +++++++++++++++++++++++++ 6 files changed, 473 insertions(+) create mode 100644 zkp/lib/tests/bullet_props.ak create mode 100644 zkp/lib/tests/groth_props.ak create mode 100644 zkp/lib/tests/plonk_props.ak create mode 100644 zkp/lib/tests/point_props.ak diff --git a/zkp/aiken.lock b/zkp/aiken.lock index 37b9b2e..cd7b3f8 100644 --- a/zkp/aiken.lock +++ b/zkp/aiken.lock @@ -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] diff --git a/zkp/aiken.toml b/zkp/aiken.toml index d7cf62b..5aa7ab3 100644 --- a/zkp/aiken.toml +++ b/zkp/aiken.toml @@ -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] diff --git a/zkp/lib/tests/bullet_props.ak b/zkp/lib/tests/bullet_props.ak new file mode 100644 index 0000000..fa60b1f --- /dev/null +++ b/zkp/lib/tests/bullet_props.ak @@ -0,0 +1,108 @@ +//// Property-based tests for the Bulletproofs range-proof verifier, at +//// n = 8 (values in [0, 256)). See `tests/groth_props` for what the `prop_*` +//// and `known_issue_*` prefixes mean. + +use aiken/crypto/bls12_381/scalar.{field_prime} +use aiken/fuzz +use bullet/bullet.{ + BulletproofProof, BulletproofVerificationKey, commit_value, + generate_proof_deterministic, setup, verify, +} +use tests/groth_props.{nonzero_scalar} + +const n: Int = 8 + +/// An in-range value, a commitment blinding, and a prover seed. +fn statement() -> Fuzzer<(Int, Int, ByteArray)> { + fuzz.tuple3( + fuzz.int_between(0, 255), + nonzero_scalar(), + fuzz.bytearray_between(0, 32), + ) +} + +/// The key, a proof for `value`, and the matching commitment. +fn prove( + value: Int, + gamma: Int, + seed: ByteArray, +) -> (BulletproofVerificationKey, BulletproofProof, G1Element) { + let vk = setup(n) + let g = scalar.from_int(gamma) + ( + vk, + generate_proof_deterministic(vk, value, g, seed), + commit_value(vk, value, g), + ) +} + +// --------------------------------------------------------------------------- +// Properties +// --------------------------------------------------------------------------- + +/// Every value in [0, 2^n) can be proven, with any blinding and seed. +test prop_bullet_valid_proof_verifies((value, gamma, seed) via statement()) { + let (vk, proof, commitment) = prove(value, gamma, seed) + verify(vk, commitment, proof) +} + +/// A proof for one value doesn't verify against a commitment to another value +/// (mod r) with the same blinding. +test prop_bullet_rejects_other_value( + ((value, gamma, seed), delta) via fuzz.tuple(statement(), nonzero_scalar()), +) { + let (vk, proof, _) = prove(value, gamma, seed) + let other = + commit_value(vk, ( value + delta ) % field_prime, scalar.from_int(gamma)) + !verify(vk, other, proof) +} + +/// Changing `tau_x`, `mu` or the first entry of `l_vec` or `r_vec` breaks the +/// proof. +test prop_bullet_rejects_tampered_proof( + ((value, gamma, seed), which, delta) via fuzz.tuple3( + statement(), + fuzz.int_between(0, 3), + nonzero_scalar(), + ), +) { + let (vk, proof, commitment) = prove(value, gamma, seed) + let d = scalar.from_int(delta) + let bump_head = + fn(xs) { + when xs is { + [x, ..rest] -> [scalar.add(x, d), ..rest] + [] -> fail @"empty vector" + } + } + let tampered = + when which is { + 0 -> BulletproofProof { ..proof, tau_x: scalar.add(proof.tau_x, d) } + 1 -> BulletproofProof { ..proof, mu: scalar.add(proof.mu, d) } + 2 -> BulletproofProof { ..proof, l_vec: bump_head(proof.l_vec) } + _ -> BulletproofProof { ..proof, r_vec: bump_head(proof.r_vec) } + } + !verify(vk, commitment, tampered) +} + +// --------------------------------------------------------------------------- +// Known issues +// --------------------------------------------------------------------------- + +/// ADAOcommunity/zk#16: `commit_value` reduces mod r, so a commitment built +/// from `value + k * r` (including negative k, i.e. a negative amount) matches +/// the proof for `value`. Once fixed, replace with +/// `prop_bullet_commit_value_rejects_out_of_field` (the same call must fail). +test known_issue_16_bullet_commit_value_reduces_mod_r( + ((value, gamma, seed), k) via fuzz.tuple( + statement(), + fuzz.either(fuzz.int_between(-1000, -1), fuzz.int_between(1, 1000)), + ), +) { + let (vk, proof, _) = prove(value, gamma, seed) + verify( + vk, + commit_value(vk, value + k * field_prime, scalar.from_int(gamma)), + proof, + ) +} diff --git a/zkp/lib/tests/groth_props.ak b/zkp/lib/tests/groth_props.ak new file mode 100644 index 0000000..efa3f79 --- /dev/null +++ b/zkp/lib/tests/groth_props.ak @@ -0,0 +1,136 @@ +//// Property-based tests for the Groth16 verifier. +//// +//// `prop_*` tests state behaviour the verifier must keep. `known_issue_*` +//// tests pin down a filed bug: they pass today *because* the bug exists, so +//// fixing the issue makes them fail. When that happens, replace the test with +//// the property named in its comment. + +use aiken/builtin +use aiken/collection/list +use aiken/crypto/bls12_381/g1 +use aiken/crypto/bls12_381/g2 +use aiken/crypto/bls12_381/scalar.{field_prime} +use aiken/fuzz +use groth/groth.{CompressedProof, CompressedVK, verify_compressed} + +/// Same fixture as `groth_verify_pass_1`: a proof valid for `[561, 3]`. +pub const groth_vk: CompressedVK = + CompressedVK { + alpha: #"8e3d9e248feda194cb6fa0a3b64fd2a380cb5e94836bf8148bf97ebcbb5819d9a78f63102f0293c104bcbb2f810d8eb4", + beta: #"8cd68a7186a908212680a0234d8210c20328f8fb3ce1d69c9aec9330a5802d6cfaf6d7cf3176133221c19188590cb4141874ea7bbfcb9872931e115d882c46b90c3dcbcee10062d1c9b9b0a691d7bec7d2735f06495c7f71dea210e55b2782df", + gamma: #"93e02b6052719f607dacd3a088274f65596bd0d09920b61ab5da61bbdc7f5049334cf11213945d57e5ac7d055d042b7e024aa2b2f08f0a91260805272dc51051c6e47ad4fa403b02b4510b647ae3d1770bac0326a805bbefd48056c8c121bdb8", + delta: #"938231fcec443fbdeb1079ff126b8f69bd8579ffe82d39923214d4345395beee60200288fa20c97ae50f3212131b6f8802af2f9f515c65af6a9a6c294c738590104376a0af44731d6699db6a286608774243f7d1dddc4605eb340e65e15060a5", + vkIC: [ + #"b5813c90d3455acb8608fdf66e8601f24ef048f3fdf9384862d77c72cb5cddfde2b307976b1b0319c42ba985f94be60a", + #"a41a0e6370c054be0f9acce08e97f6d5702d9daa9e9a934e8a377f553593baa1c58062adc73d63558653422d54d6f50c", + #"8e02a87c519c3145f984d25fdf769f74fbc36626c385d4554fb4bc1d7a12cbf669d40f257023b8b3c9a31e631aa8f981", + ], + } + +pub const groth_proof: CompressedProof = + CompressedProof { + a: #"8b84d092731c653b1accdda79c51e3f5d289bed7311189d927deadef0470e437e6d1d400634726512a79a015867424e3", + b: #"92cb1c125816e4b522c7f430a5d74a61116b6189de7b2341f040194c02f10d9ef0cf081f4029444a65ea74e69d98b1cf08d3864087d5d2dee2ed6ab102f9b78e65d341f0824341a9fc25d0ea9dacccc5d355b4eddb0057949370a19c47135b0e", + c: #"a4ef633c858a3ff194db50eacdf715f7296fb3d1202c54b543284e9656b69aa90f33ac0e2572d3ab847b88268dcd1f7e", + } + +pub const groth_inputs: List = [561, 3] + +/// A uniformly random non-zero scalar in `[1, r)`. +pub fn nonzero_scalar() -> Fuzzer { + fuzz.int_between(1, field_prime - 1) +} + +/// Replace the element at `index` with `f(element)`. +pub fn update_at(xs: List, index: Int, f: fn(Int) -> Int) -> List { + list.indexed_map( + xs, + fn(j, x) { + if j == index { + f(x) + } else { + x + } + }, + ) +} + +// --------------------------------------------------------------------------- +// Properties +// --------------------------------------------------------------------------- + +/// Moving any public input to a different value in `[0, r)` must break the +/// proof. +test prop_groth_rejects_changed_input( + (index, delta) via fuzz.tuple(fuzz.int_between(0, 1), nonzero_scalar()), +) { + let inputs = + update_at(groth_inputs, index, fn(x) { ( x + delta ) % field_prime }) + !verify_compressed(groth_vk, groth_proof, inputs) +} + +/// Replacing one proof element with an unrelated valid curve point must break +/// the proof. (`k` hitting the real discrete log has probability ~2^-255.) +test prop_groth_rejects_replaced_proof_point( + (which, k) via fuzz.tuple(fuzz.int_between(0, 2), nonzero_scalar()), +) { + let s = scalar.from_int(k) + let proof = + if which == 0 { + CompressedProof { + ..groth_proof, + a: g1.compress(g1.scale(g1.generator, s)), + } + } else if which == 1 { + CompressedProof { + ..groth_proof, + b: g2.compress(g2.scale(g2.generator, s)), + } + } else { + CompressedProof { + ..groth_proof, + c: g1.compress(g1.scale(g1.generator, s)), + } + } + !verify_compressed(groth_vk, proof, groth_inputs) +} + +/// Fewer inputs than the key expects must fail. +test groth_rejects_missing_input() fail { + verify_compressed(groth_vk, groth_proof, [561]) +} + +// --------------------------------------------------------------------------- +// Known issues +// --------------------------------------------------------------------------- + +/// ADAOcommunity/zk#11: inputs past the end of `vkIC` are ignored. +/// Once fixed, replace with `prop_groth_rejects_extra_inputs` (the same call +/// must fail). +test known_issue_11_groth_extra_inputs_ignored( + extra via fuzz.list_between(fuzz.int(), 1, 5), +) { + verify_compressed(groth_vk, groth_proof, list.concat(groth_inputs, extra)) +} + +/// ADAOcommunity/zk#12: an input of `x + k * r` verifies like `x`. +/// Once fixed, replace with `prop_groth_rejects_input_out_of_field` (the same +/// call must fail). +test known_issue_12_groth_input_not_range_checked( + (index, k) via fuzz.tuple(fuzz.int_between(0, 1), fuzz.int_between(1, 1000)), +) { + let inputs = update_at(groth_inputs, index, fn(x) { x + k * field_prime }) + verify_compressed(groth_vk, groth_proof, inputs) +} + +/// Sanity check that the builtin really reduces mod `r`, which is what makes +/// #12 possible. Unlike the test above, this one should keep passing after #12 +/// is fixed, since the fix belongs in the verifier. +test prop_g1_scalar_mul_reduces_mod_r( + (x, k) via fuzz.tuple(fuzz.int_between(0, 10000), fuzz.int_between(1, 1000)), +) { + builtin.bls12_381_g1_scalar_mul(x + k * field_prime, g1.generator) == builtin.bls12_381_g1_scalar_mul( + x, + g1.generator, + ) +} diff --git a/zkp/lib/tests/plonk_props.ak b/zkp/lib/tests/plonk_props.ak new file mode 100644 index 0000000..613e078 --- /dev/null +++ b/zkp/lib/tests/plonk_props.ak @@ -0,0 +1,112 @@ +//// Property-based tests for the PLONK verifier, on the affine fixture valid +//// for `[63, 7]` (`tests/plonk_tests`). See `tests/groth_props` for what the +//// `prop_*` and `known_issue_*` prefixes mean. + +use aiken/collection/list +use aiken/crypto/bls12_381/scalar.{field_prime} +use aiken/fuzz +use plonk/proofs.{PreparedPlonkProof, plonk_prepare_proof} +use plonk/raw_affine.{AffineProof, prepare_affine_proof, prepare_affine_vkey} +use plonk/verifier.{verify_plonk} +use tests/groth_props.{nonzero_scalar, update_at} +use tests/plonk_tests.{ + test_plonk_proof_affine, test_plonk_pub_inputs, test_plonk_vkey_affine, +} + +/// Prepare and verify, the way an on-chain caller would. +pub fn plonk_verifies(proof: AffineProof, pub_inputs: List) -> Bool { + let preinputs = prepare_affine_vkey(test_plonk_vkey_affine) + let prepared = + plonk_prepare_proof(preinputs, pub_inputs, prepare_affine_proof(proof)) + verify_plonk(preinputs: preinputs, pub_inputs: pub_inputs, proof: prepared) +} + +/// Add `delta` (mod r) to one of the six evaluation scalars. +fn tamper_eval(proof: AffineProof, which: Int, delta: Int) -> AffineProof { + let bump = + fn(x) { ( x + delta ) % field_prime } + when which is { + 0 -> AffineProof { ..proof, a_eval: bump(proof.a_eval) } + 1 -> AffineProof { ..proof, b_eval: bump(proof.b_eval) } + 2 -> AffineProof { ..proof, c_eval: bump(proof.c_eval) } + 3 -> AffineProof { ..proof, s_sig1_p: bump(proof.s_sig1_p) } + 4 -> AffineProof { ..proof, s_sig2_p: bump(proof.s_sig2_p) } + _ -> AffineProof { ..proof, z_omega: bump(proof.z_omega) } + } +} + +// --------------------------------------------------------------------------- +// Properties +// --------------------------------------------------------------------------- + +/// Moving any public input to a different value in `[0, r)` must break the +/// proof. +test prop_plonk_rejects_changed_input( + (index, delta) via fuzz.tuple(fuzz.int_between(0, 1), nonzero_scalar()), +) { + let inputs = + update_at( + test_plonk_pub_inputs, + index, + fn(x) { ( x + delta ) % field_prime }, + ) + !plonk_verifies(test_plonk_proof_affine, inputs) +} + +/// Changing any evaluation scalar in the proof must break it. +test prop_plonk_rejects_tampered_evaluation( + (which, delta) via fuzz.tuple(fuzz.int_between(0, 5), nonzero_scalar()), +) { + !plonk_verifies( + tamper_eval(test_plonk_proof_affine, which, delta), + test_plonk_pub_inputs, + ) +} + +// --------------------------------------------------------------------------- +// Known issues +// --------------------------------------------------------------------------- + +/// ADAOcommunity/zk#12: an input of `x + k * r` verifies like `x`. +/// Once fixed, replace with `prop_plonk_rejects_input_out_of_field` (the same +/// call must fail). +test known_issue_12_plonk_input_not_range_checked( + (index, k) via fuzz.tuple(fuzz.int_between(0, 1), fuzz.int_between(1, 1000)), +) { + let inputs = + update_at(test_plonk_pub_inputs, index, fn(x) { x + k * field_prime }) + plonk_verifies(test_plonk_proof_affine, inputs) +} + +/// ADAOcommunity/zk#14: nothing checks the inverse list's length. Dropping the +/// last inverse (the one for the surplus generator, #19) still verifies. +/// Dropping one that belongs to a public input makes verification fail, because +/// each inverse also weights its input in the public-input polynomial; that +/// input is then hashed into the transcript but left out of the constraint, the +/// same gap as #13. Once fixed, replace with +/// `plonk_rejects_short_inverse_list` (the same call must fail). +test known_issue_14_plonk_inverse_list_length_unchecked() { + let preinputs = prepare_affine_vkey(test_plonk_vkey_affine) + let prepared = + plonk_prepare_proof( + preinputs, + test_plonk_pub_inputs, + prepare_affine_proof(test_plonk_proof_affine), + ) + let short = + PreparedPlonkProof { + ..prepared, + lagrange_inverses: list.take( + prepared.lagrange_inverses, + list.length(test_plonk_pub_inputs), + ), + } + and { + list.length(short.lagrange_inverses) < list.length(preinputs.generators), + verify_plonk( + preinputs: preinputs, + pub_inputs: test_plonk_pub_inputs, + proof: short, + ), + } +} diff --git a/zkp/lib/tests/point_props.ak b/zkp/lib/tests/point_props.ak new file mode 100644 index 0000000..586491b --- /dev/null +++ b/zkp/lib/tests/point_props.ak @@ -0,0 +1,101 @@ +//// Property-based tests for the affine point compression in +//// `common/blst_affine`, checked against the BLS builtins. See +//// `tests/groth_props` for what the `prop_*` and `known_issue_*` prefixes mean. + +use aiken/crypto/bls12_381/g1 +use aiken/crypto/bls12_381/scalar +use aiken/fuzz +use aiken/primitive/bytearray +use common/blst_affine.{G1Affine, G1Point, g1_affine_compress, g1_on_curve} +use common/common.{bls12_381_base_prime, bls12_381_half_prime} +use tests/groth_props.{nonzero_scalar} + +/// `b^e mod m` by square-and-multiply. +fn mod_pow(b: Int, e: Int, m: Int) -> Int { + if e == 0 { + 1 + } else { + let half = mod_pow(b, e / 2, m) + let sq = half * half % m + if e % 2 == 1 { + sq * b % m + } else { + sq + } + } +} + +/// The affine coordinates of `k * G`, recovered from blst's compressed bytes: +/// clear the three flag bits to get x, then solve y^2 = x^3 + 4 (p = 3 mod 4, +/// so a square root is a power of (p + 1) / 4) and pick the root the sort bit +/// names. Returns the point, the other root's point, and blst's bytes. +fn affine_of(k: Int) -> (G1Affine, G1Affine, ByteArray) { + let p = bls12_381_base_prime + let compressed = g1.compress(g1.scale(g1.generator, scalar.from_int(k))) + let first = bytearray.at(compressed, 0) + let x_bytes = bytearray.push(bytearray.drop(compressed, 1), first % 32) + let x = bytearray.to_int_big_endian(x_bytes) + let root = mod_pow(( x * x * x + 4 ) % p, ( p + 1 ) / 4, p) + let sort_bit_set = first / 32 % 2 == 1 + let (y, other) = + if root > bls12_381_half_prime == sort_bit_set { + (root, p - root) + } else { + (p - root, root) + } + let to48 = + fn(n) { bytearray.from_int_big_endian(n, 48) } + ( + G1Point { x: x_bytes, y: to48(y) }, + G1Point { x: x_bytes, y: to48(other) }, + compressed, + ) +} + +// --------------------------------------------------------------------------- +// Properties +// --------------------------------------------------------------------------- + +/// For any point, `g1_affine_compress` gives exactly blst's encoding, the +/// recovered point is on the curve, and the other square root encodes +/// differently. +test prop_g1_affine_compress_matches_blst(k via nonzero_scalar()) { + let (point, other, compressed) = affine_of(k) + and { + g1_on_curve(point), + g1_affine_compress(point) == compressed, + g1_affine_compress(other) != compressed, + g1.decompress(g1_affine_compress(point)) == g1.scale( + g1.generator, + scalar.from_int(k), + ), + } +} + +// --------------------------------------------------------------------------- +// Known issues +// --------------------------------------------------------------------------- + +/// ADAOcommunity/zk#15: `y` only contributes its sign, so any `y` on the same +/// side of (p - 1) / 2 compresses to the same bytes, even one that isn't on the +/// curve. Once fixed, replace with `prop_g1_affine_compress_rejects_wrong_y` +/// (the same call must fail). +test known_issue_15_g1_affine_compress_ignores_y( + (k, r) via fuzz.tuple( + nonzero_scalar(), + fuzz.int_between(1, bls12_381_half_prime), + ), +) { + expect (G1Point { x, y }, _, compressed) = affine_of(k) + let y_int = bytearray.to_int_big_endian(y) + // A different y on the same side of the half-way point. + let fake = + if y_int > bls12_381_half_prime { + bls12_381_half_prime + r + } else { + r - 1 + } + fake == y_int || g1_affine_compress( + G1Point { x, y: bytearray.from_int_big_endian(fake, 48) }, + ) == compressed +} From 9d66917c6e114d5ba0abdd553ebfb2b4d5639cc1 Mon Sep 17 00:00:00 2001 From: samdelaney Date: Wed, 11 Nov 2026 11:35:56 -0800 Subject: [PATCH 2/4] Retire raw.ak and test the common.ak helpers the verifiers use raw.ak had no callers, and its projective fixtures in plonk_tests were not used by any test, so both are removed. The PLONK implementation report recommended revalidating or retiring it; it now has a dated note. The verifiers use five definitions from common.ak: the two BLS12-381 constants, concat_and_keccak_256, scalar_sum and g1_sum. The new tests/common_tests.ak covers them with 8 unit and 3 property tests: p against the spec value, (p - 1) / 2, p = 3 mod 4, the G1 generator on the curve, Keccak (not SHA3) of the empty input, join order, split invariance, and both sums against integer arithmetic. 64 tests pass with aiken check -D; fmt and build are clean. Co-Authored-By: Claude Opus 5.5 --- zkp/docs/plonk-implementation-report.md | 4 +- zkp/lib/plonk/raw.ak | 87 ----------------- zkp/lib/tests/common_tests.ak | 122 ++++++++++++++++++++++++ zkp/lib/tests/plonk_tests.ak | 113 ---------------------- 4 files changed, 125 insertions(+), 201 deletions(-) delete mode 100644 zkp/lib/plonk/raw.ak create mode 100644 zkp/lib/tests/common_tests.ak diff --git a/zkp/docs/plonk-implementation-report.md b/zkp/docs/plonk-implementation-report.md index cc66191..5be259b 100644 --- a/zkp/docs/plonk-implementation-report.md +++ b/zkp/docs/plonk-implementation-report.md @@ -7,6 +7,8 @@ - `aiken fmt` clean - `aiken build` succeeds +> **Update, 2026-11:** `raw.ak` has been removed, following the recommendation in §8. Nothing in the package called it, and its projective test vectors weren't used by any test. Use `raw_affine.ak` or compressed bytes. The rest of this report describes the module as it was when written. + ## 1. Overview This module implements a PLONK zk-SNARK verifier over the BLS12-381 curve, as one of three zero-knowledge proof systems in this repository's `zkp` package for Cardano smart contracts (Aiken, targeting Plutus V3). Given a universal-but-still-trusted verification key, a proof, and a list of public inputs, it checks the standard PLONK gate/permutation/quotient identity via a batched KZG opening, using a Keccak-256 Fiat–Shamir transcript matching the `snarkjs`-style compressed-commitment variant of the protocol. @@ -102,7 +104,7 @@ Twelve tests in `tests/plonk_tests.ak` exercise this module directly, against a - **No trusted-setup tooling.** This module consumes `x2` (and the rest of the verification key) but has no way to generate or attest to a universal SRS; that must come from an external ceremony (e.g. Perpetual Powers of Tau plus a circuit-specific phase 2) this package neither runs nor audits. - **No on-chain prover, by design (§5).** Proof generation, circuit compilation, and preprocessing are all out of scope; a production integration needs its own off-chain PLONK toolchain feeding this verifier. -- **`raw.ak`'s legacy compression path carries more risk than `raw_affine.ak`'s (§5).** New integrations should prefer `raw_affine.ak` or pre-compressed bytes; `raw.ak` should be revalidated against `common.ak`'s field-arithmetic correctness, or retired, before further use. +- **`raw.ak`'s legacy compression path carries more risk than `raw_affine.ak`'s (§5).** New integrations should prefer `raw_affine.ak` or pre-compressed bytes; `raw.ak` should be revalidated against `common.ak`'s field-arithmetic correctness, or retired, before further use. *(Retired 2026-11.)* - **Execution-unit cost is only measured at `n_public = 2`.** This is the most expensive verifier in the package per call already; larger public-input counts should be benchmarked before use in a real deployment. - **No on-chain entry point yet.** Like the other two modules in this package, how a validator obtains and trusts a given verification key/proof pair (datum/redeemer wiring) is separate, follow-on work. - **No cross-implementation interoperability testing beyond one fixture.** The transcript and batching scheme are documented as matching a `snarkjs`-style variant, but only one externally-produced proof has been used to validate that against this implementation; broader test vectors are future work. diff --git a/zkp/lib/plonk/raw.ak b/zkp/lib/plonk/raw.ak deleted file mode 100644 index 94bd47b..0000000 --- a/zkp/lib/plonk/raw.ak +++ /dev/null @@ -1,87 +0,0 @@ -use aiken/crypto/bls12_381/scalar -use common/common.{G1Point, G2Point, g1_compress, g2_compress} -use plonk/preinputs.{ - PlonkPreInputs, PreparedPlonkPreInputs, plonk_prepare_preinputs, -} -use plonk/proofs.{PlonkProof} - -pub type PlonkVerificationKey { - n_public: Int, - power: Int, - k1: Int, - k2: Int, - q_m: G1Point, - q_l: G1Point, - q_r: G1Point, - q_o: G1Point, - q_c: G1Point, - s_sig1: G1Point, - s_sig2: G1Point, - s_sig3: G1Point, - x2: G2Point, - w: Int, -} - -pub type RawPlonkProof { - commitment_a: G1Point, - commitment_b: G1Point, - commitment_c: G1Point, - commitment_z: G1Point, - t_low: G1Point, - t_mid: G1Point, - t_high: G1Point, - w_omega: G1Point, - w_omega_zeta: G1Point, - a_eval: Int, - b_eval: Int, - c_eval: Int, - s_sig1_p: Int, - s_sig2_p: Int, - z_omega: Int, -} - -pub fn vkey_to_prepared_preinputs( - vkey: PlonkVerificationKey, -) -> PreparedPlonkPreInputs { - let preinputs = - PlonkPreInputs { - power: vkey.power, - k1: scalar.from_int(vkey.k1), - k2: scalar.from_int(vkey.k2), - q_m: g1_compress(vkey.q_m), - q_l: g1_compress(vkey.q_l), - q_r: g1_compress(vkey.q_r), - q_o: g1_compress(vkey.q_o), - q_c: g1_compress(vkey.q_c), - s_sig1: g1_compress(vkey.s_sig1), - s_sig2: g1_compress(vkey.s_sig2), - s_sig3: g1_compress(vkey.s_sig3), - x2: g2_compress(vkey.x2), - } - - plonk_prepare_preinputs( - inputs: preinputs, - generator: scalar.from_int(vkey.w), - n_public: vkey.n_public, - ) -} - -pub fn prepare_raw_proof(proof: RawPlonkProof) -> PlonkProof { - PlonkProof { - commitment_a: g1_compress(proof.commitment_a), - commitment_b: g1_compress(proof.commitment_b), - commitment_c: g1_compress(proof.commitment_c), - commitment_z: g1_compress(proof.commitment_z), - t_low: g1_compress(proof.t_low), - t_mid: g1_compress(proof.t_mid), - t_high: g1_compress(proof.t_high), - w_omega: g1_compress(proof.w_omega), - w_omega_zeta: g1_compress(proof.w_omega_zeta), - a_eval: proof.a_eval, - b_eval: proof.b_eval, - c_eval: proof.c_eval, - s_sig1_p: proof.s_sig1_p, - s_sig2_p: proof.s_sig2_p, - z_omega: proof.z_omega, - } -} diff --git a/zkp/lib/tests/common_tests.ak b/zkp/lib/tests/common_tests.ak new file mode 100644 index 0000000..d70390b --- /dev/null +++ b/zkp/lib/tests/common_tests.ak @@ -0,0 +1,122 @@ +//// Unit and property tests for the parts of `common/common` that the +//// verifiers depend on: the two BLS12-381 constants (used by `blst_affine`), +//// `concat_and_keccak_256` (the PLONK transcript), and `scalar_sum` and +//// `g1_sum` (the PLONK verifier's sums). The rest of `common/common` is legacy +//// code that no verifier calls; see the implementation reports. + +use aiken/collection/list +use aiken/crypto +use aiken/crypto/bls12_381/g1 +use aiken/crypto/bls12_381/scalar.{field_prime} +use aiken/fuzz +use aiken/primitive/bytearray +use common/common.{ + bls12_381_base_prime, bls12_381_half_prime, concat_and_keccak_256, g1_sum, + scalar_sum, +} +use tests/groth_props.{nonzero_scalar} + +// --------------------------------------------------------------------------- +// Constants +// --------------------------------------------------------------------------- + +/// p as published in the BLS12-381 specification. +test common_base_prime_matches_spec() { + bls12_381_base_prime == bytearray.to_int_big_endian( + #"1a0111ea397fe69a4b1ba7b6434bacd764774b84f38512bf6730d2a0f6b0f6241eabfffeb153ffffb9feffffffffaaab", + ) +} + +test common_half_prime_is_half() { + bls12_381_half_prime == ( bls12_381_base_prime - 1 ) / 2 +} + +/// The square root in `tests/point_props` relies on p = 3 mod 4. +test common_base_prime_is_3_mod_4() { + bls12_381_base_prime % 4 == 3 +} + +/// The standard G1 generator satisfies y^2 = x^3 + 4 mod p, and its x matches +/// the builtin generator's compressed bytes. +test common_base_prime_fits_g1_generator() { + let p = bls12_381_base_prime + let x = + bytearray.to_int_big_endian( + #"17f1d3a73197d7942695638c4fa9ac0fc3688c4f9774b905a14e3a3f171bac586c55e83ff97a1aeffb3af00adb22c6bb", + ) + let y = + bytearray.to_int_big_endian( + #"08b3f481e3aaa0f1a09e30ed741d8ae4fcf5e095d5d00af600db18cb2c04b3edd03cc744a2888ae40caa232946c5e7e1", + ) + let compressed = g1.compress(g1.generator) + let first = bytearray.at(compressed, 0) + and { + y * y % p == ( x * x * x + 4 ) % p, + bytearray.to_int_big_endian( + bytearray.push(bytearray.drop(compressed, 1), first % 32), + ) == x, + } +} + +// --------------------------------------------------------------------------- +// concat_and_keccak_256 +// --------------------------------------------------------------------------- + +/// Keccak-256, not SHA3-256, of the empty string. +test common_keccak_empty_list() { + concat_and_keccak_256([]) == #"c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470" +} + +/// Pieces are joined in order. +test common_keccak_joins_in_order() { + and { + concat_and_keccak_256([#"01", #"0203"]) == crypto.keccak_256(#"010203"), + concat_and_keccak_256([#"0203", #"01"]) == crypto.keccak_256(#"020301"), + } +} + +/// Where the input is split doesn't change the hash. +test prop_common_keccak_ignores_split( + (bytes, cut) via fuzz.tuple( + fuzz.bytearray_between(0, 64), + fuzz.int_between(0, 64), + ), +) { + concat_and_keccak_256( + [bytearray.take(bytes, cut), #"", bytearray.drop(bytes, cut)], + ) == crypto.keccak_256(bytes) +} + +// --------------------------------------------------------------------------- +// scalar_sum and g1_sum +// --------------------------------------------------------------------------- + +test common_scalar_sum_empty_is_zero() { + scalar_sum([]) == scalar.from_int(0) +} + +/// Summing scalars matches summing the integers mod r. +test prop_common_scalar_sum_matches_int_sum( + xs via fuzz.list_between(nonzero_scalar(), 0, 8), +) { + scalar_sum(list.map(xs, scalar.from_int)) == scalar.from_int( + list.foldl(xs, 0, fn(x, acc) { acc + x }) % field_prime, + ) +} + +test common_g1_sum_empty_is_zero() { + g1_sum([]) == g1.zero +} + +fn times_g(k: Int) -> G1Element { + g1.scale(g1.generator, scalar.from_int(k)) +} + +/// The sum of k_i * G is (sum of k_i) * G. +test prop_common_g1_sum_matches_scalar_sum( + ks via fuzz.list_between(nonzero_scalar(), 1, 4), +) { + g1_sum(list.map(ks, times_g)) == times_g( + list.foldl(ks, 0, fn(k, acc) { acc + k }) % field_prime, + ) +} diff --git a/zkp/lib/tests/plonk_tests.ak b/zkp/lib/tests/plonk_tests.ak index 657ffc7..627ffb2 100644 --- a/zkp/lib/tests/plonk_tests.ak +++ b/zkp/lib/tests/plonk_tests.ak @@ -3,127 +3,14 @@ use aiken/crypto/bls12_381/scalar use common/blst_affine.{ G1Infinity, G1Point, G2Point, g1_affine_compress, g2_affine_compress, } -use common/common.{G2Point as RawG2Point, Point} use plonk/preinputs.{PlonkPreInputs, plonk_prepare_preinputs} use plonk/proofs.{plonk_prepare_proof} -use plonk/raw.{PlonkVerificationKey, RawPlonkProof} use plonk/raw_affine.{ AffineProof, AffineVerificationKey, prepare_affine_proof, prepare_affine_vkey, } use plonk/verifier.{verify_plonk} use tests/test_utils.{int_to_field_bytes} -// =========================================================================== -// Raw (projective) test vectors -// =========================================================================== - -pub const test_plonk_proof: RawPlonkProof = - RawPlonkProof { - commitment_a: Point { - x: 2955082493890020621983548864242801681331382761589593836396462786237809490379730083621148456292328311837539547233078, - y: 2990917470048022633751403325877110490023214940780163879068748589295894184468420861593276240916860222556041630309490, - z: 1, - }, - commitment_b: Point { - x: 2139748953192924893718111139796467598787187717809064847657431290279584919816359328113211416216965946326904372181144, - y: 2259668502813448495833083885609627801405772920489944855694509142813690380362130929482939621563275288429386208477174, - z: 1, - }, - commitment_c: Point { - x: 2029868808682428131517521841196317763678238092678415346121426692356142038272541088877792972412724621664112264945402, - y: 983551628294237524163209598922680914320460584515486665440996990611591240136708425683923303325991832470735477012116, - z: 1, - }, - commitment_z: Point { - x: 2387801164586378454252042857525161272590791672625817623997854477584013441773831593184571862621830523992226453996145, - y: 2963460115634323994397623882034777328875861522711306860138637408553554162058666092728227754125238789945570425688766, - z: 1, - }, - t_low: Point { - x: 1894516259155874795478636775854000079842047119288244714503215181482526148945291020416724440229372193886732121411353, - y: 1031154329693902984660329178103732470848052600799342617372338054649599821052286659433310234216256987572488522064742, - z: 1, - }, - t_mid: Point { - x: 396230736967861803635980419570754115302632616415474674207045272682865255719918284458879898212237757916289534540503, - y: 1286345817905833523305277948742871641051845921916399591001898962704587418794625017612994249491313890015329626321188, - z: 1, - }, - t_high: Point { - x: 1605020952126297833723226836157259589899522431634090862836060595671759262433465086466801152520962321838375613406480, - y: 3380611695801979784487178272729979547287652149847817235299237981219620495852861730756702710944277941379315901919628, - z: 1, - }, - w_omega: Point { - x: 3450797490829451101684300912559686520039512327488446737240041689856044522958259926705205991152261371334594680942229, - y: 3325733188905070684197604249400574204476897614422083280941305902591531412024682158968329032713733872654995261106522, - z: 1, - }, - w_omega_zeta: Point { - x: 863669987569139054364812933508800738931137091074775255594224713818925528334922843056187052587160290967836521340909, - y: 2166514895834521672481059065176477660352283408684189579849124753231689040068150141242374151666482477587206334178810, - z: 1, - }, - a_eval: 22757212845473628986664301092572773725843860106781649491082133699785307937133, - b_eval: 51429051849495352387445623433681097795689954214627149917980353176226473881347, - c_eval: 48242326795347271969267233696976762494320046178030976356298515157950481259823, - s_sig1_p: 49194979834930093396344655415079764564343526505778221100851639750638575027756, - s_sig2_p: 12011587759165679750727880280659232729752930325587463363828179196808481389053, - z_omega: 24019962433584515698965513494582469296076614442597410659646743422950745162859, - } - -pub const test_plonk_vkey: PlonkVerificationKey = - PlonkVerificationKey { - n_public: 2, - power: 3, - k1: 2, - k2: 3, - q_m: Point { - x: 390420818566493858367464181076148178859555478863002692514545834368269879447681841082068585551564235503308947232378, - y: 3276847779626248817921041660741117745502051773945482686666030885472398470355715064844179289766796069907281222412724, - z: 1, - }, - q_l: Point { - x: 2832459832163495150479122726264129004255627621445400446445904161463167979768458296565736026250455466004404325092996, - y: 3741891246739296148991860192122594744687151654172617277458830187550386521367405061644711803513753648977431388490950, - z: 1, - }, - q_r: Point { x: 0, y: 1, z: 0 }, - q_o: Point { - x: 390420818566493858367464181076148178859555478863002692514545834368269879447681841082068585551564235503308947232378, - y: 725561775595418575496748164994786411054831045993525198666027250651633180135122799598508339362219594130613050147063, - z: 1, - }, - q_c: Point { x: 0, y: 1, z: 0 }, - s_sig1: Point { - x: 3944485635698459932433634706365550699364147680658608621022581948882602066423214201823994363817057003852352113973102, - y: 2481473700589819128241850529786326259739363860413421083419242322439772753684327842018177309699278701645719502063011, - z: 1, - }, - s_sig2: Point { - x: 608913174169519000812264133236120028473675090457027054092233721874136995363377165138135110723165351281407038604929, - y: 2540453045645467686101782045248642180331599264159056690287844382784021393502357721825604716334062206625833942598550, - z: 1, - }, - s_sig3: Point { - x: 324514252262195321244614754390467750793932334185439650123651923691851924066772665377485916928100616166627086332426, - y: 3113468956497733006315552301280484390953024074059319036050522016086390656265116534130248224200617657987091997981033, - z: 1, - }, - x2: RawG2Point { - x: ( - 315392587371006580320359080746390447102226920810775075601256338851306698095121762912694048386654833732339420515166, - 2161957325100184324059278577028157171100154313724439672191511832751025188121569798837418082248673407995264313041542, - ), - y: ( - 3808454252163556366145098778553759832772829525954193157529438608174590910603583474173900502559366413190158202701670, - 2556911765464293729917692748672416866651619396879891492332729234344507429587256369481474563225773001582828153945765, - ), - z: (1, 0), - }, - w: 28761180743467419819834788392525162889723178799021384024940474588120723734663, - } - // =========================================================================== // Affine test vectors // =========================================================================== From 86a66121d0c3c16ceff2516ca9749f63705bae9f Mon Sep 17 00:00:00 2001 From: samdelaney Date: Wed, 11 Nov 2026 12:03:46 -0800 Subject: [PATCH 3/4] Describe the PLONK module without raw.ak and refresh test counts The PLONK implementation report now describes the module as it is: raw_affine.ak is the one point-type front door, and the raw.ak passages and limitation are gone. The README and the three implementation reports give the current test counts (64 across the package, including the property-test files); the Bulletproofs report said 13 where the module has 10. Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- zkp/docs/bulletproofs-implementation-report.md | 2 +- zkp/docs/groth16-implementation-report.md | 2 +- zkp/docs/plonk-implementation-report.md | 17 +++++++---------- 4 files changed, 10 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 2f7229c..173bf15 100644 --- a/README.md +++ b/README.md @@ -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, unit-tested, and build cleanly (`aiken check` / `aiken build`, 64/64 tests passing). 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 diff --git a/zkp/docs/bulletproofs-implementation-report.md b/zkp/docs/bulletproofs-implementation-report.md index f198030..dbcb999 100644 --- a/zkp/docs/bulletproofs-implementation-report.md +++ b/zkp/docs/bulletproofs-implementation-report.md @@ -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 diff --git a/zkp/docs/groth16-implementation-report.md b/zkp/docs/groth16-implementation-report.md index bfead38..b13d193 100644 --- a/zkp/docs/groth16-implementation-report.md +++ b/zkp/docs/groth16-implementation-report.md @@ -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 diff --git a/zkp/docs/plonk-implementation-report.md b/zkp/docs/plonk-implementation-report.md index 5be259b..e3f9dd2 100644 --- a/zkp/docs/plonk-implementation-report.md +++ b/zkp/docs/plonk-implementation-report.md @@ -1,14 +1,12 @@ # PLONK Verifier - Implementation Report -- **Module:** `zkp/lib/plonk/{preinputs,proofs,raw,raw_affine,verifier}.ak` +- **Module:** `zkp/lib/plonk/{preinputs,proofs,raw_affine,verifier}.ak` - **Status:** Functional, tested, unaudited - **Test results:** - - `aiken check` 12/12 in `tests/plonk_tests`, plus 12/12 in the closely-related `tests/point_tests` (part of 37/37 across the package) + - `aiken check` 12/12 in `tests/plonk_tests`, 4/4 in `tests/plonk_props`, plus 12/12 in the closely-related `tests/point_tests` and 2/2 in `tests/point_props` (part of 64/64 across the package) - `aiken fmt` clean - `aiken build` succeeds -> **Update, 2026-11:** `raw.ak` has been removed, following the recommendation in §8. Nothing in the package called it, and its projective test vectors weren't used by any test. Use `raw_affine.ak` or compressed bytes. The rest of this report describes the module as it was when written. - ## 1. Overview This module implements a PLONK zk-SNARK verifier over the BLS12-381 curve, as one of three zero-knowledge proof systems in this repository's `zkp` package for Cardano smart contracts (Aiken, targeting Plutus V3). Given a universal-but-still-trusted verification key, a proof, and a list of public inputs, it checks the standard PLONK gate/permutation/quotient identity via a batched KZG opening, using a Keccak-256 Fiat–Shamir transcript matching the `snarkjs`-style compressed-commitment variant of the protocol. @@ -34,7 +32,7 @@ PLONK's universal SRS (reusable across circuits, unlike Groth16's circuit-specif - `preinputs.ak` - `PlonkPreInputs` (compressed-bytes verification key) and `PreparedPlonkPreInputs` (decompressed, with the evaluation-domain data filled in); `plonk_prepare_preinputs` converts one to the other. - `proofs.ak` - `PlonkProof` (compressed-bytes proof, `Int` evaluations) and `PreparedPlonkProof` (decompressed, `Scalar` evaluations, plus a derived `lagrange_inverses` hint); `plonk_prepare_proof` converts one to the other. -- `raw.ak` / `raw_affine.ak` - two alternate front doors that accept a verification key/proof expressed in this package's own point types rather than raw compressed bytes, and route them into the same `PreparedPlonkPreInputs`/`PlonkProof` pipeline (see §5 for why there are two, and why they aren't equivalent in what they trust). +- `raw_affine.ak` - an alternate front door that accepts a verification key/proof expressed in this package's own affine point types rather than raw compressed bytes, and routes them into the same `PreparedPlonkPreInputs`/`PlonkProof` pipeline (see §5). - `verifier.ak` - `verify_plonk`, the actual pairing-and-permutation check. **Key types** @@ -51,7 +49,7 @@ PreparedPlonkProof { ...same, decompressed, plus lagrange_inverses: List Bool` - the verifier; the only function a validator needs. ## 4. Protocol walkthrough @@ -68,7 +66,7 @@ PreparedPlonkProof { ...same, decompressed, plus lagrange_inverses: List Date: Wed, 11 Nov 2026 12:23:39 -0800 Subject: [PATCH 4/4] Bring the docs up to date with the property tests and open issues The README, zkp/README, specification and the three implementation reports now describe the property-based test files and the known_issue_* convention, and give the current layout of tests/. Each report's limitations section now lists the open issues that affect its module (#11 to #19). The Groth16 report described extra public inputs being truncated as safe, which #11 shows it isn't. The README links #20 for the unused part of common.ak. Co-Authored-By: Claude Opus 5.5 --- README.md | 4 ++-- specification.md | 8 ++++---- zkp/README.md | 6 ++++-- zkp/docs/bulletproofs-implementation-report.md | 8 ++++++-- zkp/docs/groth16-implementation-report.md | 8 +++++--- zkp/docs/plonk-implementation-report.md | 4 ++++ 6 files changed, 25 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 173bf15..34e944c 100644 --- a/README.md +++ b/README.md @@ -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`, 64/64 tests passing). 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 @@ -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 diff --git a/specification.md b/specification.md index e712324..a8b59f6 100644 --- a/specification.md +++ b/specification.md @@ -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 diff --git a/zkp/README.md b/zkp/README.md index a58f167..7e6ac08 100644 --- a/zkp/README.md +++ b/zkp/README.md @@ -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 @@ -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 ``` diff --git a/zkp/docs/bulletproofs-implementation-report.md b/zkp/docs/bulletproofs-implementation-report.md index dbcb999..85bb6f7 100644 --- a/zkp/docs/bulletproofs-implementation-report.md +++ b/zkp/docs/bulletproofs-implementation-report.md @@ -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 | |---|---| @@ -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. @@ -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 diff --git a/zkp/docs/groth16-implementation-report.md b/zkp/docs/groth16-implementation-report.md index b13d193..691ae39 100644 --- a/zkp/docs/groth16-implementation-report.md +++ b/zkp/docs/groth16-implementation-report.md @@ -72,7 +72,7 @@ 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 | |---|---| @@ -80,13 +80,15 @@ Three tests exercise this module, alongside the Bulletproofs and PLONK suites in | `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. diff --git a/zkp/docs/plonk-implementation-report.md b/zkp/docs/plonk-implementation-report.md index e3f9dd2..868ec89 100644 --- a/zkp/docs/plonk-implementation-report.md +++ b/zkp/docs/plonk-implementation-report.md @@ -96,6 +96,8 @@ Twelve tests in `tests/plonk_tests.ak` exercise this module directly, against a `tests/point_tests.ak` (12 further tests, also part of the package's 64) directly exercises `common/blst_affine.ak`'s compression and curve-membership helpers against this same fixture's proof and verification-key points, closing the loop on the affine front door described in §5. +`tests/plonk_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, and changing any of the six evaluation scalars is rejected. Its known-issue tests cover [#12](https://github.com/ADAOcommunity/zk/issues/12) (inputs not range-checked) and [#14](https://github.com/ADAOcommunity/zk/issues/14) (inverse-list length unchecked). `tests/point_props.ak` checks that `g1_affine_compress` produces exactly the builtin's encoding for random points, and pins [#15](https://github.com/ADAOcommunity/zk/issues/15). + `test_plonk_verification_with_affine_points` measures approximately 6.68M memory units and 8.63B CPU units - by far the most expensive single call among this package's three verifiers (compare Groth16's ~66.9K mem / 2.79B cpu and Bulletproofs' range proof at ~5.2M mem / 14.2B cpu at `n=8`), and leaves markedly less headroom against Cardano's per-transaction budget than either. Cost scales with `n_public`: each additional public input adds both a Lagrange-inverse check and a term in the public-input polynomial evaluation; only the 2-public-input fixture has been measured. ## 8. Known limitations and roadmap @@ -105,6 +107,8 @@ Twelve tests in `tests/plonk_tests.ak` exercise this module directly, against a - **Execution-unit cost is only measured at `n_public = 2`.** This is the most expensive verifier in the package per call already; larger public-input counts should be benchmarked before use in a real deployment. - **No on-chain entry point yet.** Like the other two modules in this package, how a validator obtains and trusts a given verification key/proof pair (datum/redeemer wiring) is separate, follow-on work. - **No cross-implementation interoperability testing beyond one fixture.** The transcript and batching scheme are documented as matching a `snarkjs`-style variant, but only one externally-produced proof has been used to validate that against this implementation; broader test vectors are future work. +- **Public-input and hint lengths aren't validated.** Inputs aren't range-checked against `r` ([#12](https://github.com/ADAOcommunity/zk/issues/12)); their count isn't checked against `n_public` ([#13](https://github.com/ADAOcommunity/zk/issues/13)); the `lagrange_inverses` list's length isn't checked, so dropping an inverse leaves its input unconstrained ([#14](https://github.com/ADAOcommunity/zk/issues/14)); and `generators` has one entry too many ([#19](https://github.com/ADAOcommunity/zk/issues/19)). These should be fixed together. +- **The affine front door trusts `y`.** `g1_affine_compress` uses only the sign of `y`, so different `AffineProof`s with the same `x` decode to the same proof ([#15](https://github.com/ADAOcommunity/zk/issues/15)). - **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. ## 9. Conclusion