# 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](/developers/contract-overview/jackpot.md)                                     | [`0x3bAe643002069dBCbcd62B1A4eb4C4A397d042a2`](https://basescan.org/address/0x3bAe643002069dBCbcd62B1A4eb4C4A397d042a2) | Main lottery orchestrator               |
| [JackpotLPManager](/developers/contract-overview/jackpot-lp-manager.md)                 | [`0xE63E54DF82d894396B885CE498F828f2454d9dCf`](https://basescan.org/address/0xE63E54DF82d894396B885CE498F828f2454d9dCf) | Backer deposit and share management     |
| [JackpotTicketNFT](/developers/contract-overview/jackpot-ticket-nft.md)                 | [`0x48FfE35AbB9f4780a4f1775C2Ce1c46185b366e4`](https://basescan.org/address/0x48FfE35AbB9f4780a4f1775C2Ce1c46185b366e4) | ERC-721 ticket NFTs                     |
| [JackpotAutoSubscription](/developers/contract-overview/auto-subscription.md)           | [`0x02A58B725116BA687D9356Eafe0fA771d58a37ac`](https://basescan.org/address/0x02A58B725116BA687D9356Eafe0fA771d58a37ac) | Auto-subscription management            |
| [BatchPurchaseFacilitator](/developers/contract-overview/batch-purchase.md)             | [`0x01774B531591b286b9f02C6Bc02ab3fD9526Aa76`](https://basescan.org/address/0x01774B531591b286b9f02C6Bc02ab3fD9526Aa76) | Batch ticket purchases                  |
| [TicketAutoCompoundVault](/developers/contract-overview/ticket-auto-compound-vault.md)  | [`0x3E22Ea60A1206A4BfEefBCff04D5E9d0A2D9B3Fc`](https://basescan.org/address/0x3E22Ea60A1206A4BfEefBCff04D5E9d0A2D9B3Fc) | Auto-reinvest winnings into new tickets |
| [JackpotRandomTicketBuyer](/developers/contract-overview/random-ticket-buyer.md)        | [`0xb9560b43b91dE2c1DaF5dfbb76b2CFcDaFc13aBd`](https://basescan.org/address/0xb9560b43b91dE2c1DaF5dfbb76b2CFcDaFc13aBd) | Random ticket purchases                 |
| [GuaranteedMinimumPayoutCalculator](/developers/contract-overview/payout-calculator.md) | [`0x97a22361b6208aC8cd9afaea09D20feC47046CBD`](https://basescan.org/address/0x97a22361b6208aC8cd9afaea09D20feC47046CBD) | Prize tier calculations                 |
| [ScaledEntropyProvider](/developers/contract-overview/entropy-provider.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)       |
| 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.

***

{% hint style="info" %}
**Looking for read-only off-chain data?** For round history, wallet aggregates, leaderboards, or any cross-drawing analytics, use the [Data API](/developers/data-api.md) instead of the contract reads documented below. The API is read-only — keep RPC for live state and writes.
{% endhint %}

## 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]
        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](/developers/contract-overview/jackpot.md)                     | Main entry point for ticket purchases, LP operations, and prize claims | Core          |
| [JackpotTicketNFT](/developers/contract-overview/jackpot-ticket-nft.md) | ERC-721 NFTs representing lottery tickets                              | Core          |
| [JackpotLPManager](/developers/contract-overview/jackpot-lp-manager.md) | Manages LP deposits, withdrawals, and share calculations               | Core          |

### User-Facing Contracts

| Contract                                                                               | Description                                        | Documentation |
| -------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------- |
| [BatchPurchaseFacilitator](/developers/contract-overview/batch-purchase.md)            | Bulk ticket orders with static and dynamic tickets | Helper        |
| [JackpotAutoSubscription](/developers/contract-overview/auto-subscription.md)          | Recurring ticket purchases across drawings         | Helper        |
| [TicketAutoCompoundVault](/developers/contract-overview/ticket-auto-compound-vault.md) | Auto-reinvest winnings into new tickets            | Helper        |
| [JackpotBridgeManager](/developers/contract-overview/bridge-manager.md)                | Cross-chain ticket purchases and claims            | Helper        |
| [JackpotRandomTicketBuyer](/developers/contract-overview/random-ticket-buyer.md)       | Simple random ticket purchases                     | Helper        |

### Internal Contracts

| Contract                                                                                | Description                         | Documentation |
| --------------------------------------------------------------------------------------- | ----------------------------------- | ------------- |
| [GuaranteedMinimumPayoutCalculator](/developers/contract-overview/payout-calculator.md) | Prize tier payout calculations      | Internal      |
| [ScaledEntropyProvider](/developers/contract-overview/entropy-provider.md)              | 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();
```


---

# 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.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.