Struct AccountPatch 

pub struct AccountPatch { /* private fields */ }

An AccountPatch describes the new absolute state of an account after one or more transactions, in contrast to an AccountDelta, which describes the relative change.

For example, where a delta might say “remove 50 USDC from the vault”, a patch says “the new USDC balance is 100”. This means a patch can be applied to compute the new account state without loading the previous state and without invoking any custom asset compose logic (e.g. merge/split procedures defined by the issuing faucet).

The patch represents updates to the account as follows:

• storage: an AccountStoragePatch containing the new values of changed storage slots and map entries. Storage updates are already absolute per changed entry, so no dedicated patch type is required for storage.
• vault: an AccountVaultPatch containing the new values of changed vault entries.
• nonce: the new (absolute) nonce of the account, in contrast to AccountDelta::nonce_delta which stores the increment.
• code: an AccountCodePatch containing the code of a new or upgraded account.

Implementations

impl AccountPatch

pub fn new( account_id: AccountId, storage: AccountStoragePatch, vault: AccountVaultPatch, code: AccountCodePatch, final_nonce: Option<Felt>, ) -> Result<Self, AccountPatchError>

Returns a new AccountPatch instantiated from the provided components.

final_nonce must be Some(non_zero_nonce) if storage, vault or code contain any updates, and can be None only for empty patches.

Errors

Returns an error if:

• final_nonce is Some(Felt::ZERO). The tx kernel guarantees that an updated nonce is at least one, so a zero nonce is never a valid post-tx-state. Empty patches must be constructed with None instead.
• storage or vault contain updates or code is present but final_nonce is None. The tx kernel mandates that the nonce is incremented whenever account state changes.
• final_nonce is 1 but code is not Some. Such a patch describes a new account and should be convertible into a full Account, so account code is required.

pub fn empty(account_id: AccountId) -> Self

Returns an empty patch for the provided account ID.

pub fn merge(&mut self, other: Self) -> Result<(), AccountPatchError>

Merges the other AccountPatch into this one with patch semantics: entries present in other overwrite their counterparts in self, and other.final_nonce, if present, becomes the new final nonce.

The merge is not commutative: self must describe the earlier and other the later state, so a.merge(b) and b.merge(a) generally give different results.

Both patches must apply to the same account, and other.final_nonce must be greater than self.final_nonce whenever both are set. other can be an aggregate of multiple transactions (e.g. of a batch), so the nonce can grow by more than one. Continuity of the merged patches is not and cannot be checked here.

If other carries code, it replaces the code of self, since other describes the later state.

Empty patches are neutral: merging into an empty self adopts other, and merging an empty other is a no-op.

Errors

Returns an error if:

• the two patches apply to different accounts.
• both patches carry a final nonce and the nonce in other is not greater than the nonce in self.
• a storage slot is used as different slot types in the two patches.

pub fn id(&self) -> AccountId

Returns the account ID to which this patch applies.

pub fn storage(&self) -> &AccountStoragePatch

Returns the storage updates of this patch.

pub fn vault(&self) -> &AccountVaultPatch

Returns the vault updates of this patch.

pub fn code(&self) -> &AccountCodePatch

Returns the code updates of this patch.

pub fn final_nonce(&self) -> Option<Felt>

Returns the new (absolute) nonce of the account after this patch is applied, or None if the nonce wasn’t updated.

pub fn is_empty(&self) -> bool

Returns true if this account patch does not contain any vault, storage or code updates and the nonce wasn’t updated.

pub fn to_commitment(&self) -> Word

Computes the commitment to the account patch.

This is very similar to AccountDelta::to_commitment. See its docs for the rationale, security aspects, and other details. The only differences between these are:

• the patch includes the new nonce rather than the nonce delta.
• The patch includes the new absolute asset values (AccountVaultPatch) while the delta includes the relative asset changes (AccountVaultDelta).

Computation

The patch commitment is a sequential hash over a vector of field elements which starts out empty and is appended to in the following way. If no asset, storage or code elements were appended, the commitment is defined as the empty word. Whenever sorting is expected, it is that of a Word. The hash is domain-separated by the patch’s DOMAIN, which is placed in the capacity word of the hasher. This is what distinguishes a patch commitment from a delta commitment, whose headers are otherwise identically shaped.

• Append [[version = 1, final_nonce, account_id_suffix, account_id_prefix], EMPTY_WORD], where account_id_{prefix,suffix} are the prefix and suffix felts of the native account id, final_nonce is the new nonce of the account, and version is the version of this layout.
• Asset Patch
  • For each asset whose value has changed compared to the initial state of the transaction, including if it was removed, sorted by its asset ID:
    • Append [ASSET_ID, ASSET_VALUE_OR_EMPTY_WORD] which are the key and either the value of the asset (for updates) or the empty word (for removals).
    • Append [[domain = 1, num_changed_assets, 0, 0], 0, 0, 0, 0], where num_changed_assets is the number of assets that were appended. This is the same domain as the delta asset section uses, since the capacity domain already prevents an asset delta and an asset patch from producing the same commitment.
• Storage Slots are sorted by slot ID and are iterated in this order. patch_op is the StoragePatchOperation of the slot patch and slot_id_{suffix, prefix} is the identifier of the slot. For each slot, depending on its slot type:
  • Value Slot
    • Append [[domain = 2, patch_op, slot_id_suffix, slot_id_prefix], NEW_VALUE] where NEW_VALUE is the new value of the slot.
  • Map Slot
    • For each key-value pair, sorted by key, whose new value is different from the previous value in the map:
      • Append [KEY, NEW_VALUE].
    • The map trailer is constructed as [[domain = 3, patch_op, slot_id_suffix, slot_id_prefix], [num_changed_entries, 0, 0, 0]], where num_changed_entries is the number of key-value pairs appended above. Whether the trailer is included depends on patch_op:
      • For StoragePatchOperation::Create, the trailer is always included, since the slot’s creation must be committed to even when the map is created empty (num_changed_entries == 0).
      • For StoragePatchOperation::Update, the trailer is included only if num_changed_entries != 0. An update that changes no entries is a no-op and is omitted entirely.
      • For StoragePatchOperation::Remove, the trailer is always included with num_changed_entries set to zero, since the number of removed entries is unknown.
• If the account is new or its code was upgraded, append [[domain = 4, 0, 0, 0], CODE_COMMITMENT], where CODE_COMMITMENT is the commitment of the account code.

Headers for storage map slots and asset patches are appended rather than prepended since the tx kernel cannot efficiently get the number of changed entries before the iteration.

pub fn try_to_new_account(&self) -> Result<Account, AccountError>

Returns the new Account created by this patch.

Conceptually, this applies the patch onto an empty account.

Warning

This method only results in a semantically correct account if the caller knows that the patch is from an account-creating transaction itself or resulted from merging patches onto the account-creating patch. The method can also succeed on patches coming from code-upgrading transactions, but the result will not correspond to a meaningful account state. Prefer applying the patch onto the new account against which the account-creating transaction was executed.

Errors

Returns an error if:

• the patch does not carry account code or a final nonce.
• the storage patch contains an Update or Remove operation, which cannot be applied to the empty storage of a new account.
• applying the vault patch to an empty vault fails.
• applying the storage patch to empty storage fails.
• Account::new fails on the resulting components.

Trait Implementations

impl Clone for AccountPatch

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AccountPatch

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

Formats the value using the given formatter.

impl Deserializable for AccountPatch

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

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

fn min_serialized_size() -> usize

Returns the minimum serialized size for one instance of this type.

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

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

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

Deserializes Self from bytes with a byte budget limit.

impl Eq for AccountPatch

impl PartialEq for AccountPatch

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

Equality operator ==.

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

Inequality operator !=.

impl SequentialCommit for AccountPatch

fn to_commitment(&self) -> Word

Computes the commitment to the patch, domain-separated by its DOMAIN.

See AccountPatch::to_commitment() for more details.

fn to_elements(&self) -> Vec<Felt>

Reduces the patch to a sequence of field elements.

See AccountPatch::to_commitment() for more details.

type Commitment = Word

A type of the commitment which must be derivable from Word.

impl Serializable for AccountPatch

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

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

fn get_size_hint(&self) -> usize

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

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

Serializes self into a vector of bytes.

impl StructuralPartialEq for AccountPatch

impl TryFrom<Account> for AccountPatch

fn try_from(account: Account) -> Result<Self, Self::Error>

Converts an Account into an AccountPatch.

Errors

Returns an error if:

• the account has a seed. Accounts with seeds have a nonce of 0. Representing such accounts as patches is not possible because patches with a non-empty state change need a final_nonce greater than 0.

type Error = AccountError

The type returned in the event of a conversion error.