# Jackpot

**Contract Address:** [`0x3bAe643002069dBCbcd62B1A4eb4C4A397d042a2`](https://basescan.org/address/0x3bAe643002069dBCbcd62B1A4eb4C4A397d042a2)

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

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

### DrawingState

```solidity
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

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

## Events

### TicketPurchased

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

### TicketWinningsClaimed

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

### JackpotSettled

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

### NewDrawingInitialized

```solidity
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.

```solidity
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:**

```solidity
// 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.

```solidity
function claimWinnings(uint256[] memory _userTicketIds) external
```

**Parameters:**

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

**Example:**

```solidity
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.

```solidity
function lpDeposit(uint256 _amountToDeposit) external
```

**Parameters:**

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

**Example:**

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

***

### initiateWithdraw

Start LP withdrawal process by converting shares to pending withdrawal.

```solidity
function initiateWithdraw(uint256 _amountToWithdrawInShares) external
```

**Parameters:**

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

**Example:**

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

***

### finalizeWithdraw

Complete pending LP withdrawals and receive USDC.

```solidity
function finalizeWithdraw() external
```

**Example:**

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

***

### emergencyWithdrawLP

Emergency withdrawal for LPs when system is stuck.

```solidity
function emergencyWithdrawLP() external
```

**Requirements:**

* Emergency mode must be enabled

**Example:**

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

***

### emergencyRefundTickets

Refund tickets from the current drawing during emergency mode.

```solidity
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.

```solidity
function claimReferralFees() external
```

**Example:**

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

// Claim all fees
jackpot.claimReferralFees();
```

***

### runJackpot

Execute the drawing by requesting randomness from entropy provider.

```solidity
function runJackpot() external payable
```

**Requirements:**

* Drawing time must have passed
* Drawing must not be locked
* Sufficient ETH for entropy fee

**Example:**

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

***

## View Functions

### getDrawingState

Get complete state for a drawing.

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

**Example:**

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

***

### getReferralScheme

Get referral scheme details.

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

***

### checkIfTicketsBought

Check if specific tickets have been purchased.

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

***

### getUnpackedTicket

Unpack a packed ticket into normal numbers and bonusball.

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

***

### getTicketTierIds

Get prize tier IDs for a list of tickets.

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

***

### getDrawingTierPayouts

Get payout amounts for all tiers in a drawing.

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

***

### getEntropyCallbackFee

Get the ETH fee required to run the jackpot.

```solidity
function getEntropyCallbackFee() external view returns (uint256 fee)
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.megapot.io/developers/contract-overview/jackpot.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.