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).

Full and Partial State Patches

The presence of the code in a patch signals if the patch is a full state or partial state patch. A full state patch must be converted into an Account object, while a partial state patch must be applied to an existing Account. Because a full state patch reconstructs the account from empty storage, its storage patch may only create slots, never update or remove them; AccountPatch::new enforces this. A full state patch can only be the base of a merge, never the incoming patch (see its docs for the permutation rules).

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 AccountCode for new accounts and None for others, with the same semantics as in AccountDelta.

Implementations

impl AccountPatch

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

Returns a new AccountPatch instantiated from the provided components.

final_nonce must be Some(non_zero_nonce) if storage or vault 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) -> AccountPatch

Returns an empty patch for the provided account ID.

pub fn merge(&mut self, other: AccountPatch) -> 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.

Both patches must apply to the same account, and other.final_nonce must be exactly one greater than self.final_nonce whenever both are set. The exact +1 requirement reflects the tx kernel invariants that (a) a state-changing transaction must increment the nonce, and (b) the nonce can be incremented at most once per transaction. As a consequence the patch of the next transaction always lands at self.final_nonce + 1. The same nonce in both patches represents a fork and a nonce delta larger than 1 means a missed transaction.

Full and Partial State

The patches’ full/partial state determines whether the merge is allowed. In short, the incoming patch (other) must never be a full state patch. In more detail:

• full_state + partial_state: allowed. The full state (account-creation) patch is the base and later partial patches layer on top of it.
• partial_state + partial_state: allowed. Both are incremental updates.
• partial_state + full_state: disallowed. A full state patch describes the account’s initial state, so it cannot follow an earlier (partial) patch.
• full_state + full_state: disallowed. An account is created once, so two creation patches cannot both apply.

Empty patches are neutral and handled before this rule: 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 exactly one greater than the nonce in self.
• the incoming patch (other) is a full state patch (see permutations above).
• 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) -> Option<&AccountCode>

Returns a reference to the account code of this patch, if present.

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

Returns true if this patch is a “full state” patch, false otherwise, i.e. if it is a “partial state” patch.

See the type-level docs for more on this distinction.

pub fn is_empty(&self) -> bool

Returns true if this account patch does not contain any vault or storage 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. Whenever sorting is expected, it is that of a Word.

• Append [[domain = 2, 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 domain = 2 identifies the header as the start of an account patch commitment (distinguishing it from a delta commitment, which uses domain = 1).
• 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 = 4, num_changed_assets, 0, 0], 0, 0, 0, 0], where num_changed_assets is the number of assets that were appended. Note that this is a distinct domain from the delta asset domain (3), so an asset delta and an asset patch can never produce 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 = 5, 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 = 6, 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.

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.

Trait Implementations

impl Clone for AccountPatch

fn clone(&self) -> AccountPatch

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<(), Error>

Formats the value using the given formatter.

impl Deserializable for AccountPatch

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

where R: ByteReader,

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: &AccountPatch) -> bool

Equality operator ==.

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

Inequality operator !=.

impl SequentialCommit for AccountPatch

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.

fn to_commitment(&self) -> Self::Commitment

Computes the commitment to the object.

impl Serializable for AccountPatch

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

where W: ByteWriter,

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<&AccountPatch> for Account

fn try_from( patch: &AccountPatch, ) -> Result<Account, <Account as TryFrom<&AccountPatch>>::Error>

Converts an AccountPatch into an Account.

Conceptually, this applies the patch onto an empty account. Only patches that fully describe an account (i.e. carry account code and a final nonce) can be converted; see AccountPatch for details.

Errors

Returns an error if:

• The patch does not carry account code or a final nonce.
• Applying the vault patch to an empty vault fails.
• Applying the storage patch to empty storage fails.

type Error = AccountError

The type returned in the event of a conversion error.

impl TryFrom<Account> for AccountPatch

fn try_from( account: Account, ) -> Result<AccountPatch, <AccountPatch as TryFrom<Account>>::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.