miden_protocol/note/
assets.rs

1use alloc::vec::Vec;
2
3use miden_crypto::SequentialCommit;
4
5use crate::asset::{Asset, FungibleAsset, NonFungibleAsset};
6use crate::errors::NoteError;
7use crate::utils::serde::{
8    ByteReader,
9    ByteWriter,
10    Deserializable,
11    DeserializationError,
12    Serializable,
13};
14use crate::{Felt, Hasher, MAX_ASSETS_PER_NOTE, WORD_SIZE, Word};
15
16// NOTE ASSETS
17// ================================================================================================
18
19/// An asset container for a note.
20///
21/// A note can contain between 0 and 64 assets. No duplicates are allowed, but the order of assets
22/// is unspecified.
23///
24/// All the assets in a note can be reduced to a single commitment which is computed by
25/// sequentially hashing the assets. Note that the same list of assets can result in two different
26/// commitments if the asset ordering is different.
27#[derive(Debug, Default, Clone)]
28pub struct NoteAssets {
29    assets: Vec<Asset>,
30    commitment: Word,
31}
32
33impl NoteAssets {
34    // CONSTANTS
35    // --------------------------------------------------------------------------------------------
36
37    /// The maximum number of assets which can be carried by a single note.
38    pub const MAX_NUM_ASSETS: usize = MAX_ASSETS_PER_NOTE;
39
40    // CONSTRUCTOR
41    // --------------------------------------------------------------------------------------------
42
43    /// Returns new [NoteAssets] constructed from the provided list of assets.
44    ///
45    /// # Errors
46    /// Returns an error if:
47    /// - The list contains more than 64 assets.
48    /// - There are duplicate assets in the list.
49    pub fn new(assets: Vec<Asset>) -> Result<Self, NoteError> {
50        if assets.len() > Self::MAX_NUM_ASSETS {
51            return Err(NoteError::TooManyAssets(assets.len()));
52        }
53
54        // make sure all provided assets are unique
55        for (i, asset) in assets.iter().enumerate().skip(1) {
56            // for all assets except the first one, check if the asset is the same as any other
57            // asset in the list, and if so return an error
58            if assets[..i].iter().any(|a| a.is_same(asset)) {
59                return Err(match asset {
60                    Asset::Fungible(asset) => NoteError::DuplicateFungibleAsset(asset.faucet_id()),
61                    Asset::NonFungible(asset) => NoteError::DuplicateNonFungibleAsset(*asset),
62                });
63            }
64        }
65
66        let commitment = to_commitment(&assets);
67
68        Ok(Self { assets, commitment })
69    }
70
71    // PUBLIC ACCESSORS
72    // --------------------------------------------------------------------------------------------
73
74    /// Returns a commitment to the note's assets.
75    pub fn commitment(&self) -> Word {
76        self.commitment
77    }
78
79    /// Returns the number of assets.
80    pub fn num_assets(&self) -> usize {
81        self.assets.len()
82    }
83
84    /// Returns true if the number of assets is 0.
85    pub fn is_empty(&self) -> bool {
86        self.assets.is_empty()
87    }
88
89    /// Returns an iterator over all assets.
90    pub fn iter(&self) -> core::slice::Iter<'_, Asset> {
91        self.assets.iter()
92    }
93
94    /// Returns all assets represented as a vector of field elements.
95    pub fn to_elements(&self) -> Vec<Felt> {
96        <Self as SequentialCommit>::to_elements(self)
97    }
98
99    /// Returns an iterator over all [`FungibleAsset`].
100    pub fn iter_fungible(&self) -> impl Iterator<Item = FungibleAsset> {
101        self.assets.iter().filter_map(|asset| match asset {
102            Asset::Fungible(fungible_asset) => Some(*fungible_asset),
103            Asset::NonFungible(_) => None,
104        })
105    }
106
107    /// Returns iterator over all [`NonFungibleAsset`].
108    pub fn iter_non_fungible(&self) -> impl Iterator<Item = NonFungibleAsset> {
109        self.assets.iter().filter_map(|asset| match asset {
110            Asset::Fungible(_) => None,
111            Asset::NonFungible(non_fungible_asset) => Some(*non_fungible_asset),
112        })
113    }
114
115    /// Consumes self and returns the underlying vector of assets.
116    pub fn into_vec(self) -> Vec<Asset> {
117        self.assets
118    }
119}
120
121impl PartialEq for NoteAssets {
122    fn eq(&self, other: &Self) -> bool {
123        self.assets == other.assets
124    }
125}
126
127impl Eq for NoteAssets {}
128
129impl SequentialCommit for NoteAssets {
130    type Commitment = Word;
131
132    /// Returns all assets represented as a vector of field elements.
133    fn to_elements(&self) -> Vec<Felt> {
134        to_elements(&self.assets)
135    }
136
137    /// Computes the commitment to the assets.
138    fn to_commitment(&self) -> Self::Commitment {
139        to_commitment(&self.assets)
140    }
141}
142
143fn to_elements(assets: &[Asset]) -> Vec<Felt> {
144    let mut elements = Vec::with_capacity(assets.len() * 2 * WORD_SIZE);
145    elements.extend(assets.iter().flat_map(Asset::as_elements));
146    elements
147}
148
149fn to_commitment(assets: &[Asset]) -> Word {
150    Hasher::hash_elements(&to_elements(assets))
151}
152
153// SERIALIZATION
154// ================================================================================================
155
156impl Serializable for NoteAssets {
157    fn write_into<W: ByteWriter>(&self, target: &mut W) {
158        const _: () = assert!(NoteAssets::MAX_NUM_ASSETS <= u8::MAX as usize);
159        debug_assert!(self.assets.len() <= NoteAssets::MAX_NUM_ASSETS);
160        target.write_u8(self.assets.len().try_into().expect("Asset number must fit into `u8`"));
161        target.write_many(&self.assets);
162    }
163
164    fn get_size_hint(&self) -> usize {
165        // Size of the serialized asset count prefix.
166        let u8_size = 0u8.get_size_hint();
167
168        let assets_size: usize = self.assets.iter().map(|asset| asset.get_size_hint()).sum();
169
170        u8_size + assets_size
171    }
172}
173
174impl Deserializable for NoteAssets {
175    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
176        let count = source.read_u8()?;
177        let assets = source.read_many_iter::<Asset>(count.into())?.collect::<Result<_, _>>()?;
178        Self::new(assets).map_err(|e| DeserializationError::InvalidValue(format!("{e:?}")))
179    }
180}
181
182// TESTS
183// ================================================================================================
184
185#[cfg(test)]
186mod tests {
187    use alloc::vec;
188    use alloc::vec::Vec;
189
190    use assert_matches::assert_matches;
191
192    use super::NoteAssets;
193    use crate::account::AccountId;
194    use crate::asset::{Asset, FungibleAsset, NonFungibleAsset, NonFungibleAssetDetails};
195    use crate::errors::NoteError;
196    use crate::testing::account_id::{
197        ACCOUNT_ID_PRIVATE_FUNGIBLE_FAUCET,
198        ACCOUNT_ID_PRIVATE_NON_FUNGIBLE_FAUCET,
199        ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET,
200    };
201
202    /// Helper to create `n` unique non-fungible assets.
203    fn make_non_fungible_assets(n: usize) -> Vec<Asset> {
204        let faucet_id = AccountId::try_from(ACCOUNT_ID_PRIVATE_NON_FUNGIBLE_FAUCET).unwrap();
205        (0..n)
206            .map(|i| {
207                // Use the index bytes to create unique asset data.
208                let data = (i as u64).to_le_bytes().to_vec();
209                let details = NonFungibleAssetDetails::new(faucet_id, data);
210                Asset::NonFungible(NonFungibleAsset::new(&details))
211            })
212            .collect()
213    }
214
215    #[test]
216    fn iter_fungible_asset() {
217        let faucet_id_1 = AccountId::try_from(ACCOUNT_ID_PRIVATE_FUNGIBLE_FAUCET).unwrap();
218        let faucet_id_2 = AccountId::try_from(ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET).unwrap();
219        let account_id = AccountId::try_from(ACCOUNT_ID_PRIVATE_NON_FUNGIBLE_FAUCET).unwrap();
220        let details = NonFungibleAssetDetails::new(account_id, vec![1, 2, 3]);
221
222        let asset1 = Asset::Fungible(FungibleAsset::new(faucet_id_1, 100).unwrap());
223        let asset2 = Asset::Fungible(FungibleAsset::new(faucet_id_2, 50).unwrap());
224        let non_fungible_asset = Asset::NonFungible(NonFungibleAsset::new(&details));
225
226        // Create NoteAsset from assets
227        let assets = NoteAssets::new([asset1, asset2, non_fungible_asset].to_vec()).unwrap();
228
229        let mut fungible_assets = assets.iter_fungible();
230        assert_eq!(fungible_assets.next().unwrap(), asset1.unwrap_fungible());
231        assert_eq!(fungible_assets.next().unwrap(), asset2.unwrap_fungible());
232        assert_eq!(fungible_assets.next(), None);
233    }
234
235    #[test]
236    fn note_assets_at_max_succeeds() {
237        let assets = make_non_fungible_assets(NoteAssets::MAX_NUM_ASSETS);
238        assert_eq!(assets.len(), NoteAssets::MAX_NUM_ASSETS);
239
240        let note_assets = NoteAssets::new(assets).unwrap();
241        assert_eq!(note_assets.num_assets(), NoteAssets::MAX_NUM_ASSETS);
242    }
243
244    #[test]
245    fn note_assets_exceeding_max_fails() {
246        let assets = make_non_fungible_assets(NoteAssets::MAX_NUM_ASSETS + 1);
247        assert_eq!(assets.len(), NoteAssets::MAX_NUM_ASSETS + 1);
248
249        let result = NoteAssets::new(assets);
250        assert_matches!(result, Err(NoteError::TooManyAssets(n)) if n == NoteAssets::MAX_NUM_ASSETS + 1);
251    }
252}
miden_protocol/note/assets.rs

miden_protocol/note/
assets.rs
