Module arch 

Traits and constructs for the OpenVM architecture.

Re-exports

pub use execution_mode::ExecutionCtxTrait;

pub use execution_mode::MeteredExecutionCtxTrait;

pub use interpreter::InterpretedInstance;

pub use openvm_instructions as instructions;

pub use execution::*;

pub use vm::*;

Modules

deferral

Streams-like deferral state

execution

Instruction execution traits and types. Execution bus and interface.

execution_mode

Execution context types for different execution modes.

hasher

interpreter

Interpreter for pure and metered VM execution

interpreter_preflight

Interpreter for preflight VM execution, for trace generation purposes.

vm

Top level VmExecutor and VirtualMachine constructor and API. VmExecutor is the struct that can execute an arbitrary program, provided in the form of a VmExe, for a fixed set of OpenVM instructions corresponding to a VmExecutionConfig. Internally once it is given a program, it will preprocess the program to rewrite it into a more optimized format for runtime execution. This instance of the executor will be a separate struct specialized to running a fixed program on different program inputs.

Structs

AdapterAirContext

AdapterCoreEmptyMetadata

Empty metadata that implements AdapterCoreMetadata NOTE: AS is the adapter type that implements AdapterTraceExecutor WARNING: AS::WIDTH is the number of field elements, not the size in bytes

AdapterCoreLayout

Minimal layout information that RecordArena requires for record allocation in scenarios involving chips that:

AddressSpaceHostConfig

AirInventory

BasicAdapterInterface

The most common adapter interface. Performs NUM_READS batch reads of size READ_SIZE and NUM_WRITES batch writes of size WRITE_SIZE.

BusIndexManager

ChipInventory

DenseRecordArena

DynAdapterInterface

An interface that is fully determined during runtime. This should only be used as a last resort when static compile-time guarantees cannot be made.

DynArray

Newtype to implement From.

EmptyMultiRowMetadata

Empty metadata that implements MultiRowMetadata with get_num_rows always returning 1

ExecutorInventory

ExecutorInventoryBuilder

FlatInterface

Similar to BasicAdapterInterface, but it flattens the reads and writes into a single flat array for each

ImmInstruction

MatrixRecordArena

MemoryConfig

MinimalInstruction

MultiRowLayout

Minimal layout information that RecordArena requires for record allocation in scenarios involving chips that:

RecordSeeker

SignedImmInstruction

SystemConfig

System-level configuration for the virtual machine. Contains all configuration parameters that are managed by the architecture.

VecHeapAdapterInterface

VecHeapBranchAdapterInterface

Adapter interface for branch operations that read from heap via vec-style blocks. Similar to VecHeapAdapterInterface but without writes (branch operations only compare values).

VmAirWrapper

VmChipComplex

The collection of all chips in the VM. The chips should correspond 1-to-1 with the associated AirInventory. The VmChipComplex coordinates the trace generation for all chips in the VM after construction.

VmChipWrapper

We want a blanket implementation of Chip<MatrixRecordArena, CpuBackend> on any struct that implements TraceFiller but due to Rust orphan rules, we need a wrapper struct.

VmExecState

Represents the full execution state of a VM during execution. The global state is generic in guest memory MEM and additional context CTX. The host state is execution context specific.

VmState

Represents the core state of a VM.

Enums

AirInventoryError

ChipInventoryError

ExecutorInventoryError

MemoryCellType

Constants

ADDR_SPACE_OFFSET

Offset for address space indices. This is used to distinguish between different memory spaces.

BOUNDARY_AIR_ID

AIR index of the boundary AIR in the VM circuit.

CONNECTOR_AIR_ID

DEFAULT_BLOCK_SIZE

Default block size for memory bus interactions. RISC-V byte/halfword loads (lb/lh) need fewer bytes, but the adapter always reads a full 4-byte block from memory.

DEFAULT_DEFERRAL_ADDR_SPACE_CELLS

Max number of deferral address space cells

DEFAULT_MAX_NUM_PUBLIC_VALUES

MEMORY_AIRS_START_IDX

Starting AIR index of memory AIRs in the VM circuit.

MERKLE_AIR_ID

If VM has continuations enabled, all AIRs of MemoryController are added after ConnectorChip. Merkle AIR commits start/final memory states.

OPENVM_DEFAULT_INIT_FILE_BASENAME

OPENVM_DEFAULT_INIT_FILE_NAME

POSEIDON2_WIDTH

Width of Poseidon2 VM uses.

PROGRAM_AIR_ID

Global AIR ID in the VM circuit verifying key.

PROGRAM_CACHED_TRACE_INDEX

ProgramAir is the first AIR so its cached trace should be the first main trace.

Traits

AdapterCoreMetadata

Metadata types need to implement this trait to be used with AdapterCoreLayout NOTE: get_adapter_width returns the size in bytes

AdapterTraceExecutor

A helper trait for expressing generic state accesses within the implementation of PreflightExecutor. Note that this is only a helper trait when the same interface of state access is reused or shared by multiple implementations. It is not required to implement this trait if it is easier to implement the PreflightExecutor trait directly without this trait.

AdapterTraceFiller

AddressSpaceHostLayout

Each address space in guest memory may be configured with a different type T to represent a memory cell in the address space. On host, the address space will be mapped to linear host memory in bytes. The type T must be plain old data (POD) and be safely transmutable from a fixed size array of bytes. Moreover, each type T must be convertible to a field element F.

AnyAirWithColumns

AIR trait object combining [AnyAir] (used by stark-backend for proving) with [ColumnsAir] (OpenVM-internal column-name introspection used by external tooling). The blanket impl below makes every type satisfying both traits also satisfy this one, so existing concrete AIRs need no changes.

AnyEnum

A helper trait for downcasting types that may be enums.

Arena

CustomBorrow

A trait that allows for custom implementation of borrow given the necessary information This is useful for record structs that have dynamic size

InitFileGenerator

Trait for generating a init.rs file that contains a call to moduli_init!, complex_init!, sw_init! with the supported moduli and curves. Should be implemented by all VM config structs.

MultiRowMetadata

Metadata types need to implement this trait to be used with MultiRowLayout

RecordArena

Given some minimum layout of type Layout, the RecordArena should allocate a buffer, of size possibly larger than the record, and then return mutable pointers to the record within the buffer.

RowMajorMatrixArena

Helper trait for arenas backed by row-major matrices.

SizedRecord

SizedRecord is a trait that provides additional information about the size and alignment requirements of a record. Should be implemented on RecordMut types

TraceFiller

Helper trait for CPU tracegen.

VmAdapterAir

VmAdapterInterface

The interface between primitive AIR and machine adapter AIR.

VmBuilder

This trait is intended to be implemented on a new type wrapper of the VmConfig struct to get around Rust orphan rules.

VmCircuitConfig

VmCircuitExtension

Extension of the VM circuit. Allows in-order addition of new AIRs with interactions.

VmConfig

A VM configuration is the minimum serializable format to be able to create the execution environment and circuit for a zkVM supporting a fixed set of instructions. This trait contains the sub-traits VmExecutionConfig and VmCircuitConfig. The InitFileGenerator sub-trait provides custom build hooks to generate code for initializing some VM extensions. The VmConfig is expected to contain the SystemConfig internally.

VmCoreAir

VmExecutionConfig

VmExecutionExtension

Extension of VM execution. Allows registration of custom execution of new instructions by opcode.

VmProverExtension

Extension of VM trace generation. The generics are E for [StarkEngine], RA for record arena, and EXT for execution and circuit extension.

Functions

get_record_from_slice^⚠

Converts a field element slice into a record type. This function transmutes the &mut [F] to raw bytes, then uses the CustomBorrow trait to transmute to the desired record type T.

vm_poseidon2_config

Returns a Poseidon2 config for the VM.

Type Aliases

AirRefWithColumns

Reference-counted dyn pointer to an AIR with column-name introspection.

EmptyAdapterCoreLayout

AdapterCoreLayout with empty metadata that can be used by chips that have record type (&mut A, &mut C) where A and C are Sized

EmptyMultiRowLayout

Empty metadata that implements MultiRowMetadata

ExecutorId

Attribute Macros

create_handler

An attribute procedural macro for creating TCO (Tail Call Optimization) handlers.