miden_objects/account/account_id/

mod.rs

pub(crate) mod v0;
pub use v0::{AccountIdPrefixV0, AccountIdV0};

mod id_prefix;
pub use id_prefix::AccountIdPrefix;

mod seed;

mod network_id;
pub use network_id::NetworkId;

mod account_type;
pub use account_type::AccountType;

mod storage_mode;
pub use storage_mode::AccountStorageMode;

mod id_version;
use alloc::string::{String, ToString};
use core::fmt;

pub use id_version::AccountIdVersion;
use miden_core::Felt;
use miden_core::utils::{ByteReader, Deserializable, Serializable};
use miden_crypto::utils::hex_to_bytes;
use miden_processor::DeserializationError;

use crate::errors::AccountIdError;
use crate::{AccountError, Word};

/// The identifier of an [`Account`](crate::account::Account).
///
/// This enum is a wrapper around concrete versions of IDs. The following documents version 0.
///
/// # Layout
///
/// An `AccountId` consists of two field elements, where the first is called the prefix and the
/// second is called the suffix. It is laid out as follows:
///
/// ```text
/// prefix: [hash (56 bits) | storage mode (2 bits) | type (2 bits) | version (4 bits)]
/// suffix: [zero bit | hash (55 bits) | 8 zero bits]
/// ```
///
/// # Generation
///
/// An `AccountId` is a commitment to a user-generated seed and the code and storage of an account.
/// An id is generated by first creating the account's initial storage and code. Then a random seed
/// is picked and the hash of `(SEED, CODE_COMMITMENT, STORAGE_COMMITMENT, EMPTY_WORD)` is computed.
/// This process is repeated until the hash's first element has the desired storage mode, account
/// type and version and the suffix' most significant bit is zero.
///
/// The prefix of the ID is exactly the first element of the hash. The suffix of the ID is the
/// second element of the hash, but its lower 8 bits are zeroed. Thus, the prefix of the ID must
/// derive exactly from the hash, while only the first 56 bits of the suffix are derived from the
/// hash.
///
/// In total, due to requiring specific bits for storage mode, type, version and the most
/// significant bit in the suffix, generating an ID requires 9 bits of Proof-of-Work.
///
/// # Constraints
///
/// Constructors will return an error if:
///
/// - The prefix contains account ID metadata (storage mode, type or version) that does not match
///   any of the known values.
/// - The most significant bit of the suffix is not zero.
/// - The lower 8 bits of the suffix are not zero, although [`AccountId::new`] ensures this is the
///   case rather than return an error.
///
/// # Design Rationale
///
/// The rationale behind the above layout is as follows.
///
/// - The prefix is the output of a hash function so it will be a valid field element without
///   requiring additional constraints.
/// - The version is placed at a static offset such that future ID versions which may change the
///   number of type or storage mode bits will not cause the version to be at a different offset.
///   This is important so that a parser can always reliably read the version and then parse the
///   remainder of the ID depending on the version. Having only 4 bits for the version is a trade
///   off between future proofing to allow introducing more versions and the version requiring Proof
///   of Work as part of the ID generation.
/// - The version, type and storage mode are part of the prefix which is included in the
///   representation of a non-fungible asset. The prefix alone is enough to determine all of these
///   properties about the ID.
/// - The most significant bit of the suffix must be zero to ensure the value of the suffix is
///   always a valid felt, even if the lower 8 bits are all set to `1`. The lower 8 bits of the
///   suffix may be overwritten when the ID is embedded in other layouts such as the
///   [`NoteMetadata`](crate::note::NoteMetadata). In that case, it can happen that all lower bits
///   of the encoded suffix are one, so having the zero bit constraint is important for validity.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum AccountId {
    V0(AccountIdV0),
}

impl AccountId {
    // CONSTANTS
    // --------------------------------------------------------------------------------------------

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

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

    /// Creates an [`AccountId`] by hashing the given `seed`, `code_commitment`,
    /// `storage_commitment` and using the resulting first and second element of the hash as the
    /// prefix and suffix felts of the ID.
    ///
    /// See the documentation of the [`AccountId`] for more details on the generation.
    ///
    /// # Errors
    ///
    /// Returns an error if any of the ID constraints are not met. See the [constraints
    /// documentation](AccountId#constraints) for details.
    pub fn new(
        seed: Word,
        version: AccountIdVersion,
        code_commitment: Word,
        storage_commitment: Word,
    ) -> Result<Self, AccountIdError> {
        match version {
            AccountIdVersion::Version0 => {
                AccountIdV0::new(seed, code_commitment, storage_commitment).map(Self::V0)
            },
        }
    }

    /// Creates an [`AccountId`] from the given felts where the felt at index 0 is the prefix
    /// and the felt at index 1 is the suffix.
    ///
    /// # Warning
    ///
    /// Validity of the ID must be ensured by the caller. An invalid ID may lead to panics.
    ///
    /// # Panics
    ///
    /// Panics if the prefix does not contain a known account ID version.
    ///
    /// If debug_assertions are enabled (e.g. in debug mode), this function panics if any of the ID
    /// constraints are not met. See the [constraints documentation](AccountId#constraints) for
    /// details.
    pub fn new_unchecked(elements: [Felt; 2]) -> Self {
        // The prefix contains the metadata.
        // If we add more versions in the future, we may need to generalize this.
        match v0::extract_version(elements[0].as_int())
            .expect("prefix should contain a valid account ID version")
        {
            AccountIdVersion::Version0 => Self::V0(AccountIdV0::new_unchecked(elements)),
        }
    }

    /// Constructs an [`AccountId`] for testing purposes with the given account type, storage
    /// mode.
    ///
    /// This function does the following:
    /// - Split the given bytes into a `prefix = bytes[0..8]` and `suffix = bytes[8..]` part to be
    ///   used for the prefix and suffix felts, respectively.
    /// - The least significant byte of the prefix is set to the given version, type and storage
    ///   mode.
    /// - The 32nd most significant bit in the prefix is cleared to ensure it is a valid felt. The
    ///   32nd is chosen as it is the lowest bit that we can clear and still ensure felt validity.
    ///   This leaves the upper 31 bits to be set by the input `bytes` which makes it simpler to
    ///   create test values which more often need specific values for the most significant end of
    ///   the ID.
    /// - In the suffix the most significant bit and the lower 8 bits are cleared.
    #[cfg(any(feature = "testing", test))]
    pub fn dummy(
        bytes: [u8; 15],
        version: AccountIdVersion,
        account_type: AccountType,
        storage_mode: AccountStorageMode,
    ) -> AccountId {
        match version {
            AccountIdVersion::Version0 => {
                Self::V0(AccountIdV0::dummy(bytes, account_type, storage_mode))
            },
        }
    }

    /// Grinds an account seed until its hash matches the given `account_type`, `storage_mode` and
    /// `version` and returns it as a [`Word`]. The input to the hash function next to the seed are
    /// the `code_commitment` and `storage_commitment`.
    ///
    /// The grinding process is started from the given `init_seed` which should be a random seed
    /// generated from a cryptographically secure source.
    pub fn compute_account_seed(
        init_seed: [u8; 32],
        account_type: AccountType,
        storage_mode: AccountStorageMode,
        version: AccountIdVersion,
        code_commitment: Word,
        storage_commitment: Word,
    ) -> Result<Word, AccountError> {
        match version {
            AccountIdVersion::Version0 => AccountIdV0::compute_account_seed(
                init_seed,
                account_type,
                storage_mode,
                version,
                code_commitment,
                storage_commitment,
            ),
        }
    }

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

    /// Returns the type of this account ID.
    pub const fn account_type(&self) -> AccountType {
        match self {
            AccountId::V0(account_id) => account_id.account_type(),
        }
    }

    /// Returns `true` if an account with this ID is a faucet which can issue assets.
    pub fn is_faucet(&self) -> bool {
        self.account_type().is_faucet()
    }

    /// Returns `true` if an account with this ID is a regular account.
    pub fn is_regular_account(&self) -> bool {
        self.account_type().is_regular_account()
    }

    /// Returns the storage mode of this account ID.
    pub fn storage_mode(&self) -> AccountStorageMode {
        match self {
            AccountId::V0(account_id) => account_id.storage_mode(),
        }
    }

    /// Returns `true` if the full state of the account is on chain, i.e. if the modes are
    /// [`AccountStorageMode::Public`] or [`AccountStorageMode::Network`], `false` otherwise.
    pub fn is_onchain(&self) -> bool {
        self.storage_mode().is_onchain()
    }

    /// Returns `true` if the storage mode is [`AccountStorageMode::Public`], `false` otherwise.
    pub fn is_public(&self) -> bool {
        self.storage_mode().is_public()
    }

    /// Returns `true` if the storage mode is [`AccountStorageMode::Network`], `false` otherwise.
    pub fn is_network(&self) -> bool {
        self.storage_mode().is_network()
    }

    /// Returns `true` if the storage mode is [`AccountStorageMode::Private`], `false` otherwise.
    pub fn is_private(&self) -> bool {
        self.storage_mode().is_private()
    }

    /// Returns the version of this account ID.
    pub fn version(&self) -> AccountIdVersion {
        match self {
            AccountId::V0(_) => AccountIdVersion::Version0,
        }
    }

    /// Creates an [`AccountId`] from a hex string. Assumes the string starts with "0x" and
    /// that the hexadecimal characters are big-endian encoded.
    pub fn from_hex(hex_str: &str) -> Result<Self, AccountIdError> {
        hex_to_bytes(hex_str)
            .map_err(AccountIdError::AccountIdHexParseError)
            .and_then(AccountId::try_from)
    }

    /// Returns a big-endian, hex-encoded string of length 32, including the `0x` prefix. This means
    /// it encodes 15 bytes.
    pub fn to_hex(self) -> String {
        match self {
            AccountId::V0(account_id) => account_id.to_hex(),
        }
    }

    /// Returns the [`AccountIdPrefix`] of this ID.
    ///
    /// The prefix of an account ID is guaranteed to be unique.
    pub fn prefix(&self) -> AccountIdPrefix {
        match self {
            AccountId::V0(account_id) => AccountIdPrefix::V0(account_id.prefix()),
        }
    }

    /// Returns the suffix of this ID as a [`Felt`].
    pub const fn suffix(&self) -> Felt {
        match self {
            AccountId::V0(account_id) => account_id.suffix(),
        }
    }
}

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

impl From<AccountId> for [Felt; 2] {
    fn from(id: AccountId) -> Self {
        match id {
            AccountId::V0(account_id) => account_id.into(),
        }
    }
}

impl From<AccountId> for [u8; 15] {
    fn from(id: AccountId) -> Self {
        match id {
            AccountId::V0(account_id) => account_id.into(),
        }
    }
}

impl From<AccountId> for u128 {
    fn from(id: AccountId) -> Self {
        match id {
            AccountId::V0(account_id) => account_id.into(),
        }
    }
}

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

impl From<AccountIdV0> for AccountId {
    fn from(id: AccountIdV0) -> Self {
        Self::V0(id)
    }
}

impl TryFrom<[Felt; 2]> for AccountId {
    type Error = AccountIdError;

    /// Returns an [`AccountId`] instantiated with the provided field elements where `elements[0]`
    /// is taken as the prefix and `elements[1]` is taken as the suffix.
    ///
    /// # Errors
    ///
    /// Returns an error if any of the ID constraints are not met. See the [constraints
    /// documentation](AccountId#constraints) for details.
    fn try_from(elements: [Felt; 2]) -> Result<Self, Self::Error> {
        // The prefix contains the metadata.
        // If we add more versions in the future, we may need to generalize this.
        match v0::extract_version(elements[0].as_int())? {
            AccountIdVersion::Version0 => AccountIdV0::try_from(elements).map(Self::V0),
        }
    }
}

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

    /// Tries to convert a byte array in big-endian order to an [`AccountId`].
    ///
    /// # Errors
    ///
    /// Returns an error if any of the ID constraints are not met. See the [constraints
    /// documentation](AccountId#constraints) for details.
    fn try_from(bytes: [u8; 15]) -> Result<Self, Self::Error> {
        // The least significant byte of the ID prefix contains the metadata.
        let metadata_byte = bytes[7];
        // We only have one supported version for now, so we use the extractor from that version.
        // If we add more versions in the future, we may need to generalize this.
        let version = v0::extract_version(metadata_byte as u64)?;

        match version {
            AccountIdVersion::Version0 => AccountIdV0::try_from(bytes).map(Self::V0),
        }
    }
}

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

    /// Tries to convert a u128 into an [`AccountId`].
    ///
    /// # Errors
    ///
    /// Returns an error if any of the ID constraints are not met. See the [constraints
    /// documentation](AccountId#constraints) 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)
    }
}

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

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

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

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

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

impl Serializable for AccountId {
    fn write_into<W: miden_core::utils::ByteWriter>(&self, target: &mut W) {
        match self {
            AccountId::V0(account_id) => {
                account_id.write_into(target);
            },
        }
    }

    fn get_size_hint(&self) -> usize {
        match self {
            AccountId::V0(account_id) => account_id.get_size_hint(),
        }
    }
}

impl Deserializable for AccountId {
    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()))
    }
}

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

#[cfg(test)]
mod tests {

    use super::*;
    use crate::testing::account_id::{
        ACCOUNT_ID_NETWORK_NON_FUNGIBLE_FAUCET,
        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 test_account_id_wrapper_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,
            ACCOUNT_ID_NETWORK_NON_FUNGIBLE_FAUCET,
        ]
        .into_iter()
        .enumerate()
        {
            let wrapper = AccountId::try_from(account_id).unwrap();
            assert_eq!(
                wrapper,
                AccountId::read_from_bytes(&wrapper.to_bytes()).unwrap(),
                "failed in {idx}"
            );
        }
    }
}