Finalize Documentation

README.md

@@ -8,15 +8,15 @@ The Aiken ZKP Standards Library takes a pragmatic approach to implementing zero-
 
 This implementation is designed for Plutus v3, leveraging its built-in BLS12-381 curve functions to ensure efficient and secure verification of ZKPs. It emphasizes clarity and maintainability, making it suitable for educational/demonstrative purposes without sacrificing security.
 
-## Targeted Features
+## Status
 
-### Groth16
+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).
 
-Status: Complete
+### Groth16
 
-The Groth16 implementation is largely based on Modulo-P's [ak-381](https://github.com/Modulo-P/ak-381), with some ideas taken from [zarassh's implementation](https://github.com/tarassh/zkSNARK-under-the-hood/blob/main/groth16.py) and an emphasis on explicitness and clarity. This should make this implementation ideal for learning, or for further modification.
+Status: Complete (verifier)
 
-Currently, the Groth16 module includes:
+The Groth16 implementation ([`zkp/lib/groth`](./zkp/lib/groth)) is largely based on Modulo-P's [ak-381](https://github.com/Modulo-P/ak-381), with some ideas taken from [tarassh's implementation](https://github.com/tarassh/zkSNARK-under-the-hood/blob/main/groth16.py), and operates on native BLS12-381 pairing builtins throughout. It's tested against externally-generated proof/verification-key fixtures, both accepting valid proofs and rejecting a tampered one. [Implementation report](./zkp/docs/groth16-implementation-report.md).
 
 - [x] Generic Groth16 proof verifier system
 - [x] Onchain verification tests
@@ -30,9 +30,9 @@ Wishlist:
 
 Status: Optimizing
 
-The Plonk implementation is loosely based on perturbing's [plutus-plonk](https://github.com/perturbing/plutus-plonk-example), with several optimizations and restructuring done around point compression to improve performance and clarity.
+The Plonk implementation ([`zkp/lib/plonk`](./zkp/lib/plonk)) is loosely based on perturbing's [plutus-plonk-example](https://github.com/perturbing/plutus-plonk-example), with several optimizations and restructuring done around point compression to improve performance and clarity, a batched KZG opening, and a Keccak-256 Fiat–Shamir transcript matching the SnarkJS convention. It's tested against an externally-generated proof/verification-key fixture, including rejection of tampered proofs and mismatched public inputs. [Implementation report](./zkp/docs/plonk-implementation-report.md).
 
-The Plonk module currently includes:
+At current measurements, a full verification call is the most expensive of the three verifiers in this library (§7 of the implementation report) and leaves the least headroom against Cardano's per-transaction execution budget — hence "Optimizing" rather than "Complete."
 
 - [x] Generic Plonk proof verifier system
 - [x] Onchain verification tests
@@ -45,30 +45,47 @@ Wishlist:
 
 ### Bulletproofs
 
-Status: Early Development
+Status: Complete (verifier and reference prover)
+
+The Bulletproofs implementation ([`zkp/lib/bullet`](./zkp/lib/bullet)) is the only one of the three with no trusted setup, so this library implements and tests both a verifier *and* a reference prover directly, with no external fixtures required. [Implementation report](./zkp/docs/bulletproofs-implementation-report.md).
+
+- [x] Generic Bulletproofs range-proof verifier and reference prover
+- [x] Onchain verification tests, including boundary values and tamper rejection
+
+Wishlist:
 
-The Bulletproofs implementation is in the early stages, with a focus on building out the necessary field arithmetic and point operations required for Bulletproofs.
+- [ ] Recursive inner-product-argument (IPA) compression, for `O(log n)` rather than `O(n)` proof size
+- [ ] Integration into a merkelized validator
 
 ### Helper Functions
 
-- Affine point operations - conversion to/from native types
-- Field arithmetic utilities
+- 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
 
 ## Aspirational ZKP Systems
 
 - **Marlin**: Preprocessing zkSNARKs with Universal and Updatable SRS
 - **Plonky2**: Advanced recursive proof composition
 
-## Contributing
+## Implementation
 
-We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for:
+- Leverages PlutusV3's BLS12-381 curve builtin functions
+- Focuses on efficient verification
+- Maintains strong security guarantees
+- See the per-protocol implementation reports in [`zkp/docs/`](./zkp/docs) for details
 
-- Development guidelines
-- Submission process
-- Testing requirements
+## Getting Started
 
 ### Prerequisites
 
 - Aiken development environment
 - Familiarity with ZKP systems
 - Understanding of Cardano smart contracts
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for:
+
+- Development guidelines
+- Submission process
+- Testing requirements

specification.md

@@ -28,22 +28,24 @@ Bulletproofs shine through their versatility. They’re small in size, easily ag
 
 The library's scope has been carefully defined through a systematic evaluation process:
 
-### Committed Features
+### 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/`.
 
 #### Groth16
-- Provide a generic Groth16 proof verifier system in Aiken which supports user-defined circuits leveraging circom and SnarkJS
-- Provide an example circuit and R1CS constraint set for the Groth16 verifier to show the entire process of creating and verifying a Groth16 proof
-- Provide a test suite that demonstrates the ability of the proof system to successfully verify the generated proof, while denying validation of invalid proofs
+- 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
+- See `zkp/docs/groth16-implementation-report.md`
 
 #### Plonk
-- Provide a generic Plonk proof verifier system in Aiken which supports user-defined circuits leveraging circom and SnarkJS
-- Provide an example circuit and R1CS constraint set for the Plonk verifier to show the entire process of creating and verifying a Plonk proof
-- Provide a test suite that demonstrates the ability of the proof system to successfully verify the generated proof, while denying validation of invalid proofs
+- 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
+- See `zkp/docs/plonk-implementation-report.md`
 
 #### Bulletproofs
-- Provide a generic Bulletproof verifier system in Aiken which supports user-defined circuits leveraging circom and SnarkJS
-- Provide an example circuit and R1CS constraint set for the Bulletproof verifier to show the entire process of creating and verifying a Bulletproof
-- Provide a test suite that demonstrates the ability of the proof system to successfully verify the generated proof, while denying validation of invalid proofs
+- 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
+- See `zkp/docs/bulletproofs-implementation-report.md`
 
 ### Non-Committed / Aspirational Features
 
@@ -55,10 +57,4 @@ The library's scope has been carefully defined through a systematic evaluation p
 
 ## Implementation
 
-### On-Chain
-
-Our on-chain implementation will be supported largely by the new builtin functions provided by PlutusV3 that relate to the BLS12-381 curve. Some of the type signatures for both type definitions and functions of the library can be found within the `.ak` files throughout the rest of the repository. These implementations will focus on efficient verification while maintaining security guarantees.
-
-### Off-Chain
-
-Given that this library is specific to Aiken, the off-chain implementation is highly dependent upon the design choices and requirements of the user. We will be providing examples using circom, but support for general purpose proof creation is outside the scope of this work. Users will need to implement their own proof generation infrastructure using tools like circom and SnarkJS while following our provided examples as guidance.
+Our implementation will be supported largely by the new builtin functions provided by PlutusV3 that relate to the BLS12-381 curve. Some of the type signatures for both type definitions and functions of the library can be found within the `.ak` files throughout the rest of the repository. These implementations will focus on efficient verification while maintaining security guarantees. See `zkp/docs/` for a full implementation report per protocol, covering architecture, design decisions, and security arguments.

zkp/README.md

@@ -0,0 +1,30 @@
+# zkp
+
+Aiken package containing this project's three zero-knowledge proof verifiers, targeting Plutus V3 on Cardano. See the repository root [README](../README.md) and [specification.md](../specification.md) for project-level scope and status.
+
+## Layout
+
+```
+lib/
+  groth/    Groth16 verifier
+  plonk/    PLONK verifier
+  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)
+docs/
+  step-by-step.md                       Protocol-level walkthrough of all three systems
+  groth16-implementation-report.md      Architecture, design decisions, security argument
+  plonk-implementation-report.md          "
+  bulletproofs-implementation-report.md   "
+```
+
+## Working with this package
+
+```sh
+aiken check   # run the test suite
+aiken build   # compile and generate plutus.json
+aiken fmt     # format .ak source
+```
+
+Each implementation report in `docs/` documents what's actually built, how it departs from a naive port of the underlying protocol, and its known limitations — read those before integrating one of these verifiers into a validator.