> ## Documentation Index
> Fetch the complete documentation index at: https://docs.megapot.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.megapot.io/developers/build/protocol-reference.md) | [`0x3bAe643002069dBCbcd62B1A4eb4C4A397d042a2`](https://basescan.org/address/0x3bAe643002069dBCbcd62B1A4eb4C4A397d042a2) | Main lottery orchestrator |
| [JackpotLPManager](https://docs.megapot.io/developers/build/protocol-reference.md) | [`0xE63E54DF82d894396B885CE498F828f2454d9dCf`](https://basescan.org/address/0xE63E54DF82d894396B885CE498F828f2454d9dCf) | Backer deposit and share management |
| [JackpotTicketNFT](https://docs.megapot.io/developers/build/protocol-reference.md) | [`0x48FfE35AbB9f4780a4f1775C2Ce1c46185b366e4`](https://basescan.org/address/0x48FfE35AbB9f4780a4f1775C2Ce1c46185b366e4) | ERC-721 ticket NFTs |
| [JackpotAutoSubscription](https://docs.megapot.io/developers/build/protocol-reference.md) | [`0x02A58B725116BA687D9356Eafe0fA771d58a37ac`](https://basescan.org/address/0x02A58B725116BA687D9356Eafe0fA771d58a37ac) | Auto-subscription management |
| [BatchPurchaseFacilitator](https://docs.megapot.io/developers/build/protocol-reference.md) | [`0x01774B531591b286b9f02C6Bc02ab3fD9526Aa76`](https://basescan.org/address/0x01774B531591b286b9f02C6Bc02ab3fD9526Aa76) | Batch ticket purchases |
| [TicketAutoCompoundVault](https://docs.megapot.io/developers/build/protocol-reference.md) | [`0x3E22Ea60A1206A4BfEefBCff04D5E9d0A2D9B3Fc`](https://basescan.org/address/0x3E22Ea60A1206A4BfEefBCff04D5E9d0A2D9B3Fc) | Auto-reinvest winnings into new tickets |
| [JackpotRandomTicketBuyer](https://docs.megapot.io/developers/build/protocol-reference.md) | [`0xb9560b43b91dE2c1DaF5dfbb76b2CFcDaFc13aBd`](https://basescan.org/address/0xb9560b43b91dE2c1DaF5dfbb76b2CFcDaFc13aBd) | Random ticket purchases |
| [GuaranteedMinimumPayoutCalculator](https://docs.megapot.io/developers/build/protocol-reference.md) | [`0x97a22361b6208aC8cd9afaea09D20feC47046CBD`](https://basescan.org/address/0x97a22361b6208aC8cd9afaea09D20feC47046CBD) | Prize tier calculations |
| [ScaledEntropyProvider](https://docs.megapot.io/developers/build/protocol-reference.md) | [`0x5D030DEC2e0d38935e662C0d2feD44B050c8Ae51`](https://basescan.org/address/0x5D030DEC2e0d38935e662C0d2feD44B050c8Ae51) | Pyth randomness integration |

You can find contract ABIs and artifacts [here](https://github.com/coordinationlabs/megapot-v2-public)

***

## 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) | Trusted by Polymarket, Morpho, Hyperliquid |
| Code4rena | Nov 2025 | [View Report](https://github.com/coordinationlabs/megapot-v2-audit-reports/blob/main/code4rena/) | Trusted by AAVE, Coinbase, Chainlink |
| Independent Auditors | Dec 2025 | [View Report](https://github.com/coordinationlabs/megapot-v2-audit-reports/tree/main/ind-auditors) | |

> [!WARNING]
>
> **The bug bounty program is no longer active.** New vulnerability submissions will not be addressed. See [Security](https://docs.megapot.io/appendix/security.md) and [Bug Bounty](https://docs.megapot.io/appendix/bug-bounty.md) for the closed program record. [Read Announcement](https://megapot.io/blog/thank-you-for-playing).

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

***

> [!NOTE]
>
> **Looking for read-only off-chain data?** For round history, wallet aggregates, leaderboards, or any cross-drawing analytics, use the [Data API](https://docs.megapot.io/developers/pull-data.md) instead of the contract reads documented below. The API is read-only — keep RPC for live state and writes.

## Architecture

Megapot uses a modular smart contract architecture:

```mermaid theme={null}
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]
        ACV[AutoCompound<br/>Vault]
        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
    ACV --> J
    ACV --> NFT
    ACV --> BF
    BM --> J
    RB --> J

    SEP --> PYTH
```

## Contract Categories

### Core Contracts

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

### User-Facing Contracts

| Contract | Description | Documentation |
| - | - | - |
| [BatchPurchaseFacilitator](https://docs.megapot.io/developers/build/protocol-reference.md) | Bulk ticket orders with static and dynamic tickets | Helper |
| [JackpotAutoSubscription](https://docs.megapot.io/developers/build/protocol-reference.md) | Recurring ticket purchases across drawings | Helper |
| [TicketAutoCompoundVault](https://docs.megapot.io/developers/build/protocol-reference.md) | Auto-reinvest winnings into new tickets | Helper |
| [JackpotBridgeManager](https://docs.megapot.io/developers/build/protocol-reference.md) | Cross-chain ticket purchases and claims | Helper |
| [JackpotRandomTicketBuyer](https://docs.megapot.io/developers/build/protocol-reference.md) | Simple random ticket purchases | Helper |

### Internal Contracts

| Contract | Description | Documentation |
| - | - | - |
| [GuaranteedMinimumPayoutCalculator](https://docs.megapot.io/developers/build/protocol-reference.md) | Prize tier payout calculations | Internal |
| [ScaledEntropyProvider](https://docs.megapot.io/developers/build/protocol-reference.md) | Pyth Network randomness integration | Internal |

## Key Concepts

### Ticket Structure

Tickets consist of 5 normal ball numbers and 1 bonusball:

```solidity theme={null}
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 theme={null}
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 theme={null}
// 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 theme={null}
// 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 theme={null}
// Claim winnings for ticket IDs
uint256[] memory ticketIds = new uint256[](1);
ticketIds[0] = yourTicketId;
jackpot.claimWinnings(ticketIds);
```

### LP Operations

```solidity theme={null}
// Deposit as LP
usdc.approve(jackpotAddress, depositAmount);
jackpot.lpDeposit(depositAmount);

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.