# tritonvm/triton-vm architecture

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

- Interactive diagram: https://gitdiagram.com/tritonvm/triton-vm
- Repository: https://github.com/tritonvm/triton-vm

## Overview

##### Project type and purpose
- Triton VM is an open-source, multi-crate Rust library implementing a Turing-complete virtual machine with recursive STARK proofs. It provides:
- An Instruction Set Architecture (ISA) and parser (crate: triton-isa)
- Algebraic Intermediate Representation (AIR) generation (crate: triton-air)
- A code-generation pipeline to compile AIR constraints into Rust for maximum runtime speed (crates: triton-constraint-builder and triton-constraint-circuit)
- The VM runtime itself with embedded STARK proof generation & verification (crate: triton-vm), depending on the twenty-first cryptographic library.
- It is not a client-server or UI application; it is a library/toolchain for high-integrity computation.

##### File structure
- Top-level:
- specification/ – mdBook source for the formal spec (offline docs)
- tips/ – design tips and reference papers
- triton-isa/, triton-air/, triton-constraint-builder/, triton-constraint-circuit/, triton-vm/ – five Rust crates.
- Build scripts & CI configs under .github/workflows.
- Cargo.toml links the workspace; each crate has its own Cargo.toml and README.
- Pattern: a compile-time pipeline (constraint builder + circuit) feeding into a runtime library (tvm).

##### README
- Describes the VM’s role in generating and recursively verifying STARKs.
- Points to the online spec (mdBook) and examples in triton-vm/examples.
- Emphasizes that the STARK engine is embedded in triton-vm, not in twenty-first.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Compile-time crates
    subgraph "Compile-Time Crates"
        direction TB
        ISA["Triton-ISA\n(Instruction Set & Parser)"]:::compile
        AIR["Triton-AIR\n(AIR Constraint Definitions)"]:::compile
        Builder["Triton-Constraint-Builder\n(Codegen for AIR)"]:::compile
        Circuit["Triton-Constraint-Circuit\n(Circuit Assembler/Optimizer)"]:::compile
    end

    %% Runtime modules
    subgraph "VM Runtime Modules"
        direction TB
        Parser["Parser & Instruction Scheduler"]:::runtime
        ExecEngine["Execution Engine"]:::runtime
        AET["AET (Algebraic Execution Table)"]:::data
        AIRMod["AIR Module\n(Generated Constraints)"]:::runtime
        STARK["STARK Engine\n(Proof Gen & Verifier)"]:::runtime
        Verifier["Verifier (Recursive Loop)"]:::runtime
    end

    %% External interfaces
    subgraph "External Interfaces"
        direction TB
        CLI["Triton CLI/TUI"]:::external
        Spec["mdBook Spec (Docs)"]:::external
    end

    %% Data flow and dependencies
    ISA -->|"uses definitions"| Builder
    AIR -->|"uses tables"| Builder
    Builder -->|"generates Rust code"| Circuit
    Circuit -->|"optimized code embedded"| AIRMod
    AIRMod -->|"included in"| STARK

    CLI -->|"invokes"| Parser
    Parser -->|"parses program"| ExecEngine
    ExecEngine -->|"produces trace"| AET
    AET -->|"feeds constraints"| AIRMod
    AIRMod -->|"provides constraints"| STARK
    STARK -->|"produces proof"| Verifier
    Verifier -->|"verifies proof"| STARK

    STARK ---|"depends on (crypto)"| TwentyFirst["twenty-first"]:::external

    Spec -->|"documentation"| CLI

    %% Click events for component mappings
    click ISA "https://github.com/tritonvm/triton-vm/blob/master/triton-isa/Cargo.toml"
    click ISA "https://github.com/tritonvm/triton-vm/blob/master/triton-isa/src/lib.rs"
    click ISA "https://github.com/tritonvm/triton-vm/blob/master/triton-isa/src/parser.rs"
    click ISA "https://github.com/tritonvm/triton-vm/blob/master/triton-isa/src/instruction.rs"

    click AIR "https://github.com/tritonvm/triton-vm/blob/master/triton-air/Cargo.toml"
    click AIR "https://github.com/tritonvm/triton-vm/blob/master/triton-air/src/lib.rs"
    click AIR "https://github.com/tritonvm/triton-vm/blob/master/triton-air/src/table.rs"
    click AIR "https://github.com/tritonvm/triton-vm/blob/master/triton-air/src/cross_table_argument.rs"

    click Builder "https://github.com/tritonvm/triton-vm/blob/master/triton-constraint-builder/Cargo.toml"
    click Builder "https://github.com/tritonvm/triton-vm/blob/master/triton-constraint-builder/src/lib.rs"
    click Builder "https://github.com/tritonvm/triton-vm/blob/master/triton-constraint-builder/src/codegen.rs"
    click Builder "https://github.com/tritonvm/triton-vm/blob/master/triton-constraint-builder/src/substitutions.rs"

    click Circuit "https://github.com/tritonvm/triton-vm/blob/master/triton-constraint-circuit/Cargo.toml"
    click Circuit "https://github.com/tritonvm/triton-vm/blob/master/triton-constraint-circuit/src/lib.rs"

    click Parser "https://github.com/tritonvm/triton-vm/blob/master/triton-vm/src/vm.rs"
    click ExecEngine "https://github.com/tritonvm/triton-vm/blob/master/triton-vm/src/vm.rs"
    click AET "https://github.com/tritonvm/triton-vm/blob/master/triton-vm/src/aet.rs"
    click AIRMod "https://github.com/tritonvm/triton-vm/blob/master/triton-vm/src/constraints.rs"
    click AIRMod "https://github.com/tritonvm/triton-vm/blob/master/triton-vm/src/challenges.rs"
    click STARK "https://github.com/tritonvm/triton-vm/blob/master/triton-vm/src/proof.rs"
    click STARK "https://github.com/tritonvm/triton-vm/blob/master/triton-vm/src/proof_item.rs"
    click STARK "https://github.com/tritonvm/triton-vm/blob/master/triton-vm/src/proof_stream.rs"
    click STARK "https://github.com/tritonvm/triton-vm/blob/master/triton-vm/src/stark.rs"
    click STARK "https://github.com/tritonvm/triton-vm/blob/master/triton-vm/src/fri.rs"

    click CLI "https://github.com/tritonvm/triton-vm/blob/master/triton-vm/examples/factorial.rs"
    click Spec "https://github.com/tritonvm/triton-vm/blob/master/specification/book.toml"
    click Spec "https://github.com/tritonvm/triton-vm/blob/master/specification/src/SUMMARY.md"
    click Spec "https://github.com/tritonvm/triton-vm/blob/master/specification/src/."

    %% Styles
    classDef compile fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef runtime fill:#ccf,stroke:#333,stroke-width:1px
    classDef external fill:#cfc,stroke:#333,stroke-width:1px
    classDef data fill:#ffe4b3,stroke:#333,stroke-width:1px
```
