Struct BasicBlockNode 

pub struct BasicBlockNode { /* private fields */ }

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

Executes its operations in order. Fails if any of the operations fails.

A basic block is composed of operation batches, operation batches are composed of operation groups, operation groups encode the VM’s operations and immediate values. These values are created according to these rules:

• A basic block contains one or more batches.
• A batch contains up to 8 groups, and the number of groups must be a power of 2.
• A group contains up to 9 operations or 1 immediate value.
• Last operation in a group cannot be an operation that requires an immediate value.
• NOOPs are used to fill a group or batch when necessary.
• An immediate value follows the operation that requires it, using the next available group in the batch. If there are no groups available in the batch, then both the operation and its immediate value are moved to the next batch.

Example: 8 pushes result in two operation batches:

• First batch: First group with 7 push opcodes and 2 zero-paddings packed together, followed by 7 groups with their respective immediate values.
• Second batch: First group with the last push opcode and 8 zero-paddings packed together, followed by one immediate and 6 padding groups.

The hash of a basic block is:

hash(batches, domain=BASIC_BLOCK_DOMAIN)

Where batches is the concatenation of each batch in the basic block, and each batch is 8 field elements (512 bits).

Implementations

impl BasicBlockNode

Constants

pub const DOMAIN: Felt = ZERO

The domain of the basic block node (used for control block hashing).

impl BasicBlockNode

Constructors

pub fn adjust_decorators( decorators: Vec<(usize, DecoratorId)>, op_batches: &[OpBatch], ) -> Vec<(usize, DecoratorId)>

pub fn adjust_asm_op_indices<T>( asm_ops: Vec<(usize, T)>, op_batches: &[OpBatch], ) -> Vec<(usize, T)>

where T: Copy,

Adjusts raw operation indices to padded indices for AssemblyOp mappings.

Similar to adjust_decorators, but works with AssemblyOp mappings (raw_idx, id) pairs. The op_batches contain padding NOOPs that shift operation indices. This method adjusts the raw indices to account for this padding so lookups during execution use correct indices.

pub fn unadjust_asm_op_indices<T>( asm_ops: Vec<(usize, T)>, op_batches: &[OpBatch], ) -> Vec<(usize, T)>

where T: Copy,

Adjusts padded operation indices back to raw indices for AssemblyOp mappings.

impl BasicBlockNode

Public accessors

pub fn op_batches(&self) -> &[OpBatch]

Returns a reference to the operation batches in this basic block.

pub fn num_op_batches(&self) -> usize

Returns the number of operation batches in this basic block.

pub fn num_op_groups(&self) -> usize

Returns the total number of operation groups in this basic block.

Then number of operation groups is computed as follows:

• For all batches but the last one we set the number of groups to 8, regardless of the actual number of groups in the batch. The reason for this is that when operation batches are concatenated together each batch contributes 8 elements to the hash.
• For the last batch, we take the number of actual groups and round it up to the next power of two. The reason for rounding is that the VM always executes a number of operation groups which is a power of two.

pub fn num_operations(&self) -> u32

Returns the number of operations in this basic block.

pub fn indexed_decorator_iter<'a>( &'a self, forest: &'a MastForest, ) -> DecoratorOpLinkIterator<'a>

Returns a DecoratorOpLinkIterator which allows us to iterate through the op-indexed decorators of this basic block node.

This method borrows from the forest’s storage, avoiding unnecessary Arc clones and providing efficient access to decorators.

This iterator is intended for e.g. processor consumption and provides access to only the operation-indexed decorators (excluding before_enter and after_exit decorators).

pub fn raw_decorator_iter<'a>( &'a self, forest: &'a MastForest, ) -> RawDecoratorOpLinkIterator<'a>

Returns an iterator which allows us to iterate through the decorator list of this basic block node with op indexes aligned to the “raw” (un-padded)) op batches of the basic block node.

Though this adjusts the indexation of op-indexed decorators, this iterator returns all decorators of the BasicBlockNode in the order in which they appear in the program. This includes before_enter, op-indexed decorators, and after_exit.

Returns an iterator which allows us to iterate through the decorator list of this basic block node with op indexes aligned to the “raw” (un-padded)) op batches of the basic block node.

This method borrows from the forest’s storage, avoiding unnecessary Arc clones and providing efficient access to decorators.

Though this adjusts the indexation of op-indexed decorators, this iterator returns all decorators of the BasicBlockNode in the order in which they appear in the program. This includes before_enter, op-indexed decorators, and after_exit`.

pub fn raw_op_indexed_decorators( &self, forest: &MastForest, ) -> Vec<(usize, DecoratorId)>

Returns only the raw op-indexed decorators (without before_enter/after_exit) with indices based on raw operations.

Stores decorators with raw operation indices for serialization.

Returns only the raw op-indexed decorators (without before_enter/after_exit) with indices based on raw operations.

This method borrows from the forest’s storage, avoiding unnecessary Arc clones and providing efficient access to decorators.

Stores decorators with raw operation indices for serialization.

pub fn operations(&self) -> impl Iterator<Item = &Operation>

Returns an iterator over the operations in the order in which they appear in the program.

pub fn raw_operations(&self) -> impl Iterator<Item = &Operation>

Returns an iterator over the un-padded operations in the order in which they appear in the program.

pub fn num_operations_and_decorators(&self, forest: &MastForest) -> u32

Returns the total number of operations and decorators in this basic block.

pub fn linked_id(&self) -> Option<MastNodeId>

Return the MastNodeId of this BasicBlockNode, if in Linked state

impl BasicBlockNode

pub fn validate_batch_invariants(&self) -> Result<(), String>

Validates that this BasicBlockNode satisfies the core invariants:

1. Non-final batches must be full (BATCH_SIZE groups), final batch must be power-of-two
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)
5. Immediate values are committed to empty groups and match group contents
6. OpBatch padding semantics (no padding on empty groups; padded groups end with NOOP)

Returns an error string describing which invariant was violated if validation fails.

Trait Implementations

impl Clone for BasicBlockNode

fn clone(&self) -> BasicBlockNode

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BasicBlockNode

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

Formats the value using the given formatter.

impl Eq for BasicBlockNode

impl From<BasicBlockNode> for MastNode

fn from(value: BasicBlockNode) -> MastNode

Converts to this type from the input type.

impl MastNodeExt for BasicBlockNode

fn digest(&self) -> Word

Returns a commitment to this basic block.

type Builder = BasicBlockNodeBuilder

Converts this node into its corresponding builder, reusing allocated data where possible.

fn before_enter<'a>(&'a self, forest: &'a MastForest) -> &'a [DecoratorId]

Returns the decorators to be executed before this node is executed.

fn after_exit<'a>(&'a self, forest: &'a MastForest) -> &'a [DecoratorId]

Returns the decorators to be executed after this node is executed.

fn to_display<'a>( &'a self, mast_forest: &'a MastForest, ) -> Box<dyn Display + 'a>

Returns a display formatter for this node.

fn to_pretty_print<'a>( &'a self, mast_forest: &'a MastForest, ) -> Box<dyn PrettyPrint + 'a>

Returns a pretty printer for this node.

fn has_children(&self) -> bool

Returns true if the this node has children.

fn append_children_to(&self, _target: &mut Vec<MastNodeId>)

Appends the NodeIds of the children of this node, if any, to the vector.

fn for_each_child<F>(&self, _f: F)

where F: FnMut(MastNodeId),

Executes the given closure for each child of this node.

fn domain(&self) -> Felt

Returns the domain of this node.

fn to_builder( self, forest: &MastForest, ) -> <BasicBlockNode as MastNodeExt>::Builder

fn verify_node_in_forest(&self, forest: &MastForest)

Verifies that this node is stored at the ID in its decorators field in the forest.

impl PartialEq for BasicBlockNode

fn eq(&self, other: &BasicBlockNode) -> 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 StructuralPartialEq for BasicBlockNode