Trackers are persistent, on-chain variables defined within a policy. They allow you to store historical, cumulative, or computed values. Tracker values can be referenced and updated by rules in the policy. Trackers are great for scenarios like thresholds or quotas (e.g. “users can only mint X per day”), storing cumulative activity (e.g. total tokens sold, volume), and anything you want to track over time. There are 2 types of Trackers; standard Trackers that can store a single value and MappedTrackers that can store a value per key.

​
Defining a Tracker

​
Standard Tracker

To add a new tracker to a policy, you’ll define:
  • Name (this will not be stored on-chain but is used to reference the tracker when using the SDK or the UI)
  • Type
  • Initial value: the tracker’s starting value.
Example tracker definition: 
  "Trackers": [
    {
      "name": "volume",
      "type": "uint256",
      "initialValue": 0
    }
  ]

​
Mapped Tracker

To add a new mapped tracker to a policy, you’ll define:
  • Name (this will not be stored on-chain but is used to reference the tracker when using the SDK or the UI)
  • keyType the data type of the mapped tracker keys
  • valueType the data type of the mapped tracker values
  • initialKeys: the tracker’s initial keys.
  • initialValues: the tracker’s initial values.
Example mapped tracker definition: 
  "MappedTrackers": [
    {
      "name": "volume",
      "keyType": "address",
      "valueType": "uint256",
      "initialKeys": ["0xB7f8BC63BbcaD18155201308C8f3540b07f84F5e"],
      "initialValues": [0]
    }
  ]
Once added, trackers are available immediately for use in rules in the policy.

​
Reading from a Tracker

Once defined, you can reference any tracker in any expression in the policy. For example, you can use a tracker in a rule’s condition expression, or use a tracker in a tracker’s update expression (its own or another’s).

​
Updating a Tracker

Trackers are updated by using the update tracker effect in a rule. When using this effect, you’ll provide the name of the tracker and the update expression. Updating a mapped tracker requires the name of the tracker, the key, and the update expression. For full details on how to use trackers in your policy, see our Trackers Guide.
Be mindful of the ordering of your rules that use and update trackers. Trackers are updated as rule effects, so the new value is only visible in later rules—not the one that triggered the update. Also, if multiple rules update the same tracker, make sure it’s deliberate.

​
Tracker Visibility

While trackers are internal to your policy, they are stored on-chain and can be read externally. External contracts can query current tracker values, use them as part of onchain or off-chain logic, integrate them into dashboards, etc. Available SDK functions for trackers here.