Skip to main content
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.

​
Tracker Schema

Each tracker consists of:
  • name: Unique identifier for the tracker
  • type: Data type of the tracker value
  • initialValue: Initial value(s) for the tracker

​
Validation Rules

  • name must be unique within the policy’s Trackers array
  • type must be a supported tracker type
  • initialValue must match the specified type
  • String values are automatically trimmed of whitespace

​
Supported Tracker Types

  • uint256 - Unsigned 256-bit integer
  • address - Ethereum address
  • bool - Boolean value (“true” / “false”)
  • bytes - Bytes value (must use prefix “0x” e.g. “0x1234”)
  • string - String value
  • Array variants of the above types (uint256[], address[], bool[], bytes[], string[])

​
Type-Value Validation

  • For single value types: initialValue must be a string
  • For array types: initialValue must be an array of strings
  • Values must be compatible with the specified type

​
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

​
Mapped Tracker Schema

Each mapped tracker consists of:
  • name: Unique identifier for the mapped tracker
  • keyType: Data type for the mapping keys
  • valueType: Data type for the mapping values
  • initialKeys: Array of initial keys for the mapping
  • initialValues: Array of initial values corresponding to the keys

​
Mapped Tracker Validation Rules

  • name must be unique within the policy’s MappedTrackers array
  • keyType must be a supported tracker key type
  • valueType must be a supported tracker type
  • initialKeys and initialValues arrays must have the same length
  • initialKeys must contain unique values (no duplicates)
  • Each value in initialValues must match the specified valueType
  • Each key in initialKeys must match the specified keyType

​
Supported Key Types

  • uint256 - Unsigned 256-bit integer
  • address - Ethereum address
  • string - String value
  • bool - Boolean value (“true” / “false”)
  • bytes - Bytes value (must use prefix “0x” e.g. “0x1234”)

​
Supported Value Types

  • Same as regular tracker types (including array variants)

​
Type-Value Validation for Mapped Trackers

  • For single value types: each entry in initialValues must be a string
  • For array value types: each entry in initialValues must be an array of strings
  • All keys must be valid for the specified keyType
  • All values must be valid for the specified valueType
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.