JackpotAutoSubscription

Enables recurring ticket purchases across multiple drawings. Users prepay for a subscription period and keepers execute daily ticket purchases automatically.

State Variables

Variable	Type	Description
jackpot	IJackpot	Immutable reference to Jackpot contract
usdc	IERC20	Immutable USDC token reference
batchFacilitator	IBatchPurchaseFacilitator	Batch facilitator for large orders
subscriptions	mapping(address => Subscription)	Active subscriptions per user
staticTickets	mapping(address => Ticket[])	Static tickets per user
ticketPickerNonce	uint256	Nonce for dynamic ticket generation

Structs

Subscription

struct Subscription {
    uint64 remainingUSDC;           // USDC balance for remaining days
    uint64 lastExecutedDrawing;     // Last drawing tickets were purchased
    uint64 subscribedTicketPrice;   // Price locked at subscription time
    uint64 dynamicTicketCount;      // Random tickets per day
    address[] referrers;            // Referrer addresses
    uint256[] referralSplit;        // PRECISE_UNIT-scaled weights
}

SubscriptionInfo

struct SubscriptionInfo {
    Subscription subscription;       // Subscription details
    IJackpot.Ticket[] staticTickets; // User's static tickets for each day
}

Enums

ExecutionAction

enum ExecutionAction {
    EXECUTE,                       // Execute tickets, subscription continues
    EXECUTE_AND_CLOSE,             // Final execution, subscription completed
    SKIP_ALREADY_EXECUTED,         // Already executed this drawing
    SKIP_NO_ACTIVE_SUBSCRIPTION,   // No active subscription
    SKIP_ACTIVE_BATCH_ORDER,       // Has active batch order, skip
    CANCEL_PRICE_CHANGE,           // Ticket price changed, auto-cancelled
    CANCEL_TOO_MANY_REFERRERS,     // Too many referrers, auto-cancelled
    CANCEL_USER_REQUESTED          // User requested cancellation
}

Events

SubscriptionCreated

event SubscriptionCreated(
    address indexed payer,
    address indexed recipient,
    uint256 totalCost,
    uint256 totalDays,
    uint256 drawingStart,
    uint256 dynamicTicketCount,
    uint256 staticTicketCount,
    uint256 ticketPrice
);

SubscriptionCancelled

event SubscriptionCancelled(
    address indexed recipient,
    ExecutionAction indexed executionAction,
    uint64 refundAmount
);

SubscriptionExecuted

event SubscriptionExecuted(
    address indexed recipient,
    uint256 indexed drawingId,
    uint256[] ticketIds,
    uint256 dynamicTicketsPurchased,
    uint256 staticTicketsPurchased
);

SubscriptionSkipped

event SubscriptionSkipped(
    address indexed recipient,
    uint256 indexed drawingId,
    ExecutionAction indexed executionAction
);

Functions

createSubscription

Create an auto-subscription for consecutive daily ticket purchases.

function createSubscription(
    address _recipient,
    uint64 _totalDays,
    uint64 _dynamicTicketCount,
    IJackpot.Ticket[] calldata _userStaticTickets,
    address[] calldata _referrers,
    uint256[] calldata _referralSplit
) external

Parameters:

Name	Type	Description
_recipient	address	Address to receive ticket NFTs each day
_totalDays	uint64	Number of days to run subscription
_dynamicTicketCount	uint64	Random tickets to purchase per day
_userStaticTickets	Ticket[]	User-defined static tickets per day
_referrers	address[]	Referrer addresses for all purchases
_referralSplit	uint256[]	PRECISE_UNIT-scaled weights (sum to 1e18)

Requirements:

• Recipient must not have an active subscription

• _totalDays must be > 0

• Per-day ticket count (dynamic + static) must be > 0

• Static tickets must have valid numbers

• Caller must have approved sufficient USDC for all days

Example:

// Subscribe for 30 days with 5 random tickets + 2 lucky numbers per day
uint64 days = 30;
uint64 dynamicPerDay = 5;

// My lucky numbers for each day
IJackpot.Ticket[] memory myTickets = new IJackpot.Ticket[](2);
myTickets[0] = IJackpot.Ticket({
    normals: [1, 7, 14, 21, 28],
    bonusball: 7
});
myTickets[1] = IJackpot.Ticket({
    normals: [5, 10, 15, 20, 25],
    bonusball: 5
});

// Calculate total cost: 30 days × 7 tickets × price
uint256 ticketPrice = jackpot.ticketPrice();
uint256 totalCost = days * (dynamicPerDay + myTickets.length) * ticketPrice;

// Approve and subscribe
usdc.approve(address(autoSubscription), totalCost);
autoSubscription.createSubscription(
    msg.sender,
    days,
    dynamicPerDay,
    myTickets,
    new address[](0),   // no referrers
    new uint256[](0)    // no splits
);

---

cancelSubscription

Cancel your active subscription and receive a refund.

function cancelSubscription() external

Requirements:

• Caller must have an active subscription

Example:

// Cancel and get remaining USDC back
autoSubscription.cancelSubscription();

---

getSubscriptionInfo

Get subscription details for a user.

function getSubscriptionInfo(address _recipient) external view returns (SubscriptionInfo memory)

Parameters:

Name	Type	Description
_recipient	address	Address to query

Returns:

Type	Description
SubscriptionInfo	Subscription details and static tickets

Example:

IJackpotAutoSubscription.SubscriptionInfo memory info =
    autoSubscription.getSubscriptionInfo(msg.sender);

uint64 remainingUSDC = info.subscription.remainingUSDC;
uint64 lastExecuted = info.subscription.lastExecutedDrawing;
uint64 ticketsPerDay = info.subscription.dynamicTicketCount +
                       uint64(info.staticTickets.length);

// Calculate remaining days
uint256 ticketPrice = info.subscription.subscribedTicketPrice;
uint256 remainingDays = remainingUSDC / (ticketsPerDay * ticketPrice);

---

getSubscriptionsAction

Get recommended actions for a batch of subscriptions (for keepers).

function getSubscriptionsAction(
    address[] calldata _subscriptions
) external view returns (ExecutionAction[] memory)

Parameters:

Name	Type	Description
_subscriptions	address[]	Addresses to evaluate

Returns:

Type	Description
ExecutionAction[]	Recommended action for each address

Subscription Flow

1. Create: User approves USDC and calls createSubscription

2. Daily Execution: Keepers call executeSubscriptions each day

3. Ticket Purchase: Subscription buys tickets for current drawing

4. Completion: Subscription ends when USDC runs out or user cancels

Price Protection

Subscriptions lock in the ticket price at creation time:

• If ticket price increases, subscription is auto-cancelled with refund

• This protects users from unexpected cost increases

Cancellation Scenarios

Subscriptions are automatically cancelled when:

• Ticket price changes from subscribed price

• Too many referrers (exceeds max allowed)

Integration with Batch Facilitator

Large subscriptions (>= minimum batch size) are routed through the BatchPurchaseFacilitator for efficient execution.