Storage state diffs

info

Check out the Caveats page to avoid common EvmBatchProcessor configuration issues.

addStateDiff(options)

Subscribe to changes in the contract storage. This allows for tracking the contract state changes that are difficult to infer from events or transactions, such as the changes that take into account the output of internal calls. options has the following structure:

{
  // data requests
  address?: string[]
  key?: string[]
  kind?: ('=' | '+' | '*' | '-')[]
  range?: {from: number, to?: number}

  // related data retrieval
  transaction?: boolean
}

The data requests here are:

• address: the set of addresses of contracts to track. Leave undefined or set to [] to subscribe to state changes of all contracts from the whole network.
• key: the set of storage keys that should be tracked. Regular hexadecimal contract storage keys and special keys ('balance', 'code', 'nonce') are allowed. Leave undefined or set to [] to subscribe to all state changes.
• kind: the set of diff kinds that should be tracked. Refer to the StateDiff section of data items documentation for an explanation of the meaning of the permitted values.
• range: the range of blocks within which the storage changes should be tracked.

Enabling the transaction flag will cause the processor to retrieve the transaction that gave rise to each state change and add it to the transactions iterable of block data.

Note that state diffs can also be requested by the addTransaction() method as related data.

Selection of the exact data to be retrieved for each state diff item and its optional parent transaction is done with the setFields() method documented on the Field selection page. Unlike other data items, state diffs do not have any fields that can be enabled, but some can be disabled for improved sync performance.