From 7335fe7c20c2606222d0235f00ee3775507ce4d6 Mon Sep 17 00:00:00 2001 From: Philipp Gackstatter Date: Fri, 10 Jan 2025 08:15:04 +0100 Subject: [PATCH] Rename `AccountId` first and second felt to prefix and suffix (#1054) * feat: Replace "account id" with "account ID" everywhere * feat: Rename first/second felt to prefix/suffix * chore: Fix generated tx kernel errors file --- miden-lib/asm/kernels/transaction/api.masm | 46 ++-- .../asm/kernels/transaction/lib/account.masm | 209 ++++++++------- .../asm/kernels/transaction/lib/asset.masm | 18 +- .../kernels/transaction/lib/asset_vault.masm | 48 ++-- .../asm/kernels/transaction/lib/memory.masm | 60 ++--- .../asm/kernels/transaction/lib/note.masm | 6 +- .../asm/kernels/transaction/lib/prologue.masm | 24 +- miden-lib/asm/kernels/transaction/lib/tx.masm | 22 +- miden-lib/asm/miden/account.masm | 42 +-- miden-lib/asm/miden/asset.masm | 20 +- miden-lib/asm/miden/contracts/auth/basic.masm | 4 +- miden-lib/asm/miden/note.masm | 6 +- miden-lib/asm/miden/tx.masm | 8 +- miden-lib/asm/note_scripts/P2ID.masm | 6 +- miden-lib/asm/note_scripts/P2IDR.masm | 12 +- miden-lib/src/errors/tx_kernel_errors.rs | 4 +- miden-lib/src/notes/mod.rs | 2 +- miden-lib/src/notes/utils.rs | 2 +- miden-lib/src/transaction/inputs.rs | 8 +- miden-lib/src/transaction/memory.rs | 14 +- miden-lib/src/transaction/mod.rs | 10 +- miden-lib/src/transaction/outputs.rs | 10 +- miden-tx/src/errors/mod.rs | 2 +- .../src/tests/kernel_tests/test_account.rs | 8 +- miden-tx/src/tests/kernel_tests/test_asset.rs | 4 +- .../tests/kernel_tests/test_asset_vault.rs | 62 +++-- .../src/tests/kernel_tests/test_faucet.rs | 56 ++-- miden-tx/src/tests/kernel_tests/test_note.rs | 4 +- .../src/tests/kernel_tests/test_prologue.rs | 16 +- miden-tx/src/tests/kernel_tests/test_tx.rs | 68 ++--- objects/src/accounts/account_id.rs | 251 +++++++++--------- objects/src/accounts/account_id_prefix.rs | 64 +++-- objects/src/accounts/header.rs | 6 +- objects/src/accounts/mod.rs | 4 +- objects/src/accounts/seed.rs | 10 +- objects/src/assets/fungible.rs | 10 +- objects/src/assets/mod.rs | 20 +- objects/src/assets/nonfungible.rs | 6 +- objects/src/errors.rs | 14 +- objects/src/notes/metadata.rs | 63 ++--- objects/src/notes/note_tag.rs | 16 +- objects/src/testing/account_id.rs | 14 +- objects/src/testing/storage.rs | 2 +- objects/src/transaction/proven_tx.rs | 2 +- 44 files changed, 651 insertions(+), 632 deletions(-) diff --git a/miden-lib/asm/kernels/transaction/api.masm b/miden-lib/asm/kernels/transaction/api.masm index 48ada8128..497165409 100644 --- a/miden-lib/asm/kernels/transaction/api.masm +++ b/miden-lib/asm/kernels/transaction/api.masm @@ -71,23 +71,23 @@ end # KERNEL PROCEDURES # ================================================================================================= -#! Returns the account id. +#! Returns the account ID. #! #! Inputs: [pad(16)] -#! Outputs: [acct_id_hi, acct_id_lo, pad(14)] +#! Outputs: [acct_id_prefix, acct_id_suffix, pad(14)] #! #! Where: -#! - acct_id is the account id. +#! - acct_id is the account ID. #! #! Invocation: dynexec export.get_account_id - # get the account id + # get the account ID exec.account::get_id - # => [acct_id_hi, acct_id_lo, pad(16)] + # => [acct_id_prefix, acct_id_suffix, pad(16)] # truncate the stack movup.2 drop movup.2 drop - # => [acct_id_hi, acct_id_lo, pad(14)] + # => [acct_id_prefix, acct_id_suffix, pad(14)] end #! Returns the account nonce. @@ -371,11 +371,11 @@ end #! Returns the balance of a fungible asset associated with a faucet_id. #! -#! Inputs: [faucet_id_hi, faucet_id_lo, pad(14)] +#! Inputs: [faucet_id_prefix, faucet_id_suffix, pad(14)] #! Outputs: [balance, pad(15)] #! #! Where: -#! - faucet_id_{hi,lo} are the first and second felt of the faucet id of the fungible asset +#! - faucet_id_{prefix,suffix} are the prefix and suffix felts of the faucet id of the fungible asset #! of interest. #! - balance is the vault balance of the fungible asset. #! @@ -386,7 +386,7 @@ end export.account_vault_get_balance # get the vault root exec.memory::get_acct_vault_root_ptr movdn.2 - # => [faucet_id_hi, faucet_id_lo, acct_vault_root_ptr, pad(14)] + # => [faucet_id_prefix, faucet_id_suffix, acct_vault_root_ptr, pad(14)] # get the asset balance exec.asset_vault::get_balance @@ -555,10 +555,10 @@ end #! Returns the sender of the note currently being processed. #! #! Inputs: [pad(16)] -#! Outputs: [sender_hi, sender_lo, pad(14)] +#! Outputs: [sender_id_prefix, sender_id_suffix, pad(14)] #! #! Where: -#! - sender_{hi,lo} are the first and second felt of the sender account id of the note currently +#! - sender_{prefix,suffix} are the prefix and suffix felts of the sender account ID of the note currently #! being processed. #! #! Panics if: @@ -567,11 +567,11 @@ end #! Invocation: dynexec export.get_note_sender exec.note::get_sender - # => [sender_hi, sender_lo, pad(16)] + # => [sender_id_prefix, sender_id_suffix, pad(16)] # truncate the stack movup.2 drop movup.2 drop - # => [sender_hi, sender_lo, pad(14)] + # => [sender_id_prefix, sender_id_suffix, pad(14)] end #! Returns the block number of the last known block at the time of transaction execution. @@ -881,9 +881,9 @@ end #! Moves the account pointer to the currently accessing foreign account. #! #! Inputs: -#! Operand stack: [foreign_account_id_hi, foreign_account_id_lo, pad(14)] +#! Operand stack: [foreign_account_id_prefix, foreign_account_id_suffix, pad(14)] #! Advice map: { -#! FOREIGN_ACCOUNT_ID: [[foreign_account_lo, foreign_account_id_hi, 0, account_nonce], +#! FOREIGN_ACCOUNT_ID: [[foreign_account_id_suffix, foreign_account_id_prefix, 0, account_nonce], #! VAULT_ROOT, STORAGE_ROOT, CODE_ROOT], #! STORAGE_ROOT: [[STORAGE_SLOT_DATA]], #! CODE_ROOT: [num_procs, [ACCOUNT_PROCEDURE_DATA]] @@ -892,10 +892,10 @@ end #! Operand stack: [pad(16)] #! #! Where: -#! - foreign_account_id_{hi,lo} are the first and second felt of the ID of the foreign account +#! - foreign_account_id_{prefix,suffix} are the prefix and suffix felts of the ID of the foreign account #! whose procedure is going to be executed. #! - FOREIGN_ACCOUNT_ID is the word constructed from the foreign_account_id as follows: -#! [foreign_account_lo, foreign_account_id_hi, 0, 0]. +#! [foreign_account_id_suffix, foreign_account_id_prefix, 0, 0]. #! - account_nonce is the nonce of the foreign account. #! - VAULT_ROOT is the commitment of the foreign account's vault. #! - STORAGE_ROOT is the commitment of the foreign account's storage. @@ -912,27 +912,27 @@ end export.start_foreign_context # check that this procedure was executed against the native account exec.memory::assert_native_account - # OS => [foreign_account_id_hi, foreign_account_id_lo, pad(14)] + # OS => [foreign_account_id_prefix, foreign_account_id_suffix, pad(14)] # get the memory address and a flag whether this account was already loaded. exec.account::get_foreign_account_ptr - # OS => [was_loaded, ptr, foreign_account_id_hi, foreign_account_id_lo, pad(14)] + # OS => [was_loaded, ptr, foreign_account_id_prefix, foreign_account_id_suffix, pad(14)] if.true exec.memory::set_current_account_data_ptr drop drop # OS => [pad(16)] else exec.memory::set_current_account_data_ptr - # OS => [foreign_account_id_hi, foreign_account_id_lo, pad(14)] + # OS => [foreign_account_id_prefix, foreign_account_id_suffix, pad(14)] # construct the word with account ID to load the core account data from the advice map push.0.0 - # OS => [0, 0, foreign_account_id_hi, foreign_account_id_lo, pad(14)] + # OS => [0, 0, foreign_account_id_prefix, foreign_account_id_suffix, pad(14)] # move the core account data to the advice stack adv.push_mapval - # OS => [0, 0, foreign_account_id_hi, foreign_account_id_lo, pad(14)] - # AS => [[foreign_account_id_hi, foreign_account_lo, 0, account_nonce], VAULT_ROOT, STORAGE_ROOT, CODE_ROOT] + # OS => [0, 0, foreign_account_id_prefix, foreign_account_id_suffix, pad(14)] + # AS => [[foreign_account_id_prefix, foreign_account_id_suffix, 0, account_nonce], VAULT_ROOT, STORAGE_ROOT, CODE_ROOT] # store the id and nonce of the foreign account to the memory dropw adv_loadw diff --git a/miden-lib/asm/kernels/transaction/lib/account.masm b/miden-lib/asm/kernels/transaction/lib/account.masm index ea4c01573..8ddfd6973 100644 --- a/miden-lib/asm/kernels/transaction/lib/account.masm +++ b/miden-lib/asm/kernels/transaction/lib/account.masm @@ -12,7 +12,7 @@ use.kernel::memory # Account nonce cannot be increased by a greater than u32 value const.ERR_ACCOUNT_NONCE_INCREASE_MUST_BE_U32=0x00020004 -# Least significant byte of second felt of the account id must be zero. +# Least significant byte of the account ID suffix must be zero. const.ERR_ACCOUNT_ID_LEAST_SIGNIFICANT_BYTE_MUST_BE_ZERO=0x00020005 # Account code must be updatable for it to be possible to set new code @@ -69,7 +69,7 @@ const.ERR_FOREIGN_ACCOUNT_ID_EQUALS_NATIVE_ACCT_ID=0x00020016 # State of the current foreign account is invalid. const.ERR_FOREIGN_ACCOUNT_INVALID=0x00020017 -# Unknown version in account id. +# Unknown version in account ID. const.ERR_ACCOUNT_ID_UNKNOWN_VERSION=0x00020057 # Epoch must be less than u16::MAX (0xffff). @@ -78,11 +78,11 @@ const.ERR_ACCOUNT_ID_EPOCH_MUST_BE_LESS_THAN_U16_MAX=0x00020058 # CONSTANTS # ================================================================================================= -# Given the least significant 32 bits of an account id's first felt, this mask defines the bits used +# Given the least significant 32 bits of an account ID's prefix, this mask defines the bits used # to determine the account version. const.ACCOUNT_VERSION_MASK_U32=0x0f # 0b1111 -# Given the least significant 32 bits of an account id's first felt, this mask defines the bits used +# Given the least significant 32 bits of an account ID's prefix, this mask defines the bits used # to determine the account type. const.ACCOUNT_ID_TYPE_MASK_U32=0x30 # 0b11_0000 @@ -232,13 +232,13 @@ export.incr_nonce emit.ACCOUNT_AFTER_INCREMENT_NONCE_EVENT end -#! Returns the account id. +#! Returns the account ID. #! #! Inputs: [] #! Outputs: [acct_id] #! #! Where: -#! - acct_id is the account id. +#! - acct_id is the account ID. export.memory::get_account_id->get_id #! Returns the account nonce. @@ -261,11 +261,11 @@ export.memory::get_init_acct_hash->get_initial_hash #! Returns a boolean indicating whether the account is a fungible faucet. #! -#! Inputs: [acct_id_hi] +#! Inputs: [acct_id_prefix] #! Outputs: [is_fungible_faucet] #! #! Where: -#! - acct_id_hi is the first felt of the account id. +#! - acct_id_prefix is the prefix of the account ID. #! - is_fungible_faucet is a boolean indicating whether the account is a fungible faucet. export.is_fungible_faucet exec.type push.FUNGIBLE_FAUCET_ACCOUNT eq @@ -274,11 +274,11 @@ end #! Returns a boolean indicating whether the account is a non-fungible faucet. #! -#! Inputs: [acct_id_hi] +#! Inputs: [acct_id_prefix] #! Outputs: [is_non_fungible_faucet] #! #! Where: -#! - acct_id_hi is the first felt of the account id. +#! - acct_id_prefix is the prefix of the account ID. #! - is_non_fungible_faucet is a boolean indicating whether the account is a non-fungible faucet. export.is_non_fungible_faucet exec.type push.NON_FUNGIBLE_FAUCET_ACCOUNT eq @@ -287,11 +287,11 @@ end #! Returns a boolean indicating whether the account is a faucet. #! -#! Inputs: [acct_id_hi] +#! Inputs: [acct_id_prefix] #! Outputs: [is_faucet] #! #! Where: -#! - acct_id_hi is the first felt of the account id. +#! - acct_id_prefix is the prefix of the account ID. #! - is_faucet is a boolean indicating whether the account is a faucet. export.is_faucet u32split drop push.FAUCET_ACCOUNT u32and eq.0 not @@ -300,11 +300,11 @@ end #! Returns a boolean indicating whether the account is a regular updatable account. #! -#! Inputs: [acct_id_hi] +#! Inputs: [acct_id_prefix] #! Outputs: [is_updatable_account] #! #! Where: -#! - acct_id_hi is the first felt of the account id. +#! - acct_id_prefix is the prefix of the account ID. #! - is_updatable_account is a boolean indicating whether the account is a regular updatable #! account. export.is_updatable_account @@ -314,11 +314,11 @@ end #! Returns a boolean indicating whether the account is a regular immutable account. #! -#! Inputs: [acct_id_hi] +#! Inputs: [acct_id_prefix] #! Outputs: [is_immutable_account] #! #! Where: -#! - acct_id_hi is the first felt of the account id. +#! - acct_id_prefix is the prefix of the account ID. #! - is_immutable_account is a boolean indicating whether the account is a regular immutable #! account. export.is_immutable_account @@ -328,52 +328,52 @@ end #! Returns a boolean indicating whether the given account_ids are equal. #! -#! Inputs: [acct_id_hi, acct_id_lo, other_acct_id_hi, other_acct_id_lo] +#! Inputs: [acct_id_prefix, acct_id_suffix, other_acct_id_prefix, other_acct_id_suffix] #! Outputs: [is_id_equal] #! #! Where: -#! - acct_id_{hi,lo} are the first and second felt of an account id. -#! - other_acct_id_{hi,lo} are the first and second felt of the other account id to compare against. -#! - is_id_equal is a boolean indicating whether the account ids are equal. +#! - acct_id_{prefix,suffix} are the prefix and suffix felts of an account ID. +#! - other_acct_id_{prefix,suffix} are the prefix and suffix felts of the other account ID to compare against. +#! - is_id_equal is a boolean indicating whether the account IDs are equal. export.is_id_eq movup.2 eq - # => [is_hi_equal, acct_id_lo, other_acct_id_lo] + # => [is_prefix_equal, acct_id_suffix, other_acct_id_suffix] movdn.2 eq - # => [is_lo_equal, is_hi_equal] + # => [is_suffix_equal, is_prefix_equal] and # => [is_id_equal] end -#! Validates an account id. +#! Validates an account ID. #! -#! Inputs: [account_id_hi, account_id_lo] +#! Inputs: [account_id_prefix, account_id_suffix] #! Outputs: [] #! #! Where: -#! - account_id_{hi,lo} are the first and second felt of the account id. +#! - account_id_{prefix,suffix} are the prefix and suffix felts of the account ID. #! #! Panics if: -#! - account_id_hi does not contain version zero. -#! - account_id_lo contains an anchor epoch that is greater or equal to 2^16. -#! - account_id_lo does not have its lower 8 bits set to zero. +#! - account_id_prefix does not contain version zero. +#! - account_id_suffix contains an anchor epoch that is greater or equal to 2^16. +#! - account_id_suffix does not have its lower 8 bits set to zero. export.validate_id - # Validate version in first felt. For now only version 0 is supported. + # Validate version in prefix. For now only version 0 is supported. # --------------------------------------------------------------------------------------------- exec.id_version - # => [id_version, account_id_lo] + # => [id_version, account_id_suffix] assertz.err=ERR_ACCOUNT_ID_UNKNOWN_VERSION - # => [account_id_lo] + # => [account_id_suffix] - # Validate anchor epoch is less than u16::MAX (0xffff) in second felt. + # Validate anchor epoch is less than u16::MAX (0xffff) in suffix. # --------------------------------------------------------------------------------------------- dup exec.id_anchor_epoch - # => [anchor_epoch, account_id_lo] + # => [anchor_epoch, account_id_suffix] lt.0xffff assert.err=ERR_ACCOUNT_ID_EPOCH_MUST_BE_LESS_THAN_U16_MAX - # => [account_id_lo] + # => [account_id_suffix] - # Validate lower 8 bits of second felt are zero. + # Validate lower 8 bits of suffix are zero. # --------------------------------------------------------------------------------------------- u32split drop u32and.0xff eq.0 @@ -393,9 +393,9 @@ end #! Panics if: #! - this procedure is executed on an account whose type differs from `regular mutable`. export.set_code - # get the account id + # get the account ID exec.memory::get_account_id swap drop - # => [acct_id_hi, CODE_COMMITMENT] + # => [acct_id_prefix, CODE_COMMITMENT] # assert the account is an updatable regular account exec.is_updatable_account assert.err=ERR_ACCOUNT_CODE_IS_NOT_UPDATABLE @@ -739,7 +739,7 @@ end #! 1. Retrieve the anchor block hash by computing the block number of the anchor block and #! retrieving it from the chain mmr. #! 2. Compute the hash of (SEED, CODE_COMMITMENT, STORAGE_COMMITMENT, ANCHOR_BLOCK_HASH). -#! 3. Assert the two least significant elements of the digest are equal to the account id of the +#! 3. Assert the two least significant elements of the digest are equal to the account ID of the #! account the transaction is being executed against. #! #! Inputs: [] @@ -751,30 +751,30 @@ export.validate_seed # prepare the advice map key for the seed for later exec.memory::get_account_id push.0.0 - # => [0, 0, account_id_hi, account_id_lo] + # => [0, 0, account_id_prefix, account_id_suffix] # get the anchor block's number dup.3 exec.id_anchor_block_num - # => [anchor_block_num, 0, 0, account_id_hi, account_id_lo] + # => [anchor_block_num, 0, 0, account_id_prefix, account_id_suffix] exec.memory::get_chain_mmr_ptr swap - # => [anchor_block_num, chain_mmr_ptr, 0, 0, account_id_hi, account_id_lo] + # => [anchor_block_num, chain_mmr_ptr, 0, 0, account_id_prefix, account_id_suffix] exec.mmr::get - # => [ANCHOR_BLOCK_HASH, 0, 0, account_id_hi, account_id_lo] + # => [ANCHOR_BLOCK_HASH, 0, 0, account_id_prefix, account_id_suffix] # assert that the anchor block hash is not the empty word padw eqw not assert.err=ERR_ACCOUNT_ANCHOR_BLOCK_HASH_MUST_NOT_BE_EMPTY dropw - # => [ANCHOR_BLOCK_HASH, 0, 0, account_id_hi, account_id_lo] + # => [ANCHOR_BLOCK_HASH, 0, 0, account_id_prefix, account_id_suffix] # Compute the hash of (SEED, CODE_COMMITMENT, STORAGE_COMMITMENT, ANCHOR_BLOCK_HASH). # --------------------------------------------------------------------------------------------- # prepare advice push_mapval swapw - # => [0, 0, account_id_hi, account_id_lo, ANCHOR_BLOCK_HASH] + # => [0, 0, account_id_prefix, account_id_suffix, ANCHOR_BLOCK_HASH] - # populate first four elements of the rate with the account id seed + # populate first four elements of the rate with the account ID seed adv.push_mapval push.15263 drop # TODO: remove line, see miden-vm/#1122 adv_loadw # => [SEED, ANCHOR_BLOCK_HASH] @@ -807,117 +807,117 @@ export.validate_seed exec.rpo::squeeze_digest # => [DIGEST] - # Shape second felt to add the anchor epoch and compare computed and provided ID. + # Shape suffix to add the anchor epoch and compare computed and provided ID. # --------------------------------------------------------------------------------------------- - # extract account id from digest + # extract account ID from digest drop drop swap - # => [hashed_account_id_hi, hashed_account_id_lo] + # => [hashed_account_id_prefix, hashed_account_id_suffix] exec.memory::get_account_id movdn.3 - # => [account_id_lo, hashed_account_id_hi, hashed_account_id_lo, account_id_hi] + # => [account_id_suffix, hashed_account_id_prefix, hashed_account_id_suffix, account_id_prefix] # extract anchor epoch from ID of the new account dup movdn.4 exec.id_anchor_epoch - # => [anchor_epoch, hashed_account_id_hi, hashed_account_id_lo, account_id_hi, account_id_lo] + # => [anchor_epoch, hashed_account_id_prefix, hashed_account_id_suffix, account_id_prefix, account_id_suffix] - # shape second felt of hashed id, adding the anchor epoch and setting the lower 8 bits to zero - movup.2 exec.shape_second_felt swap - # => [hashed_account_id_hi, hashed_account_id_lo, account_id_hi, account_id_lo] + # shape suffix of hashed id, adding the anchor epoch and setting the lower 8 bits to zero + movup.2 exec.shape_suffix swap + # => [hashed_account_id_prefix, hashed_account_id_suffix, account_id_prefix, account_id_suffix] - # assert the account id matches the account id of the new account + # assert the account ID matches the account ID of the new account exec.is_id_eq assert.err=ERR_ACCOUNT_SEED_ANCHOR_BLOCK_HASH_DIGEST_MISMATCH # => [] end -#! Shapes the second felt so it meets the requirements of the account ID, by overwriting the +#! Shapes the suffix so it meets the requirements of the account ID, by overwriting the #! upper 16 bits with the anchor epoch and setting the lower 8 bits to zero. #! -#! Inputs: [seed_digest_lo, anchor_epoch] -#! Outputs: [account_id_lo] +#! Inputs: [seed_digest_suffix, anchor_epoch] +#! Outputs: [account_id_suffix] #! #! Where: -#! - seed_digest_lo is the second felt of the digest that should be shaped into the second felt +#! - seed_digest_suffix is the suffix of the digest that should be shaped into the suffix #! of an account ID. -#! - account_id_lo is the second felt of an account ID. +#! - account_id_suffix is the suffix of an account ID. #! - anchor_epoch is the epoch number to which this account ID is anchored. -proc.shape_second_felt +proc.shape_suffix u32split - # => [seed_digest_lo_hi, seed_digest_lo_lo, anchor_epoch] + # => [seed_digest_suffix_hi, seed_digest_suffix_lo, anchor_epoch] # clear epoch bits in hi part so we can set them later u32and.0x0000ffff swap - # => [seed_digest_lo_lo, seed_digest_lo_hi', anchor_epoch] + # => [seed_digest_suffix_lo, seed_digest_suffix_hi', anchor_epoch] # clear lower 8 bits of the lo part u32and.0xffffff00 swap.2 - # => [anchor_epoch, seed_digest_lo_hi', seed_digest_lo_lo'] + # => [anchor_epoch, seed_digest_suffix_hi', seed_digest_suffix_lo'] # assert epoch is not 2^16 # this is technically optional as we will compare this id with the provided one for which # this property was already checked, but since this check is cheap we include it anyway dup eq.0xffff assertz.err=ERR_ACCOUNT_ID_EPOCH_MUST_BE_LESS_THAN_U16_MAX - # => [anchor_epoch, seed_digest_lo_hi', seed_digest_lo_lo'] + # => [anchor_epoch, seed_digest_suffix_hi', seed_digest_suffix_lo'] # shift epoch left by 16 bits and set epoch bits on hi part u32shl.16 u32or - # => [seed_digest_lo_hi'', seed_digest_lo_lo'] + # => [seed_digest_suffix_hi'', seed_digest_suffix_lo'] - # reassemble the second felt by multiplying the hi part with 2^32 and adding the lo part + # reassemble the suffix by multiplying the hi part with 2^32 and adding the lo part mul.0x0100000000 add - # => [account_id_lo] + # => [account_id_suffix] end -#! Extracts the block number of the anchor block from the second felt of an account ID. +#! Extracts the block number of the anchor block from the suffix of an account ID. #! -#! Inputs: [account_id_lo] +#! Inputs: [account_id_suffix] #! Outputs: [anchor_block_num] #! #! Where: -#! - account_id_lo is the second felt of an account ID. +#! - account_id_suffix is the suffix of an account ID. #! - anchor_block_num is the number of the block to which this account ID is anchored. proc.id_anchor_block_num # extract the upper 32 bits u32split swap drop - # => [account_id_lo_hi] + # => [account_id_suffix_hi] - # to get the epoch's block number we would have to multiply the epoch in the account id by 2^16 + # to get the epoch's block number we would have to multiply the epoch in the account ID by 2^16 # since the epoch is already in the upper 16 bits of the u32, we can simply zero out the # lower 16 bits to achieve the same result. u32and.0xffff0000 # => [anchor_block_num] end -#! Extracts the epoch from the second felt of an account ID. +#! Extracts the epoch from the suffix of an account ID. #! -#! Inputs: [account_id_lo] +#! Inputs: [account_id_suffix] #! Outputs: [anchor_epoch] #! #! Where: -#! - account_id_lo is the second felt of an account ID. +#! - account_id_suffix is the suffix of an account ID. #! - anchor_epoch is the epoch number to which this account ID is anchored. proc.id_anchor_epoch # extract the upper 32 bits u32split swap drop - # => [account_id_lo_hi] + # => [account_id_suffix_hi] # shift the upper 16 bits to the right to produce the epoch u32shr.16 # => [anchor_epoch] end -#! Extracts the account ID version from the first felt of an account ID. +#! Extracts the account ID version from the prefix of an account ID. #! -#! Inputs: [account_id_hi] +#! Inputs: [account_id_prefix] #! Outputs: [id_version] #! #! Where: -#! - account_id_hi is the first felt of an account ID. +#! - account_id_prefix is the prefix of an account ID. #! - id_version is the version number of the ID. proc.id_version # extract the lower 32 bits u32split drop - # => [account_id_hi_lo] + # => [account_id_prefix_lo] # mask out the version u32and.ACCOUNT_VERSION_MASK_U32 @@ -1068,19 +1068,19 @@ end # HELPER PROCEDURES # ================================================================================================= -#! Returns the most significant half with the account type bits masked out. +#! Returns the least significant half of an account ID prefix with the account type bits masked out. #! -#! The account type can be defined by comparing this value with the following constants: +#! The account type can be obtained by comparing this value with the following constants: #! - REGULAR_ACCOUNT_UPDATABLE_CODE #! - REGULAR_ACCOUNT_IMMUTABLE_CODE #! - FUNGIBLE_FAUCET_ACCOUNT #! - NON_FUNGIBLE_FAUCET_ACCOUNT #! -#! Inputs: [acct_id_hi] +#! Inputs: [acct_id_prefix] #! Outputs: [acct_type] #! #! Where: -#! - acct_id_hi is the first felt of the account id. +#! - acct_id_prefix is the prefix of the account ID. #! - acct_type is the account type. proc.type u32split drop push.ACCOUNT_ID_TYPE_MASK_U32 u32and @@ -1142,11 +1142,11 @@ end #! Returns the pointer to the next vacant memory slot if the account was not loaded before, and the #! pointer to the account data otherwise. #! -#! Inputs: [foreign_account_id_hi, foreign_account_id_lo] -#! Outputs: [was_loaded, ptr, foreign_account_id_hi, foreign_account_id_lo] +#! Inputs: [foreign_account_id_prefix, foreign_account_id_suffix] +#! Outputs: [was_loaded, ptr, foreign_account_id_prefix, foreign_account_id_suffix] #! #! Where: -#! - foreign_account_id_{hi,lo} are the first and second felt of the ID of the foreign account +#! - foreign_account_id_{prefix,suffix} are the prefix and suffix felts of the ID of the foreign account #! whose procedure is going to be executed. #! - was_loaded is the binary flag indicating whether the foreign account was already loaded to the #! memory. @@ -1154,20 +1154,20 @@ end #! data, depending on the value of the was_loaded flag. #! #! Panics if: -#! - the first or second felt of the provided foreign account ID equal zero. +#! - the prefix or suffix of the provided foreign account ID equal zero. #! - the maximum allowed number of foreign account to be loaded (64) was exceeded. export.get_foreign_account_ptr - # check that foreign account id is not equal zero + # check that foreign account ID is not equal zero dup.1 eq.0 dup.1 eq.0 and not assert.err=ERR_FOREIGN_ACCOUNT_ID_IS_ZERO - # => [foreign_account_id_hi, foreign_account_id_lo] + # => [foreign_account_id_prefix, foreign_account_id_suffix] - # check that foreign account id is not equal to the native account id + # check that foreign account ID is not equal to the native account ID dup.1 dup.1 exec.memory::get_native_account_id exec.is_id_eq not assert.err=ERR_FOREIGN_ACCOUNT_ID_EQUALS_NATIVE_ACCT_ID # get the initial account data pointer exec.memory::get_native_account_data_ptr - # => [curr_account_ptr, foreign_account_id_hi, foreign_account_id_lo] + # => [curr_account_ptr, foreign_account_id_prefix, foreign_account_id_suffix] # push the flag to enter the loop push.1 @@ -1176,41 +1176,41 @@ export.get_foreign_account_ptr # drop the flag left from the previous loop # in the first iteration this will be a pad element movup.3 drop - # => [curr_account_ptr, foreign_account_id_hi, foreign_account_id_lo] + # => [curr_account_ptr, foreign_account_id_prefix, foreign_account_id_suffix] # move the current account pointer to the next account data block exec.memory::get_account_data_length add - # => [curr_account_ptr', foreign_account_id_hi, foreign_account_id_lo] + # => [curr_account_ptr', foreign_account_id_prefix, foreign_account_id_suffix] # load the first data word at the current account pointer padw dup.4 mem_loadw - # => [FIRST_DATA_WORD, curr_account_ptr', foreign_account_id_hi, foreign_account_id_lo] + # => [FIRST_DATA_WORD, curr_account_ptr', foreign_account_id_prefix, foreign_account_id_suffix] # check whether the last value in the word equals zero # if so it means this memory block was not yet initialized drop drop dup.1 eq.0 - # => [is_empty_block, maybe_account_id_hi, maybe_account_id_lo, curr_account_ptr', foreign_account_id_hi, foreign_account_id_lo] + # => [is_empty_block, maybe_account_id_prefix, maybe_account_id_suffix, curr_account_ptr', foreign_account_id_prefix, foreign_account_id_suffix] # check whether the current id matches the foreign id movdn.2 dup.5 dup.5 exec.is_id_eq - # => [is_equal_id, is_empty_word, curr_account_ptr', foreign_account_id_hi, foreign_account_id_lo] + # => [is_equal_id, is_empty_word, curr_account_ptr', foreign_account_id_prefix, foreign_account_id_suffix] # get the loop flag # it equals 1 if both `is_equal_id` and `is_empty_block` flags are equal to 0, so we should # continue iterating dup movdn.5 or not - # => [loop_flag, curr_account_ptr', foreign_account_id_hi, foreign_account_id_lo, is_equal_id] + # => [loop_flag, curr_account_ptr', foreign_account_id_prefix, foreign_account_id_suffix, is_equal_id] end # check that the loading of one more account won't exceed the maximum number of the foreign # accounts which can be loaded. dup exec.memory::get_max_foreign_account_ptr lte assert.err=ERR_FOREIGN_ACCOUNT_MAX_NUMBER_EXCEEDED - # => [curr_account_ptr, foreign_account_id_hi, foreign_account_id_lo, is_equal_id] + # => [curr_account_ptr, foreign_account_id_prefix, foreign_account_id_suffix, is_equal_id] # the resulting `was_loaded` flag is essentially equal to the `is_equal_id` flag movup.3 - # => [was_loaded, curr_account_ptr, foreign_account_id_hi, foreign_account_id_lo] + # => [was_loaded, curr_account_ptr, foreign_account_id_prefix, foreign_account_id_suffix] end #! Checks that the state of the current foreign account is valid. @@ -1225,22 +1225,21 @@ export.validate_current_foreign_account exec.memory::get_acct_db_root # => [ACCOUNT_DB_ROOT] - # TODO: Update when account tree was updated. # get the current account ID exec.memory::get_account_id swap drop - # => [account_id_hi, ACCOUNT_DB_ROOT] + # => [account_id_prefix, ACCOUNT_DB_ROOT] # push the depth of the account database tree push.ACCOUNT_TREE_DEPTH - # => [depth, account_id_hi, ACCOUNT_DB_ROOT] + # => [depth, account_id_prefix, ACCOUNT_DB_ROOT] # get the foreign account hash exec.get_current_hash - # => [FOREIGN_ACCOUNT_HASH, depth, account_id_hi, ACCOUNT_DB_ROOT] + # => [FOREIGN_ACCOUNT_HASH, depth, account_id_prefix, ACCOUNT_DB_ROOT] # verify that the account database has the hash of the current foreign account mtree_verify.err=ERR_FOREIGN_ACCOUNT_INVALID - # => [FOREIGN_ACCOUNT_HASH, depth, account_id_hi, ACCOUNT_DB_ROOT] + # => [FOREIGN_ACCOUNT_HASH, depth, account_id_prefix, ACCOUNT_DB_ROOT] # clean the stack dropw drop drop dropw diff --git a/miden-lib/asm/kernels/transaction/lib/asset.masm b/miden-lib/asm/kernels/transaction/lib/asset.masm index 6d6add3a3..d38b257fd 100644 --- a/miden-lib/asm/kernels/transaction/lib/asset.masm +++ b/miden-lib/asm/kernels/transaction/lib/asset.masm @@ -59,11 +59,11 @@ export.validate_fungible_asset dup.2 not assert.err=ERR_FUNGIBLE_ASSET_FORMAT_ELEMENT_ONE_MUST_BE_ZERO # => [ASSET] - # assert that the tuple (ASSET[3], ASSET[2]) forms a valid account id + # assert that the tuple (ASSET[3], ASSET[2]) forms a valid account ID dup.1 dup.1 exec.account::validate_id # => [ASSET] - # assert that the first felt (ASSET[3]) of the account id is of type fungible faucet + # assert that the prefix (ASSET[3]) of the account ID is of type fungible faucet dup exec.account::is_fungible_faucet assert.err=ERR_FUNGIBLE_ASSET_FORMAT_ELEMENT_TWO_AND_THREE_MUST_BE_FUNGIBLE_FAUCET_ID # => [ASSET] @@ -101,8 +101,8 @@ end #! Panics if: #! - the asset is not well formed. export.validate_non_fungible_asset - # assert that ASSET[3] is a valid account id prefix - # hack: because we only have the first felt we add a 0 as the second felt which is always valid + # assert that ASSET[3] is a valid account ID prefix + # hack: because we only have the prefix we add a 0 as the suffix which is always valid push.0 dup.1 exec.account::validate_id # => [ASSET] @@ -155,16 +155,16 @@ end #! Validates that a fungible asset is associated with the provided faucet_id. #! -#! Inputs: [faucet_id_hi, faucet_id_lo, ASSET] +#! Inputs: [faucet_id_prefix, faucet_id_suffix, ASSET] #! Outputs: [ASSET] #! #! Where: -#! - faucet_id_hi is the first felt of the faucet's account id. +#! - faucet_id_prefix is the prefix of the faucet's account ID. #! - ASSET is the asset to validate. export.validate_fungible_asset_origin # assert the origin of the asset is the faucet_id provided via the stack dup.3 dup.3 - # => [asset_id_hi, asset_id_lo, faucet_id_hi, faucet_id_lo, ASSET] + # => [asset_id_prefix, asset_id_suffix, faucet_id_prefix, faucet_id_suffix, ASSET] exec.account::is_id_eq assert.err=ERR_FUNGIBLE_ASSET_FAUCET_IS_NOT_ORIGIN # => [ASSET] @@ -176,11 +176,11 @@ end #! Validates that a non-fungible asset is associated with the provided faucet_id. #! -#! Inputs: [faucet_id_hi, ASSET] +#! Inputs: [faucet_id_prefix, ASSET] #! Outputs: [ASSET] #! #! Where: -#! - faucet_id_hi is the first felt of the faucet's account id. +#! - faucet_id_prefix is the prefix of the faucet's account ID. #! - ASSET is the asset to validate. export.validate_non_fungible_asset_origin # assert the origin of the asset is the faucet_id prefix provided via the stack diff --git a/miden-lib/asm/kernels/transaction/lib/asset_vault.masm b/miden-lib/asm/kernels/transaction/lib/asset_vault.masm index cbba6e040..0f63f7f0e 100644 --- a/miden-lib/asm/kernels/transaction/lib/asset_vault.masm +++ b/miden-lib/asm/kernels/transaction/lib/asset_vault.masm @@ -42,12 +42,12 @@ const.INVERSE_FUNGIBLE_BITMASK_U32=0xffffffdf # last byte: 0b1101_1111 #! Returns the balance of a fungible asset associated with a faucet_id. #! -#! Inputs: [faucet_id_hi, faucet_id_lo, vault_root_ptr] +#! Inputs: [faucet_id_prefix, faucet_id_suffix, vault_root_ptr] #! Outputs: [balance] #! #! Where: #! - vault_root_ptr is a pointer to the memory location at which the vault root is stored. -#! - faucet_id_hi is the first felt of the faucet id of the fungible asset of interest. +#! - faucet_id_prefix is the prefix of the faucet id of the fungible asset of interest. #! - balance is the vault balance of the fungible asset. #! #! Panics if: @@ -56,15 +56,15 @@ export.get_balance # assert that the faucet id is a fungible faucet dup exec.account::is_fungible_faucet assert.err=ERR_VAULT_GET_BALANCE_PROC_CAN_ONLY_BE_CALLED_ON_FUNGIBLE_FAUCET - # => [faucet_id_hi, faucet_id_lo, vault_root_ptr] + # => [faucet_id_prefix, faucet_id_suffix, vault_root_ptr] # get the asset vault root padw movup.6 mem_loadw - # => [ASSET_VAULT_ROOT, faucet_id_hi, faucet_id_lo] + # => [ASSET_VAULT_ROOT, faucet_id_prefix, faucet_id_suffix] # prepare the key for fungible asset lookup (pad least significant elements with zeros) push.0.0 movup.7 movup.7 - # => [faucet_id_hi, faucet_id_lo, 0, 0, ASSET_VAULT_ROOT] + # => [faucet_id_prefix, faucet_id_suffix, 0, 0, ASSET_VAULT_ROOT] # lookup asset exec.smt::get swapw dropw @@ -134,15 +134,15 @@ export.add_fungible_asset # Create the asset key from the asset. # --------------------------------------------------------------------------------------------- - # => [faucet_id_hi, faucet_id_lo, 0, amount, vault_root_ptr] + # => [faucet_id_prefix, faucet_id_suffix, 0, amount, vault_root_ptr] dupw - # => [faucet_id_hi, faucet_id_lo, 0, amount, faucet_id_hi, faucet_id_lo, 0, amount, vault_root_ptr] + # => [faucet_id_prefix, faucet_id_suffix, 0, amount, faucet_id_prefix, faucet_id_suffix, 0, amount, vault_root_ptr] push.0 swap.4 drop - # => [[faucet_id_hi, faucet_id_lo, 0, 0], faucet_id_hi, faucet_id_lo, 0, amount, vault_root_ptr] + # => [[faucet_id_prefix, faucet_id_suffix, 0, 0], faucet_id_prefix, faucet_id_suffix, 0, amount, vault_root_ptr] movup.6 drop - # => [[faucet_id_hi, faucet_id_lo, 0, 0], faucet_id_hi, faucet_id_lo, amount, vault_root_ptr] + # => [[faucet_id_prefix, faucet_id_suffix, 0, 0], faucet_id_prefix, faucet_id_suffix, amount, vault_root_ptr] padw dup.11 - # => [vault_root_ptr, pad(4), ASSET_KEY, faucet_id_hi, faucet_id_lo, amount, vault_root_ptr] + # => [vault_root_ptr, pad(4), ASSET_KEY, faucet_id_prefix, faucet_id_suffix, amount, vault_root_ptr] # Get the asset vault root and read the current asset using the `push_smtpeek` decorator. # --------------------------------------------------------------------------------------------- @@ -150,18 +150,18 @@ export.add_fungible_asset # the current asset may be the empty word if it does not exist and so its faucet id would be zeroes # we therefore overwrite the faucet id with the faucet id from ASSET to account for this edge case mem_loadw swapw - # => [ASSET_KEY, VAULT_ROOT, faucet_id_hi, faucet_id_lo, amount, vault_root_ptr] + # => [ASSET_KEY, VAULT_ROOT, faucet_id_prefix, faucet_id_suffix, amount, vault_root_ptr] adv.push_smtpeek push.15329 drop # TODO: remove line, see miden-vm/#1122 adv_loadw - # => [CUR_VAULT_VALUE, VAULT_ROOT, faucet_id_hi, faucet_id_lo, amount, vault_root_ptr] + # => [CUR_VAULT_VALUE, VAULT_ROOT, faucet_id_prefix, faucet_id_suffix, amount, vault_root_ptr] swapw - # => [VAULT_ROOT, CUR_VAULT_VALUE, faucet_id_hi, faucet_id_lo, amount, vault_root_ptr] + # => [VAULT_ROOT, CUR_VAULT_VALUE, faucet_id_prefix, faucet_id_suffix, amount, vault_root_ptr] dupw.1 - # => [CUR_VAULT_VALUE, VAULT_ROOT, CUR_VAULT_VALUE, faucet_id_hi, faucet_id_lo, amount, vault_root_ptr] + # => [CUR_VAULT_VALUE, VAULT_ROOT, CUR_VAULT_VALUE, faucet_id_prefix, faucet_id_suffix, amount, vault_root_ptr] drop drop - # => [[0, cur_amount], VAULT_ROOT, CUR_VAULT_VALUE, faucet_id_hi, faucet_id_lo, amount, vault_root_ptr] + # => [[0, cur_amount], VAULT_ROOT, CUR_VAULT_VALUE, faucet_id_prefix, faucet_id_suffix, amount, vault_root_ptr] movup.11 movup.11 - # => [[faucet_id_hi, faucet_id_lo, 0, cur_amount], VAULT_ROOT, CUR_VAULT_VALUE, amount, vault_root_ptr] + # => [[faucet_id_prefix, faucet_id_suffix, 0, cur_amount], VAULT_ROOT, CUR_VAULT_VALUE, amount, vault_root_ptr] # Check the new amount does not exceed the maximum allowed amount and add the two # fungible assets together. @@ -169,16 +169,16 @@ export.add_fungible_asset # arrange amounts movup.3 movup.12 dup - # => [amount, amount, cur_amount, faucet_id_hi, faucet_id_lo, 0, VAULT_ROOT, CUR_VAULT_VALUE, vault_root_ptr] + # => [amount, amount, cur_amount, faucet_id_prefix, faucet_id_suffix, 0, VAULT_ROOT, CUR_VAULT_VALUE, vault_root_ptr] # compute max_amount - cur_amount exec.asset::get_fungible_asset_max_amount dup.3 sub - # => [(max_amount - cur_amount), amount, amount, cur_amount, faucet_id_hi, faucet_id_lo, 0, VAULT_ROOT, + # => [(max_amount - cur_amount), amount, amount, cur_amount, faucet_id_prefix, faucet_id_suffix, 0, VAULT_ROOT, # CUR_VAULT_VALUE, vault_root_ptr] # assert amount + cur_amount < max_amount lte assert.err=ERR_VAULT_FUNGIBLE_MAX_AMOUNT_EXCEEDED - # => [amount, cur_amount, faucet_id_hi, faucet_id_lo, 0, VAULT_ROOT, CUR_VAULT_VALUE, vault_root_ptr] + # => [amount, cur_amount, faucet_id_prefix, faucet_id_suffix, 0, VAULT_ROOT, CUR_VAULT_VALUE, vault_root_ptr] # add asset amounts add movdn.3 @@ -193,7 +193,7 @@ export.add_fungible_asset dupw # => [ASSET', ASSET', VAULT_ROOT, CUR_VAULT_VALUE, ASSET', vault_root_ptr] push.0 swap.4 drop - # => [[faucet_id_hi, faucet_id_lo, 0, 0], ASSET', VAULT_ROOT, CUR_VAULT_VALUE, ASSET', vault_root_ptr] + # => [[faucet_id_prefix, faucet_id_suffix, 0, 0], ASSET', VAULT_ROOT, CUR_VAULT_VALUE, ASSET', vault_root_ptr] swapw # => [ASSET', ASSET_KEY', VAULT_ROOT, CUR_VAULT_VALUE, ASSET', vault_root_ptr] @@ -433,17 +433,17 @@ end #! - ASSET_KEY is the vault key of the non-fungible asset. proc.build_non_fungible_asset_vault_key # create the asset key from the non-fungible asset by swapping hash0 with the faucet id - # => [faucet_id_hi, hash2, hash1, hash0] + # => [faucet_id_prefix, hash2, hash1, hash0] swap.3 - # => [hash0, hash2, hash1 faucet_id_hi] + # => [hash0, hash2, hash1 faucet_id_prefix] # disassemble hash0 into u32 limbs u32split swap - # => [hash0_lo, hash0_hi, hash2, hash1 faucet_id_hi] + # => [hash0_lo, hash0_hi, hash2, hash1 faucet_id_prefix] # set the fungible bit to 0 u32and.INVERSE_FUNGIBLE_BITMASK_U32 - # => [hash0_lo', hash0_hi, hash2, hash1 faucet_id_hi] + # => [hash0_lo', hash0_hi, hash2, hash1 faucet_id_prefix] # reassemble hash0 felt by multiplying the high part with 2^32 and adding the lo part swap push.0x0100000000 mul add diff --git a/miden-lib/asm/kernels/transaction/lib/memory.masm b/miden-lib/asm/kernels/transaction/lib/memory.masm index 87e5450df..e7804eb40 100644 --- a/miden-lib/asm/kernels/transaction/lib/memory.masm +++ b/miden-lib/asm/kernels/transaction/lib/memory.masm @@ -49,7 +49,7 @@ const.GLOBAL_INPUTS_SECTION_OFFSET=100 # The memory address at which the latest known block hash is stored const.BLK_HASH_PTR=100 -# The memory address at which the account id felts are stored. +# The memory address at which the account ID felts are stored. const.ACCT_ID_PTR=101 # The memory address at which the initial account hash is stored @@ -328,31 +328,31 @@ export.get_block_hash padw push.BLK_HASH_PTR mem_loadw end -#! Sets the account id. +#! Sets the account ID. #! -#! Inputs: [acct_id_hi, acct_id_lo] +#! Inputs: [acct_id_prefix, acct_id_suffix] #! Outputs: [] #! #! Where: -#! - acct_id_{hi,lo} are the first and second felt of the account id. +#! - acct_id_{prefix,suffix} are the prefix and suffix felts of the account ID. export.set_global_acct_id push.0.0 - # => [0, 0, acct_id_hi, acct_id_lo] + # => [0, 0, acct_id_prefix, acct_id_suffix] mem_storew.ACCT_ID_PTR dropw # => [] end -#! Returns the global account id. +#! Returns the global account ID. #! #! Inputs: [] -#! Outputs: [acct_id_hi, acct_id_lo] +#! Outputs: [acct_id_prefix, acct_id_suffix] #! #! Where: -#! - acct_id_{hi,lo} are the first and second felt of the account id. +#! - acct_id_{prefix,suffix} are the prefix and suffix felts of the account ID. export.get_global_acct_id padw mem_loadw.ACCT_ID_PTR - # => [0, 0, acct_id_hi, acct_id_lo] + # => [0, 0, acct_id_prefix, acct_id_suffix] drop drop end @@ -731,25 +731,25 @@ end #! Returns the id of the current account. #! #! Inputs: [] -#! Outputs: [curr_acct_id_hi, curr_acct_id_lo] +#! Outputs: [curr_acct_id_prefix, curr_acct_id_suffix] #! #! Where: -#! - curr_acct_id_{hi,lo} are the first and second felt of the account id of the currently +#! - curr_acct_id_{prefix,suffix} are the prefix and suffix felts of the account ID of the currently #! accessing account. export.get_account_id padw exec.get_current_account_data_ptr push.ACCT_ID_AND_NONCE_OFFSET add mem_loadw - # => [nonce, 0, curr_acct_id_hi, curr_acct_id_lo] + # => [nonce, 0, curr_acct_id_prefix, curr_acct_id_suffix] drop drop - # => [curr_acct_id_hi, curr_acct_id_lo] + # => [curr_acct_id_prefix, curr_acct_id_suffix] end -#! Sets the account id and nonce. +#! Sets the account ID and nonce. #! -#! Inputs: [account_nonce, 0, account_id_hi, account_id_lo] -#! Outputs: [account_nonce, 0, account_id_hi, account_id_lo] +#! Inputs: [account_nonce, 0, account_id_prefix, account_id_suffix] +#! Outputs: [account_nonce, 0, account_id_prefix, account_id_suffix] #! #! Where: -#! - account_id_{hi,lo} are the first and second felt of the id of the currently accessing account. +#! - account_id_{prefix,suffix} are the prefix and suffix felts of the id of the currently accessing account. #! - account_nonce is the nonce of the currently accessing account. export.set_acct_id_and_nonce exec.get_current_account_data_ptr push.ACCT_ID_AND_NONCE_OFFSET add @@ -759,15 +759,15 @@ end #! Returns the id of the native account. #! #! Inputs: [] -#! Outputs: [native_acct_id_hi, native_acct_id_lo] +#! Outputs: [native_acct_id_prefix, native_acct_id_suffix] #! #! Where: -#! - native_acct_id_{hi,lo} are the first and second felt of the id of the native account. +#! - native_acct_id_{prefix,suffix} are the prefix and suffix felts of the id of the native account. export.get_native_account_id padw push.NATIVE_ACCOUNT_DATA_PTR push.ACCT_ID_AND_NONCE_OFFSET add mem_loadw - # => [nonce, 0, native_acct_id_hi, native_acct_id_lo] + # => [nonce, 0, native_acct_id_prefix, native_acct_id_suffix] drop drop - # => [native_acct_id_hi, native_acct_id_lo] + # => [native_acct_id_prefix, native_acct_id_suffix] end #! Returns the account nonce. @@ -795,7 +795,7 @@ export.set_acct_nonce exec.get_current_account_data_ptr push.ACCT_ID_AND_NONCE_OFFSET add padw # => [0, 0, 0, 0, acct_id_and_nonce_ptr, new_nonce] dup.4 mem_loadw - # => [old_nonce, 0, old_id_hi, old_id_lo, acct_id_and_nonce_ptr, new_nonce] + # => [old_nonce, 0, old_id_prefix, old_id_suffix, acct_id_and_nonce_ptr, new_nonce] drop movup.4 movup.4 mem_storew dropw # => [] end @@ -1261,7 +1261,7 @@ end #! Returns the sender for the input note located at the specified memory address. #! #! Inputs: [note_ptr] -#! Outputs: [sender_hi, sender_lo] +#! Outputs: [sender_id_prefix, sender_id_suffix] #! #! Where: #! - note_ptr is the memory address at which the input note data begins. @@ -1270,22 +1270,22 @@ export.get_input_note_sender padw movup.4 push.INPUT_NOTE_METADATA_OFFSET add mem_loadw - # => [aux, merged_tag_hint_payload, merged_sender_id_type_hint_tag, sender_hi] + # => [aux, merged_tag_hint_payload, merged_sender_id_type_hint_tag, sender_id_prefix] drop drop - # => [merged_sender_id_type_hint_tag, sender_hi] + # => [merged_sender_id_type_hint_tag, sender_id_prefix] - # extract second felt of sender from merged layout, which means clearing the least significant byte + # extract suffix of sender from merged layout, which means clearing the least significant byte u32split swap - # => [merged_lo, merged_hi, sender_hi] + # => [merged_lo, merged_hi, sender_id_prefix] # clear least significant byte u32and.0xffffff00 swap - # => [sender_lo_hi, sender_lo_lo, sender_hi] + # => [sender_id_suffix_hi, sender_id_suffix_lo, sender_id_prefix] - # reassemble the second felt by multiplying the high part with 2^32 and adding the lo part + # reassemble the suffix by multiplying the high part with 2^32 and adding the lo part mul.0x0100000000 add swap - # => [sender_hi, sender_lo] + # => [sender_id_prefix, sender_id_suffix] end diff --git a/miden-lib/asm/kernels/transaction/lib/note.masm b/miden-lib/asm/kernels/transaction/lib/note.masm index c69b6b2df..64f92066a 100644 --- a/miden-lib/asm/kernels/transaction/lib/note.masm +++ b/miden-lib/asm/kernels/transaction/lib/note.masm @@ -31,10 +31,10 @@ const.OUTPUT_NOTE_HASHING_MEM_DIFF=510 #! Returns the sender of the note currently being processed. #! #! Inputs: [] -#! Outputs: [sender_hi, sender_lo] +#! Outputs: [sender_id_prefix, sender_id_suffix] #! #! Where: -#! - sender_{hi,lo} are the first and second felt of the sender of the note currently being processed. +#! - sender_{prefix,suffix} are the prefix and suffix felts of the sender of the note currently being processed. #! #! Panics if: #! - the note is not being processed. @@ -50,7 +50,7 @@ export.get_sender # get the sender from the note pointer exec.memory::get_input_note_sender - # => [sender_hi, sender_lo] + # => [sender_id_prefix, sender_id_suffix] end #! Returns the number of assets and the assets hash of the note currently being processed. diff --git a/miden-lib/asm/kernels/transaction/lib/prologue.masm b/miden-lib/asm/kernels/transaction/lib/prologue.masm index f72943eef..ce35a82f2 100644 --- a/miden-lib/asm/kernels/transaction/lib/prologue.masm +++ b/miden-lib/asm/kernels/transaction/lib/prologue.masm @@ -66,12 +66,12 @@ const.ERR_PROLOGUE_NEW_ACCOUNT_NONCE_MUST_BE_ZERO=0x0002005B #! Saves global inputs to memory. #! -#! Inputs: [BLOCK_HASH, account_id_hi, account_id_lo, INITIAL_ACCOUNT_HASH, INPUT_NOTES_COMMITMENT] +#! Inputs: [BLOCK_HASH, account_id_prefix, account_id_suffix, INITIAL_ACCOUNT_HASH, INPUT_NOTES_COMMITMENT] #! Outputs: [] #! #! Where: #! - BLOCK_HASH is the reference block for the transaction execution. -#! - account_id_{hi,lo} are the first and second felt of the account id of the account that the +#! - account_id_{prefix,suffix} are the prefix and suffix felts of the account ID of the account that the #! transaction is being executed against. #! - INITIAL_ACCOUNT_HASH is the account state prior to the transaction, EMPTY_WORD for new #! accounts. @@ -308,7 +308,7 @@ end #! for a new account. #! #! Applies the following validation to the new account: -#! - assert that the account id is valid. +#! - assert that the account ID is valid. #! - assert that the account vault is empty. #! - assert that the account nonce is set to 0. #! - read the account seed from the advice provider and assert it satisfies seed requirements. @@ -316,7 +316,7 @@ end #! Inputs: [] #! Outputs: [] proc.validate_new_account - # Assert the account id of the account is valid + # Assert the account ID of the account is valid exec.memory::get_account_id exec.account::validate_id # => [] @@ -341,13 +341,13 @@ proc.validate_new_account # --------------------------------------------------------------------------------------------- # check if the account is a faucet exec.account::get_id swap drop dup exec.account::is_faucet - # => [is_faucet, acct_id_hi] + # => [is_faucet, acct_id_prefix] # process conditional logic depending on whether the account is a faucet if.true # get the faucet reserved slot exec.account::get_faucet_storage_data_slot exec.account::get_item - # => [FAUCET_RESERVED_SLOT, acct_id_hi] + # => [FAUCET_RESERVED_SLOT, acct_id_prefix] # check if the account is a fungible faucet movup.4 exec.account::is_fungible_faucet @@ -429,7 +429,7 @@ end #! Inputs: #! Operand stack: [] #! Advice stack: [ -#! account_id_lo, account_id_hi, 0, account_nonce, +#! account_id_suffix, account_id_prefix, 0, account_nonce, #! ACCOUNT_VAULT_ROOT, #! ACCOUNT_STORAGE_COMMITMENT, #! ACCOUNT_CODE_COMMITMENT @@ -439,7 +439,7 @@ end #! Advice stack: [] #! #! Where: -#! - account_id_{hi,lo} are the first and second felt of the ID of the account that the transaction +#! - account_id_{prefix,suffix} are the prefix and suffix felts of the ID of the account that the transaction #! is being executed against. #! - account_nonce is the account's nonce. #! - ACCOUNT_VAULT_ROOT is the account's vault root. @@ -466,7 +466,7 @@ proc.process_account_data movup.4 drop # => [ACCT_HASH] - # assert the account id matches the account id in global inputs + # assert the account ID matches the account ID in global inputs exec.memory::get_global_acct_id exec.memory::get_account_id exec.account::is_id_eq assert.err=ERR_PROLOGUE_MISMATCH_OF_ACCOUNT_IDS_FROM_GLOBAL_INPUTS_AND_ADVICE_PROVIDER @@ -1086,7 +1086,7 @@ end #! Inputs: #! Operand stack: [ #! BLOCK_HASH, -#! account_id_hi, account_id_lo, +#! account_id_prefix, account_id_suffix, #! INITIAL_ACCOUNT_HASH, #! INPUT_NOTES_COMMITMENT, #! ] @@ -1101,7 +1101,7 @@ end #! [block_num, version, timestamp, 0], #! NOTE_ROOT, #! kernel_version -#! [account_id_lo, account_id_hi, 0, account_nonce], +#! [account_id_suffix, account_id_prefix, 0, account_nonce], #! ACCOUNT_VAULT_ROOT, #! ACCOUNT_STORAGE_COMMITMENT, #! ACCOUNT_CODE_COMMITMENT, @@ -1122,7 +1122,7 @@ end #! #! Where: #! - BLOCK_HASH is the reference block for the transaction execution. -#! - account_id_{hi,lo} are the first and second felt of the account that the transaction is being +#! - account_id_{prefix,suffix} are the prefix and suffix felts of the account that the transaction is being #! executed against. #! - INITIAL_ACCOUNT_HASH is the account state prior to the transaction, EMPTY_WORD for new #! accounts. diff --git a/miden-lib/asm/kernels/transaction/lib/tx.masm b/miden-lib/asm/kernels/transaction/lib/tx.masm index 0e0399463..6646e71fc 100644 --- a/miden-lib/asm/kernels/transaction/lib/tx.masm +++ b/miden-lib/asm/kernels/transaction/lib/tx.masm @@ -46,7 +46,7 @@ const.ERR_NOTE_INVALID_TYPE=0x00020043 # account # Target: Is a hint for the type of target. Use case means the note may be consumed by anyone, # specific means there is a specific target for the note (the target may be a public key, a user -# that knows some secret, or a specific account id) +# that knows some secret, or a specific account ID) # # Only the note type from the above list is enforced. The other values are only hints intended as a # best effort optimization strategy. A badly formatted note may 1. not be consumed because honest @@ -422,36 +422,36 @@ proc.build_note_metadata movup.2 add # => [note_tag_hint_payload, execution_hint_tag, aux, note_type] - # Merge sender_lo, note_type and execution_hint_tag. + # Merge sender_id_suffix, note_type and execution_hint_tag. # -------------------------------------------------------------------------------------------- exec.account::get_id - # => [sender_hi, sender_lo, note_tag_hint_payload, execution_hint_tag, aux, note_type] + # => [sender_id_prefix, sender_id_suffix, note_tag_hint_payload, execution_hint_tag, aux, note_type] movup.5 - # => [note_type, sender_hi, sender_lo, note_tag_hint_payload, execution_hint_tag, aux] + # => [note_type, sender_id_prefix, sender_id_suffix, note_tag_hint_payload, execution_hint_tag, aux] # multiply by 2^6 to shift the two note_type bits left by 6 bits. push.0x40 mul - # => [shifted_note_type, sender_hi, sender_lo, note_tag_hint_payload, execution_hint_tag, aux] + # => [shifted_note_type, sender_id_prefix, sender_id_suffix, note_tag_hint_payload, execution_hint_tag, aux] # merge execution_hint_tag into the note_type # this produces an 8-bit value with the layout: [note_type (2 bits) | execution_hint_tag (6 bits)] movup.4 add - # => [merged_note_type_execution_hint_tag, sender_hi, sender_lo, note_tag_hint_payload, aux] + # => [merged_note_type_execution_hint_tag, sender_id_prefix, sender_id_suffix, note_tag_hint_payload, aux] - # merge sender_lo into this value + # merge sender_id_suffix into this value movup.2 add - # => [sender_lo_type_and_hint_tag, sender_hi, note_tag_hint_payload, aux] + # => [sender_id_suffix_type_and_hint_tag, sender_id_prefix, note_tag_hint_payload, aux] # Rearrange elements to produce the final note metadata layout. # -------------------------------------------------------------------------------------------- swap movdn.3 - # => [sender_lo_type_and_hint_tag, note_tag_hint_payload, aux, sender_hi] + # => [sender_id_suffix_type_and_hint_tag, note_tag_hint_payload, aux, sender_id_prefix] swap - # => [note_tag_hint_payload, sender_lo_type_and_hint_tag, aux, sender_hi] + # => [note_tag_hint_payload, sender_id_suffix_type_and_hint_tag, aux, sender_id_prefix] movup.2 - # => [NOTE_METADATA = [aux, note_tag_hint_payload, sender_lo_type_and_hint_tag, sender_hi]] + # => [NOTE_METADATA = [aux, note_tag_hint_payload, sender_id_suffix_type_and_hint_tag, sender_id_prefix]] end #! Creates a new note and returns the index of the note. diff --git a/miden-lib/asm/miden/account.masm b/miden-lib/asm/miden/account.masm index 7c10c064b..bc48b7da9 100644 --- a/miden-lib/asm/miden/account.masm +++ b/miden-lib/asm/miden/account.masm @@ -3,13 +3,13 @@ use.miden::kernel_proc_offsets # NATIVE ACCOUNT PROCEDURES # ================================================================================================= -#! Returns the account id. +#! Returns the account ID. #! #! Inputs: [] -#! Outputs: [acct_id_hi, acct_id_lo] +#! Outputs: [acct_id_prefix, acct_id_suffix] #! #! Where: -#! - acct_id_{hi,lo} are the first and second felt of the account id. +#! - acct_id_{prefix,suffix} are the prefix and suffix felts of the account ID. #! #! Invocation: exec export.get_id @@ -24,11 +24,11 @@ export.get_id # => [offset, pad(15)] syscall.exec_kernel_proc - # => [acct_id_hi, acct_id_lo, pad(14)] + # => [acct_id_prefix, acct_id_suffix, pad(14)] # clean the stack swapdw dropw dropw swapw dropw movdn.3 movdn.3 drop drop - # => [acct_id_hi, acct_id_lo] + # => [acct_id_prefix, acct_id_suffix] end #! Returns the account nonce. @@ -294,11 +294,11 @@ end #! Returns the balance of a fungible asset associated with a faucet_id. #! -#! Inputs: [faucet_id_hi, faucet_id_lo] +#! Inputs: [faucet_id_prefix, faucet_id_suffix] #! Outputs: [balance] #! #! Where: -#! - faucet_id_{hi,lo} are the first and second felt of the faucet id of the fungible asset +#! - faucet_id_{prefix,suffix} are the prefix and suffix felts of the faucet id of the fungible asset #! of interest. #! - balance is the vault balance of the fungible asset. #! @@ -308,11 +308,11 @@ end #! Invocation: exec export.get_balance exec.kernel_proc_offsets::account_vault_get_balance_offset - # => [offset, faucet_id_hi, faucet_id_lo] + # => [offset, faucet_id_prefix, faucet_id_suffix] # pad the stack push.0 movdn.3 padw swapw padw padw swapdw - # => [offset, faucet_id_hi, faucet_id_lo, pad(13)] + # => [offset, faucet_id_prefix, faucet_id_suffix, pad(13)] syscall.exec_kernel_proc # => [balance, pad(15)] @@ -442,7 +442,7 @@ end # PROCEDURES COPIED FROM KERNEL (TODO: get rid of this duplication) # ================================================================================================= -# Given the least significant 32 bits of an account id's first felt, this mask defines the bits used +# Given the least significant 32 bits of an account ID's prefix, this mask defines the bits used # to determine the account type. const.ACCOUNT_ID_TYPE_MASK_U32=0x30 # 0b11_0000 @@ -462,10 +462,10 @@ const.NON_FUNGIBLE_FAUCET_ACCOUNT=0x30 # 0b11_0000 #! - FUNGIBLE_FAUCET_ACCOUNT #! - NON_FUNGIBLE_FAUCET_ACCOUNT #! -#! Stack: [acct_id_hi] +#! Stack: [acct_id_prefix] #! Output: [acct_type] #! -#! - acct_id_hi is the first felt of the account id. +#! - acct_id_prefix is the prefix of the account ID. #! - acct_type is the account type. proc.type u32split drop push.ACCOUNT_ID_TYPE_MASK_U32 u32and @@ -477,7 +477,7 @@ end #! Stack: [acct_id] #! Output: [is_fungible_faucet] #! -#! - acct_id is the account id. +#! - acct_id is the account ID. #! - is_fungible_faucet is a boolean indicating whether the account is a fungible faucet. export.is_fungible_faucet exec.type push.FUNGIBLE_FAUCET_ACCOUNT eq @@ -489,7 +489,7 @@ end #! Stack: [acct_id] #! Output: [is_non_fungible_faucet] #! -#! - acct_id is the account id. +#! - acct_id is the account ID. #! - is_non_fungible_faucet is a boolean indicating whether the account is a non-fungible faucet. export.is_non_fungible_faucet exec.type push.NON_FUNGIBLE_FAUCET_ACCOUNT eq @@ -500,18 +500,18 @@ end #! #! Returns a boolean indicating whether the given account_ids are equal. #! -#! Inputs: [acct_id_hi, acct_id_lo, other_acct_id_hi, other_acct_id_lo] +#! Inputs: [acct_id_prefix, acct_id_suffix, other_acct_id_prefix, other_acct_id_suffix] #! Outputs: [is_id_equal] #! #! Where: -#! - acct_id_{hi,lo} are the first and second felt of an account id. -#! - other_acct_id_{hi,lo} are the first and second felt of the other account id to compare against. -#! - is_id_equal is a boolean indicating whether the account ids are equal. +#! - acct_id_{prefix,suffix} are the prefix and suffix felts of an account ID. +#! - other_acct_id_{prefix,suffix} are the prefix and suffix felts of the other account ID to compare against. +#! - is_id_equal is a boolean indicating whether the account IDs are equal. export.is_id_eq movup.2 eq - # => [is_hi_equal, acct_id_lo, other_acct_id_lo] - swap movup.2 eq - # => [is_lo_equal, is_hi_equal] + # => [is_prefix_equal, acct_id_suffix, other_acct_id_suffix] + movdn.2 eq + # => [is_suffix_equal, is_prefix_equal] and # => [is_id_equal] end diff --git a/miden-lib/asm/miden/asset.masm b/miden-lib/asm/miden/asset.masm index b421f1fec..d1b9d2dc2 100644 --- a/miden-lib/asm/miden/asset.masm +++ b/miden-lib/asm/miden/asset.masm @@ -17,11 +17,11 @@ const.ERR_NON_FUNGIBLE_ASSET_PROVIDED_FAUCET_ID_IS_INVALID=0x0002004D #! Builds a fungible asset for the specified fungible faucet and amount. #! -#! Inputs: [faucet_id_hi, faucet_id_lo, amount] +#! Inputs: [faucet_id_prefix, faucet_id_suffix, amount] #! Outputs: [ASSET] #! #! Where: -#! - faucet_id_{hi,lo} are the first and second felt of the faucet to create the asset for. +#! - faucet_id_{prefix,suffix} are the prefix and suffix felts of the faucet to create the asset for. #! - amount is the amount of the asset to create. #! - ASSET is the built fungible asset. #! @@ -29,12 +29,12 @@ const.ERR_NON_FUNGIBLE_ASSET_PROVIDED_FAUCET_ID_IS_INVALID=0x0002004D export.build_fungible_asset # assert the faucet is a fungible faucet dup exec.account::is_fungible_faucet assert.err=ERR_FUNGIBLE_ASSET_PROVIDED_FAUCET_ID_IS_INVALID - # => [faucet_id_hi, faucet_id_lo, amount] + # => [faucet_id_prefix, faucet_id_suffix, amount] # assert the amount is valid dup.2 exec.get_fungible_asset_max_amount lte assert.err=ERR_FUNGIBLE_ASSET_AMOUNT_EXCEEDS_MAX_ALLOWED_AMOUNT - # => [faucet_id_hi, faucet_id_lo, amount] + # => [faucet_id_prefix, faucet_id_suffix, amount] # create the asset push.0 movdn.2 @@ -54,7 +54,7 @@ end export.create_fungible_asset # fetch the id of the faucet the transaction is being executed against. exec.account::get_id - # => [id_hi, id_lo, amount] + # => [id_prefix, id_suffix, amount] # build the fungible asset exec.build_fungible_asset @@ -63,11 +63,11 @@ end #! Builds a non fungible asset for the specified non-fungible faucet and amount. #! -#! Inputs: [faucet_id_hi, DATA_HASH] +#! Inputs: [faucet_id_prefix, DATA_HASH] #! Outputs: [ASSET] #! #! Where: -#! - faucet_id_{hi,lo} are the first and second felt of the faucet to create the asset for. +#! - faucet_id_{prefix,suffix} are the prefix and suffix felts of the faucet to create the asset for. #! - DATA_HASH is the data hash of the non-fungible asset to build. #! - ASSET is the built non-fungible asset. #! @@ -76,11 +76,11 @@ export.build_non_fungible_asset # assert the faucet is a non-fungible faucet dup exec.account::is_non_fungible_faucet assert.err=ERR_NON_FUNGIBLE_ASSET_PROVIDED_FAUCET_ID_IS_INVALID - # => [faucet_id_hi, hash3, hash2, hash1, hash0] + # => [faucet_id_prefix, hash3, hash2, hash1, hash0] # build the asset swap drop - # => [faucet_id_hi, hash2, hash1, hash0] + # => [faucet_id_prefix, hash2, hash1, hash0] # => [ASSET] end @@ -97,7 +97,7 @@ end export.create_non_fungible_asset # get the id of the faucet the transaction is being executed against exec.account::get_id swap drop - # => [faucet_id_hi, DATA_HASH] + # => [faucet_id_prefix, DATA_HASH] # build the non-fungible asset exec.build_non_fungible_asset diff --git a/miden-lib/asm/miden/contracts/auth/basic.masm b/miden-lib/asm/miden/contracts/auth/basic.masm index 36c205a7d..6e035b4d1 100644 --- a/miden-lib/asm/miden/contracts/auth/basic.masm +++ b/miden-lib/asm/miden/contracts/auth/basic.masm @@ -26,10 +26,10 @@ export.auth_tx_rpo_falcon512 # Get current AccountID and pad exec.account::get_id push.0.0 - # => [0, 0, account_id_hi, account_id_lo, 0, 0, 0, nonce, INPUT_NOTES_HASH, OUTPUT_NOTES_HASH, pad(16)] + # => [0, 0, account_id_prefix, account_id_suffix, 0, 0, 0, nonce, INPUT_NOTES_HASH, OUTPUT_NOTES_HASH, pad(16)] # Compute the message to be signed - # MESSAGE = h(OUTPUT_NOTES_HASH, h(INPUT_NOTES_HASH, h(0, 0, account_id_hi, account_id_lo, 0, 0, 0, nonce))) + # MESSAGE = h(OUTPUT_NOTES_HASH, h(INPUT_NOTES_HASH, h(0, 0, account_id_prefix, account_id_suffix, 0, 0, 0, nonce))) hmerge hmerge hmerge # => [MESSAGE, pad(16)] diff --git a/miden-lib/asm/miden/note.masm b/miden-lib/asm/miden/note.masm index 41f304c0a..070854571 100644 --- a/miden-lib/asm/miden/note.masm +++ b/miden-lib/asm/miden/note.masm @@ -144,10 +144,10 @@ end #! Returns the sender of the note currently being processed. #! #! Inputs: [] -#! Outputs: [sender_hi, sender_lo] +#! Outputs: [sender_id_prefix, sender_id_suffix] #! #! Where: -#! - sender_{hi,lo} are the first and second felt of the sender of the note currently being processed. +#! - sender_{prefix,suffix} are the prefix and suffix felts of the sender of the note currently being processed. #! #! Panics if: #! - no note is being processed. @@ -166,7 +166,7 @@ export.get_sender # clean the stack swapdw dropw dropw swapw dropw movdn.3 movdn.3 drop drop - # => [sender_hi, sender_lo] + # => [sender_id_prefix, sender_id_suffix] end #! Returns the serial number of the note currently being processed. diff --git a/miden-lib/asm/miden/tx.masm b/miden-lib/asm/miden/tx.masm index 11520887e..f4d5f6e5e 100644 --- a/miden-lib/asm/miden/tx.masm +++ b/miden-lib/asm/miden/tx.masm @@ -190,11 +190,11 @@ end #! than 15 elements back. Otherwise exceeding elements will not be provided to the procedure and #! will not be returned from it. #! -#! Inputs: [foreign_account_id_hi, foreign_account_id_lo, FOREIGN_PROC_ROOT, , pad(n)] +#! Inputs: [foreign_account_id_prefix, foreign_account_id_suffix, FOREIGN_PROC_ROOT, , pad(n)] #! Outputs: [] #! #! Where: -#! - foreign_account_id_{hi,lo} are the first and second felt of the account ID of the foreign +#! - foreign_account_id_{prefix,suffix} are the prefix and suffix felts of the account ID of the foreign #! account to execute the procedure on. #! - pad(n) is the exact number of pads needed to set the number of procedure inputs to 16 at the #! moment of the foreign procedure execution (n = 16 - mem_addr_size - foreign_inputs_len). @@ -203,11 +203,11 @@ end export.execute_foreign_procedure.1 # get the start_foreign_context procedure offset push.0 movup.2 movup.2 exec.kernel_proc_offsets::start_foreign_context_offset - # => [offset, foreign_account_id_hi, foreign_account_id_lo, 0, FOREIGN_PROC_ROOT, , pad(n)] + # => [offset, foreign_account_id_prefix, foreign_account_id_suffix, 0, FOREIGN_PROC_ROOT, , pad(n)] # pad the stack before the syscall padw swapw padw padw swapdw - # => [offset, foreign_account_id_hi, foreign_account_id_lo, pad(13), FOREIGN_PROC_ROOT, , pad(n)] + # => [offset, foreign_account_id_prefix, foreign_account_id_suffix, pad(13), FOREIGN_PROC_ROOT, , pad(n)] # load the foreign account to the memory syscall.exec_kernel_proc diff --git a/miden-lib/asm/note_scripts/P2ID.masm b/miden-lib/asm/note_scripts/P2ID.masm index 6bfe759bd..aed3a5cb9 100644 --- a/miden-lib/asm/note_scripts/P2ID.masm +++ b/miden-lib/asm/note_scripts/P2ID.masm @@ -90,12 +90,12 @@ begin eq.2 assert.err=ERR_P2ID_WRONG_NUMBER_OF_INPUTS # => [inputs_ptr] - # read the target account id from the note inputs + # read the target account ID from the note inputs padw movup.4 mem_loadw drop drop - # => [target_account_id_hi, target_account_id_lo] + # => [target_account_id_prefix, target_account_id_suffix] exec.account::get_id - # => [account_id_hi, account_id_lo, target_account_id_hi, target_account_id_lo, ...] + # => [account_id_prefix, account_id_suffix, target_account_id_prefix, target_account_id_suffix, ...] # ensure account_id = target_account_id, fails otherwise exec.account::is_id_eq assert.err=ERR_P2ID_TARGET_ACCT_MISMATCH diff --git a/miden-lib/asm/note_scripts/P2IDR.masm b/miden-lib/asm/note_scripts/P2IDR.masm index 1828b307d..c0ff7a73e 100644 --- a/miden-lib/asm/note_scripts/P2IDR.masm +++ b/miden-lib/asm/note_scripts/P2IDR.masm @@ -99,16 +99,16 @@ begin eq.3 assert.err=ERR_P2IDR_WRONG_NUMBER_OF_INPUTS # => [inputs_ptr] - # read the reclaim block height and target account id from the note inputs + # read the reclaim block height and target account ID from the note inputs padw movup.4 mem_loadw drop - # => [reclaim_block_height, target_account_id_hi, target_account_id_lo] + # => [reclaim_block_height, target_account_id_prefix, target_account_id_suffix] exec.account::get_id dup.1 dup.1 - # => [account_id_hi, account_id_lo, account_id_hi, account_id_lo, reclaim_block_height, target_account_id_hi, target_account_id_lo, ...] + # => [account_id_prefix, account_id_suffix, account_id_prefix, account_id_suffix, reclaim_block_height, target_account_id_prefix, target_account_id_suffix, ...] # determine if the current account is the target account movup.6 movup.6 exec.account::is_id_eq - # => [is_target, account_id_hi, account_id_lo, reclaim_block_height] + # => [is_target, account_id_prefix, account_id_suffix, reclaim_block_height] if.true # if current account is the target, we don't need to check anything else @@ -118,9 +118,9 @@ begin else # if current account is not the target, we need to ensure it is the sender exec.note::get_sender - # => [sender_account_id_hi, sender_account_id_lo, account_id_hi, account_id_lo, reclaim_block_height] + # => [sender_account_id_prefix, sender_account_id_suffix, account_id_prefix, account_id_suffix, reclaim_block_height] - # ensure current account id = sender account id + # ensure current account ID = sender account ID exec.account::is_id_eq assert.err=ERR_P2IDR_RECLAIM_ACCT_IS_NOT_SENDER # => [reclaim_block_height] diff --git a/miden-lib/src/errors/tx_kernel_errors.rs b/miden-lib/src/errors/tx_kernel_errors.rs index 16fab03f6..cd3cfa132 100644 --- a/miden-lib/src/errors/tx_kernel_errors.rs +++ b/miden-lib/src/errors/tx_kernel_errors.rs @@ -119,8 +119,8 @@ pub const TX_KERNEL_ERRORS: [(u32, &str); 89] = [ (ERR_ACCOUNT_CODE_COMMITMENT_MISMATCH, "Computed account code commitment does not match recorded account code commitment"), (ERR_ACCOUNT_CODE_IS_NOT_UPDATABLE, "Account code must be updatable for it to be possible to set new code"), (ERR_ACCOUNT_ID_EPOCH_MUST_BE_LESS_THAN_U16_MAX, "Epoch must be less than u16::MAX (0xffff)."), - (ERR_ACCOUNT_ID_LEAST_SIGNIFICANT_BYTE_MUST_BE_ZERO, "Least significant byte of second felt of the account id must be zero."), - (ERR_ACCOUNT_ID_UNKNOWN_VERSION, "Unknown version in account id."), + (ERR_ACCOUNT_ID_LEAST_SIGNIFICANT_BYTE_MUST_BE_ZERO, "Least significant byte of the account ID suffix must be zero."), + (ERR_ACCOUNT_ID_UNKNOWN_VERSION, "Unknown version in account ID."), (ERR_ACCOUNT_INVALID_STORAGE_OFFSET_FOR_SIZE, "Storage offset is invalid for 0 storage size (should be 0)"), (ERR_ACCOUNT_IS_NOT_NATIVE, "The current account is not native"), (ERR_ACCOUNT_NONCE_DID_NOT_INCREASE_AFTER_STATE_CHANGE, "Account nonce did not increase after a state changing transaction"), diff --git a/miden-lib/src/notes/mod.rs b/miden-lib/src/notes/mod.rs index 8ef85bc78..2c7e27cd6 100644 --- a/miden-lib/src/notes/mod.rs +++ b/miden-lib/src/notes/mod.rs @@ -71,7 +71,7 @@ pub fn create_p2idr_note( let note_script = scripts::p2idr(); let inputs = - NoteInputs::new(vec![target.second_felt(), target.first_felt(), recall_height.into()])?; + NoteInputs::new(vec![target.suffix(), target.prefix().as_felt(), recall_height.into()])?; let tag = NoteTag::from_account_id(target, NoteExecutionMode::Local)?; let serial_num = rng.draw_word(); diff --git a/miden-lib/src/notes/utils.rs b/miden-lib/src/notes/utils.rs index 8491a56ca..e8a6e9f8b 100644 --- a/miden-lib/src/notes/utils.rs +++ b/miden-lib/src/notes/utils.rs @@ -16,7 +16,7 @@ pub fn build_p2id_recipient( serial_num: Word, ) -> Result { let note_script = scripts::p2id(); - let note_inputs = NoteInputs::new(vec![target.second_felt(), target.first_felt()])?; + let note_inputs = NoteInputs::new(vec![target.suffix(), target.prefix().as_felt()])?; Ok(NoteRecipient::new(serial_num, note_script, note_inputs)) } diff --git a/miden-lib/src/transaction/inputs.rs b/miden-lib/src/transaction/inputs.rs index ad0b488a9..d62a16725 100644 --- a/miden-lib/src/transaction/inputs.rs +++ b/miden-lib/src/transaction/inputs.rs @@ -94,8 +94,8 @@ fn build_advice_stack( // Note: keep in sync with the process_account_data kernel procedure let account = tx_inputs.account(); inputs.extend_stack([ - account.id().second_felt(), - account.id().first_felt(), + account.id().suffix(), + account.id().prefix().as_felt(), ZERO, account.nonce(), ]); @@ -152,7 +152,7 @@ fn add_chain_mmr_to_advice_inputs(mmr: &ChainMmr, inputs: &mut AdviceInputs) { /// - The account storage commitment |-> storage slots and types vector. /// - The account code commitment |-> procedures vector. /// - The node |-> (key, value), for all leaf nodes of the asset vault SMT. -/// - [account_id_lo, account_id_hi, 0, 0] |-> account_seed, when account seed is provided. +/// - [account_id_suffix, account_id_prefix, 0, 0] |-> account_seed, when account seed is provided. /// - If present, the Merkle leaves associated with the account storage maps. fn add_account_to_advice_inputs( account: &Account, @@ -194,7 +194,7 @@ fn add_account_to_advice_inputs( // --- account seed ------------------------------------------------------- if let Some(account_seed) = account_seed { inputs.extend_map(vec![( - [account.id().second_felt(), account.id().first_felt(), ZERO, ZERO].into(), + [account.id().suffix(), account.id().prefix().as_felt(), ZERO, ZERO].into(), account_seed.to_vec(), )]); } diff --git a/miden-lib/src/transaction/memory.rs b/miden-lib/src/transaction/memory.rs index 55f9cb3c5..8650abce9 100644 --- a/miden-lib/src/transaction/memory.rs +++ b/miden-lib/src/transaction/memory.rs @@ -85,7 +85,7 @@ pub const GLOBAL_INPUTS_SECTION_OFFSET: MemoryOffset = 100; /// The memory address at which the latest known block hash is stored. pub const BLK_HASH_PTR: MemoryAddress = 100; -/// The memory address at which the account id is stored. +/// The memory address at which the account ID is stored. pub const ACCT_ID_PTR: MemoryAddress = 101; /// The memory address at which the initial account hash is stored. @@ -176,19 +176,19 @@ pub const NATIVE_ACCOUNT_DATA_PTR: MemoryAddress = 2048; /// The length of the memory interval that the account data occupies. pub const ACCOUNT_DATA_LENGTH: MemSize = 2048; -/// The offset at which the account id and nonce are stored relative to the start of +/// The offset at which the account ID and nonce are stored relative to the start of /// the account data segment. pub const ACCT_ID_AND_NONCE_OFFSET: MemoryOffset = 0; -/// The memory address at which the account id and nonce are stored in the native account. +/// The memory address at which the account ID and nonce are stored in the native account. pub const NATIVE_ACCT_ID_AND_NONCE_PTR: MemoryAddress = NATIVE_ACCOUNT_DATA_PTR + ACCT_ID_AND_NONCE_OFFSET; -/// The index of the account id within the account id and nonce data. -pub const ACCT_ID_LO_IDX: DataIndex = 0; -pub const ACCT_ID_HI_IDX: DataIndex = 1; +/// The index of the account ID within the account ID and nonce data. +pub const ACCT_ID_SUFFIX_IDX: DataIndex = 0; +pub const ACCT_ID_PREFIX_IDX: DataIndex = 1; -/// The index of the account nonce within the account id and nonce data. +/// The index of the account nonce within the account ID and nonce data. pub const ACCT_NONCE_IDX: DataIndex = 3; /// The offset at which the account vault root is stored relative to the start of the account diff --git a/miden-lib/src/transaction/mod.rs b/miden-lib/src/transaction/mod.rs index 965a26acc..aa8789894 100644 --- a/miden-lib/src/transaction/mod.rs +++ b/miden-lib/src/transaction/mod.rs @@ -153,8 +153,8 @@ impl TransactionKernel { let mut inputs: Vec = Vec::with_capacity(14); inputs.extend(input_notes_hash); inputs.extend_from_slice(init_acct_hash.as_elements()); - inputs.push(account_id.second_felt()); - inputs.push(account_id.first_felt()); + inputs.push(account_id.suffix()); + inputs.push(account_id.prefix().as_felt()); inputs.extend_from_slice(block_hash.as_elements()); StackInputs::new(inputs) .map_err(|e| e.to_string()) @@ -181,7 +181,7 @@ impl TransactionKernel { let code_root = account_header.code_commitment(); // Note: keep in sync with the start_foreign_context kernel procedure let account_key = - Digest::from([account_id.second_felt(), account_id.first_felt(), ZERO, ZERO]); + Digest::from([account_id.suffix(), account_id.prefix().as_felt(), ZERO, ZERO]); // Extend the advice inputs with the new data advice_inputs.extend_map([ @@ -195,8 +195,8 @@ impl TransactionKernel { // Extend the advice inputs with Merkle store data advice_inputs.extend_merkle_store( - // The first felt is the index in the account tree. - merkle_path.inner_nodes(account_id.first_felt().as_int(), account_header.hash())?, + // The prefix is the index in the account tree. + merkle_path.inner_nodes(account_id.prefix().as_u64(), account_header.hash())?, ); Ok(()) diff --git a/miden-lib/src/transaction/outputs.rs b/miden-lib/src/transaction/outputs.rs index ac16a7ed8..8cff2839e 100644 --- a/miden-lib/src/transaction/outputs.rs +++ b/miden-lib/src/transaction/outputs.rs @@ -4,10 +4,10 @@ use miden_objects::{ }; use super::memory::{ - ACCT_CODE_COMMITMENT_OFFSET, ACCT_DATA_MEM_SIZE, ACCT_ID_AND_NONCE_OFFSET, ACCT_ID_HI_IDX, - ACCT_NONCE_IDX, ACCT_STORAGE_COMMITMENT_OFFSET, ACCT_VAULT_ROOT_OFFSET, + ACCT_CODE_COMMITMENT_OFFSET, ACCT_DATA_MEM_SIZE, ACCT_ID_AND_NONCE_OFFSET, ACCT_NONCE_IDX, + ACCT_STORAGE_COMMITMENT_OFFSET, ACCT_VAULT_ROOT_OFFSET, }; -use crate::transaction::memory::ACCT_ID_LO_IDX; +use crate::transaction::memory::{ACCT_ID_PREFIX_IDX, ACCT_ID_SUFFIX_IDX}; // STACK OUTPUTS // ================================================================================================ @@ -35,8 +35,8 @@ pub fn parse_final_account_header(elements: &[Word]) -> Result [is_faucet, account_id_hi] + # => [is_faucet, account_id_prefix] # truncate the stack swap drop end ", - first_felt = account_id.first_felt(), + prefix = account_id.prefix().as_felt(), ); let process = CodeExecutor::with_advice_provider(MemAdviceProvider::default()) diff --git a/miden-tx/src/tests/kernel_tests/test_asset.rs b/miden-tx/src/tests/kernel_tests/test_asset.rs index a9dfce990..21030dc7b 100644 --- a/miden-tx/src/tests/kernel_tests/test_asset.rs +++ b/miden-tx/src/tests/kernel_tests/test_asset.rs @@ -49,8 +49,8 @@ fn test_create_fungible_asset_succeeds() { Word::from([ Felt::new(FUNGIBLE_ASSET_AMOUNT), Felt::new(0), - faucet_id.second_felt(), - faucet_id.first_felt(), + faucet_id.suffix(), + faucet_id.prefix().as_felt(), ]) ); } diff --git a/miden-tx/src/tests/kernel_tests/test_asset_vault.rs b/miden-tx/src/tests/kernel_tests/test_asset_vault.rs index 8ad83bbfb..40a21ce3e 100644 --- a/miden-tx/src/tests/kernel_tests/test_asset_vault.rs +++ b/miden-tx/src/tests/kernel_tests/test_asset_vault.rs @@ -41,15 +41,15 @@ fn test_get_balance() { begin exec.prologue::prepare_transaction - push.{second_felt}.{first_felt} + push.{suffix}.{prefix} exec.account::get_balance # truncate the stack swap drop end ", - first_felt = faucet_id.first_felt(), - second_felt = faucet_id.second_felt(), + prefix = faucet_id.prefix().as_felt(), + suffix = faucet_id.suffix(), ); let process = tx_context.execute_code(&code).unwrap(); @@ -72,12 +72,12 @@ fn test_get_balance_non_fungible_fails() { begin exec.prologue::prepare_transaction - push.{second_felt}.{first_felt} + push.{suffix}.{prefix} exec.account::get_balance end ", - first_felt = faucet_id.first_felt(), - second_felt = faucet_id.second_felt(), + prefix = faucet_id.prefix().as_felt(), + suffix = faucet_id.suffix(), ); let process = tx_context.execute_code(&code); @@ -122,9 +122,13 @@ fn test_add_fungible_asset_success() { let mut account_vault = tx_context.account().vault().clone(); let faucet_id: AccountId = ACCOUNT_ID_FUNGIBLE_FAUCET_ON_CHAIN.try_into().unwrap(); let amount = FungibleAsset::MAX_AMOUNT - FUNGIBLE_ASSET_AMOUNT; - let add_fungible_asset = - Asset::try_from([Felt::new(amount), ZERO, faucet_id.second_felt(), faucet_id.first_felt()]) - .unwrap(); + let add_fungible_asset = Asset::try_from([ + Felt::new(amount), + ZERO, + faucet_id.suffix(), + faucet_id.prefix().as_felt(), + ]) + .unwrap(); let code = format!( " @@ -163,9 +167,13 @@ fn test_add_non_fungible_asset_fail_overflow() { let faucet_id: AccountId = ACCOUNT_ID_FUNGIBLE_FAUCET_ON_CHAIN.try_into().unwrap(); let amount = FungibleAsset::MAX_AMOUNT - FUNGIBLE_ASSET_AMOUNT + 1; - let add_fungible_asset = - Asset::try_from([Felt::new(amount), ZERO, faucet_id.second_felt(), faucet_id.first_felt()]) - .unwrap(); + let add_fungible_asset = Asset::try_from([ + Felt::new(amount), + ZERO, + faucet_id.suffix(), + faucet_id.prefix().as_felt(), + ]) + .unwrap(); let code = format!( " @@ -267,9 +275,13 @@ fn test_remove_fungible_asset_success_no_balance_remaining() { let faucet_id: AccountId = ACCOUNT_ID_FUNGIBLE_FAUCET_ON_CHAIN.try_into().unwrap(); let amount = FUNGIBLE_ASSET_AMOUNT; - let remove_fungible_asset = - Asset::try_from([Felt::new(amount), ZERO, faucet_id.second_felt(), faucet_id.first_felt()]) - .unwrap(); + let remove_fungible_asset = Asset::try_from([ + Felt::new(amount), + ZERO, + faucet_id.suffix(), + faucet_id.prefix().as_felt(), + ]) + .unwrap(); let code = format!( " @@ -306,9 +318,13 @@ fn test_remove_fungible_asset_fail_remove_too_much() { let tx_context = TransactionContextBuilder::with_standard_account(ONE).build(); let faucet_id: AccountId = ACCOUNT_ID_FUNGIBLE_FAUCET_ON_CHAIN.try_into().unwrap(); let amount = FUNGIBLE_ASSET_AMOUNT + 1; - let remove_fungible_asset = - Asset::try_from([Felt::new(amount), ZERO, faucet_id.second_felt(), faucet_id.first_felt()]) - .unwrap(); + let remove_fungible_asset = Asset::try_from([ + Felt::new(amount), + ZERO, + faucet_id.suffix(), + faucet_id.prefix().as_felt(), + ]) + .unwrap(); let code = format!( " @@ -336,9 +352,13 @@ fn test_remove_fungible_asset_success_balance_remaining() { let faucet_id: AccountId = ACCOUNT_ID_FUNGIBLE_FAUCET_ON_CHAIN.try_into().unwrap(); let amount = FUNGIBLE_ASSET_AMOUNT - 1; - let remove_fungible_asset = - Asset::try_from([Felt::new(amount), ZERO, faucet_id.second_felt(), faucet_id.first_felt()]) - .unwrap(); + let remove_fungible_asset = Asset::try_from([ + Felt::new(amount), + ZERO, + faucet_id.suffix(), + faucet_id.prefix().as_felt(), + ]) + .unwrap(); let code = format!( " diff --git a/miden-tx/src/tests/kernel_tests/test_faucet.rs b/miden-tx/src/tests/kernel_tests/test_faucet.rs index 9a0f7406b..0fa6a9c13 100644 --- a/miden-tx/src/tests/kernel_tests/test_faucet.rs +++ b/miden-tx/src/tests/kernel_tests/test_faucet.rs @@ -55,22 +55,22 @@ fn test_mint_fungible_asset_succeeds() { begin # mint asset exec.prologue::prepare_transaction - push.{FUNGIBLE_ASSET_AMOUNT}.0.{second_felt}.{first_felt} + push.{FUNGIBLE_ASSET_AMOUNT}.0.{suffix}.{prefix} call.account::mint # assert the correct asset is returned - push.{FUNGIBLE_ASSET_AMOUNT}.0.{second_felt}.{first_felt} + push.{FUNGIBLE_ASSET_AMOUNT}.0.{suffix}.{prefix} assert_eqw # assert the input vault has been updated exec.memory::get_input_vault_root_ptr - push.{second_felt}.{first_felt} + push.{suffix}.{prefix} exec.asset_vault::get_balance push.{FUNGIBLE_ASSET_AMOUNT} assert_eq end ", - first_felt = faucet_id.first_felt(), - second_felt = faucet_id.second_felt(), + prefix = faucet_id.prefix().as_felt(), + suffix = faucet_id.suffix(), ); let process = tx_context.execute_code(&code).unwrap(); @@ -99,12 +99,12 @@ fn test_mint_fungible_asset_fails_not_faucet_account() { begin exec.prologue::prepare_transaction - push.{FUNGIBLE_ASSET_AMOUNT}.0.{second_felt}.{first_felt} + push.{FUNGIBLE_ASSET_AMOUNT}.0.{suffix}.{prefix} call.account::mint end ", - first_felt = faucet_id.first_felt(), - second_felt = faucet_id.second_felt(), + prefix = faucet_id.prefix().as_felt(), + suffix = faucet_id.suffix(), ); let process = tx_context.execute_code(&code); @@ -124,12 +124,12 @@ fn test_mint_fungible_asset_inconsistent_faucet_id() { begin exec.prologue::prepare_transaction - push.{FUNGIBLE_ASSET_AMOUNT}.0.{second_felt}.{first_felt} + push.{FUNGIBLE_ASSET_AMOUNT}.0.{suffix}.{prefix} call.account::mint end ", - first_felt = faucet_id.first_felt(), - second_felt = faucet_id.second_felt(), + prefix = faucet_id.prefix().as_felt(), + suffix = faucet_id.suffix(), ); let process = tx_context.execute_code(&code); @@ -154,12 +154,12 @@ fn test_mint_fungible_asset_fails_saturate_max_amount() { begin exec.prologue::prepare_transaction - push.{saturating_amount}.0.{second_felt}.{first_felt} + push.{saturating_amount}.0.{suffix}.{prefix} call.account::mint end ", - first_felt = faucet_id.first_felt(), - second_felt = faucet_id.second_felt(), + prefix = faucet_id.prefix().as_felt(), + suffix = faucet_id.suffix(), saturating_amount = FungibleAsset::MAX_AMOUNT - FUNGIBLE_FAUCET_INITIAL_BALANCE + 1 ); @@ -330,23 +330,23 @@ fn test_burn_fungible_asset_succeeds() { begin # mint asset exec.prologue::prepare_transaction - push.{FUNGIBLE_ASSET_AMOUNT}.0.{second_felt}.{first_felt} + push.{FUNGIBLE_ASSET_AMOUNT}.0.{suffix}.{prefix} call.account::burn # assert the correct asset is returned - push.{FUNGIBLE_ASSET_AMOUNT}.0.{second_felt}.{first_felt} + push.{FUNGIBLE_ASSET_AMOUNT}.0.{suffix}.{prefix} assert_eqw # assert the input vault has been updated exec.memory::get_input_vault_root_ptr - push.{second_felt}.{first_felt} + push.{suffix}.{prefix} exec.asset_vault::get_balance push.{final_input_vault_asset_amount} assert_eq end ", - first_felt = faucet_id.first_felt(), - second_felt = faucet_id.second_felt(), + prefix = faucet_id.prefix().as_felt(), + suffix = faucet_id.suffix(), final_input_vault_asset_amount = CONSUMED_ASSET_1_AMOUNT - FUNGIBLE_ASSET_AMOUNT, ); @@ -376,12 +376,12 @@ fn test_burn_fungible_asset_fails_not_faucet_account() { begin exec.prologue::prepare_transaction - push.{FUNGIBLE_ASSET_AMOUNT}.0.{second_felt}.{first_felt} + push.{FUNGIBLE_ASSET_AMOUNT}.0.{suffix}.{prefix} call.account::burn end ", - first_felt = faucet_id.first_felt(), - second_felt = faucet_id.second_felt(), + prefix = faucet_id.prefix().as_felt(), + suffix = faucet_id.suffix(), ); let process = tx_context.execute_code(&code); @@ -407,12 +407,12 @@ fn test_burn_fungible_asset_inconsistent_faucet_id() { begin exec.prologue::prepare_transaction - push.{FUNGIBLE_ASSET_AMOUNT}.0.{second_felt}.{first_felt} + push.{FUNGIBLE_ASSET_AMOUNT}.0.{suffix}.{prefix} call.account::burn end ", - first_felt = faucet_id.first_felt(), - second_felt = faucet_id.second_felt(), + prefix = faucet_id.prefix().as_felt(), + suffix = faucet_id.suffix(), ); let process = tx_context.execute_code(&code); @@ -438,12 +438,12 @@ fn test_burn_fungible_asset_insufficient_input_amount() { begin exec.prologue::prepare_transaction - push.{saturating_amount}.0.{second_felt}.{first_felt} + push.{saturating_amount}.0.{suffix}.{prefix} call.account::burn end ", - first_felt = faucet_id.first_felt(), - second_felt = faucet_id.second_felt(), + prefix = faucet_id.prefix().as_felt(), + suffix = faucet_id.suffix(), saturating_amount = CONSUMED_ASSET_1_AMOUNT + 1 ); diff --git a/miden-tx/src/tests/kernel_tests/test_note.rs b/miden-tx/src/tests/kernel_tests/test_note.rs index 8374cc6c6..906da38bf 100644 --- a/miden-tx/src/tests/kernel_tests/test_note.rs +++ b/miden-tx/src/tests/kernel_tests/test_note.rs @@ -69,8 +69,8 @@ fn test_get_sender() { let process = tx_context.execute_code(code).unwrap(); let sender = tx_context.input_notes().get_note(0).note().metadata().sender(); - assert_eq!(process.stack.get(0), sender.first_felt()); - assert_eq!(process.stack.get(1), sender.second_felt()); + assert_eq!(process.stack.get(0), sender.prefix().as_felt()); + assert_eq!(process.stack.get(1), sender.suffix()); } #[test] diff --git a/miden-tx/src/tests/kernel_tests/test_prologue.rs b/miden-tx/src/tests/kernel_tests/test_prologue.rs index dae5777cf..24411caa1 100644 --- a/miden-tx/src/tests/kernel_tests/test_prologue.rs +++ b/miden-tx/src/tests/kernel_tests/test_prologue.rs @@ -115,13 +115,13 @@ fn global_input_memory_assertions(process: &Process, inputs: &Transact assert_eq!( read_root_mem_value(process, ACCT_ID_PTR)[0], - inputs.account().id().second_felt(), - "The account ID first felt should be stored at the ACCT_ID_PTR[0]" + inputs.account().id().suffix(), + "The account ID prefix should be stored at the ACCT_ID_PTR[0]" ); assert_eq!( read_root_mem_value(process, ACCT_ID_PTR)[1], - inputs.account().id().first_felt(), - "The account ID second felt should be stored at the ACCT_ID_PTR[1]" + inputs.account().id().prefix().as_felt(), + "The account ID suffix should be stored at the ACCT_ID_PTR[1]" ); assert_eq!( @@ -247,12 +247,12 @@ fn account_data_memory_assertions(process: &Process, inputs: &Transact assert_eq!( read_root_mem_value(process, NATIVE_ACCT_ID_AND_NONCE_PTR), [ - inputs.account().id().second_felt(), - inputs.account().id().first_felt(), + inputs.account().id().suffix(), + inputs.account().id().prefix().as_felt(), ZERO, inputs.account().nonce() ], - "The account id should be stored at NATIVE_ACCT_ID_AND_NONCE_PTR[0]" + "The account ID should be stored at NATIVE_ACCT_ID_AND_NONCE_PTR[0]" ); assert_eq!( @@ -586,7 +586,7 @@ pub fn create_account_invalid_seed() { let tx_inputs = mock_chain.get_transaction_inputs(account.clone(), Some(seed), &[], &[]); // override the seed with an invalid seed to ensure the kernel fails - let account_seed_key = [account.id().second_felt(), account.id().first_felt(), ZERO, ZERO]; + let account_seed_key = [account.id().suffix(), account.id().prefix().as_felt(), ZERO, ZERO]; let adv_inputs = AdviceInputs::default().with_map([(Digest::from(account_seed_key), vec![ZERO; 4])]); diff --git a/miden-tx/src/tests/kernel_tests/test_tx.rs b/miden-tx/src/tests/kernel_tests/test_tx.rs index 96b76d6f1..29ca1b395 100644 --- a/miden-tx/src/tests/kernel_tests/test_tx.rs +++ b/miden-tx/src/tests/kernel_tests/test_tx.rs @@ -368,7 +368,7 @@ fn test_create_note_and_add_asset() { let recipient = [ZERO, ONE, Felt::new(2), Felt::new(3)]; let aux = Felt::new(27); let tag = Felt::new(4); - let asset = [Felt::new(10), ZERO, faucet_id.second_felt(), faucet_id.first_felt()]; + let asset = [Felt::new(10), ZERO, faucet_id.suffix(), faucet_id.prefix().as_felt()]; let code = format!( " @@ -433,10 +433,10 @@ fn test_create_note_and_add_multiple_assets() { let aux = Felt::new(27); let tag = Felt::new(4); - let asset = [Felt::new(10), ZERO, faucet.second_felt(), faucet.first_felt()]; - let asset_2 = [Felt::new(20), ZERO, faucet_2.second_felt(), faucet_2.first_felt()]; - let asset_3 = [Felt::new(30), ZERO, faucet_2.second_felt(), faucet_2.first_felt()]; - let asset_2_and_3 = [Felt::new(50), ZERO, faucet_2.second_felt(), faucet_2.first_felt()]; + let asset = [Felt::new(10), ZERO, faucet.suffix(), faucet.prefix().as_felt()]; + let asset_2 = [Felt::new(20), ZERO, faucet_2.suffix(), faucet_2.prefix().as_felt()]; + let asset_3 = [Felt::new(30), ZERO, faucet_2.suffix(), faucet_2.prefix().as_felt()]; + let asset_2_and_3 = [Felt::new(50), ZERO, faucet_2.suffix(), faucet_2.prefix().as_felt()]; let non_fungible_asset = NonFungibleAsset::mock(&NON_FUNGIBLE_ASSET_DATA_2); let non_fungible_asset_encoded = Word::from(non_fungible_asset); @@ -743,9 +743,9 @@ fn test_fpi_memory() { # get the hash of the `get_item_foreign` procedure of the foreign account push.{get_item_foreign_hash} - # push the foreign account id - push.{foreign_second_felt}.{foreign_first_felt} - # => [foreign_account_id_hi, foreign_account_id_lo, FOREIGN_PROC_ROOT, storage_item_index, pad(11)] + # push the foreign account ID + push.{foreign_suffix}.{foreign_prefix} + # => [foreign_account_id_prefix, foreign_account_id_suffix, FOREIGN_PROC_ROOT, storage_item_index, pad(11)] exec.tx::execute_foreign_procedure # => [STORAGE_VALUE_1] @@ -754,8 +754,8 @@ fn test_fpi_memory() { exec.sys::truncate_stack end ", - foreign_first_felt = foreign_account.id().first_felt(), - foreign_second_felt = foreign_account.id().second_felt(), + foreign_prefix = foreign_account.id().prefix().as_felt(), + foreign_suffix = foreign_account.id().suffix(), get_item_foreign_hash = foreign_account.code().procedures()[0].mast_root(), ); @@ -796,9 +796,9 @@ fn test_fpi_memory() { # get the hash of the `get_map_item_foreign` account procedure push.{get_map_item_foreign_hash} - # push the foreign account id - push.{foreign_second_felt}.{foreign_first_felt} - # => [foreign_account_id_hi, foreign_account_id_lo, FOREIGN_PROC_ROOT, storage_item_index, MAP_ITEM_KEY, pad(10)] + # push the foreign account ID + push.{foreign_suffix}.{foreign_prefix} + # => [foreign_account_id_prefix, foreign_account_id_suffix, FOREIGN_PROC_ROOT, storage_item_index, MAP_ITEM_KEY, pad(10)] exec.tx::execute_foreign_procedure # => [MAP_VALUE] @@ -807,8 +807,8 @@ fn test_fpi_memory() { exec.sys::truncate_stack end ", - foreign_first_felt = foreign_account.id().first_felt(), - foreign_second_felt = foreign_account.id().second_felt(), + foreign_prefix = foreign_account.id().prefix().as_felt(), + foreign_suffix = foreign_account.id().suffix(), map_key = STORAGE_LEAVES_2[0].0, get_map_item_foreign_hash = foreign_account.code().procedures()[1].mast_root(), ); @@ -850,9 +850,9 @@ fn test_fpi_memory() { # get the hash of the `get_item_foreign` procedure of the foreign account push.{get_item_foreign_hash} - # push the foreign account id - push.{foreign_second_felt}.{foreign_first_felt} - # => [foreign_account_id_hi, foreign_account_id_lo, FOREIGN_PROC_ROOT, storage_item_index, pad(14)] + # push the foreign account ID + push.{foreign_suffix}.{foreign_prefix} + # => [foreign_account_id_prefix, foreign_account_id_suffix, FOREIGN_PROC_ROOT, storage_item_index, pad(14)] exec.tx::execute_foreign_procedure dropw # => [] @@ -868,9 +868,9 @@ fn test_fpi_memory() { # get the hash of the `get_item_foreign` procedure of the foreign account push.{get_item_foreign_hash} - # push the foreign account id - push.{foreign_second_felt}.{foreign_first_felt} - # => [foreign_account_id_hi, foreign_account_id_lo, FOREIGN_PROC_ROOT, storage_item_index, pad(14)] + # push the foreign account ID + push.{foreign_suffix}.{foreign_prefix} + # => [foreign_account_id_prefix, foreign_account_id_suffix, FOREIGN_PROC_ROOT, storage_item_index, pad(14)] exec.tx::execute_foreign_procedure @@ -878,8 +878,8 @@ fn test_fpi_memory() { exec.sys::truncate_stack end ", - foreign_first_felt = foreign_account.id().first_felt(), - foreign_second_felt = foreign_account.id().second_felt(), + foreign_prefix = foreign_account.id().prefix().as_felt(), + foreign_suffix = foreign_account.id().suffix(), get_item_foreign_hash = foreign_account.code().procedures()[0].mast_root(), ); @@ -975,9 +975,9 @@ fn test_fpi_execute_foreign_procedure() { # get the hash of the `get_item` account procedure push.{get_item_foreign_hash} - # push the foreign account id - push.{foreign_second_felt}.{foreign_first_felt} - # => [foreign_account_id_hi, foreign_account_id_lo, FOREIGN_PROC_ROOT, storage_item_index, pad(14)] + # push the foreign account ID + push.{foreign_suffix}.{foreign_prefix} + # => [foreign_account_id_prefix, foreign_account_id_suffix, FOREIGN_PROC_ROOT, storage_item_index, pad(14)] exec.tx::execute_foreign_procedure # => [STORAGE_VALUE] @@ -1000,9 +1000,9 @@ fn test_fpi_execute_foreign_procedure() { # get the hash of the `get_map_item_foreign` account procedure push.{get_map_item_foreign_hash} - # push the foreign account id - push.{foreign_second_felt}.{foreign_first_felt} - # => [foreign_account_id_hi, foreign_account_id_lo, FOREIGN_PROC_ROOT, storage_item_index, MAP_ITEM_KEY, pad(10)] + # push the foreign account ID + push.{foreign_suffix}.{foreign_prefix} + # => [foreign_account_id_prefix, foreign_account_id_suffix, FOREIGN_PROC_ROOT, storage_item_index, MAP_ITEM_KEY, pad(10)] exec.tx::execute_foreign_procedure # => [MAP_VALUE] @@ -1015,8 +1015,8 @@ fn test_fpi_execute_foreign_procedure() { exec.sys::truncate_stack end ", - foreign_first_felt = foreign_account.id().first_felt(), - foreign_second_felt = foreign_account.id().second_felt(), + foreign_prefix = foreign_account.id().prefix().as_felt(), + foreign_suffix = foreign_account.id().suffix(), get_item_foreign_hash = foreign_account.code().procedures()[0].mast_root(), get_map_item_foreign_hash = foreign_account.code().procedures()[1].mast_root(), map_key = STORAGE_LEAVES_2[0].0, @@ -1074,7 +1074,7 @@ fn get_mock_fpi_adv_inputs(foreign_account: &Account, mock_chain: &MockChain) -> mock_chain .accounts() // TODO: Update. - .open(&LeafIndex::::new(foreign_account.id().first_felt().as_int()).unwrap()) + .open(&LeafIndex::::new(foreign_account.id().prefix().as_felt().as_int()).unwrap()) .path .into(), ), @@ -1101,8 +1101,8 @@ fn foreign_account_data_memory_assertions(foreign_account: &Account, process: &P assert_eq!( read_root_mem_value(process, foreign_account_data_ptr + ACCT_ID_AND_NONCE_OFFSET), [ - foreign_account.id().second_felt(), - foreign_account.id().first_felt(), + foreign_account.id().suffix(), + foreign_account.id().prefix().as_felt(), ZERO, foreign_account.nonce() ], diff --git a/objects/src/accounts/account_id.rs b/objects/src/accounts/account_id.rs index f8e258405..9d3565f2a 100644 --- a/objects/src/accounts/account_id.rs +++ b/objects/src/accounts/account_id.rs @@ -251,26 +251,26 @@ impl From for AccountIdVersion { /// 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 second felt 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 first felt -/// of the ID must derive exactly from the hash, while only part of the second felt is derived from +/// 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 first felt contains account ID metadata (storage mode, type or version) that does not -/// match any of the known values. -/// - The anchor epoch in the second felt is equal to [`u16::MAX`]. -/// - The lower 8 bits of the second felt are not zero, although [`AccountId::new`] ensures this is -/// the case rather than return an error. +/// - 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 first felt is the output of a hash function so it will be a valid field element without +/// - 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. @@ -278,19 +278,19 @@ impl From for AccountIdVersion { /// 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 first felt which is included in the -/// representation of a non-fungible asset. The first felt alone is enough to determine all of -/// these properties about the ID. +/// - 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 first felt must be derived from the seed, so +/// 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 second felt. 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 second felt is valid even if the remaining bits of the felt are one. -/// - The lower 8 bits of the second felt may be overwritten when the ID is encoded in other layouts -/// such as the [`NoteMetadata`](crate::notes::NoteMetadata). In such cases, it can happen that -/// all bits of the encoded second felt would be one, so having the epoch constraint is important. +/// - 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`](crate::notes::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^[`BlockHeader::EPOCH_LENGTH_EXPONENT`][epoch_len_exp], e.g. `0`, `65536`, `131072`, ... /// These are the first blocks of epoch 0, 1, 2, ... We call this dependence _anchoring_ because @@ -311,8 +311,8 @@ impl From for AccountIdVersion { /// [epoch_len_exp]: crate::block::BlockHeader::EPOCH_LENGTH_EXPONENT #[derive(Debug, Copy, Clone, Eq, PartialEq)] pub struct AccountId { - first_felt: Felt, - second_felt: Felt, + prefix: Felt, + suffix: Felt, } impl AccountId { @@ -344,8 +344,8 @@ impl AccountId { /// Creates an [`AccountId`] by hashing the given `seed`, `code_commitment`, /// `storage_commitment` and [`AccountIdAnchor::block_hash`] from the `anchor` and using the - /// resulting first and second element of the hash as the first and second felt of the ID. - /// The [`AccountIdAnchor::epoch`] from the `anchor` overwrites part of the second felt. + /// 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. @@ -369,14 +369,14 @@ impl AccountId { .try_into() .expect("we should have sliced off 2 elements"); - felts[1] = shape_second_felt(felts[1], anchor.epoch()); + felts[1] = shape_suffix(felts[1], anchor.epoch())?; // This will validate that the anchor_epoch we have just written is not u16::MAX. account_id_from_felts(felts) } - /// Creates an [`AccountId`] from the given felts where the felt at index 0 is the first felt - /// and the felt at index 2 is the second felt. + /// 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 /// @@ -387,34 +387,32 @@ impl AccountId { /// If debug_assertions are enabled (e.g. in debug mode), this function panics if any of the ID /// constraints are not met. See the [type documentation](AccountId) for details. pub fn new_unchecked(elements: [Felt; 2]) -> Self { - let first_felt = elements[0]; - let second_felt = elements[1]; + let prefix = elements[0]; + let suffix = elements[1]; // Panic on invalid felts in debug mode. if cfg!(debug_assertions) { - validate_first_felt(first_felt) - .expect("AccountId::new_unchecked called with invalid first felt"); - validate_second_felt(second_felt) - .expect("AccountId::new_unchecked called with invalid first felt"); + validate_prefix(prefix).expect("AccountId::new_unchecked called with invalid prefix"); + validate_suffix(suffix).expect("AccountId::new_unchecked called with invalid suffix"); } - Self { first_felt, second_felt } + Self { prefix, suffix } } /// Constructs an [`AccountId`] for testing purposes with the given account type and storage /// mode. /// /// This function does the following: - /// - Split the given bytes into a `first_felt = bytes[0..8]` and `second_felt = bytes[8..]` - /// part to be used for the first and second felt, respectively. - /// - The least significant byte of the first felt is set to the version 0, and the given type - /// and storage mode. - /// - The 32nd most significant bit in the first felt 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 second felt the anchor epoch is set to 0 and the lower 8 bits are cleared. + /// - 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 version 0, and the given 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 anchor epoch is set to 0 and the lower 8 bits are cleared. #[cfg(any(feature = "testing", test))] pub fn dummy( mut bytes: [u8; 15], @@ -432,21 +430,21 @@ impl AccountId { // Clear the 32nd most significant bit. bytes[3] &= 0b1111_1110; - let first_felt_bytes = + let prefix_bytes = bytes[0..8].try_into().expect("we should have sliced off exactly 8 bytes"); - let first_felt = Felt::try_from(u64::from_be_bytes(first_felt_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 second_felt_bytes = [0; 8]; + let mut suffix_bytes = [0; 8]; // Overwrite first 7 bytes, leaving the 8th byte 0 (which will be cleared by - // shape_second_felt anyway). - second_felt_bytes[..7].copy_from_slice(&bytes[8..]); + // shape_suffix anyway). + suffix_bytes[..7].copy_from_slice(&bytes[8..]); // If the value is too large modular reduction is performed, which is fine here. - let mut second_felt = Felt::new(u64::from_be_bytes(second_felt_bytes)); + let mut suffix = Felt::new(u64::from_be_bytes(suffix_bytes)); - second_felt = shape_second_felt(second_felt, 0); + suffix = shape_suffix(suffix, 0).expect("anchor epoch is not u16::MAX"); - let account_id = account_id_from_felts([first_felt, second_felt]) + let account_id = account_id_from_felts([prefix, suffix]) .expect("we should have shaped the felts to produce a valid id"); debug_assert_eq!(account_id.account_type(), account_type); @@ -486,7 +484,7 @@ impl AccountId { /// Returns the type of this account ID. pub const fn account_type(&self) -> AccountType { - extract_type(self.first_felt().as_int()) + extract_type(self.prefix.as_int()) } /// Returns true if an account with this ID is a faucet which can issue assets. @@ -501,8 +499,8 @@ impl AccountId { /// Returns the storage mode of this account ID. pub fn storage_mode(&self) -> AccountStorageMode { - extract_storage_mode(self.first_felt().as_int()) - .expect("account id should have been constructed with a valid storage mode") + extract_storage_mode(self.prefix().as_u64()) + .expect("account ID should have been constructed with a valid storage mode") } /// Returns true if an account with this ID is a public account. @@ -512,8 +510,8 @@ impl AccountId { /// Returns the version of this account ID. pub fn version(&self) -> AccountIdVersion { - extract_version(self.first_felt().as_int()) - .expect("account id should have been constructed with a valid version") + extract_version(self.prefix().as_u64()) + .expect("account ID should have been constructed with a valid version") } /// Returns the anchor epoch of this account ID. @@ -521,7 +519,7 @@ impl AccountId { /// 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 anchor_epoch(&self) -> u16 { - extract_anchor_epoch(self.second_felt().as_int()) + extract_anchor_epoch(self.suffix().as_int()) } /// Creates an [`AccountId`] from a hex string. Assumes the string starts with "0x" and @@ -529,9 +527,9 @@ impl AccountId { pub fn from_hex(hex_str: &str) -> Result { hex_to_bytes(hex_str).map_err(AccountError::AccountIdHexParseError).and_then( |mut bytes: [u8; 15]| { - // TryFrom<[u8; 15]> expects [first_felt, second_felt] in little-endian order, so we + // TryFrom<[u8; 15]> expects [prefix, suffix] in little-endian order, so we // need to convert the bytes representation from big endian to little endian by - // reversing each felt. The first felt has 8 and the second felt has + // reversing each felt. The prefix has 8 and the suffix has // 7 bytes. bytes[0..8].reverse(); bytes[8..15].reverse(); @@ -544,30 +542,27 @@ impl AccountId { /// Returns a big-endian, hex-encoded string of length 32, including the `0x` prefix, so it /// encodes 15 bytes. pub fn to_hex(&self) -> String { - // We need to pad the second felt with 16 zeroes so it produces a correctly padded 8 byte + // 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.first_felt().as_int(), self.second_felt().as_int()); + format!("0x{:016x}{:016x}", self.prefix().as_u64(), self.suffix().as_int()); hex_string.truncate(32); hex_string } - /// Returns the [`AccountIdPrefix`] of this ID which is equivalent to the first felt. + /// Returns the [`AccountIdPrefix`] of this ID. + /// + /// The prefix of an account ID is guaranteed to be unique. pub fn prefix(&self) -> AccountIdPrefix { - // SAFETY: We only construct accounts with valid first felts, so we don't have to validate + // SAFETY: We only construct account IDs with valid prefixes, so we don't have to validate // it again. - AccountIdPrefix::new_unchecked(self.first_felt) - } - - /// Returns the first felt of this ID. - pub const fn first_felt(&self) -> Felt { - self.first_felt + AccountIdPrefix::new_unchecked(self.prefix) } - /// Returns the second felt of this ID. - pub const fn second_felt(&self) -> Felt { - self.second_felt + /// Returns the suffix of this ID as a [`Felt`]. + pub const fn suffix(&self) -> Felt { + self.suffix } } @@ -576,17 +571,17 @@ impl AccountId { impl From for [Felt; 2] { fn from(id: AccountId) -> Self { - [id.first_felt, id.second_felt] + [id.prefix, id.suffix] } } impl From for [u8; 15] { fn from(id: AccountId) -> Self { let mut result = [0_u8; 15]; - result[..8].copy_from_slice(&id.first_felt().as_int().to_le_bytes()); - // The last byte of the second felt is always zero, and in little endian this is the first + result[..8].copy_from_slice(&id.prefix().as_u64().to_le_bytes()); + // The last byte of the suffix is always zero, and in little endian this is the first // byte, so we skip it here. - result[8..].copy_from_slice(&id.second_felt().as_int().to_le_bytes()[1..8]); + result[8..].copy_from_slice(&id.suffix().as_int().to_le_bytes()[1..8]); result } } @@ -594,8 +589,8 @@ impl From for [u8; 15] { impl From for u128 { fn from(id: AccountId) -> Self { let mut le_bytes = [0_u8; 16]; - le_bytes[..8].copy_from_slice(&id.second_felt().as_int().to_le_bytes()); - le_bytes[8..].copy_from_slice(&id.first_felt().as_int().to_le_bytes()); + le_bytes[..8].copy_from_slice(&id.suffix().as_int().to_le_bytes()); + le_bytes[8..].copy_from_slice(&id.prefix().as_u64().to_le_bytes()); u128::from_le_bytes(le_bytes) } } @@ -603,7 +598,7 @@ impl From for u128 { /// Account IDs are used as indexes in the account database, which is a tree of depth 64. impl From for LeafIndex { fn from(id: AccountId) -> Self { - LeafIndex::new_max_depth(id.first_felt().as_int()) + LeafIndex::new_max_depth(id.prefix().as_u64()) } } @@ -614,7 +609,7 @@ impl TryFrom<[Felt; 2]> for AccountId { type Error = AccountError; /// Returns an [`AccountId`] instantiated with the provided field elements where `elements[0]` - /// is taken as the first felt and `elements[1]` is taken as the second element. + /// is taken as the prefix and `elements[1]` is taken as the second element. /// /// # Errors /// @@ -636,21 +631,21 @@ impl TryFrom<[u8; 15]> for AccountId { /// documentation](AccountId) for details. fn try_from(bytes: [u8; 15]) -> Result { // This slice has 8 bytes. - let first_felt_slice = &bytes[..8]; + let prefix_slice = &bytes[..8]; // This slice has 7 bytes, since the 8th byte will always be zero. - let second_felt_slice = &bytes[8..15]; + let suffix_slice = &bytes[8..15]; // The byte order is little-endian order, so prepending a 0 sets the least significant byte. - let mut second_felt_bytes = [0; 8]; - second_felt_bytes[1..8].copy_from_slice(second_felt_slice); + let mut suffix_bytes = [0; 8]; + suffix_bytes[1..8].copy_from_slice(suffix_slice); - let first_felt = - Felt::try_from(first_felt_slice).map_err(AccountError::AccountIdInvalidFieldElement)?; + let prefix = + Felt::try_from(prefix_slice).map_err(AccountError::AccountIdInvalidFieldElement)?; - let second_felt = Felt::try_from(second_felt_bytes.as_slice()) + let suffix = Felt::try_from(suffix_bytes.as_slice()) .map_err(AccountError::AccountIdInvalidFieldElement)?; - Self::try_from([first_felt, second_felt]) + Self::try_from([prefix, suffix]) } } @@ -668,9 +663,9 @@ impl TryFrom for AccountId { let mut bytes: [u8; 15] = [0; 15]; // Swap the positions of the Felts to match what the TryFrom<[u8; 15]> impl expects. - // This copies the first felt's 8 bytes. + // This copies the prefix's 8 bytes. bytes[..8].copy_from_slice(&little_endian_bytes[8..]); - // This copies the second felt's 7 bytes. The least significant byte is zero and is + // This copies the suffix's 7 bytes. The least significant byte is zero and is // therefore skipped. bytes[8..].copy_from_slice(&little_endian_bytes[1..8]); @@ -710,58 +705,54 @@ impl Deserializable for AccountId { /// Returns an error if any of the ID constraints are not met. See the See the [type /// documentation](AccountId) for details. fn account_id_from_felts(elements: [Felt; 2]) -> Result { - validate_first_felt(elements[0])?; - validate_second_felt(elements[1])?; + validate_prefix(elements[0])?; + validate_suffix(elements[1])?; - Ok(AccountId { - first_felt: elements[0], - second_felt: elements[1], - }) + Ok(AccountId { prefix: elements[0], suffix: elements[1] }) } -/// Checks that the first felt: +/// Checks that the prefix: /// - has known values for metadata (storage mode, type and version). -pub(super) fn validate_first_felt( - first_felt: Felt, +pub(super) fn validate_prefix( + prefix: Felt, ) -> Result<(AccountType, AccountStorageMode, AccountIdVersion), AccountError> { - let first_felt = first_felt.as_int(); + let prefix = prefix.as_int(); // Validate storage bits. - let storage_mode = extract_storage_mode(first_felt)?; + let storage_mode = extract_storage_mode(prefix)?; // Validate version bits. - let version = extract_version(first_felt)?; + let version = extract_version(prefix)?; - let account_type = extract_type(first_felt); + let account_type = extract_type(prefix); Ok((account_type, storage_mode, version)) } -/// Checks that the second felt: +/// Checks that the suffix: /// - has an anchor_epoch that is not [`u16::MAX`]. /// - has its lower 8 bits set to zero. -fn validate_second_felt(second_felt: Felt) -> Result<(), AccountError> { - let second_felt = second_felt.as_int(); +fn validate_suffix(suffix: Felt) -> Result<(), AccountError> { + let suffix = suffix.as_int(); - if extract_anchor_epoch(second_felt) == u16::MAX { + if extract_anchor_epoch(suffix) == u16::MAX { return Err(AccountError::AssumptionViolated( - "TODO: Make proper error: second felt epoch must be less than 2^16".into(), + "TODO: Make proper error: suffix epoch must be less than 2^16".into(), )); } - // Validate lower 8 bits of second felt are zero. - if second_felt & 0xff != 0 { + // Validate lower 8 bits of suffix are zero. + if suffix & 0xff != 0 { return Err(AccountError::AssumptionViolated( - "TODO: Make proper error: second felt lower 8 bits must be zero".into(), + "TODO: Make proper error: suffix lower 8 bits must be zero".into(), )); } Ok(()) } -pub(crate) fn extract_storage_mode(first_felt: u64) -> Result { - let bits = - (first_felt & (AccountId::STORAGE_MODE_MASK as u64)) >> AccountId::STORAGE_MODE_SHIFT; +pub(crate) fn extract_storage_mode(prefix: u64) -> Result { + let bits = (prefix & AccountId::STORAGE_MODE_MASK as u64) >> AccountId::STORAGE_MODE_SHIFT; // SAFETY: `STORAGE_MODE_MASK` is u8 so casting bits is lossless match bits as u8 { PUBLIC => Ok(AccountStorageMode::Public), @@ -770,8 +761,8 @@ pub(crate) fn extract_storage_mode(first_felt: u64) -> Result Result { - let bits = first_felt & AccountId::VERSION_MASK; +pub(crate) fn extract_version(prefix: u64) -> Result { + let bits = prefix & AccountId::VERSION_MASK; let version = bits.try_into().expect("TODO"); match version { AccountIdVersion::VERSION_0_NUMBER => Ok(AccountIdVersion::VERSION_0), @@ -781,8 +772,8 @@ pub(crate) fn extract_version(first_felt: u64) -> Result AccountType { - let bits = (first_felt & (AccountId::TYPE_MASK as u64)) >> AccountId::TYPE_SHIFT; +pub(crate) const fn extract_type(prefix: u64) -> AccountType { + let bits = (prefix & (AccountId::TYPE_MASK as u64)) >> AccountId::TYPE_SHIFT; // SAFETY: `TYPE_MASK` is u8 so casting bits is lossless match bits as u8 { REGULAR_ACCOUNT_UPDATABLE_CODE => AccountType::RegularAccountUpdatableCode, @@ -796,28 +787,28 @@ pub(crate) const fn extract_type(first_felt: u64) -> AccountType { } } -fn extract_anchor_epoch(second_felt: u64) -> u16 { - ((second_felt & AccountId::ANCHOR_EPOCH_MASK) >> AccountId::ANCHOR_EPOCH_SHIFT) as u16 +const fn extract_anchor_epoch(suffix: u64) -> u16 { + ((suffix & AccountId::ANCHOR_EPOCH_MASK) >> AccountId::ANCHOR_EPOCH_SHIFT) as u16 } -/// Shapes the second felt so it meets the requirements of the account ID, by overwriting the +/// Shapes the suffix so it meets the requirements of the account ID, by overwriting the /// upper 16 bits with the epoch and setting the lower 8 bits to zero. -fn shape_second_felt(second_felt: Felt, anchor_epoch: u16) -> Felt { +fn shape_suffix(suffix: Felt, anchor_epoch: u16) -> Result { if anchor_epoch == u16::MAX { unimplemented!("TODO: Return error"); } - let mut second_felt = second_felt.as_int(); + let mut suffix = suffix.as_int(); // Clear upper 16 epoch bits and the lower 8 bits. - second_felt &= 0x0000_ffff_ffff_ff00; + suffix &= 0x0000_ffff_ffff_ff00; // Set the upper 16 anchor epoch bits. - second_felt |= (anchor_epoch as u64) << AccountId::ANCHOR_EPOCH_SHIFT; + suffix |= (anchor_epoch as u64) << AccountId::ANCHOR_EPOCH_SHIFT; // SAFETY: We disallow u16::MAX which would be all 1 bits, so at least one of the most // significant bits will always be zero. - Felt::try_from(second_felt).expect("epoch is never all ones so felt should be valid") + Ok(Felt::try_from(suffix).expect("epoch is never all ones so felt should be valid")) } // COMMON TRAIT IMPLS @@ -890,16 +881,16 @@ mod tests { for anchor_epoch in [0, u16::MAX - 1, 5000] { let anchor = AccountIdAnchor::new_unchecked(anchor_epoch, anchor_block_hash); let id = AccountId::new(seed, anchor, code_commitment, storage_commitment).unwrap(); - assert_eq!(id.anchor_epoch(), anchor_epoch, "failed for account id: {id}"); + assert_eq!(id.anchor_epoch(), anchor_epoch, "failed for account ID: {id}"); } } #[test] fn account_id_from_felts_with_high_pop_count() { - let valid_second_felt = Felt::try_from(0xfffe_ffff_ffff_ff00u64).unwrap(); - let valid_first_felt = Felt::try_from(0x7fff_ffff_ffff_ff00u64).unwrap(); + let valid_suffix = Felt::try_from(0xfffe_ffff_ffff_ff00u64).unwrap(); + let valid_prefix = Felt::try_from(0x7fff_ffff_ffff_ff00u64).unwrap(); - let id1 = AccountId::new_unchecked([valid_first_felt, valid_second_felt]); + let id1 = AccountId::new_unchecked([valid_prefix, valid_suffix]); assert_eq!(id1.account_type(), AccountType::RegularAccountImmutableCode); assert_eq!(id1.storage_mode(), AccountStorageMode::Public); assert_eq!(id1.version(), AccountIdVersion::VERSION_0); diff --git a/objects/src/accounts/account_id_prefix.rs b/objects/src/accounts/account_id_prefix.rs index 0a955a4df..f12f784b5 100644 --- a/objects/src/accounts/account_id_prefix.rs +++ b/objects/src/accounts/account_id_prefix.rs @@ -10,16 +10,14 @@ use vm_processor::DeserializationError; use super::account_id; use crate::{ - accounts::{ - account_id::validate_first_felt, AccountIdVersion, AccountStorageMode, AccountType, - }, + accounts::{account_id::validate_prefix, AccountIdVersion, AccountStorageMode, AccountType}, AccountError, }; // ACCOUNT ID PREFIX // ================================================================================================ -/// The first felt of an [`AccountId`][id], i.e. its prefix. +/// The prefix of an [`AccountId`][id], i.e. its first field element. /// /// See the type's documentation for details. /// @@ -29,7 +27,7 @@ use crate::{ /// [id]: crate::accounts::AccountId #[derive(Debug, Copy, Clone, Eq, PartialEq)] pub struct AccountIdPrefix { - first_felt: Felt, + prefix: Felt, } impl AccountIdPrefix { @@ -42,7 +40,7 @@ impl AccountIdPrefix { // CONSTRUCTORS // -------------------------------------------------------------------------------------------- - /// Constructs a new [`AccountIdPrefix`] from the given `first_felt` without checking its + /// Constructs a new [`AccountIdPrefix`] from the given `prefix` without checking its /// validity. /// /// # Warning @@ -54,34 +52,44 @@ impl AccountIdPrefix { /// If debug_assertions are enabled (e.g. in debug mode), this function panics if the given /// felt is invalid according to the constraints in the /// [`AccountId`](crate::accounts::AccountId) documentation. - pub fn new_unchecked(first_felt: Felt) -> Self { + pub fn new_unchecked(prefix: Felt) -> Self { // Panic on invalid felts in debug mode. if cfg!(debug_assertions) { - validate_first_felt(first_felt) - .expect("AccountIdPrefix::new_unchecked called with invalid first felt"); + validate_prefix(prefix) + .expect("AccountIdPrefix::new_unchecked called with invalid prefix"); } - AccountIdPrefix { first_felt } + AccountIdPrefix { prefix } } - /// Constructs a new [`AccountIdPrefix`] from the given `first_felt` and checks its validity. + /// Constructs a new [`AccountIdPrefix`] from the given `prefix` and checks its validity. /// /// # Errors /// - /// Returns an error if any of the ID constraints of the first felt are not met. See the + /// Returns an error if any of the ID constraints of the prefix are not met. See the /// [`AccountId`](crate::accounts::AccountId) type documentation for details. - pub fn new(first_felt: Felt) -> Result { - validate_first_felt(first_felt)?; + pub fn new(prefix: Felt) -> Result { + validate_prefix(prefix)?; - Ok(AccountIdPrefix { first_felt }) + Ok(AccountIdPrefix { prefix }) } // PUBLIC ACCESSORS // -------------------------------------------------------------------------------------------- + /// Returns the [`Felt`] that represents this prefix. + pub const fn as_felt(&self) -> Felt { + self.prefix + } + + /// Returns the prefix as a [`u64`]. + pub const fn as_u64(&self) -> u64 { + self.prefix.as_int() + } + /// Returns the type of this account ID. pub const fn account_type(&self) -> AccountType { - account_id::extract_type(self.first_felt.as_int()) + account_id::extract_type(self.prefix.as_int()) } /// Returns true if an account with this ID is a faucet (can issue assets). @@ -96,8 +104,8 @@ impl AccountIdPrefix { /// Returns the storage mode of this account ID. pub fn storage_mode(&self) -> AccountStorageMode { - account_id::extract_storage_mode(self.first_felt.as_int()) - .expect("account id prefix should have been constructed with a valid storage mode") + account_id::extract_storage_mode(self.prefix.as_int()) + .expect("account ID prefix should have been constructed with a valid storage mode") } /// Returns true if an account with this ID is a public account. @@ -107,13 +115,13 @@ impl AccountIdPrefix { /// Returns the version of this account ID. pub fn version(&self) -> AccountIdVersion { - account_id::extract_version(self.first_felt.as_int()) - .expect("account id prefix should have been constructed with a valid version") + account_id::extract_version(self.prefix.as_int()) + .expect("account ID prefix should have been constructed with a valid version") } /// Returns the prefix as a big-endian, hex-encoded string. pub fn to_hex(&self) -> String { - format!("0x{:016x}", self.first_felt.as_int()) + format!("0x{:016x}", self.prefix.as_int()) } } @@ -122,21 +130,21 @@ impl AccountIdPrefix { impl From for Felt { fn from(id: AccountIdPrefix) -> Self { - id.first_felt + id.prefix } } impl From for [u8; 8] { fn from(id: AccountIdPrefix) -> Self { let mut result = [0_u8; 8]; - result[..8].copy_from_slice(&id.first_felt.as_int().to_le_bytes()); + result[..8].copy_from_slice(&id.prefix.as_int().to_le_bytes()); result } } impl From for u64 { fn from(id: AccountIdPrefix) -> Self { - id.first_felt.as_int() + id.prefix.as_int() } } @@ -150,7 +158,7 @@ impl TryFrom<[u8; 8]> for AccountIdPrefix { /// /// # Errors /// - /// Returns an error if any of the ID constraints of the first felt are not met. See the + /// Returns an error if any of the ID constraints of the prefix are not met. See the /// [`AccountId`](crate::accounts::AccountId) type documentation for details. fn try_from(value: [u8; 8]) -> Result { let element = @@ -166,7 +174,7 @@ impl TryFrom for AccountIdPrefix { /// /// # Errors /// - /// Returns an error if any of the ID constraints of the first felt are not met. See the + /// Returns an error if any of the ID constraints of the prefix are not met. See the /// [`AccountId`](crate::accounts::AccountId) type documentation for details. fn try_from(value: u64) -> Result { let element = Felt::try_from(value.to_le_bytes().as_slice()) @@ -182,7 +190,7 @@ impl TryFrom for AccountIdPrefix { /// /// # Errors /// - /// Returns an error if any of the ID constraints of the first felt are not met. See the + /// Returns an error if any of the ID constraints of the prefix are not met. See the /// [`AccountId`](crate::accounts::AccountId) type documentation for details. fn try_from(element: Felt) -> Result { Self::new(element) @@ -200,7 +208,7 @@ impl PartialOrd for AccountIdPrefix { impl Ord for AccountIdPrefix { fn cmp(&self, other: &Self) -> core::cmp::Ordering { - self.first_felt.as_int().cmp(&other.first_felt.as_int()) + self.prefix.as_int().cmp(&other.prefix.as_int()) } } diff --git a/objects/src/accounts/header.rs b/objects/src/accounts/header.rs index f4594f83f..1780cfa4b 100644 --- a/objects/src/accounts/header.rs +++ b/objects/src/accounts/header.rs @@ -11,7 +11,7 @@ use super::{hash_account, Account, AccountId, Digest, Felt, ZERO}; /// components of the account. /// /// The [AccountHeader] is composed of: -/// - id: the account id ([`AccountId`]) of the account. +/// - id: the account ID ([`AccountId`]) of the account. /// - nonce: the nonce of the account. /// - vault_root: a commitment to the account's vault ([super::AssetVault]). /// - storage_commitment: a commitment to the account's storage ([super::AccountStorage]). @@ -92,7 +92,7 @@ impl AccountHeader { /// This is done by first converting the account header data into an array of Words as follows: /// ```text /// [ - /// [account_id_lo, account_id_hi, 0, account_nonce] + /// [account_id_suffix, account_id_prefix, 0, account_nonce] /// [VAULT_COMMITMENT] /// [STORAGE_COMMITMENT] /// [CODE_COMMITMENT] @@ -101,7 +101,7 @@ impl AccountHeader { /// And then concatenating the resulting elements into a single vector. pub fn as_elements(&self) -> Vec { [ - &[self.id.second_felt(), self.id.first_felt(), ZERO, self.nonce], + &[self.id.suffix(), self.id.prefix().as_felt(), ZERO, self.nonce], self.vault_root.as_elements(), self.storage_commitment.as_elements(), self.code_commitment.as_elements(), diff --git a/objects/src/accounts/mod.rs b/objects/src/accounts/mod.rs index 31b8e09a9..e4c8f45d3 100644 --- a/objects/src/accounts/mod.rs +++ b/objects/src/accounts/mod.rs @@ -354,8 +354,8 @@ pub fn hash_account( code_commitment: Digest, ) -> Digest { let mut elements = [ZERO; 16]; - elements[0] = id.second_felt(); - elements[1] = id.first_felt(); + elements[0] = id.suffix(); + elements[1] = id.prefix().as_felt(); elements[3] = nonce; elements[4..8].copy_from_slice(&*vault_root); elements[8..12].copy_from_slice(&*storage_commitment); diff --git a/objects/src/accounts/seed.rs b/objects/src/accounts/seed.rs index 095b97907..cd6b54997 100644 --- a/objects/src/accounts/seed.rs +++ b/objects/src/accounts/seed.rs @@ -11,7 +11,7 @@ use std::{ use super::{ account_id::compute_digest, AccountError, AccountStorageMode, AccountType, Digest, Felt, Word, }; -use crate::accounts::account_id::{validate_first_felt, AccountIdVersion}; +use crate::accounts::account_id::{validate_prefix, AccountIdVersion}; // SEED GENERATORS // -------------------------------------------------------------------------------------------- @@ -108,9 +108,9 @@ fn compute_account_seed_inner( return; } - let first_felt = current_digest.as_elements()[0]; + let prefix = current_digest.as_elements()[0]; if let Ok((computed_account_type, computed_storage_mode, computed_version)) = - validate_first_felt(first_felt) + validate_prefix(prefix) { if computed_account_type == account_type && computed_storage_mode == storage_mode @@ -183,9 +183,9 @@ pub fn compute_account_seed_single( log.iteration(current_digest, current_seed); // check if the seed satisfies the specified account type - let first_felt = current_digest.as_elements()[0]; + let prefix = current_digest.as_elements()[0]; if let Ok((computed_account_type, computed_storage_mode, computed_version)) = - validate_first_felt(first_felt) + validate_prefix(prefix) { if computed_account_type == account_type && computed_storage_mode == storage_mode diff --git a/objects/src/assets/fungible.rs b/objects/src/assets/fungible.rs index 36dbe8e1a..9557f1408 100644 --- a/objects/src/assets/fungible.rs +++ b/objects/src/assets/fungible.rs @@ -27,7 +27,7 @@ impl FungibleAsset { /// The serialized size of a [`FungibleAsset`] in bytes. /// - /// Currently an account id (15 bytes) plus an amount (u64). + /// Currently an account ID (15 bytes) plus an amount (u64). pub const SERIALIZED_SIZE: usize = AccountId::SERIALIZED_SIZE + core::mem::size_of::(); // CONSTRUCTOR @@ -142,8 +142,8 @@ impl FungibleAsset { /// Returns the key which is used to store this asset in the account vault. pub(super) fn vault_key_from_faucet(faucet_id: AccountId) -> Word { let mut key = Word::default(); - key[2] = faucet_id.second_felt(); - key[3] = faucet_id.first_felt(); + key[2] = faucet_id.suffix(); + key[3] = faucet_id.prefix().as_felt(); key } } @@ -152,8 +152,8 @@ impl From for Word { fn from(asset: FungibleAsset) -> Self { let mut result = Word::default(); result[0] = Felt::new(asset.amount); - result[2] = asset.faucet_id.second_felt(); - result[3] = asset.faucet_id.first_felt(); + result[2] = asset.faucet_id.suffix(); + result[3] = asset.faucet_id.prefix().as_felt(); debug_assert!(is_not_a_non_fungible_asset(result)); result } diff --git a/objects/src/assets/mod.rs b/objects/src/assets/mod.rs index 971fef50e..3d0e02f2b 100644 --- a/objects/src/assets/mod.rs +++ b/objects/src/assets/mod.rs @@ -32,7 +32,7 @@ pub use vault::AssetVault; /// - ZERO for a fungible asset. /// - non-ZERO for a non-fungible asset. /// -/// Element 3 of both asset types is an [`AccountIdPrefix`] or equivalently, the first felt of an +/// Element 3 of both asset types is an [`AccountIdPrefix`] or equivalently, the prefix of an /// [`AccountId`](crate::accounts::AccountId), which can be used to distinguish assets /// based on [`AccountIdPrefix::account_type`]. /// @@ -48,11 +48,11 @@ pub use vault::AssetVault; /// /// # Fungible assets /// -/// - A fungible asset's data layout is: `[amount, 0, faucet_id_lo, faucet_id_hi]`. -/// - A fungible asset's vault key layout is: `[0, 0, faucet_id_lo, faucet_id_hi]`. +/// - A fungible asset's data layout is: `[amount, 0, faucet_id_suffix, faucet_id_prefix]`. +/// - A fungible asset's vault key layout is: `[0, 0, faucet_id_suffix, faucet_id_prefix]`. /// -/// The most significant elements of a fungible asset are set to the first (`faucet_id_hi`) and -/// second felt (`faucet_id_lo`) of the ID of the faucet which issues the asset. This guarantees the +/// The most significant elements of a fungible asset are set to the prefix (`faucet_id_prefix`) and +/// suffix (`faucet_id_suffix`) of the ID of the faucet which issues the asset. This guarantees the /// properties described above (the fungible bit is `1`). /// /// The least significant element is set to the amount of the asset. This amount cannot be greater @@ -66,16 +66,16 @@ pub use vault::AssetVault; /// /// # Non-fungible assets /// -/// - A non-fungible asset's data layout is: `[hash0, hash1, hash2, faucet_id_hi]`. -/// - A non-fungible asset's vault key layout is: `[faucet_id_hi, hash1, hash2, hash0']`, where +/// - A non-fungible asset's data layout is: `[hash0, hash1, hash2, faucet_id_prefix]`. +/// - A non-fungible asset's vault key layout is: `[faucet_id_prefix, hash1, hash2, hash0']`, where /// `hash0'` is equivalent to `hash0` with the fungible bit set to `0`. See /// [`NonFungibleAsset::vault_key`] for more details. /// /// The 4 elements of non-fungible assets are computed as follows: /// - First the asset data is hashed. This compresses an asset of an arbitrary length to 4 field /// elements: `[hash0, hash1, hash2, hash3]`. -/// - `hash3` is then replaced with the first felt of the faucet ID (`faucet_id_hi`) which issues -/// the asset: `[hash0, hash1, hash2, faucet_id_hi]`. +/// - `hash3` is then replaced with the prefix of the faucet ID (`faucet_id_prefix`) which issues +/// the asset: `[hash0, hash1, hash2, faucet_id_prefix]`. /// /// It is impossible to find a collision between two non-fungible assets issued by different faucets /// as the faucet_id is included in the description of the non-fungible asset and this is guaranteed @@ -249,7 +249,7 @@ fn is_not_a_non_fungible_asset(asset: Word) -> bool { }, Err(err) => { #[cfg(debug_assertions)] - panic!("invalid account id prefix passed to is_not_a_non_fungible_asset: {err}"); + panic!("invalid account ID prefix passed to is_not_a_non_fungible_asset: {err}"); #[cfg(not(debug_assertions))] false }, diff --git a/objects/src/assets/nonfungible.rs b/objects/src/assets/nonfungible.rs index feaee7067..af1059f58 100644 --- a/objects/src/assets/nonfungible.rs +++ b/objects/src/assets/nonfungible.rs @@ -21,8 +21,8 @@ const FAUCET_ID_POS: usize = 3; /// The commitment is constructed as follows: /// /// - Hash the asset data producing `[hash0, hash1, hash2, hash3]`. -/// - Replace the value of `hash3` with the first felt of the faucet id (`faucet_id_hi`) producing -/// `[hash0, hash1, hash2, faucet_id_hi]`. +/// - Replace the value of `hash3` with the prefix of the faucet id (`faucet_id_prefix`) producing +/// `[hash0, hash1, hash2, faucet_id_prefix]`. /// - This layout ensures that fungible and non-fungible assets are distinguishable by interpreting /// the 3rd element of an asset as an [`AccountIdPrefix`] and checking its type. /// @@ -112,7 +112,7 @@ impl NonFungibleAsset { pub fn vault_key(&self) -> Word { let mut vault_key = self.0; - // Swap first felt of faucet ID with hash0. + // Swap prefix of faucet ID with hash0. vault_key.swap(0, FAUCET_ID_POS); // Set the fungible bit to zero by taking the bitwise `and` of the felt with the inverted diff --git a/objects/src/errors.rs b/objects/src/errors.rs index 94cedf585..783776e90 100644 --- a/objects/src/errors.rs +++ b/objects/src/errors.rs @@ -70,7 +70,7 @@ pub enum AccountError { AccountComponentMergeError(String), #[error("failed to create account component")] AccountComponentTemplateInstantiationError(#[source] AccountComponentTemplateError), - #[error("failed to convert bytes into account id field element")] + #[error("failed to convert bytes into account ID field element")] AccountIdInvalidFieldElement(#[source] DeserializationError), #[error("failed to update asset vault")] AssetVaultUpdateError(#[source] AssetVaultError), @@ -84,7 +84,7 @@ pub enum AccountError { HeaderDataIncorrectLength { actual: usize, expected: usize }, // TODO: Make #[source] and remove from msg once HexParseError implements Error trait in // no-std. - #[error("failed to parse hex string into account id: {0}")] + #[error("failed to parse hex string into account ID: {0}")] AccountIdHexParseError(HexParseError), #[error("`{0}` is not a valid account storage mode")] InvalidAccountStorageMode(String), @@ -146,7 +146,7 @@ pub enum AccountDeltaError { }, #[error("inconsistent nonce update: {0}")] InconsistentNonceUpdate(String), - #[error("account id {0} in fungible asset delta is not of type fungible faucet")] + #[error("account ID {0} in fungible asset delta is not of type fungible faucet")] NotAFungibleFaucetId(AccountId), } @@ -171,7 +171,7 @@ pub enum AssetError { original_issuer: AccountId, other_issuer: AccountId, }, - #[error("faucet account id in asset is invalid")] + #[error("faucet account ID in asset is invalid")] InvalidFaucetAccountId(#[source] Box), #[error( "faucet id {0} of type {id_type:?} must be of type {expected_ty:?} for fungible assets", @@ -224,7 +224,7 @@ pub enum NoteError { InconsistentNoteTag(NoteType, u64), #[error("adding fungible asset amounts would exceed maximum allowed amount")] AddFungibleAssetBalanceError(#[source] AssetError), - #[error("note sender is not a valid account id")] + #[error("note sender is not a valid account ID")] NoteSenderInvalidAccountId(#[source] AccountError), #[error("note tag use case {0} must be less than 2^{exp}", exp = NoteTag::MAX_USE_CASE_ID_EXPONENT)] NoteTagUseCaseTooLarge(u16), @@ -327,7 +327,7 @@ pub enum TransactionInputError { InputNoteBlockNotInChainMmr(NoteId), #[error("input note with id {0} was not created in block {1}")] InputNoteNotInBlock(NoteId, u32), - #[error("account id computed from seed is invalid")] + #[error("account ID computed from seed is invalid")] InvalidAccountIdSeed(#[source] AccountError), #[error( "total number of input notes is {0} which exceeds the maximum of {MAX_INPUT_NOTES_PER_TX}" @@ -364,7 +364,7 @@ pub enum ProvenTransactionError { tx_final_hash: Digest, details_hash: Digest, }, - #[error("proven transaction's final account id {tx_account_id} and account details id {details_account_id} must match")] + #[error("proven transaction's final account ID {tx_account_id} and account details id {details_account_id} must match")] AccountIdMismatch { tx_account_id: AccountId, details_account_id: AccountId, diff --git a/objects/src/notes/metadata.rs b/objects/src/notes/metadata.rs index f2c9d20cf..cf0c73457 100644 --- a/objects/src/notes/metadata.rs +++ b/objects/src/notes/metadata.rs @@ -20,17 +20,18 @@ use super::{ /// [`NoteMetadata`] can be encoded into a [`Word`] with the following layout: /// /// ```text -/// 1st felt: [sender_id_hi (64 bits)] -/// 2nd felt: [sender_id_lo (56 bits) | note_type (2 bits) | note_execution_hint_tag (6 bits)] +/// 1st felt: [sender_id_prefix (64 bits)] +/// 2nd felt: [sender_id_suffix (56 bits) | note_type (2 bits) | note_execution_hint_tag (6 bits)] /// 3rd felt: [note_execution_hint_payload (32 bits) | note_tag (32 bits)] /// 4th felt: [aux (64 bits)] /// ``` /// /// The rationale for the above layout is to ensure the validity of each felt: -/// - 1st felt: Is equivalent to the first felt of the account ID so it inherits its validity. -/// - 2nd felt: The second felt of the account ID is designed such that its lower 8 bits can all be -/// set to `1` and still retain its validity due to the anchor epoch in the upper 16 bits always -/// containing at least one `0` bit. +/// - 1st felt: Is equivalent to the prefix of the account ID so it inherits its validity. +/// - 2nd felt: The lower 8 bits of the account ID suffix are `0` by construction, so that they can +/// be overwritten with other data. The suffix is designed such that it retains its felt validity +/// even if all of its lower 8 bits are be set to `1`. This is because the anchor epoch in the +/// upper 16 bits always contains at least one `0` bit. /// - 3rd felt: The note execution hint payload must contain at least one `0` bit in its encoding, /// so the upper 32 bits of the felt will contain at least one `0` bit making the entire felt /// valid. @@ -121,9 +122,9 @@ impl From<&NoteMetadata> for Word { /// The produced layout of the word is documented on the [`NoteMetadata`] type. fn from(metadata: &NoteMetadata) -> Self { let mut elements = Word::default(); - elements[0] = metadata.sender.first_felt(); + elements[0] = metadata.sender.prefix().as_felt(); elements[1] = merge_id_type_and_hint_tag( - metadata.sender.second_felt(), + metadata.sender.suffix(), metadata.note_type, metadata.execution_hint, ); @@ -140,12 +141,12 @@ impl TryFrom for NoteMetadata { /// /// The expected layout of the word is documented on the [`NoteMetadata`] type. fn try_from(elements: Word) -> Result { - let sender_id_first_felt: Felt = elements[0]; + let sender_id_prefix: Felt = elements[0]; - let (sender_id_second_felt, note_type, execution_hint_tag) = + let (sender_id_suffix, note_type, execution_hint_tag) = unmerge_id_type_and_hint_tag(elements[1])?; - let sender = AccountId::try_from([sender_id_first_felt, sender_id_second_felt]) + let sender = AccountId::try_from([sender_id_prefix, sender_id_suffix]) .map_err(NoteError::NoteSenderInvalidAccountId)?; let (execution_hint, note_tag) = @@ -174,25 +175,25 @@ impl Deserializable for NoteMetadata { // HELPER FUNCTIONS // ================================================================================================ -/// Merges the second felt of an [`AccountId`], a [`NoteType`] and the tag of a +/// Merges the suffix of an [`AccountId`], a [`NoteType`] and the tag of a /// [`NoteExecutionHint`] into a single [`Felt`]. /// /// The layout is as follows: /// /// ```text -/// [sender_id_lo (56 bits) | note_type (2 bits) | note_execution_hint_tag (6 bits)] +/// [sender_id_suffix (56 bits) | note_type (2 bits) | note_execution_hint_tag (6 bits)] /// ``` /// /// One of the upper 16 bits is guaranteed to be zero due to the guarantees of the epoch in the -/// account id. +/// account ID. /// -/// Note that `sender_id_lo` is the second felt of the sender's account ID. +/// Note that `sender_id_suffix` is the suffix of the sender's account ID. fn merge_id_type_and_hint_tag( - sender_id_second_felt: Felt, + sender_id_suffix: Felt, note_type: NoteType, note_execution_hint: NoteExecutionHint, ) -> Felt { - let mut merged = sender_id_second_felt.as_int(); + let mut merged = sender_id_suffix.as_int(); let type_bits = note_type as u8; let (tag_bits, _) = note_execution_hint.into_parts(); @@ -208,12 +209,12 @@ fn merge_id_type_and_hint_tag( merged |= (type_bits << 6) as u64; merged |= tag_bits as u64; - // SAFETY: One of the top 16 bits of the second felt (the anchor epoch) is zero by construction + // SAFETY: One of the top 16 bits (the anchor epoch) of the suffix is zero by construction // so the bytes will be a valid felt. Felt::try_from(merged).expect("encoded value should be a valid felt") } -/// Unmerges the given felt into the second felt of an [`AccountId`], a [`NoteType`] and the tag of +/// Unmerges the given felt into the suffix of an [`AccountId`], a [`NoteType`] and the tag of /// a [`NoteExecutionHint`]. fn unmerge_id_type_and_hint_tag(element: Felt) -> Result<(Felt, NoteType, u8), NoteError> { let element = element.as_int(); @@ -230,9 +231,9 @@ fn unmerge_id_type_and_hint_tag(element: Felt) -> Result<(Felt, NoteType, u8), N // SAFETY: The input was a valid felt and and we cleared additional bits and did not set any // bits, so it must still be a valid felt. - let sender_id_second_felt = Felt::try_from(element).expect("element should still be valid"); + let sender_id_suffix = Felt::try_from(element).expect("element should still be valid"); - Ok((sender_id_second_felt, note_type, tag_bits)) + Ok((sender_id_suffix, note_type, tag_bits)) } /// Merges the [`NoteExecutionHint`] payload and a [`NoteTag`] into a single [`Felt`]. @@ -320,7 +321,7 @@ mod tests { // Use the Account ID with the maximum one bits to test if the merge function always // produces valid felts. let sender = AccountId::try_from(ACCOUNT_ID_MAX_ONES).unwrap(); - let sender_second_felt = sender.second_felt(); + let sender_id_suffix = sender.suffix(); let note_type = NoteType::Public; let note_execution_hint = NoteExecutionHint::OnBlockSlot { @@ -330,36 +331,36 @@ mod tests { }; let merged_value = - merge_id_type_and_hint_tag(sender_second_felt, note_type, note_execution_hint); - let (extracted_second_felt, extracted_note_type, extracted_note_execution_hint_tag) = + merge_id_type_and_hint_tag(sender_id_suffix, note_type, note_execution_hint); + let (extracted_suffix, extracted_note_type, extracted_note_execution_hint_tag) = unmerge_id_type_and_hint_tag(merged_value).unwrap(); assert_eq!(note_type, extracted_note_type); assert_eq!(note_execution_hint.into_parts().0, extracted_note_execution_hint_tag); - assert_eq!(sender_second_felt, extracted_second_felt); + assert_eq!(sender_id_suffix, extracted_suffix); let note_type = NoteType::Private; let note_execution_hint = NoteExecutionHint::Always; let merged_value = - merge_id_type_and_hint_tag(sender_second_felt, note_type, note_execution_hint); - let (extracted_second_felt, extracted_note_type, extracted_note_execution_hint_tag) = + merge_id_type_and_hint_tag(sender_id_suffix, note_type, note_execution_hint); + let (extracted_suffix, extracted_note_type, extracted_note_execution_hint_tag) = unmerge_id_type_and_hint_tag(merged_value).unwrap(); assert_eq!(note_type, extracted_note_type); assert_eq!(note_execution_hint.into_parts().0, extracted_note_execution_hint_tag); - assert_eq!(sender_second_felt, extracted_second_felt); + assert_eq!(sender_id_suffix, extracted_suffix); let note_type = NoteType::Private; let note_execution_hint = NoteExecutionHint::None; let merged_value = - merge_id_type_and_hint_tag(sender_second_felt, note_type, note_execution_hint); - let (extracted_second_felt, extracted_note_type, extracted_note_execution_hint_tag) = + merge_id_type_and_hint_tag(sender_id_suffix, note_type, note_execution_hint); + let (extracted_suffix, extracted_note_type, extracted_note_execution_hint_tag) = unmerge_id_type_and_hint_tag(merged_value).unwrap(); assert_eq!(note_type, extracted_note_type); assert_eq!(note_execution_hint.into_parts().0, extracted_note_execution_hint_tag); - assert_eq!(sender_second_felt, extracted_second_felt); + assert_eq!(sender_id_suffix, extracted_suffix); } } diff --git a/objects/src/notes/note_tag.rs b/objects/src/notes/note_tag.rs index eaf8f6a0f..b53e4f90c 100644 --- a/objects/src/notes/note_tag.rs +++ b/objects/src/notes/note_tag.rs @@ -96,11 +96,11 @@ impl NoteTag { ) -> Result { match execution { NoteExecutionMode::Local => { - let first_felt_id: u64 = account_id.first_felt().into(); + let prefix_id: u64 = account_id.prefix().into(); // Shift the high bits of the account ID such that they are layed out as: // [34 zero bits | remaining high bits (30 bits)]. - let high_bits = first_felt_id >> 34; + let high_bits = prefix_id >> 34; // This is equivalent to the following layout, interpreted as a u32: // [2 zero bits | remaining high bits (30 bits)]. @@ -118,11 +118,11 @@ impl NoteTag { if !account_id.is_public() { Err(NoteError::NetworkExecutionRequiresOnChainAccount) } else { - let first_felt_id: u64 = account_id.first_felt().into(); + let prefix_id: u64 = account_id.prefix().into(); // Shift the high bits of the account ID such that they are layed out as: // [34 zero bits | remaining high bits (30 bits)]. - let high_bits = first_felt_id >> 34; + let high_bits = prefix_id >> 34; // This is equivalent to the following layout, interpreted as a u32: // [2 zero bits | remaining high bits (30 bits)]. @@ -354,13 +354,13 @@ mod tests { assert_matches!( NoteTag::from_account_id(off_chain, NoteExecutionMode::Network).unwrap_err(), NoteError::NetworkExecutionRequiresOnChainAccount, - "Tag generation must fail if network execution and off-chain account id are mixed" + "Tag generation must fail if network execution and off-chain account ID are mixed" ) } for on_chain in on_chain_accounts { let tag = NoteTag::from_account_id(on_chain, NoteExecutionMode::Network) - .expect("tag generation must work with network execution and on-chain account id"); + .expect("tag generation must work with network execution and on-chain account ID"); assert!(tag.is_single_target()); assert_eq!(tag.execution_mode(), NoteExecutionMode::Network); @@ -378,7 +378,7 @@ mod tests { for off_chain in off_chain_accounts { let tag = NoteTag::from_account_id(off_chain, NoteExecutionMode::Local) - .expect("tag generation must work with local execution and off-chain account id"); + .expect("tag generation must work with local execution and off-chain account ID"); assert!(!tag.is_single_target()); assert_eq!(tag.execution_mode(), NoteExecutionMode::Local); @@ -392,7 +392,7 @@ mod tests { for on_chain in on_chain_accounts { let tag = NoteTag::from_account_id(on_chain, NoteExecutionMode::Local) - .expect("Tag generation must work with local execution and on-chain account id"); + .expect("Tag generation must work with local execution and on-chain account ID"); assert!(!tag.is_single_target()); assert_eq!(tag.execution_mode(), NoteExecutionMode::Local); diff --git a/objects/src/testing/account_id.rs b/objects/src/testing/account_id.rs index fcd065c52..863ffe7da 100644 --- a/objects/src/testing/account_id.rs +++ b/objects/src/testing/account_id.rs @@ -43,7 +43,7 @@ pub const ACCOUNT_ID_REGULAR_ACCOUNT_UPDATABLE_CODE_ON_CHAIN_2: u128 = account_i 0xeeff_ccdd, ); -// These faucet IDs all have a unique first and second felt. This is to ensure that when they +// These faucet IDs all have a unique prefix and suffix felts. This is to ensure that when they // are used to issue an asset they don't cause us to run into the "multiple leaf" case when // calling std::collections::smt::{set,get} which doesn't support the "multiple leaf" case at // this time. @@ -100,10 +100,10 @@ pub const fn account_id( storage_mode: AccountStorageMode, random: u32, ) -> u128 { - let mut first_felt: u64 = 0; + let mut prefix: u64 = 0; - first_felt |= (account_type as u64) << AccountId::TYPE_SHIFT; - first_felt |= (storage_mode as u64) << AccountId::STORAGE_MODE_SHIFT; + prefix |= (account_type as u64) << AccountId::TYPE_SHIFT; + prefix |= (storage_mode as u64) << AccountId::STORAGE_MODE_SHIFT; // Produce non-trivial IDs by distributing the random value. let random_1st_felt_upper = random & 0xff00_0000; @@ -112,10 +112,10 @@ pub const fn account_id( let random_2nd_felt_lower = random & 0x0000_00ff; // Shift the random part of the ID to start at the most significant end. - first_felt |= (random_1st_felt_upper as u64) << 32; - first_felt |= (random_1st_felt_lower as u64) >> 8; + prefix |= (random_1st_felt_upper as u64) << 32; + prefix |= (random_1st_felt_lower as u64) >> 8; - let mut id = (first_felt as u128) << 64; + let mut id = (prefix as u128) << 64; id |= (random_2nd_felt_upper as u128) << 32; id |= (random_2nd_felt_lower as u128) << 8; diff --git a/objects/src/testing/storage.rs b/objects/src/testing/storage.rs index c6e6f5189..4943d6544 100644 --- a/objects/src/testing/storage.rs +++ b/objects/src/testing/storage.rs @@ -137,7 +137,7 @@ pub enum AccountSeedType { RegularAccountUpdatableCodeOffChain, } -/// Returns the account id and seed for the specified account type. +/// Returns the account ID and seed for the specified account type. /// /// TODO: Not all variants are needed anymore, remove unneeded parts. pub fn generate_account_seed( diff --git a/objects/src/transaction/proven_tx.rs b/objects/src/transaction/proven_tx.rs index 149464f7c..492ecf5f0 100644 --- a/objects/src/transaction/proven_tx.rs +++ b/objects/src/transaction/proven_tx.rs @@ -285,7 +285,7 @@ impl ProvenTransactionBuilder { /// # Errors /// /// An error will be returned if an on-chain account is used without provided on-chain detail. - /// Or if the account details, i.e. account id and final hash, don't match the transaction. + /// Or if the account details, i.e. account ID and final hash, don't match the transaction. pub fn build(self) -> Result { let input_notes = InputNotes::new(self.input_notes).map_err(ProvenTransactionError::InputNotesError)?;