Skip to main content

TwabRewards

Contract to distribute rewards to depositors in a pool. This contract supports the creation of several promotions that can run simultaneously. In order to calculate user rewards, we use the TWAB (Time-Weighted Average Balance) from the Ticket contract. This way, users simply need to hold their tickets to be eligible to claim rewards. Rewards are calculated based on the average amount of tickets they hold during the epoch duration.

This contract supports only one prize pool ticket. This contract does not support the use of fee on transfer tokens.

Structs

Promotion

  • address creator
  • uint64 startTimestamp
  • uint8 numberOfEpochs
  • uint48 epochDuration
  • uint48 createdAt
  • contract IERC20 token
  • uint256 tokensPerEpoch
  • uint256 rewardsUnclaimed

Functions

constructor

  function constructor(
contract ITicket _ticket
) public

Constructor of the contract.

Parameters:

NameTypeDescription
_ticketcontract ITicketPrize Pool ticket address for which the promotions will be created

createPromotion

  function createPromotion(
contract IERC20 _token,
uint64 _startTimestamp,
uint256 _tokensPerEpoch,
uint48 _epochDuration,
uint8 _numberOfEpochs
) external returns (uint256)

Creates a new promotion.

For sake of simplicity, msg.sender will be the creator of the promotion. _latestPromotionId starts at 0 and is incremented by 1 for each new promotion. So the first promotion will have id 1, the second 2, etc. The transaction will revert if the amount of reward tokens provided is not equal to _tokensPerEpoch * _numberOfEpochs. This scenario could happen if the token supplied is a fee on transfer one.

Parameters:

NameTypeDescription
_tokencontract IERC20Address of the token to be distributed
_startTimestampuint64Timestamp at which the promotion starts
_tokensPerEpochuint256Number of tokens to be distributed per epoch
_epochDurationuint48Duration of one epoch in seconds
_numberOfEpochsuint8Number of epochs the promotion will last for

Return Values:

TypeDescription
uint256Id of the newly created promotion

endPromotion

  function endPromotion(
uint256 _promotionId,
address _to
) external returns (bool)

End currently active promotion and send promotion tokens back to the creator.

Will only send back tokens from the epochs that have not completed.

Parameters:

NameTypeDescription
_promotionIduint256Promotion id to end
_toaddressAddress that will receive the remaining tokens if there are any left

Return Values:

TypeDescription
booltrue if operation was successful

destroyPromotion

  function destroyPromotion(
uint256 _promotionId,
address _to
) external returns (bool)

Delete an inactive promotion and send promotion tokens back to the creator.

Will send back all the tokens that have not been claimed yet by users. This function will revert if the promotion is still active. This function will revert if the grace period is not over yet.

Parameters:

NameTypeDescription
_promotionIduint256Promotion id to destroy
_toaddressAddress that will receive the remaining tokens if there are any left

Return Values:

TypeDescription
boolTrue if operation was successful

extendPromotion

  function extendPromotion(
uint256 _promotionId,
uint8 _numberOfEpochs
) external returns (bool)

Extend promotion by adding more epochs.

Parameters:

NameTypeDescription
_promotionIduint256Id of the promotion to extend
_numberOfEpochsuint8Number of epochs to add

Return Values:

TypeDescription
boolTrue if the operation was successful

claimRewards

  function claimRewards(
address _user,
uint256 _promotionId,
uint8[] _epochIds
) external returns (uint256)

Claim rewards for a given promotion and epoch.

Rewards can be claimed on behalf of a user. Rewards can only be claimed for a past epoch.

Parameters:

NameTypeDescription
_useraddressAddress of the user to claim rewards for
_promotionIduint256Id of the promotion to claim rewards for
_epochIdsuint8[]Epoch ids to claim rewards for

Return Values:

TypeDescription
uint256Total amount of rewards claimed

getPromotion

  function getPromotion(
uint256 _promotionId
) external returns (struct ITwabRewards.Promotion)

Get settings for a specific promotion.

Parameters:

NameTypeDescription
_promotionIduint256Id of the promotion to get settings for

Return Values:

TypeDescription
struct ITwabRewards.PromotionPromotion settings

getCurrentEpochId

  function getCurrentEpochId(
uint256 _promotionId
) external returns (uint256)

Get the current epoch id of a promotion.

Epoch ids and their boolean values are tightly packed and stored in a uint256, so epoch id starts at 0.

Parameters:

NameTypeDescription
_promotionIduint256Id of the promotion to get current epoch for

Return Values:

TypeDescription
uint256Current epoch id of the promotion

getRemainingRewards

  function getRemainingRewards(
uint256 _promotionId
) external returns (uint256)

Get the total amount of tokens left to be rewarded.

Parameters:

NameTypeDescription
_promotionIduint256Id of the promotion to get the total amount of tokens left to be rewarded for

Return Values:

TypeDescription
uint256Amount of tokens left to be rewarded

getRewardsAmount

  function getRewardsAmount(
address _user,
uint256 _promotionId,
uint8[] _epochIds
) external returns (uint256[])

Get amount of tokens to be rewarded for a given epoch.

Rewards amount can only be retrieved for epochs that are over. Will revert if _epochId is over the total number of epochs or if epoch is not over. Will return 0 if the user average balance of tickets is 0. Will be 0 if user has already claimed rewards for the epoch.

Parameters:

NameTypeDescription
_useraddressAddress of the user to get amount of rewards for
_promotionIduint256Id of the promotion from which the epoch is
_epochIdsuint8[]Epoch ids to get reward amount for

Return Values:

TypeDescription
uint256[]Amount of tokens per epoch to be rewarded

Events

PromotionCreated

  event PromotionCreated(
uint256 promotionId
)

Emitted when a promotion is created.

Parameters:

NameTypeDescription
promotionIduint256Id of the newly created promotion

PromotionEnded

  event PromotionEnded(
uint256 promotionId,
address recipient,
uint256 amount,
uint8 epochNumber
)

Emitted when a promotion is ended.

Parameters:

NameTypeDescription
promotionIduint256Id of the promotion being ended
recipientaddressAddress of the recipient that will receive the remaining rewards
amountuint256Amount of tokens transferred to the recipient
epochNumberuint8Epoch number at which the promotion ended

PromotionDestroyed

  event PromotionDestroyed(
uint256 promotionId,
address recipient,
uint256 amount
)

Emitted when a promotion is destroyed.

Parameters:

NameTypeDescription
promotionIduint256Id of the promotion being destroyed
recipientaddressAddress of the recipient that will receive the unclaimed rewards
amountuint256Amount of tokens transferred to the recipient

PromotionExtended

  event PromotionExtended(
uint256 promotionId,
uint256 numberOfEpochs
)

Emitted when a promotion is extended.

Parameters:

NameTypeDescription
promotionIduint256Id of the promotion being extended
numberOfEpochsuint256Number of epochs the promotion has been extended by

RewardsClaimed

  event RewardsClaimed(
uint256 promotionId,
uint8[] epochIds,
address user,
uint256 amount
)

Emitted when rewards have been claimed.

Parameters:

NameTypeDescription
promotionIduint256Id of the promotion for which epoch rewards were claimed
epochIdsuint8[]Ids of the epochs being claimed
useraddressAddress of the user for which the rewards were claimed
amountuint256Amount of tokens transferred to the recipient address