# Contract Overview

This section provides developer reference documentation for Megapot's smart contracts, including function signatures, parameters, and usage examples.

***

## Contract Addresses

All contracts are deployed on **Base** (Chain ID: 8453).

| Contract                          | Address                                      | Description                         |
| --------------------------------- | -------------------------------------------- | ----------------------------------- |
| Jackpot                           | `0x3bAe643002069dBCbcd62B1A4eb4C4A397d042a2` | Main lottery orchestrator           |
| JackpotLPManager                  | `0xE63E54DF82d894396B885CE498F828f2454d9dCf` | Backer deposit and share management |
| JackpotTicketNFT                  | `0x48FfE35AbB9f4780a4f1775C2Ce1c46185b366e4` | ERC-721 ticket NFTs                 |
| JackpotAutoSubscription           | `0x02A58B725116BA687D9356Eafe0fA771d58a37ac` | Auto-subscription management        |
| BatchPurchaseFacilitator          | `0x01774B531591b286b9f02C6Bc02ab3fD9526Aa76` | Batch ticket purchases              |
| JackpotRandomTicketBuyer          | `0xb9560b43b91dE2c1DaF5dfbb76b2CFcDaFc13aBd` | Random ticket purchases             |
| GuaranteedMinimumPayoutCalculator | `0x97a22361b6208aC8cd9afaea09D20feC47046CBD` | Prize tier calculations             |
| ScaledEntropyProvider             | `0x5D030DEC2e0d38935e662C0d2feD44B050c8Ae51` | Pyth randomness integration         |

***

## Security Audits

The Megapot protocol has been independently audited:

| Auditor              | Date     | Report                                                                                             |
| -------------------- | -------- | -------------------------------------------------------------------------------------------------- |
| Zellic               | Oct 2025 | [View Report](https://github.com/coordinationlabs/megapot-v2-audit-reports/tree/main/zellic)       |
| Code4rena            | Nov 2025 | [View Report](https://github.com/coordinationlabs/megapot-v2-audit-reports/blob/main/code4rena/)   |
| Independent Auditors | Dec 2025 | [View Report](https://github.com/coordinationlabs/megapot-v2-audit-reports/tree/main/ind-auditors) |

The Megapot protocol above operates autonomously, enabling anyone to build on it, or use it, without permission.

***

## Architecture

Megapot uses a modular smart contract architecture:

```mermaid
flowchart TB
    subgraph Core["Core Contracts"]
        J[Jackpot]
        NFT[JackpotTicketNFT]
        LP[JackpotLPManager]
        PC[PayoutCalculator]
    end

    subgraph Helpers["User-Facing Helpers"]
        BF[BatchPurchase<br/>Facilitator]
        AS[AutoSubscription]
        BM[BridgeManager]
        RB[RandomTicketBuyer]
    end

    subgraph External["External"]
        SEP[ScaledEntropyProvider]
        PYTH[Pyth Network]
    end

    J --> NFT
    J --> LP
    J --> PC
    J --> SEP

    BF --> J
    AS --> J
    AS --> BF
    BM --> J
    RB --> J

    SEP --> PYTH
```

## Contract Categories

### Core Contracts

| Contract                                                                                    | Description                                                            | Documentation |
| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------- |
| [Jackpot](https://docs.megapot.io/developers/contract-overview/jackpot)                     | Main entry point for ticket purchases, LP operations, and prize claims | Core          |
| [JackpotTicketNFT](https://docs.megapot.io/developers/contract-overview/jackpot-ticket-nft) | ERC-721 NFTs representing lottery tickets                              | Core          |
| [JackpotLPManager](https://docs.megapot.io/developers/contract-overview/jackpot-lp-manager) | Manages LP deposits, withdrawals, and share calculations               | Core          |

### User-Facing Contracts

| Contract                                                                                             | Description                                        | Documentation |
| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------- |
| [BatchPurchaseFacilitator](https://docs.megapot.io/developers/contract-overview/batch-purchase)      | Bulk ticket orders with static and dynamic tickets | Helper        |
| [JackpotAutoSubscription](https://docs.megapot.io/developers/contract-overview/auto-subscription)    | Recurring ticket purchases across drawings         | Helper        |
| [JackpotBridgeManager](https://docs.megapot.io/developers/contract-overview/bridge-manager)          | Cross-chain ticket purchases and claims            | Helper        |
| [JackpotRandomTicketBuyer](https://docs.megapot.io/developers/contract-overview/random-ticket-buyer) | Simple random ticket purchases                     | Helper        |

### Internal Contracts

| Contract                                                                                                    | Description                         | Documentation |
| ----------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------- |
| [GuaranteedMinimumPayoutCalculator](https://docs.megapot.io/developers/contract-overview/payout-calculator) | Prize tier payout calculations      | Internal      |
| [ScaledEntropyProvider](https://docs.megapot.io/developers/contract-overview/entropy-provider)              | Pyth Network randomness integration | Internal      |

## Key Concepts

### Ticket Structure

Tickets consist of 5 normal ball numbers and 1 bonusball:

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

### Drawing State

Each drawing has a complete state record:

```solidity
struct DrawingState {
    uint256 prizePool;          // Total prize available
    uint256 ticketPrice;        // Cost per ticket (USDC)
    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
    uint256 lpEarnings;         // LP revenue from tickets
    uint256 drawingTime;        // When drawing executes
    uint256 winningTicket;      // Packed winning numbers
    uint8 ballMax;              // Max normal ball number
    uint8 bonusballMax;         // Max bonusball number
    IPayoutCalculator payoutCalculator;
    bool jackpotLock;           // True when drawing in progress
}
```

### Prize Tiers

The system uses 12 prize tiers based on matches:

| Tier | Matches | Bonusball | Formula                   |
| ---- | ------- | --------- | ------------------------- |
| 0    | 0       | No        | `0*2 + 0 = 0`             |
| 1    | 0       | Yes       | `0*2 + 1 = 1`             |
| 2    | 1       | No        | `1*2 + 0 = 2`             |
| 3    | 1       | Yes       | `1*2 + 1 = 3`             |
| ...  | ...     | ...       | ...                       |
| 10   | 5       | No        | `5*2 + 0 = 10`            |
| 11   | 5       | Yes       | `5*2 + 1 = 11` (Jackpot!) |

### Referral System

Tickets can include referrers who earn fees:

```solidity
// Referrers array and split weights must match length
// Split weights must sum to 1e18 (PRECISE_UNIT)
address[] referrers;
uint256[] referralSplit;
```

## Integration Quick Start

### Buy Tickets

```solidity
// 1. Approve USDC
usdc.approve(jackpotAddress, ticketCost);

// 2. Define tickets
IJackpot.Ticket[] memory tickets = new IJackpot.Ticket[](1);
tickets[0] = IJackpot.Ticket({
    normals: [1, 2, 3, 4, 5],
    bonusball: 10
});

// 3. Buy tickets
uint256[] memory ticketIds = jackpot.buyTickets(
    tickets,
    recipientAddress,
    new address[](0),     // No referrers
    new uint256[](0),     // No referral splits
    bytes32(0)            // No source tracking
);
```

### Claim Winnings

```solidity
// Claim winnings for ticket IDs
uint256[] memory ticketIds = new uint256[](1);
ticketIds[0] = yourTicketId;
jackpot.claimWinnings(ticketIds);
```

### LP Operations

```solidity
// Deposit as LP
usdc.approve(jackpotAddress, depositAmount);
jackpot.lpDeposit(depositAmount);

// Initiate withdrawal (in shares)
jackpot.initiateWithdraw(shareAmount);

// Finalize withdrawal (after drawing completes)
jackpot.finalizeWithdraw();
```