├── LICENSE ├── README.md ├── activation └── README.md ├── conv_layers └── README.md ├── core_ops ├── README.md ├── range_check_and_relu.pdf ├── range_check_max_min_relu.pdf └── square_root.pdf ├── matmul ├── README.md ├── matrix_addition_hadamard_product_matrix_multiplication.pdf ├── matrix_multiplication_freivalds_algorithm.pdf └── quantized_matrix_multiplication_via_freivalds.pdf ├── pooling └── README.md └── utils └── links.md /LICENSE: -------------------------------------------------------------------------------- 1 | Creative Commons Attribution 4.0 International (CC BY 4.0) 2 | 3 | You are free to: 4 | - Share — copy and redistribute the material in any medium or format. 5 | - Adapt — remix, transform, and build upon the material for any purpose, even commercially. 6 | 7 | Under the following terms: 8 | - **Attribution** — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use. 9 | 10 | Full license text: https://creativecommons.org/licenses/by/4.0/legalcode 11 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # zkml-blueprints 2 | 3 | > A growing collection of custom circuit designs—with every constraint proven and every idea explained. 4 | > Built for clarity, rigor, and community collaboration—the reference we all wish we’d had! 5 | 6 | --- 7 | 8 | **zkml-blueprints** is a collection of mathematical formulations and circuit designs supporting zero-knowledge (ZK) proofs for machine learning (ML) applications, focusing on efficiently implementing provable computations in ZK circuits. This repository provides formal descriptions, constraints, and structured blueprints for designing circuits that preserve privacy while ensuring verifiable correctness. 9 | 10 | If you're new here, a good starting point is the [matrix addition, Hadamard product, and matrix multiplication blueprint](./matmul/matrix_addition_hadamard_product_matrix_multiplication.pdf). It introduces the core ideas and verification paradigm used throughout the project, grounded in addition and multiplication over finite fields, before moving on to more technical constructions. 11 | 12 | ## Features 13 | - 📖 **Mathematical Formulations** – Rigorous explanations of key principles underlying ZK circuit design. 14 | - 🛠 **Circuit Constraints** – Well-documented approaches to encoding computations in finite fields. 15 | - ⚡ **Implementation Guidelines** – Blueprints for translating mathematical constructs into efficient circuit implementations. 16 | - 🔒 **Use Cases** – Applications in cryptographic protocols, zk-SNARKs, and privacy-preserving machine learning. 17 | 18 | This repository aims to serve as a structured reference for researchers, developers, and practitioners working on ZK and zkML proof systems, offering both theoretical insights and practical implementations. 19 | 20 | 💡 *Contributions and discussions are welcome!* 21 | 22 | --- 23 | 24 | ## 📁 Repository Structure 25 | 26 | Each subdirectory focuses on a specific class of operations: 27 | 28 | | Directory | Contents | 29 | |------------------|--------------------------------------------------------------------------| 30 | | [`core_ops/`](./core_ops) | Range checks, max/min, and basic ReLU formulations | 31 | | [`matmul/`](./matmul) | Hadamard product, matrix addition, and matrix multiplication (standard and quantized) | 32 | | [`pooling/`](./pooling) | Max and min pooling circuits (⏳ coming soon) | 33 | | [`conv_layers/`](./conv_layers)| Convolutional layer blueprints (⏳ coming soon) | 34 | | [`activation/`](./activation) | Activation functions like ReLU, LeakyReLU, etc. (only ReLU at this stage; others may follow in future work) | 35 | | [`utils/`](./utils) | Internal links and shared references for documentation navigation | 36 | 37 | Each section contains: 38 | - 📄 **PDF blueprints** describing the circuit logic, constraints, and mathematical justification 39 | - 📓 *(Planned)* Jupyter notebooks for live examples and testing 40 | - 📘 A local `README.md` with context and links 41 | 42 | --- 43 | 44 | -------------------------------------------------------------------------------- /activation/README.md: -------------------------------------------------------------------------------- 1 | # Activation Functions 2 | 3 | This directory will collect activation circuits. For now, ReLU circuits are defined in: 4 | 5 | - [`../core_ops/range_check_and_relu.pdf`](../core_ops/range_check_and_relu.pdf) 6 | - [`../core_ops/range_check_max_min_relu.pdf`](../core_ops/range_check_max_min_relu.pdf) 7 | 8 | Future additions may include: 9 | - LeakyReLU 10 | - Sigmoid (approximated) 11 | - Softmax (circuit-compatible version) 12 | 13 | 14 | -------------------------------------------------------------------------------- /conv_layers/README.md: -------------------------------------------------------------------------------- 1 | # Convolution Layers 2 | 3 | 🚧 This section will contain circuits for convolutional layers. 4 | 5 | Stay tuned! 6 | 7 | 8 | -------------------------------------------------------------------------------- /core_ops/README.md: -------------------------------------------------------------------------------- 1 | # Core Operations 2 | 3 | This directory contains foundational circuit blueprints for core operations: 4 | 5 | - [`range_check_and_relu.pdf`](./range_check_and_relu.pdf): Range check and ReLU implementation 6 | - [`range_check_max_min_relu.pdf`](./range_check_max_min_relu.pdf): Extended operations: max, min, and ReLU 7 | - [`square_root.pdf`](./square_root.pdf): Square root 8 | 9 | ## 🔗 Related Modules 10 | 11 | - See [`activation/`](../activation) for additional ReLU-related circuits 12 | - See [`matmul/`](../matmul) for applications of ReLU in quantized matrix multiplication 13 | 14 | 15 | -------------------------------------------------------------------------------- /core_ops/range_check_and_relu.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/inference-labs-inc/zkml-blueprints/c773765b67f446c3207693b49f61ac4d9d2729a0/core_ops/range_check_and_relu.pdf -------------------------------------------------------------------------------- /core_ops/range_check_max_min_relu.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/inference-labs-inc/zkml-blueprints/c773765b67f446c3207693b49f61ac4d9d2729a0/core_ops/range_check_max_min_relu.pdf -------------------------------------------------------------------------------- /core_ops/square_root.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/inference-labs-inc/zkml-blueprints/c773765b67f446c3207693b49f61ac4d9d2729a0/core_ops/square_root.pdf -------------------------------------------------------------------------------- /matmul/README.md: -------------------------------------------------------------------------------- 1 | # Matrix Multiplication 2 | 3 | This directory covers matrix multiplication circuits: 4 | 5 | - [`matrix_addition_hadamard_product_matrix_multiplication.pdf`](./matrix_addition_hadamard_product_matrix_multiplication.pdf) – Matrix addition, Hadamard product, generalized matrix multiplication 6 | - [`matrix_multiplication_freivalds_algorithm.pdf`](./matrix_multiplication_freivalds_algorithm.pdf) – Matrix multiplication, non-deterministic verification via Freivalds' technique 7 | - [`quantized_matrix_multiplication_via_freivalds.pdf`](./quantized_matrix_multiplication_via_freivalds.pdf) – [Will add a variation soon!] Quantized version with scaling and ReLU-compatible range checks 8 | 9 | ## 🔗 Related 10 | 11 | - ReLU and range checks in [`core_ops/`](../core_ops) 12 | 13 | 14 | -------------------------------------------------------------------------------- /matmul/matrix_addition_hadamard_product_matrix_multiplication.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/inference-labs-inc/zkml-blueprints/c773765b67f446c3207693b49f61ac4d9d2729a0/matmul/matrix_addition_hadamard_product_matrix_multiplication.pdf -------------------------------------------------------------------------------- /matmul/matrix_multiplication_freivalds_algorithm.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/inference-labs-inc/zkml-blueprints/c773765b67f446c3207693b49f61ac4d9d2729a0/matmul/matrix_multiplication_freivalds_algorithm.pdf -------------------------------------------------------------------------------- /matmul/quantized_matrix_multiplication_via_freivalds.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/inference-labs-inc/zkml-blueprints/c773765b67f446c3207693b49f61ac4d9d2729a0/matmul/quantized_matrix_multiplication_via_freivalds.pdf -------------------------------------------------------------------------------- /pooling/README.md: -------------------------------------------------------------------------------- 1 | # Pooling Layers 2 | 3 | 🚧 Blueprints for max and min pooling circuits (under development). 4 | 5 | ## Status 6 | 7 | 📝 Max pooling planned 8 | 📝 Min pooling planned 9 | 📝 Notebooks planned 10 | 11 | 12 | -------------------------------------------------------------------------------- /utils/links.md: -------------------------------------------------------------------------------- 1 | # Internal Reference Links 2 | 3 | 🚧 This file maps cross-links between documents. 4 | 5 | 6 | 7 | --------------------------------------------------------------------------------