# alv-around/mini-stark architecture

> Architecture diagram of the GitHub repository alv-around/mini-stark, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alv-around/mini-stark
- Repository: https://github.com/alv-around/mini-stark

## Overview

##### Project Type and Purpose
- This is a Rust library (Cargo crate) implementing a STARK prover (zero-knowledge proof system) for learning purposes.
- It is not a full-stack application, but rather a cryptographic tool/library, organized into modules that correspond to each stage of the STARK protocol (AIR, Merkle commitments, FRI, Fiat–Shamir, etc.).

##### High-Level Architecture Analysis
- Top-level crates and folders:
- Cargo.toml, src/ → core Rust modules
- scripts/ → Python/Jupyter notebooks and helper scripts demonstrating usage (fibonacci_air_example.ipynb, merkle_tree.py)
- tests/ → end-to-end Rust tests (e2e.rs)
- Core modules in src/:
- field.rs → finite field arithmetic (Goldilocks field and extensions)
- air.rs → Algebraic Intermediate Representation (AIR) arithmetization of computation traces
- fri.rs → implementation of the FRI low-degree testing protocol
- fiatshamir.rs → Fiat–Shamir transform for non-interactive proof generation
- merkle.rs → Merkle tree commitments over polynomial evaluations
- starks.rs → orchestration of the full STARK PIOP: from trace to proof
- util.rs, error.rs → helpers and error handling

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Prover Pipeline
    subgraph "Prover Pipeline"
        direction TB
        Client[/Client/Prover/]:::io
        Client --> AIR
        AIR["AIR Module"]:::air
        AIR --> Trace["Execution Trace & Constraints"]:::data
        Trace --> Eval["Interpolation & Evaluation"]:::interp
        Eval --> Merkle
        Merkle["Merkle Tree Commitments"]:::commit
        Merkle -->|Merkle Root| FS
        FS["Fiat–Shamir Transform"]:::fiat
        FS -->|Challenges r_i| FRI
        FRI["FRI Module"]:::fri
        FRI -->|FRI Layers| STARK
        STARK["STARK Proof Orchestration"]:::orchestrate
        STARK --> Proof[/Proof Output/]:::io
    end

    %% Verifier Pipeline
    subgraph "Verifier Pipeline"
        direction TB
        Proof --> Verify["Verifier (Merkle & FRI Checks)"]:::verify
        Verify --> Verdict[/Accept or Reject/]:::io
    end

    %% Core Modules
    subgraph "Core Modules"
        direction TB
        Field["Field Arithmetic Module"]:::algebra
        Util["Utility Helpers Module"]:::support
        Error["Error Handling Module"]:::support
    end

    %% Library Entry & Config
    subgraph "Library Setup"
        direction TB
        Entry["Library Entry Point"]:::setup
        Config["Package Configuration & Dependencies"]:::setup
    end

    %% Example Scripts
    subgraph "Example & Tests"
        direction TB
        Notebook[/fibonacci_air_example.ipynb/]:::script
        Demo[/merkle_tree.py/]:::script
        E2E[/End-to-End Tests/ e2e.rs/]:::script
    end

    %% Relationships
    Entry -->|imports| Field
    Entry -->|imports| AIR
    Entry -->|imports| merkle
    Entry -->|imports| fri
    Entry -->|imports| fiat
    Entry -->|imports| starks
    Entry -->|imports| Util
    Entry -->|imports| Error

    Notebook -->|uses| Client
    Demo -->|uses| Merkle
    E2E -->|tests| STARK

    %% Click Events
    click Field "https://github.com/alv-around/mini-stark/blob/main/src/field.rs"
    click AIR "https://github.com/alv-around/mini-stark/blob/main/src/air.rs"
    click Merkle "https://github.com/alv-around/mini-stark/blob/main/src/merkle.rs"
    click FRI "https://github.com/alv-around/mini-stark/blob/main/src/fri.rs"
    click FS "https://github.com/alv-around/mini-stark/blob/main/src/fiatshamir.rs"
    click STARK "https://github.com/alv-around/mini-stark/blob/main/src/starks.rs"
    click Util "https://github.com/alv-around/mini-stark/blob/main/src/util.rs"
    click Error "https://github.com/alv-around/mini-stark/blob/main/src/error.rs"
    click Entry "https://github.com/alv-around/mini-stark/blob/main/src/lib.rs"
    click Config "https://github.com/alv-around/mini-stark/blob/main/Cargo.toml"
    click Notebook "https://github.com/alv-around/mini-stark/blob/main/scripts/fibonacci_air_example.ipynb"
    click Demo "https://github.com/alv-around/mini-stark/blob/main/scripts/merkle_tree.py"
    click E2E "https://github.com/alv-around/mini-stark/blob/main/tests/e2e.rs"

    %% Styles
    classDef io fill:#f9f,stroke:#333,stroke-width:1px;
    classDef air fill:#d0e1f9,stroke:#333,stroke-width:1px;
    classDef data fill:#fef3c7,stroke:#333,stroke-width:1px;
    classDef interp fill:#d0e1f9,stroke:#333,stroke-width:1px;
    classDef commit fill:#c7f3d4,stroke:#333,stroke-width:1px;
    classDef fiat fill:#f3d4c7,stroke:#333,stroke-width:1px;
    classDef fri fill:#e1d0f9,stroke:#333,stroke-width:1px;
    classDef orchestrate fill:#f9d0d0,stroke:#333,stroke-width:1px;
    classDef verify fill:#f3c7e1,stroke:#333,stroke-width:1px;
    classDef algebra fill:#d0f9d6,stroke:#333,stroke-width:1px;
    classDef support fill:#e0e0e0,stroke:#333,stroke-width:1px;
    classDef setup fill:#f0f0f9,stroke:#333,stroke-width:1px;
    classDef script fill:#fff0b3,stroke:#333,stroke-width:1px;
```
