Struct SerializedMastForest 

pub struct SerializedMastForest<'a> { /* private fields */ }

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

This view accepts full, stripped, and hashless payloads. It validates the header and the fixed-width structural sections needed for random access, but it does not fully materialize the forest.

Use this when callers need random access to roots or node metadata without deserializing the full forest. For strict trusted deserialization, use crate::mast::MastForest::read_from_bytes.

Examples

use miden_core::{
    mast::{BasicBlockNodeBuilder, MastForest, MastForestContributor, SerializedMastForest},
    operations::Operation,
};

let mut forest = MastForest::new();
let block_id = BasicBlockNodeBuilder::new(vec![Operation::Add], Vec::new())
    .add_to_forest(&mut forest)
    .unwrap();
forest.make_root(block_id);

let mut bytes = Vec::new();
forest.write_stripped(&mut bytes);

let view = SerializedMastForest::new(&bytes).unwrap();
assert_eq!(view.node_count(), forest.nodes().len());
assert!(view.node_info_at(0).is_ok());

Implementations

impl<'a> SerializedMastForest<'a>

pub fn new( bytes: &'a [u8], ) -> Result<SerializedMastForest<'a>, DeserializationError>

Creates a new view from serialized bytes.

The input may be full, stripped, or hashless format. Structural parsing is delegated to the same single-pass scanner used by reader-based deserialization paths.

This constructor is layout-oriented: it validates the header and sections needed for node/roots/random-access metadata only. It does not validate or fully parse trailing AdviceMap / DebugInfo payloads.

Treat this as a trusted inspection API, not as an untrusted-validation entry point. It is appropriate for local tools that need random access over serialized structure, but callers handling adversarial bytes should use crate::mast::UntrustedMastForest instead.

In particular, this constructor does not protect callers from untrusted-input concerns that are enforced by crate::mast::UntrustedMastForest::validate. It does not:

• verify that serialized non-external digests match the structure they describe
• check topological ordering / forward-reference constraints
• validate basic-block batch invariants or procedure-name-root consistency
• fully parse or validate trailing AdviceMap / DebugInfo payloads
• provide a bounded-work guarantee for hashless digest-backed inspection

For strict full-payload validation, use crate::mast::MastForest::read_from_bytes.

Wire flags describe serializer intent, not trust policy. This constructor accepts hashless payloads for inspection even though trusted crate::mast::MastForest deserialization rejects them.

Digest lookup follows the wire layout:

• If the internal-hash section is present, non-external node digests are read from it.
• If the internal-hash section is absent, the first digest-backed access rebuilds all non-external node digests from structure and caches them.
• External node digests are always read from the external-digest section.

Examples

use miden_core::{
    mast::{BasicBlockNodeBuilder, MastForest, MastForestContributor, SerializedMastForest},
    operations::Operation,
};

let mut forest = MastForest::new();
let block_id = BasicBlockNodeBuilder::new(vec![Operation::Add], Vec::new())
    .add_to_forest(&mut forest)
    .unwrap();
forest.make_root(block_id);

let mut bytes = Vec::new();
forest.write_stripped(&mut bytes);

let view = SerializedMastForest::new(&bytes).unwrap();
assert_eq!(view.node_count(), 1);

pub fn node_count(&self) -> usize

Returns the number of nodes in the serialized forest.

pub fn is_hashless(&self) -> bool

Returns true when the wire header says that the internal-hash section is omitted.

pub fn is_stripped(&self) -> bool

Returns true when the wire header says that the DebugInfo section is omitted.

pub fn procedure_root_count(&self) -> usize

Returns the number of procedure roots in the serialized forest.

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

Returns the procedure root id at the specified index.

Returns an error if index >= self.procedure_root_count().

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

Returns the MastNodeInfo at the specified index.

On hashless payloads, this may trigger the first digest-backed access and therefore the one-time rebuild of the non-external digest table described in Self::node_digest_at.

Returns an error if index >= self.node_count().

Examples

use miden_core::{
    mast::{BasicBlockNodeBuilder, MastForest, MastForestContributor, SerializedMastForest},
    operations::Operation,
};

let mut forest = MastForest::new();
let block_id = BasicBlockNodeBuilder::new(vec![Operation::Add], Vec::new())
    .add_to_forest(&mut forest)
    .unwrap();
forest.make_root(block_id);

let mut bytes = Vec::new();
forest.write_stripped(&mut bytes);

let view = SerializedMastForest::new(&bytes).unwrap();
assert!(view.node_info_at(0).is_ok());

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

Returns the fixed-width structural node entry at the specified index.

Returns an error if index >= self.node_count().

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

Returns the digest for the node at the specified index.

This resolves digests lazily. If the internal-hash section is absent, the first digest-backed access rebuilds all non-external node digests and caches them.

This means the hashless cost model is:

• node_count(), node_entry_at(), and procedure_root_at() stay cheap and structural
• the first node_digest_at() / node_info_at() call does O(node_count) digest rebuild work and allocates the cached digest table
• later digest lookups reuse that cache

Returns an error if index >= self.node_count().

Trait Implementations

impl<'a> Debug for SerializedMastForest<'a>

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

Formats the value using the given formatter.

impl MastForestView for SerializedMastForest<'_>

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 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.