miden_protocol/account/account_id/v1/

mod.rs

mod prefix;
use alloc::string::{String, ToString};
use alloc::vec::Vec;
use core::fmt;
use core::hash::Hash;

use bech32::Bech32m;
use bech32::primitives::decode::{ByteIter, CheckedHrpstring};
use miden_crypto::utils::hex_to_bytes;
pub use prefix::AccountIdPrefixV1;

use crate::account::account_id::NetworkId;
use crate::account::{AccountIdVersion, AccountType};
use crate::address::AddressType;
use crate::errors::{AccountError, AccountIdError, Bech32Error};
use crate::utils::serde::{
    ByteReader,
    ByteWriter,
    Deserializable,
    DeserializationError,
    Serializable,
};
use crate::{EMPTY_WORD, Felt, Hasher, Word};

// ACCOUNT ID VERSION 1
// ================================================================================================

/// Version 1 of the [`Account`](crate::account::Account) identifier.
///
/// See the [`AccountId`](super::AccountId) type's documentation for details.
#[derive(Debug, Copy, Clone, Eq, PartialEq)]
pub struct AccountIdV1 {
    suffix: Felt,
    prefix: Felt,
}

impl Hash for AccountIdV1 {
    fn hash<H: core::hash::Hasher>(&self, state: &mut H) {
        self.prefix.as_canonical_u64().hash(state);
        self.suffix.as_canonical_u64().hash(state);
    }
}

impl AccountIdV1 {
    // CONSTANTS
    // --------------------------------------------------------------------------------------------

    /// The serialized size of an [`AccountIdV1`] in bytes.
    const SERIALIZED_SIZE: usize = 15;

    /// The least significant nibble determines the account version.
    const VERSION_MASK: u64 = 0b1111;

    /// The second most significant bit of the prefix's least significant byte encodes the account
    /// type.
    pub(crate) const ACCOUNT_TYPE_MASK: u8 = 0b1 << Self::ACCOUNT_TYPE_SHIFT;
    pub(crate) const ACCOUNT_TYPE_SHIFT: u64 = 4;

    /// The element index in the seed digest that becomes the account ID suffix (after
    /// [`shape_suffix`]).
    pub(crate) const SEED_DIGEST_SUFFIX_ELEMENT_IDX: usize = 0;
    /// The element index in the seed digest that becomes the account ID prefix.
    pub(crate) const SEED_DIGEST_PREFIX_ELEMENT_IDX: usize = 1;

    // CONSTRUCTORS
    // --------------------------------------------------------------------------------------------

    /// See [`AccountId::new`](super::AccountId::new) for details.
    pub fn new(
        seed: Word,
        code_commitment: Word,
        storage_commitment: Word,
    ) -> Result<Self, AccountIdError> {
        let seed_digest = compute_digest(seed, code_commitment, storage_commitment);

        // Use the first half-word of the seed digest as the account ID, where the prefix is the
        // most significant element.
        let mut suffix = seed_digest[Self::SEED_DIGEST_SUFFIX_ELEMENT_IDX];
        let prefix = seed_digest[Self::SEED_DIGEST_PREFIX_ELEMENT_IDX];

        suffix = shape_suffix(suffix);

        Self::try_from_elements(suffix, prefix)
    }

    /// See [`AccountId::new_unchecked`](super::AccountId::new_unchecked) for details.
    pub fn new_unchecked(elements: [Felt; 2]) -> Self {
        let prefix = elements[0];
        let suffix = elements[1];

        // Panic on invalid felts in debug mode.
        if cfg!(debug_assertions) {
            validate_prefix(prefix).expect("AccountId::new_unchecked called with invalid prefix");
            validate_suffix(suffix).expect("AccountId::new_unchecked called with invalid suffix");
        }

        Self { prefix, suffix }
    }

    /// See [`AccountId::try_from_elements`](super::AccountId::try_from_elements) for details.
    pub fn try_from_elements(suffix: Felt, prefix: Felt) -> Result<Self, AccountIdError> {
        validate_suffix(suffix)?;
        validate_prefix(prefix)?;

        Ok(AccountIdV1 { suffix, prefix })
    }

    /// See [`AccountId::dummy`](super::AccountId::dummy) for details.
    #[cfg(any(feature = "testing", test))]
    pub fn dummy(mut bytes: [u8; 15], account_type: AccountType) -> AccountIdV1 {
        let version = AccountIdVersion::Version1 as u8;
        let low_nibble = ((account_type as u8) << Self::ACCOUNT_TYPE_SHIFT) | version;

        // Set least significant byte.
        bytes[7] = low_nibble;

        // Clear the 32nd most significant bit.
        bytes[3] &= 0b1111_1110;

        let prefix_bytes =
            bytes[0..8].try_into().expect("we should have sliced off exactly 8 bytes");
        let prefix = Felt::try_from(u64::from_be_bytes(prefix_bytes))
            .expect("should be a valid felt due to the most significant bit being zero");

        let mut suffix_bytes = [0; 8];
        // Overwrite first 7 bytes, leaving the 8th byte 0 (which will be cleared by
        // shape_suffix anyway).
        suffix_bytes[..7].copy_from_slice(&bytes[8..]);

        // Clear the most significant bit of the suffix to make sure we get a valid felt
        let suffix = u64::from_be_bytes(suffix_bytes) & 0x7fff_ffff_ffff_ffff;
        let mut suffix =
            Felt::try_from(suffix).expect("no bits were set so felt should still be valid");

        suffix = shape_suffix(suffix);

        let account_id = Self::try_from_elements(suffix, prefix)
            .expect("we should have shaped the felts to produce a valid id");

        debug_assert_eq!(account_id.account_type(), account_type);

        account_id
    }

    /// See [`AccountId::compute_account_seed`](super::AccountId::compute_account_seed) for details.
    pub fn compute_account_seed(
        init_seed: [u8; 32],
        account_type: AccountType,
        version: AccountIdVersion,
        code_commitment: Word,
        storage_commitment: Word,
    ) -> Result<Word, AccountError> {
        crate::account::account_id::seed::compute_account_seed(
            init_seed,
            account_type,
            version,
            code_commitment,
            storage_commitment,
        )
    }

    // PUBLIC ACCESSORS
    // --------------------------------------------------------------------------------------------

    /// See [`AccountId::account_type`](super::AccountId::account_type) for details.
    pub fn account_type(&self) -> AccountType {
        extract_account_type(self.prefix().as_u64())
    }

    /// See [`AccountId::is_public`](super::AccountId::is_public) for details.
    pub fn is_public(&self) -> bool {
        self.account_type() == AccountType::Public
    }

    /// See [`AccountId::version`](super::AccountId::version) for details.
    pub fn version(&self) -> AccountIdVersion {
        extract_version(self.prefix().as_u64())
            .expect("account ID should have been constructed with a valid version")
    }

    /// See [`AccountId::from_hex`](super::AccountId::from_hex) for details.
    pub fn from_hex(hex_str: &str) -> Result<AccountIdV1, AccountIdError> {
        hex_to_bytes(hex_str)
            .map_err(AccountIdError::AccountIdHexParseError)
            .and_then(AccountIdV1::try_from)
    }

    /// See [`AccountId::to_hex`](super::AccountId::to_hex) for details.
    pub fn to_hex(self) -> String {
        // We need to pad the suffix with 16 zeroes so it produces a correctly padded 8 byte
        // big-endian hex string. Only then can we cut off the last zero byte by truncating. We
        // cannot use `:014x` padding.
        let mut hex_string =
            format!("0x{:016x}{:016x}", self.prefix().as_u64(), self.suffix().as_canonical_u64());
        hex_string.truncate(32);
        hex_string
    }

    /// See [`AccountId::to_bech32`](super::AccountId::to_bech32) for details.
    pub fn to_bech32(&self, network_id: NetworkId) -> String {
        let id_bytes: [u8; Self::SERIALIZED_SIZE] = (*self).into();

        let mut data = [0; Self::SERIALIZED_SIZE + 1];
        data[0] = AddressType::AccountId as u8;
        data[1..16].copy_from_slice(&id_bytes);

        // SAFETY: Encoding only panics if the total length of the hrp, data (in GF(32)), separator
        // and checksum exceeds Bech32m::CODE_LENGTH, which is 1023. Since the data is 26 bytes in
        // that field and the hrp is at most 83 in size we are way below the limit.
        //
        // The only allowed checksum algorithm is [`Bech32m`](bech32::Bech32m) due to being the
        // best available checksum algorithm with no known weaknesses (unlike
        // [`Bech32`](bech32::Bech32)). No checksum is also not allowed since the intended
        // use of bech32 is to have error detection capabilities.
        bech32::encode::<Bech32m>(network_id.into_hrp(), &data)
            .expect("code length of bech32 should not be exceeded")
    }

    /// See [`AccountId::from_bech32`](super::AccountId::from_bech32) for details.
    pub fn from_bech32(bech32_string: &str) -> Result<(NetworkId, Self), AccountIdError> {
        // We use CheckedHrpString instead of bech32::decode with an explicit checksum algorithm so
        // we don't allow the `Bech32` or `NoChecksum` algorithms.
        let checked_string = CheckedHrpstring::new::<Bech32m>(bech32_string).map_err(|source| {
            // The CheckedHrpStringError does not implement core::error::Error, only
            // std::error::Error, so for now we convert it to a String. Even if it will
            // implement the trait in the future, we should include it as an opaque
            // error since the crate does not have a stable release yet.
            AccountIdError::Bech32DecodeError(Bech32Error::DecodeError(source.to_string().into()))
        })?;

        let hrp = checked_string.hrp();
        let network_id = NetworkId::from_hrp(hrp);

        let mut byte_iter = checked_string.byte_iter();

        // The length must be the serialized size of the account ID plus the address byte.
        if byte_iter.len() != Self::SERIALIZED_SIZE + 1 {
            return Err(AccountIdError::Bech32DecodeError(Bech32Error::InvalidDataLength {
                expected: Self::SERIALIZED_SIZE + 1,
                actual: byte_iter.len(),
            }));
        }

        let address_byte = byte_iter.next().expect("there should be at least one byte");
        if address_byte != AddressType::AccountId as u8 {
            return Err(AccountIdError::Bech32DecodeError(Bech32Error::UnknownAddressType(
                address_byte,
            )));
        }

        Self::from_bech32_byte_iter(byte_iter).map(|account_id| (network_id, account_id))
    }

    /// Decodes the data from the bech32 byte iterator into an [`AccountId`].
    pub(crate) fn from_bech32_byte_iter(byte_iter: ByteIter<'_>) -> Result<Self, AccountIdError> {
        // The _remaining_ length of the iterator must be the serialized size of the account ID.
        if byte_iter.len() != Self::SERIALIZED_SIZE {
            return Err(AccountIdError::Bech32DecodeError(Bech32Error::InvalidDataLength {
                expected: Self::SERIALIZED_SIZE,
                actual: byte_iter.len(),
            }));
        }

        // Every byte is guaranteed to be overwritten since we've checked the length of the
        // iterator.
        let mut id_bytes = [0_u8; Self::SERIALIZED_SIZE];
        for (i, byte) in byte_iter.enumerate() {
            id_bytes[i] = byte;
        }

        let account_id = Self::try_from(id_bytes)?;

        Ok(account_id)
    }

    /// Returns the [`AccountIdPrefixV1`] of this account ID.
    ///
    /// See also [`AccountId::prefix`](super::AccountId::prefix) for details.
    pub fn prefix(&self) -> AccountIdPrefixV1 {
        // SAFETY: We only construct account IDs with valid prefixes, so we don't have to validate
        // it again.
        AccountIdPrefixV1::new_unchecked(self.prefix)
    }

    /// See [`AccountId::suffix`](super::AccountId::suffix) for details.
    pub const fn suffix(&self) -> Felt {
        self.suffix
    }
}

// CONVERSIONS FROM ACCOUNT ID
// ================================================================================================

impl From<AccountIdV1> for [Felt; 2] {
    fn from(id: AccountIdV1) -> Self {
        [id.prefix, id.suffix]
    }
}

impl From<AccountIdV1> for [u8; 15] {
    fn from(id: AccountIdV1) -> Self {
        let mut result = [0_u8; 15];
        result[..8].copy_from_slice(&id.prefix().as_u64().to_be_bytes());
        // The last byte of the suffix is always zero so we skip it here.
        result[8..].copy_from_slice(&id.suffix().as_canonical_u64().to_be_bytes()[..7]);
        result
    }
}

impl From<AccountIdV1> for u128 {
    fn from(id: AccountIdV1) -> Self {
        let mut le_bytes = [0_u8; 16];
        le_bytes[..8].copy_from_slice(&id.suffix().as_canonical_u64().to_le_bytes());
        le_bytes[8..].copy_from_slice(&id.prefix().as_u64().to_le_bytes());
        u128::from_le_bytes(le_bytes)
    }
}

// CONVERSIONS TO ACCOUNT ID
// ================================================================================================

impl TryFrom<[u8; 15]> for AccountIdV1 {
    type Error = AccountIdError;

    /// See [`TryFrom<[u8; 15]> for
    /// AccountId`](super::AccountId#impl-TryFrom<%5Bu8;+15%5D>-for-AccountId) for details.
    fn try_from(mut bytes: [u8; 15]) -> Result<Self, Self::Error> {
        // Felt::try_from expects little-endian order, so reverse the individual felt slices.
        // This prefix slice has 8 bytes.
        bytes[..8].reverse();
        // The suffix slice has 7 bytes, since the 8th byte will always be zero.
        bytes[8..15].reverse();

        let prefix_slice = &bytes[..8];
        let suffix_slice = &bytes[8..15];

        // The byte order is little-endian here, so we prepend a 0 to set the least significant
        // byte.
        let mut suffix_bytes = [0; 8];
        suffix_bytes[1..8].copy_from_slice(suffix_slice);

        let prefix = Felt::try_from(u64::from_le_bytes(
            prefix_slice.try_into().expect("prefix slice should be 8 bytes"),
        ))
        .map_err(|err| {
            AccountIdError::AccountIdInvalidPrefixFieldElement(DeserializationError::InvalidValue(
                err.to_string(),
            ))
        })?;

        let suffix = Felt::try_from(u64::from_le_bytes(suffix_bytes)).map_err(|err| {
            AccountIdError::AccountIdInvalidSuffixFieldElement(DeserializationError::InvalidValue(
                err.to_string(),
            ))
        })?;

        Self::try_from_elements(suffix, prefix)
    }
}

impl TryFrom<u128> for AccountIdV1 {
    type Error = AccountIdError;

    /// See [`TryFrom<u128> for AccountId`](super::AccountId#impl-TryFrom<u128>-for-AccountId) for
    /// details.
    fn try_from(int: u128) -> Result<Self, Self::Error> {
        let mut bytes: [u8; 15] = [0; 15];
        bytes.copy_from_slice(&int.to_be_bytes()[0..15]);

        Self::try_from(bytes)
    }
}

// SERIALIZATION
// ================================================================================================

impl Serializable for AccountIdV1 {
    fn write_into<W: ByteWriter>(&self, target: &mut W) {
        let bytes: [u8; 15] = (*self).into();
        bytes.write_into(target);
    }

    fn get_size_hint(&self) -> usize {
        Self::SERIALIZED_SIZE
    }
}

impl Deserializable for AccountIdV1 {
    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
        <[u8; 15]>::read_from(source)?
            .try_into()
            .map_err(|err: AccountIdError| DeserializationError::InvalidValue(err.to_string()))
    }
}

// HELPER FUNCTIONS
// ================================================================================================

/// Checks that the prefix has a known value for the version.
pub(crate) fn validate_prefix(
    prefix: Felt,
) -> Result<(AccountType, AccountIdVersion), AccountIdError> {
    let prefix = prefix.as_canonical_u64();

    let account_type = extract_account_type(prefix);

    // Validate version bits.
    let version = extract_version(prefix)?;

    Ok((account_type, version))
}

/// Checks that the suffix:
/// - has its most significant bit set to zero.
/// - has its lower 8 bits set to zero.
fn validate_suffix(suffix: Felt) -> Result<(), AccountIdError> {
    let suffix = suffix.as_canonical_u64();

    // Validate most significant bit is zero.
    if suffix >> 63 != 0 {
        return Err(AccountIdError::AccountIdSuffixMostSignificantBitMustBeZero);
    }

    // Validate lower 8 bits of second felt are zero.
    if suffix & 0xff != 0 {
        return Err(AccountIdError::AccountIdSuffixLeastSignificantByteMustBeZero);
    }

    Ok(())
}

pub(crate) fn extract_account_type(prefix: u64) -> AccountType {
    let bits = (prefix & AccountIdV1::ACCOUNT_TYPE_MASK as u64) >> AccountIdV1::ACCOUNT_TYPE_SHIFT;
    // SAFETY: `ACCOUNT_TYPE_MASK` is u8 so casting bits is lossless
    match bits as u8 {
        AccountType::PRIVATE => AccountType::Private,
        AccountType::PUBLIC => AccountType::Public,
        _ => unreachable!("account type mask is 1 bit so every value is covered above"),
    }
}

pub(crate) fn extract_version(prefix: u64) -> Result<AccountIdVersion, AccountIdError> {
    // SAFETY: The mask guarantees that we only mask out the least significant nibble, so casting to
    // u8 is safe.
    let version = (prefix & AccountIdV1::VERSION_MASK) as u8;
    AccountIdVersion::try_from(version)
}

/// Shapes the suffix so it meets the requirements of the account ID, by setting the lower 8 bits to
/// zero.
fn shape_suffix(suffix: Felt) -> Felt {
    let mut suffix = suffix.as_canonical_u64();

    // Clear the lower 8 bits.
    suffix &= 0xffff_ffff_ffff_ff00;

    // SAFETY: Felt was previously valid and we only cleared bits, so it must still be valid.
    Felt::try_from(suffix).expect("no bits were set so felt should still be valid")
}

// COMMON TRAIT IMPLS
// ================================================================================================

impl PartialOrd for AccountIdV1 {
    fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
        Some(self.cmp(other))
    }
}

impl Ord for AccountIdV1 {
    fn cmp(&self, other: &Self) -> core::cmp::Ordering {
        u128::from(*self).cmp(&u128::from(*other))
    }
}

impl fmt::Display for AccountIdV1 {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.to_hex())
    }
}

/// Returns the digest of two hashing permutations over the seed, code commitment, storage
/// commitment and padding.
pub(crate) fn compute_digest(seed: Word, code_commitment: Word, storage_commitment: Word) -> Word {
    let mut elements = Vec::with_capacity(16);
    elements.extend(seed);
    elements.extend(*code_commitment);
    elements.extend(*storage_commitment);
    elements.extend(EMPTY_WORD);
    Hasher::hash_elements(&elements)
}

// TESTS
// ================================================================================================

#[cfg(test)]
mod tests {

    use rstest::rstest;

    use super::*;
    use crate::account::AccountIdPrefix;
    use crate::testing::account_id::{
        ACCOUNT_ID_PRIVATE_NON_FUNGIBLE_FAUCET,
        ACCOUNT_ID_PRIVATE_SENDER,
        ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET,
        ACCOUNT_ID_REGULAR_PRIVATE_ACCOUNT_UPDATABLE_CODE,
        ACCOUNT_ID_REGULAR_PUBLIC_ACCOUNT_IMMUTABLE_CODE,
    };

    #[test]
    fn account_id_from_felts_with_max_pop_count() {
        let valid_suffix = Felt::try_from(0x7fff_ffff_ffff_ff00u64).unwrap();
        let valid_prefix = Felt::try_from(0x7fff_ffff_ffff_fff1u64).unwrap();

        let id1 = AccountIdV1::new_unchecked([valid_prefix, valid_suffix]);
        assert_eq!(id1.account_type(), AccountType::Public);
        assert_eq!(id1.version(), AccountIdVersion::Version1);
    }

    #[rstest]
    fn account_id_serde_roundtrip(
        // Use the highest possible input to check if the constructed id is a valid Felt in that
        // scenario.
        // Use the lowest possible input to check whether the constructor produces valid IDs with
        // all-zeroes input.
        #[values([0xff; 15], [0; 15])] input: [u8; 15],
        #[values(AccountType::Private, AccountType::Public)] account_type: AccountType,
    ) {
        let id = AccountIdV1::dummy(input, account_type);
        assert_eq!(id.account_type(), account_type);
        assert_eq!(id.version(), AccountIdVersion::Version1);

        // Do a serialization roundtrip to ensure validity.
        let serialized_id = id.to_bytes();
        AccountIdV1::read_from_bytes(&serialized_id).unwrap();
        assert_eq!(serialized_id.len(), AccountIdV1::SERIALIZED_SIZE);

        let serialized_prefix = id.prefix().to_bytes();
        AccountIdPrefix::read_from_bytes(&serialized_prefix).unwrap();
        assert_eq!(serialized_prefix.len(), AccountIdPrefix::SERIALIZED_SIZE);
    }

    #[test]
    fn account_id_prefix_serialization_compatibility() {
        // Ensure that an AccountIdPrefix can be read from the serialized bytes of an AccountId.
        let account_id = AccountIdV1::try_from(ACCOUNT_ID_PRIVATE_SENDER).unwrap();
        let id_bytes = account_id.to_bytes();
        assert_eq!(account_id.prefix().to_bytes(), id_bytes[..8]);

        let deserialized_prefix = AccountIdPrefix::read_from_bytes(&id_bytes).unwrap();
        assert_eq!(AccountIdPrefix::V1(account_id.prefix()), deserialized_prefix);

        // Ensure AccountId and AccountIdPrefix's hex representation are compatible.
        assert!(account_id.to_hex().starts_with(&account_id.prefix().to_hex()));
    }

    // CONVERSION TESTS
    // ================================================================================================

    #[test]
    fn test_account_id_conversion_roundtrip() {
        for (idx, account_id) in [
            ACCOUNT_ID_REGULAR_PUBLIC_ACCOUNT_IMMUTABLE_CODE,
            ACCOUNT_ID_REGULAR_PRIVATE_ACCOUNT_UPDATABLE_CODE,
            ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET,
            ACCOUNT_ID_PRIVATE_NON_FUNGIBLE_FAUCET,
            ACCOUNT_ID_PRIVATE_SENDER,
        ]
        .into_iter()
        .enumerate()
        {
            let id = AccountIdV1::try_from(account_id).expect("account ID should be valid");
            assert_eq!(id, AccountIdV1::from_hex(&id.to_hex()).unwrap(), "failed in {idx}");
            assert_eq!(id, AccountIdV1::try_from(<[u8; 15]>::from(id)).unwrap(), "failed in {idx}");
            assert_eq!(id, AccountIdV1::try_from(u128::from(id)).unwrap(), "failed in {idx}");
            // The u128 big-endian representation without the least significant byte and the
            // [u8; 15] representations should be equivalent.
            assert_eq!(u128::from(id).to_be_bytes()[0..15], <[u8; 15]>::from(id));
            assert_eq!(account_id, u128::from(id), "failed in {idx}");
        }
    }

    #[test]
    fn test_account_id_accessors() {
        let account_id = AccountIdV1::try_from(ACCOUNT_ID_REGULAR_PUBLIC_ACCOUNT_IMMUTABLE_CODE)
            .expect("valid account ID");
        assert!(account_id.is_public());

        let account_id = AccountIdV1::try_from(ACCOUNT_ID_REGULAR_PRIVATE_ACCOUNT_UPDATABLE_CODE)
            .expect("valid account ID");
        assert!(!account_id.is_public());

        let account_id =
            AccountIdV1::try_from(ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET).expect("valid account ID");
        assert!(account_id.is_public());

        let account_id = AccountIdV1::try_from(ACCOUNT_ID_PRIVATE_NON_FUNGIBLE_FAUCET)
            .expect("valid account ID");
        assert!(!account_id.is_public());
    }
}