Enum SystemEvent 

#[repr(u8)]
pub enum SystemEvent {
    MerkleNodeMerge = 0,
    MerkleNodeToStack = 1,
    MapValueToStack = 2,
    MapValueCountToStack = 3,
    MapValueToStackN0 = 4,
    MapValueToStackN4 = 5,
    MapValueToStackN8 = 6,
    HasMapKey = 7,
    Ext2Inv = 8,
    U32Clz = 9,
    U32Ctz = 10,
    U32Clo = 11,
    U32Cto = 12,
    ILog2 = 13,
    MemToMap = 14,
    HdwordToMap = 15,
    HqwordToMap = 16,
    CompressToMap = 17,
    DeferredRegister = 18,
    DeferredEvaluate = 19,
    DeferredEvaluateFrame = 20,
    DeferredEvaluatePayload = 21,
    DeferredRegisterData = 22,
    DeferredExportWitness = 23,
    TraceEvent = 24,
}

Defines a set of host-side actions which can be initiated from the VM.

Most actions update or query one of the three advice-provider components: Merkle store, advice stack, or advice map. Deferred-DAG actions update host-side deferred state, and evaluation may also push canonical node data to the advice stack.

All actions, except for MerkleNodeMerge, Ext2Inv and UpdateMerkleNode can be invoked directly from Miden assembly via dedicated instructions.

System event IDs are derived from blake3-hashing their names (prefixed with “sys::”).

The enum variant order matches the indices in SYSTEM_EVENT_LOOKUP, allowing efficient const lookup via to_event_id(). The discriminants are implicitly 0, 1, 2, … COUNT - 1.

Variants

MerkleNodeMerge = 0

Creates a new Merkle tree in the advice provider by combining Merkle trees with the specified roots. The root of the new tree is defined as Hash(LEFT_ROOT, RIGHT_ROOT).

Inputs: Operand stack: [LEFT_ROOT, RIGHT_ROOT, …] Merkle store: {LEFT_ROOT, RIGHT_ROOT}

Outputs: Operand stack: [LEFT_ROOT, RIGHT_ROOT, …] Merkle store: {LEFT_ROOT, RIGHT_ROOT, hash(LEFT_ROOT, RIGHT_ROOT)}

After the operation, both the original trees and the new tree remains in the advice provider (i.e., the input trees are not removed).

MerkleNodeToStack = 1

Pushes a node of the Merkle tree specified by the values on the top of the operand stack onto the advice stack in structural order for consumption by AdvPopW.

Inputs: Operand stack: [depth, index, TREE_ROOT, …] Advice stack: […] Merkle store: {TREE_ROOT<-NODE}

Outputs: Operand stack: [depth, index, TREE_ROOT, …] Advice stack: [NODE, …] Merkle store: {TREE_ROOT<-NODE}

MapValueToStack = 2

Pushes a list of field elements onto the advice stack. The list is looked up in the advice map using the specified word from the operand stack as the key.

Inputs: Operand stack: [KEY, …] Advice stack: […] Advice map: {KEY: values}

Outputs: Operand stack: [KEY, …] Advice stack: [values, …] Advice map: {KEY: values}

MapValueCountToStack = 3

Pushes the number of elements in a list of field elements onto the advice stack. The list is looked up in the advice map using the specified word from the operand stack as the key.

Inputs: Operand stack: [KEY, …] Advice stack: […] Advice map: {KEY: values}

Outputs: Operand stack: [KEY, …] Advice stack: [values.len(), …] Advice map: {KEY: values}

MapValueToStackN0 = 4

Pushes a list of field elements onto the advice stack, along with the number of elements in that list. The list is looked up in the advice map using the word at the top of the operand stack as the key.

Notice that the resulting elements list is not padded.

Inputs: Operand stack: [KEY, …] Advice stack: […] Advice map: {KEY: values}

Outputs: Operand stack: [KEY, …] Advice stack: [num_values, values, …] Advice map: {KEY: values}

MapValueToStackN4 = 5

Pushes a padded list of field elements onto the advice stack, along with the number of elements in that list. The list is looked up in the advice map using the word at the top of the operand stack as the key.

Notice that the elements list obtained from the advice map will be padded with zeros, increasing its length to the next multiple of 4.

Inputs: Operand stack: [KEY, …] Advice stack: […] Advice map: {KEY: values}

Outputs: Operand stack: [KEY, …] Advice stack: [num_values, values, padding, …] Advice map: {KEY: values}

MapValueToStackN8 = 6

Pushes a padded list of field elements onto the advice stack, along with the number of elements in that list. The list is looked up in the advice map using the word at the top of the operand stack as the key.

Notice that the elements list obtained from the advice map will be padded with zeros, increasing its length to the next multiple of 8.

Inputs: Operand stack: [KEY, …] Advice stack: […] Advice map: {KEY: values}

Outputs: Operand stack: [KEY, …] Advice stack: [num_values, values, padding, …] Advice map: {KEY: values}

HasMapKey = 7

Pushes a flag onto the advice stack whether advice map has an entry with specified key.

If the advice map has the entry with the key equal to the key placed at the top of the operand stack, 1 will be pushed to the advice stack and 0 otherwise.

Inputs: Operand stack: [KEY, …] Advice stack: […]

Outputs: Operand stack: [KEY, …] Advice stack: [has_mapkey, …]

Ext2Inv = 8

Given an element in a quadratic extension field on the top of the stack (i.e., a0, b1), computes its multiplicative inverse and push the result onto the advice stack.

Inputs: Operand stack: [a1, a0, …] Advice stack: […]

Outputs: Operand stack: [a1, a0, …] Advice stack: [b0, b1…]

Where (b0, b1) is the multiplicative inverse of the extension field element (a0, a1) at the top of the stack.

U32Clz = 9

Pushes the number of the leading zeros of the top stack element onto the advice stack.

Inputs: Operand stack: [n, …] Advice stack: […]

Outputs: Operand stack: [n, …] Advice stack: [leading_zeros, …]

U32Ctz = 10

Pushes the number of the trailing zeros of the top stack element onto the advice stack.

Inputs: Operand stack: [n, …] Advice stack: […]

Outputs: Operand stack: [n, …] Advice stack: [trailing_zeros, …]

U32Clo = 11

Pushes the number of the leading ones of the top stack element onto the advice stack.

Inputs: Operand stack: [n, …] Advice stack: […]

Outputs: Operand stack: [n, …] Advice stack: [leading_ones, …]

U32Cto = 12

Pushes the number of the trailing ones of the top stack element onto the advice stack.

Inputs: Operand stack: [n, …] Advice stack: […]

Outputs: Operand stack: [n, …] Advice stack: [trailing_ones, …]

ILog2 = 13

Pushes the base 2 logarithm of the top stack element, rounded down. Inputs: Operand stack: [n, …] Advice stack: […]

Outputs: Operand stack: [n, …] Advice stack: [ilog2(n), …]

MemToMap = 14

Reads words from memory at the specified range and inserts them into the advice map under the key KEY located at the top of the stack.

Inputs: Operand stack: [KEY, start_addr, end_addr, …] Advice map: {…}

Outputs: Operand stack: [KEY, start_addr, end_addr, …] Advice map: {KEY: values}

Where values are the elements located in memory[start_addr..end_addr].

HdwordToMap = 15

Reads two words from the operand stack and inserts them into the advice map under hdword(A, B).

Inputs: Operand stack: [A, B, …] Advice map: {…}

Outputs: Operand stack: [A, B, …] Advice map: {KEY: [a0, a1, a2, a3, b0, b1, b2, b3]}

KEY is the generic Eidos hash of the eight Felts in A || B.

HqwordToMap = 16

Reads four words from the operand stack and inserts them into the advice map under the key defined by the hash of these words.

Inputs: Operand stack: [A, B, C, D, …] Advice map: {…}

Outputs: Operand stack: [A, B, C, D, …] Advice map: {KEY: [A, B, C, D]} (16 elements)

Where:

• KEY is computed as the canonical Eidos hash of [A, B, C, D], using two 8-Felt compression blocks with the full 16-Felt length bound into the initial chaining value.

CompressToMap = 17

Reads three words from the operand stack and inserts the top two words into the advice map under the key Eidos::compress(C, A || B).

Inputs: Operand stack: [A, B, C, …] Advice map: {…}

Outputs: Operand stack: [A, B, C, …] Advice map: {KEY: [a0, a1, a2, a3, b0, b1, b2, b3]}

In particular, using the framed initial CV for (domain_tag = d, param0 = 8) produces Eidos::hash_elements_in_domain(A || B, d).

DeferredRegister = 18

Registers and eagerly evaluates a deferred node whose full payload is on the operand stack.

CV is one word containing the framed initial Eidos chaining value. PAYLOAD_LO || PAYLOAD_HI is eight field elements: either one crate::deferred::DataChunk, two child digests (lhs || rhs) for a precompile-owned join, or one lhs || rhs pair for a pair-list node. The installed registry recovers the semantic crate::deferred::EidosFrame from CV and decodes it via crate::deferred::DeferredState::decode. Framework-owned AND and TRUE nodes are not accepted by this generic event; log_deferred constructs rolling AND nodes. Frames that semantically require more data chunks or pairs are rejected during precompile-specific evaluation. Registration is performed by crate::deferred::DeferredState::register, so semantic failures surface immediately.

This event does not push advice or return the node digest. The stack arguments are visible in the VM execution trace, but the host-side registration is not constrained by the event. Assembly code that later relies on the digest must compute it inside the VM from the same CV and payload.

Inputs: Operand stack: [event_id, CV, PAYLOAD_LO, PAYLOAD_HI, …]

Outputs: Operand stack: unchanged Advice stack: unchanged Deferred state: node registered and semantically evaluated

DeferredEvaluate = 19

Evaluates a registered deferred node and pushes its canonical frame and payload as advice.

NODE_DIGEST is one word (4 field elements) and must already be registered in deferred state. The handler evaluates it with crate::deferred::DeferredState::evaluate_digest, fetches the canonical node, and pushes its frame followed by its payload to the advice stack.

The frame is emitted first in advice-pop order so adv_pushw adv_pushw adv_pushw leaves [PAYLOAD_LO, PAYLOAD_HI, FRAME, ...] on the operand stack for a single 8-felt payload. Data payloads push two words per 8-felt chunk in advice order HIGH, LOW, preserving canonical chunk order. Join payloads use the same two-word LIFO convention, leaving [lhs, rhs, FRAME, ...]. TRUE pushes one zero word. These felts are unbound host hints. Before proof-relevant use, assembly code must relate them with VM instructions to values established independently of that advice.

Inputs: Operand stack: [event_id, NODE_DIGEST, …]

Outputs: Operand stack: unchanged Advice stack: canonical frame, then canonical payload words for adv_pushw LIFO consumption

DeferredEvaluateFrame = 20

Evaluates a registered deferred node and pushes only its canonical frame as advice.

NODE_DIGEST is one word (4 field elements) and must already be registered in deferred state. TRUE pushes one zero word. The returned frame is an unbound host hint; before proof-relevant use, assembly code must relate it with VM instructions to a value established independently of that advice.

Inputs: Operand stack: [event_id, NODE_DIGEST, …]

Outputs: Operand stack: unchanged Advice stack: canonical frame only

DeferredEvaluatePayload = 21

Evaluates a registered deferred node and pushes only its canonical payload as advice.

Data payloads push two words per 8-felt chunk in advice order HIGH, LOW so adv_pushw adv_pushw leaves [LOW, HIGH, ...] on the operand stack for that chunk. Chunks are emitted in canonical chunk order. Join payloads use the same two-word LIFO convention, leaving [lhs, rhs, ...] after two adv_pushws. TRUE pushes no advice. These felts are unbound host hints. Before proof-relevant use, assembly code must relate them with VM instructions to values established independently of that advice.

Inputs: Operand stack: [event_id, NODE_DIGEST, …]

Outputs: Operand stack: unchanged Advice stack: canonical payload only, word-ordered for adv_pushw LIFO consumption

DeferredRegisterData = 22

Registers and eagerly evaluates a memory-backed deferred node.

CV is one word containing the framed initial Eidos chaining value. The installed registry recovers its semantic frame to determine the memory-backed payload shape. The stack-supplied ptr and n_chunks are visible in the VM execution trace and select the range [ptr, ptr + 8 * n_chunks). The host reads n_chunks 8-felt crate::deferred::DataChunk values from that range, but this event adds no AIR constraint tying the registered contents to those memory cells.

The registered deferred-CHUNKS domain denotes framework-owned opaque data, while other data frames remain precompile-owned. Pair-list frames interpret chunks as lhs || rhs pairs. Precompile-owned join frames require n_chunks == 1 and interpret the single chunk as lhs || rhs. Framework-owned AND and TRUE nodes are not accepted by this generic event; log_deferred constructs rolling AND nodes. The handler performs a cheap budget pre-check before allocating or reading memory, then delegates registration to crate::deferred::DeferredState::register.

This event does not push advice or return the node digest. A program that relies on the registered node must compute its digest with VM instructions from the same CV and ordered chunk sequence. The register_mem MASM wrapper does this with the canonical Eidos deferred framing: the frame determines the initial chaining word, then payload chunks are compressed in order. If the event and the VM hash different chunk sequences, the VM-computed digest does not identify the host-registered node and cannot bind that registration into a proof-relevant deferred claim.

Inputs: Operand stack: [event_id, n_chunks, CV, ptr, …]

Outputs: Operand stack: unchanged Advice stack: unchanged Deferred state: node registered and semantically evaluated

DeferredExportWitness = 23

Exports a registered true assertion’s witness into the advice map.

The selected node may be unlogged, but cannot be literal TRUE. Its original digest is both the witness root and map key; any existing value is replaced with the computed witness. The value is [byte_len, packed_u32_le(witness_bytes)...]. Only the final u32 limb is zero-padded, and byte_len excludes padding.

Both stacks and the deferred root are preserved. Errors leave existing advice unchanged. Consumers must validate the witness and bind its root to an independently established expected digest.

Inputs: Operand stack: [event_id, NODE_DIGEST, …]

Outputs: Operand stack: unchanged Advice stack: unchanged Advice map: {NODE_DIGEST: [byte_len, packed_u32_le(witness_bytes)…]}

TraceEvent = 24

Signals an optional, read-only trace event to the host.

Assembly programs emit trace events with trace, trace.CONST, or trace.event("..."). When the underlying emit observes this system event ID at stack position 0, the VM forwards the user trace event ID at stack position 1 to the host’s trace handler. The immediate form lowers to push.<user_trace_id> push.<sys::trace_event> emit drop drop. Trace handlers can observe the processor state, but cannot mutate VM state or the advice provider. If no handler is registered for the user trace event ID, the event is a no-op.

Hosts are expected not to raise an error if they encounter a user_trace_id for which no trace handler is registered.

Inputs: Operand stack: [sys::trace_event, user_trace_id, …]

Outputs: Operand stack: unchanged Advice provider: unchanged

Implementations

impl SystemEvent

pub const fn from_event_id(event_id: EventId) -> Option<SystemEvent>

Attempts to convert an EventId into a SystemEvent by looking it up in the const table.

Returns Some(SystemEvent) if the ID matches a known system event, None otherwise. This uses a const lookup table with hardcoded EventIds, avoiding runtime hash computation.

pub const fn from_name(name: &str) -> Option<SystemEvent>

Attempts to convert a name into a SystemEvent by looking it up in the const table.

Returns Some(SystemEvent) if the name matches a known system event, None otherwise. This uses const string comparison against the lookup table.

pub const fn event_name(&self) -> EventName

Returns the human-readable name of this system event as an EventName.

System event names are prefixed with sys:: to distinguish them from user-defined events.

pub const fn event_id(&self) -> EventId

Returns the EventId for this system event.

The ID is looked up from the const LOOKUP table using the enum’s discriminant as the index. The discriminants are explicitly set to match the array indices.

pub const fn all() -> [SystemEvent; 25]

Returns an array of all system event variants.

impl SystemEvent

pub const COUNT: usize = 25

The total number of system events.

Trait Implementations

impl Clone for SystemEvent

fn clone(&self) -> SystemEvent

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for SystemEvent

impl Debug for SystemEvent

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for SystemEvent

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Eq for SystemEvent

impl From<&SystemEventNode> for SystemEvent

fn from(value: &SystemEventNode) -> SystemEvent

Converts to this type from the input type.

impl From<SystemEvent> for EventName

fn from(system_event: SystemEvent) -> EventName

Converts to this type from the input type.

impl PartialEq for SystemEvent

fn eq(&self, other: &SystemEvent) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PrettyPrint for SystemEvent

fn render(&self) -> Document

The core of the PrettyPrint functionality.

fn to_pretty_string(&self) -> String

Produce a String containing the results of pretty-printing this object.

fn pretty_print(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Pretty-print this object to the given core::fmt::Formatter.

impl StructuralPartialEq for SystemEvent