Track on-chain data

Record and graph on-chain state as your Stagenet runs — native balances, ERC20 holdings, storage variables, and view function return values. Each tracked item shows up in the Tracked Data section of the relevant Workspace, with its history visualised over time.

Prerequisites

A Stagenet — create one in the dashboard if you don’t have one yet
The contract.dev CLI installed and configured at your project root:


npm install contract.dev
npx contract.dev init --rpc-url=<YOUR_STAGENET_RPC_URL>

A Workspace for the address you’re tracking is helpful but not required — the tracked value records either way.

What you can track

Each track add subcommand records a different kind of value:

Command	Records
`track add balance`	Native token balance of an address
`track add erc20`	An ERC20 token balance
`track add storage`	A single storage slot on a contract
`track add function`	The return value of a view function

By default each tracked item samples on every transaction that touches your Stagenet. For state that doesn’t change every block, switch the trigger to every-n-blocks or cron (see Choose when to record).

Track a native token balance


npx contract.dev track add balance 0x1111111111111111111111111111111111111111 \
  --name "treasury ETH"

Track an ERC20 balance

Pass the token address followed by the holder. The CLI fills in balanceOf(holder) for you — you don’t need to provide the ABI.


npx contract.dev track add erc20 \
  0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
  0x1111111111111111111111111111111111111111 \
  --name "treasury USDC"

Track a storage slot


npx contract.dev track add storage 0xYourContract... \
  --slot 0x0 \
  --name "owner slot"

Short hex slot keys (0x0, 0x2) are auto-padded to 32 bytes.

Track a view function

Pass the function signature with --abi and a JSON array of arguments with --args:


npx contract.dev track add function 0xYourToken... \
  --abi 'function totalSupply() view returns (uint256)' \
  --args '[]' \
  --name "totalSupply"

For a function with arguments:


npx contract.dev track add function 0xYourToken... \
  --abi 'function balanceOf(address) view returns (uint256)' \
  --args '["0x1111111111111111111111111111111111111111"]' \
  --name "alice USDC"

If the function returns a struct or tuple, drill into a single field with --output-path:


npx contract.dev track add function 0xPool... \
  --abi 'function getPosition(address) view returns (tuple(uint256 balance, uint256 reward))' \
  --args '["0xUser..."]' \
  --output-path "balance" \
  --name "user position balance"

For example, if you were building a yield vault, you could track the result of totalAssets() to graph its TVL over time, the result of balanceOf(user) for each user to monitor share accounting, and the storage slot of lastHarvest to confirm harvest cadence.

Choose when to record

By default, every track add records on every transaction. Override with --trigger and --frequency:


# Sample every 100 blocks instead of every tx
npx contract.dev track add function 0xPool... \
  --abi 'function getReserves() view returns (uint256,uint256)' \
  --args '[]' \
  --name "reserves" \
  --trigger every-n-blocks --frequency 100
 
# Sample every 60 seconds
npx contract.dev track add balance 0xWhale... \
  --name "whale ETH" \
  --trigger cron --frequency 60

every-tx is the right default for state that changes with each interaction. Use every-n-blocks or cron for things that drift slowly (oracle prices, accrued yield) where every-tx sampling would just produce noise.

List, view, and remove

List all tracked items, or filter by address or tag:


npx contract.dev track list                            # all
npx contract.dev track list --address 0xContract...    # for a contract
npx contract.dev track list --tag treasury             # by tag
npx contract.dev track list --with-values              # include latest value

Show recorded history for a tracked item:


npx contract.dev track values <id>                # all values
npx contract.dev track values <id> --period 1d    # last 24 hours

Remove a tracked item and its history:


npx contract.dev track remove <id>

See the track reference for the full flag list, including tags, updates, and the SDK equivalent.

See your data

Each tracked item is graphed in the Tracked Data section of the Workspace for the address it tracks. Open the Workspace from the Stagenet’s Analytics dashboard.

If you haven’t created a Workspace for the address yet, see Create Workspaces with the CLI.

Next steps

Workspaces — the dashboards where tracked data appears.
Tracked Data — the broader Tracked Data system and its UI-based workflow.
track reference — every subcommand, flag, and option in one place.