Contract Overview & Functions
Last updated
Last updated
Liquidity providers deposit liquidity at any time. Their liquidity starts guaranteeing a minimum jackpot starting the next jackpot.
Players can buy jackpot tickets at any time, except when awaiting drawing results.
Users can buy jackpot tickets on behalf of other users/wallets.
Referrers can claim fees instantly after a ticket is purchased.
The jackpot drawing is done every 24 hours. A winning ticket is drawn, liquidity providers' balances are updated, fees are distributed to LPs, and then a new minimum jackpot is realized.
LPs can initiate the process to withdraw liquidity at any time, but it takes one jackpot drawing to complete.
All of these examples are built from the Megapot demo app. Feel free to fork the repo and use it as a starting point for your own project. Or just for a reference implementation.
This is list of all the functions you should be familiar with for a successful integration.
READ FUNCTIONS
WRITE FUNCTIONS
activeLpAddress(uint256) -> address
Starting from 0 returns the address of the active liquidity provider for a given integer.
Output:
lpAddress: The address of the active liquidity provider for the given round.
allowPurchasing() -> bool
Returns a boolean value indicating whether ticket purchasing is allowed.
feeBps() -> uint256
Returns the fee in basis points collected from each ticket purchase.
A value of 1000 means 10% fee. This includes referralFeeBps as well.
Example: If the feeBps is 1_000 and referralFeeBps is 500, if a ticket is purchased with a referrer address set, LPs will receive 5% of the ticket price and the referrer will receive 5% of the ticket price. Otherwise, LPs will receive 10% of the ticket price.
lastJackpotEndTime() -> uint256
Returns the timestamp of the last jackpot end time. Useful for determining the next jackpot start time when combined with roundDurationInSeconds.
lpLimit() -> uint256
Returns the maximum amount of LP wallets that can add LP to the jackpot. We limit this due to contract gas limits.
lpPoolCap() -> uint256
Returns the maximum amount of LP tokens that can be added to the jackpot. We limit this to keep the jackpot from getting too large. A value that is too high can make it extremely difficult for a player to win.
When the lpPoolTotal exceeds the lpPoolCap, no more LPs can add liquidity to the jackpot.
lpPoolTotal() -> uint256
Returns the total amount of LP tokens, in wei, that is currently in range for the jackpot. ie. This is how much a player can win in the current jackpot.
lpsInfo(address) -> principal uint256, stake uint256, riskPercentage uint256, active bool
Returns info about a given LP address.
Output:
principal: The amount of LP tokens in total that the address has added to the jackpot.
stake: The amount of LP tokens that the address has at risk in the current jackpot.
riskPercentage: The risk percentage of the address. 0 - 100
active: Whether the lp is active. When a LP initially deposits, their position is not active until the next jackpot drawing. Similarly, if an LP sets their risk percentage to 0 to withdraw, they will be inactive after the next jackpot drawing.
minLpDeposit() -> uint256
Returns the minimum amount of LP tokens that can be added to the jackpot. This prevents LPs from adding too little liquidity and using up all the lp slots dictated by lpLimit.
referralFeeBps() -> uint256
The fee in basis points collected from each ticket purchase that is given to the referrer. If a ticket is purchased without a referrer, the fee is given to the LPs.
roundDurationInSeconds() -> uint256
Returns the duration of a jackpot round in seconds.
ticketCountTotalBps() -> uint256
Returns the total amount of tickets that have been purchased in basis points. This is a cumulative value. A single ticket entry bought by a users is worth 10_000 basis points. Then the feeBps is removed from this value.
Example: If a player buys 1 ticket, worth 10_000 basis points, and the feeBps is 1000, then the ticketCountTotalBps will be 9_000. The other 1_000 goes to the LPs, and referrer if set on purchase.
ticketPrice() -> uint256
The cost of a single ticket in wei.
token() -> address
Returns the address of the token that is being used for the jackpot. In other words, the erc-20 token the jackpot is denominated in.
tokenDecimals() -> uint256
Returns the number of decimals of the token that is being used for the jackpot. Most erc-20 tokens have 18 decimals. Some like USDC have 6 decimals.
userPoolTotal(address) -> uint256
Returns the total amount of tickets in basis points that are active in the current jackpot. This is a cumulative value.
Example: If players have bought 100 tickets, worth 10_000 basis points each, and the feeBps is 1000, then the userPoolTotal will be 90_000. The other 10_000 goes to the LPs, and referrer if set on purchase.
usersInfo(address) -> ticketsPurchasedTotalBps uint256, winningsClaimable uint256, active bool
Returns info about a given user address.
Output:
ticketsPurchasedTotalBps: The total amount of tickets that the address has purchased in basis points for the current jackpot.
winningsClaimable: The amount of winnings that the address can claim.
active: Whether the user is active in the current jackpot.
lpAdjustRiskPercentage(uint256 riskPercentage) -> bool
Adjusts the risk percentage of the LP. A value between 0 and 100. If the value is set to 0, the LP can withdraw their liquidity after the next jackpot drawing.
Input:
riskPercentage: The risk percentage to set.
lpDeposit(uint256 riskPercentage, uint256 value) -> bool
Adds liquidity to the jackpot. The value must be greater than the minLpDeposit. The total must be less than or equal to the lpPoolCap after the deposit.
Input:
riskPercentage: The risk percentage to set. 0 - 100.
value: The amount of LP tokens to add in wei.
purchaseTickets(address referrer, uint256 value, address recipient) -> bool
Purchases tickets for a given recipient. The value must be increments of the ticketPrice.
If a referrer is set, the referrer will receive a percentage of the ticket price as defined by referralFeeBps. Otherwise, the LPs will receive the fee. If using a referrer, the recipient must be different than the referrer.
If not setting a referrer, the value must be set to the zero address (0x0000000000000000000000000000000000000000).
Similarly, if not setting a recipient, the value must be set to the zero address (0x0000000000000000000000000000000000000000).
Input:
referrer: The address of the referrer, of the zero address if no referrer is set.
value: The amount of tickets to purchase.
recipient: The address of the recipient, of the zero address if the recipient is the msg.sender.
runJackpot(ether payableAmount, bytes32 userRandomNumber) -> bool
Runs the jackpot. This can be called by anyone once the lastJackpotEndTime + roundDurationInSeconds is greater than the current timestamp.
Input:
ether: The amount of ether to pay to the entropy provider to get the random number used to determine the winner.
userRandomNumber: The random number to use for entropy with the entropy provider. This can be any valid bytes32 value. ie. 0x55fb29339a98ca25bedb7b5aa225041f669ca1407e926a95ce4a9b080ac66907
setAllowPurchasing(bool _allow) -> bool
Sets whether purchasing is allowed. Set to 1 to allow purchasing, set to 0 to disallow purchasing.
Input:
_allow: The boolean value to set.
setFeeBps(uint256 _feeBps) -> bool
Sets the fee in basis points collected from each ticket purchase.
Input:
_feeBps: The fee in basis points to set. A value of 1000 means 10% fee.
setLpLimit(uint256 _lpLimit) -> bool
Sets the maximum amount of LP wallets that can add LP to the jackpot. This should not be adjusted. For documentation purposes. A setting too high can prevent the jackpot from executing due to gas limits.
Input:
_lpLimit: The maximum amount of LP wallets to set. Default is 100.
setLpPoolCap(uint256 _cap) -> bool
Sets the maximum amount of LP tokens that can be added to the jackpot. We aim to find a balance between a jackpot that is too large to win, and a jackpot that is too small to be worth playing.
setMinLpDeposit(uint256 _minDeposit) -> bool
Sets the minimum amount of LP tokens that can be added to the jackpot. This prevents LPs from adding too little liquidity and using up all the lp slots dictated by lpLimit.
Input:
_minDeposit: The minimum amount of LP tokens to set. Default is 100x the ticketPrice.
setReferralFeeBps(uint256 _referralFeeBps) -> bool
Sets the fee in basis points collected from each ticket purchase that is given to the referrer. This is taken from the feeBps.
Example: If the feeBps is 1_000 and referralFeeBps is 500, if a ticket is purchased with a referrer address set, LPs will receive 5% of the ticket price and the referrer will receive 5% of the ticket price. Otherwise, LPs will receive 10% of the ticket price.
Input:
_referralFeeBps: The fee in basis points to set. A value of 1000 means 10% fee.
setRoundDurationInSeconds(uint256 _newDuration) -> bool
Sets the duration of a jackpot round in seconds. The contract will not let runJackpot be called until the lastJackpotEndTime + _newDuration is greater than the current timestamp.
Input:
_newDuration: The new duration of a jackpot round in seconds.
setTicketPrice(uint256 _newTicketPrice) -> bool
Sets the price of a single ticket in wei. For example, if the token has 18 decimals, and you want the price to be 100 tokens, you would set the _newTicketPrice to 100 * 10 ** 18.
Input:
_newTicketPrice: The new price of a single ticket in wei.
withdrawAllLp() -> bool
Withdraws all LP tokens from the jackpot. This can only be called by the LPs.
If the LP has a risk percentage > 0, this will not withdraw immediately. Instead it will set their risk percentage to 0 and they will be able to withdraw after the next jackpot drawing.
If the LP has a risk percentage = 0, this will withdraw the liquidity immediately.
withdrawReferralFee() -> bool
Withdraws the referral fee from the jackpot. This can only be called by the referrer. Referrer fees accumulate instantly after a ticket is purchased and can be withdrawn immediately.
withdrawWinnings() -> bool
Withdraws the winnings from the jackpot. This can only be called by a winner.
Jump to