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()?;

UntrustedMastForest::read_from_bytes applies default parsing and validation budgets derived from the input size. Use UntrustedMastForest::read_from_bytes_with_budget to tune only the wire-parsing budget, or UntrustedMastForest::read_from_bytes_with_budgets to tune both: the parsing budget limits allocations driven directly by wire counts while reading the payload, and the validation budget limits later helper allocations needed to materialize and check stripped or hashless payloads.

use miden_core::mast::UntrustedMastForest;

// Parsing budget only
let forest = UntrustedMastForest::read_from_bytes_with_budget(&bytes, bytes.len())?
    .validate()?;

// Parsing budget plus explicit validation-allocation budget
let forest = UntrustedMastForest::read_from_bytes_with_budgets(&bytes, bytes.len(), bytes.len() * 7)?
    .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).

In practice, the public entry points split into three policies:

• MastForest::read_from_bytes: trusted full deserialization; rejects hashless payloads and trusts serialized non-external digests.
• SerializedMastForest::new: structural inspection path for local tooling; scans only the layout needed for random access and may accept full, stripped, or hashless payloads, but it is not an untrusted-validation entry point.
• UntrustedMastForest::read_from_bytes and UntrustedMastForest::read_from_bytes_with_budgets: untrusted paths; parse with bounded readers and require UntrustedMastForest::validate before use.

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.

DebugVarId

An identifier for a debug variable stored in DebugInfo.

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.

MastNodeInfo

Logical node metadata combining fixed-width structure and a digest value.

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.

OpToDebugVarIds

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

OpToDecoratorIds

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

SerializedMastForest

A zero-copy structural view over serialized MAST forest bytes.

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.

MastNodeEntry

Fixed-width structural metadata for a serialized MastNode.

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

MastForestView

Read-only view over serialization-oriented MAST node metadata.

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.