# sunblaze-ucb/libra architecture

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

- Interactive diagram: https://gitdiagram.com/sunblaze-ucb/libra
- Repository: https://github.com/sunblaze-ucb/libra

## Overview

##### Main Components
- Core Library Modules:
- VPD: Contains files in both “include/VPD” and “src/VPD”. This module likely handles verifiable computation or proofs related to polynomial delegation.
- Linear GKR: Located under “include/linear_gkr” and “src/linear_gkr”. Contains the implementations (including several “prover” and “verifier” variants) for interactive proofs using the linear approach.
- Traditional GKR: Found in “include/traditional_gkr” and “src/traditional_gkr”. This module provides an alternative (traditional) implementation approach for the GKR protocol.
- Binary Executables:
- The “bin” directory holds several compiled programs (e.g., main_zk, various “clogc” and “bclogc” versions) that serve as entry points to run experiments or demonstrations of these protocols.
- Testing Components:
- Tests for specific algorithms (SHA256, Lanczos, and Matmul) are organized under the “tests” directory with their own build scripts and Python runners.
- Auxiliary/Supporting Components:
- Build scripts (e.g., Makefile, setup.sh, and various Python “build.py” scripts in the tests) indicate integration/compilation procedures.
- Helper code in the “include/infrastructure” directory.

##### Relationships and Data Flow
- The binary executables in “bin” likely depend on the core library modules to perform the proof computations.
- The “src” code implements the actual logic of the protocols which get exposed via header files in “include”.
- The tests in “tests” call into the core modules (for instance, running SHA256 or Lanczos tests) by invoking the corresponding binaries or test runners.
- Build scripts and configuration files (like the Makefile and Python build scripts) orchestrate the building and testing processes.

##### Architectural Patterns and Design Principles
- Component Separation: The project is cleanly segmented into libraries (core protocols) and test suites—this indicates a layered architecture.
- Modular Design: VPD, linear GKR, and traditional GKR are isolated modules. This suggests modularity and possible reusability of the proof components.
- Clear Interfaces: The headers (in “include”) define a clear API for components, and the existence of different “prover” and “verifier” variants hints at an interface-based design.
- Test-Driven/Experiment-Driven: The presence of comprehensive test directories (with build and run scripts) means the design incorporates automated testing as an integral component.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Core Library Modules
    subgraph "Core Library Modules"
        VPD_H["VPD Module (Header Files)"]:::library
        VPD_I["VPD Module (Implementation)"]:::library
        LKG_H["Linear GKR (Header Files)"]:::library
        LKG_I["Linear GKR (Implementation)"]:::library
        TGKR_H["Traditional GKR (Header Files)"]:::library
        TGKR_I["Traditional GKR (Implementation)"]:::library
        INF["Infrastructure Helpers"]:::library
    end

    %% Binary Executables
    subgraph "Binary Executables"
        BIN["Executable Programs"]:::executable
    end

    %% Test Suites
    subgraph "SHA256 Test Suite"
        SHA256_DIR["SHA256 Test Directory"]:::test
        SHA256_BuildPy["build.py"]:::test
        SHA256_BuildSh["build.sh"]:::test
        SHA256_Run["run.py"]:::test
    end

    subgraph "Lanczos Test Suite"
        LANCZOS_DIR["Lanczos Test Directory"]:::test
        LANCZOS_BuildPy["build.py"]:::test
        LANCZOS_BuildSh["build.sh"]:::test
        LANCZOS_Run["run.py"]:::test
    end

    subgraph "Matmul Test Suite"
        MATMUL_DIR["Matmul Test Directory"]:::test
        MATMUL_BuildPy["build.py"]:::test
        MATMUL_Gen["gen.cpp"]:::test
        MATMUL_Run["run.py"]:::test
    end

    %% Build and Auxiliary Scripts
    subgraph "Build and Auxiliary Scripts"
        MAKEFILE["Makefile"]:::build
        SETUP["setup.sh"]:::build
    end

    %% Relationships between Core Modules and Binary Executables
    BIN -->|"calls"| VPD_H
    BIN -->|"calls"| LKG_H
    BIN -->|"calls"| TGKR_H
    BIN -->|"uses"| INF

    %% Relationships within Test Suites
    SHA256_DIR -->|"contains"| SHA256_BuildPy
    SHA256_DIR -->|"contains"| SHA256_BuildSh
    SHA256_DIR -->|"contains"| SHA256_Run

    LANCZOS_DIR -->|"contains"| LANCZOS_BuildPy
    LANCZOS_DIR -->|"contains"| LANCZOS_BuildSh
    LANCZOS_DIR -->|"contains"| LANCZOS_Run

    MATMUL_DIR -->|"contains"| MATMUL_BuildPy
    MATMUL_DIR -->|"contains"| MATMUL_Gen
    MATMUL_DIR -->|"contains"| MATMUL_Run

    %% Test Suites trigger Binary Executables
    SHA256_Run -->|"triggers"| BIN
    LANCZOS_Run -->|"triggers"| BIN
    MATMUL_Run -->|"triggers"| BIN

    %% Build Scripts orchestrate build process
    MAKEFILE -->|"orchestrates"| BIN
    SETUP -->|"deploys"| BIN

    %% Styling for vertical layout hints by grouping
    classDef library fill:#E8F8F5,stroke:#1F618D,stroke-width:2px;
    classDef executable fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef test fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef build fill:#FAD7A0,stroke:#D68910,stroke-width:2px;

    %% Click Events for Core Library Modules
    click VPD_H "https://github.com/sunblaze-ucb/libra/tree/Libra/include/VPD/"
    click VPD_I "https://github.com/sunblaze-ucb/libra/tree/Libra/src/VPD/"
    click LKG_H "https://github.com/sunblaze-ucb/libra/tree/Libra/include/linear_gkr/"
    click LKG_I "https://github.com/sunblaze-ucb/libra/tree/Libra/src/linear_gkr/"
    click TGKR_H "https://github.com/sunblaze-ucb/libra/tree/Libra/include/traditional_gkr/"
    click TGKR_I "https://github.com/sunblaze-ucb/libra/tree/Libra/src/traditional_gkr/"
    click INF "https://github.com/sunblaze-ucb/libra/tree/Libra/include/infrastructure/"

    %% Click Events for Binary Executables
    click BIN "https://github.com/sunblaze-ucb/libra/tree/Libra/bin/"

    %% Click Events for SHA256 Test Suite
    click SHA256_DIR "https://github.com/sunblaze-ucb/libra/tree/Libra/tests/SHA256/"
    click SHA256_BuildPy "https://github.com/sunblaze-ucb/libra/blob/Libra/tests/SHA256/build.py"
    click SHA256_BuildSh "https://github.com/sunblaze-ucb/libra/blob/Libra/tests/SHA256/build.sh"
    click SHA256_Run "https://github.com/sunblaze-ucb/libra/blob/Libra/tests/SHA256/run.py"

    %% Click Events for Lanczos Test Suite
    click LANCZOS_DIR "https://github.com/sunblaze-ucb/libra/tree/Libra/tests/lanczos/"
    click LANCZOS_BuildPy "https://github.com/sunblaze-ucb/libra/blob/Libra/tests/lanczos/build.py"
    click LANCZOS_BuildSh "https://github.com/sunblaze-ucb/libra/blob/Libra/tests/lanczos/build.sh"
    click LANCZOS_Run "https://github.com/sunblaze-ucb/libra/blob/Libra/tests/lanczos/run.py"

    %% Click Events for Matmul Test Suite
    click MATMUL_DIR "https://github.com/sunblaze-ucb/libra/tree/Libra/tests/matmul/"
    click MATMUL_BuildPy "https://github.com/sunblaze-ucb/libra/blob/Libra/tests/matmul/build.py"
    click MATMUL_Gen "https://github.com/sunblaze-ucb/libra/blob/Libra/tests/matmul/gen.cpp"
    click MATMUL_Run "https://github.com/sunblaze-ucb/libra/blob/Libra/tests/matmul/run.py"

    %% Click Events for Build and Auxiliary Scripts
    click MAKEFILE "https://github.com/sunblaze-ucb/libra/tree/Libra/Makefile"
    click SETUP "https://github.com/sunblaze-ucb/libra/blob/Libra/setup.sh"
```
