# 0xmiden/miden-vm architecture

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

- Interactive diagram: https://gitdiagram.com/0xmiden/miden-vm
- Repository: https://github.com/0xmiden/miden-vm

## Overview

##### Project type and purpose
- Type: A poly-crate Rust library/toolchain & CLI for a STARK-based VM—and associated prover/verifier.
- Purpose:
– Assemble Miden assembly programs
– Execute them to produce a trace
– Generate a STARK proof of execution
– Verify proofs
– Provide a CLI interface for compile/run/prove/verify

##### Top-level components
a. miden (crate + CLI)
b. assembly (parser → AST → assembler → MAST → VM bytecode)
c. processor (executes bytecode → produces execution trace)
d. air (converts processor logic into Algebraic IR for STARK constraints)
e. prover (consumes trace + AIR → generates STARK proof)
f. verifier (consumes proof + AIR → verifies proof)
g. core (shared definitions: instruction set, program structure, utils)
h. stdlib (pre-built Miden libraries linked into programs)
i. test-utils (testing harness)

##### Data flows and interactions
- Source code (Miden .masm) → assembly parser (LALRPOP) → AST → assembler → MAST (module-graph) → bytecode / MidenProgram →
↳ (optional) link with stdlib → final program
- miden CLI “compile” command invokes assembly crate
- miden CLI “run” command calls processor crate → produces execution trace
- processor crate references core for instruction definitions
- miden CLI “prove” command: processor → trace → air crate → prover crate → proof output
- miden CLI “verify” command: proof + AIR code → verifier crate → boolean result
- stdlib supplies bytecode libraries to assembler and to processor at runtime
- test-utils and integration tests sit alongside to drive and verify each component

##### Architectural patterns & design principles
– Layered architecture: assembly → processor → prover/verifier
– Modularity via Cargo workspaces (each crate is independently buildable/testable)
– Clear separation of concerns: parsing, program representation (core + assembly), execution (processor), proof logic (air + prover), verification
– Plugin/host abstraction: user-provided host supplies nondeterministic inputs via a Host trait in processor/prover
– Concurrency: rayon used in prover for parallel proof generation

##### Technologies & frameworks
– Rust + Cargo workspaces
– LALRPOP for grammar/lexer in assembly
– rayon for parallelism in prover
– wasm32 targets via no-std features
– GPU/Metal backend in prover (prover/src/gpu/metal)
– Build scripts (build.rs) for stdlib and assembly crates

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Entrypoint
    Miden[/Miden CLI/]:::cli

    %% Artifacts
    Source[(.masm Source)]:::artifact
    AST[(AST)]:::artifact
    Bytecode[(Bytecode)]:::artifact
    Trace[(Execution Trace)]:::artifact
    Proof[(STARK Proof)]:::artifact
    Result[(Verification Result)]:::artifact

    %% Crate Groups
    subgraph "Compiler"
        Assembly["Assembly Crate\n(parser→AST→assembler)"]:::compile
        Core["Core Crate\n(defs & MAST)"]:::compile
    end

    subgraph "Runtime"
        Processor["Processor Crate\n(exec → trace)"]:::runtime
        Stdlib["Stdlib Crate\n(pre-built libraries)"]:::runtime
    end

    subgraph "ZK Proof"
        Air["AIR Crate\n(constraints gen)"]:::proof
        Prover["Prover Crate\n(proof gen)"]:::proof
    end

    subgraph "ZK Verify"
        Verifier["Verifier Crate\n(proof verify)"]:::verify
    end

    subgraph "Utilities"
        TestUtils["Test-Utils Crate"]:::lib
    end

    %% Data Flow
    Source -->|"parse"| Assembly
    Assembly -->|"AST"| AST
    AST -->|"assemble"| Bytecode
    Bytecode -->|"link stdlib"| Assembly
    Bytecode --> Processor
    Processor --> Trace
    Trace --> Air
    Air --> Prover
    Prover --> Proof
    Proof --> Verifier
    Verifier --> Result

    %% CLI Commands
    Miden -->|"compile"| Assembly
    Miden -->|"run"| Processor
    Miden -->|"prove"| Prover
    Miden -->|"verify"| Verifier

    %% Test Utils Integration
    TestUtils -.-> Assembly
    TestUtils -.-> Processor
    TestUtils -.-> Prover
    TestUtils -.-> Verifier

    %% Click Events
    click Miden "https://github.com/0xmiden/miden-vm/tree/next/miden/"
    click Assembly "https://github.com/0xmiden/miden-vm/tree/next/assembly/"
    click Core "https://github.com/0xmiden/miden-vm/tree/next/core/"
    click Processor "https://github.com/0xmiden/miden-vm/tree/next/processor/"
    click Stdlib "https://github.com/0xmiden/miden-vm/tree/next/stdlib/"
    click Air "https://github.com/0xmiden/miden-vm/tree/next/air/"
    click Prover "https://github.com/0xmiden/miden-vm/tree/next/prover/"
    click Verifier "https://github.com/0xmiden/miden-vm/tree/next/verifier/"
    click TestUtils "https://github.com/0xmiden/miden-vm/tree/next/test-utils/"

    %% Styles
    classDef cli fill:#ccccff,stroke:#333,stroke-width:1px
    classDef compile fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef runtime fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef proof fill:#ff99ff,stroke:#333,stroke-width:1px
    classDef verify fill:#dddddd,stroke:#333,stroke-width:1px
    classDef lib fill:#eeeeee,stroke:#333,stroke-width:1px
    classDef artifact fill:#ffffff,stroke:#666,stroke-dasharray: 5 5,stroke-width:1px
```
