Jackpot

The main Jackpot contract orchestrates all jackpot operations including ticket purchases, drawings, LP management, and prize distribution.

State Variables

Variable	Type	Description
currentDrawingId	uint256	Current active drawing identifier
ticketPrice	uint256	Cost per ticket in USDC (6 decimals)
normalBallMax	uint8	Maximum value for normal ball numbers
bonusballMin	uint8	Minimum bonusball range
bonusballSoftCap	uint8	Soft cap for bonusball used in pool calculations
bonusballHardCap	uint8	Hard cap for bonusball (cannot be exceeded)
referralFee	uint256	Fraction of ticket price to referrers (1e18 scale)
referralWinShare	uint256	Fraction of winnings shared with referrers
referralFees	mapping(address => uint256)	Accumulated referral fees per address
allowTicketPurchases	bool	Whether ticket purchases are enabled
emergencyMode	bool	Whether emergency mode is active

Structs

Ticket

struct Ticket {
    uint8[] normals;   // 5 unique numbers in [1, ballMax]
    uint8 bonusball;   // 1 number in [1, bonusballMax]
}

DrawingState

struct DrawingState {
    uint256 prizePool;           // Total prize available for distribution
    uint256 ticketPrice;         // Cost per ticket (USDC wei)
    uint256 edgePerTicket;       // LP edge amount per ticket
    uint256 referralWinShare;    // % of winnings to referrers
    uint256 referralFee;         // % of ticket price to referrers
    uint256 globalTicketsBought; // Total tickets sold this drawing
    uint256 lpEarnings;          // LP revenue from ticket sales
    uint256 drawingTime;         // Unix timestamp when drawing executes
    uint256 winningTicket;       // Packed winning numbers (after settlement)
    uint8 ballMax;               // Max normal ball number for this drawing
    uint8 bonusballMax;          // Max bonusball for this drawing
    IPayoutCalculator payoutCalculator;
    bool jackpotLock;            // True when drawing in progress
}

ReferralScheme

struct ReferralScheme {
    address[] referrers;      // Array of referrer addresses
    uint256[] referralSplit;  // PRECISE_UNIT-scaled weights (must sum to 1e18)
}

Events

TicketPurchased

event TicketPurchased(
    address indexed recipient,
    uint256 indexed currentDrawingId,
    bytes32 indexed source,
    uint256 userTicketId,
    uint8[] normals,
    uint8 bonusball,
    bytes32 referralScheme
);

TicketWinningsClaimed

event TicketWinningsClaimed(
    address indexed userAddress,
    uint256 indexed drawingId,
    uint256 userTicketId,
    uint256 matchedNormals,
    bool bonusballMatch,
    uint256 winningsAmount
);

JackpotSettled

event JackpotSettled(
    uint256 indexed drawingId,
    uint256 lpEarnings,
    uint256 userWinnings,
    uint8 winningBonusball,
    uint256 winningNumbers,
    uint256 newDrawingAccumulator
);

NewDrawingInitialized

event NewDrawingInitialized(
    uint256 indexed drawingId,
    uint256 lpPoolTotal,
    uint256 prizePool,
    uint256 ticketPrice,
    uint256 normalBallMax,
    uint8 bonusballMax,
    uint256 referralWinShare,
    uint256 drawingTime
);

Functions

buyTickets

Purchase jackpot tickets for the current drawing.

function buyTickets(
    Ticket[] memory _tickets,
    address _recipient,
    address[] memory _referrers,
    uint256[] memory _referralSplit,
    bytes32 _source
) external returns (uint256[] memory ticketIds)

Parameters:

Name	Type	Description
_tickets	Ticket[]	Array of ticket structs with normal numbers and bonusball
_recipient	address	Address to receive the minted ticket NFTs
_referrers	address[]	Referrer addresses for fee sharing (can be empty)
_referralSplit	uint256[]	PRECISE_UNIT-scaled weights (must sum to 1e18 if provided)
_source	bytes32	Identifier for tracking ticket source (telemetry)

Returns:

Type	Description
uint256[]	Array of minted ticket NFT IDs

Example:

// Approve USDC first
usdc.approve(address(jackpot), 2e6); // $2 for 2 tickets

// Create tickets
IJackpot.Ticket[] memory tickets = new IJackpot.Ticket[](2);
tickets[0] = IJackpot.Ticket({
    normals: new uint8[](5),
    bonusball: 10
});
tickets[0].normals[0] = 1;
tickets[0].normals[1] = 15;
tickets[0].normals[2] = 23;
tickets[0].normals[3] = 42;
tickets[0].normals[4] = 55;

tickets[1] = IJackpot.Ticket({
    normals: new uint8[](5),
    bonusball: 5
});
tickets[1].normals[0] = 7;
tickets[1].normals[1] = 14;
tickets[1].normals[2] = 21;
tickets[1].normals[3] = 28;
tickets[1].normals[4] = 30;

// Buy tickets with referrer
address[] memory referrers = new address[](1);
referrers[0] = 0x1234...;
uint256[] memory splits = new uint256[](1);
splits[0] = 1e18; // 100% to single referrer

uint256[] memory ticketIds = jackpot.buyTickets(
    tickets,
    msg.sender,
    referrers,
    splits,
    bytes32("my-app")
);

---

claimWinnings

Claim prize winnings for completed drawings.

function claimWinnings(uint256[] memory _userTicketIds) external

Parameters:

Name	Type	Description
_userTicketIds	uint256[]	Array of ticket NFT IDs to claim winnings for

Example:

uint256[] memory myTickets = new uint256[](2);
myTickets[0] = ticketId1;
myTickets[1] = ticketId2;

jackpot.claimWinnings(myTickets);
// USDC transferred to msg.sender
// Tickets are burned

---

lpDeposit

Deposit USDC into the prize pool as a liquidity provider.

function lpDeposit(uint256 _amountToDeposit) external

Parameters:

Name	Type	Description
_amountToDeposit	uint256	Amount of USDC to deposit (6 decimals)

Example:

usdc.approve(address(jackpot), 10000e6); // $10,000
jackpot.lpDeposit(10000e6);

---

initiateWithdraw

Start LP withdrawal process by converting shares to pending withdrawal.

function initiateWithdraw(uint256 _amountToWithdrawInShares) external

Parameters:

Name	Type	Description
_amountToWithdrawInShares	uint256	Amount of LP shares to withdraw (1e18 scale)

Example:

// Withdraw 50% of shares
uint256 myShares = lpManager.getLpInfo(msg.sender).consolidatedShares;
jackpot.initiateWithdraw(myShares / 2);

---

finalizeWithdraw

Complete pending LP withdrawals and receive USDC.

function finalizeWithdraw() external

Example:

// After drawing completes
jackpot.finalizeWithdraw();
// USDC transferred to msg.sender

---

emergencyWithdrawLP

Emergency withdrawal for LPs when system is stuck.

function emergencyWithdrawLP() external

Requirements:

• Emergency mode must be enabled

Example:

// Only available in emergency mode
jackpot.emergencyWithdrawLP();

---

emergencyRefundTickets

Refund tickets from the current drawing during emergency mode.

function emergencyRefundTickets(uint256[] memory _userTicketIds) external

Parameters:

Name	Type	Description
_userTicketIds	uint256[]	Array of ticket IDs to refund

Requirements:

• Emergency mode must be active

• Tickets must be from current drawing only

---

claimReferralFees

Claim accumulated referral fees.

function claimReferralFees() external

Example:

// Check balance first
uint256 myFees = jackpot.referralFees(msg.sender);

// Claim all fees
jackpot.claimReferralFees();

---

runJackpot

Execute the drawing by requesting randomness from entropy provider.

function runJackpot() external payable

Requirements:

• Drawing time must have passed

• Drawing must not be locked

• Sufficient ETH for entropy fee

Example:

uint256 fee = jackpot.getEntropyCallbackFee();
jackpot.runJackpot{value: fee}();

---

View Functions

getDrawingState

Get complete state for a drawing.

function getDrawingState(uint256 _drawingId) external view returns (DrawingState memory)

Example:

IJackpot.DrawingState memory state = jackpot.getDrawingState(jackpot.currentDrawingId());
uint256 prizePool = state.prizePool;
uint256 ticketPrice = state.ticketPrice;

---

getReferralScheme

Get referral scheme details.

function getReferralScheme(bytes32 _referralSchemeId) external view returns (ReferralScheme memory)

---

checkIfTicketsBought

Check if specific tickets have been purchased.

function checkIfTicketsBought(uint256 _drawingId, Ticket[] memory _tickets) external view returns (bool[] memory)

---

getUnpackedTicket

Unpack a packed ticket into normal numbers and bonusball.

function getUnpackedTicket(uint256 _drawingId, uint256 _packedTicket) external view returns (uint8[] memory normals, uint8 bonusball)

---

getTicketTierIds

Get prize tier IDs for a list of tickets.

function getTicketTierIds(uint256[] memory _ticketIds) external view returns (uint256[] memory tierIds)

---

getDrawingTierPayouts

Get payout amounts for all tiers in a drawing.

function getDrawingTierPayouts(uint256 _drawingId) external view returns (uint256[12] memory)

---

getEntropyCallbackFee

Get the ETH fee required to run the jackpot.

function getEntropyCallbackFee() external view returns (uint256 fee)