Struct AccountDelta 

pub struct AccountDelta { /* private fields */ }

The AccountDelta stores the differences between two account states, which can result from one or more transaction.

The differences are represented as follows:

• storage: an AccountStoragePatch that contains the changes to the account storage.
• vault: an AccountVaultDelta object that contains the changes to the account vault.
• nonce: if the nonce of the account has changed, the delta of the nonce is stored, i.e. the value by which the nonce increased.
• code: an AccountCode for new accounts and None for others.

The presence of the code in a delta signals if the delta is a full state or partial state delta. A full state delta must be converted into an Account object, while a partial state delta must be applied to an existing Account. Because a full state delta reconstructs the account from empty storage, its storage patch may only create slots, never update or remove them; AccountDelta::new enforces this.

TODO(code_upgrades): The ability to track account code updates is an outstanding feature. For that reason, the account code is not considered as part of the “nonce must be incremented if state changed” check.

Implementations

impl AccountDelta

pub fn new( account_id: AccountId, storage: AccountStoragePatch, vault: AccountVaultDelta, code: Option<AccountCode>, nonce_delta: Felt, ) -> Result<AccountDelta, AccountDeltaError>

Returns new AccountDelta instantiated from the provided components.

code is Some for a full state delta (a new account) and None otherwise.

Errors

• Returns an error if storage or vault were updated, but the nonce_delta is 0.
• Returns an error if code is provided but the storage patch contains an Update or Remove operation. A full state delta must reconstruct the account from empty storage, so it may only create slots.

pub fn vault_mut(&mut self) -> &mut AccountVaultDelta

Returns a mutable reference to the account vault delta.

pub fn is_empty(&self) -> bool

Returns true if this account delta does not contain any vault, storage or nonce updates.

pub fn is_full_state(&self) -> bool

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

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

pub fn storage(&self) -> &AccountStoragePatch

Returns storage updates for this account delta.

pub fn vault(&self) -> &AccountVaultDelta

Returns vault updates for this account delta.

pub fn nonce_delta(&self) -> Felt

Returns the amount by which the nonce was incremented.

pub fn id(&self) -> AccountId

Returns the account ID to which this delta applies.

pub fn code(&self) -> Option<&AccountCode>

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

pub fn into_parts( self, ) -> (AccountStoragePatch, AccountVaultDelta, Option<AccountCode>, Felt)

Converts this delta into its individual components.

pub fn to_commitment(&self) -> Word

Computes the commitment to the account delta.

Computation

The delta 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 = 1, nonce_delta, account_id_suffix, account_id_prefix], EMPTY_WORD], where account_id_{prefix,suffix} are the prefix and suffix felts of the native account id, nonce_delta is the value by which the nonce was incremented, and domain = 1 identifies the header as the start of an account delta commitment.
• Asset Delta
  • For each added asset, sorted by its asset ID:
    • Append [ASSET_ID, ASSET_VALUE].
  • Append [domain = 3, delta_op = 1, num_added_assets, 0] if num_added_assets != 0 where num_added_assets is the number of added assets and delta_op is set to 1 indicating asset addition.
  • For each removed asset, sorted by its asset ID:
    • Append [ASSET_ID, ASSET_VALUE].
  • Append [domain = 3, delta_op = 2, num_removed_assets, 0] if num_removed_assets != 0 where num_removed_assets is the number of removed assets and delta_op is set to 2 indicating asset removal.
  • Note that the domain is the same independent of asset addition or removal, since the delta_op sufficiently distinguishes the two domains.
• 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.

Rationale

The rationale for this layout is that hashing in the VM should be as efficient as possible and minimize the number of branches to be as efficient as possible. Every high-level section in this bullet point list should add an even number of words since the hasher operates on double words. In the VM, each permutation is done immediately, so adding an uneven number of words in a given step will result in more difficulty in the MASM implementation.

New Accounts

The delta for new accounts (a full state delta) must commit to all the created storage slots of the account, even if these slots contain the default value (e.g. the empty word for value slots or an empty storage map). This ensures the full state delta commits to the exact storage slots that are contained in the account.

Security

The general concern with the commitment is that two distinct deltas must never hash to the same commitment. E.g. a commitment of a delta that changes a key-value pair in a storage map slot should be different from a delta that adds a non-fungible asset to the vault. If not, a delta can be crafted in the VM that sets a map key but a malicious actor crafts a delta outside the VM that adds a non-fungible asset. To prevent that, a couple of measures are taken.

• Because multiple unrelated domains (e.g. vaults and storage slots) are hashed in the same hasher, domain separators are used to disambiguate. For each changed asset and each changed slot in the delta, a domain separator is hashed into the delta. The domain separator is always at the same index in each layout so it cannot be maliciously crafted (see below for an example).
• Storage value slots:
  • since value slots are only included in the patch if their value has changed when the operation is Update, there is no ambiguity between a value slot being set to EMPTY_WORD and its value being unchanged.
• Storage map slots:
  • Map slots append a header which summarizes the changes in the slot, in particular the slot ID and number of changed entries.
  • Two distinct storage map slots use the same domain but are disambiguated due to inclusion of the slot ID.

Domain Separators

As an example for ambiguity, consider these two deltas:

[
  ID_AND_NONCE, EMPTY_WORD,
  [ASSET_ID, ASSET_VALUE],
  [[domain = 3, delta_op = 1, num_added_assets = 1, 0], EMPTY_WORD],
  [/* no removed assets delta */],
  [/* no storage patch */]
]

[
  ID_AND_NONCE, EMPTY_WORD,
  [/* no asset delta */],
  [[domain = 5, patch_op, slot_id_suffix0, slot_id_prefix0], NEW_VALUE]
  [[domain = 5, patch_op, slot_id_suffix1, slot_id_prefix1], NEW_VALUE]
]

• NEW_VALUE is user-controlled and can be crafted to match ASSET_VALUE or EMPTY_WORD.
• Slot IDs are user-controlled and can be crafted to match the two most significant elements in the asset ID or num_added_assets and the fixed 0.
• This leaves only the domain separator and the patch_op to differentiate these two deltas.

The delta and patch headers further use distinct domain separators (1 and 2 respectively), so a delta and a patch with otherwise identical bodies can never collide.

Number of Changed Entries

As an example for ambiguity, consider these two deltas:

[
  ID_AND_NONCE, EMPTY_WORD,
  [/* no asset delta */],
  [domain = 6, patch_op, slot_id_suffix = 20, slot_id_prefix = 21, num_changed_entries = 0, 0, 0, 0]
  [domain = 6, patch_op, slot_id_suffix = 42, slot_id_prefix = 43, num_changed_entries = 0, 0, 0, 0]
]

[
  ID_AND_NONCE, EMPTY_WORD,
  [/* no asset delta */],
  [KEY0, VALUE0],
  [domain = 6, patch_op, slot_id_suffix = 42, slot_id_prefix = 43, num_changed_entries = 1, 0, 0, 0]
]

The keys and values of map slots are user-controllable so KEY0 and VALUE0 could be crafted to match the first map header in the first delta. So, without having num_changed_entries included in the commitment, these deltas would be ambiguous. A delta with two empty maps could have the same commitment as a delta with one map entry where one key-value pair has changed.

New Accounts

The number of changed entries of a storage map can be validly zero when an empty storage map is created in account (e.g. at account creation time). In such cases, the number of changed key-value pairs is 0, but the map must still be committed to, in order to differentiate between a slot being created as an empty map or not being created at all.

Trait Implementations

impl Clone for AccountDelta

fn clone(&self) -> AccountDelta

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AccountDelta

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

Formats the value using the given formatter.

impl Deserializable for AccountDelta

fn read_from<R>(source: &mut R) -> Result<AccountDelta, 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 AccountDelta

impl PartialEq for AccountDelta

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

Equality operator ==.

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

Inequality operator !=.

impl SequentialCommit for AccountDelta

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

Reduces the delta to a sequence of field elements.

See AccountDelta::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 AccountDelta

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 AccountDelta

impl TryFrom<&AccountDelta> for Account

fn try_from( delta: &AccountDelta, ) -> Result<Account, <Account as TryFrom<&AccountDelta>>::Error>

Converts an AccountDelta into an Account.

Conceptually, this applies the delta onto an empty account.

Errors

Returns an error if:

• If the delta is not a full state delta. See AccountDelta for details.
• If any vault delta operation removes an asset.
• If any vault delta operation adds an asset that would overflow the maximum representable amount.
• If any storage patch update violates account storage constraints.

type Error = AccountError

The type returned in the event of a conversion error.

impl TryFrom<Account> for AccountDelta

fn try_from( account: Account, ) -> Result<AccountDelta, <AccountDelta as TryFrom<Account>>::Error>

Converts an Account into an AccountDelta.

Errors

Returns an error if:

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

type Error = AccountError

The type returned in the event of a conversion error.