Historical balances
How the historical-balances token feature snapshots holder balances at every block, and how operators use those snapshots for reporting, voting, and audit reads.
The historical-balances token feature records a balance checkpoint for every holder at every block where their balance changes. 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.
For the architecture reference, see Historical balances.
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, and transfer writes a balance checkpoint for the affected holders.
- The asset detail workspace's holders tab reads from the checkpoint table for the holders list and holder-balance history.
- 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 at the snapshot block.
Operating considerations
- The feature stores checkpoints, not a full event replay. Reading the balance at an exact block returns the checkpoint that applied at that block, which is the holder's correct balance for any block-range query.
- The feature does not retain pre-deployment history. Snapshots start at the asset deployment block.
- Checkpoints persist for the asset's lifetime. Burning 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 block is after the asset deployment block and the holder had a non-zero balance at that point. |
| Voting snapshot returns wrong weights | Confirm the snapshot block 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. |
Read next
Token features
Operator how-to pages for the eleven DALP token features, including which instrument templates attach each feature and how to configure their parameters.
Voting power
How the voting-power token feature exposes delegated voting and governance snapshots for equity, fund, and real-estate assets on DALP.