Module mast 

MAST forest: a collection of procedures represented as Merkle trees.

Deserializing from untrusted sources

When loading a MastForest from bytes you don’t fully trust (network, user upload, etc.), use UntrustedMastForest instead of calling MastForest::read_from_bytes directly:

use miden_core::mast::UntrustedMastForest;

let forest = UntrustedMastForest::read_from_bytes(&bytes)?
    .validate()?;

For maximum protection against denial-of-service attacks from malicious input, use UntrustedMastForest::read_from_bytes_with_budget which limits memory consumption:

use miden_core::mast::UntrustedMastForest;

// Budget limits pre-allocation sizes and total bytes consumed
let forest = UntrustedMastForest::read_from_bytes_with_budget(&bytes, bytes.len())?
    .validate()?;

This recomputes all node hashes and checks structural invariants before returning a usable MastForest. Direct deserialization via MastForest::read_from_bytes trusts the serialized hashes and should only be used for data from trusted sources (e.g. compiled locally).

Structs

AsmOpId

Unique identifier for an AssemblyOp within a MastForest.

BasicBlockNode

Block for a linear sequence of operations (i.e., no branching or loops).

BasicBlockNodeBuilder

Builder for creating BasicBlockNode instances with decorators.

CallNode

A Call node describes a function call such that the callee is executed in a different execution context from the currently executing code.

CallNodeBuilder

Builder for creating CallNode instances with decorators.

DebugInfo

Debug information for a MAST forest, containing decorators and error messages.

DecoratedLinks

Immutable view over all (op_idx, DecoratorId) pairs for a node. Uses the two-level CSR encoded by node_indptr_for_op_idx and op_indptr_for_dec_idx.

DecoratedLinksIter

The concrete, zero-alloc iterator over (relative_op_idx, DecoratorId).

DecoratorId

An opaque handle to a Decorator in some MastForest. It is the responsibility of the user to use a given DecoratorId with the corresponding MastForest.

DecoratorOpLinkIterator

Iterator used to iterate through the op-indexed decorators of a basic block.

DynNode

A Dyn node specifies that the node to be executed next is defined dynamically via the stack.

DynNodeBuilder

Builder for creating DynNode instances with decorators.

ExternalNode

Node for referencing procedures not present in a given MastForest (hence “external”).

ExternalNodeBuilder

Builder for creating ExternalNode instances with decorators.

JoinNode

A Join node describe sequential execution. When the VM encounters a Join node, it executes the first child first and the second child second.

JoinNodeBuilder

Builder for creating JoinNode instances with decorators.

LoopNode

A Loop node defines condition-controlled iterative execution. When the VM encounters a Loop node, it will keep executing the body of the loop as long as the top of the stack is `1``.

LoopNodeBuilder

Builder for creating LoopNode instances with decorators.

MastForest

Represents one or more procedures, represented as a collection of MastNodes.

MastForestRootMap

A mapping for the new location of the roots of a MastForest after a merge.

MastNodeFingerprint

Represents the hash used to test for equality between crate::mast::MastNodes.

MastNodeId

An opaque handle to a MastNode in some MastForest. It is the responsibility of the user to use a given MastNodeId with the corresponding MastForest.

NodeToDecoratorIds

A CSR (Compressed Sparse Row) representation for storing node-level decorators (before_enter and after_exit).

OpBatch

A batch of operations in a span block.

OpToAsmOpId

CSR storage mapping (NodeId, OpIdx) -> AsmOpId.

OpToDecoratorIds

A two-level compressed sparse row (CSR) representation for indexing decorator IDs per operation per node.

SplitNode

A Split node defines conditional execution. When the VM encounters a Split node it executes either the on_true child or on_false child.

SplitNodeBuilder

Builder for creating SplitNode instances with decorators.

SubtreeIterator

Iterates over all the nodes a root depends on, in pre-order. The iteration can include other roots in the same forest.

UntrustedMastForest

A MastForest deserialized from untrusted input that has not yet been validated.

Enums

AsmOpIndexError

Error type for AsmOp index mapping operations.

DecoratorIndexError

Error type for decorator index mapping operations

DecoratorStore

A data structure for storing decorators for MAST nodes, including both operation-level decorators and node-level decorators (before_enter/after_exit).

MastForestError

Represents the types of errors that can occur when dealing with MAST forest.

MastNode

MastNodeBuilder

Enum of all MAST node builders that can be added to a forest. This allows for generic handling of different builder types through enum dispatch.

OperationOrDecorator

Encodes either an Operation or a crate::operations::Decorator.

Constants

OP_BATCH_SIZE

Maximum number of groups per batch.

OP_GROUP_SIZE

Maximum number of operations per group.

Traits

MastForestContributor

MastNodeExt

Functions

build_node_with_remapped_ids

Builds a node builder with remapped children and decorators using the provided mappings.

error_code_from_msg

Derives an error code from an error message by hashing the message and returning the 0th element of the resulting Word.

Type Aliases

DecoratedOpLink

DecoratorFingerprint

Remapping

Operations that mutate a MAST often produce this mapping between old and new NodeIds.