# tnyuzg/fairzk architecture

> Architecture diagram of the GitHub repository tnyuzg/fairzk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tnyuzg/fairzk
- Repository: https://github.com/tnyuzg/fairzk

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Libraries
    subgraph "Algebra Layer"
        direction TB
        Algebra["algebra"]:::lib
        Field["field/"]:::lib
        Ext["extension/"]:::lib
        Poly["polynomial/"]:::lib
        Util["utils/"]:::lib
    end

    subgraph "PCS Layer"
        direction TB
        PCS["pcs"]:::lib
        ML["multilinear/"]:::lib
        Code["code/"]:::lib
        Hash["hash.rs"]:::lib
        Merkle["merkle_tree.rs"]:::lib
    end

    subgraph "FairZK Library"
        direction TB
        subgraph "PIOP Modules"
            direction TB
            PIOP["piop"]:::proof
        end
        subgraph "Sumcheck"
            direction TB
            SUM["sumcheck"]:::proof
        end
        subgraph "SNARK Assembly"
            direction TB
            SNARK["snark"]:::orchestration
        end
        subgraph "Examples & CLI"
            direction TB
            EX["examples"]:::cli
        end
        FG["fairzk/src/lib.rs"]:::orchestration
    end

    Models["models"]:::data

    %% Dependency flows (dashed)
    PIOP -.->|depends on| Algebra
    SUM -.->|depends on| Algebra
    PIOP -.->|depends on| PCS
    SNARK -.->|uses| PCS
    SNARK -.->|uses| Algebra

    %% Runtime flows (solid)
    EX -->|load models| Models
    EX -->|instantiate oracles| PIOP
    PIOP -->|"commit oracles"| PCS
    PIOP -->|"prove sumcheck"| SUM
    SUM -->|"compose SNARK"| SNARK
    SNARK -->|"verify proof"| EX

    %% Click Events
    click Algebra "https://github.com/tnyuzg/fairzk/blob/main/algebra/src/lib.rs"
    click Field "https://github.com/tnyuzg/fairzk/tree/main/algebra/src/field/"
    click Ext "https://github.com/tnyuzg/fairzk/tree/main/algebra/src/extension/"
    click Poly "https://github.com/tnyuzg/fairzk/tree/main/algebra/src/polynomial/"
    click Util "https://github.com/tnyuzg/fairzk/tree/main/algebra/src/utils/"
    click PCS "https://github.com/tnyuzg/fairzk/blob/main/pcs/src/lib.rs"
    click ML "https://github.com/tnyuzg/fairzk/tree/main/pcs/src/multilinear/"
    click Code "https://github.com/tnyuzg/fairzk/tree/main/pcs/src/utils/code/"
    click Hash "https://github.com/tnyuzg/fairzk/blob/main/pcs/src/utils/hash.rs"
    click Merkle "https://github.com/tnyuzg/fairzk/blob/main/pcs/src/utils/merkle_tree.rs"
    click PIOP "https://github.com/tnyuzg/fairzk/blob/main/fairzk/src/piop/mod.rs"
    click SUM "https://github.com/tnyuzg/fairzk/blob/main/fairzk/src/sumcheck/mod.rs"
    click SNARK "https://github.com/tnyuzg/fairzk/blob/main/fairzk/src/snark/mod.rs"
    click EX "https://github.com/tnyuzg/fairzk/tree/main/fairzk/examples/"
    click Models "https://github.com/tnyuzg/fairzk/tree/main/models/"

    %% Styles
    classDef lib fill:#cce5ff,stroke:#004085,color:#004085;
    classDef proof fill:#d4edda,stroke:#155724,color:#155724;
    classDef orchestration fill:#ffe5b4,stroke:#cc8400,color:#cc8400;
    classDef cli fill:#fff3cd,stroke:#856404,color:#856404;
    classDef data fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
