v3.4.0
Resources
Protocol
Contributing
Security
🖖
Prize Splits
Distribute a percentage of the prize (before awarding winners) on every draw to fixed address.
Introduction
The prize split features (introduced in v3.4.0) allows contract owners to designate a percentage of the awarded prize to a fixed wallet address in every draw period. In other words, prize pools can now directly award a wallet, whether that's a charity organization, prize pool manager, decentralized autonomous organization or any unique combination of prize splits every time a draw occurs.
Example
Setup
Prize Award: $10,000 USDC
Loot Box: $2,500 COMP
Number of Winners: 3
Prize Splits:
- 5% Sponsorship to Gitcoin Developer
- 5% Ticket to PrizePool manager
Outcome
Main Winner: $3,000 and Loot Box ($2,500)
Secondary Winners: $3,000
Prize Splits:
- $500 to Gitcoin Developer Address
- $500 to PrizePool manager
Code
1
PrizeSplitConfig {
2
target: 0x0000000000000000000000000000000000000000 // Gitcoin Wallet
3
percentage: 50 // 5%
4
token: 1 // Sponsorship Token
5
}
6
7
PrizeSplitConfig {
8
target: 0x0000000000000000000000000000000000000001 // Owner Wallet
9
percentage: 50 // 5%
10
token: 0 // Ticket Token
11
}
Copied!
How It Works
The prize split configuration is an abstract contract inherited by any PrizePool smart contract. The PrizeSplit.sol smart contract is a minimal smart contract with limited external functions and a single primary
internal function named _distributePrizeSplits which should be called at the top of the inheriting smart contracts _distribute function.Public Functions
setPrizeSplitssetPrizeSplit
Primary Internal Functions
_distributePrizeSplits
Helper Internal Functions
_getPrizeSplitAmount_totalPrizeSplitPercentageAmount
Prize Split Config (PrizeSplitConfig)
Prize split configurations are saved in a PrizeSplitConfig struct and stored in the internal _prizeSplits array. During the award distribution (before awarding the winners) prize split recipients are awarded the designated token type (Ticket or Sponsorship). After the recipients have been awarded, the remaining updated prize award amount is distributed to the winners.
Prize Splits Configuration
Each prize splits is stored in a
PrizeSplitConfig struct with 3 configurable variables: target, percentage and token. The target variable designates the receiver of the prize split. The percentage variable stores single point decimal precision percentage using a number with a range between 0-to-1000. And finally the token parameter references the index position of the ControlledToken in the PrizePool.tokens array.1
PrizeSplits.sol
2
---------------
3
4
struct PrizeSplitConfig {
5
address target;
6
uint16 percentage;
7
uint8 token;
8
}
Copied!
Target is self-explanatory, but percentage and token require a deeper understanding of percentages are calculated and how an external contract stores token references.
Percentage
The
percentage uses a range of 0-to-1000 so single decimal precision can easily be calculated without requiring a fixed point math library.1
PrizeSplits.sol
2
---------------
3
4
function _getPrizeSplitAmount(uint256 amount, uint16 percentage) internal pure returns (uint256) {
5
return (amount * percentage).div(1000);
6
}
Copied!
When calculating a prize split distribution amount, the result of totalPrizeAmount * prizeSplitPercentage is divided by 1,000. Thus if the prize split percentage is set to
1000 than the distribution amount would result in 100% of the prize being awarded to the prize split. If the the prize split percentage is set to 505 distribution amount would equate to 50.5% of the original award amount. Token
If using the
PoolWithMultipleWinnersBuilder.sol instance to deploy a new PrizePool, the first token stored in the tokens array is the Ticket and the second is the Sponsorship token. Thus, when deciding which token is minted during the prize split distribution, the token variable must be set to either 0 or 1 depending on the desired ticket to be awarded.1
PoolWithMultipleWinnersBuilder.sol
2
----------------------------------
3
4
function _tokens(MultipleWinners _multipleWinners) internal view returns (ControlledTokenInterface[] memory) {
5
ControlledTokenInterface[] memory tokens = new ControlledTokenInterface[](2);
6
tokens[0] = ControlledTokenInterface(address(_multipleWinners.ticket()));
7
tokens[1] = ControlledTokenInterface(address(_multipleWinners.sponsorship()));
8
return tokens;
9
}
10
Copied!
Awarding the Prize Splits
Before the draw winners are award
Tickets the prize splits must first be distributed, so the remaining prize award amount can be used to calculate the winners distribution amount.Thus when the
_distribute function is called within MultipleWinners.sol (responsible for capturing the interest earned during that award period) the captured award balance is immediately passed into the internal_distributePrizeSplits function. Distributing the prize splits to target recipients and returning the updated prize amount for winner award distribution.1
MultipleWinners.sol
2
-------------------
3
4
function _distribute(uint256 randomNumber) internal override {
5
uint256 prize = prizePool.captureAwardBalance();
6
7
// distributes prize to prize splits and returns remaining award.
8
prize = _distributePrizeSplits(prize);
9
10
if (IERC20Upgradeable(address(ticket)).totalSupply() == 0) {
11
emit NoWinners();
12
return;
13
}
14
15
...
16
}
Copied!
Last modified 9mo ago