TicketAutoCompoundVault

Contract Address: 0x3E22Ea60A1206A4BfEefBCff04D5E9d0A2D9B3Fc

Enables users to automatically reinvest winning ticket prizes into new random tickets. Deposit winning tickets and compound winnings into new entries in a single transaction.

Overview

The vault streamlines the reinvestment flow:

1. User approves the vault once via setApprovalForAll

2. User calls depositAndCompound with winning ticket IDs

3. Vault transfers tickets, claims winnings, and purchases new random tickets

4. Any remainder (less than one ticket's price) is stored for the next compound

This is ideal for third-party integrations that want to offer users a "reinvest winnings" feature without requiring multiple transactions.

For a complete integration guide with pre-flight validation checks, see Add Megapot to Your Site - Auto-Compound Winnings.

State Variables

Variable	Type	Description
jackpot	IJackpot	Immutable reference to Jackpot contract
jackpotNFT	IJackpotTicketNFT	Immutable reference to ticket NFT contract
usdc	IERC20	Immutable USDC token reference
batchFacilitator	IBatchPurchaseFacilitator	Batch facilitator for large orders
userPendingUSDC	mapping(address => uint256)	Accumulated USDC remainder per user
ticketPickerNonce	uint256	Nonce for random ticket generation

Events

Compounded

event Compounded(
    address indexed user,
    uint256 ticketsClaimed,
    uint256 usdcClaimed,
    uint256 ticketsBought,
    uint256 usdcSpent,
    uint256 usdcRemaining,
    bool useBatchPurchase,
    address[] referrers,
    uint256[] referralSplit
);

Emitted when a user successfully compounds winning tickets into new tickets.

Field	Description
user	Address that performed the compound
ticketsClaimed	Number of winning tickets deposited
usdcClaimed	Total USDC claimed from winnings
ticketsBought	Number of new tickets purchased
usdcSpent	USDC spent on new tickets
usdcRemaining	USDC stored for next compound
useBatchPurchase	Whether batch purchase was used (large orders)
referrers	Referrer addresses for the purchase
referralSplit	Fee split weights for referrers

Functions

depositAndCompound

Compound winning tickets into new random tickets in a single transaction.

function depositAndCompound(
    uint256[] calldata _ticketIds,
    address[] calldata _referrers,
    uint256[] calldata _referralSplit
) external

Parameters:

Name	Type	Description
_ticketIds	uint256[]	Array of winning ticket IDs to compound
_referrers	address[]	Referrer addresses for fee sharing (can be empty)
_referralSplit	uint256[]	PRECISE_UNIT-scaled weights (must sum to 1e18 if non-empty)

Requirements:

• User must have approved vault via jackpotNFT.setApprovalForAll(vaultAddress, true)

• All tickets must be owned by the caller

• At least one ticket must have winnings (from a completed drawing)

• Jackpot must not be locked (drawing in progress)

• User must not have an active batch order (if purchase would use batch path)

Example:

// One-time setup: Approve vault to transfer your ticket NFTs
await jackpotNFT.setApprovalForAll(vaultAddress, true);

// Get winning ticket IDs (from a completed drawing)
const winningTicketIds = [123, 456, 789];

// Compound winnings into new tickets
const tx = await vault.depositAndCompound(
    winningTicketIds,
    [],  // no referrers
    []   // no splits
);

await tx.wait();
// New tickets minted to user (or batch order created for large amounts)

With Referrers:

// Compound with referrer fees
const tx = await vault.depositAndCompound(
    winningTicketIds,
    [referrerAddress],           // your referrer address
    [BigInt(1e18)]               // 100% to single referrer
);

---

getUserPendingUSDC

Get the pending USDC balance for a user (remainder from previous compounds).

function getUserPendingUSDC(address _user) external view returns (uint256)

Parameters:

Name	Type	Description
_user	address	Address to query

Returns:

Type	Description
uint256	Pending USDC balance (6 decimals)

Example:

const pendingUSDC = await vault.getUserPendingUSDC(userAddress);
const pendingAmount = Number(pendingUSDC) / 1e6;
console.log(`User has $${pendingAmount} pending for next compound`);

---

Compound Flow

Purchase Paths

The vault automatically selects the optimal purchase path:

Scenario	Path	Execution
< 10 tickets	Direct via Jackpot.buyTickets	Immediate, tickets minted in same tx
>= 10 tickets	Via BatchPurchaseFacilitator	Queued, keepers execute over time

Pending USDC Accumulation

When winnings don't divide evenly by ticket price, the remainder accumulates:

Example:
- Drawing ticket price: $1.00
- User compounds ticket worth $2.50
- Previous pending: $0.30
- Total available: $2.80
- Tickets purchased: 2 ($2.00)
- New pending: $0.80 (carries to next compound)

Integration Guide

Setup (One-Time)

Before users can compound, they must approve the vault:

// Check if already approved
const isApproved = await jackpotNFT.isApprovedForAll(userAddress, vaultAddress);

if (!isApproved) {
    const tx = await jackpotNFT.setApprovalForAll(vaultAddress, true);
    await tx.wait();
}

Finding Winning Tickets

async function getWinningTickets(userAddress: string, drawingId: number) {
    // Get user's tickets for the drawing
    const tickets = await ticketNFT.getUserTickets(userAddress, drawingId);
    const ticketIds = tickets.map(t => t.ticketId);

    // Check which tickets won
    const tierIds = await jackpot.getTicketTierIds(ticketIds);

    // Filter to winning tickets (tier > 0)
    return ticketIds.filter((_, i) => Number(tierIds[i]) > 0);
}

Complete Compound Flow

async function compoundWinnings(
    userAddress: string,
    drawingId: number,
    referrerAddress?: string
) {
    // 1. Ensure approval
    const isApproved = await jackpotNFT.isApprovedForAll(userAddress, vaultAddress);
    if (!isApproved) {
        throw new Error('User must approve vault first');
    }

    // 2. Get winning tickets
    const winningTicketIds = await getWinningTickets(userAddress, drawingId);
    if (winningTicketIds.length === 0) {
        return { message: 'No winning tickets to compound' };
    }

    // 3. Check for active batch order (would block large compounds)
    const hasActiveBatch = await batchFacilitator.hasActiveBatchOrder(userAddress);
    if (hasActiveBatch) {
        throw new Error('User has active batch order - wait for completion');
    }

    // 4. Compound
    const referrers = referrerAddress ? [referrerAddress] : [];
    const splits = referrerAddress ? [BigInt(1e18)] : [];

    const tx = await vault.depositAndCompound(
        winningTicketIds,
        referrers,
        splits
    );

    const receipt = await tx.wait();

    // 5. Parse result from Compounded event
    const event = receipt.logs.find(
        log => log.topics[0] === vault.interface.getEvent('Compounded').topicHash
    );
    const decoded = vault.interface.parseLog(event);

    return {
        ticketsClaimed: Number(decoded.args.ticketsClaimed),
        usdcClaimed: Number(decoded.args.usdcClaimed) / 1e6,
        ticketsBought: Number(decoded.args.ticketsBought),
        usdcRemaining: Number(decoded.args.usdcRemaining) / 1e6,
        usedBatchPurchase: decoded.args.useBatchPurchase
    };
}

Displaying Pending Balance

async function displayCompoundStatus(userAddress: string) {
    const pendingUSDC = await vault.getUserPendingUSDC(userAddress);
    const ticketPrice = (await jackpot.getDrawingState(
        await jackpot.currentDrawingId()
    )).ticketPrice;

    const pendingAmount = Number(pendingUSDC) / 1e6;
    const priceAmount = Number(ticketPrice) / 1e6;
    const neededForTicket = priceAmount - pendingAmount;

    console.log(`Pending balance: $${pendingAmount.toFixed(2)}`);
    console.log(`Current ticket price: $${priceAmount.toFixed(2)}`);

    if (pendingAmount > 0 && neededForTicket > 0) {
        console.log(`Need $${neededForTicket.toFixed(2)} more winnings for next ticket`);
    }
}

Error Handling

Error	Cause	Solution
EmptyTicketArray	Called with no ticket IDs	Provide at least one ticket ID
InvalidClaimedAmount	No tickets had winnings	Ensure tickets are winners from completed drawings
ActiveBatchOrderExists	User has pending batch order	Wait for batch order to complete or cancel it
JackpotLocked	Drawing is in progress	Wait for drawing to complete
NotTicketOwner	Caller doesn't own the tickets	Only compound your own tickets
TransferFromIncorrectOwner	NFT transfer failed	Ensure vault is approved via setApprovalForAll

Best Practices

1. Batch old drawings: Compound tickets from multiple completed drawings at once to save gas

2. Check active batch orders: Before compounding large amounts, verify the user doesn't have an active batch order

3. Display pending balance: Show users their accumulated pending USDC so they understand the system

4. Handle batch path: If useBatchPurchase is true, inform users their tickets will be minted by keepers (not immediately)

5. Referrer integration: Pass your referrer address to earn fees on the new ticket purchases