DALP historical balances: timestamp-based token checkpoints

Timestamp checkpoints written after every token operation let reporting, yield, and snapshot logic read point-in-time balances and total supply without changing transfer amounts.

Historical Balances is the checkpointing feature for DALPAsset token history. Every mint, burn, redeem, and transfer writes a timestamped checkpoint. Your reporting, snapshot, and yield logic can query that history at any past point without adding holder approval steps or special roles.

Link to this page from operator and integration pages for the shared behavior model, then keep those pages focused on tasks or endpoint facts.

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 holder balance and total supply at a past timestamp.

The feature clock uses block.timestamp and reports CLOCK_MODE() as mode=timestamp. Use Unix timestamps, not block numbers, when you query 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 primary purpose. Use them in your reporting and yield logic where on-chain reads are acceptable.

Lookup behavior

Historical Balances exposes two lookup paths: non-strict and strict. Choose the path based on whether you need proof that tracking had already started at the queried time.

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 activation time. Any query before that point has no checkpoint history. Strict reads before activation fail with QueryBeforeEnabled; reads at a future time fail with FutureLookup.

Business impact

Holders have nothing to approve or submit. Historical Balances does not move tokens, change balances, or add any approval steps. For issuers, it enables point-in-time ownership reporting, snapshot-based eligibility, and Fixed Treasury Yield entitlement calculation. It has no direct economic impact: it records data from token operations without altering the operation result.

Risks and abuse cases

Checkpoint storage growth: Token operations that change tracked state add checkpoint entries. High-frequency tokens accumulate entries over time, increasing on-chain storage costs.
Query gas cost: On-chain reads across many holders or many timestamps 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 you must distinguish recorded history from fallback behavior.

This feature introduces no financial risk vector on its own: 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. You cannot pause checkpointing or change the clock mode at runtime.

Failure modes and edge cases

Future lookup: Balance and supply queries revert with FutureLookup when the requested time exceeds the feature clock.
Strict reads revert with QueryBeforeEnabled when the requested time is earlier than enabledAt().
Non-strict balance reads can return the current balance fallback when the account has no checkpoint history after activation.
Non-strict total supply reads can return the current supply fallback when no checkpoint exists after activation.
Multiple operations in the same block timestamp can collapse into the latest checkpoint value for that block.

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-based eligibility, or governance balance analysis.

Compatibility and ordering notes

supportsRewriting = false: Historical Balances does not modify operation amounts.
Place it 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 can coexist.

Change impact

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

Historical Balances