# Historical Balances

Source: https://docs.settlemint.com/docs/architecture/components/token-features/historical-balances
Point-in-time balance and total supply queries via on-chain checkpoints. Passive feature — no configuration, no roles, no economic impact. Required by Fixed Treasury Yield.



**Purpose:** Historical Balances adds on-chain checkpoints to DALPAsset — recording balance and total supply at every mint, burn, and transfer. Any system can query token state at any past block.

* **Doc type:** Reference
* **What you'll find here:** Business impact, risks, controls, failure modes, auditability, dependencies, and ordering notes
* **Related:**
  * [Token Features Catalog](/docs/architecture/components/token-features)
  * [Fixed Treasury Yield](/docs/architecture/components/token-features/fixed-treasury-yield)
  * [Voting Power](/docs/architecture/components/token-features/voting-power)
  * [Asset Contracts](/docs/architecture/components/asset-contracts)

***

## Interface (capabilities) [#interface-capabilities]

This feature is entirely passive — no configuration, no roles, no economic impact. Every token operation creates a permanent on-chain checkpoint.

| Capability                    | Who can call     | Inputs                                  | On-chain effect                          | Emits               | Notes                                        |
| ----------------------------- | ---------------- | --------------------------------------- | ---------------------------------------- | ------------------- | -------------------------------------------- |
| Record balance checkpoint     | Automatic (hook) | Triggered on every mint, burn, transfer | Writes balance + total supply checkpoint | `CheckpointUpdated` | Storage grows with each operation            |
| Query historical balance      | Anyone           | Account address + block number          | None (view-only)                         | None                | Reverts for blocks before feature activation |
| Query historical total supply | Anyone           | Block number                            | None (view-only)                         | None                | Required by Fixed Treasury Yield             |

Note: view-only rows are included here because query capabilities ARE this feature's primary purpose.

***

## Business impact [#business-impact]

* **Holders:** Fully passive — no action required, no economic impact, no token movement.
* **Issuer / platform:** Enables compliance reporting (point-in-time ownership), snapshot-based airdrop eligibility, and is a required dependency for Fixed Treasury Yield.
* **Economics:** No economic impact. Pure data-recording feature.

***

## Risks & abuse cases [#risks--abuse-cases]

* **Checkpoint storage growth:** Every token operation creates a new checkpoint entry per holder. High-frequency tokens accumulate large checkpoint histories, increasing on-chain storage costs over time.
* **Query gas cost at scale:** Reading historical checkpoints at large block intervals or across many holders increases gas cost for callers (off-chain reads are free).

No financial risk vectors — this is a passive observability feature.

***

## Controls & guardrails [#controls--guardrails]

| Role | Actions                                             |
| ---- | --------------------------------------------------- |
| None | No `GOVERNANCE_ROLE` or `CUSTODIAN_ROLE` parameters |

No configuration. Tracking starts at deployment (feature activation) and cannot be paused or reconfigured.

***

## Failure modes & edge cases [#failure-modes--edge-cases]

* **Pre-activation history:** Transfers before this feature was activated are not checkpointed. Historical queries for blocks before activation will return zero or the activation-time balance.
* **Same-block updates:** Multiple transfers in the same block result in a single checkpoint update (the final state for that block), not one per transaction.

***

## Auditability & operational signals [#auditability--operational-signals]

* `CheckpointUpdated(sender, account, oldBalance, newBalance)` — emitted on every balance checkpoint write. Monitor for unexpected checkpoint volume.
* Checkpoint data is stored on-chain and queryable at any block via `getPastTotalSupply(blockNumber)` and `getPastBalanceOf(account, blockNumber)`.

***

## Dependencies [#dependencies]

* No external dependencies.
* Required by: **Fixed Treasury Yield** — cannot function without Historical Balances.
* Recommended for: any token where compliance reporting, snapshot airdrops, or governance will be used.

***

## Compatibility & ordering notes [#compatibility--ordering-notes]

* `supportsRewriting = false` — no amount modification.
* **Order last** in the feature array — must run after fee features that rewrite amounts, so snapshots capture post-fee balances.
* Compatible with all other features. Voting Power uses its own independent checkpoint mechanism — both can coexist without conflict.

***

## Change impact [#change-impact]

* **Enable after launch:** Checkpoints start from the activation block. Pre-activation history is not available.
* **Disable:** Existing checkpoints remain on-chain and are still queryable. No new checkpoints are created. Fixed Treasury Yield will stop functioning if Historical Balances is removed.
* **No configuration to change.**

***

## See also [#see-also]

* [Token Features Catalog](/docs/architecture/components/token-features) — return to the full feature catalog
* [Fixed Treasury Yield](/docs/architecture/components/token-features/fixed-treasury-yield) — requires Historical Balances
* [Voting Power](/docs/architecture/components/token-features/voting-power) — companion governance feature