/ README.md
README.md
1 ``` 2 ╔═══════════════════════════════════════════════════╗ 3 ║ ║ 4 ║ ▄████ ██▀███ ▒█████ ▄▄▄█████▓ ██░ ██ ║ 5 ║ ██▒ ▀█▒▓██ ▒ ██▒▒██▒ ██▒▓ ██▒ ▓▒▓██░ ██▒ ║ 6 ║ ▒██░▄▄▄░▓██ ░▄█ ▒▒██░ ██▒▒ ▓██░ ▒░▒██▀▀██░ ║ 7 ║ ░▓█ ██▓▒██▀▀█▄ ▒██ ██░░ ▓██▓ ░ ░▓█ ░██ ║ 8 ║ ░▒▓███▀▒░██▓ ▒██▒░ ████▓▒░ ▒██▒ ░ ░▓█▒░██▓ ║ 9 ║ ░▒ ▒ ░ ▒▓ ░▒▓░░ ▒░▒░▒░ ▒ ░░ ▒ ░░▒░▒ ║ 10 ║ ░ ░ ░▒ ░ ▒░ ░ ▒ ▒░ ░ ▒ ░▒░ ░ ║ 11 ║ ░ ░ ░ ░░ ░ ░ ░ ░ ▒ ░ ░ ░░ ░ ║ 12 ║ ░ ░ ░ ░ ░ ░ ░ ║ 13 ╚═══════════════════════════════════════════════════╝ 14 ∴‥∵‥∴ zkSNARK SUPREMACY ∴‥∵‥∴ 15 16 ░▒▓█► ρяσνє єνєяутнιηg, яєνєαℓ ησтнιηg ◄█▓▒░ 17 18 ╔═════════════════════════════════════════════════════════════╗ 19 ║ "In cryptography we trust, in zero-knowledge we thrive" ║ 20 ║ ∞ milady privacy maximalism ∞ ║ 21 ╚═════════════════════════════════════════════════════════════╝ 22 23 ▓▓▓▓▓▓▓ ▓▓▓▓▓▓▓ 24 ▓ ▓ ▓ ▓ ┌─────────────┐ 25 ▓ ╳ ╳ ▓ ▓ ╳ ╳ ▓ │ COMMITMENT │ 26 ▓ ▓ ▓ ▓ │ HIDDEN │ 27 ▓ ▓ ▓ ▓ │ KNOWLEDGE │ 28 ▓▓▓▓▓ ▓▓▓▓▓ └─────────────┘ 29 ║ ║ 30 ═══╬═════════╬═══ 31 ║ ║ 32 ╔═════╩═════════╩═════╗ 33 ║ TRUSTED SETUP CULT ║ 34 ╚═════════════════════╝ 35 ``` 36 37 # Groth.jl 38 39 Research-focused, modular implementation of the Groth16 zero-knowledge proof system in Julia. 40 This repository explores cryptographic primitives (finite fields, curves, pairings) and the Groth16 protocol end-to-end in Julia. It is a research codebase and **not** production software. 41 42 ## Repository layout 43 44 ``` 45 Groth.jl/ 46 ├── GrothAlgebra/ # finite fields, polynomials, group utilities 47 ├── GrothCurves/ # BN254 curve + pairing engine 48 ├── GrothProofs/ # R1CS, QAP, Groth16 prover/verifier 49 ├── GrothExamples/ # tutorial scripts and walkthroughs 50 ├── GrothCrypto/ # placeholder for higher-level protocols 51 ├── benchmarks/ # BenchmarkTools environment + plots 52 └── docs/ # Roadmap, package reference, arkworks mapping 53 ``` 54 55 - `docs/PACKAGE_REFERENCE.md` — per-package summary, key modules, follow-ups 56 - `docs/Implementation_vs_Arkworks.md` — how our implementation compares to 57 arkworks (domains, MSM, pairing, Groth16 pipeline) 58 - `docs/ROADMAP.md` — current priorities and completed milestones 59 - `docs/RareSkills_Groth16_Map.md` — link between the RareSkills ZK book and 60 the Julia code 61 62 The sibling repositories `ark-works/` and `zk-book/` are reference checkouts 63 only; all active work lives in `Groth.jl/`. 64 65 ## Getting started 66 67 ``` 68 # develop packages locally 69 julia --project -e 'using Pkg; Pkg.develop("GrothAlgebra"); Pkg.develop("GrothCurves"); Pkg.develop("GrothProofs")' 70 71 # run tests 72 julia --project=GrothAlgebra -e 'using Pkg; Pkg.test()' 73 julia --project=GrothProofs -e 'using Pkg; Pkg.test()' 74 75 # benchmarks 76 julia --project=benchmarks benchmarks/run.jl 77 julia --project=benchmarks benchmarks/plot.jl 78 ``` 79 80 Key tutorials live in `GrothExamples/`; run `demonstrate_r1cs_qap()` or 81 `multiplication_proof_example()` to see the Groth16 pipeline end-to-end. 82 83 ## Project status 84 85 - **GrothAlgebra** — prime fields, polynomial utilities, MSM helpers. Coset FFT 86 path uses coefficient-first padding; domain alignment with arkworks is the 87 next major task. 88 - **GrothCurves** — BN254 tower, Jacobian curve ops, optimal ate pairing, and 89 a pairing-engine abstraction ready for additional curves. 90 - **GrothProofs** — R1CS/QAP conversion, Groth16 setup/prove/verify mirroring 91 arkworks. Coset FFT path is default; dense path retained only for assertions. 92 - **Benchmarks** — `benchmarks/results_2025-09-29_121914.json` captures the 93 current coset-enabled timings; plots regenerated via `benchmarks/plot.jl`. 94 95 See `docs/ROADMAP.md` for detailed milestones and follow-up work (domain 96 alignment, MSM optimisations, second curve prototype, proof aggregation). 97 98 ## Development guidelines 99 100 - Follow Julia style conventions: 4-space indent, `lowercase_with_underscores` 101 for functions, docstrings on exported methods, and dispatch-friendly 102 signatures that match existing APIs. 103 - Run the relevant `Pkg.test()` suites and update benchmarks when performance 104 changes. 105 - Use concise imperative commit messages (e.g., `groth16: align coset domain`). 106 - Keep tutorial/docs in sync when user-visible output changes; the docs listed 107 above are the canonical references. 108 109 ## References 110 111 - [arkworks](https://github.com/arkworks-rs) (Groth16 and algebra implementations) 112 - [RareSkills Zero Knowledge Book](https://github.com/zkCollective/zk-book) 113 114 This repo explores cryptographic primitives (finite fields, curves, pairings) and the Groth16 protocol end-to-end in Julia. 115 116 Note: This project is for research and experimentation. It is not intended for production use. 117 118 ## Project Structure 119 120 This is a monorepo containing several interconnected Julia packages: 121 122 ### Core Packages 123 124 - **[GrothAlgebra](./GrothAlgebra)** - Foundation package with finite field arithmetic, polynomial operations, and group theory primitives 125 - **[GrothCurves](./GrothCurves)** - Elliptic curve implementations, focusing on BN254 (alt-bn128) with pairing support 126 - **[GrothProofs](./GrothProofs)** - Zero-knowledge proof systems including R1CS, QAP conversion, and Groth16 implementation 127 - **[GrothCrypto](./GrothCrypto)** - High-level cryptographic protocols built on top of the primitives 128 - **[GrothExamples](./GrothExamples)** - Educational examples and demonstrations 129 130 ### Documentation & Tools 131 132 - **[docs/](./docs)** - Project documentation including the RareSkills→Groth16 map and polishing roadmap 133 - **[benchmarks/](./benchmarks)** - Performance benchmarks across packages 134 135 ## Status Overview 136 137 - Algebra (GrothAlgebra) 138 - Prime fields (Fp) and scalar field (Fr) implementations; polynomial arithmetic with interpolation and evaluation. 139 - FFT/NTT and roots-of-unity domain planned (not yet implemented). 140 - Curves & Pairing (GrothCurves) 141 - BN254 G1/G2 with Fp2/Fp6/Fp12 tower, optimal ate Miller loop, and final exponentiation. 142 - Pairing engine abstraction (`AbstractPairingEngine`, `BN254Engine`) to support future curves while keeping BN254 optimized. 143 - Proofs (GrothProofs) 144 - R1CS and QAP conversion in Fr; end-to-end Groth16 (CRS, prover, verifier) aligned with arkworks structure and equations. 145 - Verifier enforces on-curve and subgroup checks; prepared verifier path batches pairings through the engine interface. 146 - Examples (GrothExamples) 147 - End-to-end demonstration of the Groth16 pipeline. 148 149 ## Roadmap Highlights 150 151 - Grow curve/generalization support: extend the pairing-engine interface to additional curves and trait-style abstractions. 152 - FFT/NTT + roots-of-unity domain for QAP and faster polynomial ops. 153 - MSM, fixed-base tables, and threaded hot paths for the prover plus batch normalization of CRS elements. 154 - Documentation polish: Documenter.jl site, Pluto notebooks, and contributor guides for multiple dispatch patterns. 155 156 ## Pairing Engine Interface 157 158 - Depend on `AbstractPairingEngine` (re-exported by `GrothCurves`) when writing code that needs pairings. The interface consists of `miller_loop`, `final_exponentiation`, `pairing`, and `pairing_batch` methods specialised on an engine type parameterised by the curve family. 159 - `BN254Engine` is the default zero-sized backend; use the explicit form `pairing(BN254_ENGINE, P, Q)` or pass `engine=BN254_ENGINE` into helpers such as `GrothProofs.setup_full`. Convenience overloads without the engine argument remain available for interactive use. 160 - The engine test harness lives in `GrothCurves/test/test_pairing_engine_interface.jl` and checks zero-handling, bilinearity, and batch pairing consistency. Mirror those checks when introducing additional engines. 161 162 ## Development 163 164 - This is a research project: APIs may evolve. Not for production use. 165 - Each package is a standalone Julia project with its own tests and docs. 166 167 ## References 168 169 - arkworks-rs (groth16, algebra, relations) 170 - RareSkills ZK Book