Track State

Record on-chain state over time on your Stagenet.

A tracked item is a piece of state — a balance, an ERC20 holding, a storage slot, or the result of a view function — that your Stagenet snapshots as it runs. The history shows up in the contract’s Workspace, alongside transactions and balances.

How it works

Each track add creates a tracked item on your Stagenet. By default, the Stagenet records its value after every transaction. Periodic triggers (every-N-blocks or cron) are also supported for state that doesn’t change with every tx but should still be sampled on a cadence.

History is stored on your Stagenet and is visible in the Workspace of the address you’re tracking.

Usage

With a contract.dev.js at your project root (see Setup):


contract.dev track <subcommand>

`track add balance`

Track the native token balance of an address.


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

Argument	Description
`<address>`	The address whose native balance to track
`--name <name>`	Display name (optional — auto-generated if omitted)

`track add erc20`

Track an ERC20 balance. Pass the token address followed by the holder.


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

Argument	Description
`<token>`	The ERC20 token contract address
`<holder>`	The address whose token balance to track
`--name <name>`	Display name (optional)

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

`track add storage`

Track a single storage slot on a contract.


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

Argument	Description
`<address>`	The contract address
`--slot <hex>`	Storage slot key. Short hex (e.g. `0x0`) is auto-padded to 32 bytes.
`--name <name>`	Display name (optional)

`track add function`

Track the result of a view function on a contract.


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

For a function with arguments, pass a JSON array as --args:


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

Argument	Description
`<address>`	The contract address
`--abi <abi>`	Function ABI — JSON fragment or human-readable signature
`--args <json>`	JSON array of arguments (use `'[]'` for none)
`--output-path <path>`	Dot-separated path into a struct/tuple return (e.g. `info.balance`). Optional.
`--name <name>`	Display name (optional)

Common options

These apply to every track add and to track update:

Flag	Description
`--trigger <every-tx \| every-n-blocks \| cron>`	When to record. Defaults to `every-tx`.
`--frequency <n>`	Block count (for `every-n-blocks`) or seconds (for `cron`). Required when trigger is one of those.
`--tags <a,b,c>`	Comma-separated tags.


# Sample every 100 blocks instead of every tx
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
contract.dev track add balance 0xWhale... \
  --name "whale ETH" \
  --trigger cron --frequency 60 \
  --tags whales,monitoring

`track list`

List tracked items.


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

Output:


ckxyz...  native-token-balance  0x1111...  treasury ETH [treasury]  latest=1000000000000000000@123
ckabc...  erc20-balance         0xA0b8...  treasury USDC            latest=5000000@123

`track values`

Show the recorded history for a tracked item.


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

Flag	Description
`--period <window>`	One of `10min`, `1h`, `1d`, `1w`, `1m`. Omit for full history.

`track remove`

Delete a tracked item and its recorded history.


contract.dev track remove <id>

track rm is accepted as an alias.

`track update`

Update a tracked item.


contract.dev track update <id> --name "new name"
contract.dev track update <id> --tags treasury,monitoring
contract.dev track update <id> --trigger every-n-blocks --frequency 50

Any of the flags accepted by track add (other than the positional kind) can be passed. Changing a “semantic” field — --address, --abi, --args, --output-path, or the type — clears the item’s history, since old and new values would no longer be comparable.