# starkware-libs/stwo architecture

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

- Interactive diagram: https://gitdiagram.com/starkware-libs/stwo
- Repository: https://github.com/starkware-libs/stwo

## Overview

##### Project type and purpose
- This is a Rust workspace hosting a multi-crate library and toolchain for generating and verifying CSTARK proofs.
- The main deliverable is the `stwo` crate (the core prover/verifier) plus an optional no_std verifier binary (`ensure-verifier-no_std`).
- Supporting crates provide utilities (`air-utils`), derive-macro code generation (`air-utils-derive`), a constraint-framework, no_std shims, and example/benchmark code.

##### File structure
- Top-level
- Workspace manifest (`Cargo.toml`, `WORKSPACE`), CI/config files under `.github/`, helper scripts.
- `crates/` folder
- air-utils-derive: Rust derive macros for allocation/iteration boilerplate
- air-utils: runtime data structures and trace utilities
- constraint-framework: core abstractions for constraints, component evaluators, CPU & SIMD provers
- examples: demo implementations and benches (Poseidon, Blake, PLONK, etc.)
- std-shims: minimal std library replacements for no_std environments
- stwo: the heart of the system (core logic, prover modules, channel, tracing)
- Top-level binary
- -verifier-no_std: CLI app producing a no_std-compatible verifier
- Config and tooling
- Scripts for benchmarks, clippy, fmt; GitHub Actions workflows for CI/benchmarks/coverage.

##### README for insights
- Confirms it is a next-generation CSTARK prover/verifier library in Rust.
- Emphasizes performance (CPU & SIMD backends), flexibility, and ongoing development status.
- Points to benchmark scripts and hosted benchmark visualizations.

##### Main components and their interactions
a. Components
- Sub-libraries:
– air-utils-derive
– air-utils
– constraint-framework
– std-shims
- Core library: stwo
- Binary: ensure-verifier-no_std
- Examples & Benchmark harness
- CI/CD & tooling (GitHub Actions, Cargo, codecov)
b. Dependencies / interactions
- air-utils-derive → generates code used by air-utils & constraint-framework
- air-utils & constraint-framework → foundational data structures & algorithms
- stwo → depends on air-utils, constraint-framework, std-shims for its core modules (core, prover, channel, tracing)
- -verifier-no_std → depends on stwo & std-shims to build a compact verifier binary
- examples → import stwo, air-utils, and constraint-framework to demonstrate usage
- CI workflows pull everything together: build, test, bench, coverage
c. Architectural patterns and principles
- Layered library architecture (derive macros → utilities → framework → core)
- Plug-in backends (CPU & SIMD) behind unified prover interfaces
- Zero-std compatibility via `std-shims` and feature flags
- Monorepo workspace for tightly coupled crates with shared versioning
d. Key technologies
- Rust Cargo workspaces
- Procedural macros (derive)
- SIMD & multi-threading for performance
- CI with GitHub Actions and codecov
- Shell scripts for benchmarks & code hygiene

##### Putting it all together
- Start at the bottom with `air-utils-derive` and `std-shims`.
- Above them place `air-utils` and `constraint-framework`.
- Above those, center `stwo` (core library).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Bottom layer: Macros and shims
    subgraph "Foundation Layer"
        direction TB
        AMDerive["air-utils-derive"]:::macros
        StdShims["std-shims"]:::stdshims
    end

    %% Middle layer: Utilities and Framework
    subgraph "Utility & Framework Layer"
        direction TB
        AirUtils["air-utils"]:::utils
        ConstraintFW["constraint-framework"]:::framework
    end

    %% Core library
    subgraph "Core Layer"
        direction TB
        STwo["stwo (core library)"]:::core
    end

    %% Top layer: Binary and Examples
    subgraph "Application Layer"
        direction TB
        NoStdVerifier["ensure-verifier-no_std"]:::binary
        Examples["Examples & Benchmarks"]:::examples
    end

    %% External CI/CD
    CI[/"CI/CD Workflows"/]:::ci
    Scripts[(Scripts)]:::scripts
    Manifests[(Workspace Manifests)]:::manifests

    %% Dependencies
    AirUtils -->|depends on| AMDerive
    ConstraintFW -->|depends on| AMDerive
    STwo -->|depends on| AirUtils
    STwo -->|depends on| ConstraintFW
    STwo -->|depends on| StdShims
    NoStdVerifier -->|depends on| STwo
    NoStdVerifier -->|depends on| StdShims
    Examples -->|uses| STwo
    Examples -->|uses| AirUtils
    Examples -->|uses| ConstraintFW

    CI -->|triggers build/test/bench| Manifests
    CI -->|runs scripts| Scripts
    CI -->|builds workspace| STwo

    %% Click events for component mapping
    click AMDerive "https://github.com/starkware-libs/stwo/tree/dev/crates/air-utils-derive"
    click AirUtils "https://github.com/starkware-libs/stwo/tree/dev/crates/air-utils"
    click ConstraintFW "https://github.com/starkware-libs/stwo/tree/dev/crates/constraint-framework"
    click StdShims "https://github.com/starkware-libs/stwo/tree/dev/crates/std-shims"
    click STwo "https://github.com/starkware-libs/stwo/tree/dev/crates/stwo"
    click NoStdVerifier "https://github.com/starkware-libs/stwo/tree/dev/ensure-verifier-no_std"
    click Examples "https://github.com/starkware-libs/stwo/tree/dev/crates/examples"
    click CI "https://github.com/starkware-libs/stwo/tree/dev/.github/workflows"
    click Scripts "https://github.com/starkware-libs/stwo/tree/dev/scripts"
    click Manifests "https://github.com/starkware-libs/stwo/blob/dev/Cargo.toml"

    %% Styling
    classDef macros fill:#FFDDC1,stroke:#E69A68,stroke-width:2px
    classDef stdshims fill:#FFF2AC,stroke:#D4B354,stroke-width:2px
    classDef utils fill:#D0E8F2,stroke:#5698C4,stroke-width:2px
    classDef framework fill:#C9E4CA,stroke:#5B9F73,stroke-width:2px
    classDef core fill:#E4D0F2,stroke:#9257C4,stroke-width:2px
    classDef binary fill:#F2D0D0,stroke:#C45757,stroke-width:2px
    classDef examples fill:#DCE4F2,stroke:#5A68C4,stroke-width:2px
    classDef ci fill:#F0F0F0,stroke:#A0A0A0,stroke-width:2px,stroke-dasharray: 5 5
    classDef scripts fill:#F8E1C1,stroke:#C48F57,stroke-width:2px,stroke-dasharray: 5 5
    classDef manifests fill:#E1F8E2,stroke:#57C485,stroke-width:2px,stroke-dasharray: 5 5
```
