# lambdaclass/cairo-vm architecture

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

- Interactive diagram: https://gitdiagram.com/lambdaclass/cairo-vm
- Repository: https://github.com/lambdaclass/cairo-vm

## Overview

##### Project type and purpose
- This is a compiler/interpreter–style project: a complete, production-grade implementation of the Cairo Virtual Machine (VM) in Rust.
- It exposes a CLI (`cairo-vm-cli`), a tracing UI (`cairo-vm-tracer`), a Cairo-1 runner (`cairo1-run`), a fuzzing harness (`fuzzer`), benchmark drivers (`bench`), and library crates (`vm`, `corelib`, etc.).
- Its goal is to load and execute Cairo programs (compiled JSON), process hints via pluggable hint-processors, and produce outputs/traces/air inputs for proof generation.

##### File structure
Top-level crates and directories:
- vm: the core VM library
- cairo-vm-cli: command-line interface
- cairo-vm-tracer: web-based trace visualizer
- cairo1-run: runner for Cairo-1 programs
- fuzzer: fuzz-testing harness
- bench: Criterion and IAI benchmarks
- corelib: standard Cairo builtins library
- -no_std: no_std compatibility demo
- examples: custom hints, hyper-threading, WASM demo
- docs, scripts, install-scripts, tests, CI workflows
– program loading & serde
– CairoRunner (execution engine)
– HintProcessor (builtin & Cairo-1 implementations)
– memory & segment manager
– builtin runners (bitwise, hash, ecdsa, keccak, etc.)
– tracing, AIR input/output, context & decoding, error types

##### README for additional insights
- It describes the user-facing workflow: compile `.cairo` → JSON → run via CLI → optional flags for trace, memory dump, proof_mode, AIR inputs.
- Explains the HintProcessor interface for extending hints.
- Mentions WebAssembly demo, dynamic layouts, testing and benchmarking workflows.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Subgraphs for executables
    subgraph "CLI & Runners"
        CLI["cairo-vm-cli CLI"]:::exe
        CR["cairo1-run Runner"]:::exe
    end
    click CLI "https://github.com/lambdaclass/cairo-vm/blob/main/cairo-vm-cli/src/main.rs"
    click CR "https://github.com/lambdaclass/cairo-vm/blob/main/cairo1-run/src/main.rs"

    %% Core VM library and modules
    subgraph "Core VM Library (vm crate)"
        VM["vm crate"]:::lib
        PL["Program Loader & Serializer"]:::lib
        CRu["CairoRunner (Execution Engine)"]:::lib
        HP["Hint Processor Interface"]:::lib
        MSM["Memory & Segment Manager"]:::lib
        BR["Builtin Runners"]:::lib
        TA["Trace Generator & AIR I/O"]:::lib
    end
    click VM "https://github.com/lambdaclass/cairo-vm/blob/main/vm/src/lib.rs"
    click CRu "https://github.com/lambdaclass/cairo-vm/blob/main/vm/src/vm/runners/cairo_runner.rs"
    click HP "https://github.com/lambdaclass/cairo-vm/blob/main/vm/src/hint_processor/mod.rs"
    click MSM "https://github.com/lambdaclass/cairo-vm/blob/main/vm/src/vm/vm_memory/memory.rs"
    click BR "https://github.com/lambdaclass/cairo-vm/blob/main/vm/src/vm/runners/builtin_runner/mod.rs"
    click TA "https://github.com/lambdaclass/cairo-vm/blob/main/vm/src/vm/trace/mod.rs"

    %% Tracer UI
    subgraph "Tracer UI"
        TrUI["cairo-vm-tracer"]:::exe
    end
    click TrUI "https://github.com/lambdaclass/cairo-vm/blob/main/cairo-vm-tracer/src/tracer.rs"

    %% Fuzzer harness
    subgraph "Fuzzing Harness"
        Fz["fuzzer"]:::tool
    end
    click Fz "https://github.com/lambdaclass/cairo-vm/blob/main/fuzzer/src/cairo_compiled_programs_fuzzer.rs"

    %% Benchmark drivers
    subgraph "Benchmark Drivers"
        B1["Criterion Benchmarks"]:::tool
        B2["IAI Benchmarks"]:::tool
    end
    click B1 "https://github.com/lambdaclass/cairo-vm/blob/main/bench/criterion_benchmark.rs"
    click B2 "https://github.com/lambdaclass/cairo-vm/blob/main/bench/iai_benchmark.rs"

    %% Core library of builtins
    Core["corelib"]:::lib
    click Core "https://github.com/lambdaclass/cairo-vm/tree/main/corelib/"

    %% Examples and demos
    subgraph "Examples & Demos"
        WASM["WASM Demo"]:::tool
        CH["Custom Hint Example"]:::tool
        HT["Hyper-threading Example"]:::tool
        ENS["no_std Compatibility Demo"]:::tool
    end
    click WASM "https://github.com/lambdaclass/cairo-vm/blob/main/examples/wasm-demo/src/lib.rs"
    click CH "https://github.com/lambdaclass/cairo-vm/blob/main/examples/custom_hint/src/main.rs"
    click HT "https://github.com/lambdaclass/cairo-vm/blob/main/examples/hyper_threading/src/main.rs"
    click ENS "https://github.com/lambdaclass/cairo-vm/blob/main/ensure-no_std/src/main.rs"

    %% External tools
    subgraph "External Tools & Integrations"
        CC["cairo-compile (Python)"]:::ext
        WH["WASM Host (wasm-bindgen)"]:::ext
    end

    %% Data flows and dependencies
    CC -->|"produces JSON"| CLI
    CLI -->|"loads JSON"| PL
    PL -->|deserialized| VM
    VM -->|"executes via CairoRunner"| CRu
    CRu -->|"uses"| MSM
    CRu -->|"invokes"| BR
    VM -->|"calls"| HP
    HP -->|plugins| BR
    VM -->|"emits trace"| TA
    TA -->|"serves data to"| TrUI
    CLI -->|"returns outputs"| CLI

    %% Hooks for tooling and examples
    Fz -->|"invokes VM API"| VM
    B1 -->|"benchmarks VM"| VM
    B2 -->|"benchmarks VM"| VM
    CH -->|"uses HintProcessor"| VM
    HT -->|"uses VM Library"| VM
    WASM -->|"calls VM via wasm-bindgen"| VM
    WH -->|"hosts WASM Demo"| WASM

    %% Styling
    classDef lib fill:#ccf,stroke:#669;
    classDef exe fill:#cfc,stroke:#393;
    classDef tool fill:#fc9,stroke:#c60;
    classDef ext fill:#fcc,stroke:#933;
```
