Historical Balances

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
  • Fixed Treasury Yield
  • Voting Power
  • Asset Contracts

---

Interface (capabilities)

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

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

---

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

• 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

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

---

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

• 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

• 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

• 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

• 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

• Token Features Catalog — return to the full feature catalog
• Fixed Treasury Yield — requires Historical Balances
• Voting Power — companion governance feature