Struct AdviceProvider 

pub struct AdviceProvider { /* private fields */ }

An advice provider is a component through which the VM can request nondeterministic inputs from the host (i.e., result of a computation performed outside of the VM), as well as insert new data into the advice provider to be recovered by the host after the program has finished executing.

An advice provider consists of the following components:

1. Advice stack, which is a LIFO data structure. The processor can move the elements from the advice stack onto the operand stack, as well as push new elements onto the advice stack. The maximum number of elements that can be on the advice stack is 2^17.
2. Advice map, which is a key-value map where keys are words (4 field elements) and values are vectors of field elements. The processor can push the values from the map onto the advice stack, as well as insert new values into the map.
3. Merkle store, which contains structured data reducible to Merkle paths. The VM can request Merkle paths from the store, as well as mutate it by updating or merging nodes contained in the store.
4. Deferred precompile requests containing the calldata of any precompile requests made by the VM. The VM computes a commitment to the calldata of all the precompiles it requests. When verifying each call, this commitment must be recomputed and should match the one computed by the VM. After executing a program, the data in these requests can either
   • be included in the proof of the VM execution and verified natively alongside the VM proof, or,
   • used to produce a STARK proof using a precompile VM, which can be verified in the epilog of the program.

Implementations

impl AdviceProvider

pub fn apply_mutations( &mut self, mutations: impl IntoIterator<Item = AdviceMutation>, ) -> Result<(), AdviceError>

Applies the mutations given in order to the AdviceProvider.

pub fn push_stack(&mut self, value: Felt) -> Result<(), AdviceError>

Pushes a single value onto the advice stack.

pub fn push_stack_word(&mut self, word: &Word) -> Result<(), AdviceError>

Pushes a word (4 elements) onto the stack.

pub fn push_from_map( &mut self, key: Word, include_len: bool, pad_to: u8, ) -> Result<(), AdviceError>

Fetches a list of elements under the specified key from the advice map and pushes them onto the advice stack.

If include_len is set to true, this also pushes the number of elements onto the advice stack.

If pad_to is not equal to 0, the elements list obtained from the advice map will be padded with zeros, increasing its length to the next multiple of pad_to.

Note: this operation doesn’t consume the map element so it can be called multiple times for the same key.

Example

Given an advice stack [a, b, c, ...], and a map x |-> [d, e, f]:

A call push_stack(AdviceSource::Map { key: x, include_len: false, pad_to: 0 }) will result in advice stack: [d, e, f, a, b, c, ...].

A call push_stack(AdviceSource::Map { key: x, include_len: true, pad_to: 0 }) will result in advice stack: [3, d, e, f, a, b, c, ...].

A call push_stack(AdviceSource::Map { key: x, include_len: true, pad_to: 4 }) will result in advice stack: [3, d, e, f, 0, a, b, c, ...].

Errors

Returns an error if the key was not found in the key-value map.

pub fn stack(&self) -> Vec<Felt>

Returns the current stack as a vector ordered from top (index 0) to bottom.

pub fn extend_stack<I>(&mut self, iter: I) -> Result<(), AdviceError>

where I: IntoIterator<Item = Felt>,

Extends the stack with the given elements.

pub fn contains_map_key(&self, key: &Word) -> bool

Returns true if the key has a corresponding value in the map.

pub fn get_mapped_values(&self, key: &Word) -> Option<&[Felt]>

Returns a reference to the value(s) associated with the specified key in the advice map.

pub fn insert_into_map( &mut self, key: Word, values: Vec<Felt>, ) -> Result<(), AdviceError>

Inserts the provided value into the advice map under the specified key.

The values in the advice map can be moved onto the advice stack by invoking the AdviceProvider::push_from_map() method.

Returns an error if the specified key is already present in the advice map.

pub fn extend_map(&mut self, other: &AdviceMap) -> Result<(), AdviceError>

Merges all entries from the given [AdviceMap] into the current advice map.

Returns an error if any new entry already exists with the same key but a different value than the one currently stored. The current map remains unchanged.

pub fn get_tree_node( &self, root: Word, depth: Felt, index: Felt, ) -> Result<Word, AdviceError>

Returns a node at the specified depth and index in a Merkle tree with the given root.

Errors

Returns an error if:

• A Merkle tree for the specified root cannot be found in this advice provider.
• The specified depth is either zero or greater than the depth of the Merkle tree identified by the specified root.
• Value of the node at the specified depth and index is not known to this advice provider.

pub fn has_merkle_path( &self, root: Word, depth: Felt, index: Felt, ) -> Result<bool, AdviceError>

Returns true if a path to a node at the specified depth and index in a Merkle tree with the specified root exists in this Merkle store.

Errors

Returns an error if accessing the Merkle store fails.

pub fn get_merkle_path( &self, root: Word, depth: Felt, index: Felt, ) -> Result<MerklePath, AdviceError>

Returns a path to a node at the specified depth and index in a Merkle tree with the specified root.

Errors

Returns an error if:

• A Merkle tree for the specified root cannot be found in this advice provider.
• The specified depth is either zero or greater than the depth of the Merkle tree identified by the specified root.
• Path to the node at the specified depth and index is not known to this advice provider.

pub fn update_merkle_node( &mut self, root: Word, depth: Felt, index: Felt, value: Word, ) -> Result<(MerklePath, Word), AdviceError>

Updates a node at the specified depth and index in a Merkle tree with the specified root; returns the Merkle path from the updated node to the new root, together with the new root.

The tree is cloned prior to the update. Thus, the advice provider retains the original and the updated tree.

Errors

Returns an error if:

• A Merkle tree for the specified root cannot be found in this advice provider.
• The specified depth is either zero or greater than the depth of the Merkle tree identified by the specified root.
• Path to the leaf at the specified index in the specified Merkle tree is not known to this advice provider.

pub fn merge_roots(&mut self, lhs: Word, rhs: Word) -> Result<Word, AdviceError>

Creates a new Merkle tree in the advice provider by combining Merkle trees with the specified roots. The root of the new tree is defined as hash(left_root, right_root).

After the operation, both the original trees and the new tree remains in the advice provider (i.e., the input trees are not removed).

It is not checked whether a Merkle tree for either of the specified roots can be found in this advice provider.

pub fn has_merkle_root(&self, root: Word) -> bool

Returns true if the Merkle root exists for the advice provider Merkle store.

pub fn extend_merkle_store<I>(&mut self, iter: I)

where I: IntoIterator<Item = InnerNodeInfo>,

Extends the MerkleStore with the given nodes.

pub fn precompile_requests(&self) -> &[PrecompileRequest]

Returns a reference to the precompile requests.

Ordering is the same as the order in which requests are issued during execution. This ordering is relied upon when recomputing the precompile sponge during verification.

pub fn extend_precompile_requests<I>(&mut self, iter: I)

where I: IntoIterator<Item = PrecompileRequest>,

Extends the precompile requests with the given entries.

pub fn take_precompile_requests(&mut self) -> Vec<PrecompileRequest>

Moves all accumulated precompile requests out of this provider, leaving it empty.

Intended for proof packaging, where requests are serialized into the proof and no longer needed in the provider after consumption.

pub fn extend_from_inputs( &mut self, inputs: &AdviceInputs, ) -> Result<(), AdviceError>

Extends the contents of this instance with the contents of an AdviceInputs.

pub fn into_parts( self, ) -> (Vec<Felt>, AdviceMap, MerkleStore, Vec<PrecompileRequest>)

Consumes self and return its parts (stack, map, store, precompile_requests).

The returned stack vector is ordered from top (index 0) to bottom.

Trait Implementations

impl Clone for AdviceProvider

fn clone(&self) -> AdviceProvider

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AdviceProvider

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

Formats the value using the given formatter.

impl Default for AdviceProvider

fn default() -> AdviceProvider

Returns the “default value” for a type.

impl From<AdviceInputs> for AdviceProvider

fn from(inputs: AdviceInputs) -> AdviceProvider

Converts to this type from the input type.

impl PartialEq for AdviceProvider

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

impl StructuralPartialEq for AdviceProvider