Struct AdviceStackBuilder 

pub struct AdviceStackBuilder { /* private fields */ }

A builder for constructing advice stack inputs with intuitive ordering.

The builder maintains a conceptual advice stack where index 0 is the “top” - i.e., the element that will be consumed first. Method names indicate which MASM instruction pattern they target, abstracting away the internal transformations needed for correct element ordering.

Building Direction

Building happens “top-first”: the first method call adds elements that will be consumed first by the MASM code. Each subsequent method call adds elements “below” the previous ones.

Example

let advice = AdviceStackBuilder::new()
    .push_for_adv_push(&[a, b, c])  // Consumed first by adv_push adv_push adv_push
    .push_word(word)                // Consumed second by adv_loadw (or adv_pushw)
    .build();

Implementations

impl AdviceStackBuilder

pub fn new() -> AdviceStackBuilder

Creates a new empty builder.

pub fn push_element(&mut self, value: Felt) -> &mut AdviceStackBuilder

Pushes a single element onto the advice stack.

Elements are consumed in FIFO order: first pushed = first consumed by advice operations.

pub fn push_elements<I>(&mut self, values: I) -> &mut AdviceStackBuilder

where I: IntoIterator<Item = Felt>,

Extends the advice stack with raw elements (already ordered top-to-bottom).

Elements are consumed in FIFO order: first element in iter = first consumed.

pub fn push_for_adv_push(&mut self, slice: &[Felt]) -> &mut AdviceStackBuilder

Adds elements for consumption by multiple sequential adv_push instructions.

After repeat.n adv_push end, the operand stack will have slice[0] on top.

How it works

Each adv_push pops one element from the advice stack and pushes it to the operand stack. Since each push goes to the top, the first-popped element ends up at the bottom of the n elements, and the last-popped element ends up on top.

Therefore, this method reverses the slice internally so that slice[0] is popped last and ends up on top of the operand stack.

Example

builder.push_for_adv_push(&[a, b, c]);
// MASM: adv_push adv_push adv_push
// Result: operand stack = [a, b, c, ...] with a on top

pub fn push_word(&mut self, word: Word) -> &mut AdviceStackBuilder

Adds a word for consumption by adv_loadw or adv_pushw.

Both instructions consume the same 4 elements from the advice stack and place them on the operand stack with word[0] on top; they differ only in whether the top operand word is overwritten (adv_loadw) or the stack grows by 4 (adv_pushw).

Example

builder.push_word([w0, w1, w2, w3].into());
// MASM: adv_loadw (or adv_pushw)
// Result: operand stack = [w0, w1, w2, w3, ...] with w0 on top

pub fn push_for_adv_pipe(&mut self, slice: &[Felt]) -> &mut AdviceStackBuilder

Adds elements for sequential consumption by adv_pipe operations.

Elements are consumed in order: slice[0..8] first, then slice[8..16], etc. No reversal is applied.

Panics

Panics if the slice length is not a multiple of 8 (double-word aligned).

Example

builder.push_for_adv_pipe(&elements); // elements.len() must be multiple of 8
// MASM: multiple adv_pipe calls
// Result: elements consumed in order [elements[0], elements[1], ...]

pub fn push_u64_slice(&mut self, values: &[u64]) -> &mut AdviceStackBuilder

Extends the advice stack with u64 values converted to Felt.

This is a convenience method for test data that is typically specified as u64. Elements are consumed in FIFO order: first element = first consumed.

Example

builder.push_u64_slice(&[1, 2, 3, 4, 5, 6, 7, 8]);
// Elements consumed in order: 1, 2, 3, 4, 5, 6, 7, 8

pub fn build(self) -> AdviceInputs

Builds the AdviceInputs from the accumulated stack.

The builder’s conceptual stack (with index 0 as top) is converted to the format expected by AdviceInputs, which will be reversed when creating an AdviceProvider.

pub fn build_with(self, map: AdviceMap, store: MerkleStore) -> AdviceInputs

Builds the AdviceInputs with additional map and store data.

pub fn build_vec_u64(self) -> Vec<u64>

Builds just the advice stack as Vec<u64> for use with build_test! macro.

This is a convenience method that avoids needing to modify the test infrastructure.

pub fn into_elements(self) -> Vec<Felt>

Consumes the builder and returns the accumulated elements as Vec<Felt>.

Trait Implementations

impl Clone for AdviceStackBuilder

fn clone(&self) -> AdviceStackBuilder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AdviceStackBuilder

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

Formats the value using the given formatter.

impl Default for AdviceStackBuilder

fn default() -> AdviceStackBuilder

Returns the “default value” for a type.