Cryo Explorer Ethereum Mainnet

// SPDX-License-Identifier: -- DG --
pragma solidity ^0.8.24;

/**
 * @title WeightedLotteryVRF
 * @notice Weighted lottery with ordered winners and seasonal resets, using Chainlink VRF v2.5 Wrapper (Direct Funding).
 * @author Decentral Games Team
 * @dev
 * - Simple UX: Uses VRFV2PlusWrapperConsumerBase
 * - Lifecycle: upsert/remove -> lock() -> requestDraw() -> fulfillRandomWords() -> finalizeWinners().
 * - Randomness: Direct Funding via wrapper; always pays in native (ETH)
 * - Sampling: Weighted without replacement via Fenwick tree built in memory per finalize call.
 *   Rationale: maintaining a Fenwick tree in storage during upserts/lock significantly increases SSTORE cost
 *   (O(n log n) storage writes across a season) and can trigger out-of-gas with large batches. Rebuilding the
 *   Fenwick in memory at finalization shifts the cost to transient memory (cheap, no long-term rent), keeps the
 *   hot paths (upsert/remove/lock) inexpensive, and enables chunked finalization (maxPicks) by recomputing a
 *   consistent tree each call. Trade-offs: we re-do O(n log n) work per finalize chunk; acceptable because
 *   finalize is called infrequently (once or a few times per season) vs many upserts. This also avoids storage
 *   complexity across season resets and simplifies audits.
 */

import {ConfirmedOwner} from "@chainlink/contracts/src/v0.8/shared/access/ConfirmedOwner.sol";
import {VRFV2PlusWrapperConsumerBase} from "@chainlink/contracts/src/v0.8/vrf/dev/VRFV2PlusWrapperConsumerBase.sol";
import {VRFV2PlusClient} from "@chainlink/contracts/src/v0.8/vrf/dev/libraries/VRFV2PlusClient.sol";

/// @title WeightedLotteryVRF
/// @notice Seasonal weighted lottery using Chainlink VRF v2.5 Wrapper with native funding.
/// @author Lottery-VRF Team
/// @dev See function-level docs for lifecycle, invariants, and Fenwick rationale.
contract WeightedLotteryVRF is VRFV2PlusWrapperConsumerBase, ConfirmedOwner {
    // --- Access model & state machine ---
    // Access: owner + managers via onlyAdmin for operational actions
    // Lifecycle:
    // 1) Pre-lock: upsert/remove entries; winner count configurable. Mapping indexPlus1 may include IDs with zero counts.
    // 2) lock(): compacts in-place (swap-with-last), updates indexPlus1 on-the-fly, sets snapshot totals.
    // 3) requestDraw(): requests 1 VRF word via wrapper (native-only).
    // 4) fulfillRandomWords(): idempotently stores vrfSeed and clears pending markers.
    // 5) finalizeWinners(): in chunks, builds Fenwick tree in memory, picks weighted winners without replacement until done.
    // After finalize completes: drawn=true. emergencyUnlock() is only allowed while locked and not finalized.

    // Roles
    /// @notice Manager accounts allowed to execute operational calls via onlyAdmin.
    mapping(address => bool) public isManager;
    modifier onlyAdmin() {
        require(
            msg.sender == owner() || isManager[msg.sender],
            "only owner or manager"
        );
        _;
    }

    // Season state
    /// @notice Current season identifier.
    string public seasonId;
    /// @notice True once lock() has been called for the season.
    bool public isLocked;
    /// @notice True when all winners have been finalized for the season.
    bool public drawn;
    /// @notice Target number of winners for the season.
    uint256 public winnersCount;

    // Entries
    uint64[] private idList;
    uint64[] private counts;
    mapping(uint64 => uint256) private indexPlus1; // id => idx+1
    // Invariant (post-lock): indexPlus1 mirrors idList exactly (id => position+1). Pre-lock it may include zero-count IDs.

    // Snapshot
    /// @notice Total weight snapshot at lock() (sum of counts > 0).
    uint256 public totalEntriesAtLock;
    /// @notice Number of unique IDs with non-zero entries at lock().
    uint256 public nonZeroIdsAtLock;
    /// @notice Remaining total weight not yet selected during finalization, in case of batched finalization.
    uint256 public remainingWeight;

    // Winners
    struct Winner {
        uint64 id;
        uint64 entriesAtLock;
    }
    /// @notice Ordered list of winners picked so far.
    Winner[] public winners;

    // VRF via Wrapper
    /// @notice Gas limit provided to the VRF wrapper's callback.
    uint32 public callbackGasLimit = 300000;
    /// @notice Number of block confirmations to wait before VRF fulfills.
    uint16 public requestConfirmations = 3;
    // Payment mode fixed to native; LINK payments are intentionally not supported for simplicity.

    /// @notice Last VRF request id (0 when no request is pending).
    uint256 public lastRequestId;
    /// @notice Random seed set by fulfillRandomWords (0 until set).
    uint256 public vrfSeed;
    /// @notice Timestamp when last VRF request was made (0 when none pending).
    uint256 public requestTimestamp;
    /// @notice Minimum seconds to wait before retrying a pending request (0 disables).
    uint256 public requestTimeout = 1 hours; // admin-configurable safety timeout

    // Events
    /// @notice Emitted when a manager account is added/removed.
    /// @param account The manager address.
    /// @param enabled True if enabled, false if removed.
    event ManagerSet(address account, bool enabled);
    /// @notice Emitted when a new season starts.
    /// @param seasonId Human-readable season id.
    /// @param defaultWinners Initial winners target for the season.
    event SeasonStarted(string seasonId, uint256 defaultWinners);
    /// @notice Emitted after upsertEntries runs.
    /// @param count Number of ids processed.
    event EntriesUpserted(uint256 count);
    /// @notice Emitted after removeEntries runs.
    /// @param count Number of ids processed.
    event EntriesRemoved(uint256 count);
    /// @notice Emitted when the season is locked with snapshot totals.
    /// @param totalIds Number of ids with non-zero entries at lock.
    /// @param totalEntries Sum of all entries at lock.
    /// @param winnersCount Winners target (may be clamped to totalIds).
    event Locked(
        string seasonId,
        uint256 totalIds,
        uint256 totalEntries,
        uint256 winnersCount
    );
    /// @notice Emitted when an emergency unlock occurs before finalization.
    event EmergencyUnlocked(string seasonId);
    /// @notice Emitted when a VRF request is made.
    /// @param requestId The VRF request id.
    /// @param nativePayment Always true; wrapper paid in native token.
    event VRFRequested(uint256 requestId, bool nativePayment, string seasonId);
    /// @notice Emitted with the fee actually charged for a VRF request (in wei of native token).
    /// @param requestId The VRF request id.
    /// @param feeWei The fee paid (wrapper + coordinator + premium) in native wei.
    event VRFFeeCharged(uint256 requestId, uint256 feeWei, string seasonId);
    /// @notice Emitted when the VRF seed is set by the callback.
    /// @param requestId The VRF request id.
    /// @param seed The random seed.
    event VRFSeedSet(uint256 requestId, uint256 seed, string seasonId);
    /// @notice Emitted per winner pick (rank starts at 1).
    /// @param rank The 1-based rank in winners array.
    /// @param id The winning id.
    /// @param entriesAtLock The winner's weight at lock.
    event WinnerPicked(
        uint256 rank,
        uint64 id,
        uint64 entriesAtLock,
        string seasonId
    );
    /// @notice Emitted when all winners are finalized.
    /// @param totalWinners Number of winners finalized.
    event DrawFinalized(uint256 totalWinners, string seasonId);
    // Native funding events
    /// @notice Emitted when native funds are received.
    /// @param from Sender address.
    /// @param amount Amount received.
    event NativeFundsReceived(address from, uint256 amount);
    /// @notice Emitted when native funds are withdrawn by the owner.
    /// @param to Recipient address.
    /// @param amount Amount withdrawn.
    event NativeFundsWithdrawn(address to, uint256 amount);

    /// @notice Initializes the contract with a VRF wrapper and initial season.
    /// @param vrfWrapper Address of the Chainlink VRF v2.5 Wrapper.
    /// @param _initialSeasonId Initial season identifier.
    /// @param _defaultWinners Initial winners target for the first season.
    constructor(
        address vrfWrapper,
        string memory _initialSeasonId,
        uint256 _defaultWinners
    ) VRFV2PlusWrapperConsumerBase(vrfWrapper) ConfirmedOwner(msg.sender) {
        _startSeason(_initialSeasonId, _defaultWinners);
    }

    // Admin
    /// @notice Adds or removes manager accounts.
    /// @param addrs List of addresses to update.
    /// @param enabled True to enable, false to disable.
    function setManagers(
        address[] calldata addrs,
        bool enabled
    ) external onlyOwner {
        for (uint256 i = 0; i < addrs.length; ++i) {
            isManager[addrs[i]] = enabled;
            emit ManagerSet(addrs[i], enabled);
        }
    }

    /// @notice Starts a new season; previous season must be unlocked or finalized.
    /// @param newSeasonId New season identifier.
    /// @param defaultWinners Winners target for the new season.
    function startNewSeason(
        string calldata newSeasonId,
        uint256 defaultWinners
    ) external onlyAdmin {
        require(!isLocked || drawn, "previous season not finalized");
        _startSeason(newSeasonId, defaultWinners);
    }

    /// @notice Internal season initializer; resets state and clears mappings.
    /// @param newSeasonId New season identifier.
    /// @param defaultWinners Winners target for the new season.
    function _startSeason(
        string memory newSeasonId,
        uint256 defaultWinners
    ) internal {
        // Clear-first vs selective clearing rationale:
        // - We clear indexPlus1 for ALL current IDs here, then delete/rebuild arrays and repopulate the mapping.
        // - Selective clearing (only deleting keys for removed IDs) is error-prone while compaction/rebuild happens,
        //   because indices shift and some IDs drop to zero. We'd also have to update moved IDs' indices on-the-fly.
        // - Clear-first is linear and simple: remove all mapping entries, rebuild compact arrays, then repopulate an exact
        //   mapping mirror (id => newIndex+1). This avoids stale pointers and out-of-bounds risks.
        // - Gas trade-off is acceptable since season resets are rare vs many upserts.
        // clear mapping for existing IDs
        for (uint256 i = 0; i < idList.length; ) {
            delete indexPlus1[idList[i]];
            unchecked {
                ++i;
            }
        }
        delete idList;
        delete counts;
        delete winners;
        totalEntriesAtLock = 0;
        nonZeroIdsAtLock = 0;
        remainingWeight = 0;
        isLocked = false;
        drawn = false;
        vrfSeed = 0;
        lastRequestId = 0;
        seasonId = bytes(newSeasonId).length == 0
            ? string(abi.encodePacked("Season ", _toString(block.number)))
            : newSeasonId;
        winnersCount = defaultWinners;
        emit SeasonStarted(seasonId, defaultWinners);
    }

    // Pre-lock mutations
    /// @notice Sets the winners target for the current season (pre-lock only).
    /// @param n New winners target.
    function setWinnersCount(uint256 n) external onlyAdmin {
        require(!isLocked, "season locked");
        winnersCount = n;
    }

    /// @notice Upserts entries for ids (pre-lock only). Replaces existing counts.
    /// @param ids List of ids to upsert.
    /// @param newCounts Corresponding weights for each id.
    function upsertEntries(
        uint64[] calldata ids,
        uint64[] calldata newCounts
    ) external onlyAdmin {
        require(!isLocked, "season locked");
        require(ids.length == newCounts.length, "array length mismatch");
        for (uint256 i = 0; i < ids.length; ) {
            uint64 id = ids[i];
            uint256 idxp1 = indexPlus1[id];
            if (idxp1 == 0) {
                idList.push(id);
                counts.push(newCounts[i]);
                indexPlus1[id] = idList.length; // idx+1
            } else {
                counts[idxp1 - 1] = newCounts[i];
            }
            unchecked {
                ++i;
            }
        }
        emit EntriesUpserted(ids.length);
    }

    /// @notice Sets counts to zero for the given ids (pre-lock only).
    /// @param ids List of ids to remove.
    function removeEntries(uint64[] calldata ids) external onlyAdmin {
        require(!isLocked, "season locked");
        for (uint256 i = 0; i < ids.length; ) {
            uint256 idxp1 = indexPlus1[ids[i]];
            if (idxp1 != 0) counts[idxp1 - 1] = 0;
            unchecked {
                ++i;
            }
        }
        emit EntriesRemoved(ids.length);
    }

    // Lock snapshot
    /// @notice Locks the season, compacts arrays in-place, and snapshots totals.
    function lock() external onlyAdmin {
        require(!isLocked, "already locked");
        (uint256 end, uint256 total) = _compactInPlace();
        nonZeroIdsAtLock = end;
        totalEntriesAtLock = total;
        remainingWeight = total;
        if (winnersCount > end) winnersCount = end;
        isLocked = true;
        emit Locked(seasonId, end, total, winnersCount);
    }

    /// @notice Compacts idList/counts in-place via swap-with-last and returns (newLength, totalWeight).
    /// @dev Updates indexPlus1 for moved IDs and deletes mapping for removed IDs. Physically pops tail.
    /// @return end The new compacted logical length after removals.
    /// @return total The total weight (sum of remaining counts) after compaction.
    function _compactInPlace() internal returns (uint256 end, uint256 total) {
        // Invariants during the loop:
        // - We maintain an active region idList[0..end-1] and counts[0..end-1]. Elements in [end..len-1] are garbage.
        // - Mapping correctness: For any position j in [0, end), indexPlus1[idList[j]] == j+1. For removed IDs, the
        //   mapping entry is deleted. We only ever set mapping for IDs we place inside [0, end).
        // - Progress variables: 0 <= i <= end <= len. We increment i only when we keep an element. When we remove at i,
        //   we swap in the last element (end-1) and decrement end, then re-process the same i without incrementing.
        // - Sum correctness: 'total' accumulates the sum of counts for all kept (non-zero) elements encountered so far.
        //   Removed elements contribute 0 to 'total'.
        uint256 len = idList.length;
        end = len; // new logical length after compaction
        total = 0;
        uint256 i = 0;
        while (i < end) {
            uint64 cid = idList[i];
            uint64 c = counts[i];
            if (c == 0) {
                // Remove this ID by swapping in the last element (if different)
                uint256 lastIndex = end - 1;
                uint64 lastId = idList[lastIndex];
                uint64 lastCount = counts[lastIndex];
                // Delete mapping for removed id
                delete indexPlus1[cid];
                if (i != lastIndex) {
                    idList[i] = lastId;
                    counts[i] = lastCount;
                    // Update mapping for the moved id
                    indexPlus1[lastId] = i + 1;
                }
                // Shrink logical end; do not increment i to process the swapped-in element
                end = lastIndex;
            } else {
                // Keep; accumulate total and advance
                unchecked {
                    total += c;
                }
                unchecked {
                    ++i;
                }
            }
        }
        // Physically shrink arrays to 'end'
        while (idList.length > end) {
            idList.pop();
            counts.pop();
        }
        // Post-conditions: arrays compact; mapping mirrors idList; 'total' equals sum of remaining counts.
        return (end, total);
    }

    /// @notice Unlocks a locked season before finalization (emergency only).
    function emergencyUnlock() external onlyAdmin {
        require(isLocked && !drawn, "must be locked and not finalized");
        isLocked = false;
        emit EmergencyUnlocked(seasonId);
    }

    // VRF Wrapper config
    /// @notice Sets VRF wrapper config parameters.
    /// @param _callbackGasLimit Gas limit for the wrapper callback.
    /// @param _confirmations Number of block confirmations to wait.
    function setWrapperConfig(
        uint32 _callbackGasLimit,
        uint16 _confirmations
    ) external onlyAdmin {
        callbackGasLimit = _callbackGasLimit;
        requestConfirmations = _confirmations;
    }

    /// @notice Sets the timeout window to allow retrying a stuck VRF request.
    /// @param seconds_ Seconds to wait before allowing a retry (0 disables).
    function setRequestTimeout(uint256 seconds_) external onlyAdmin {
        // 0 disables timeout protection (not recommended)
        requestTimeout = seconds_;
    }

    // --- Native funding (for wrapper payments) ---
    // The VRF v2.5 Wrapper will pull native funds from this contract when using requestRandomnessPayInNative.
    // Fund this contract by sending native tokens (ETH) directly to it. We expose receive/fallback and
    // a simple withdraw for the owner.
    /// @notice Accept native token funding for VRF payments.
    receive() external payable {
        emit NativeFundsReceived(msg.sender, msg.value);
    }
    /// @notice Fallback to accept native token funding.
    fallback() external payable {
        emit NativeFundsReceived(msg.sender, msg.value);
    }

    /// @notice Withdraws native funds to an address (owner-only).
    /// @param to Recipient address.
    /// @param amount Amount to withdraw.
    function withdrawNative(
        address payable to,
        uint256 amount
    ) external onlyOwner {
        require(to != address(0), "zero to");
        require(amount > 0, "amount is zero");
        // Strict-inequality friendly form: allow equality via logical OR
        uint256 bal = address(this).balance;
        require(bal > amount || bal == amount, "insufficient balance");
        (bool ok, ) = to.call{value: amount}("");
        require(ok, "withdraw failed");
        emit NativeFundsWithdrawn(to, amount);
    }

    // Request randomness via wrapper
    /// @notice Requests VRF randomness (native payment pulled from this contract's balance; non-payable like Chainlink sample).
    /// @return requestId The VRF request identifier.
    function requestDraw() external onlyAdmin returns (uint256 requestId) {
        require(isLocked, "season not locked");
        require(!drawn, "already finalized");
        require(vrfSeed == 0, "seed already set");
        if (lastRequestId != 0 && requestTimeout != 0) {
            uint256 readyAt = requestTimestamp + requestTimeout;
            // Strict-inequality friendly form: allow equality via logical OR
            require(
                block.timestamp > readyAt || block.timestamp == readyAt,
                "pending; wait timeout"
            );
        }
        require(winnersCount > 0, "winners count is zero");
        // We only need a single 256-bit word; we stretch it deterministically
        // for multiple picks during finalization. Requesting more words costs
        // more and increases callback gas without improving security here.
        bytes memory extraArgs = VRFV2PlusClient._argsToBytes(
            VRFV2PlusClient.ExtraArgsV1({nativePayment: true})
        );
        uint256 feeWei;
        (requestId, feeWei) = requestRandomnessPayInNative(
            callbackGasLimit,
            requestConfirmations,
            1,
            extraArgs
        );
        lastRequestId = requestId;
        requestTimestamp = block.timestamp;
        emit VRFRequested(requestId, true, seasonId);
        emit VRFFeeCharged(requestId, feeWei, seasonId);
        return requestId;
    }

    // VRF callback
    /// @notice VRF callback hook sets the seed once; late/duplicate calls are ignored.
    /// @param requestId The VRF request id.
    /// @param randomWords Array with a single random word.
    function fulfillRandomWords(
        uint256 requestId,
        uint256[] memory randomWords
    ) internal override {
        /// @dev Idempotent callback: ignores late/duplicate callbacks instead of reverting.
        if (!(isLocked && !drawn)) return;
        if (vrfSeed != 0) return;
        vrfSeed = randomWords[0];
        // Clear pending markers to reflect success
        lastRequestId = 0;
        requestTimestamp = 0;
        emit VRFSeedSet(requestId, vrfSeed, seasonId);
    }

    // Finalization
    /// @notice Picks up to maxPicks winners (weighted without replacement) until winnersCount is reached.
    /// @param maxPicks Maximum winners to finalize in this transaction. To be used to batch the operation in case revealing all winners in a single call passes the gas limits.
    function finalizeWinners(uint256 maxPicks) external onlyAdmin {
        // Trade-off rationale:
        // - Pros: avoids O(n log n) SSTORE during upserts/lock; reduces gas on hot paths; no storage state to keep in sync
        //   across season resets; enables chunked finalize (we recompute a clean tree each call for maxPicks).
        // - Cons: recomputation costs O(n log n) memory ops per call; acceptable since finalize is rare compared to upserts.
        // - Security: we zero out picked counts and use remainingWeight so recomputation remains consistent across chunks.
        require(isLocked, "season not locked");
        require(vrfSeed != 0, "random seed not set");
        require(winners.length < winnersCount, "all winners already finalized");
        require(maxPicks > 0, "maxPicks must be > 0");
        uint256 picks = _min(maxPicks, winnersCount - winners.length);
        uint256 n = counts.length;
        uint256[] memory fenwickMem = new uint256[](n + 1);
        _buildFenwickFromCounts(fenwickMem);
        uint256 bit = _largestPowerOfTwoLE(n);
        for (uint256 i = 0; i < picks; ) {
            bool done = _pickOneWinner(fenwickMem, bit, n);
            if (done) return;
            unchecked {
                ++i;
            }
        }
        if (winners.length == winnersCount) {
            drawn = true;
            emit DrawFinalized(winners.length, seasonId);
        }
    }

    /// @notice Builds Fenwick tree in memory from current counts[].
    /// @param fenwickMem The Fenwick array (length n+1) to populate from counts[].
    function _buildFenwickFromCounts(
        uint256[] memory fenwickMem
    ) internal view {
        uint256 n = counts.length;
        for (uint256 i = 0; i < n; ) {
            uint256 c = counts[i];
            if (c > 0) _fenwickAddMem(fenwickMem, i + 1, c);
            unchecked {
                ++i;
            }
        }
    }

    /// @notice Returns the largest power of two <= n using strict inequality form.
    /// @param n The number of elements in the Fenwick tree (counts length).
    /// @return bit The largest power-of-two step not exceeding n.
    function _largestPowerOfTwoLE(
        uint256 n
    ) internal pure returns (uint256 bit) {
        bit = 1;
        while ((bit << 1) < (n + 1)) {
            bit <<= 1;
        }
    }

    /// @notice Picks one winner, mutating fenwickMem, counts, remainingWeight; finalizes if none left.
    /// @param fenwickMem The Fenwick array over current (non-zero) counts.
    /// @param bit The largest power-of-two step size for Fenwick search.
    /// @param n The number of entries (counts length).
    /// @return done True if drawing completed in this call (remainingWeight == 0), and DrawFinalized emitted.
    function _pickOneWinner(
        uint256[] memory fenwickMem,
        uint256 bit,
        uint256 n
    ) internal returns (bool done) {
        uint256 rw = remainingWeight;
        if (rw == 0) {
            drawn = true;
            emit DrawFinalized(winners.length, seasonId);
            return true;
        }
        uint256 rnd = uint256(
            keccak256(abi.encode(vrfSeed, seasonId, winners.length))
        );
        uint256 ticket = rnd % rw;
        uint256 idx = _fenwickFindMem(fenwickMem, bit, n, ticket + 1);
        uint256 arrIdx = idx - 1;
        uint64 idVal = idList[arrIdx];
        uint64 cnt = counts[arrIdx];
        winners.push(Winner({id: idVal, entriesAtLock: cnt}));
        emit WinnerPicked(winners.length, idVal, cnt, seasonId);
        if (cnt > 0) {
            _fenwickSubMem(fenwickMem, idx, cnt);
            unchecked {
                remainingWeight = rw - cnt;
            }
        }
        counts[arrIdx] = 0;
        return false;
    }

    // Views
    /// @notice Returns the current entries count for an id.
    /// @param id The id to query.
    /// @return entries The current count.
    function entryOf(uint64 id) external view returns (uint64 entries) {
        uint256 p = indexPlus1[id];
        if (p == 0) return 0;
        return counts[p - 1];
    }
    /// @notice Returns the winner at given 1-based rank.
    /// @param rank1 1-based rank in winners array.
    /// @return w Winner struct at that rank.
    function getWinner(uint256 rank1) external view returns (Winner memory w) {
        // Use strict inequality form
        require(rank1 != 0 && rank1 < winners.length + 1, "rank out of bounds");
        return winners[rank1 - 1];
    }
    /// @notice Returns parallel arrays of winner ids and their entries at lock.
    /// @return ids Winner ids in order.
    /// @return entriesAtLock Entries-at-lock for each winner.
    function getWinners()
        external
        view
        returns (uint64[] memory ids, uint64[] memory entriesAtLock)
    {
        uint256 n = winners.length;
        ids = new uint64[](n);
        entriesAtLock = new uint64[](n);
        for (uint256 i = 0; i < n; ) {
            Winner memory w = winners[i];
            ids[i] = w.id;
            entriesAtLock[i] = w.entriesAtLock;
            unchecked {
                ++i;
            }
        }
    }

    /// @notice Computes live totals over entries regardless of lock state.
    /// @dev O(n) over the current tracked ids. Safe for off-chain calls; avoid heavy on-chain use.
    /// @return idsTracked Number of ids currently tracked (pre-lock may include zero-count ids).
    /// @return nonZeroIds Number of ids with count > 0 at the moment of the call.
    /// @return totalWeight Sum of all counts > 0 at the moment of the call.
    function currentTotals()
        external
        view
        returns (uint256 idsTracked, uint256 nonZeroIds, uint256 totalWeight)
    {
        uint256 len = idList.length;
        idsTracked = len;
        uint256 nz = 0;
        uint256 sum = 0;
        for (uint256 i = 0; i < len; ) {
            uint256 c = counts[i];
            if (c > 0) {
                unchecked {
                    ++nz;
                    sum += c;
                }
            }
            unchecked {
                ++i;
            }
        }
        return (idsTracked, nz, sum);
    }

    // Fenwick helpers (memory)
    // Note: memory-only Fenwick helpers; we deliberately avoid storage writes for gas and simplicity reasons.
    // Fenwick basics:
    // - f[] encodes partial sums so that adding at index i updates f[i], f[i + LSB(i)], f[i + 2*LSB(i)], ...
    // - LSB(i) (least significant set bit) is computed as i & (~i + 1) (two's complement trick).
    // - Prefix sums and find-by-prefix operations run in O(log n).
    /// @notice Fenwick tree point add (memory-only, 1-based index).
    /// @param f Fenwick array (length n+1).
    /// @param i Index (1-based).
    /// @param delta Amount to add.
    function _fenwickAddMem(
        uint256[] memory f,
        uint256 i,
        uint256 delta
    ) internal pure {
        uint256 n = f.length - 1;
        uint256 limit = n + 1;
        while (i < limit) {
            f[i] += delta;
            i += i & (~i + 1); // advance by LSB(i)
        }
    }
    /// @notice Fenwick tree point subtract (memory-only, 1-based index).
    /// @param f Fenwick array (length n+1).
    /// @param i Index (1-based).
    /// @param amount Amount to subtract.
    function _fenwickSubMem(
        uint256[] memory f,
        uint256 i,
        uint256 amount
    ) internal pure {
        uint256 n = f.length - 1;
        uint256 limit = n + 1;
        while (i < limit) {
            f[i] -= amount;
            i += i & (~i + 1); // advance by LSB(i)
        }
    }
    /// @notice Fenwick find-by-prefix-sum (memory-only).
    /// @param f Fenwick array (length n+1).
    /// @param bit Largest power-of-two step <= n.
    /// @param n Number of elements (not including f[0]).
    /// @param target The 1-based rank to find.
    /// @return idx 1-based index of the found element.
    function _fenwickFindMem(
        uint256[] memory f,
        uint256 bit,
        uint256 n,
        uint256 target
    ) internal pure returns (uint256 idx) {
        idx = 0;
        uint256 sum = 0;
        uint256 limit = n + 1;
        for (; bit > 0; bit >>= 1) {
            uint256 next = idx + bit;
            if (next < limit && sum + f[next] < target) {
                sum += f[next];
                idx = next;
            }
        }
        return idx + 1;
    }

    // Utils
    /// @notice Returns the smaller of two numbers.
    /// @param a First number.
    /// @param b Second number.
    /// @return The minimum of a and b.
    function _min(uint256 a, uint256 b) internal pure returns (uint256) {
        return a < b ? a : b;
    }
    /// @notice Converts uint256 to decimal string without leading zeros.
    /// @param value The value to convert.
    /// @return str The decimal string.
    function _toString(
        uint256 value
    ) internal pure returns (string memory str) {
        if (value == 0) return "0";
        uint256 temp = value;
        uint256 digits;
        while (temp != 0) {
            ++digits;
            temp /= 10;
        }
        bytes memory buffer = new bytes(digits);
        while (value != 0) {
            --digits;
            buffer[digits] = bytes1(uint8(48 + uint256(value % 10)));
            value /= 10;
        }
        return string(buffer);
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.4;

// End consumer library.
library VRFV2PlusClient {
  // extraArgs will evolve to support new features
  bytes4 public constant EXTRA_ARGS_V1_TAG = bytes4(keccak256("VRF ExtraArgsV1"));

  struct ExtraArgsV1 {
    bool nativePayment;
  }

  struct RandomWordsRequest {
    bytes32 keyHash;
    uint256 subId;
    uint16 requestConfirmations;
    uint32 callbackGasLimit;
    uint32 numWords;
    bytes extraArgs;
  }

  function _argsToBytes(
    ExtraArgsV1 memory extraArgs
  ) internal pure returns (bytes memory bts) {
    return abi.encodeWithSelector(EXTRA_ARGS_V1_TAG, extraArgs);
  }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import {LinkTokenInterface} from "../../shared/interfaces/LinkTokenInterface.sol";
import {IVRFV2PlusWrapper} from "./interfaces/IVRFV2PlusWrapper.sol";

/**
 *
 * @notice Interface for contracts using VRF randomness through the VRF V2 wrapper
 * ********************************************************************************
 * @dev PURPOSE
 *
 * @dev Create VRF V2+ requests without the need for subscription management. Rather than creating
 * @dev and funding a VRF V2+ subscription, a user can use this wrapper to create one off requests,
 * @dev paying up front rather than at fulfillment.
 *
 * @dev Since the price is determined using the gas price of the request transaction rather than
 * @dev the fulfillment transaction, the wrapper charges an additional premium on callback gas
 * @dev usage, in addition to some extra overhead costs associated with the VRFV2Wrapper contract.
 * *****************************************************************************
 * @dev USAGE
 *
 * @dev Calling contracts must inherit from VRFV2PlusWrapperConsumerBase. The consumer must be funded
 * @dev with enough LINK or ether to make the request, otherwise requests will revert. To request randomness,
 * @dev call the 'requestRandomWords' function with the desired VRF parameters. This function handles
 * @dev paying for the request based on the current pricing.
 *
 * @dev Consumers must implement the fullfillRandomWords function, which will be called during
 * @dev fulfillment with the randomness result.
 */
abstract contract VRFV2PlusWrapperConsumerBase {
  error OnlyVRFWrapperCanFulfill(address have, address want);

  LinkTokenInterface internal immutable i_linkToken;
  IVRFV2PlusWrapper public immutable i_vrfV2PlusWrapper;

  /**
   * @param _vrfV2PlusWrapper is the address of the VRFV2Wrapper contract
   */
  constructor(
    address _vrfV2PlusWrapper
  ) {
    IVRFV2PlusWrapper vrfV2PlusWrapper = IVRFV2PlusWrapper(_vrfV2PlusWrapper);

    i_linkToken = LinkTokenInterface(vrfV2PlusWrapper.link());
    i_vrfV2PlusWrapper = vrfV2PlusWrapper;
  }

  /**
   * @dev Requests randomness from the VRF V2+ wrapper.
   *
   * @param _callbackGasLimit is the gas limit that should be used when calling the consumer's
   *        fulfillRandomWords function.
   * @param _requestConfirmations is the number of confirmations to wait before fulfilling the
   *        request. A higher number of confirmations increases security by reducing the likelihood
   *        that a chain re-org changes a published randomness outcome.
   * @param _numWords is the number of random words to request.
   *
   * @return requestId is the VRF V2+ request ID of the newly created randomness request.
   */
  // solhint-disable-next-line chainlink-solidity/prefix-internal-functions-with-underscore
  function requestRandomness(
    uint32 _callbackGasLimit,
    uint16 _requestConfirmations,
    uint32 _numWords,
    bytes memory extraArgs
  ) internal returns (uint256 requestId, uint256 reqPrice) {
    reqPrice = i_vrfV2PlusWrapper.calculateRequestPrice(_callbackGasLimit, _numWords);
    i_linkToken.transferAndCall(
      address(i_vrfV2PlusWrapper), reqPrice, abi.encode(_callbackGasLimit, _requestConfirmations, _numWords, extraArgs)
    );
    return (i_vrfV2PlusWrapper.lastRequestId(), reqPrice);
  }

  // solhint-disable-next-line chainlink-solidity/prefix-internal-functions-with-underscore
  function requestRandomnessPayInNative(
    uint32 _callbackGasLimit,
    uint16 _requestConfirmations,
    uint32 _numWords,
    bytes memory extraArgs
  ) internal returns (uint256 requestId, uint256 requestPrice) {
    requestPrice = i_vrfV2PlusWrapper.calculateRequestPriceNative(_callbackGasLimit, _numWords);
    return (
      i_vrfV2PlusWrapper.requestRandomWordsInNative{value: requestPrice}(
        _callbackGasLimit, _requestConfirmations, _numWords, extraArgs
      ),
      requestPrice
    );
  }

  /**
   * @notice fulfillRandomWords handles the VRF V2 wrapper response. The consuming contract must
   * @notice implement it.
   *
   * @param _requestId is the VRF V2 request ID.
   * @param _randomWords is the randomness result.
   */
  // solhint-disable-next-line chainlink-solidity/prefix-internal-functions-with-underscore
  function fulfillRandomWords(uint256 _requestId, uint256[] memory _randomWords) internal virtual;

  function rawFulfillRandomWords(uint256 _requestId, uint256[] memory _randomWords) external {
    address vrfWrapperAddr = address(i_vrfV2PlusWrapper);
    if (msg.sender != vrfWrapperAddr) {
      revert OnlyVRFWrapperCanFulfill(msg.sender, vrfWrapperAddr);
    }
    fulfillRandomWords(_requestId, _randomWords);
  }

  /// @notice getBalance returns the native balance of the consumer contract
  function getBalance() public view returns (uint256) {
    return address(this).balance;
  }

  /// @notice getLinkToken returns the link token contract
  function getLinkToken() public view returns (LinkTokenInterface) {
    return i_linkToken;
  }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import {ConfirmedOwnerWithProposal} from "./ConfirmedOwnerWithProposal.sol";

/// @title The ConfirmedOwner contract
/// @notice A contract with helpers for basic contract ownership.
contract ConfirmedOwner is ConfirmedOwnerWithProposal {
  constructor(
    address newOwner
  ) ConfirmedOwnerWithProposal(newOwner, address(0)) {}
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

interface IVRFV2PlusWrapper {
  /**
   * @return the request ID of the most recent VRF V2 request made by this wrapper. This should only
   * be relied option within the same transaction that the request was made.
   */
  function lastRequestId() external view returns (uint256);

  /**
   * @notice Calculates the price of a VRF request with the given callbackGasLimit at the current
   * @notice block.
   *
   * @dev This function relies on the transaction gas price which is not automatically set during
   * @dev simulation. To estimate the price at a specific gas price, use the estimatePrice function.
   *
   * @param _callbackGasLimit is the gas limit used to estimate the price.
   * @param _numWords is the number of words to request.
   */
  function calculateRequestPrice(uint32 _callbackGasLimit, uint32 _numWords) external view returns (uint256);

  /**
   * @notice Calculates the price of a VRF request in native with the given callbackGasLimit at the current
   * @notice block.
   *
   * @dev This function relies on the transaction gas price which is not automatically set during
   * @dev simulation. To estimate the price at a specific gas price, use the estimatePrice function.
   *
   * @param _callbackGasLimit is the gas limit used to estimate the price.
   * @param _numWords is the number of words to request.
   */
  function calculateRequestPriceNative(uint32 _callbackGasLimit, uint32 _numWords) external view returns (uint256);

  /**
   * @notice Estimates the price of a VRF request with a specific gas limit and gas price.
   *
   * @dev This is a convenience function that can be called in simulation to better understand
   * @dev pricing.
   *
   * @param _callbackGasLimit is the gas limit used to estimate the price.
   * @param _numWords is the number of words to request.
   * @param _requestGasPriceWei is the gas price in wei used for the estimation.
   */
  function estimateRequestPrice(
    uint32 _callbackGasLimit,
    uint32 _numWords,
    uint256 _requestGasPriceWei
  ) external view returns (uint256);

  /**
   * @notice Estimates the price of a VRF request in native with a specific gas limit and gas price.
   *
   * @dev This is a convenience function that can be called in simulation to better understand
   * @dev pricing.
   *
   * @param _callbackGasLimit is the gas limit used to estimate the price.
   * @param _numWords is the number of words to request.
   * @param _requestGasPriceWei is the gas price in wei used for the estimation.
   */
  function estimateRequestPriceNative(
    uint32 _callbackGasLimit,
    uint32 _numWords,
    uint256 _requestGasPriceWei
  ) external view returns (uint256);

  /**
   * @notice Requests randomness from the VRF V2 wrapper, paying in native token.
   *
   * @param _callbackGasLimit is the gas limit for the request.
   * @param _requestConfirmations number of request confirmations to wait before serving a request.
   * @param _numWords is the number of words to request.
   */
  function requestRandomWordsInNative(
    uint32 _callbackGasLimit,
    uint16 _requestConfirmations,
    uint32 _numWords,
    bytes calldata extraArgs
  ) external payable returns (uint256 requestId);

  function link() external view returns (address);
  function linkNativeFeed() external view returns (address);
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

// solhint-disable-next-line interface-starts-with-i
interface LinkTokenInterface {
  function allowance(address owner, address spender) external view returns (uint256 remaining);

  function approve(address spender, uint256 value) external returns (bool success);

  function balanceOf(
    address owner
  ) external view returns (uint256 balance);

  function decimals() external view returns (uint8 decimalPlaces);

  function decreaseApproval(address spender, uint256 addedValue) external returns (bool success);

  function increaseApproval(address spender, uint256 subtractedValue) external;

  function name() external view returns (string memory tokenName);

  function symbol() external view returns (string memory tokenSymbol);

  function totalSupply() external view returns (uint256 totalTokensIssued);

  function transfer(address to, uint256 value) external returns (bool success);

  function transferAndCall(address to, uint256 value, bytes calldata data) external returns (bool success);

  function transferFrom(address from, address to, uint256 value) external returns (bool success);
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import {IOwnable} from "../interfaces/IOwnable.sol";

/// @title The ConfirmedOwner contract
/// @notice A contract with helpers for basic contract ownership.
contract ConfirmedOwnerWithProposal is IOwnable {
  address private s_owner;
  address private s_pendingOwner;

  event OwnershipTransferRequested(address indexed from, address indexed to);
  event OwnershipTransferred(address indexed from, address indexed to);

  constructor(address newOwner, address pendingOwner) {
    // solhint-disable-next-line gas-custom-errors
    require(newOwner != address(0), "Cannot set owner to zero");

    s_owner = newOwner;
    if (pendingOwner != address(0)) {
      _transferOwnership(pendingOwner);
    }
  }

  /// @notice Allows an owner to begin transferring ownership to a new address.
  function transferOwnership(
    address to
  ) public override onlyOwner {
    _transferOwnership(to);
  }

  /// @notice Allows an ownership transfer to be completed by the recipient.
  function acceptOwnership() external override {
    // solhint-disable-next-line gas-custom-errors
    require(msg.sender == s_pendingOwner, "Must be proposed owner");

    address oldOwner = s_owner;
    s_owner = msg.sender;
    s_pendingOwner = address(0);

    emit OwnershipTransferred(oldOwner, msg.sender);
  }

  /// @notice Get the current owner
  function owner() public view override returns (address) {
    return s_owner;
  }

  /// @notice validate, transfer ownership, and emit relevant events
  function _transferOwnership(
    address to
  ) private {
    // solhint-disable-next-line gas-custom-errors
    require(to != msg.sender, "Cannot transfer to self");

    s_pendingOwner = to;

    emit OwnershipTransferRequested(s_owner, to);
  }

  /// @notice validate access
  function _validateOwnership() internal view {
    // solhint-disable-next-line gas-custom-errors
    require(msg.sender == s_owner, "Only callable by owner");
  }

  /// @notice Reverts if called by anyone other than the contract owner.
  modifier onlyOwner() {
    _validateOwnership();
    _;
  }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

interface IOwnable {
  function owner() external returns (address);

  function transferOwnership(
    address recipient
  ) external;

  function acceptOwnership() external;
}