State Tracking

RPC methods for recording on-chain state over time. Each tracked item is a piece of state — a balance, an ERC20 holding, a storage slot, or the result of a view function — that the Stagenet snapshots as it runs. The recorded history shows up in the corresponding Workspace.

These methods back the contract.dev track CLI.

Tracked item shape

Every tracked item has these fields:

Field	Type	Description
`address`	`string`	The address the item is anchored to
`name`	`string`	Display name
`type`	`string`	One of `native-token-balance`, `erc20-balance`, `function-result`, `storage-variable`
`functionAbi`	`string?`	For `erc20-balance` and `function-result`: a JSON ABI fragment or human-readable signature
`functionArgs`	`string?`	JSON-encoded arg array. For `erc20-balance`: `["<holder>"]`. For `storage-variable`: `["<slot>"]` (32-byte hex).
`functionOutputPath`	`string?`	Dot-separated path into a struct/tuple return value (e.g. `info.balance`)
`recordTrigger`	`string?`	One of `every-tx` (default), `every-n-blocks`, `cron`
`trackingFrequency`	`number?`	Block count (for `every-n-blocks`) or seconds (for `cron`). Required for those triggers.
`tags`	`string[]?`	Free-form tags for filtering

`dev_addTrackedData`

Create a tracked item. The Stagenet records its initial value on the next block, then again on the configured trigger.

Parameter	Type	Description
`item`	`object`	A tracked item, as described above

Returns:


{
  "id": "ckxyz...",
  "address": "0x1111111111111111111111111111111111111111",
  "type": "native-token-balance",
  "name": "treasury ETH"
}

Example — track a native balance:


curl -X POST <YOUR_STAGENET_RPC_URL> \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "dev_addTrackedData",
    "params": [{
      "type": "native-token-balance",
      "address": "0x1111111111111111111111111111111111111111",
      "name": "treasury ETH"
    }]
  }'

Example — track an ERC20 balance with a periodic sample:


curl -X POST <YOUR_STAGENET_RPC_URL> \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "dev_addTrackedData",
    "params": [{
      "type": "erc20-balance",
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "name": "treasury USDC",
      "functionAbi": "function balanceOf(address) view returns (uint256)",
      "functionArgs": "[\"0x1111111111111111111111111111111111111111\"]",
      "recordTrigger": "every-n-blocks",
      "trackingFrequency": 100,
      "tags": ["treasury"]
    }]
  }'

`dev_removeTrackedData`

Delete a tracked item and its recorded history.

Parameter	Type	Description
`id`	`string`	The tracked item id returned by `dev_addTrackedData`

Returns:


{ "id": "ckxyz...", "removed": true }

`dev_updateTrackedData`

Update an existing tracked item.

Parameter	Type	Description
`id`	`string`	The tracked item id
`updates`	`object`	Any subset of the fields in the tracked item shape

Returns the updated tracked item.

Changing a “semantic” field — type, address, functionAbi, functionArgs, or functionOutputPath — clears the item’s recorded history, since old and new values would no longer be comparable.


curl -X POST <YOUR_STAGENET_RPC_URL> \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "dev_updateTrackedData",
    "params": ["ckxyz...", { "name": "treasury USDC (renamed)", "tags": ["treasury", "monitoring"] }]
  }'

`dev_getTrackedData`

List tracked items. The filter argument is optional:

Field	Type	Description
`address`	`string?`	Return only items anchored to this address
`tag`	`string?`	Return only items with this tag
`withValues`	`boolean?`	Attach `latestValue` to each item

Returns an array of tracked items. When withValues is set, each item includes a latestValue field:


{
  "id": "ckxyz...",
  "type": "native-token-balance",
  "address": "0x1111...",
  "name": "treasury ETH",
  "tags": ["treasury"],
  "latestValue": {
    "value": "1000000000000000000",
    "blockNumber": 123,
    "timestamp": "2025-04-12T14:32:01.000Z"
  }
}


curl -X POST <YOUR_STAGENET_RPC_URL> \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "dev_getTrackedData",
    "params": [{ "withValues": true }]
  }'

`dev_getTrackedDataValues`

Read the recorded history of a tracked item.

Parameter	Type	Description
`id`	`string`	The tracked item id
`options`	`object?`	See below

Options:

Field	Type	Description
`period`	`string?`	One of `10min`, `1h`, `1d`, `1w`, `1m`. Restricts to a trailing time window.
`maxBlockNumber`	`number?`	Return values at or before this block, in ascending order.

Returns:


{
  "values": [
    { "value": "999000000000000000000", "blockNumber": 110, "timestamp": "2025-04-12T14:30:00.000Z", "txHash": "0x..." },
    { "value": "1000000000000000000000", "blockNumber": 123, "timestamp": "2025-04-12T14:32:01.000Z", "txHash": "0x..." }
  ],
  "anchor": { "value": "...", "blockNumber": 100, "timestamp": "..." },
  "periodStart": "2025-04-12T13:32:01.000Z",
  "periodEnd": "2025-04-12T14:32:01.000Z"
}

When period is set, anchor is the value immediately before the window — useful for drawing a chart that starts with the right baseline.


curl -X POST <YOUR_STAGENET_RPC_URL> \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "dev_getTrackedDataValues",
    "params": ["ckxyz...", { "period": "1d" }]
  }'