> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Storage state diffs

> Track EVM storage, balance, code and nonce changes with addStateDiff().

<Tip>
  State diffs are [available](/en/data/evm) from [SQD Network](/en/network) Portals on the same basis as all other data served there: for free, including real-time blocks. There are no surcharges for traces or state diffs.
</Tip>

<h4 id="add-state-diff">
  `addStateDiff(options)`
</h4>

Subscribe to changes in the [contract storage](https://coinsbench.com/solidity-layout-and-access-of-storage-variables-simply-explained-1ce964d7c738). 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:

```typescript theme={"system"}
{
  // item filters
  where?: {
    address?: string[]
    key?: string[]
    kind?: ('=' | '+' | '*' | '-')[]
  }

  // related data retrieval
  include?: {
    transaction?: boolean
  }

  // block range override
  range?: {from: number, to?: number}
}
```

Item filters (`where`):

* `address`: the set of addresses of contracts to track. Omit 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](./field-selection#state-diffs) (`'balance'`, `'code'`, `'nonce'`) are allowed. Omit to subscribe to all state changes.
* `kind`: the set of diff kinds that should be tracked. Refer to the [state diffs section](./field-selection#state-diffs) of the field selection page for an explanation of the meaning of the permitted values.

<Warning>
  Filter values are matched as exact strings by the Portal — always pass addresses and storage keys as lowercase hex strings. `@subsquid/evm-stream` does not normalize the case for you.
</Warning>

Enabling the `transaction` flag of `include` will cause the data source to retrieve the transaction that gave rise to each state change and add it to the `transactions` iterable of the [block data](./context-interfaces). Call `augmentBlock()` from `@subsquid/evm-objects` to navigate from a diff to its transaction conveniently (`stateDiff.transaction`, `stateDiff.getTransaction()`).

`range` overrides the global [`setBlockRange()`](../evm-stream) for this particular request.

Note that state diffs can also be requested by the [`addTransaction()`](./transactions) method as related data.

Selection of the exact fields to be retrieved for each state diff item and its optional parent transaction is done with the `setFields()` method documented on the [Field selection](./field-selection) page. There are no default fields: request `kind`, `prev` and/or `next` explicitly if your handler reads them.

## Example

Track additions and changes to the storage of the DAI contract, fetching the old and the new values and the hash of the responsible transaction:

```ts theme={"system"}
import {DataSourceBuilder} from '@subsquid/evm-stream'

const dataSource = new DataSourceBuilder()
  .setPortal('https://portal.sqd.dev/datasets/ethereum-mainnet')
  .addStateDiff({
    where: {
      address: ['0x6b175474e89094c44da98b954eedeac495271d0f'], // DAI
      kind: ['+', '*']
    },
    include: {
      transaction: true
    }
  })
  .setFields({
    stateDiff: {
      kind: true,
      prev: true,
      next: true
    },
    transaction: {
      hash: true
    }
  })
  .build()
```