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

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: AccountStorageDelta, vault: AccountVaultDelta, nonce_delta: Felt, ) -> Result<Self, AccountDeltaError>

Returns new AccountDelta instantiated from the provided components.

Errors

• Returns an error if storage or vault were updated, but the nonce_delta is 0.

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

Merge another AccountDelta into this one.

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

Returns a mutable reference to the account vault delta.

pub fn with_code(self, code: Option<AccountCode>) -> Self

Sets the AccountCode of the 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) -> &AccountStorageDelta

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, ) -> (AccountStorageDelta, AccountVaultDelta, Option<AccountCode>, Felt)

Converts this storage delta into individual delta components.

pub fn to_commitment(&self) -> Word

Computes the commitment to the account delta.

Computation

The delta 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 LexicographicWord. The WORD layout is in memory-order.

• Append [[nonce_delta, 0, account_id_suffix, account_id_prefix], EMPTY_WORD], where account_id_{prefix,suffix} are the prefix and suffix felts of the native account id and nonce_delta is the value by which the nonce was incremented.
• Fungible Asset Delta
  • For each updated fungible asset, sorted by its vault key, whose amount delta is non-zero:
    • Append [domain = 1, was_added, 0, 0].
    • Append [amount, 0, faucet_id_suffix, faucet_id_prefix] where amount is the delta by which the fungible asset’s amount has changed and was_added is a boolean flag indicating whether the amount was added (1) or subtracted (0).
• Non-Fungible Asset Delta
  • For each updated non-fungible asset, sorted by its vault key:
    • Append [domain = 1, was_added, 0, 0] where was_added is a boolean flag indicating whether the asset was added (1) or removed (0). Note that the domain is the same for assets since faucet_id_prefix is at the same position in the layout for both assets, and, by design, it is never the same for fungible and non-fungible assets.
    • Append [hash0, hash1, hash2, faucet_id_prefix], i.e. the non-fungible asset.
• Storage Slots are sorted by slot ID and are iterated in this order. For each slot whose value has changed, depending on the slot type:
  • Value Slot
    • Append [[domain = 2, 0, slot_id_suffix, slot_id_prefix], NEW_VALUE] where NEW_VALUE is the new value of the slot and slot_id_{suffix, prefix} is the identifier 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].
    • Append [[domain = 3, num_changed_entries, slot_id_suffix, slot_id_prefix], 0, 0, 0, 0], where slot_id_{suffix, prefix} are the slot identifiers and num_changed_entries is the number of changed key-value pairs in the map.
      • For partial state deltas, the map header must only be included if num_changed_entries is not zero.
      • For full state deltas, the map header must always be included.

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 storage slots of the account, even if the storage slots have a 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 contexts (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 only changed value slots are included in the delta, 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,
  [/* no fungible asset delta */],
  [[domain = 1, was_added = 0, 0, 0], NON_FUNGIBLE_ASSET],
  [/* no storage delta */]
]

[
  ID_AND_NONCE, EMPTY_WORD,
  [/* no fungible asset delta */],
  [/* no non-fungible asset delta */],
  [[domain = 2, 0, slot_id_suffix = 0, slot_id_prefix = 0], NEW_VALUE]
]

NEW_VALUE is user-controllable so it can be crafted to match NON_FUNGIBLE_ASSET. The domain separator is then the only value that differentiates these two deltas. This shows the importance of placing the domain separators in the same index within each word’s layout which makes it easy to see that this value cannot be crafted to be the same.

Number of Changed Entries

As an example for ambiguity, consider these two deltas:

[
  ID_AND_NONCE, EMPTY_WORD,
  [/* no fungible asset delta */],
  [/* no non-fungible asset delta */],
  [domain = 3, num_changed_entries = 0, slot_id_suffix = 20, slot_id_prefix = 21, 0, 0, 0, 0]
  [domain = 3, num_changed_entries = 0, slot_id_suffix = 42, slot_id_prefix = 43, 0, 0, 0, 0]
]

[
  ID_AND_NONCE, EMPTY_WORD,
  [/* no fungible asset delta */],
  [/* no non-fungible asset delta */],
  [KEY0, VALUE0],
  [domain = 3, num_changed_entries = 1, slot_id_suffix = 42, slot_id_prefix = 43, 0, 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 added to a new account. 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 an empty map or not being present 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

Formats the value using the given formatter.

impl Deserializable for AccountDelta

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

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

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

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

impl PartialEq for AccountDelta

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

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

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

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

impl 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: ByteWriter>(&self, target: &mut W)

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

fn get_size_hint(&self) -> usize

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

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

Serializes self into a vector of bytes.

impl TryFrom<&AccountDelta> for Account

fn try_from(delta: &AccountDelta) -> Result<Self, Self::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 delta 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<Self, Self::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.

impl Eq for AccountDelta

impl StructuralPartialEq for AccountDelta