miden_processor/host/advice/
inputs.rs

1use alloc::vec::Vec;
2
3use miden_core::{
4    AdviceMap, Felt, Word,
5    crypto::merkle::MerkleStore,
6    errors::InputError,
7    utils::{ByteReader, ByteWriter, Deserializable, DeserializationError, Serializable},
8};
9
10// ADVICE INPUTS
11// ================================================================================================
12
13/// Inputs container to initialize advice provider for the execution of Miden VM programs.
14///
15/// The program may request nondeterministic advice inputs from the prover. These inputs are secret
16/// inputs. This means that the prover does not need to share them with the verifier.
17///
18/// There are three types of advice inputs:
19///
20/// 1. Single advice stack which can contain any number of elements.
21/// 2. Key-mapped element lists which can be pushed onto the advice stack.
22/// 3. Merkle store, which is used to provide nondeterministic inputs for instructions that operates
23///    with Merkle trees.
24#[derive(Clone, Debug, Default, PartialEq, Eq)]
25pub struct AdviceInputs {
26    pub stack: Vec<Felt>,
27    pub map: AdviceMap,
28    pub store: MerkleStore,
29}
30
31impl AdviceInputs {
32    // CONSTRUCTORS
33    // --------------------------------------------------------------------------------------------
34
35    /// Attempts to extend the stack values with the given sequence of integers, returning an error
36    /// if any of the numbers fails while converting to an element `[Felt]`.
37    pub fn with_stack_values<I>(mut self, iter: I) -> Result<Self, InputError>
38    where
39        I: IntoIterator<Item = u64>,
40    {
41        let stack = iter
42            .into_iter()
43            .map(|v| Felt::try_from(v).map_err(|e| InputError::NotFieldElement(v, e)))
44            .collect::<Result<Vec<_>, _>>()?;
45
46        self.stack.extend(stack.iter());
47        Ok(self)
48    }
49
50    /// Extends the stack with the given elements.
51    pub fn with_stack<I>(mut self, iter: I) -> Self
52    where
53        I: IntoIterator<Item = Felt>,
54    {
55        self.stack.extend(iter);
56        self
57    }
58
59    /// Extends the map of values with the given argument, replacing previously inserted items.
60    pub fn with_map<I>(mut self, iter: I) -> Self
61    where
62        I: IntoIterator<Item = (Word, Vec<Felt>)>,
63    {
64        self.map.extend(iter);
65        self
66    }
67
68    /// Replaces the [MerkleStore] with the provided argument.
69    pub fn with_merkle_store(mut self, store: MerkleStore) -> Self {
70        self.store = store;
71        self
72    }
73
74    // PUBLIC MUTATORS
75    // --------------------------------------------------------------------------------------------
76
77    /// Extends the contents of this instance with the contents of the other instance.
78    pub fn extend(&mut self, other: Self) {
79        self.stack.extend(other.stack);
80        self.map.extend(other.map);
81        self.store.extend(other.store.inner_nodes());
82    }
83}
84
85impl Serializable for AdviceInputs {
86    fn write_into<W: ByteWriter>(&self, target: &mut W) {
87        let Self { stack, map, store } = self;
88        stack.write_into(target);
89        map.write_into(target);
90        store.write_into(target);
91    }
92}
93
94impl Deserializable for AdviceInputs {
95    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
96        let stack = Vec::<Felt>::read_from(source)?;
97        let map = AdviceMap::read_from(source)?;
98        let store = MerkleStore::read_from(source)?;
99        Ok(Self { stack, map, store })
100    }
101}
102
103// TESTS
104// ================================================================================================
105
106#[cfg(test)]
107mod tests {
108    use winter_utils::{Deserializable, Serializable};
109
110    use crate::AdviceInputs;
111
112    #[test]
113    fn test_advice_inputs_eq() {
114        let advice1 = AdviceInputs::default();
115        let advice2 = AdviceInputs::default();
116
117        assert_eq!(advice1, advice2);
118
119        let advice1 = AdviceInputs::default().with_stack_values([1, 2, 3].iter().copied()).unwrap();
120        let advice2 = AdviceInputs::default().with_stack_values([1, 2, 3].iter().copied()).unwrap();
121
122        assert_eq!(advice1, advice2);
123    }
124
125    #[test]
126    fn test_advice_inputs_serialization() {
127        let advice1 = AdviceInputs::default().with_stack_values([1, 2, 3].iter().copied()).unwrap();
128        let bytes = advice1.to_bytes();
129        let advice2 = AdviceInputs::read_from_bytes(&bytes).unwrap();
130
131        assert_eq!(advice1, advice2);
132    }
133}
miden_processor/host/advice/inputs.rs

miden_processor/host/advice/
inputs.rs
