Crate brillig_vm

The Brillig VM is a specialized VM which allows the ACVM to perform custom non-determinism.

Brillig bytecode is distinct from regular ACIR in that it does not generate constraints.

Input Validation

Important: The VM assumes that all inputs have been validated by the caller before execution. This includes ensuring that field element values fit within the expected bit sizes for typed operations (e.g., u8, u16, u32, etc.).

If invalid inputs are provided, the VM may produce unexpected results without error:

• Cast operations truncate call data values that exceed the target bit size (e.g., casting 256 to u8 produces 0)

When using the VM with Noir programs, the ABI layer handles input validation automatically. Direct consumers of the VM API must implement their own input validation.

Re-exports

pub use crate::fuzzing::BranchToFeatureMap;

pub use acir::brillig;

Modules

arithmetic 🔒

Implementations for [binary field operations][acir::brillig::Opcode::BinaryFieldOp] and [binary integer operations][acir::brillig::Opcode::BinaryIntOp].

black_box 🔒

Implementations for VM native [black box functions][acir::brillig::Opcode::BlackBox].

cast 🔒

Implementation for the [cast operation][acir::brillig::Opcode::Cast].

foreign_call 🔒

Implementation for [foreign calls][acir::brillig::Opcode::ForeignCall]

fuzzing

memory 🔒

Implementation of the VM’s memory.

offsets

Offset constants for arrays and vectors:

Structs

BrilligProfilingSample

A sample for an executed opcode.

Memory

The VM’s memory.

VM

VM encapsulates the state of the Brillig VM during execution.

Enums

FailureReason

Represents the reason why the Brillig VM failed during execution.

MemoryValue

A single typed value in the Brillig VM’s memory.

VMStatus

Represents the current execution status of the Brillig VM.

Constants

FREE_MEMORY_POINTER_ADDRESS

The free memory pointer is always in slot 1.

MEMORY_ADDRESSING_BIT_SIZE

The bit size used for addressing memory within the Brillig VM.

STACK_POINTER_ADDRESS

The current stack pointer is always in slot 0.

Functions

assert_u32 🔒

Converts a usize value to u32, panicking if the conversion fails.

assert_usize 🔒

Converts a u32 value to usize, panicking if the conversion fails.

Type Aliases

BrilligProfilingSamples

All samples for each opcode that was executed.

ErrorCallStack

The error call stack contains the opcode indexes of the call stack at the time of failure, plus the index of the opcode that failed.

NextOpcodePositionOrState

The position of the next opcode that will be executed in the bytecode, or an id of a specific state produced by the opcode.

OpcodePosition

The position of an opcode that is currently being executed in the bytecode.