From 25abf521156e281d88dddf39c374706d3e790a6f Mon Sep 17 00:00:00 2001 From: Brendan Asselstine Date: Thu, 21 Mar 2024 15:26:47 -0700 Subject: [PATCH 1/4] Added comments and natspec --- src/PrizePool.sol | 25 +++++++++++++++++++-- src/abstract/TieredLiquidityDistributor.sol | 15 ++++++++++++- 2 files changed, 37 insertions(+), 3 deletions(-) diff --git a/src/PrizePool.sol b/src/PrizePool.sol index b893ef9..a120e7d 100644 --- a/src/PrizePool.sol +++ b/src/PrizePool.sol @@ -789,6 +789,12 @@ contract PrizePool is TieredLiquidityDistributor { } } + /// @notice Returns the shutdown balance for a given vault and account. The prize pool must already be shutdown. + /// @dev The shutdown balance is the amount of prize tokens that a user can claim after the prize pool has been shutdown. + /// @dev The shutdown balance is calculated using the user's TWAB and the total supply TWAB, whose timeranges are the grand prize period prior to the shutdown timestamp. + /// @param _vault The vault to check + /// @param _account The account to check + /// @return The shutdown balance for the given vault and account function shutdownBalanceOf(address _vault, address _account) public view returns (uint256) { if (!isShutdown()) { return 0; @@ -847,6 +853,10 @@ contract PrizePool is TieredLiquidityDistributor { return balance; } + /// @notice Withdraws the shutdown balance for a given vault the sender + /// @param _vault The sender's vault whose shutdown balance should be withdrawn + /// @param _recipient The address to send the shutdown balance to + /// @return The amount of prize tokens withdrawn function withdrawShutdownBalance(address _vault, address _recipient) external returns (uint256) { if (!isShutdown()) { revert PrizePoolNotShutdown(); @@ -860,18 +870,24 @@ contract PrizePool is TieredLiquidityDistributor { return balance; } + /// @notice Returns the draw ID that will be awarded prior to the prize pool being shutdown + /// @return The draw id function drawIdPriorToShutdown() public view returns (uint24) { return _lastAwardedDrawId + drawTimeout; } + /// @notice Returns the timestamp at which the prize pool will be considered inactive and shutdown + /// @return The timestamp at which the prize pool will be considered inactive function shutdownAt() public view returns (uint256) { uint256 twabShutdownAt = twabController.lastObservationAt(); uint256 drawTimeoutAt_ = drawTimeoutAt(); return drawTimeoutAt_ < twabShutdownAt ? drawTimeoutAt_ : twabShutdownAt; } - function isShutdown() public view returns (bool shutdown) { - shutdown = block.timestamp >= shutdownAt(); + /// @notice Returns whether the prize pool has been shutdown + /// @return True if shutdown, false otherwise + function isShutdown() public view returns (bool) { + return block.timestamp >= shutdownAt(); } /** @@ -961,6 +977,10 @@ contract PrizePool is TieredLiquidityDistributor { ); } + /// @notice Compute the start draw id for a range given the end draw id and range size + /// @param _endDrawIdInclusive The end draw id (inclusive) of the range + /// @param _rangeSize The size of the range + /// @return The start draw id (inclusive) of the range function computeRangeStartDrawIdInclusive(uint24 _endDrawIdInclusive, uint24 _rangeSize) public pure returns (uint24) { if (_rangeSize != 0) { return _rangeSize > _endDrawIdInclusive ? 1 : _endDrawIdInclusive - _rangeSize + 1; @@ -1038,6 +1058,7 @@ contract PrizePool is TieredLiquidityDistributor { : sd(0); } + /// @notice Modifier that requires the prize pool not to be shutdown modifier notShutdown() { if (isShutdown()) { revert PrizePoolShutdown(); diff --git a/src/abstract/TieredLiquidityDistributor.sol b/src/abstract/TieredLiquidityDistributor.sol index 7ff347e..37caa02 100644 --- a/src/abstract/TieredLiquidityDistributor.sol +++ b/src/abstract/TieredLiquidityDistributor.sol @@ -10,6 +10,9 @@ import { UD34x4, fromUD60x18 as fromUD60x18toUD34x4, intoUD60x18 as fromUD34x4to import { TierCalculationLib } from "../libraries/TierCalculationLib.sol"; /// @notice Struct that tracks tier liquidity information. +/// @param drawId The draw ID that the tier was last updated for +/// @param prizeSize The size of the prize for the tier for the drawId +/// @param prizeTokenPerShare The total prize tokens per share that have already been consumed for this tier. struct Tier { uint24 drawId; uint104 prizeSize; @@ -110,7 +113,10 @@ contract TieredLiquidityDistributor { /// @notice The percentage of tier liquidity to target for utilization. UD60x18 public immutable tierLiquidityUtilizationRate; - /// @notice The current number of prize tokens per share. + /// @notice The number of prize tokens that have accrued per share for all time. + /// @dev This is an ever-increasing exchange rate that is used to calculate the prize liquidity for each tier. + /// @dev Each tier holds a separate tierPrizeTokenPerShare; the delta between the tierPrizeTokenPerShare and + /// the prizeTokenPerShare * tierShares is the available liquidity they have. UD34x4 public prizeTokenPerShare; /// @notice The number of tiers for the last awarded draw. The last tier is the canary tier. @@ -416,10 +422,17 @@ contract TieredLiquidityDistributor { return prizeSize > type(uint104).max ? type(uint104).max : uint104(prizeSize); } + /// @notice Returns whether the given tier is a canary tier + /// @param _tier The tier to check + /// @return True if the passed tier is a canary tier, false otherwise function isCanaryTier(uint8 _tier) public view returns (bool) { return _tier >= numberOfTiers - NUMBER_OF_CANARY_TIERS; } + /// @notice Returns the number of shares for the given tier and number of tiers. + /// @param _tier The tier to compute the number of shares for + /// @param _numberOfTiers The number of tiers + /// @return The number of shares function _numShares(uint8 _tier, uint8 _numberOfTiers) internal view returns (uint8) { uint8 result = _tier > _numberOfTiers - 3 ? canaryShares : tierShares; return result; From 24adc8e467c5fddff96b12d963bff9e23fdefba7 Mon Sep 17 00:00:00 2001 From: Brendan Asselstine Date: Fri, 22 Mar 2024 16:44:38 -0700 Subject: [PATCH 2/4] Update src/PrizePool.sol Co-authored-by: Trevor Richard <40277611+trmid@users.noreply.github.com> --- src/PrizePool.sol | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/PrizePool.sol b/src/PrizePool.sol index a120e7d..5963fc7 100644 --- a/src/PrizePool.sol +++ b/src/PrizePool.sol @@ -853,7 +853,7 @@ contract PrizePool is TieredLiquidityDistributor { return balance; } - /// @notice Withdraws the shutdown balance for a given vault the sender + /// @notice Withdraws the shutdown balance for a given vault and sender /// @param _vault The sender's vault whose shutdown balance should be withdrawn /// @param _recipient The address to send the shutdown balance to /// @return The amount of prize tokens withdrawn From 42b1454055446c49e3a8edfe4e6778a086e9e47b Mon Sep 17 00:00:00 2001 From: Brendan Asselstine Date: Fri, 22 Mar 2024 16:44:43 -0700 Subject: [PATCH 3/4] Update src/PrizePool.sol Co-authored-by: Trevor Richard <40277611+trmid@users.noreply.github.com> --- src/PrizePool.sol | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/PrizePool.sol b/src/PrizePool.sol index 5963fc7..2b666a2 100644 --- a/src/PrizePool.sol +++ b/src/PrizePool.sol @@ -854,7 +854,7 @@ contract PrizePool is TieredLiquidityDistributor { } /// @notice Withdraws the shutdown balance for a given vault and sender - /// @param _vault The sender's vault whose shutdown balance should be withdrawn + /// @param _vault The eligible vault to withdraw the shutdown balance from /// @param _recipient The address to send the shutdown balance to /// @return The amount of prize tokens withdrawn function withdrawShutdownBalance(address _vault, address _recipient) external returns (uint256) { From 068e2ad0c172bcbedc4940ea01d072822dcc91d6 Mon Sep 17 00:00:00 2001 From: Brendan Asselstine Date: Fri, 22 Mar 2024 16:44:48 -0700 Subject: [PATCH 4/4] Update src/abstract/TieredLiquidityDistributor.sol Co-authored-by: Trevor Richard <40277611+trmid@users.noreply.github.com> --- src/abstract/TieredLiquidityDistributor.sol | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/abstract/TieredLiquidityDistributor.sol b/src/abstract/TieredLiquidityDistributor.sol index 37caa02..e15f585 100644 --- a/src/abstract/TieredLiquidityDistributor.sol +++ b/src/abstract/TieredLiquidityDistributor.sol @@ -11,7 +11,7 @@ import { TierCalculationLib } from "../libraries/TierCalculationLib.sol"; /// @notice Struct that tracks tier liquidity information. /// @param drawId The draw ID that the tier was last updated for -/// @param prizeSize The size of the prize for the tier for the drawId +/// @param prizeSize The size of the prize for the tier at the drawId /// @param prizeTokenPerShare The total prize tokens per share that have already been consumed for this tier. struct Tier { uint24 drawId;