1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
use super::{
Asset, ByteReader, ByteWriter, Deserializable, DeserializationError, Digest, Felt, Hasher,
NoteError, Serializable, Word, WORD_SIZE, ZERO,
};
use crate::{
utils::{collections::*, format},
MAX_ASSETS_PER_NOTE,
};
// NOTE ASSETS
// ================================================================================================
/// An asset container for a note.
///
/// A note must contain at least 1 asset and can contain up to 256 assets. No duplicates are
/// allowed, but the order of assets is unspecified.
///
/// All the assets in a note can be reduced to a single commitment which is computed by
/// sequentially hashing the assets. Note that the same list of assets can result in two different
/// commitments if the asset ordering is different.
#[derive(Debug, Clone)]
pub struct NoteAssets {
assets: Vec<Asset>,
hash: Digest,
}
impl NoteAssets {
// CONSTANTS
// --------------------------------------------------------------------------------------------
/// The maximum number of assets which can be carried by a single note.
pub const MAX_NUM_ASSETS: usize = MAX_ASSETS_PER_NOTE;
// CONSTRUCTOR
// --------------------------------------------------------------------------------------------
/// Returns new [NoteAssets] constructed from the provided list of assets.
///
/// # Errors
/// Returns an error if:
/// - The asset list is empty.
/// - The list contains more than 256 assets.
/// - There are duplicate assets in the list.
pub fn new(assets: &[Asset]) -> Result<Self, NoteError> {
if assets.is_empty() {
return Err(NoteError::EmptyAssetList);
} else if assets.len() > Self::MAX_NUM_ASSETS {
return Err(NoteError::too_many_assets(assets.len()));
}
// make sure all provided assets are unique
for (i, asset) in assets.iter().enumerate() {
// for all assets except the last one, check if the asset is the same as any other
// asset in the list, and if so return an error
if i < assets.len() - 1 && assets[i + 1..].iter().any(|a| a.is_same(asset)) {
return Err(match asset {
Asset::Fungible(a) => NoteError::duplicate_fungible_asset(a.faucet_id()),
Asset::NonFungible(a) => NoteError::duplicate_non_fungible_asset(*a),
});
}
}
Ok(Self {
assets: assets.to_vec(),
hash: compute_asset_commitment(assets),
})
}
// PUBLIC ACCESSORS
// --------------------------------------------------------------------------------------------
/// Returns a commitment to the note's assets.
pub fn commitment(&self) -> Digest {
self.hash
}
/// Returns the number of assets.
pub fn num_assets(&self) -> usize {
self.assets.len()
}
/// Returns an iterator over all assets.
pub fn iter(&self) -> core::slice::Iter<Asset> {
self.assets.iter()
}
/// Returns all assets represented as a vector of field elements.
///
/// The vector is padded with ZEROs so that its length is a multiple of 8. This is useful
/// because hashing the returned elements results in the note asset commitment.
pub fn to_padded_assets(&self) -> Vec<Felt> {
// if we have an odd number of assets with pad with a single word.
let padded_len = if self.assets.len() % 2 == 0 {
self.assets.len() * WORD_SIZE
} else {
(self.assets.len() + 1) * WORD_SIZE
};
// allocate a vector to hold the padded assets
let mut padded_assets = Vec::with_capacity(padded_len * WORD_SIZE);
// populate the vector with the assets
padded_assets.extend(self.assets.iter().flat_map(|asset| <[Felt; 4]>::from(*asset)));
// pad with an empty word if we have an odd number of assets
padded_assets.resize(padded_len, ZERO);
padded_assets
}
}
impl PartialEq for NoteAssets {
fn eq(&self, other: &Self) -> bool {
self.assets == other.assets
}
}
impl Eq for NoteAssets {}
// HELPER FUNCTIONS
// ================================================================================================
/// Returns a commitment to a note's assets.
///
/// The commitment is computed as a sequential hash of all assets (each asset represented by 4
/// field elements), padded to the next multiple of 2.
fn compute_asset_commitment(assets: &[Asset]) -> Digest {
// If we have an odd number of assets we pad the vector with 4 zero elements. This is to
// ensure the number of elements is a multiple of 8 - the size of the hasher rate.
let word_capacity = if assets.len() % 2 == 0 {
assets.len()
} else {
assets.len() + 1
};
let mut asset_elements = Vec::with_capacity(word_capacity * WORD_SIZE);
for asset in assets.iter() {
// convert the asset into field elements and add them to the list elements
let asset_word: Word = (*asset).into();
asset_elements.extend_from_slice(&asset_word);
}
// If we have an odd number of assets we pad the vector with 4 zero elements. This is to
// ensure the number of elements is a multiple of 8 - the size of the hasher rate. This
// simplifies hashing inside of the virtual machine when ingesting assets from a note.
if assets.len() % 2 == 1 {
asset_elements.extend_from_slice(&Word::default());
}
Hasher::hash_elements(&asset_elements)
}
// SERIALIZATION
// ================================================================================================
impl Serializable for NoteAssets {
fn write_into<W: ByteWriter>(&self, target: &mut W) {
debug_assert!(self.assets.len() <= NoteAssets::MAX_NUM_ASSETS);
target.write_u8((self.assets.len() - 1) as u8);
target.write_many(&self.assets);
}
}
impl Deserializable for NoteAssets {
fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
let count = source.read_u8()? + 1;
let assets = source.read_many::<Asset>(count.into())?;
Self::new(&assets).map_err(|e| DeserializationError::InvalidValue(format!("{e:?}")))
}
}