Contract Overview & Functions
Contract Overview
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.
Megapot Demo
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.
Functions
This is list of all the functions you should be familiar with for a successful integration.
Contract Functions
READ FUNCTIONS
WRITE FUNCTIONS
activeLpAddresses
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
allowPurchasing() -> bool
Returns a boolean value indicating whether ticket purchasing is allowed.
feeBps
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
lastJackpotEndTime() -> uint256
Returns the timestamp of the last jackpot end time. Useful for determining the next jackpot start time when combined with roundDurationInSeconds
.
lpLimit
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
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
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
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 - 100active
: 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
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
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
roundDurationInSeconds() -> uint256
Returns the duration of a jackpot round in seconds.
ticketCountTotalBps
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
ticketPrice() -> uint256
The cost of a single ticket in wei.
token
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
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
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
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.
Write Functions
Jump to Read Functions
lpAdjustRiskPercentage
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
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
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
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.
Megapot runs this automatically for all jackpots we deploy. There is no need to call this function. This is for documentation purposes.
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
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
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
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
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
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 theticketPrice
.
setReferralFeeBps
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
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
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
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
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
withdrawWinnings() -> bool
Withdraws the winnings from the jackpot. This can only be called by a winner.
Last updated