Smart Contracts

Deployed Contracts

Hyperliquid L1

Contract	Address	Description
LiquidLotteryProxy	<!-- TODO: INSERT_ADDRESS_HERE -->	ERC-1967 proxy — all user interactions go here
HyperLotteryV1 (implementation)	<!-- TODO: INSERT_ADDRESS_HERE -->	UUPS implementation behind the proxy
LotteryMath (library)	<!-- TODO: INSERT_ADDRESS_HERE -->	Core game logic library
LotteryViews (library)	<!-- TODO: INSERT_ADDRESS_HERE -->	Views and admin library

Base

Contract	Address	Description
LotteryVRFRequester	<!-- TODO: INSERT_ADDRESS_HERE -->	VRF + CCIP bridge on Base

---

Source Files

File	Description
HyperLotteryV1.sol	Thin UUPS wrapper; delegates to LotteryMath and LotteryViews
LotteryMath.sol	Core game logic: ticket purchase, draw, settlement, claiming, CCIP send/receive
LotteryViews.sol	View functions, admin setters, timelocks, emergency cancel
LotteryVRFRequester.sol	Deployed on Base; CCIP receiver → VRF request → CCIP fulfillment
LiquidLotteryProxy.sol	Minimal ERC-1967 proxy wrapper

---

Key Functions

Player Functions

Function	Description
buyTickets(whites[], goldNums[], goldPositions[])	Buy one or more tickets for the current round
claimPrize(roundId, ticketIndex)	Claim prize for a single winning ticket
claimPrizeBatch(roundId, ticketIndices[])	Claim prizes for multiple tickets in one transaction
claimPendingPayout()	Withdraw a payout that failed on initial transfer
triggerPublicDraw()	Trigger the draw after the grace period (earns 2 free tickets)
publicEmergencyCancelDraw()	Cancel a stuck draw after 24 hours (earns 2 free tickets)

Settlement Functions (callable by anyone)

Function	Description
settleRound()	Settle a round with ≤ settlementBatchSize tickets
settleRoundBatch()	Settle the next batch of tickets in a large round

Admin Functions (owner only)

Function	Timelock	Description
closeBettingAndDraw()	—	Close the round and send draw request
emergencyCancelDraw()	5 min grace	Cancel a stuck draw
withdrawFees()	—	Withdraw accumulated protocol fees
topUpOwnerFees()	—	Top up the fee pool for CCIP costs
setSettlementBatchSize(n)	—	Set batch size (1–10 000)
setCCIPGasLimit(n)	—	Set CCIP callback gas (100 000–2 000 000)
proposeSetCCIPRouter(addr)	48 h	Propose new CCIP router
proposeSetVRFRequester(addr)	48 h	Propose new VRF requester
proposeSetSourceChainSelector(sel)	48 h	Propose new source chain selector
proposeSetUpkeepInterval(n)	24 h	Propose new upkeep interval
proposeUpgrade(impl)	72 h + 1 h window	Propose proxy implementation upgrade
cancelAdminAction(hash)	—	Cancel any pending timelocked action

---

View Functions

Function	Returns
getCurrentRound()	Current round ID
getRoundInfo(roundId)	Full round state (pools, ticket count, drawn numbers, winners)
getPlayerTickets(roundId, player)	Array of ticket structs for a player in a round
getClaimableAmount(roundId, player)	Total unclaimed prize for a player in a round
getTicketPrice()	Current ticket price in wei
getPendingPayout(player)	Pending payout balance
getFreeTicketCredits(player)	Free ticket credit balance
drawRequestedAt()	Timestamp of the current draw request

---

Constants

Constant	Value	Description
TICKET_PRICE_BPS	5	Ticket price = 0.05 % of pool
MIN_TICKET_PRICE	0.01 ether	Floor ticket price
MAX_TICKETS	25	Max tickets per player per round
MAX_ROUND_TICKETS	10 000	Max tickets per round
JACKPOT_BPS	5 000	50 % to jackpot
SEED_BPS	3 000	30 % to super jackpot seed
FEE_BPS	2 000	20 % protocol fee
SETTLE_REWARD_BPS	100	1 % of fee pool to settler
DRAW_TRIGGER_CREDITS	2	Free tickets for public draw trigger
DRAW_GRACE_PERIOD	300 s	Grace before public draw
ADMIN_TIMELOCK	48 h	Admin action delay
UPGRADE_TIMELOCK	72 h	Upgrade proposal delay
UPGRADE_EXPIRY	1 h	Upgrade execution window
UPKEEP_INTERVAL_TIMELOCK	24 h	Upkeep interval change delay
EMERGENCY_CANCEL_DELAY	24 h	Public emergency cancel delay
MIN_CCIP_GAS_LIMIT	100 000	Minimum CCIP callback gas
MAX_CCIP_GAS_LIMIT	2 000 000	Maximum CCIP callback gas
DEFAULT_CCIP_GAS_LIMIT	500 000	Default CCIP callback gas

---

Events

Game Events

event TicketsPurchased(uint256 indexed roundId, address indexed player, uint256 count);
event DrawRequested(uint256 indexed roundId, bytes32 ccipMessageId);
event NumbersDrawn(uint256 indexed roundId, uint8[5] whites, uint8 goldNum, uint8 goldPos);
event RoundSettled(uint256 indexed roundId, uint256 jackpotWinners, uint256 superWinners);
event PrizeClaimed(uint256 indexed roundId, address indexed player, uint256 amount);
event DrawCancelled(uint256 indexed roundId);
event CCIPDrawFulfilled(uint256 indexed roundId, uint256 randomWord);

Admin Events

event AdminActionProposed(bytes32 indexed actionHash, uint256 executeAfter);
event AdminActionExecuted(bytes32 indexed actionHash);
event AdminActionCancelled(bytes32 indexed actionHash);
event UpgradeProposed(address indexed newImplementation, uint256 executeAfter, uint256 expiresAt);
event UpkeepIntervalProposed(uint256 newInterval, uint256 executeAfter);

Reward Events

event OwnerFeesTopUp(address indexed sender, uint256 amount);
event DrawTriggerRewarded(address indexed caller, uint256 credits);
event SettleRewarded(address indexed caller, uint256 amount);

---

Storage Layout

All contracts share a single ERC-7201 namespaced storage slot:

keccak256("hyperlottery.v1.main.storage")

This ensures the proxy, implementation, and both libraries read and write the same state.