# scipr-lab/libsnark architecture

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

- Interactive diagram: https://gitdiagram.com/scipr-lab/libsnark
- Repository: https://github.com/scipr-lab/libsnark

## Overview

##### Project type and purpose
- This is a C++ cryptographic library (libsnark) implementing zero-knowledge SNARK proof systems.
- It is a reusable, research‐quality toolkit, not a standalone application; client code (examples or user applications) link against it.

##### High‐level components
A. External Dependencies (“depends” submodule)
- libff (finite fields & elliptic curves)
- libfqfft (FFT over finite fields)
- ate-pairing, xbyak (BN128 curve support)
- libsnark-supercop (crypto primitives for ADSNARK)
- GTest (unit tests)
B. Build & Config
- CMakeLists.txt, Dockerfile, Travis CI config
- Transition‐to‐CMake.md, doxygen.conf
C. Core Library (`libsnark/` directory)
1. common
– Utilities, data structures (Merkle trees, sparse vectors, integer permutation)
2. gadgetlib1
– Low‐level, template‐based gadget API for building R1CS constraints
– Basic gadgets, CPU checkers, curve gadgets, hash gadgets, pairing gadgets, routing gadgets, etc.
3. gadgetlib2
– Higher‐level, non‐template gadget API; examples & tutorial
4. relations
– Formal definitions of NP languages: R1CS, USCS, BACS, TBCS, SAP, QAP, SSP, RAM computations
5. reductions
– Conversions between NP languages (e.g. BACS→R1CS, R1CS→QAP, RAM→R1CS, TBCS→USCS)
6. zk_proof_systems
– Implementations of proof systems (ppzkSNARKs, ADSNARK, PCD) parameterized over R1CS, TBCS, USCS, etc.
7. examples & tests
– In‐tree examples for each module and unit tests (GTest)

##### Relationships and interactions
- External Dependencies → built by CMake → linked into libsnark core
- common → foundational data types → used by gadgetlib1, gadgetlib2, relations, reductions, zk_proof_systems
- relations → defines NP languages → consumed by gadgetlib1/gadgetlib2 (to build instances) and by zk_proof_systems (to implement prove/verify)
- reductions → use relations to translate languages → feed into zk_proof_systems backends
- gadgetlib1 & gadgetlib2 → produce R1CS instances (by pulling in common and relations) → passed to zk_proof_systems R1CS backends
- zk_proof_systems → core generator/prover/verifier algorithms → depend on libff and libfqfft for field arithmetic & FFT, and on pairing libraries (ate-pairing)
- examples → demonstrate usage of gadget libraries and proof system APIs
- tests → validate individual modules

##### Architectural patterns & design principles
- Layered modular architecture:
- Base layer: common utilities & external libraries
- Middle layer: constraint-building (gadgets & relations)
- Upper layer: proof system implementations
- Consumer layer: examples, applications, tests
- Separation of concerns: data structures vs. language definitions vs. proof algorithms
- Template‐based vs. object‐oriented APIs (gadgetlib1 vs. gadgetlib2)
- Use of CMake for multi‐platform build configuration and dependency management
- Optional features toggled via CMake flags (curve choice, multicore, profiling, etc.)

##### Detailed capture of essential elements
- Do not omit the “common” layer—it underpins everything.
- Both gadgetlib1 and gadgetlib2, since they represent alternative APIs.
- Reductions module to illustrate language‐translation pathways.
- Tie in build scripts/CMake as the orchestrator for fetching dependencies, configuring flags, and building each module.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & Config Layer
    subgraph "Build & Config"
        direction TB
        CMake["CMakeLists.txt"]:::build
        SubCMake["depends/CMakeLists.txt"]:::build
        LibCMake["libsnark/CMakeLists.txt"]:::build
        Travis[".travis.yml"]:::build
        Docker["Dockerfile"]:::build
        Transition["Transition-to-CMake.md"]:::build
        Doxygen["doxygen.conf"]:::build
    end

    %% External Dependencies Layer
    subgraph "External Dependencies"
        direction TB
        LibFF["libff"]:::external
        LibFQFFT["libfqfft"]:::external
        AtePair["ate-pairing"]:::external
        Xbyak["xbyak"]:::external
        Supercop["libsnark-supercop"]:::external
        GTest["GTest"]:::external
    end

    %% Core Utilities & Relations Layer
    subgraph "Core Utilities & Relations"
        direction TB
        Common["common"]:::core
        Relations["relations"]:::core
    end

    %% Gadget & Reductions Layer
    subgraph "Gadget Libraries & Reductions"
        direction TB
        Gadget1["gadgetlib1"]:::gadget
        Gadget2["gadgetlib2"]:::gadget
        Reductions["reductions"]:::gadget
    end

    %% Proof Systems Layer
    subgraph "Proof Systems"
        direction TB
        ZK["zk_proof_systems"]:::proof
    end

    %% Examples & Tests Layer
    subgraph "Examples & Tests"
        direction TB
        Examples["examples"]:::example
        Tests["tests"]:::example
    end

    %% Dependencies
    CMake -->|orchestrates build| LibFF
    CMake --> LibFQFFT
    CMake --> AtePair
    CMake --> Xbyak
    CMake --> Supercop
    CMake --> GTest

    LibFF -->|linked into| Common
    LibFQFFT --> Common
    AtePair --> ZK
    Xbyak --> ZK
    Supercop --> ZK
    GTest --> Tests

    Common -->|uses data structures| Gadget1
    Common --> Gadget2
    Common --> Relations
    Relations --> Gadget1
    Relations --> Gadget2
    Relations --> ZK

    Gadget1 -->|produces R1CS instances| ZK
    Gadget2 -->|produces R1CS instances| ZK
    Reductions --> Relations
    Reductions --> ZK

    ZK -->|APIs consumed by| Examples
    Gadget1 --> Examples
    Gadget2 --> Examples
    Relations --> Examples
    Reductions --> Examples
    Tests --> Common
    Tests --> Gadget1
    Tests --> Gadget2
    Tests --> Relations
    Tests --> Reductions
    Tests --> ZK

    %% Click Events for Build & Config
    click CMake "https://github.com/scipr-lab/libsnark/blob/master/CMakeLists.txt"
    click SubCMake "https://github.com/scipr-lab/libsnark/blob/master/depends/CMakeLists.txt"
    click LibCMake "https://github.com/scipr-lab/libsnark/blob/master/libsnark/CMakeLists.txt"
    click Travis "https://github.com/scipr-lab/libsnark/blob/master/.travis.yml"
    click Docker "https://github.com/scipr-lab/libsnark/tree/master/Dockerfile"
    click Transition "https://github.com/scipr-lab/libsnark/blob/master/Transition-to-CMake.md"
    click Doxygen "https://github.com/scipr-lab/libsnark/blob/master/doxygen.conf"

    %% Click Events for External Dependencies
    click LibFF "https://github.com/scipr-lab/libsnark/tree/master/depends/libff"
    click LibFQFFT "https://github.com/scipr-lab/libsnark/tree/master/depends/libfqfft"
    click AtePair "https://github.com/scipr-lab/libsnark/tree/master/depends/ate-pairing"
    click Xbyak "https://github.com/scipr-lab/libsnark/tree/master/depends/xbyak"
    click Supercop "https://github.com/scipr-lab/libsnark/tree/master/depends/libsnark-supercop"
    click GTest "https://github.com/scipr-lab/libsnark/tree/master/depends/gtest"

    %% Click Events for common
    click Common "https://github.com/scipr-lab/libsnark/tree/master/libsnark/common/data_structures/"
    click Common "https://github.com/scipr-lab/libsnark/tree/master/libsnark/common/default_types/"
    click Common "https://github.com/scipr-lab/libsnark/tree/master/libsnark/common/routing_algorithms/"
    click Common "https://github.com/scipr-lab/libsnark/blob/master/libsnark/common/libsnark_serialization.hpp"
    click Common "https://github.com/scipr-lab/libsnark/tree/master/libsnark/common/routing_algorithms/tests/"

    %% Click Events for gadgetlib1
    click Gadget1 "https://github.com/scipr-lab/libsnark/blob/master/libsnark/gadgetlib1/gadget.hpp"
    click Gadget1 "https://github.com/scipr-lab/libsnark/blob/master/libsnark/gadgetlib1/protoboard.hpp"
    click Gadget1 "https://github.com/scipr-lab/libsnark/blob/master/libsnark/gadgetlib1/gadgets/basic_gadgets.*"
    click Gadget1 "https://github.com/scipr-lab/libsnark/tree/master/libsnark/gadgetlib1/gadgets/cpu_checkers/"
    click Gadget1 "https://github.com/scipr-lab/libsnark/tree/master/libsnark/gadgetlib1/gadgets/curves/"
    click Gadget1 "https://github.com/scipr-lab/libsnark/tree/master/libsnark/gadgetlib1/gadgets/hashes/"
    click Gadget1 "https://github.com/scipr-lab/libsnark/tree/master/libsnark/gadgetlib1/gadgets/pairing/"
    click Gadget1 "https://github.com/scipr-lab/libsnark/tree/master/libsnark/gadgetlib1/gadgets/routing/"
    click Gadget1 "https://github.com/scipr-lab/libsnark/tree/master/libsnark/gadgetlib1/gadgets/set_commitment/"
    click Gadget1 "https://github.com/scipr-lab/libsnark/tree/master/libsnark/gadgetlib1/gadgets/verifiers/"
    click Gadget1 "https://github.com/scipr-lab/libsnark/tree/master/libsnark/gadgetlib1/examples/"
    click Gadget1 "https://github.com/scipr-lab/libsnark/tree/master/libsnark/gadgetlib1/tests/"

    %% Click Events for gadgetlib2
    click Gadget2 "https://github.com/scipr-lab/libsnark/blob/master/libsnark/gadgetlib2/gadget.hpp"
    click Gadget2 "https://github.com/scipr-lab/libsnark/blob/master/libsnark/gadgetlib2/constraint.hpp"
    click Gadget2 "https://github.com/scipr-lab/libsnark/blob/master/libsnark/gadgetlib2/variable.hpp"
    click Gadget2 "https://github.com/scipr-lab/libsnark/blob/master/libsnark/gadgetlib2/protoboard.hpp"
    click Gadget2 "https://github.com/scipr-lab/libsnark/blob/master/libsnark/gadgetlib2/adapters.hpp"
    click Gadget2 "https://github.com/scipr-lab/libsnark/blob/master/libsnark/gadgetlib2/integration.hpp"
    click Gadget2 "https://github.com/scipr-lab/libsnark/blob/master/libsnark/gadgetlib2/pp.hpp"
    click Gadget2 "https://github.com/scipr-lab/libsnark/tree/master/libsnark/gadgetlib2/examples/"
    click Gadget2 "https://github.com/scipr-lab/libsnark/tree/master/libsnark/gadgetlib2/tests/"

    %% Click Events for relations
    click Relations "https://github.com/scipr-lab/libsnark/tree/master/libsnark/relations/arithmetic_programs/"
    click Relations "https://github.com/scipr-lab/libsnark/tree/master/libsnark/relations/circuit_satisfaction_problems/"
    click Relations "https://github.com/scipr-lab/libsnark/tree/master/libsnark/relations/constraint_satisfaction_problems/"
    click Relations "https://github.com/scipr-lab/libsnark/tree/master/libsnark/relations/ram_computations/"
    click Relations "https://github.com/scipr-lab/libsnark/blob/master/libsnark/relations/variable.*"

    %% Click Events for reductions
    click Reductions "https://github.com/scipr-lab/libsnark/tree/master/libsnark/reductions/bacs_to_r1cs/"
    click Reductions "https://github.com/scipr-lab/libsnark/tree/master/libsnark/reductions/r1cs_to_qap/"
    click Reductions "https://github.com/scipr-lab/libsnark/tree/master/libsnark/reductions/r1cs_to_sap/"
    click Reductions "https://github.com/scipr-lab/libsnark/tree/master/libsnark/reductions/ram_to_r1cs/"
    click Reductions "https://github.com/scipr-lab/libsnark/tree/master/libsnark/reductions/tbcs_to_uscs/"
    click Reductions "https://github.com/scipr-lab/libsnark/tree/master/libsnark/reductions/uscs_to_ssp/"

    %% Click Events for proof systems
    click ZK "https://github.com/scipr-lab/libsnark/tree/master/libsnark/zk_proof_systems/pcd/"
    click ZK "https://github.com/scipr-lab/libsnark/tree/master/libsnark/zk_proof_systems/ppzkadsnark/"
    click ZK "https://github.com/scipr-lab/libsnark/tree/master/libsnark/zk_proof_systems/ppzksnark/"
    click ZK "https://github.com/scipr-lab/libsnark/tree/master/libsnark/zk_proof_systems/zksnark/ram_zksnark/"

    %% Styles
    classDef external fill:#d3d3d3,stroke:#000
    classDef build fill:#d1a8f1,stroke:#000
    classDef core fill:#a8c2f1,stroke:#000
    classDef gadget fill:#b2f1a8,stroke:#000
    classDef proof fill:#f1c9a8,stroke:#000
    classDef example fill:#f1f1a8,stroke:#000
```
