Struct MastForest 

pub struct MastForest { /* private fields */ }

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

A MastForest does not have an entrypoint, and hence is not executable. A crate::program::Program can be built from a MastForest to specify an entrypoint.

Implementations

impl MastForest

pub fn read_view_from_bytes( bytes: &[u8], mode: MastForestReadMode, ) -> Result<MastForestReadView<'_>, DeserializationError>

Reads trusted MAST forest bytes using the requested backing mode.

MastForestReadMode::Materialized is equivalent to Self::read_from_bytes. MastForestReadMode::WireBacked returns a trusted random-access cache view and rejects hashless and trailing payloads because trusted cache bytes must be complete execution payloads.

impl MastForest

Constructors

pub fn new() -> MastForest

Creates a new empty MastForest.

impl MastForest

State mutators

pub fn compact(self) -> (MastForest, MastForestRootMap)

Compacts the forest by merging duplicate nodes.

This operation performs node deduplication by merging the forest with itself. This method consumes the forest and returns a new compacted forest.

The process works by:

1. Merging the forest with itself to deduplicate identical nodes
2. Updating internal node references and remappings
3. Returning the compacted forest and root map

Examples

use miden_core::mast::MastForest;

let forest = MastForest::new();
// Add nodes to the forest

// Compact the forest (consumes the original)
let (compacted_forest, root_map) = forest.compact();

// compacted_forest is now compacted with duplicate nodes merged

pub fn merge<'forest>( forests: impl IntoIterator<Item = &'forest MastForest>, ) -> Result<(MastForest, MastForestRootMap), MastForestError>

Merges all forests into a new MastForest.

Merging two forests means combining all their constituent parts, i.e. MastNodes and roots. During this process, any duplicate or unreachable nodes are removed. Additionally, MastNodeIds of nodes may change and references to them are remapped to their new location.

For example, consider this representation of a forest’s nodes with all of these nodes being roots:

[Block(foo), Block(bar)]

If we merge another forest into it:

[Block(bar), Call(0)]

then we would expect this forest:

[Block(foo), Block(bar), Call(1)]

• The Call to the bar block was remapped to its new index (now 1, previously 0).
• The Block(bar) was deduplicated any only exists once in the merged forest.

The function also returns a vector of MastForestRootMaps, whose length equals the number of passed forests. The indices in the vector correspond to the ones in forests. The map of a given forest contains the new locations of its roots in the merged forest. To illustrate, the above example would return a vector of two maps:

vec![{0 -> 0, 1 -> 1}
     {0 -> 1, 1 -> 2}]

• The root locations of the original forest are unchanged.
• For the second forest, the bar block has moved from index 0 to index 1 in the merged forest, and the Call has moved from index 1 to 2.

If any forest being merged contains an External(qux) node and another forest contains a node whose digest is qux, then the external node will be replaced with the qux node, which is effectively deduplication.

impl MastForest

This impl block contains no public items.

Helpers

impl MastForest

Public accessors

pub fn get_node_by_id(&self, node_id: MastNodeId) -> Option<&MastNode>

Returns the MastNode associated with the provided MastNodeId if valid, or else None.

This is the fallible version of indexing (e.g. mast_forest[node_id]).

pub fn find_procedure_root(&self, digest: Word) -> Option<MastNodeId>

Returns the MastNodeId of the procedure associated with a given digest, if any.

pub fn is_procedure_root(&self, node_id: MastNodeId) -> bool

Returns true if a node with the specified ID is a root of a procedure in this MAST forest.

pub fn is_procedure_root_with_exact_digest( &self, node_id: MastNodeId, digest: Word, ) -> bool

Returns true if a node with the specified ID is a root of a procedure in this MAST forest, and the digest of that procedure is digest.

This is primarily intended for use in confirming that procedure exports of a package, which declare their MAST node and digest, actually exist in the MAST.

pub fn procedure_digests(&self) -> impl Iterator<Item = Word>

Returns an iterator over the digests of all procedures in this MAST forest.

pub fn local_procedure_digests(&self) -> impl Iterator<Item = Word>

Returns an iterator over the digests of local procedures in this MAST forest.

A local procedure is defined as a procedure which is not a single external node.

pub fn procedure_roots(&self) -> &[MastNodeId]

Returns an iterator over the IDs of the procedures in this MAST forest.

pub fn num_procedures(&self) -> u32

Returns the number of procedures in this MAST forest.

pub fn compute_nodes_commitment<'a>( &self, node_ids: impl IntoIterator<Item = &'a MastNodeId>, ) -> Word

Returns the Word representing the content hash of a subset of MastNodeIds.

Panics

This function panics if any node_ids is not a node of this forest.

pub fn commitment(&self) -> Word

Returns the commitment to this MAST forest.

The commitment is computed as the sequential hash of all procedure roots in the forest.

The commitment uniquely identifies the forest’s structure, as each root’s digest transitively includes all of its descendants. Therefore, a commitment to all roots is a commitment to the entire forest.

pub fn num_nodes(&self) -> u32

Returns the number of nodes in this MAST forest.

pub fn nodes(&self) -> &[MastNode]

Returns the underlying nodes in this MAST forest.

pub fn advice_map(&self) -> &AdviceMap

pub fn with_advice_map(self, advice_map: AdviceMap) -> MastForest

Returns this forest with advice_map entries added.

pub fn write_hashless<W>(&self, target: &mut W)

where W: ByteWriter,

Serializes this MastForest with the HASHLESS flag set.

Hashless forest bytes omit rebuildable internal node hashes. External node digests stay on the wire because they cannot be rebuilt from local structure. Trusted deserialization rejects this flag.

Use this when producing data for untrusted validation.

impl MastForest

Validation methods

pub fn validate(&self) -> Result<(), MastForestError>

Validates that all BasicBlockNodes in this forest satisfy the core invariants:

1. Power-of-two number of groups in each batch
2. No operation group ends with an operation requiring an immediate value
3. The last operation group in a batch cannot contain operations requiring immediate values
4. OpBatch structural consistency (num_groups <= BATCH_SIZE, group size <= GROUP_SIZE, indptr integrity, bounds checking)

This addresses the gap created by PR 2094, where padding NOOPs are now inserted at assembly time rather than dynamically during execution, and adds comprehensive structural validation to prevent deserialization-time panics.

Trait Implementations

impl Clone for MastForest

fn clone(&self) -> MastForest

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for MastForest

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

Formats the value using the given formatter.

impl Default for MastForest

fn default() -> MastForest

Returns the “default value” for a type.

impl Deserializable for MastForest

fn read_from<R>(source: &mut R) -> Result<MastForest, DeserializationError>

where R: ByteReader,

Reads a sequence of bytes from the provided source, attempts to deserialize these bytes into Self, and returns the result.

fn read_from_bytes(bytes: &[u8]) -> Result<MastForest, DeserializationError>

Attempts to deserialize the provided bytes into Self and returns the result.

fn min_serialized_size() -> usize

Returns the minimum serialized size for one instance of this type.

fn read_from_bytes_with_budget( bytes: &[u8], budget: usize, ) -> Result<Self, DeserializationError>

Deserializes Self from bytes with a byte budget limit.

impl Eq for MastForest

impl ExecutableMastForest for MastForest

fn get_node_by_id(&self, node_id: MastNodeId) -> Option<&MastNode>

Returns the MastNode associated with the provided MastNodeId if present, or else None.

fn get_digest_by_id(&self, node_id: MastNodeId) -> Option<Word>

Returns the digest of the node associated with the provided MastNodeId if present, or else None.

fn find_procedure_root(&self, digest: Word) -> Option<MastNodeId>

Returns the MastNodeId of the procedure associated with a given digest, if any.

fn advice_map(&self) -> &AdviceMap

Returns the advice map associated with this forest.

impl Index<MastNodeId> for MastForest

type Output = MastNode

The returned type after indexing.

fn index( &self, node_id: MastNodeId, ) -> &<MastForest as Index<MastNodeId>>::Output

Performs the indexing (container[index]) operation.

impl MastForestView for MastForest

fn node_count(&self) -> usize

Returns the number of nodes in the forest.

fn node_entry_at( &self, index: usize, ) -> Result<MastNodeEntry, DeserializationError>

Returns fixed-width structural metadata for a node at the specified index.

fn node_digest_at(&self, index: usize) -> Result<Word, DeserializationError>

Returns the digest of the node at the specified index.

fn procedure_root_count(&self) -> usize

Returns the number of procedure roots in the forest.

fn procedure_root_at( &self, index: usize, ) -> Result<MastNodeId, DeserializationError>

Returns the procedure root id at the specified index.

fn advice_map(&self) -> AdviceMapView<'_>

Returns a read-only view over the forest advice map.

fn node_info_at( &self, index: usize, ) -> Result<MastNodeInfo, DeserializationError>

Returns serialized-equivalent metadata for a node at the specified index.

fn is_empty(&self) -> bool

Returns true when the forest contains no nodes.

fn has_node(&self, index: usize) -> bool

Returns true when index is a valid node index.

fn all_node_infos(&self) -> Result<Vec<MastNodeInfo>, DeserializationError>

Returns all node infos in index order.

fn procedure_roots(&self) -> Result<Vec<MastNodeId>, DeserializationError>

Returns all procedure roots in index order.

impl PartialEq for MastForest

Equality implementations

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serializable for MastForest

fn write_into<W>(&self, target: &mut W)

where W: ByteWriter,

Serializes self into bytes and writes these bytes into the target.

fn to_bytes(&self) -> Vec<u8>

Serializes self into a vector of bytes.

fn get_size_hint(&self) -> usize

Returns an estimate of how many bytes are needed to represent self.