đPrize Pools
Pool deposits and award accrued interest periodically as a prize
Introduction
Prize Pools allow funds to be pooled together into a no-loss yield source, such as Compound, and have the yield safely exposed to a separate Prize Strategy. They are the primary way through which users interact with PoolTogether prize games.
Prize Pools provide controls to the owner so that participation can be made fair. See Fairness for more information.
There is a different type of prize pool for each yield source. For example, if you wish to use Compound you will use the Compound Prize Pool.
All Prize Pools share the functionality below.
Owner
When a Prize Pool is created, the creator is set as the pool's "owner". The owner is able to:
Add additional pool tokens
Change the Prize Strategy
Set the credit rate and credit limit
Shutdown the prize pool
Transfer ownership
Renounce ownership
The prize pool is not upgradeable and therefore the owner can never seize the funds deposited into the prize pool
Limits
When a Prize Pool is created it is initialized with some hard-coded limits to protect users. See Fairness for more details.
Maximum Timelock Duration
The maximum timelock duration ensures that a user has to wait at most X amount of time to withdraw their funds loss-lessly. If the owner of a pool sets the credit rate to be way too low, this limit ensures users will still be able to withdraw.
If using the Single Random Winner Prize Strategy, it would make sense to set the maximum timelock duration to 2x the prize period. That way the owner has some flexibility when adjusting the credit limit and credit rate.
Maximum Credit Limit
The maximum credit limit ensures that the credit limit cannot be set higher than this number. This prevents the owner of the Prize Pool from capturing *all* of a user's deposit at withdrawal time.
Maximum Liquidity Limit
The maximum liquidity limit allows the PrizePool owner to set a cap on the amount of liquidity the pool can hold. This can be set by calling:
Token Model
A Prize Pool accepts a single type of ERC20 token for deposits. This token depends on the implementation: for a Compound Prize Pool bound to cDai it will be Dai, for a yEarn yUSDC vault it will be USDC. This is the underlying asset of the Prize Pool.
Prize Pools use Controlled Tokens for their internal accounting. These tokens are minted when depositing or awarding prizes. Controlled Tokens are burned when users withdraw. They are exchanged at a ratio of 1:1 to the asset.
The tokens associated with a PrizePool can be seen by calling:
Controlled Tokens
A Controlled Token is a standard ERC20 that is bound to a Token Controller.
The Token Controller has the privileged ability to mint and burn tokens on user's behalf, and has a callback that listens for token transfers. Controlled Tokens are expected to trigger this callback on any mint, burns or transfers.
The Prize Pool must be the Token Controller for the controlled tokens that it is initialized with at construction.
The default Compound Prize Pool Builder creates a Ticket controlled token and a Sponsorship controlled token.
A Controlled Token can be added by the PrizePool owner by calling:
Minting
When a user deposits into a Prize Pool they must request what type of controlled token they receive in exchange. This token will be minted to them at an exchange rate of 1:1 for the asset.
Burning
When a user wishes to withdraw from a Prize Pool they must burn controlled tokens.
Depositing
Users can deposit into the Prize Pool using the depositTo function. A user is instantly minted tokens upon deposit.
Depositing fires the event:
Depositing Using Timelocked Funds
If a user wishes to re-deposit their timelocked funds, they can do so using this function:
Withdrawing
When a user withdraws they may need to contribute to the prize according to the fairness rules. They may either cover the contribution by time-locking their funds, or cover the contribution explicitly using funds.
Withdraw with Timelock
Funds can be withdrawn losslessly by time-locking the funds. The withdrawal amount will be unlocked at a later date at which point the funds can be swept back to the user. The timelock duration is calculated based on the users accrued credit, the credit rate, and the fairness fee.
If the user has sufficient credit, the unlockTimestamp may be "now" and the funds are instantly swept to the from
address.
Tip: You can call this function in a constant way to see when the users funds will be unlocked.
To start a lossless withdrawal a user may call:
Checking Timelock Balances
To see how many funds have been timelocked for a user
call:
After funds have been time-locked, you can see at what timestamp they'll be available:
Checking Timelock Duration
To calculate a timelocked withdrawal duration and credit consumption call:
returns:
Estimating Credit Accrual Time
Similarly it is also possible to calculate how long a user must keep their funds in the pool:
Sweeping Timelocked Funds
When a user's withdrawal timelocks have ended, the funds may be swept to their wallets:
The function accepts an array of addresses and will attempt to sweep the time-locked funds for each one. The funds will be transferred back to the users wallets.
Withdraw Instantly
If a user would like their tickets right away, they may pay an early exit fee to the prize. The early exit fee is determined by the Prize Strategy.
The instant withdrawal function returns the amount of the withdrawal that was retained as payment. This means you can call this function in a constant way to check to see what the exit fee will be. When it comes time to run the tx, that exit fee can be passed as the maximumExitFee
to ensure it doesn't exceed the expected limit.
This early exit fee can also be calculated by calling:
returns the exitFee
that would be paid along with the credit that would be burned (burnedCredit
).
Awarding
Only the Prize Strategy can call the award functions. These functions allow prizes to be disbursed to users.
Awarding Yield
Yield that accrues in the Prize Pool can be awarded by the Prize Strategy. The yield must first be captured and then it can be awarded.
To capture the yield the prize strategy can call the captureAwardBalance
function:
This function will:
add the current yield balance to the available award balance
capture a portion for the reserve
return the total available award balance.
To award the captured yield to an address, the Prize strategy uses the award
function. The yield must be awarded as one of the controlled tokens configured in the Prize Pool.
Awarding ERC20s
The Prize Strategy can award ERC20 tokens that are held by the Prize Pool.
However, some tokens are be blacklisted if they need to be held to generate yield (i.e. Compound cTokens).
Awarding ERC721s (NFTs)
The Prize Strategy can award ERC721 tokens that are held by the Prize Pool.
Credit
Credit accrues differently for each of the Prize Pool's controlled tokens, so each token will have its own credit rate and credit limit.
Credit Balance
To get a users credit balance for a controlled token:
Credit Plan
The credit rate and credit limit for a controlled token can be checked like so:
Note that the returned values are "mantissas": i.e. fixed point numbers with 18 decimal places.
Prizes
Current Award Balance
The following function returns the amount calculated by captureAwardBalance()
:
Total Balances
The total of all controlled tokens (including timelocked) can be obtained by calling:
The total underlying balance of all assets (including both principal and interest) can be obtained by calling:
External Prizes
Adding Tokens
The owner can add "external" ERC20 tokens as prizes. The strategy will award the entire balance held by the Prize Pool to the winner.
The owner can add "external" ERC721 tokens as prizes. These tokens will be transferred to the winner.
Checking Tokens
Checks with the Prize Pool if a specific token type (_externalToken
) may be awarded as an external prize:
Prize Time Periods
To retrieve when the current prize started:
To retrieve when the prize will end:
Reserve
Calculate Reserve Fee
Calculates the reserve portion of the given amount
of funds. If there is no reserve address, the Reserve fee portion will be zero.
Prize Strategy
Set the Prize Strategy
The associated Prize Strategy can be set by calling:
Only the Prize Pool owner can call this function.
Last updated