Skip to main content

Snapshots Periods

The SnapshotPeriods contract (SnapshotPeriods.sol) provides a robust mechanism for tracking token balances over time periods, enabling functionality like historical balance lookups and time-weighted ownership calculations. This is particularly valuable for applications that require historical data verification such as voting rights, interest distributions, and other time-sensitive token operations.

Key Features​

  • Historical balance tracking for any RestrictedLockup-compatible token
  • Time-weighted ownership calculation across custom periods
  • Past balance lookup for both individual accounts and total supply
  • Automatic period management for token transfers, mints, and burns

How It Works​

SnapshotPeriods works by maintaining a historical record of token balances and calculating ownership based on time periods:

  1. When token transfers, mints, or burns occur, the RestrictedLockupToken contract calls the onUpdate function in SnapshotPeriods.
  2. SnapshotPeriods creates and maintains periods that record the token balances and timestamps for both individual accounts and the total supply.
  3. For time-weighted operations, the contract calculates ownership as the product of token amount and time period length.

Time-Weighted Ownership​

A key feature of SnapshotPeriods is the ability to calculate time-weighted ownership, which is essential for applications like interest distribution based on token holding duration:

The time-weighted ownership is calculated by:

  • Tracking when token balances change for each account
  • Creating period entries that record the balance, start time, and end time
  • Calculating the ownership as amount * (endTime - startTime)
  • Summing these values to determine the total ownership over specific time ranges

Primary Functions​

The SnapshotPeriods contract provides these primary functions:

  • getPastBalanceOf(token, account, timestamp): Retrieves the balance an account had at a specific past moment
  • getPastTotalSupply(token, timestamp): Retrieves the total token supply at a specific past moment
  • ownershipForPeriod(token, account, startTimestamp, endTimestamp): Calculates time-weighted ownership for an account over a given period
  • totalOwnershipForPeriod(token, startTimestamp, endTimestamp): Calculates the total time-weighted ownership over a given period
  • calculateOwnershipForPeriod(amount, periodStart, periodEnd): Helper function to calculate ownership weight as amount * (periodEnd - periodStart)

Integration with Interest Payment​

SnapshotPeriods is a critical component for the Interest Payment system, as it provides the historical data needed to calculate interest distributions based on token ownership over specific time periods:

  1. Interest Payment periods are created with specific start and end timestamps
  2. When tokens are claimed, the SnapshotPeriods contract calculates each account's proportional ownership during that period
  3. Interest is distributed according to the proportion of time-weighted ownership

This mechanism ensures fair distribution of interest based on both the amount of tokens held and the duration they were held during each interest accrual period.