Skip to main content

TierCalculationLib

Git Source

Author: PoolTogether Inc. Team

Provides helper functions to assist in calculating tier prize counts, frequency, and odds.

Functions

getTierOdds

Calculates the odds of a tier occurring.

function getTierOdds(uint8 _tier, uint8 _numberOfTiers, uint24 _grandPrizePeriod) internal pure returns (SD59x18);

Parameters

NameTypeDescription
_tieruint8The tier to calculate odds for
_numberOfTiersuint8The total number of tiers
_grandPrizePerioduint24The number of draws between grand prizes

Returns

NameTypeDescription
<none>SD59x18The odds that a tier should occur for a single draw.

estimatePrizeFrequencyInDraws

Estimates the number of draws between a tier occurring.

Limits the frequency to the grand prize period in draws.

function estimatePrizeFrequencyInDraws(SD59x18 _tierOdds, uint24 _grandPrizePeriod) internal pure returns (uint24);

Parameters

NameTypeDescription
_tierOddsSD59x18The odds for the tier to calculate the frequency of
_grandPrizePerioduint24The number of draws between grand prizes

Returns

NameTypeDescription
<none>uint24The estimated number of draws between the tier occurring

prizeCount

Computes the number of prizes for a given tier.

function prizeCount(uint8 _tier) internal pure returns (uint256);

Parameters

NameTypeDescription
_tieruint8The tier to compute for

Returns

NameTypeDescription
<none>uint256The number of prizes

isWinner

Determines if a user won a prize tier.

function isWinner(
uint256 _userSpecificRandomNumber,
uint256 _userTwab,
uint256 _vaultTwabTotalSupply,
SD59x18 _vaultContributionFraction,
SD59x18 _tierOdds
) internal pure returns (bool);

Parameters

NameTypeDescription
_userSpecificRandomNumberuint256The random number to use as entropy
_userTwabuint256The user's time weighted average balance
_vaultTwabTotalSupplyuint256The vault's time weighted average total supply
_vaultContributionFractionSD59x18The portion of the prize that was contributed by the vault
_tierOddsSD59x18The odds of the tier occurring

Returns

NameTypeDescription
<none>boolTrue if the user won the tier, false otherwise

calculatePseudoRandomNumber

The user-held portion of the total supply is the "winning zone". If the above pseudo-random number falls within the winning zone, the user has won this tier. However, we scale the size of the zone based on:

  • Odds of the tier occurring
  • Number of prizes
  • Portion of prize that was contributed by the vault

Calculates a pseudo-random number that is unique to the user, tier, and winning random number.

function calculatePseudoRandomNumber(
uint24 _drawId,
address _vault,
address _user,
uint8 _tier,
uint32 _prizeIndex,
uint256 _winningRandomNumber
) internal pure returns (uint256);

Parameters

NameTypeDescription
_drawIduint24The draw id the user is checking
_vaultaddressThe vault the user deposited into
_useraddressThe user
_tieruint8The tier
_prizeIndexuint32The particular prize index they are checking
_winningRandomNumberuint256The winning random number

Returns

NameTypeDescription
<none>uint256A pseudo-random number

calculateWinningZone

Calculates the winning zone for a user. If their pseudo-random number falls within this zone, they win the tier.

function calculateWinningZone(uint256 _userTwab, SD59x18 _vaultContributionFraction, SD59x18 _tierOdds)
internal
pure
returns (uint256);

Parameters

NameTypeDescription
_userTwabuint256The user's time weighted average balance
_vaultContributionFractionSD59x18The portion of the prize that was contributed by the vault
_tierOddsSD59x18The odds of the tier occurring

Returns

NameTypeDescription
<none>uint256The winning zone for the user.

tierPrizeCountPerDraw

Computes the estimated number of prizes per draw for a given tier and tier odds.

function tierPrizeCountPerDraw(uint8 _tier, SD59x18 _odds) internal pure returns (uint32);

Parameters

NameTypeDescription
_tieruint8The tier
_oddsSD59x18The odds of the tier occurring for the draw

Returns

NameTypeDescription
<none>uint32The estimated number of prizes per draw for the given tier and tier odds

isValidTier

Checks whether a tier is a valid tier

function isValidTier(uint8 _tier, uint8 _numberOfTiers) internal pure returns (bool);

Parameters

NameTypeDescription
_tieruint8The tier to check
_numberOfTiersuint8The number of tiers

Returns

NameTypeDescription
<none>boolTrue if the tier is valid, false otherwise