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.

Write methods description

initialize()

Allows to initialize the contract during the deployment.

Parameters:

Name	Type	Description
_ticket	address	Address of the prize pool ticket for which the promotions are created.

claimRewards()

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:

Name	Type	Description
_user	address	Address of the user to claim rewards for.
_promotionId	uint256	ID of the promotion to claim rewards for.

Return:

Name	Type	Description
_claimed	uint256	Total amount of rewards claimed.

createPromotion()

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:

Name	Type	Description
_token	address	Address of the token to be distributed.
_startTimestamp	uint64	Timestamp at which the promotion starts.
_tokensPerEpoch	uint256	Number of tokens to be distributed per epoch.
_epochDuration	uint48	Duration of one epoch in seconds.
_numberOfEpochs	uint8	Number of epochs the promotion will last for.

Return:

Name	Type	Description
_promotionId	uint256	ID of the newly created promotion.

destroyPromotion()

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:

Name	Type	Description
_promotionId	uint256	Promotion ID to destroy.
_to	address	Address that will receive the remaining tokens if there are any left.

Return:

Name	Type	Description
_destroyed	bool	True if operation was successful.

endPromotion()

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:

Name	Type	Description
_promotionId	uint256	Promotion ID to end.
_to	address	Address that will receive the remaining tokens if there are any left.

Return:

Name	Type	Description
_ended	bool	True if operation was successful.

extendPromotion()

Extend promotion by adding more epochs.

Parameters:

Name	Type	Description
_promotionId	uint256	ID of the promotion to extend.
_numberOfEpochs	uint8	Number of epochs to add.

Return:

Name	Type	Description
_extended	bool	True if operation was successful.

Read methods description

GRACE_PERIOD()

Period during which the promotion owner can't destroy a promotion.

getCurrentEpochId()

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:

Name	Type	Description
_promotionId	uint256	ID of the promotion to get the current epoch for.

Return:

Name	Type	Description
_epochId	uint256	current epoch ID of the promotion.

getPromotion()

Get settings for a specific promotion.

Parameters:

Name	Type	Description
_promotionId	uint256	ID of the promotion to get settings for.

Return:

Name	Type	Description
_promotion	Promotion	Promotion settings.

getRemainingRewards()

Get the total amount of tokens left to be rewarded.

Parameters:

Name	Type	Description
_promotionId	uint256	ID of the promotion to get the total amount of tokens left to be rewarded for.

Return:

Name	Type	Description
_amount	uint256	Amount of tokens left to be rewarded.

getRewardsAmount()

Get an 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 the user has already claimed rewards for the epoch.

Parameters:

Name	Type	Description
_user	address	Address of the user to get an amount of rewards for.
_promotionId	uint256	ID of the promotion from which the epoch is.
_epochIds	uint8[]	epoch IDs to get reward amount for.

Return:

Name	Type	Description
_rewardsAmount	uint8[]	Amount of tokens per epoch to be rewarded.