Contract Address Details

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

import "@openzeppelin/contracts/access/Ownable.sol";
import "@openzeppelin/contracts/security/Pausable.sol";
import "@openzeppelin/contracts/security/ReentrancyGuard.sol";
import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";

/**
 * @title IERC20Burnable
 * @dev Extended ERC20 interface with burn functionality
 */
interface IERC20Burnable is IERC20 {
    function burn(uint256 amount) external;
    function decimals() external view returns (uint8);
}

/**
 * @title GLucky1V2
 * @author GOODOG
 * @dev lottery game(commit-reveal pattern, RNG) with EIP-712 signatures, deadline validation
 * 
 * Core Features:
 * - Single Submission: Choose multiple numbers within the same numberRange
 * - Flexible Betting: Each number can have different bet amounts
 * - Unified Draw: Use the same random number to generate winning number
 * - Gas Optimization: Complete multiple number betting in one transaction
 *
 */
contract GLucky1V2 is Ownable, Pausable, ReentrancyGuard {
    using ECDSA for bytes32;

    /// @dev Prize token contract for rewards and payments
    IERC20Burnable public immutable prizeToken;
    
    /// @dev Base point constant for percentage calculations (10000 = 100%)
    uint256 public constant BASE_POINT = 10000;
    
    // ==================== EIP-712 Constants ====================
    
    /// @dev EIP-712 Domain Separator
    bytes32 public immutable DOMAIN_SEPARATOR;
    
    /// @dev EIP-712 TypeHash for CommitTicket (includes all sub-structures)
    bytes32 public constant COMMIT_TICKET_TYPEHASH = keccak256(
        "CommitTicket(address user,uint8 numberRange,NumberChoice[] choices,uint256 salt,uint256 nonce,uint256 deadline)" "NumberChoice(uint256 ticketAmount,uint8 chosenNumber)"
    );
    
    /// @dev EIP-712 TypeHash for NumberChoice
    bytes32 public constant NUMBER_CHOICE_TYPEHASH = keccak256(
        "NumberChoice(uint256 ticketAmount,uint8 chosenNumber)"
    );
    
    // ==================== Configuration Parameters ====================
    
    /// @dev Maximum bet amount per single ticket
    uint256 public maxTicketAmount;
    
    /// @dev Minimum bet amount per single ticket
    uint256 public minTicketAmount;
    
    /// @dev Number of blocks to wait before reveal
    uint256 public futureBlockOffset;
    
    /// @dev Default signature deadline duration (seconds)
    uint256 public defaultDeadlineDuration = 120; // 2 minutes
    
    // ==================== Packed Configuration ====================
    
    /// @dev Trusted signer address for signature verification
    address public trustedSigner;
    /// @dev Minimum allowed number range
    uint8 public minNumberRange = 2;
    /// @dev Maximum allowed number range
    uint8 public maxNumberRange = 99;
    
    // ==================== Fee Configuration ====================
    
    /// @dev Percentage of bet amount to burn (500 = 5%)
    uint256 public burnFeePercent = 500;
    /// @dev Percentage of bet amount for protocol fee (500 = 5%)
    uint256 public protocolFeePercent = 500;
    /// @dev Address to receive protocol fees
    address public protocolFeeRecipient;
    
    // ==================== RTP Configuration ====================
    
    /// @dev Return to Player percentage in basis points (6667 = 66.67%)
    uint256 public rtpPercent = 6667;
    
    // ==================== Statistics Data ====================
    
    /// @dev Total number of tickets created
    uint256 public totalTicketCount;
    /// @dev Total number of commits made
    uint256 public totalCommitCount;
    /// @dev Total amount of rewards paid out
    uint256 public totalRewardsPaid;
    /// @dev Total amount of tokens burned
    uint256 public totalBurnedAmount;
    /// @dev Total protocol fees collected
    uint256 public totalProtocolFees;
    
    // ==================== Core Data Structures ====================
    
    /**
     * @dev Number choice structure for multiple numbers within the same range
     * @param ticketAmount The bet amount for this specific number
     * @param chosenNumber The selected number (1 to numberRange)
     */
    struct NumberChoice {
        uint256 ticketAmount;
        uint8 chosenNumber;
    }
    
    /**
     * @dev Simplified ticket information stored within commit
     * @param ticketAmount Bet amount for this ticket
     * @param rewardPaid Amount of reward paid out (0 if not won or insufficient funds)
     * @param chosenNumber Selected number for this ticket
     */
    struct TicketInfo {
        uint256 ticketAmount;
        uint256 rewardPaid;
        uint8 chosenNumber;
    }
    
    /**
     * @dev Commit batch information containing all ticket data
     * @param user Address of the user who made the commit
     * @param totalAmount Total bet amount for all tickets in this commit
     * @param commitBlock Block number when commit was made
     * @param salt Random salt used for this commit
     * @param totalWinnings Total winnings paid out for this commit
     * @param rtpPercent RTP percentage used for this commit (in basis points)
     * @param offsetUsed Future block offset used at commit time to prevent parameter drift
     * @param numberRange Number range used for all tickets in this commit
     * @param winningNumber Winning number for this commit batch (0 if not revealed)
     * @param revealed Whether this commit has been revealed
     * @param won Whether this commit won any rewards
     */
    struct CommitInfo {
        address user;
        uint256 totalAmount;
        uint256 commitBlock;
        uint256 salt;
        uint256 totalWinnings;
        uint256 rtpPercent;
        uint256 offsetUsed;
        uint8 numberRange;
        uint8 winningNumber;
        bool revealed;
        bool won;
    }
    
    // ==================== Storage Mappings ====================
    
    /// @dev Mapping from commit ID to commit information
    mapping(uint256 => CommitInfo) public commits;
    
    /// @dev Mapping from commit ID to array of ticket information
    mapping(uint256 => TicketInfo[]) public commitTickets;
    
    /// @dev Mapping from user address to array of their commit IDs
    mapping(address => uint256[]) public userCommits;
    
    /// @dev Mapping from user address to their used nonce for signature verification
    mapping(address => uint256) public usedNonce;
    
    // ==================== Event Definitions ====================
    
    /**
     * @dev Emitted when tickets are committed in a single transaction
     * @param commitId Unique identifier for this commit batch
     * @param user Address of the user making the commit
     * @param numberRange Number range used for all tickets in this commit
     * @param choiceCount Number of choices/tickets in this commit
     * @param totalAmount Total bet amount for all tickets
     * @param targetBlock Block number for future reveal
     * @param rtpPercent RTP percentage used for this commit
     * @param offsetUsed Future block offset used at commit time
     */
    event TicketCommitted(
        uint256 indexed commitId,
        address indexed user,
        uint8 numberRange,
        uint256 choiceCount,
        uint256 totalAmount,
        uint256 targetBlock,
        uint256 rtpPercent,
        uint256 offsetUsed
    );
    
    /**
     * @dev Emitted when a commit batch is revealed (all tickets use same winning number)
     * @param commitId ID of the revealed commit
     * @param user Address of the commit owner
     * @param numberRange Number range used for this commit
     * @param choiceCount Number of choices/tickets in this commit
     * @param totalAmount Total bet amount for all tickets
     * @param winningNumber The winning number for this batch
     * @param won Whether this commit won any rewards
     * @param totalWinnings Total amount paid out as winnings
     * @param rtpPercent RTP percentage used for this commit
     */
    event TicketRevealed(
        uint256 indexed commitId,
        address indexed user,
        uint8 numberRange,
        uint256 choiceCount,
        uint256 totalAmount,
        uint8 winningNumber,
        bool indexed won,
        uint256 totalWinnings,
        uint256 rtpPercent
    );
    
    /**
     * @dev Emitted when prize pool has insufficient funds to pay a reward
     * @param commitId ID of the commit containing the winning ticket
     * @param user Address of the ticket owner
     * @param ticketIndex Index of the winning ticket that couldn't be paid
     * @param requiredAmount Amount needed for the reward
     * @param availableAmount Amount available in the prize pool
     */
    event InsufficientPrizePool(
        uint256 indexed commitId,
        address indexed user,
        uint256 indexed ticketIndex,
        uint256 requiredAmount,
        uint256 availableAmount
    );
    
    /**
     * @dev Emitted when fees are processed for a commit
     * @param commitId ID of the commit
     * @param totalAmount Total bet amount
     * @param burnAmount Amount burned
     * @param protocolAmount Amount sent to protocol fee recipient
     */
    event FeesProcessed(
        uint256 indexed commitId,
        uint256 totalAmount,
        uint256 burnAmount,
        uint256 protocolAmount
    );
    
    /**
     * @dev Emitted when the jackpot/prize pool is funded
     * @param sender Address that funded the jackpot
     * @param amount Amount added to the jackpot
     * @param newBalance New total balance of the prize pool
     */
    event JackpotFunded(
        address indexed sender,
        uint256 amount,
        uint256 newBalance
    );
    
    /**
     * @dev Emitted when number ranges are updated by owner
     * @param oldMinRange Previous minimum number range
     * @param oldMaxRange Previous maximum number range
     * @param newMinRange New minimum number range
     * @param newMaxRange New maximum number range
     */
    event NumberRangesUpdated(
        uint8 oldMinRange,
        uint8 oldMaxRange,
        uint8 newMinRange,
        uint8 newMaxRange
    );
    
    /**
     * @dev Emitted when RTP percentage is updated by owner
     * @param oldRtpPercent Previous RTP percentage in basis points
     * @param newRtpPercent New RTP percentage in basis points
     */
    event RtpPercentUpdated(
        uint256 oldRtpPercent,
        uint256 newRtpPercent
    );
    
    /**
     * @dev Emitted when future block offset is updated by owner
     * @param oldOffset Previous block offset value
     * @param newOffset New block offset value
     */
    event FutureBlockOffsetUpdated(
        uint256 oldOffset,
        uint256 newOffset
    );
    
    /**
     * @dev Emitted when ticket amount limits are updated by owner
     * @param oldMinAmount Previous minimum ticket amount
     * @param oldMaxAmount Previous maximum ticket amount
     * @param newMinAmount New minimum ticket amount
     * @param newMaxAmount New maximum ticket amount
     */
    event TicketAmountLimitsUpdated(
        uint256 oldMinAmount,
        uint256 oldMaxAmount,
        uint256 newMinAmount,
        uint256 newMaxAmount
    );
    
    /**
     * @dev Emitted when default deadline duration is updated
     * @param oldDuration Previous default deadline duration
     * @param newDuration New default deadline duration
     */
    event DefaultDeadlineDurationUpdated(
        uint256 oldDuration,
        uint256 newDuration
    );
    
    // ==================== Constructor ====================
    
    /**
     * @dev Contract constructor
     * @param _signer Trusted signer address for signature verification
     * @param _prizeToken Address of the prize token contract
     * @param _maxTicketAmount Maximum bet amount per ticket
     * @param _minTicketAmount Minimum bet amount per ticket
     * @param _offset Number of blocks to wait before reveal (max 128)
     * @param _protocolFeeRecipient Address to receive protocol fees
     * @param _rtpPercent Initial RTP percentage in basis points (e.g., 8000 = 80%)
     */
    constructor(
        address _signer,
        address _prizeToken,
        uint256 _maxTicketAmount,
        uint256 _minTicketAmount,
        uint256 _offset,
        address _protocolFeeRecipient,
        uint256 _rtpPercent
    ) {
        require(_signer != address(0), "Invalid signer");
        require(_prizeToken != address(0), "Invalid token");
        require(_maxTicketAmount > 0, "Invalid max amount");
        require(_minTicketAmount > 0, "Invalid min amount");
        require(_minTicketAmount <= _maxTicketAmount, "Min amount must be <= max amount");
        require(_protocolFeeRecipient != address(0), "Invalid recipient");
        require(_offset > 0 && _offset < 256, "Invalid block offset");
        require(_rtpPercent > 0 && _rtpPercent <= BASE_POINT, "Invalid RTP percent");
        
        trustedSigner = _signer;
        prizeToken = IERC20Burnable(_prizeToken);
        maxTicketAmount = _maxTicketAmount;
        minTicketAmount = _minTicketAmount;
        futureBlockOffset = _offset;
        protocolFeeRecipient = _protocolFeeRecipient;
        rtpPercent = _rtpPercent;
        
        // Initialize EIP-712 Domain Separator
        DOMAIN_SEPARATOR = keccak256(abi.encode(
            keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"),
            keccak256("GLucky1V2"),
            keccak256("2.0"),
            block.chainid,
            address(this)
        ));
    }

    /**
     * @dev Validates if the number choices are valid
     * @param numberRange The number range to validate against
     * @param choices Array of number choices to validate
     * 
     * @notice This function reverts with specific error messages if validation fails
     */
    function validateChoices(uint8 numberRange, NumberChoice[] calldata choices) public view {
        require(numberRange >= minNumberRange && numberRange <= maxNumberRange, "Invalid number range");
        require(choices.length > 0, "No choices provided");
        require(choices.length <= numberRange, "Choices exceed number range");
        
        _validateChoicesInner(numberRange, choices);
    }
    
    /**
     * @dev Internal function to validate choices - reduces stack depth
     * @param numberRange The number range to validate against
     * @param choices Array of number choices to validate
     */
    function _validateChoicesInner(uint8 numberRange, NumberChoice[] calldata choices) internal view {
        _validateChoiceAmounts(choices);
        _validateChoiceNumbers(numberRange, choices);
    }
    
    /**
     * @dev Validates choice amounts
     * @param choices Array of number choices to validate
     */
    function _validateChoiceAmounts(NumberChoice[] calldata choices) internal view {
        for (uint256 i = 0; i < choices.length; i++) {
            require(choices[i].ticketAmount >= minTicketAmount, "Amount below minimum");
            require(choices[i].ticketAmount <= maxTicketAmount, "Amount exceeds max");
        }
    }
    
    /**
     * @dev Validates choice numbers and duplicates
     * @param numberRange The number range to validate against
     * @param choices Array of number choices to validate
     */
    function _validateChoiceNumbers(uint8 numberRange, NumberChoice[] calldata choices) internal pure {
        bool[256] memory usedNumbers; // Support up to 255 numbers (max numberRange)
        
        for (uint256 i = 0; i < choices.length; i++) {
            uint8 chosenNumber = choices[i].chosenNumber;
            
            require(chosenNumber >= 1 && chosenNumber <= numberRange, "Number out of range");
            require(!usedNumbers[chosenNumber], "Duplicate number found");
            
            usedNumbers[chosenNumber] = true;
        }
    }

    // ==================== Core Functionality ====================
    
    /**
     * @dev Commits multiple number tickets within the same number range with EIP-712 signature
     * @param numberRange Number range (shared by all numbers)
     * @param choices Array of number choices (number and corresponding bet amount)
     * @param salt Random salt value for randomness
     * @param nonce User nonce for signature verification
     * @param deadline Signature expiry timestamp
     * @param signature EIP-712 signature for the entire commit
     * 
     * Important Restrictions:
     * - Number of choices cannot exceed numberRange (cannot select more than total available)
     * - Cannot select duplicate numbers
     * - Each number must be within 1 to numberRange range
     * - Signature must not be expired (deadline check)
     * 
     * @notice This function allows users to bet on multiple numbers in a single transaction
     *         with different bet amounts for each number, using secure EIP-712 signatures
     */
    function commitTicket(
        uint8 numberRange,
        NumberChoice[] calldata choices,
        uint256 salt,
        uint256 nonce,
        uint256 deadline,
        bytes calldata signature
    ) external whenNotPaused nonReentrant {
        
        validateChoices(numberRange, choices);
        
        // Verify EIP-712 signature with deadline
        _verifyCommitSignature(msg.sender, numberRange, choices, salt, nonce, deadline, signature);
        usedNonce[msg.sender] = nonce;
        
        // Create commit batch
        uint256 commitId = ++totalCommitCount;
        uint256 totalAmount = 0;
        
        // Calculate total amount (validation already done in validateChoices)
        for (uint256 i = 0; i < choices.length; i++) {
            totalAmount += choices[i].ticketAmount;
        }
        
        // Transfer total amount
        require(prizeToken.transferFrom(msg.sender, address(this), totalAmount), "Payment failed");
        
        // Store ticket information directly in commitTickets array
        for (uint256 i = 0; i < choices.length; i++) {
            commitTickets[commitId].push(TicketInfo({
                chosenNumber: choices[i].chosenNumber,
                ticketAmount: choices[i].ticketAmount,
                rewardPaid: 0
            }));
        }
        
        // Record commit information
        commits[commitId] = CommitInfo({
            user: msg.sender,
            numberRange: numberRange,
            totalAmount: totalAmount,
            commitBlock: block.number,
            salt: salt,
            winningNumber: 0,
            revealed: false,
            won: false,
            totalWinnings: 0,
            rtpPercent: rtpPercent,
            offsetUsed: futureBlockOffset  // Store current futureBlockOffset to prevent parameter drift
        });
        
        userCommits[msg.sender].push(commitId);
        totalTicketCount += choices.length;
        
        emit TicketCommitted(
            commitId,
            msg.sender,
            numberRange,
            choices.length,
            totalAmount,
            block.number + futureBlockOffset,
            rtpPercent,
            futureBlockOffset
        );
    }
    
    /**
     * @dev Reveals the entire commit batch (all tickets use the same winning number)
     * @param commitId ID of the commit batch to reveal
     * 
     * @notice This function generates a single winning number for all tickets in the commit
     *         and processes all tickets at once for gas efficiency
     */
    function revealTicket(uint256 commitId) external nonReentrant {
        CommitInfo storage commit = commits[commitId];
        require(commit.user != address(0), "Commit not found");
        require(!commit.revealed, "Already revealed");
        
        uint256 targetBlock = commit.commitBlock + commit.offsetUsed;
        require(block.number > targetBlock, "Too early to reveal");
        require(block.number <= targetBlock + 256, "Reveal window expired");
        
        bytes32 blockHash = blockhash(targetBlock);
        require(blockHash != bytes32(0), "Block hash unavailable");
        
        // Generate unified winning number for this batch
        bytes32 randomHash = keccak256(abi.encode(
            commit.user,
            commitId,
            blockHash,
            commit.numberRange,
            commit.salt
        ));
        
        uint8 winningNumber = uint8((uint256(randomHash) % commit.numberRange) + 1);
        commit.winningNumber = winningNumber;
        commit.revealed = true;
        
        // Process all tickets directly from commitTickets array
        TicketInfo[] storage tickets = commitTickets[commitId];
        uint256 totalWinnings = 0;
        
        for (uint256 i = 0; i < tickets.length; i++) {
            if (tickets[i].chosenNumber == winningNumber) {
                uint256 rewardAmount = _processWinningTicket(commitId, i, commit, tickets[i]);
                if (rewardAmount > 0) {
                    totalWinnings += rewardAmount;
                    commit.won = true;
                }
            }
        }
        
        // Update commit statistics
        commit.totalWinnings = totalWinnings;
        
        emit TicketRevealed(
            commitId,
            commit.user,
            commit.numberRange,
            tickets.length,
            commit.totalAmount,
            winningNumber,
            commit.won,
            totalWinnings,
            commit.rtpPercent
        );
    }
    
    /**
     * @dev Processes a winning ticket - reduces stack depth in revealTicket
     * @param commitId The commit ID
     * @param ticketIndex The index of the winning ticket
     * @param commit The commit information
     * @param ticket The winning ticket
     * @return rewardAmount The actual reward amount paid
     */
    function _processWinningTicket(
        uint256 commitId,
        uint256 ticketIndex, 
        CommitInfo storage commit,
        TicketInfo storage ticket
    ) internal returns (uint256 rewardAmount) {
        uint256 base = ticket.ticketAmount * commit.rtpPercent / BASE_POINT;
        rewardAmount = base * commit.numberRange;
        uint256 availableBalance = prizeToken.balanceOf(address(this));
        
        if (availableBalance >= rewardAmount) {
            // Process fees on winning amount
            uint256 burnAmount = (rewardAmount * burnFeePercent) / BASE_POINT;
            uint256 protocolAmount = (rewardAmount * protocolFeePercent) / BASE_POINT;
            uint256 actualReward = rewardAmount - burnAmount - protocolAmount;
            
            // Update statistics
            totalRewardsPaid += rewardAmount;
            ticket.rewardPaid = rewardAmount;
            
            // Transfer actual reward to user
            require(prizeToken.transfer(commit.user, actualReward), "Reward transfer failed");
            
            // Process fees
            if (burnAmount > 0) {
                prizeToken.burn(burnAmount);
                totalBurnedAmount += burnAmount;
            }
            
            if (protocolAmount > 0) {
                require(prizeToken.transfer(protocolFeeRecipient, protocolAmount), "Protocol fee failed");
                totalProtocolFees += protocolAmount;
            }
            
            // Emit fees processed event
            emit FeesProcessed(commitId, rewardAmount, burnAmount, protocolAmount);
            
        } else {
            emit InsufficientPrizePool(commitId, commit.user, ticketIndex, rewardAmount, availableBalance);
            rewardAmount = 0;
        }
    }
    
    // ==================== Internal Functions ====================
    
    /**
     * @dev Verifies the EIP-712 commit signature with enhanced security
     * @param user Address of the user making the commit
     * @param numberRange Number range used
     * @param choices Array of number choices
     * @param salt Random salt value
     * @param nonce User nonce
     * @param deadline Signature expiry timestamp
     * @param signature EIP-712 signature to verify
     */
    function _verifyCommitSignature(
        address user,
        uint8 numberRange,
        NumberChoice[] calldata choices,
        uint256 salt,
        uint256 nonce,
        uint256 deadline,
        bytes calldata signature
    ) internal view {
        require(block.timestamp <= deadline, "Signature expired");
        require(usedNonce[user] < nonce, "Nonce already used");
        
        // Construct EIP-712 structured data hash
        bytes32 structHash = keccak256(abi.encode(
            COMMIT_TICKET_TYPEHASH,
            user,
            numberRange,
            _hashChoices(choices),
            salt,
            nonce,
            deadline
        ));
        
        bytes32 digest = keccak256(abi.encodePacked(
            "\x19\x01",
            DOMAIN_SEPARATOR,
            structHash
        ));
        
        address signer = _recoverSignerSecure(digest, signature);
        require(signer == trustedSigner, "Invalid signature");
    }
    
    /**
     * @dev Hashes an array of NumberChoice structs for EIP-712
     * @param choices Array of number choices to hash
     * @return Hash of the choices array
     */
    function _hashChoices(NumberChoice[] calldata choices) internal pure returns (bytes32) {
        bytes32[] memory choiceHashes = new bytes32[](choices.length);
        
        for (uint256 i = 0; i < choices.length; i++) {
            choiceHashes[i] = keccak256(abi.encode(
                NUMBER_CHOICE_TYPEHASH,
                choices[i].ticketAmount,
                choices[i].chosenNumber
            ));
        }
        
        return keccak256(abi.encodePacked(choiceHashes));
    }
    
    /**
     * @dev Securely recovers the signer address from a signature with enhanced validation
     * @param hash The hash that was signed
     * @param signature The signature to recover from
     * @return The address that created the signature
     */
    function _recoverSignerSecure(bytes32 hash, bytes calldata signature) internal pure returns (address) {
        require(signature.length == 65, "Invalid signature length");
        
        bytes32 r;
        bytes32 s;
        uint8 v;
        
        assembly {
            r := calldataload(signature.offset)
            s := calldataload(add(signature.offset, 0x20))
            v := byte(0, calldataload(add(signature.offset, 0x40)))
        }
        
        // Validate v parameter (must be 27 or 28)
        require(v == 27 || v == 28, "Invalid v value");
        
        // Validate s parameter to prevent signature malleability
        require(uint256(s) <= 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0, "Invalid s value");
        
        // Recover signer address
        address signer = ecrecover(hash, v, r, s);
        require(signer != address(0), "Invalid signature");
        
        return signer;
    }
    
    // ==================== Query Functions ====================
    
    /**
     * @dev Gets all tickets for a user across all their commits
     * @param user Address of the user
     * @return commitIds Array of commit IDs
     * @return tickets Array of ticket arrays for each commit
     */
    function getUserTickets(address user) 
        external view returns (uint256[] memory commitIds, TicketInfo[][] memory tickets) {
        uint256[] memory userCommitIds = userCommits[user];
        commitIds = userCommitIds;
        tickets = new TicketInfo[][](userCommitIds.length);
        
        for (uint256 i = 0; i < userCommitIds.length; i++) {
            uint256 commitId = userCommitIds[i];
            tickets[i] = commitTickets[commitId];
        }
    }
    
    /**
     * @dev Gets a paginated list of user's commits
     * @param user Address of the user
     * @param offset Starting index for pagination
     * @param limit Maximum number of commits to return
     * @return Array of commit IDs
     */
    function getUserCommits(address user, uint256 offset, uint256 limit)
        external view returns (uint256[] memory) {
        uint256 total = userCommits[user].length;
        if (offset >= total) return new uint256[](0);
        
        uint256 end = offset + limit;
        if (end > total) end = total;
        
        uint256[] memory result = new uint256[](end - offset);
        for (uint256 i = offset; i < end; i++) {
            result[i - offset] = userCommits[user][i];
        }
        return result;
    }
    
    /**
     * @dev Gets all tickets for a specific commit
     * @param commitId ID of the commit
     * @return Array of ticket information in the commit
     */
    function getCommitTickets(uint256 commitId) external view returns (TicketInfo[] memory) {
        return commitTickets[commitId];
    }
    
    /**
     * @dev Gets a specific ticket within a commit
     * @param commitId ID of the commit
     * @param ticketIndex Index of the ticket within the commit
     * @return Ticket information
     */
    function getTicket(uint256 commitId, uint256 ticketIndex) external view returns (TicketInfo memory) {
        require(ticketIndex < commitTickets[commitId].length, "Ticket index out of bounds");
        return commitTickets[commitId][ticketIndex];
    }
    
    /**
     * @dev Gets comprehensive lottery statistics
     * @return totalPrizePool Current balance of the prize pool
     * @return blockOffset Number of blocks to wait before reveal
     * @return totalTickets Total number of tickets created
     * @return totalCommits Total number of commits made
     * @return totalRewards Total rewards paid out
     * @return minRange Minimum allowed number range
     * @return maxRange Maximum allowed number range
     * @return maxTicketAmountReturn Maximum bet amount per ticket
     * @return minTicketAmountReturn Minimum bet amount per ticket
     * @return rtpPercentReturn Current RTP percentage in basis points
     */
    function getLotteryStats() external view returns (
        uint256 totalPrizePool,
        uint256 blockOffset,
        uint256 totalTickets,
        uint256 totalCommits,
        uint256 totalRewards,
        uint8 minRange,
        uint8 maxRange,
        uint256 maxTicketAmountReturn,
        uint256 minTicketAmountReturn,
        uint256 rtpPercentReturn
    ) {
        return (
            prizeToken.balanceOf(address(this)),
            futureBlockOffset,
            totalTicketCount,
            totalCommitCount,
            totalRewardsPaid,
            minNumberRange,
            maxNumberRange,
            maxTicketAmount,
            minTicketAmount,
            rtpPercent
        );
    }
    
    /**
     * @dev Gets detailed information about a specific commit
     * @param commitId ID of the commit to query
     * @return commit Commit information
     * @return tickets Array of tickets in this commit
     */
    function getCommitDetails(uint256 commitId) external view returns (
        CommitInfo memory commit,
        TicketInfo[] memory tickets
    ) {
        commit = commits[commitId];
        tickets = commitTickets[commitId];
    }
    
    /**
     * @dev Calculates potential total rewards with validation
     * @param numberRange The number range to use
     * @param choices Array of number choices
     * @return totalCost Total cost of all tickets
     * @return maxSingleReward Maximum possible reward for a single winning number
     * 
     * @notice This function validates the choices and calculates the total cost and maximum possible reward
     *         for a single winning number (since only one number can win per draw)
     */
    function calculateTotalReward(uint8 numberRange, NumberChoice[] calldata choices) 
        external view returns (uint256 totalCost, uint256 maxSingleReward) {
        
        // Use existing validation function to avoid duplicate code
        validateChoices(numberRange, choices);
        
        // Calculate total cost and find the maximum reward for any single winning number
        for (uint256 i = 0; i < choices.length; i++) {
            totalCost += choices[i].ticketAmount;
            
            // Calculate reward for this specific number if it wins
            uint256 currentReward = (choices[i].ticketAmount * numberRange * rtpPercent) / BASE_POINT;
            
            // Keep track of the highest possible single number reward
            if (currentReward > maxSingleReward) {
                maxSingleReward = currentReward;
            }
        }
    }
    
    /**
     * @dev Gets win probability and maximum choices for a specific number range
     * @param numberRange The number range to query
     * @return winProbabilityBP Win probability in basis points
     * @return maxPossibleChoices Maximum number of choices possible
     * @return rtpMultiplier RTP-based reward multiplier for winning tickets
     */
    function getRangeInfo(uint8 numberRange) 
        external view returns (
            uint256 winProbabilityBP,
            uint256 maxPossibleChoices,
            uint256 rtpMultiplier
        ) {
        require(numberRange >= minNumberRange && numberRange <= maxNumberRange, "Invalid range");
        
        return (
            BASE_POINT / numberRange,  // Win probability (basis points): 10000/numberRange
            numberRange,               // Maximum possible choices equals numberRange
            rtpPercent                 // RTP-based reward multiplier in basis points
        );
    }
    
    // ==================== Administrative Functions ====================
    
    /**
     * @dev Funds the jackpot/prize pool
     * @param amount Amount of tokens to add to the prize pool
     * 
     * @notice Anyone can fund the jackpot to increase the prize pool
     */
    function fundJackpot(uint256 amount) external nonReentrant {
        require(prizeToken.transferFrom(msg.sender, address(this), amount), "Transfer failed");
        emit JackpotFunded(msg.sender, amount, prizeToken.balanceOf(address(this)));
    }
    
    /**
     * @dev Emergency withdrawal function (Owner only)
     * @param to Address to send tokens to
     * @param amount Amount of tokens to withdraw
     * 
     * @notice This is an emergency function that should only be used in exceptional circumstances
     */
    function emergencyWithdraw(address to, uint256 amount) external onlyOwner nonReentrant {
        require(to != address(0), "Invalid address");
        require(prizeToken.transfer(to, amount), "Transfer failed");
    }
    
    /**
     * @dev Sets the fee configuration
     * @param _burnPercent Percentage to burn (in basis points)
     * @param _protocolPercent Percentage for protocol fee (in basis points)
     */
    function setFeeConfig(uint256 _burnPercent, uint256 _protocolPercent) external onlyOwner {
        require(_burnPercent <= 1000 && _protocolPercent <= 1000, "Fee too high");
        burnFeePercent = _burnPercent;
        protocolFeePercent = _protocolPercent;
    }
    
    /**
     * @dev Sets the trusted signer address
     * @param newSigner New trusted signer address
     */
    function setTrustedSigner(address newSigner) external onlyOwner {
        require(newSigner != address(0), "Invalid signer");
        trustedSigner = newSigner;
    }
    
    /**
     * @dev Sets the default deadline duration for signatures
     * @param _defaultDeadlineDuration New default deadline duration in seconds
     */
    function setDefaultDeadlineDuration(uint256 _defaultDeadlineDuration) external onlyOwner {
        require(_defaultDeadlineDuration > 0, "Invalid deadline duration");
        require(_defaultDeadlineDuration <= 3600, "Deadline too long"); // Max 1 hour
        
        uint256 oldDuration = defaultDeadlineDuration;
        defaultDeadlineDuration = _defaultDeadlineDuration;
        
        emit DefaultDeadlineDurationUpdated(oldDuration, _defaultDeadlineDuration);
    }
    
    /**
     * @dev Pauses the contract (Owner only)
     */
    function pause() external onlyOwner {
        _pause();
    }
    
    /**
     * @dev Unpauses the contract (Owner only)
     */
    function unpause() external onlyOwner {
        _unpause();
    }
    
    /**
     * @dev Sets the allowed number range limits (Owner only)
     * @param _minRange New minimum number range (must be >= 2)
     * @param _maxRange New maximum number range (must be <= 255)
     * 
     * @notice This function allows the owner to adjust the supported number ranges
     *         for lottery games. Changes take effect immediately for new commits.
     *         Existing commits are not affected.
     */
    function setNumberRanges(uint8 _minRange, uint8 _maxRange) external onlyOwner {
        require(_minRange >= 2, "Min range must be at least 2");
        require(_maxRange <= 255, "Max range too large");
        require(_minRange < _maxRange, "Min must be less than max");
        require(_maxRange - _minRange >= 1, "Range span too small");
        
        uint8 oldMinRange = minNumberRange;
        uint8 oldMaxRange = maxNumberRange;
        
        minNumberRange = _minRange;
        maxNumberRange = _maxRange;
        
        emit NumberRangesUpdated(oldMinRange, oldMaxRange, _minRange, _maxRange);
    }
    
    /**
     * @dev Gets the current number range configuration
     * @return minRange Current minimum number range
     * @return maxRange Current maximum number range
     * 
     * @notice Initial values are: minRange=2, maxRange=32
     */
    function getNumberRangeConfig() external view returns (
        uint8 minRange,
        uint8 maxRange
    ) {
        return (
            minNumberRange,
            maxNumberRange
        );
    }
    
    /**
     * @dev Sets the RTP (Return to Player) percentage (Owner only)
     * @param _rtpPercent New RTP percentage in basis points (max 10000 = 100%)
     * 
     * @notice This function allows the owner to adjust the reward percentage.
     *         Higher RTP means higher rewards for winners but requires more prize pool funds.
     */
    function setRtpPercent(uint256 _rtpPercent) external onlyOwner {
        require(_rtpPercent > 0 && _rtpPercent <= BASE_POINT, "Invalid RTP percent");
        
        uint256 oldRtpPercent = rtpPercent;
        rtpPercent = _rtpPercent;
        
        emit RtpPercentUpdated(oldRtpPercent, _rtpPercent);
    }
    
    /**
     * @dev Sets the future block offset for reveal timing (Owner only)
     * @param _futureBlockOffset New number of blocks to wait before reveal
     * 
     * @notice This function allows the owner to adjust the timing requirement for reveals.
     *         Changes take effect immediately for new commits.
     *         Existing commits are not affected.
     */
    function setFutureBlockOffset(uint256 _futureBlockOffset) external onlyOwner {
        require(_futureBlockOffset > 0 && _futureBlockOffset < 256, "Block offset must be positive and less than 256");
        
        uint256 oldOffset = futureBlockOffset;
        futureBlockOffset = _futureBlockOffset;
        
        emit FutureBlockOffsetUpdated(oldOffset, _futureBlockOffset);
    }
    
    /**
     * @dev Sets the minimum and maximum ticket amounts (Owner only)
     * @param _minTicketAmount New minimum bet amount per ticket
     * @param _maxTicketAmount New maximum bet amount per ticket
     * 
     * @notice This function allows the owner to adjust bet amount limits.
     *         Changes take effect immediately for new commits.
     *         Existing commits are not affected.
     */
    function setTicketAmountLimits(uint256 _minTicketAmount, uint256 _maxTicketAmount) external onlyOwner {
        require(_minTicketAmount > 0, "Min amount must be positive");
        require(_maxTicketAmount > 0, "Max amount must be positive");
        require(_minTicketAmount <= _maxTicketAmount, "Min amount must be <= max amount");
        
        uint256 oldMinAmount = minTicketAmount;
        uint256 oldMaxAmount = maxTicketAmount;
        
        minTicketAmount = _minTicketAmount;
        maxTicketAmount = _maxTicketAmount;
        
        emit TicketAmountLimitsUpdated(oldMinAmount, oldMaxAmount, _minTicketAmount, _maxTicketAmount);
    }
    
    // ==================== Utility Functions ====================
    
    /**
     * @dev Gets the current EIP-712 domain separator
     * @return The domain separator hash
     */
    function getDomainSeparator() external view returns (bytes32) {
        return DOMAIN_SEPARATOR;
    }
    
    /**
     * @dev Gets the recommended deadline for new signatures
     * @return Recommended deadline timestamp (current time + default duration)
     */
    function getRecommendedDeadline() external view returns (uint256) {
        return block.timestamp + defaultDeadlineDuration;
    }
}
        

// SPDX-License-Identifier: MIT

pragma solidity ^0.8.0;

import "../utils/Context.sol";

/**
 * @dev Contract module which provides a basic access control mechanism, where
 * there is an account (an owner) that can be granted exclusive access to
 * specific functions.
 *
 * By default, the owner account will be the one that deploys the contract. This
 * can later be changed with {transferOwnership}.
 *
 * This module is used through inheritance. It will make available the modifier
 * `onlyOwner`, which can be applied to your functions to restrict their use to
 * the owner.
 */
abstract contract Ownable is Context {
    address private _owner;

    event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);

    /**
     * @dev Initializes the contract setting the deployer as the initial owner.
     */
    constructor() {
        _setOwner(_msgSender());
    }

    /**
     * @dev Returns the address of the current owner.
     */
    function owner() public view virtual returns (address) {
        return _owner;
    }

    /**
     * @dev Throws if called by any account other than the owner.
     */
    modifier onlyOwner() {
        require(owner() == _msgSender(), "Ownable: caller is not the owner");
        _;
    }

    /**
     * @dev Leaves the contract without owner. It will not be possible to call
     * `onlyOwner` functions anymore. Can only be called by the current owner.
     *
     * NOTE: Renouncing ownership will leave the contract without an owner,
     * thereby removing any functionality that is only available to the owner.
     */
    function renounceOwnership() public virtual onlyOwner {
        _setOwner(address(0));
    }

    /**
     * @dev Transfers ownership of the contract to a new account (`newOwner`).
     * Can only be called by the current owner.
     */
    function transferOwnership(address newOwner) public virtual onlyOwner {
        require(newOwner != address(0), "Ownable: new owner is the zero address");
        _setOwner(newOwner);
    }

    function _setOwner(address newOwner) private {
        address oldOwner = _owner;
        _owner = newOwner;
        emit OwnershipTransferred(oldOwner, newOwner);
    }
}
          

// SPDX-License-Identifier: MIT

pragma solidity ^0.8.0;

import "../utils/Context.sol";

/**
 * @dev Contract module which allows children to implement an emergency stop
 * mechanism that can be triggered by an authorized account.
 *
 * This module is used through inheritance. It will make available the
 * modifiers `whenNotPaused` and `whenPaused`, which can be applied to
 * the functions of your contract. Note that they will not be pausable by
 * simply including this module, only once the modifiers are put in place.
 */
abstract contract Pausable is Context {
    /**
     * @dev Emitted when the pause is triggered by `account`.
     */
    event Paused(address account);

    /**
     * @dev Emitted when the pause is lifted by `account`.
     */
    event Unpaused(address account);

    bool private _paused;

    /**
     * @dev Initializes the contract in unpaused state.
     */
    constructor() {
        _paused = false;
    }

    /**
     * @dev Returns true if the contract is paused, and false otherwise.
     */
    function paused() public view virtual returns (bool) {
        return _paused;
    }

    /**
     * @dev Modifier to make a function callable only when the contract is not paused.
     *
     * Requirements:
     *
     * - The contract must not be paused.
     */
    modifier whenNotPaused() {
        require(!paused(), "Pausable: paused");
        _;
    }

    /**
     * @dev Modifier to make a function callable only when the contract is paused.
     *
     * Requirements:
     *
     * - The contract must be paused.
     */
    modifier whenPaused() {
        require(paused(), "Pausable: not paused");
        _;
    }

    /**
     * @dev Triggers stopped state.
     *
     * Requirements:
     *
     * - The contract must not be paused.
     */
    function _pause() internal virtual whenNotPaused {
        _paused = true;
        emit Paused(_msgSender());
    }

    /**
     * @dev Returns to normal state.
     *
     * Requirements:
     *
     * - The contract must be paused.
     */
    function _unpause() internal virtual whenPaused {
        _paused = false;
        emit Unpaused(_msgSender());
    }
}
          

// SPDX-License-Identifier: MIT

pragma solidity ^0.8.0;

/**
 * @dev Contract module that helps prevent reentrant calls to a function.
 *
 * Inheriting from `ReentrancyGuard` will make the {nonReentrant} modifier
 * available, which can be applied to functions to make sure there are no nested
 * (reentrant) calls to them.
 *
 * Note that because there is a single `nonReentrant` guard, functions marked as
 * `nonReentrant` may not call one another. This can be worked around by making
 * those functions `private`, and then adding `external` `nonReentrant` entry
 * points to them.
 *
 * TIP: If you would like to learn more about reentrancy and alternative ways
 * to protect against it, check out our blog post
 * https://blog.openzeppelin.com/reentrancy-after-istanbul/[Reentrancy After Istanbul].
 */
abstract contract ReentrancyGuard {
    // Booleans are more expensive than uint256 or any type that takes up a full
    // word because each write operation emits an extra SLOAD to first read the
    // slot's contents, replace the bits taken up by the boolean, and then write
    // back. This is the compiler's defense against contract upgrades and
    // pointer aliasing, and it cannot be disabled.

    // The values being non-zero value makes deployment a bit more expensive,
    // but in exchange the refund on every call to nonReentrant will be lower in
    // amount. Since refunds are capped to a percentage of the total
    // transaction's gas, it is best to keep them low in cases like this one, to
    // increase the likelihood of the full refund coming into effect.
    uint256 private constant _NOT_ENTERED = 1;
    uint256 private constant _ENTERED = 2;

    uint256 private _status;

    constructor() {
        _status = _NOT_ENTERED;
    }

    /**
     * @dev Prevents a contract from calling itself, directly or indirectly.
     * Calling a `nonReentrant` function from another `nonReentrant`
     * function is not supported. It is possible to prevent this from happening
     * by making the `nonReentrant` function external, and make it call a
     * `private` function that does the actual work.
     */
    modifier nonReentrant() {
        // On the first call to nonReentrant, _notEntered will be true
        require(_status != _ENTERED, "ReentrancyGuard: reentrant call");

        // Any calls to nonReentrant after this point will fail
        _status = _ENTERED;

        _;

        // By storing the original value once again, a refund is triggered (see
        // https://eips.ethereum.org/EIPS/eip-2200)
        _status = _NOT_ENTERED;
    }
}
          

// SPDX-License-Identifier: MIT

pragma solidity ^0.8.0;

/**
 * @dev Interface of the ERC20 standard as defined in the EIP.
 */
interface IERC20 {
    /**
     * @dev Returns the amount of tokens in existence.
     */
    function totalSupply() external view returns (uint256);

    /**
     * @dev Returns the amount of tokens owned by `account`.
     */
    function balanceOf(address account) external view returns (uint256);

    /**
     * @dev Moves `amount` tokens from the caller's account to `recipient`.
     *
     * Returns a boolean value indicating whether the operation succeeded.
     *
     * Emits a {Transfer} event.
     */
    function transfer(address recipient, uint256 amount) external returns (bool);

    /**
     * @dev Returns the remaining number of tokens that `spender` will be
     * allowed to spend on behalf of `owner` through {transferFrom}. This is
     * zero by default.
     *
     * This value changes when {approve} or {transferFrom} are called.
     */
    function allowance(address owner, address spender) external view returns (uint256);

    /**
     * @dev Sets `amount` as the allowance of `spender` over the caller's tokens.
     *
     * Returns a boolean value indicating whether the operation succeeded.
     *
     * IMPORTANT: Beware that changing an allowance with this method brings the risk
     * that someone may use both the old and the new allowance by unfortunate
     * transaction ordering. One possible solution to mitigate this race
     * condition is to first reduce the spender's allowance to 0 and set the
     * desired value afterwards:
     * https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729
     *
     * Emits an {Approval} event.
     */
    function approve(address spender, uint256 amount) external returns (bool);

    /**
     * @dev Moves `amount` tokens from `sender` to `recipient` using the
     * allowance mechanism. `amount` is then deducted from the caller's
     * allowance.
     *
     * Returns a boolean value indicating whether the operation succeeded.
     *
     * Emits a {Transfer} event.
     */
    function transferFrom(
        address sender,
        address recipient,
        uint256 amount
    ) external returns (bool);

    /**
     * @dev Emitted when `value` tokens are moved from one account (`from`) to
     * another (`to`).
     *
     * Note that `value` may be zero.
     */
    event Transfer(address indexed from, address indexed to, uint256 value);

    /**
     * @dev Emitted when the allowance of a `spender` for an `owner` is set by
     * a call to {approve}. `value` is the new allowance.
     */
    event Approval(address indexed owner, address indexed spender, uint256 value);
}
          

// SPDX-License-Identifier: MIT

pragma solidity ^0.8.0;

/**
 * @dev Provides information about the current execution context, including the
 * sender of the transaction and its data. While these are generally available
 * via msg.sender and msg.data, they should not be accessed in such a direct
 * manner, since when dealing with meta-transactions the account sending and
 * paying for execution may not be the actual sender (as far as an application
 * is concerned).
 *
 * This contract is only required for intermediate, library-like contracts.
 */
abstract contract Context {
    function _msgSender() internal view virtual returns (address) {
        return msg.sender;
    }

    function _msgData() internal view virtual returns (bytes calldata) {
        return msg.data;
    }
}
          

// SPDX-License-Identifier: MIT

pragma solidity ^0.8.0;

/**
 * @dev Elliptic Curve Digital Signature Algorithm (ECDSA) operations.
 *
 * These functions can be used to verify that a message was signed by the holder
 * of the private keys of a given address.
 */
library ECDSA {
    enum RecoverError {
        NoError,
        InvalidSignature,
        InvalidSignatureLength,
        InvalidSignatureS,
        InvalidSignatureV
    }

    function _throwError(RecoverError error) private pure {
        if (error == RecoverError.NoError) {
            return; // no error: do nothing
        } else if (error == RecoverError.InvalidSignature) {
            revert("ECDSA: invalid signature");
        } else if (error == RecoverError.InvalidSignatureLength) {
            revert("ECDSA: invalid signature length");
        } else if (error == RecoverError.InvalidSignatureS) {
            revert("ECDSA: invalid signature 's' value");
        } else if (error == RecoverError.InvalidSignatureV) {
            revert("ECDSA: invalid signature 'v' value");
        }
    }

    /**
     * @dev Returns the address that signed a hashed message (`hash`) with
     * `signature` or error string. This address can then be used for verification purposes.
     *
     * The `ecrecover` EVM opcode allows for malleable (non-unique) signatures:
     * this function rejects them by requiring the `s` value to be in the lower
     * half order, and the `v` value to be either 27 or 28.
     *
     * IMPORTANT: `hash` _must_ be the result of a hash operation for the
     * verification to be secure: it is possible to craft signatures that
     * recover to arbitrary addresses for non-hashed data. A safe way to ensure
     * this is by receiving a hash of the original message (which may otherwise
     * be too long), and then calling {toEthSignedMessageHash} on it.
     *
     * Documentation for signature generation:
     * - with https://web3js.readthedocs.io/en/v1.3.4/web3-eth-accounts.html#sign[Web3.js]
     * - with https://docs.ethers.io/v5/api/signer/#Signer-signMessage[ethers]
     *
     * _Available since v4.3._
     */
    function tryRecover(bytes32 hash, bytes memory signature) internal pure returns (address, RecoverError) {
        // Check the signature length
        // - case 65: r,s,v signature (standard)
        // - case 64: r,vs signature (cf https://eips.ethereum.org/EIPS/eip-2098) _Available since v4.1._
        if (signature.length == 65) {
            bytes32 r;
            bytes32 s;
            uint8 v;
            // ecrecover takes the signature parameters, and the only way to get them
            // currently is to use assembly.
            assembly {
                r := mload(add(signature, 0x20))
                s := mload(add(signature, 0x40))
                v := byte(0, mload(add(signature, 0x60)))
            }
            return tryRecover(hash, v, r, s);
        } else if (signature.length == 64) {
            bytes32 r;
            bytes32 vs;
            // ecrecover takes the signature parameters, and the only way to get them
            // currently is to use assembly.
            assembly {
                r := mload(add(signature, 0x20))
                vs := mload(add(signature, 0x40))
            }
            return tryRecover(hash, r, vs);
        } else {
            return (address(0), RecoverError.InvalidSignatureLength);
        }
    }

    /**
     * @dev Returns the address that signed a hashed message (`hash`) with
     * `signature`. This address can then be used for verification purposes.
     *
     * The `ecrecover` EVM opcode allows for malleable (non-unique) signatures:
     * this function rejects them by requiring the `s` value to be in the lower
     * half order, and the `v` value to be either 27 or 28.
     *
     * IMPORTANT: `hash` _must_ be the result of a hash operation for the
     * verification to be secure: it is possible to craft signatures that
     * recover to arbitrary addresses for non-hashed data. A safe way to ensure
     * this is by receiving a hash of the original message (which may otherwise
     * be too long), and then calling {toEthSignedMessageHash} on it.
     */
    function recover(bytes32 hash, bytes memory signature) internal pure returns (address) {
        (address recovered, RecoverError error) = tryRecover(hash, signature);
        _throwError(error);
        return recovered;
    }

    /**
     * @dev Overload of {ECDSA-tryRecover} that receives the `r` and `vs` short-signature fields separately.
     *
     * See https://eips.ethereum.org/EIPS/eip-2098[EIP-2098 short signatures]
     *
     * _Available since v4.3._
     */
    function tryRecover(
        bytes32 hash,
        bytes32 r,
        bytes32 vs
    ) internal pure returns (address, RecoverError) {
        bytes32 s;
        uint8 v;
        assembly {
            s := and(vs, 0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff)
            v := add(shr(255, vs), 27)
        }
        return tryRecover(hash, v, r, s);
    }

    /**
     * @dev Overload of {ECDSA-recover} that receives the `r and `vs` short-signature fields separately.
     *
     * _Available since v4.2._
     */
    function recover(
        bytes32 hash,
        bytes32 r,
        bytes32 vs
    ) internal pure returns (address) {
        (address recovered, RecoverError error) = tryRecover(hash, r, vs);
        _throwError(error);
        return recovered;
    }

    /**
     * @dev Overload of {ECDSA-tryRecover} that receives the `v`,
     * `r` and `s` signature fields separately.
     *
     * _Available since v4.3._
     */
    function tryRecover(
        bytes32 hash,
        uint8 v,
        bytes32 r,
        bytes32 s
    ) internal pure returns (address, RecoverError) {
        // EIP-2 still allows signature malleability for ecrecover(). Remove this possibility and make the signature
        // unique. Appendix F in the Ethereum Yellow paper (https://ethereum.github.io/yellowpaper/paper.pdf), defines
        // the valid range for s in (301): 0 < s < secp256k1n ÷ 2 + 1, and for v in (302): v ∈ {27, 28}. Most
        // signatures from current libraries generate a unique signature with an s-value in the lower half order.
        //
        // If your library generates malleable signatures, such as s-values in the upper range, calculate a new s-value
        // with 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141 - s1 and flip v from 27 to 28 or
        // vice versa. If your library also generates signatures with 0/1 for v instead 27/28, add 27 to v to accept
        // these malleable signatures as well.
        if (uint256(s) > 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0) {
            return (address(0), RecoverError.InvalidSignatureS);
        }
        if (v != 27 && v != 28) {
            return (address(0), RecoverError.InvalidSignatureV);
        }

        // If the signature is valid (and not malleable), return the signer address
        address signer = ecrecover(hash, v, r, s);
        if (signer == address(0)) {
            return (address(0), RecoverError.InvalidSignature);
        }

        return (signer, RecoverError.NoError);
    }

    /**
     * @dev Overload of {ECDSA-recover} that receives the `v`,
     * `r` and `s` signature fields separately.
     */
    function recover(
        bytes32 hash,
        uint8 v,
        bytes32 r,
        bytes32 s
    ) internal pure returns (address) {
        (address recovered, RecoverError error) = tryRecover(hash, v, r, s);
        _throwError(error);
        return recovered;
    }

    /**
     * @dev Returns an Ethereum Signed Message, created from a `hash`. This
     * produces hash corresponding to the one signed with the
     * https://eth.wiki/json-rpc/API#eth_sign[`eth_sign`]
     * JSON-RPC method as part of EIP-191.
     *
     * See {recover}.
     */
    function toEthSignedMessageHash(bytes32 hash) internal pure returns (bytes32) {
        // 32 is the length in bytes of hash,
        // enforced by the type signature above
        return keccak256(abi.encodePacked("\x19Ethereum Signed Message:\n32", hash));
    }

    /**
     * @dev Returns an Ethereum Signed Typed Data, created from a
     * `domainSeparator` and a `structHash`. This produces hash corresponding
     * to the one signed with the
     * https://eips.ethereum.org/EIPS/eip-712[`eth_signTypedData`]
     * JSON-RPC method as part of EIP-712.
     *
     * See {recover}.
     */
    function toTypedDataHash(bytes32 domainSeparator, bytes32 structHash) internal pure returns (bytes32) {
        return keccak256(abi.encodePacked("\x19\x01", domainSeparator, structHash));
    }
}