miden_protocol/asset/vault/
asset_id.rs

1use alloc::boxed::Box;
2use alloc::string::{String, ToString};
3use core::fmt;
4
5use miden_crypto::merkle::smt::LeafIndex;
6use miden_crypto_derive::WordWrapper;
7
8use crate::account::{AccountId, AssetCallbackFlag};
9use crate::asset::vault::AssetClass;
10use crate::asset::{Asset, AssetComposition, FungibleAsset, NonFungibleAsset};
11use crate::crypto::merkle::smt::SMT_DEPTH;
12use crate::errors::AssetError;
13use crate::utils::serde::{
14    ByteReader,
15    ByteWriter,
16    Deserializable,
17    DeserializationError,
18    Serializable,
19};
20use crate::{Felt, Hasher, Word};
21
22/// The unique identifier of an [`Asset`] in the [`AssetVault`](crate::asset::AssetVault).
23///
24/// Its [`Word`] layout is:
25/// ```text
26/// [
27///   asset_class_suffix (64 bits),
28///   asset_class_prefix (64 bits),
29///   [faucet_id_suffix (56 bits) | reserved (6 bits) | composition (2 bits)],
30///   faucet_id_prefix (64 bits)
31/// ]
32/// ```
33///
34/// The composition is the discriminator between assets and so it is placed at a static offset much
35/// like the version in an account ID. This makes it slightly easier to change the asset metadata in
36/// the future without affecting identification of previous assets.
37///
38/// Use [`AssetId::hash`] to produce the corresponding [`AssetIdHash`] that is used as
39/// the key in the asset vault's underlying SMT. Hashing ensures a uniform distribution across
40/// leaves regardless of how faucet IDs or asset classes are chosen.
41#[derive(Debug, PartialEq, Eq, Clone, Copy)]
42pub struct AssetId {
43    /// The asset class of the asset ID.
44    asset_class: AssetClass,
45
46    /// The ID of the faucet that issued the asset.
47    faucet_id: AccountId,
48
49    /// The composition of the asset.
50    composition: AssetComposition,
51}
52
53impl AssetId {
54    /// The serialized size of an [`AssetId`] in bytes.
55    ///
56    /// Serialized as its [`Word`] representation (4 field elements).
57    pub const SERIALIZED_SIZE: usize = Word::SERIALIZED_SIZE;
58
59    // BIT LAYOUT CONSTANTS
60    // --------------------------------------------------------------------------------------------
61
62    /// The metadata byte occupies the lower 8 bits of the third element of the asset ID word.
63    pub(in crate::asset) const METADATA_BYTE_MASK: u8 = 0xff;
64
65    /// Bits 0-1 of the metadata byte encode the [`AssetComposition`]. The composition occupies
66    /// the lowest bits so its position remains stable as new metadata bits are added, since it
67    /// identifies the asset's type.
68    pub(in crate::asset) const COMPOSITION_MASK: u8 = 0b11;
69
70    /// Bits 2-7 of the metadata byte are reserved and must be zero.
71    pub(in crate::asset) const METADATA_RESERVED_MASK: u8 = 0b1111_1100;
72
73    // CONSTRUCTORS
74    // --------------------------------------------------------------------------------------------
75
76    /// Creates an [`AssetId`] from its parts with the given [`AssetComposition`].
77    ///
78    /// # Errors
79    ///
80    /// Returns an error if:
81    /// - the asset class limbs are not zero when `composition` is [`AssetComposition::Fungible`].
82    /// - the composition is [`AssetComposition::Custom`], which is disallowed until its support is
83    ///   enabled in the tx kernel.
84    pub fn new(
85        asset_class: AssetClass,
86        faucet_id: AccountId,
87        composition: AssetComposition,
88    ) -> Result<Self, AssetError> {
89        // For now, reject custom composition.
90        if composition.is_custom() {
91            return Err(AssetError::UnsupportedAssetComposition(AssetComposition::Custom));
92        }
93
94        if composition.is_fungible() && !asset_class.is_empty() {
95            return Err(AssetError::FungibleAssetClassMustBeZero(asset_class));
96        }
97
98        Ok(Self { asset_class, faucet_id, composition })
99    }
100
101    /// Constructs a fungible asset's ID from a faucet ID.
102    pub fn new_fungible(faucet_id: AccountId) -> Self {
103        Self::new(AssetClass::default(), faucet_id, AssetComposition::Fungible).expect(
104            "passing AssetComposition::Fungible together with AssetClass::default should be valid",
105        )
106    }
107
108    // PUBLIC ACCESSORS
109    // --------------------------------------------------------------------------------------------
110
111    /// Returns the word representation of the asset ID.
112    ///
113    /// See the type-level documentation for details.
114    pub fn to_word(&self) -> Word {
115        let faucet_suffix = self.faucet_id.suffix().as_canonical_u64();
116        // The lower 8 bits of the faucet suffix are guaranteed to be zero and so it is used to
117        // encode the asset metadata.
118        debug_assert!(
119            faucet_suffix & Self::METADATA_BYTE_MASK as u64 == 0,
120            "lower 8 bits of faucet suffix must be zero",
121        );
122        let metadata_byte = self.composition.as_u8();
123        let faucet_id_suffix_and_metadata = faucet_suffix | metadata_byte as u64;
124        let faucet_id_suffix_and_metadata = Felt::try_from(faucet_id_suffix_and_metadata)
125            .expect("highest bit should still be zero resulting in a valid felt");
126
127        Word::new([
128            self.asset_class.suffix(),
129            self.asset_class.prefix(),
130            faucet_id_suffix_and_metadata,
131            self.faucet_id.prefix().as_felt(),
132        ])
133    }
134
135    /// Returns the [`AssetClass`] of the asset ID that distinguishes different assets issued by
136    /// the same faucet.
137    pub fn asset_class(&self) -> AssetClass {
138        self.asset_class
139    }
140
141    /// Returns the [`AccountId`] of the faucet that issued the asset.
142    pub fn faucet_id(&self) -> AccountId {
143        self.faucet_id
144    }
145
146    /// Returns the [`AssetCallbackFlag`] of the faucet that issued the asset.
147    pub fn callback_flag(&self) -> AssetCallbackFlag {
148        self.faucet_id.asset_callback_flag()
149    }
150
151    /// Returns the [`AssetComposition`] of the asset ID.
152    pub fn composition(&self) -> AssetComposition {
153        self.composition
154    }
155
156    /// Hashes this raw asset ID to produce the [`AssetIdHash`] used as the key in the asset
157    /// vault's underlying SMT.
158    pub fn hash(&self) -> AssetIdHash {
159        AssetIdHash::from_raw(Hasher::hash_elements(self.to_word().as_elements()))
160    }
161}
162
163// ASSET ID HASH
164// ================================================================================================
165
166/// A hashed [`AssetId`].
167///
168/// This is produced by hashing an [`AssetId`] and is used as the actual key in the
169/// underlying SMT.
170#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, WordWrapper)]
171pub struct AssetIdHash(Word);
172
173impl AssetIdHash {
174    /// Returns the leaf index in the SMT for this hashed key.
175    pub fn to_leaf_index(&self) -> LeafIndex<SMT_DEPTH> {
176        self.0.into()
177    }
178}
179
180impl From<AssetIdHash> for Word {
181    fn from(id_hash: AssetIdHash) -> Self {
182        id_hash.0
183    }
184}
185
186impl From<AssetId> for AssetIdHash {
187    fn from(id: AssetId) -> Self {
188        id.hash()
189    }
190}
191
192// CONVERSIONS
193// ================================================================================================
194
195impl From<AssetId> for Word {
196    fn from(asset_id: AssetId) -> Self {
197        asset_id.to_word()
198    }
199}
200
201impl Ord for AssetId {
202    /// Implements comparison based on the [`Word`] representation.
203    fn cmp(&self, other: &Self) -> core::cmp::Ordering {
204        self.to_word().cmp(&other.to_word())
205    }
206}
207
208impl PartialOrd for AssetId {
209    fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
210        Some(self.cmp(other))
211    }
212}
213
214impl TryFrom<Word> for AssetId {
215    type Error = AssetError;
216
217    /// Attempts to convert the provided [`Word`] into an [`AssetId`].
218    ///
219    /// # Errors
220    ///
221    /// Returns an error if:
222    /// - the asset class limbs are not zero when asset composition is
223    ///   [`AssetComposition::Fungible`].
224    /// - the metadata byte has reserved bits set.
225    /// - the composition encoded in the metadata byte is invalid.
226    fn try_from(id: Word) -> Result<Self, Self::Error> {
227        let asset_class_suffix = id[0];
228        let asset_class_prefix = id[1];
229        let faucet_id_suffix_and_metadata = id[2];
230        let faucet_id_prefix = id[3];
231
232        let raw = faucet_id_suffix_and_metadata.as_canonical_u64();
233        let metadata_byte = (raw & Self::METADATA_BYTE_MASK as u64) as u8;
234
235        // Make sure the reserved bits of the metadata are zero.
236        if metadata_byte & Self::METADATA_RESERVED_MASK != 0 {
237            return Err(AssetError::ReservedAssetMetadata(metadata_byte));
238        }
239
240        let composition = AssetComposition::try_from(metadata_byte & Self::COMPOSITION_MASK)?;
241
242        let faucet_id_suffix = Felt::try_from(raw & !(Self::METADATA_BYTE_MASK as u64))
243            .expect("clearing lower bits should not produce an invalid felt");
244
245        let asset_class = AssetClass::new(asset_class_suffix, asset_class_prefix);
246        let faucet_id = AccountId::try_from_elements(faucet_id_suffix, faucet_id_prefix)
247            .map_err(|err| AssetError::InvalidFaucetAccountId(Box::new(err)))?;
248
249        Self::new(asset_class, faucet_id, composition)
250    }
251}
252
253impl fmt::Display for AssetId {
254    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
255        f.write_str(&self.to_word().to_hex())
256    }
257}
258
259impl From<Asset> for AssetId {
260    fn from(asset: Asset) -> Self {
261        asset.id()
262    }
263}
264
265impl From<FungibleAsset> for AssetId {
266    fn from(fungible_asset: FungibleAsset) -> Self {
267        fungible_asset.id()
268    }
269}
270
271impl From<NonFungibleAsset> for AssetId {
272    fn from(non_fungible_asset: NonFungibleAsset) -> Self {
273        non_fungible_asset.id()
274    }
275}
276
277// SERIALIZATION
278// ================================================================================================
279
280impl Serializable for AssetId {
281    fn write_into<W: ByteWriter>(&self, target: &mut W) {
282        self.to_word().write_into(target);
283    }
284
285    fn get_size_hint(&self) -> usize {
286        Self::SERIALIZED_SIZE
287    }
288}
289
290impl Deserializable for AssetId {
291    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
292        let word: Word = source.read()?;
293        Self::try_from(word).map_err(|err| DeserializationError::InvalidValue(err.to_string()))
294    }
295}
296
297// TESTS
298// ================================================================================================
299
300#[cfg(test)]
301mod tests {
302    use assert_matches::assert_matches;
303
304    use super::*;
305    use crate::asset::AssetComposition;
306    use crate::asset::tests::{asset_metadata, set_asset_metadata};
307    use crate::testing::account_id::{
308        ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET,
309        ACCOUNT_ID_PUBLIC_NON_FUNGIBLE_FAUCET,
310    };
311
312    #[test]
313    fn asset_id_word_roundtrip() -> anyhow::Result<()> {
314        let fungible_faucet = AccountId::try_from(ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET)?;
315        let nonfungible_faucet = AccountId::try_from(ACCOUNT_ID_PUBLIC_NON_FUNGIBLE_FAUCET)?;
316
317        // Fungible: asset_class must be zero.
318        let id = AssetId::new(AssetClass::default(), fungible_faucet, AssetComposition::Fungible)?;
319        assert_eq!(id.composition(), AssetComposition::Fungible);
320        let roundtripped = AssetId::try_from(id.to_word())?;
321        assert_eq!(id, roundtripped);
322        assert_eq!(id, AssetId::read_from_bytes(&id.to_bytes())?);
323
324        // Non-fungible: asset_class can be non-zero.
325        let id = AssetId::new(
326            AssetClass::new(Felt::from(42u32), Felt::from(99u32)),
327            nonfungible_faucet,
328            AssetComposition::None,
329        )?;
330        assert_eq!(id.composition(), AssetComposition::None);
331        let roundtripped = AssetId::try_from(id.to_word())?;
332        assert_eq!(id, roundtripped);
333        assert_eq!(id, AssetId::read_from_bytes(&id.to_bytes())?);
334
335        Ok(())
336    }
337
338    #[test]
339    fn decoding_word_with_reserved_bits_set_fails() -> anyhow::Result<()> {
340        let id = FungibleAsset::mock(42).id();
341        let valid_metadata = asset_metadata(id);
342        // Set the reserved bits so the reserved-bits check fires.
343        let word = set_asset_metadata(id, valid_metadata | AssetId::METADATA_RESERVED_MASK);
344
345        let err = AssetId::try_from(word).unwrap_err();
346        assert_matches!(err, AssetError::ReservedAssetMetadata(_));
347
348        Ok(())
349    }
350
351    #[test]
352    fn decoding_word_with_invalid_composition_value_fails() -> anyhow::Result<()> {
353        let id = FungibleAsset::mock(42).id();
354        // Set all composition bits — value 3 is the invalid bit pattern within the 2-bit field.
355        let invalid_metadata = AssetId::COMPOSITION_MASK;
356        let word = set_asset_metadata(id, invalid_metadata);
357
358        let err = AssetId::try_from(word).unwrap_err();
359        assert_matches!(err, AssetError::UnknownAssetComposition(_));
360
361        Ok(())
362    }
363}
miden_protocol/asset/vault/asset_id.rs

miden_protocol/asset/vault/
asset_id.rs
