DALP historical balances: timestamp-based token checkpoints

Timestamp-based balance and total supply checkpoints for point-in-time token queries. Passive feature with no roles or economic rewrite. Required by Fixed Treasury Yield.

Historical Balances records timestamp-based checkpoints for DALPAsset balances and total supply after token operations. Reporting, snapshot, and yield logic can read point-in-time token state without changing transfer amounts, adding holder steps, or introducing operator roles.

Related:

Interface and capabilities

This feature is passive. It has no configuration roles and does not rewrite token operations. Mint, burn, redeem, and transfer hooks write checkpoints. View functions read balance and total supply at a past timestamp-based timepoint.

The feature clock uses block.timestamp and reports CLOCK_MODE() as mode=timestamp. Use Unix timestamp timepoints, not block numbers, when querying the feature.

Capability	Who can call	Inputs	On-chain effect	Emits	Notes
Record balance checkpoint	Automatic (hook)	Mint, burn, redeem, or transfer	Writes holder and total supply checkpoints when relevant	`CheckpointUpdated`	Zero-value operations do not write checkpoints
Query historical balance	Anyone	Account address + timepoint	None, view-only	None	Reads non-strict holder history
Query historical total supply	Anyone	Timepoint	None, view-only	None	Reads non-strict supply history
Query strict history	Anyone	Account address when needed + timepoint	None, view-only	None	Reverts before tracking was enabled

The view-only rows are included because point-in-time queries are the feature's primary purpose.

Lookup behavior

Historical Balances exposes non-strict and strict lookup paths:

Lookup path	Function	Behavior
Non-strict balance	`balanceOfAt(account, timepoint)`	Reverts for future timepoints. Returns current balance as a fallback when the account has no checkpoints and the timepoint is at or after activation.
Non-strict total supply	`totalSupplyAt(timepoint)`	Reverts for future timepoints. Returns current total supply as a fallback when no supply checkpoint exists and the timepoint is at or after activation.
Strict balance	`balanceOfAtStrict(account, timepoint)`	Reverts for future timepoints and for timepoints before `enabledAt()`. Use it when the caller needs proof that tracking had already started.
Strict total supply	`totalSupplyAtStrict(timepoint)`	Reverts for future timepoints and for timepoints before `enabledAt()`. Use it when yield, audit, or entitlement logic must reject pre-activation history.

enabledAt() returns the timestamp when tracking was enabled. A query before that timestamp has no checkpoint history. Strict reads fail with QueryBeforeEnabled; future reads fail with FutureLookup.

Business impact

Holders: Nothing to approve or submit. Historical Balances does not move tokens, change balances, or add holder approval steps.
Issuer or platform: Enables point-in-time ownership reporting, snapshot-based eligibility, and Fixed Treasury Yield entitlement calculation.
Economics: No direct economic impact. The feature records data from token operations instead of changing the operation result.

Risks and abuse cases

Checkpoint storage growth: Token operations that change tracked state add checkpoint entries. High-frequency tokens accumulate checkpoint histories, increasing on-chain storage over time.
Query gas cost at scale: On-chain reads across many holders or many timepoints cost gas for the caller. Off-chain reads do not consume gas.
Pre-activation ambiguity: Non-strict reads can return a fallback value after activation when no checkpoint exists for the account or supply. Use strict reads when the caller must distinguish recorded history from fallback behavior.

No financial risk vector is introduced by this feature alone because it does not authorize transfers, rewrite amounts, mint, burn, or redeem tokens.

Controls and guardrails

Role	Available operations
None	No `GOVERNANCE_ROLE` or `CUSTODIAN_ROLE` parameter controls this feature

Tracking starts when the feature is initialized. Runtime configuration cannot pause checkpointing or change the clock mode.

Failure modes and edge cases

Future timepoint: Balance and supply lookups revert with FutureLookup when the requested timepoint is greater than the feature clock.
Before activation: Strict lookups revert with QueryBeforeEnabled when the requested timepoint is earlier than enabledAt().
No checkpoint for an account after activation: Non-strict balance reads can return the current balance fallback when the account has no checkpoint history.
No total supply checkpoint after activation: Non-strict supply reads can return the current total supply fallback when no supply checkpoint exists.
Same-timestamp updates: Multiple operations in the same timestamp can collapse into the latest checkpoint value for that timestamp.

Auditability and operational signals

CheckpointUpdated(sender, account, oldBalance, newBalance) emits when the feature writes a balance or total supply checkpoint. Total supply checkpoints use address(0) as the account.
enabledAt() exposes the timestamp from which strict historical lookups are valid.
clock() and CLOCK_MODE() expose the timestamp-based clock used by new checkpoints and lookup validation.

Dependencies

No external provider dependency.
Required by: Fixed Treasury Yield, which needs Historical Balances for holder and supply snapshots.
Recommended for: tokens that need point-in-time compliance reporting, snapshot eligibility, or governance-adjacent balance analysis.

Compatibility and ordering notes

supportsRewriting = false: Historical Balances does not modify operation amounts.
Order after rewriting or fee features so checkpoints capture the final post-rewrite balance and supply state.
Compatible with Voting Power. Voting Power uses its own independent checkpoint mechanism, so both features can coexist.

Change impact

Enable after launch: Tracking starts from the activation timestamp. Earlier token operations are not backfilled into checkpoint history.
Disable or remove: Existing checkpoints remain on-chain, but no new checkpoints are created. Fixed Treasury Yield can no longer calculate yield if Historical Balances is unavailable.
No configuration to change: The feature has no runtime settings beyond being present or absent.

Historical Balances