Public Interface

This page is the canonical signature reference for the Quantum Raffle contract. For the semantics of each function see the linked concept page.

Entry paths

receive()  external payable;
fallback() external payable;

fallback() reverts with InvalidRecipientCalldata if msg.data.length != 20, and with InvalidPrizeRecipient if the decoded recipient is address(0).

The host's first entry (sent through receive()) opens game 1 — so the constructor's locked-in config becomes gameConfigRecord[1] at that moment. Subsequent host deposits while a game is active are treated as ordinary entries.

See Game Lifecycle and Cold-Wallet Prize Routing.

Configuration (host)

function setNextGameConfig(
    uint256 _entryAmount,
    uint256 _deadline,
    uint256 _grandPrizeLogBase,
    uint256 _viralityBonusLogBase,
    uint256 _grandPrizeProportion,
    uint256 _viralityBonusProportion,
    uint256 _depositFeeBps,
    uint256 _minTicketsBeforeEnd
) public;

Only the current host can call. Updates nextGameConfig. The new values take effect when the next game starts. Both depositFeeBps and minTicketsBeforeEnd are the trailing fields, in that order. See Parameters.

Power Slot checking

These functions identify the Power Slots — the user-facing name for the winning ticket positions. The contract calls them winners; the docs call them Power Slots. They're the same thing.

function isWinner(uint256 _gameId, uint256 _entrantId) public view returns (bool);
function getNumWinners(uint256 _gameId) public view returns (uint256);
function isPower(uint256 base, uint256 n) public pure returns (bool);
function log(uint256 base, uint256 n) public pure returns (uint256);

isWinner returns true when the entry's position from the end equals grandPrizeLogBase^j for some j — i.e. when the ticket lands a Power Slot. The last entrant (_entrantId == count) always lands a Power Slot. See Power Slots.

Prize claiming

Both grand-prize and adoption-bonus claims honor getPrizeRecipient, so a cold-wallet override set with fallback() at entry time is paid through.

function claimPrize(uint256 _gameId, uint256 _entrantId) external;

struct IdPair { uint256 cohortId; uint256 entrantId; }

function batchClaimAdoptionBonusPrize(
    uint256 _gameId,
    IdPair[] calldata identifications
) external;

function claimAdoptionBonusPrize(
    uint256 _gameId,
    uint256 _entrantId,
    uint256 _cohortId
) external;

See Adoption Bonus & Cohorts.

Host functions

function clearLeftoverAdoptionBonus(uint256 _gameId) external;   // sweep last cohort's pool
function withdrawDepositFees() external;                          // sweep accrued deposit fees

function initiateHostTransfer(address _host) public;              // step 1 of two-step transfer
function acceptHostTransfer() public;                             // step 2 (called by pending host)
function cancelHostTransfer() public;                             // current host aborts pending transfer

Host transfer is two-step with zero-address validation — see Host Guide.

State accessors and view helpers

function host()                    external view returns (address);
function pendingHost()             external view returns (address);
function gameId()                  external view returns (uint256);
function lastTimestamp(uint256 g)  external view returns (uint256);
function entrantCount(uint256 g)   external view returns (uint256);
function prizePool(uint256 g)      external view returns (uint256);
function prizePerWinner(uint256 g) external view returns (uint256);
function accruedDepositFees()      external view returns (uint256);

function entrants(uint256 g, uint256 entrantId)        external view returns (address);
function prizeRecipient(uint256 g, uint256 entrantId)  external view returns (address);
function getPrizeRecipient(uint256 g, uint256 entrantId) public  view returns (address);

function gameConfigRecord(uint256 g)  external view returns (gameConfig memory);
function nextGameConfig()             external view returns (gameConfig memory);

function isGameOver()                                              public view returns (bool);
function getCurrentCohort(uint256 g)                               public view returns (uint256);
function adoptionBonusPrizePool(uint256 g, uint256 cohortId)       external view returns (uint256);
function getAdoptionBonusPrizePerTeam(uint256 g, uint256 cohortId) public view returns (uint256);
function isQualifiedAdoptionBonus(uint256 g, uint256 entrantId, uint256 cohortId) public view returns (bool);

function hasClaimed(uint256 g, uint256 entrantId)                                  external view returns (bool);
function hasClaimedAdoptionBonus(uint256 g, uint256 cohortId, uint256 entrantId)   external view returns (bool);

function participantRecord(address user) external view returns (uint256);  // total ETH ever contributed
function leaderboard(address user)       external view returns (uint256);  // total prizes ever received

There is no standalone depositFeeBps() or minTicketsBeforeEnd() getter; read those fields off gameConfigRecord(gameId) for the active game or nextGameConfig() for the queued one.

Constants

uint256 public constant MAX_DEPOSIT_FEE_BPS = 1000;   // 10% cap
uint256 public constant BPS_DENOMINATOR     = 10000;

Constructor

constructor(
    uint256 _entryAmount,
    uint256 _deadline,
    uint256 _grandPrizeLogBase,
    uint256 _viralityBonusLogBase,
    uint256 _grandPrizeProportion,
    uint256 _viralityBonusProportion,
    uint256 _depositFeeBps,
    uint256 _minTicketsBeforeEnd
);

Validates all 8 parameters and writes them to nextGameConfig. The deployer becomes host. Game 1 starts when the host sends ETH in their first deposit after deployment.