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_options with UntrustedMastForestReadOptions to tune the wire byte budget. This limits allocations driven directly by wire counts while reading the payload. A separate validation helper budget is derived from it for later allocations needed to materialize and check hashless payloads.

use miden_core::mast::{UntrustedMastForest, UntrustedMastForestReadOptions};

let options = UntrustedMastForestReadOptions::new()
    .with_wire_byte_budget(bytes.len());
let forest = UntrustedMastForest::read_from_bytes_with_options(&bytes, options)?
    .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.
• MastForestWireView::new: trusted wire-backed cache access; scans only the layout needed for random access and rejects hashless payloads.
• UntrustedMastForest::read_from_bytes and UntrustedMastForest::read_from_bytes_with_options: untrusted paths; parse with bounded readers and require UntrustedMastForest::validate before use.

Structs

AdviceMapView

Read-only view over forest advice.

AdviceValueView

Read-only view over a value from forest advice.

BasicBlockNode

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

BasicBlockNodeBuilder

Builder for creating BasicBlockNode instances.

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.

DynNode

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

DynNodeBuilder

Builder for creating DynNode instances.

ExternalNode

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

ExternalNodeBuilder

Builder for creating ExternalNode instances.

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.

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``, except for the encounter which it executes unconditionally.

LoopNodeBuilder

Builder for creating LoopNode instances.

MastForest

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

MastForestId

MastForestRootMap

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

MastForestWireView

A trusted wire-backed view over serialized MAST forest bytes.

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.

OpBatch

A batch of operations in a span block.

SparseMastForest

A sparse replay view over a single source MastForest’s MastNodeId space, retaining only the nodes visited during execution.

SparseMastForestBuilder

Incrementally builds a SparseMastForest by collecting the MastNodeIds of nodes visited during execution of a single source MastForest.

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.

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.

UntrustedMastForestReadOptions

Options for reading an UntrustedMastForest from bytes.

Enums

MastForestError

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

MastForestReadMode

Trusted read backing mode for read-only MAST forest access.

MastForestReadView

Read-only trusted MAST forest handle.

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.

VisitKind

Describes how a node referenced during execution should be represented in the resulting SparseMastForest.

Constants

OP_BATCH_SIZE

Maximum number of groups per batch.

OP_GROUP_SIZE

Maximum number of operations per group.

Traits

ExecutableMastForest

A MAST forest that can be used as the source of nodes during program execution.

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 using the provided mapping.

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

Remapping

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