How tnyuzg/fairzk works
Project type and purpose
• This is a multi-crate Rust library/toolkit (not a web app) for constructing and verifying specialized zero-knowledge SNARK proofs of machine-learning fairness properties.
• The key crates are:
• algebra: finite-field & polynomial primitives, arithmetic, random, reduction operations, utilities.
• pcs: polynomial commitment schemes and related utilities (Merkle trees, Reed-Solomon).
• fairzk: the top-level crate orchestrating PIOPs (probabilistic interactive oracle proofs), sumcheck, SNARK generation & verification, plus example binaries.
• There is also a models directory containing pre-quantized DNN model parameters used by the examples.
File structure
• Top-level: three Cargo workspaces/crates (algebra/, pcs/, fairzk/) and a models/ folder.
• algebra/src: modules for fields, extensions, moduli, polynomials, reduction, primitives, random, utils.
• pcs/src: commitment schemes and utilities (multilinear, code, hash, merkle).
• fairzk/src:
• piop/: different proof oracles (spectral norm, inference, lookup, etc.)
• sumcheck/: sumcheck prover/verifier
• snark/: compiling PIOPs + PCS into full SNARKs
• pcs.rs: glue to pcs crate
• examples/: demo binaries that load models, build instances, run prover & verifier.
• Configuration/manifest files: Cargo.toml in each crate, top-level .gitignore.
README for insights
• Describes the workflow: example runs → constructs lookup instance → commits oracles → proves sumchecks → builds SNARK → verifies.
• Shows performance timing breakdown and proof size.
• Notes external dependencies: arkworks-rs, Plonky3, primus-fhe.
Main components and their interactions
a. Algebra layer (crate algebra)
• Core finite-field arithmetic, polynomial ops, extensions, randomness.
b. PCS layer (crate pcs)
• Polynomial commitment schemes, Merkle trees, error-correcting codes (Reed-Solomon).
c. PIOP modules (folder fairzk/src/piop)
• Build oracles for inference, spectral norm, L2 norm, lookup, total fairness bound.
• Depend on both algebra (for arithmetic) and pcs (for broadcasting commitments).
d. Sumcheck (folder fairzk/src/sumcheck)
• Generic sumcheck prover & verifier; uses algebra primitives.
e. SNARK assembly (folder fairzk/src/snark)
• Combines PIOPs + PCS into full proving & verification protocols.
f. Examples & CLI (folder fairzk/examples)
• Load pre-quantized models, instantiate circuits, run prover/verifier.
g. Models (models/)
• Static data inputs (weights, labels, features).
h. External Services
• None (pure library/CLI), but external crates referenced in acknowledgements.
Architectural patterns and design principles
• Layered/stacked architecture:
algebra → pcs → PIOPs & sumcheck → SNARK → example CLI.
• Modular crate separation ensures math primitives are independent of commitment schemes and proof logic.
• Pipeline pattern in fairzk/examples: data → commit oracles → sumcheck proofs → SNARK → verify.
• Reusability and composability: PIOPs can be composed into larger proofs (e.g., total.rs combines all sub-proofs).
Essential elements
• algebra (fields, polynomials)
• pcs (commitments)
• fairzk/piop (oracle builders)
• fairzk/sumcheck (sumcheck prover/verifier)
• fairzk/snark (proof composer)
• examples (entry points)
• models (input data)
• Annotation of key external dependencies (arkworks, Plonky3, primus-fhe)