Enum AccountId

pub enum AccountId {
    V0(AccountIdV0),
}

The identifier of an 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 layed out as follows:

prefix: [hash (56 bits) | storage mode (2 bits) | type (2 bits) | version (4 bits)]
suffix: [anchor_epoch (16 bits) | hash (40 bits) | 8 zero bits]

Generation

An AccountId is a commitment to a user-generated seed, the code and storage of an account and to a certain hash of an epoch block of the blockchain. An id is generated by picking an epoch block as an anchor - which is why it is also referred to as the anchor block - and creating the account’s initial storage and code. Then a random seed is picked and the hash of (SEED, CODE_COMMITMENT, STORAGE_COMMITMENT, ANCHOR_BLOCK_COMMITMENT) is computed. If the hash’s first element has the desired storage mode, account type and version, the computation part of the ID generation is done. If not, another random seed is picked and the process is repeated. The first felt of the ID is then the first element of the hash.

The suffix of the ID is the second element of the hash. Its upper 16 bits are overwritten with the epoch in which the ID is anchored and the lower 8 bits are zeroed. Thus, the prefix of the ID must derive exactly from the hash, while only part of the suffix is derived from the hash.

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 anchor epoch in the suffix is equal to u16::MAX.
• 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 be able to introduce 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 anchor epoch is not important beyond the creation process, so placing it in the second felt is fine. Moreover, all properties of the prefix must be derived from the seed, so they add to the proof of work difficulty. Adding 16 bits of PoW for the epoch would be significant.
• The anchor epoch is placed at the most significant end of the suffix. Its value must be less than u16::MAX so that at least one of the upper 16 bits is always zero. This ensures that the entire suffix is valid even if the remaining bits of the felt are one.
• The lower 8 bits of the suffix may be overwritten when the ID is encoded in other layouts such as the NoteMetadata. In such cases, it can happen that all bits of the encoded suffix would be one, so having the epoch constraint is important.
• The ID is dependent on the hash of an epoch block. This is a block whose number is a multiple of 2^BlockNumber::EPOCH_LENGTH_EXPONENT, e.g. 0, 65536, 131072, … These are the first blocks of epoch 0, 1, 2, … We call this dependence anchoring because the ID is anchored to that epoch block’s commitment. Anchoring makes it practically impossible for an attacker to construct a rainbow table of account IDs whose epoch is X, if the block for epoch X has not been constructed yet because its hash is then unknown. Therefore, picking a recent anchor block when generating a new ID makes it extremely unlikely that an attacker can highjack this ID because the hash of that block has only been known for a short period of time.
  • An ID highjack refers to an attack where a user generates an ID and lets someone else send assets to it. At this point the user has not registered the ID on-chain yet, likely because they need the funds in the asset to pay for their first transaction where the account would be registered. Until the ID is registered on chain, an attacker with a rainbow table who happens to have a seed, code and storage commitment combination that hashes to the user’s ID can claim the assets sent to the user’s ID. Adding the anchor block commitment to the ID generation process makes this attack practically impossible.

Variants

V0(AccountIdV0)

Implementations

impl AccountId

pub const SERIALIZED_SIZE: usize = 15usize

The serialized size of an AccountId in bytes.

pub fn new( seed: Word, anchor: AccountIdAnchor, version: AccountIdVersion, code_commitment: Digest, storage_commitment: Digest, ) -> Result<Self, AccountIdError>

Creates an AccountId by hashing the given seed, code_commitment, storage_commitment and AccountIdAnchor::block_commitment from the anchor and using the resulting first and second element of the hash as the prefix and suffix felts of the ID.

The AccountIdAnchor::epoch from the anchor overwrites part of the suffix.

Note that the anchor must correspond to a valid block in the chain for the ID to be deemed valid during creation.

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 for details.

pub fn new_unchecked(elements: [Felt; 2]) -> Self

Creates an AccountId from the given felts where the felt at index 0 is the prefix and the felt at index 2 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 for details.

pub fn compute_account_seed( init_seed: [u8; 32], account_type: AccountType, storage_mode: AccountStorageMode, version: AccountIdVersion, code_commitment: Digest, storage_commitment: Digest, anchor_block_commitment: Digest, ) -> Result<Word, AccountError>

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, storage_commitment and anchor_block_commitment.

The grinding process is started from the given init_seed which should be a random seed generated from a cryptographically secure source.

pub const fn account_type(&self) -> AccountType

Returns the type of this account ID.

pub fn is_faucet(&self) -> bool

Returns true if an account with this ID is a faucet which can issue assets.

pub fn is_regular_account(&self) -> bool

Returns true if an account with this ID is a regular account.

pub fn storage_mode(&self) -> AccountStorageMode

Returns the storage mode of this account ID.

pub fn is_onchain(&self) -> bool

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_public(&self) -> bool

Returns true if the storage mode is AccountStorageMode::Public, false otherwise.

pub fn is_network(&self) -> bool

Returns true if the storage mode is AccountStorageMode::Network, false otherwise.

pub fn is_private(&self) -> bool

Returns true if the storage mode is AccountStorageMode::Private, false otherwise.

pub fn version(&self) -> AccountIdVersion

Returns the version of this account ID.

pub fn anchor_epoch(&self) -> u16

Returns the anchor epoch of this account ID.

This is the epoch to which this ID is anchored. The hash of this epoch block is used in the generation of the ID.

pub fn from_hex(hex_str: &str) -> Result<Self, AccountIdError>

Creates an AccountId from a hex string. Assumes the string starts with “0x” and that the hexadecimal characters are big-endian encoded.

pub fn to_hex(self) -> String

Returns a big-endian, hex-encoded string of length 32, including the 0x prefix. This means it encodes 15 bytes.

pub fn to_bech32(&self, network_id: NetworkId) -> String

Encodes the AccountId into a bech32 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:

hex:    0x140fa04a1e61fc100000126ef8f1d6
bech32: mm1qq2qlgz2reslcyqqqqfxa7836chrjcvk

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.

The only allowed checksum algorithm is Bech32m due to being the best available checksum algorithm with no known weaknesses (unlike Bech32). No checksum is also not allowed since the intended use of bech32 is to have error detection capabilities.

pub fn from_bech32( bech32_string: &str, ) -> Result<(NetworkId, Self), AccountIdError>

Decodes a bech32 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 prefix(&self) -> AccountIdPrefix

Returns the AccountIdPrefix of this ID.

The prefix of an account ID is guaranteed to be unique.

pub const fn suffix(&self) -> Felt

Returns the suffix of this ID as a Felt.

Trait Implementations

impl Clone for AccountId

fn clone(&self) -> AccountId

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AccountId

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deserializable for AccountId

fn read_from<R: ByteReader>( source: &mut R, ) -> Result<Self, DeserializationError>

Reads a sequence of bytes from the provided source, attempts to deserialize these bytes into Self, and returns the result.

fn read_from_bytes(bytes: &[u8]) -> Result<Self, DeserializationError>

Attempts to deserialize the provided bytes into Self and returns the result.

impl Display for AccountId

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<AccountId> for [Felt; 2]

fn from(id: AccountId) -> Self

Converts to this type from the input type.

impl From<AccountId> for [u8; 15]

fn from(id: AccountId) -> Self

Converts to this type from the input type.

impl From<AccountId> for u128

fn from(id: AccountId) -> Self

Converts to this type from the input type.

impl From<AccountIdV0> for AccountId

fn from(id: AccountIdV0) -> Self

Converts to this type from the input type.

impl Ord for AccountId

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for AccountId

fn eq(&self, other: &AccountId) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for AccountId

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serializable for AccountId

fn write_into<W: ByteWriter>(&self, target: &mut W)

Serializes self into bytes and writes these bytes into the target.

fn get_size_hint(&self) -> usize

Returns an estimate of how many bytes are needed to represent self.

fn to_bytes(&self) -> Vec<u8>

Serializes self into a vector of bytes.

impl TryFrom<[BaseElement; 2]> for AccountId

fn try_from(elements: [Felt; 2]) -> Result<Self, Self::Error>

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 for details.

type Error = AccountIdError

The type returned in the event of a conversion error.

impl TryFrom<[u8; 15]> for AccountId

fn try_from(bytes: [u8; 15]) -> Result<Self, Self::Error>

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 for details.

type Error = AccountIdError

The type returned in the event of a conversion error.

impl TryFrom<u128> for AccountId

fn try_from(int: u128) -> Result<Self, Self::Error>

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 for details.

type Error = AccountIdError

The type returned in the event of a conversion error.

impl Copy for AccountId

impl Eq for AccountId

impl StructuralPartialEq for AccountId