Historical balances
How the historical-balances token feature records timestamped holder and supply checkpoints, and how operators read holders as of a past date for reporting, voting, and audit.
The historical-balances token feature records timestamped checkpoints when holder balances or total supply change. Reports, voting snapshots, dividend record-date reads, and audit reconciliation queries use those checkpoints to answer "what did each holder own at time T" without scanning the full event log.
Use this page when you operate an issued asset. For the canonical architecture explanation and lookup rules, see Historical balances architecture. For endpoint details, see the historical-balances API reference.
When it attaches
Historical-balances appears as a required feature on almost every system template. The asset designer attaches it during deployment with no operator input. The system templates catalog names every template that includes it.
What you configure
Nothing during asset creation. The feature has no operator-configurable parameters. The Asset Designer marks it as self-contained.
What you operate
After deployment, the feature runs automatically:
- Every mint, burn, redemption, and transfer writes timestamped checkpoints for the affected holders and, when supply changes, total supply.
- The asset detail workspace's holders tab reads from the checkpoint table for the holders list and holder-balance history.
- The holders tab includes an As of date picker that switches the list from live balances to a point-in-time snapshot. See View holders as of a past date.
- Reports and integrations read historical balances through the holders and transfers API.
- Voting snapshots (where voting-power is also attached) use the historical-balances checkpoint for the selected record-date timepoint.
View holders as of a past date
On the asset detail workspace's holders tab, use the As of date picker to read the holder list as it stood at a chosen point in time instead of the live balances.
- Open the asset, then open the Holders tab.
- Pick a date and time in the As of date field. The picker does not allow a future date.
- The holders table reloads to show each holder's balance as of that timepoint. The address bar updates so the dated view is shareable as a link.
- Clear the date with the control next to the picker to return to the live holders view.
A few rules keep the view honest:
- You cannot select a future date. The picker caps selection at the current time.
- Opening a shared link with a future or invalid date shows the live holders view rather than an empty table.
- A date before the asset was created also shows the live view, because the asset had no holders before it existed.
- An early in-range date with no recorded balances shows the holders table's empty state, not an error.
Operating considerations
- The feature stores checkpoints, not a full event replay. Feature-level historical-balance reads use Unix timestamp timepoints; indexer-backed as-of holder reads use block numbers resolved by the UI or integration.
- The feature does not retain pre-deployment history. Snapshots start at the asset deployment block.
- Checkpoints persist for the asset's lifetime. Burning or redeeming a holder's full balance writes a zero checkpoint; later mints to the same wallet write new checkpoints starting from zero.
Troubleshooting
| What you see | What to check |
|---|---|
| Historical balance returns zero unexpectedly | Confirm the queried timepoint is after the asset deployment timestamp and the holder had a non-zero balance at that point. |
| Voting snapshot returns wrong weights | Confirm the selected record-date timepoint matches the intended record date and that voting-power attached during deployment. |
| Reporting integration returns stale data | The historical-balances feature writes to the indexer; the indexer must be caught up. See Blockchain monitoring. |
| Shared as-of link shows live holders, not the snapshot | The link carried a future, invalid, or pre-creation date, so the holders tab fell back to the live view. Re-pick a valid past date in the As of date field and share the refreshed link. |
Read next
Token features operator overview
Operator how-to pages for the eleven DALP token features, including which instrument templates attach each feature and how to configure their parameters.
Operate the Voting Power token feature
How operators use Voting Power delegation and timestamp-based governance snapshots for DALP assets.