# openvm-org/openvm architecture

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

- Interactive diagram: https://gitdiagram.com/openvm-org/openvm
- Repository: https://github.com/openvm-org/openvm

## Overview

##### Main components

- Core Virtual Machine (VM) Layer:
- Represented by the “crates/vm” directory, this is the core execution environment.
- It handles the VM “architecture” (e.g., the no-CPU design) and manages system subcomponents such as memory, system modules (e.g., native adapter, memory controllers), and the public values.

- Instruction Set and Extensions Layer:
- This layer includes “extensions” (e.g. algebra, bigint, ecc, keccak256, native, pairing, rv32im) as well as the “crates/toolchain” which implements and integrates these custom instructions and chips.
- The “crates/cli” and “crates/sdk” also provide access to these extended instructions from the Rust frontend.

- Circuit and Proof Generation Layer:
- Found in “crates/circuits” (and submodules like mod-builder, poseidon2-air, primitives, sha256-air, etc.), this layer builds the zk-proof circuits.
- This segment also reflects the integration of circuits (borrowed ideas from projects like Plonky3) which underlie the zero-knowledge proof functionality.

- Toolchain / Compiler Layer:
- Several subdirectories under “crates/toolchain” (including instructions, macros, openvm and transpiler) indicate that the project compiles high-level code into VM bytecode and circuit representations.
- This toolchain is responsible for handling the native compiler, translation (e.g., RISC-V instruction translation), and optimizations.

- CLI & SDK User Interfaces:
- The command-line interface (in “crates/cli”) is the user’s primary tool to interact with the VM, build applications, generate proofs, etc.
- The “crates/sdk” provides programmable APIs and examples (also seen in the “examples” folder) for developers to integrate and develop on top of OpenVM.

- Supporting Components:
- Benchmarking (“benchmarks”), tests, audits and documentation (docs, book, and assets) provide quality assurance and visibility into design decisions.
- Continuous integration components (like the .github workflows) ensure system reliability.

##### Relationships and interactions

- The CLI and SDK interface with the toolchain – they call the native compiler, transpiler, and verification modules.
- The toolchain converts high-level instructions and calls into VM bytecode and sometimes directly into circuit representations, thereby interacting with both the VM core and the circuit builder.
- At runtime, the VM executes the compiled program while interfacing with circuit components to generate or verify zk proofs.
- The Extensions form a plug-in-like layer with directional interconnections: the core VM delegates extended arithmetic or cryptographic operations (like ECC or pairing) to specialized extension components.
- The audits, benchmarks, and tests are on the periphery; they interact with almost every core module to ensure performance and correctness.
- External services (e.g., on-chain verifiers as mentioned in “On-chain Verification” in the README) can be indicated as external systems connected to the VM for verifying proofs.

##### Architectural Patterns and Design Principles

- Modularity and Extensibility: Clearly separate core VM execution, circuit creation, toolchain compilation, and extensions.
- Layered Design: Each component (UI, compiler/toolchain, runtime, proof system) is self-contained, with well-defined interfaces.
- Customization Without Core Forking: Emphasize the plug-in nature of the extensions by showing how new modules can be “plugged into” the core without modifying it.
- Integration Points: Highlight the integration of Rust’s intrinsic functions (for a smooth developer experience) and the use of cargo workspaces (indicated by many Cargo.toml files) to manage dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interfaces"
        CLI["CLI Interface"]:::ui
        SDK["SDK / APIs"]:::ui
        EXAMPLES["Developer Examples"]:::ui
    end

    %% Toolchain / Compiler Layer
    subgraph "Toolchain / Compiler Layer"
        TC["Toolchain & Transpiler"]:::toolchain
        ISA["Base ISA & Extensions"]:::toolchain
        EXT["Extension Modules"]:::extension
    end

    %% VM & Circuit Layers
    subgraph "VM & Circuit Layers"
        VM["VM Core"]:::runtime
        CIRCUIT["Circuit & Proof Generation"]:::circuit
    end

    %% Supporting Components Layer
    subgraph "Supporting Components"
        BENCH["Benchmarks"]:::support
        AUDIT["Audits"]:::support
        DOCS["Documentation & Specs"]:::support
        CI["CI Workflows"]:::support
    end

    %% Connections between layers
    CLI -->|"invokes"| TC
    SDK -->|"invokes"| TC
    EXAMPLES -->|"supports"| SDK
    TC -->|"compiles_to"| VM
    TC -->|"generates_circuit"| CIRCUIT
    TC -->|"integrates"| ISA
    ISA -->|"defines_ops_for"| VM
    VM -->|"delegates_ops_to"| EXT

    BENCH --- VM
    AUDIT --- VM
    DOCS --- VM
    CI --- VM

    %% Click Events for component mapping
    click CLI "https://github.com/openvm-org/openvm/tree/main/crates/cli"
    click SDK "https://github.com/openvm-org/openvm/tree/main/crates/sdk"
    click EXAMPLES "https://github.com/openvm-org/openvm/tree/main/examples"
    click TC "https://github.com/openvm-org/openvm/tree/main/crates/toolchain"
    click ISA "https://github.com/openvm-org/openvm/tree/main/crates/toolchain/instructions"
    click EXT "https://github.com/openvm-org/openvm/tree/main/extensions/*"
    click VM "https://github.com/openvm-org/openvm/tree/main/crates/vm"
    click CIRCUIT "https://github.com/openvm-org/openvm/tree/main/crates/circuits"
    click BENCH "https://github.com/openvm-org/openvm/tree/main/benchmarks"
    click AUDIT "https://github.com/openvm-org/openvm/tree/main/audits"
    click DOCS "https://github.com/openvm-org/openvm/tree/main/docs"
    click CI "https://github.com/openvm-org/openvm/tree/main/.github/workflows"

    %% Styles for nodes
    classDef ui fill:#F9E79F,stroke:#F39C12,stroke-width:2px;
    classDef toolchain fill:#ABEBC6,stroke:#27AE60,stroke-width:2px;
    classDef runtime fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef circuit fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef extension fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef support fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
```
