layout.md

June 26, 2026 ยท View on GitHub

Project Layout

The main components of the repository are:

Documentation

Contributor documentation is in docs and user documentation is in docs/vocs.

Benchmarks

Benchmark guest programs and benchmark scripts are in benchmarks, which contains:

CI

Scripts for CI use and metrics post-processing are in ci.

Profiling

  • openvm-prof: Tools to post-process metrics emitted by the VM for performance profiling.

CLI

Command-line binary to compile, execute, and prove guest programs is in cli.

SDK

  • openvm-sdk: The developer SDK for the VM. It provides the final interface for proving an arbitrary program for a target VM, including a local aggregation scheduling implementation for continuations. The SDK includes functionality to generate the final onchain SNARK verifier contract.

Toolchain

  • openvm: The OpenVM standard library to be imported by guest programs. Contains main function entrypoint and standard intrinsic functions for IO.
  • openvm-platform: Rust runtime for RV32IM target using OpenVM intrinsic for system termination. This crate is re-exported by the openvm crate.
  • openvm-build: Library of build tools for compiling Rust to the RISC-V target, built on top of cargo.
  • openvm-transpiler: Transpiler for converting RISC-V ELF with custom instructions into OpenVM executable with OpenVM instructions. This crate contains the TranspilerExtension trait and a Transpiler struct which supports adding custom TranspilerExtension implementations.
  • openvm-instructions: OpenVM instruction struct and trait definitions. Also includes some system instruction definitions.
  • openvm-instructions-derive: Procedural macros to derive traits for OpenVM instructions.
  • openvm-macros-common: Common library for parsing utilities shared across procedural macros used for custom instruction setup in guest programs.
  • openvm-toolchain-tests: Includes all official RISC-V 32-bit IM test vectors and transpiler tests. Also, provides utilities for writing integration tests for custom extensions.
  • openvm-custom-insn: Custom instruction macros for use in guest programs.

Circuit Framework

  • openvm-circuit: The VM circuit framework. It includes the struct and trait definitions used throughout the architecture, as well as the system chips.
  • openvm-circuit-derive: Procedural macros to derive traits in the VM circuit framework.

Circuit Foundations

Recursion

Continuations

  • openvm-continuations: Continuation-specific AIRs and utilities for aggregating segment proofs for all VMs in the framework.

Examples

  • examples: Examples of guest programs using the OpenVM framework. Most top-level examples are CLI book examples that can be built and run directly with cargo openvm build and cargo openvm run; examples/verify-stark is an end-to-end host/guest example for recursively verifying STARK proofs with the deferral framework.

Extensions

The toolchain, ISA, and VM are simultaneously extendable. All non-system functionality is implemented via extensions, which may be moved to standalone repositories in the future but are presently in this repository for maintainer convenience.

Procedural macros for algebraic structs

  • openvm-algebra-moduli-macros: Procedural macros for use in guest program to generate modular arithmetic struct with custom intrinsics for compile-time modulus.
  • openvm-algebra-complex-macros: Procedural macros for use in guest program to generate complex field struct with custom intrinsics for compile-time modulus.
  • openvm-ecc-sw-macros: Procedural macros for use in guest program to generate short Weierstrass curve struct with custom intrinsics for compile-time curve.

RV32IM

Deferral

Keccak256

SHA-2

Big Integers

Algebra (Modular Arithmetic)

  • openvm-algebra-circuit: Circuit extension for modular arithmetic for arbitrary compile-time modulus. Supports modular arithmetic and complex field extension operations.
  • openvm-algebra-transpiler: Transpiler extension for modular arithmetic for arbitrary compile-time modulus. Supports modular arithmetic and complex field extension operations.
  • openvm-algebra-guest: Guest library with traits for modular arithmetic and complex field extension operations.
  • openvm-algebra-tests: Integration tests for the algebra extension.

Elliptic Curve Cryptography

  • openvm-ecc-circuit: Circuit extension for Weierstrass elliptic curve operations for arbitrary compile-time curve.
  • openvm-ecc-transpiler: Transpiler extension for Weierstrass elliptic curve operations for arbitrary compile-time curve.
  • openvm-ecc-guest: Guest library with traits for elliptic curve cryptography. Includes implementations of ECDSA and multi-scalar multiplication.
  • openvm-ecc-integration-tests: Integration tests for the elliptic curve cryptography extension.

Elliptic Curve Pairing

  • openvm-pairing-circuit: Circuit extension for optimal Ate pairing on BN254 and BLS12-381 curves.
  • openvm-pairing-transpiler: Transpiler extension for optimal Ate pairing on BN254 and BLS12-381.
  • openvm-pairing-guest: Guest library with optimal Ate pairing on BN254 and BLS12-381 and associated constants. Also includes elliptic curve operations for VM runtime with the halo2curves feature gate.

Guest Libraries

Forked or custom libraries optimized for guest program execution inside the VM.

Verification & Configuration