miden_protocol/account/account_id/

mod.rs

pub(crate) mod v1;
pub use v1::{AccountIdPrefixV1, AccountIdV1};

mod id_prefix;
pub use id_prefix::AccountIdPrefix;

mod seed;

mod account_type;
pub use account_type::AccountType;

mod asset_callback_flag;
pub use asset_callback_flag::AssetCallbackFlag;

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

use bech32::primitives::decode::ByteIter;
pub use id_version::AccountIdVersion;
use miden_core::Felt;
use miden_crypto::utils::hex_to_bytes;

use crate::Word;
use crate::address::NetworkId;
use crate::errors::{AccountError, AccountIdError};
use crate::utils::serde::{
    ByteReader,
    ByteWriter,
    Deserializable,
    DeserializationError,
    Serializable,
};

/// The identifier of an [`Account`](crate::account::Account).
///
/// This enum is a wrapper around concrete versions of IDs. The following documents version 1.
///
/// # 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 (58 bits) | asset callback flag (1 bit) | account type (1 bit) | 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 account type, asset
/// callback flag 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 account type, asset callback flag, version and the
/// most significant bit in the suffix, generating an ID requires 7 bits of Proof-of-Work.
///
/// # Constraints
///
/// Constructors will return an error if:
///
/// - The prefix contains an account ID 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 account type 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 asset callback flag is placed in the account ID so it is immutable throughout the lifetime
///   of the account and every asset issued by an account has the same flag.
/// - 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 {
    V1(AccountIdV1),
}

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::Version1 => {
                AccountIdV1::new(seed, code_commitment, storage_commitment).map(Self::V1)
            },
        }
    }

    /// 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 v1::extract_version(elements[0].as_canonical_u64())
            .expect("prefix should contain a valid account ID version")
        {
            AccountIdVersion::Version1 => Self::V1(AccountIdV1::new_unchecked(elements)),
        }
    }

    /// Decodes an [`AccountId`] from the provided suffix and prefix felts.
    ///
    /// # Errors
    ///
    /// Returns an error if any of the ID constraints are not met. See the [constraints
    /// documentation](AccountId#constraints) for details.
    pub fn try_from_elements(suffix: Felt, prefix: Felt) -> Result<Self, AccountIdError> {
        // The prefix contains the metadata.
        // If we add more versions in the future, we may need to generalize this.
        match v1::extract_version(prefix.as_canonical_u64())? {
            AccountIdVersion::Version1 => {
                AccountIdV1::try_from_elements(suffix, prefix).map(Self::V1)
            },
        }
    }

    /// Constructs an [`AccountId`] for testing purposes with the given account type.
    ///
    /// 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 and account type.
    /// - 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,
        asset_callbacks: AssetCallbackFlag,
    ) -> AccountId {
        match version {
            AccountIdVersion::Version1 => {
                Self::V1(AccountIdV1::dummy(bytes, account_type, asset_callbacks))
            },
        }
    }

    /// Grinds an account seed until its hash matches the given `account_type`, `asset_callbacks`
    /// 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,
        asset_callbacks: AssetCallbackFlag,
        version: AccountIdVersion,
        code_commitment: Word,
        storage_commitment: Word,
    ) -> Result<Word, AccountError> {
        match version {
            AccountIdVersion::Version1 => AccountIdV1::compute_account_seed(
                init_seed,
                account_type,
                asset_callbacks,
                version,
                code_commitment,
                storage_commitment,
            ),
        }
    }

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

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

    /// Returns the [`AssetCallbackFlag`] of this account ID.
    pub fn asset_callback_flag(&self) -> AssetCallbackFlag {
        match self {
            AccountId::V1(account_id) => account_id.asset_callback_flag(),
        }
    }

    /// Returns `true` if the account type is [`AccountType::Public`], `false` otherwise.
    pub fn is_public(&self) -> bool {
        self.account_type().is_public()
    }

    /// Returns `true` if the account type is [`AccountType::Private`], `false` otherwise.
    pub fn is_private(&self) -> bool {
        self.account_type().is_private()
    }

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

    /// 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::V1(account_id) => account_id.to_hex(),
        }
    }

    /// Encodes the [`AccountId`] into a [bech32](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki)
    /// string.
    ///
    /// # Encoding
    ///
    /// The encoding of an account ID into bech32 is done as follows:
    /// - Convert the account ID into its `[u8; 15]` data format.
    /// - Insert the address type `AddressType::AccountId` byte at index 0, shifting all other
    ///   elements to the right.
    /// - Choose an HRP, defined as a [`NetworkId`], for example [`NetworkId::Mainnet`] whose string
    ///   representation is `mm`.
    /// - Encode the resulting HRP together with the data into a bech32 string using the
    ///   [`bech32::Bech32m`] checksum algorithm.
    ///
    /// This is an example of an account ID in hex and bech32 representations:
    ///
    /// ```text
    /// hex:    0x6d449e4034fadca075d1976fef7e38
    /// bech32: mm1apk5f8jqxnadegr46xtklmm78qhdgkwc
    /// ```
    ///
    /// ## Rationale
    ///
    /// Having the address type at the very beginning is so that it can be decoded to detect the
    /// type of the address without having to decode the entire data. Moreover, choosing the
    /// address type as a multiple of 8 means the first character of the bech32 string after the
    /// `1` separator will be different for every address type. This makes the type of the address
    /// conveniently human-readable.
    pub fn to_bech32(&self, network_id: NetworkId) -> String {
        match self {
            AccountId::V1(account_id_v1) => account_id_v1.to_bech32(network_id),
        }
    }

    /// Decodes a [bech32](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki) string into an [`AccountId`].
    ///
    /// See [`AccountId::to_bech32`] for details on the format. The procedure for decoding the
    /// bech32 data into the ID consists of the inverse operations of encoding.
    pub fn from_bech32(bech32_string: &str) -> Result<(NetworkId, Self), AccountIdError> {
        AccountIdV1::from_bech32(bech32_string)
            .map(|(network_id, account_id)| (network_id, AccountId::V1(account_id)))
    }

    /// Parses a string into an [`AccountId`].
    ///
    /// This function supports parsing from both hex (`0x...`) and bech32 formats.
    ///
    /// # Returns
    ///
    /// Returns a tuple of the parsed [`AccountId`] and an optional [`NetworkId`].
    /// - For hex strings: `NetworkId` is `None`.
    /// - For bech32 strings: `NetworkId` is `Some(...)`.
    ///
    /// # Errors
    ///
    /// Returns an error if the string cannot be parsed as either hex or bech32 format.
    pub fn parse(s: &str) -> Result<(Self, Option<NetworkId>), AccountIdError> {
        if let Some(hex_digits) = s.strip_prefix("0x").or_else(|| s.strip_prefix("0X")) {
            // Normalize to lowercase "0x" prefix for from_hex
            let normalized = format!("0x{hex_digits}");
            Self::from_hex(&normalized).map(|id| (id, None))
        } else {
            Self::from_bech32(s).map(|(network_id, id)| (id, Some(network_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> {
        AccountIdV1::from_bech32_byte_iter(byte_iter).map(AccountId::V1)
    }

    /// 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::V1(account_id) => AccountIdPrefix::V1(account_id.prefix()),
        }
    }

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

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

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

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

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

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

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

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 = v1::extract_version(metadata_byte as u64)?;

        match version {
            AccountIdVersion::Version1 => AccountIdV1::try_from(bytes).map(Self::V1),
        }
    }
}

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: ByteWriter>(&self, target: &mut W) {
        match self {
            AccountId::V1(account_id) => {
                account_id.write_into(target);
            },
        }
    }

    fn get_size_hint(&self) -> usize {
        match self {
            AccountId::V1(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 alloc::boxed::Box;

    use assert_matches::assert_matches;
    use bech32::{Bech32, Bech32m, NoChecksum};

    use super::*;
    use crate::account::account_id::v1::{extract_account_type, extract_version};
    use crate::address::{AddressType, CustomNetworkId};
    use crate::errors::Bech32Error;
    use crate::testing::account_id::{
        ACCOUNT_ID_MAX_ZEROES,
        ACCOUNT_ID_PRIVATE_NON_FUNGIBLE_FAUCET,
        ACCOUNT_ID_PRIVATE_SENDER,
        ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET,
        ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET_WITH_CALLBACKS,
        ACCOUNT_ID_PUBLIC_NON_FUNGIBLE_FAUCET,
        ACCOUNT_ID_REGULAR_PRIVATE_ACCOUNT_UPDATABLE_CODE,
        ACCOUNT_ID_REGULAR_PUBLIC_ACCOUNT_IMMUTABLE_CODE,
        AccountIdBuilder,
    };

    #[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_PUBLIC_NON_FUNGIBLE_FAUCET,
            ACCOUNT_ID_MAX_ZEROES,
        ]
        .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}"
            );
        }
    }

    #[test]
    fn bech32_encode_decode_roundtrip() -> anyhow::Result<()> {
        // We use this to check that encoding does not panic even when using the longest possible
        // HRP.
        let longest_possible_hrp =
            "01234567890123456789012345678901234567890123456789012345678901234567890123456789012";
        assert_eq!(longest_possible_hrp.len(), 83);

        let random_id = AccountIdBuilder::new().build_with_rng(&mut rand::rng());

        for network_id in [
            NetworkId::Mainnet,
            NetworkId::Custom(Box::new("custom".parse::<CustomNetworkId>()?)),
            NetworkId::Custom(Box::new(longest_possible_hrp.parse::<CustomNetworkId>()?)),
        ] {
            for account_id in [
                ACCOUNT_ID_REGULAR_PUBLIC_ACCOUNT_IMMUTABLE_CODE,
                ACCOUNT_ID_REGULAR_PRIVATE_ACCOUNT_UPDATABLE_CODE,
                ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET,
                ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET_WITH_CALLBACKS,
                ACCOUNT_ID_PRIVATE_NON_FUNGIBLE_FAUCET,
                ACCOUNT_ID_PRIVATE_SENDER,
                random_id.into(),
            ]
            .into_iter()
            {
                let account_id = AccountId::try_from(account_id).unwrap();

                let bech32_string = account_id.to_bech32(network_id.clone());
                let (decoded_network_id, decoded_account_id) =
                    AccountId::from_bech32(&bech32_string).unwrap();

                assert_eq!(network_id, decoded_network_id, "network id failed for {account_id}",);
                assert_eq!(account_id, decoded_account_id, "account id failed for {account_id}");
                assert_eq!(
                    account_id.asset_callback_flag(),
                    decoded_account_id.asset_callback_flag(),
                    "asset callback flag failed for {account_id}"
                );

                let (_, data) = bech32::decode(&bech32_string).unwrap();

                // Raw bech32 data should contain the address type as the first byte.
                assert_eq!(data[0], AddressType::AccountId as u8);

                // Raw bech32 data should contain the metadata byte at index 8.
                assert_eq!(extract_version(data[8] as u64).unwrap(), account_id.version());
                assert_eq!(extract_account_type(data[8] as u64), account_id.account_type());
            }
        }

        Ok(())
    }

    #[test]
    fn bech32_invalid_checksum() {
        let network_id = NetworkId::Mainnet;
        let account_id = AccountId::try_from(ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET).unwrap();

        let bech32_string = account_id.to_bech32(network_id);
        let mut invalid_bech32_1 = bech32_string.clone();
        invalid_bech32_1.remove(0);
        let mut invalid_bech32_2 = bech32_string.clone();
        invalid_bech32_2.remove(7);

        let error = AccountId::from_bech32(&invalid_bech32_1).unwrap_err();
        assert_matches!(error, AccountIdError::Bech32DecodeError(Bech32Error::DecodeError(_)));

        let error = AccountId::from_bech32(&invalid_bech32_2).unwrap_err();
        assert_matches!(error, AccountIdError::Bech32DecodeError(Bech32Error::DecodeError(_)));
    }

    #[test]
    fn bech32_invalid_address_type() {
        let account_id = AccountId::try_from(ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET).unwrap();
        let mut id_bytes = account_id.to_bytes();

        // Set invalid address type.
        id_bytes.insert(0, 16);

        let invalid_bech32 =
            bech32::encode::<Bech32m>(NetworkId::Mainnet.into_hrp(), &id_bytes).unwrap();

        let error = AccountId::from_bech32(&invalid_bech32).unwrap_err();
        assert_matches!(
            error,
            AccountIdError::Bech32DecodeError(Bech32Error::UnknownAddressType(16))
        );
    }

    #[test]
    fn bech32_invalid_other_checksum() {
        let account_id = AccountId::try_from(ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET).unwrap();
        let mut id_bytes = account_id.to_bytes();
        id_bytes.insert(0, AddressType::AccountId as u8);

        // Use Bech32 instead of Bech32m which is disallowed.
        let invalid_bech32_regular =
            bech32::encode::<Bech32>(NetworkId::Mainnet.into_hrp(), &id_bytes).unwrap();
        let error = AccountId::from_bech32(&invalid_bech32_regular).unwrap_err();
        assert_matches!(error, AccountIdError::Bech32DecodeError(Bech32Error::DecodeError(_)));

        // Use no checksum instead of Bech32m which is disallowed.
        let invalid_bech32_no_checksum =
            bech32::encode::<NoChecksum>(NetworkId::Mainnet.into_hrp(), &id_bytes).unwrap();
        let error = AccountId::from_bech32(&invalid_bech32_no_checksum).unwrap_err();
        assert_matches!(error, AccountIdError::Bech32DecodeError(Bech32Error::DecodeError(_)));
    }

    #[test]
    fn bech32_invalid_length() {
        let account_id = AccountId::try_from(ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET).unwrap();
        let mut id_bytes = account_id.to_bytes();
        id_bytes.insert(0, AddressType::AccountId as u8);
        // Add one byte to make the length invalid.
        id_bytes.push(5);

        let invalid_bech32 =
            bech32::encode::<Bech32m>(NetworkId::Mainnet.into_hrp(), &id_bytes).unwrap();

        let error = AccountId::from_bech32(&invalid_bech32).unwrap_err();
        assert_matches!(
            error,
            AccountIdError::Bech32DecodeError(Bech32Error::InvalidDataLength { .. })
        );
    }

    #[test]
    fn parse_hex_string() {
        let account_id = AccountId::try_from(ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET).unwrap();
        let hex_string = account_id.to_hex();

        let (parsed_id, network_id) = AccountId::parse(&hex_string).unwrap();

        assert_eq!(parsed_id, account_id);
        assert!(network_id.is_none());
    }

    #[test]
    fn parse_hex_string_uppercase() {
        let account_id = AccountId::try_from(ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET).unwrap();
        // Keep "0x" prefix lowercase, only uppercase the hex digits
        let hex_string = account_id.to_hex();
        let hex_string = format!("0x{}", hex_string[2..].to_uppercase());

        let (parsed_id, network_id) = AccountId::parse(&hex_string).unwrap();

        assert_eq!(parsed_id, account_id);
        assert!(network_id.is_none());
    }

    #[test]
    fn parse_hex_string_uppercase_prefix() {
        let account_id = AccountId::try_from(ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET).unwrap();
        // Use "0X" prefix (uppercase X) with uppercase hex digits
        let hex_string = account_id.to_hex();
        let hex_string = format!("0X{}", hex_string[2..].to_uppercase());

        let (parsed_id, network_id) = AccountId::parse(&hex_string).unwrap();

        assert_eq!(parsed_id, account_id);
        assert!(network_id.is_none());
    }

    #[test]
    fn parse_bech32_string() {
        let account_id = AccountId::try_from(ACCOUNT_ID_PUBLIC_FUNGIBLE_FAUCET).unwrap();
        let bech32_string = account_id.to_bech32(NetworkId::Mainnet);

        let (parsed_id, parsed_network_id) = AccountId::parse(&bech32_string).unwrap();

        assert_eq!(parsed_id, account_id);
        assert_eq!(parsed_network_id, Some(NetworkId::Mainnet));
    }

    #[test]
    fn parse_invalid_string() {
        let error = AccountId::parse("invalid_string").unwrap_err();
        assert_matches!(error, AccountIdError::Bech32DecodeError(_));

        let error = AccountId::parse("0xinvalid").unwrap_err();
        assert_matches!(error, AccountIdError::AccountIdHexParseError(_));
    }
}