Struct AccountDelta

pub struct AccountDelta { /* private fields */ }

AccountDelta stores the differences between two account states.

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.

TODO: add ability to trace account code updates.

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 was either not updated or set to 0.

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

Merge another AccountDelta into this one.

pub fn is_empty(&self) -> bool

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

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 into_parts(self) -> (AccountStorageDelta, AccountVaultDelta, Felt)

Converts this storage delta into individual delta components.

pub fn commitment(&self) -> Digest

Computes the commitment to the account delta.

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 link map key. 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 - for each slot whose value has changed, depending on the slot type:
  • Value Slot
    • Append [[domain = 2, slot_idx, 0, 0], NEW_VALUE] where NEW_VALUE is the new value of the slot and slot_idx is the index 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, slot_idx, num_changed_entries, 0], 0, 0, 0, 0], except if num_changed_entries is 0, where slot_idx is the index of the slot and num_changed_entries is the number of changed key-value pairs in the map.

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.

Security

The general concern with the commitment is that two deltas must never has 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 index and number of changed entries. Since only changed slots are included, the number of changed entries is never zero.
  • Two distinct storage map slots use the same domain but are disambiguated due to inclusion of the slot index.

Domain Separators

As an example for ambiguity, consider these two deltas:

[
  ID_AND_NONCE, EMPTY_WORD,
  [/* no fungible asset delta */],
  [[domain = 1, was_added = 1, 0, 0], NON_FUNGIBLE_ASSET],
  [/* no storage delta */]
]

[
  ID_AND_NONCE, EMPTY_WORD,
  [/* no fungible asset delta */],
  [/* no non-fungible asset delta */],
  [[domain = 2, slot_idx = 1, 0, 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:

[
  EMPTY_WORD, ID_AND_NONCE,
  [/* no fungible asset delta */],
  [[domain = 1, was_added = 1, 0, 0], NON_FUNGIBLE_ASSET],
  [/* no storage delta */],
]

[
   ID_AND_NONCE, EMPTY_WORD,
  [/* no fungible asset delta */],
  [/* no non-fungible asset delta */],
  [KEY0, VALUE0],
  [KEY1, VALUE1],
  [domain = 3, slot_idx = 0, num_changed_entries = 2, 0, 0, 0, 0, 0]
]

The keys and values of map slots are user-controllable so KEY0 and VALUE0 can be crafted to match NON_FUNGIBLE_ASSET and its metadata. Including the header of the map slot additionally hashes the map domain into the delta, but if the header was included whenever any value in the map has changed, it would cause ambiguity about whether KEY0/VALUE0 are in fact map keys or a non-fungible asset (or any asset or a value storage slot more generally). Including num_changed_entries disambiguates this situation, by ensuring that the delta commitment is different when, e.g. 1) a non-fungible asset and one key-value pair have changed and 2) when two key-value pairs have changed.

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 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 Eq for AccountDelta

impl StructuralPartialEq for AccountDelta