# irreducibleoss/binius architecture

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

- Interactive diagram: https://gitdiagram.com/irreducibleoss/binius
- Repository: https://github.com/irreducibleoss/binius

## Overview

##### Main components
- Cryptographic Protocol Core: Represented by the “crates/core” directory, which contains the implementations of various protocols (sumcheck, fri, gkr_exp, gkr_gpa, oracle, transcript, etc.). This is the “brain” of the system that runs the cryptographic arguments.
- Circuit Building: The “crates/circuits” module encapsulates circuits logic for arithmetic, bitwise operations, lookup tables, and witness handling. It acts as the interface for building circuits that can later be proven.
- Field Arithmetic: The “crates/field” contains the logic for binary fields and various optimizations, including platform-specific implementations (e.g., GFNI support and assembly optimizations for different architectures).
- Hardware Abstraction and Optimization: The “crates/hal” (hardware abstraction layer) handles backend-specific optimizations and differences (like CPU-specific instructions and sumcheck evaluators).
- Cryptographic Hash Functions: The “crates/hash” directory provides implementations of hash algorithms (groestl, sha2, keccak, vision, etc.) that are key to commitment schemes and Fiat-Shamir transforms.
- Mathematical Utilities: “crates/math” along with “crates/m3” and “crates/macros” offer support for arithmetic expressions, composition polynomials, tensor algebra, and other gadgets used within the proofs.
- Support Utilities: Supporting libraries like “crates/utils” and “crates/maybe_rayon” offer helper functions, error handling, parallel iteration, and general purpose operations.
- Other Specialized Components: Crates like “crates/ntt” implement fast number-theoretic transforms, which are foundational for some aspects of polynomial arithmetic used in the protocols.

##### Relationships and Data Flow
- The Field module underpins almost all computations—every protocol and circuit will depend on the optimized arithmetic and field operations.
- The Core protocols (in “crates/core”) build on the functionalities provided by Field and use Hash and Fiat-Shamir (part of “core” itself) to transform and verify proofs.
- Circuit building (in “crates/circuits”) uses the Core components to define constraints and then passes witness data to the proving and verifying procedures.
- The Hardware Abstraction Layer (HAL) modulates the low-level performance optimizations and ensures that core computations take advantage of CPU features.
- Libraries like Math, M3, and Macros provide higher-level abstractions that help in expressing complex arithmetic or proof systems while “glueing” together the low-level primitives.
- Utility crates (Utils, Maybe Rayon) support parallelization and common operations which are a cross-cutting concern.

##### Architectural Patterns and Design Principles
- Layered Architecture: At the bottom, the Field and Hash libraries provide basic arithmetic and cryptographic primitives. In the middle, the Core protocols merge these primitives into complex SNARK protocols. On top, the Circuits crate and the examples provide a higher-level interface to build and execute proofs.
- Modular/Crate-Based Design: Each “crate” is a separate library with its own concern, promoting loose coupling and making it easier to test or replace components.
- Portability and Optimization: Notice that multiple architectures and parallelization techniques are considered (via “maybe_rayon”, various “arch” directories, and HAL optimizations).

##### Relevant Technologies or Frameworks
- Rust’s Cargo package management system is used extensively (each directory with a Cargo.toml is a vital component).
- Criterion is used for benchmarking.
- GitHub Actions (in .github/workflows) for CI and nightly benchmarks.
- The code also integrates with architecture-specific instruction sets like GFNI.

##### Final Advice
- Be detailed in mapping out the layered dependencies and clearly note which components depend on which others.

## Diagram (Mermaid)

```mermaid
graph TD
  %% Layer 1: Foundational Primitives
  subgraph "Layer 1: Foundational Primitives"
    A["Field Arithmetic<br>Optimized binary field operations"]:::field
    B["Cryptographic Hash Functions<br>Hash algorithms & Fiat-Shamir transforms"]:::hash
    C["Hardware Abstraction & Optimization<br>CPU-specific optimizations, GFNI support"]:::hal
    D["Support Utilities<br>Error handling & common helper functions"]:::utils
    E["Maybe Rayon<br>Parallel iteration support"]:::utils
    F["NTT<br>Fast Number-Theoretic Transforms"]:::ntt
  end

  %% Layer 2: Cryptographic Core
  subgraph "Layer 2: Cryptographic Core"
    G["Cryptographic Protocol Core<br>Implements sumcheck, FRI, GKR methods"]:::core
  end

  %% Layer 3: High-Level Abstractions
  subgraph "Layer 3: High-Level Abstractions"
    H["Circuit Building<br>Constraint definitions & witness handling"]:::circuits
    subgraph "Mathematical Utilities"
      I["Arithmetic & Polynomial Utilities"]:::mathOps
      J["Gadgets & Circuit Helpers"]:::gadgets
      K["Macros & Code Generation"]:::macros
    end
  end

  %% Dependencies from Layer 1 to Layer 2
  A -->|"provides_arithmetic_for"| G
  B -->|"supplies_hash_functions_to"| G
  C -->|"optimizes"| A
  C -->|"optimizes"| G
  D -->|"supports"| A
  D -->|"supports"| G
  E -->|"supports"| A
  E -->|"supports"| G
  F -->|"enhances"| A

  %% Dependencies from Layer 2 to Layer 3
  G -->|"used_by"| H

  %% Dependencies from Mathematical Utilities to Core and Circuits
  I -->|"aids_core_and_circuits"| G
  I -->|"aids_core_and_circuits"| H
  J -->|"aids_core_and_circuits"| G
  J -->|"aids_core_and_circuits"| H
  K -->|"aids_core_and_circuits"| G
  K -->|"aids_core_and_circuits"| H

  %% Additional dependency from Field to Mathematical Utilities
  A -->|"enables"| I

  %% Styles
  classDef field fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
  classDef hash fill:#FAD7A0,stroke:#D68910,stroke-width:2px;
  classDef hal fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
  classDef utils fill:#EBDEF0,stroke:#8E44AD,stroke-width:2px;
  classDef ntt fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
  classDef core fill:#A2D9CE,stroke:#16A085,stroke-width:2px;
  classDef circuits fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
  classDef mathOps fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
  classDef gadgets fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
  classDef macros fill:#D5F5E3,stroke:#28B463,stroke-width:2px;

  %% Click Events
  click A "https://github.com/irreducibleoss/binius/tree/main/crates/field"
  click B "https://github.com/irreducibleoss/binius/tree/main/crates/hash"
  click C "https://github.com/irreducibleoss/binius/tree/main/crates/hal"
  click D "https://github.com/irreducibleoss/binius/tree/main/crates/utils"
  click E "https://github.com/irreducibleoss/binius/tree/main/crates/maybe_rayon"
  click F "https://github.com/irreducibleoss/binius/tree/main/crates/ntt"
  click G "https://github.com/irreducibleoss/binius/tree/main/crates/core"
  click H "https://github.com/irreducibleoss/binius/tree/main/crates/circuits"
  click I "https://github.com/irreducibleoss/binius/tree/main/crates/math"
  click J "https://github.com/irreducibleoss/binius/tree/main/crates/m3"
  click K "https://github.com/irreducibleoss/binius/tree/main/crates/macros"
```
