# facebook/winterfell architecture

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

- Interactive diagram: https://gitdiagram.com/facebook/winterfell
- Repository: https://github.com/facebook/winterfell

## Overview

##### Project type and purpose
- This is a Rust workspace implementing an open-source STARK proof system (Winterfell).
- It provides:
- A DSL for describing computations (AIR)
- A multi-threaded STARK prover
- A STARK verifier
- Underlying FRI protocol implementation
- Math and crypto building blocks (fields, FFTs, hashes, Merkle trees)
- A top-level crate (`winterfell`) that re-exports prover & verifier
- Example clients demonstrating usage

##### File structure
Top-level directories (all are independent Cargo crates, linked by the workspace):
- air/            – Algebraic Intermediate Representation engine
- prover/         – STARK prover implementation
- verifier/       – STARK verifier implementation
- fri/            – FRI prover & verifier
- math/           – Finite-field, polynomial, FFT code
- crypto/         – Hash functions, Merkle trees, random coin
- utils/          – Shared traits & utilities across all crates
- winterfell/     – Facade crate re-exporting prover & verifier
- examples/       – Sample applications built atop `winterfell`
Supporting files:
- Root Cargo.toml, Makefile, CI configs, scripts/publish-crates.sh

##### README for additional insights
- Confirms modular structure and responsibilities of each crate.
- Describes multi-threaded proof generation, configurable hashes/fields, async support.
- Emphasizes research status, usage patterns, and performance characteristics.

##### Components, relationships, and patterns
1. Core Layer (bottom):
- utils
- math
- crypto
2. Computation description:
- air
3. Proof engines:
- fri
- prover
- verifier
4. Facade:
- winterfell
5. Client code:
- examples
- prover → {air, fri, math, crypto, utils}
- verifier → {air, fri, math, crypto, utils}
- fri → {math, utils}
- crypto → {utils, math}
- air → {utils, math}
- winterfell → {prover, verifier}
- examples → {winterfell}
c. Architectural patterns & design principles:
- Layered modular architecture: core libraries → computation DSL → proof pipeline → facade → clients
- Clear separation of concerns (e.g., FRI as a standalone protocol submodule)
- Trait‐based extensibility (Prover, Air, HashFunction, FieldElement)
- Concurrency built into the prover via `concurrent` feature
d. Key technologies & frameworks:
- Rust workspace & Cargo
- Multi-crate modularization
- WebAssembly compatibility (`no-std` optional)
- Common Rust features: traits, generics, async (via feature flag)

##### Final advice
- Every crate as a component, show its upstream and downstream dependencies.
- Flow of a proof:
(examples) → winterfell API → Prover → (uses air to interpret computation, math+crypto to build trace commitments, fri submodule for low-degree tests) → produces Proof → Verifier → (reuses same building blocks) → verification result

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        examples["examples"]:::client
    end

    %% Facade Layer
    subgraph "Facade Layer"
        winterfell["winterfell"]:::facade
    end

    %% Proof Engines Layer
    subgraph "Proof Engines Layer"
        prover["prover"]:::proof
        verifier["verifier"]:::proof
    end

    %% Protocols & DSL Layer
    subgraph "Protocols & DSL Layer"
        fri["fri"]:::computation
        air["air"]:::computation
    end

    %% Core Libraries Layer
    subgraph "Core Libraries Layer"
        utils["utils"]:::core
        math["math"]:::core
        crypto["crypto"]:::core
    end

    %% Dependencies
    examples -->|"uses"| winterfell
    winterfell -->|"re-exports"| prover
    winterfell -->|"re-exports"| verifier

    prover -->|"depends on"| air
    prover -->|"depends on"| fri
    prover -->|"depends on"| math
    prover -->|"depends on"| crypto
    prover -->|"depends on"| utils

    verifier -->|"depends on"| air
    verifier -->|"depends on"| fri
    verifier -->|"depends on"| math
    verifier -->|"depends on"| crypto
    verifier -->|"depends on"| utils

    air -->|"depends on"| math
    air -->|"depends on"| utils

    fri -->|"depends on"| math
    fri -->|"depends on"| utils

    crypto -->|"depends on"| math
    crypto -->|"depends on"| utils

    %% Click Events
    click utils "https://github.com/facebook/winterfell/tree/main/utils"
    click math "https://github.com/facebook/winterfell/tree/main/math"
    click crypto "https://github.com/facebook/winterfell/tree/main/crypto"
    click air "https://github.com/facebook/winterfell/tree/main/air"
    click fri "https://github.com/facebook/winterfell/tree/main/fri"
    click prover "https://github.com/facebook/winterfell/tree/main/prover"
    click verifier "https://github.com/facebook/winterfell/tree/main/verifier"
    click winterfell "https://github.com/facebook/winterfell/tree/main/winterfell"
    click examples "https://github.com/facebook/winterfell/tree/main/examples"

    %% Styles
    classDef core fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef computation fill:#cfe2f3,stroke:#333,stroke-width:1px
    classDef proof fill:#d9ead3,stroke:#333,stroke-width:1px
    classDef facade fill:#f9cb9c,stroke:#333,stroke-width:1px
    classDef client fill:#ffe599,stroke:#333,stroke-width:1px
```
