miden_core/program/stack/
inputs.rs

1use alloc::vec::Vec;
2use core::{ops::Deref, slice};
3
4use super::{MIN_STACK_DEPTH, get_num_stack_values};
5use crate::{
6    Felt, ZERO,
7    serde::{ByteReader, ByteWriter, Deserializable, DeserializationError, Serializable},
8};
9
10// STACK INPUTS
11// ================================================================================================
12
13/// Defines the initial state of the VM's operand stack.
14///
15/// The first element is at position 0 (top of stack).
16#[derive(Clone, Copy, Debug, Default)]
17pub struct StackInputs {
18    elements: [Felt; MIN_STACK_DEPTH],
19}
20
21impl StackInputs {
22    // CONSTRUCTORS
23    // --------------------------------------------------------------------------------------------
24
25    /// Returns [StackInputs] from a list of values.
26    ///
27    /// The first element will be at position 0 (top of stack).
28    ///
29    /// # Errors
30    /// Returns an error if the number of input values exceeds the allowed maximum.
31    pub fn new(values: &[Felt]) -> Result<Self, InputError> {
32        if values.len() > MIN_STACK_DEPTH {
33            return Err(InputError::InputStackTooBig(MIN_STACK_DEPTH, values.len()));
34        }
35
36        let mut elements = [ZERO; MIN_STACK_DEPTH];
37        elements[..values.len()].copy_from_slice(values);
38
39        Ok(Self { elements })
40    }
41
42    // TESTING
43    // --------------------------------------------------------------------------------------------
44
45    /// Attempts to create stack inputs from an iterator of integers.
46    ///
47    /// # Errors
48    /// Returns an error if:
49    /// - The values do not represent a valid field element.
50    /// - Number of values in the iterator exceeds the allowed maximum number of input values.
51    #[cfg(any(test, feature = "testing"))]
52    pub fn try_from_ints<I>(iter: I) -> Result<Self, InputError>
53    where
54        I: IntoIterator<Item = u64>,
55    {
56        use crate::field::QuotientMap;
57
58        let values = iter
59            .into_iter()
60            .map(|v| Felt::from_canonical_checked(v).ok_or(InputError::InvalidStackElement(v)))
61            .collect::<Result<Vec<_>, _>>()?;
62
63        Self::new(&values)
64    }
65}
66
67impl Deref for StackInputs {
68    type Target = [Felt; MIN_STACK_DEPTH];
69
70    fn deref(&self) -> &Self::Target {
71        &self.elements
72    }
73}
74
75impl From<[Felt; MIN_STACK_DEPTH]> for StackInputs {
76    fn from(value: [Felt; MIN_STACK_DEPTH]) -> Self {
77        Self { elements: value }
78    }
79}
80
81impl<'a> IntoIterator for &'a StackInputs {
82    type Item = &'a Felt;
83    type IntoIter = slice::Iter<'a, Felt>;
84
85    fn into_iter(self) -> Self::IntoIter {
86        self.elements.iter()
87    }
88}
89
90impl IntoIterator for StackInputs {
91    type Item = Felt;
92    type IntoIter = core::array::IntoIter<Felt, 16>;
93
94    fn into_iter(self) -> Self::IntoIter {
95        self.elements.into_iter()
96    }
97}
98
99// SERIALIZATION
100// ================================================================================================
101
102impl Serializable for StackInputs {
103    fn write_into<W: ByteWriter>(&self, target: &mut W) {
104        let num_stack_values = get_num_stack_values(self);
105        target.write_u8(num_stack_values);
106        target.write_many(&self.elements[..num_stack_values as usize]);
107    }
108}
109
110impl Deserializable for StackInputs {
111    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
112        let num_elements = source.read_u8()?;
113        let elements: Vec<Felt> =
114            source.read_many_iter::<Felt>(num_elements.into())?.collect::<Result<_, _>>()?;
115
116        StackInputs::new(&elements).map_err(|err| {
117            DeserializationError::InvalidValue(format!("failed to create stack inputs: {err}",))
118        })
119    }
120}
121
122// INPUT ERROR
123// ================================================================================================
124
125#[derive(Clone, Debug, thiserror::Error)]
126pub enum InputError {
127    #[error("value {0} exceeds field modulus")]
128    InvalidStackElement(u64),
129    #[error("number of input values on the stack cannot exceed {0}, but was {1}")]
130    InputStackTooBig(usize, usize),
131}
miden_core/program/stack/inputs.rs

miden_core/program/stack/
inputs.rs
