layout.md

Project Layout

The main components of the repository are:

• Project Layout
  • Documentation
  • Benchmarks
  • CI
  • Profiling
  • CLI
  • SDK
  • Toolchain
  • Circuit Framework
  • Circuit Foundations
  • Examples
  • Extensions
    • RV32IM
    • Native Recursion
    • Keccak256
    • Big Integers
    • Algebra (Modular Arithmetic)
    • Elliptic Curve Cryptography
    • Elliptic Curve Pairing

Documentation

Contributor documentation is in docs and user documentation is in book.

Benchmarks

Benchmark guest programs and benchmark scripts are in openvm-benchmarks.

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 includes the OpenVM aggregation programs to support continuations for all VMs in the framework, and well as a local aggregation scheduling implementation. It provides the final interface for proving an arbitrary program for a target VM. 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.

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

• openvm-circuit-primitives: Primitive chips and sub-chips for standalone use in any circuit.
• openvm-circuit-primitives-derive: Procedural macros for use in circuit to derive traits.
• openvm-poseidon2-air: Standalone poseidon2 AIR implementation which is configurable based on the desired maximum constraint degree.
• openvm-mod-circuit-builder: General builder for generating a chip for any modular arithmetic expression for a modulus known at compile time.

Examples

• examples: Examples of guest programs using the OpenVM framework. All of the examples can be built and run using the CLI.

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.

RV32IM

• openvm-rv32im-circuit: Circuit extension for RV32IM instructions and IO instructions.
• openvm-rv32im-transpiler: Transpiler extension for RV32IM instructions and IO instructions.
• openvm-rv32im-guest: Guest library for RV32IM instructions and IO instructions. This is re-exported by the openvm crate for convenience.
• openvm-rv32-adapters: Circuit adapters for other circuit extensions to use to be compatible with the RISC-V 32-bit architecture.
• openvm-rv32im-tests: Integration tests for the RV32IM extension.

Native Recursion

• openvm-native-circuit: Circuit extension for native instructions operating on field elements.
• openvm-native-compiler: Implementation of compiler from a Rust embedded DSL to OpenVM assembly targeting the native kernel extension. The eDSL also has a static mode to support compilation to a Halo2 circuit.
• openvm-native-recursion: Library written in the native eDSL with functions to verify arbitrary STARK proofs. The library also supports compilation to a Halo2 circuit.

Keccak256

• openvm-keccak256-circuit: Circuit extension for the keccak256 hash function.
• openvm-keccak256-transpiler: Transpiler extension for the keccak256 hash function.
• openvm-keccak256-guest: Guest library with intrinsic function for the keccak256 hash function.
• openvm-keccak256-tests: Integration tests for the keccak256 extension.

Big Integers

• openvm-bigint-circuit: Circuit extension for I256 and U256 big integer operations.
• openvm-bigint-transpiler: Transpiler extension for I256 and U256 big integer operations.
• openvm-bigint-guest: Guest library with I256 and U256 big integers operations using intrinsics for underlying operations.
• openvm-bigint-tests: Integration tests for the bigint extension.

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-moduli-setup: 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-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-sw-setup: Procedural macros for use in guest program to generate short Weierstrass curve struct with custom intrinsics for compile-time curve.
• openvm-ecc-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.
• openvm-pairing-tests: Integration tests for the pairing extension.