> For the complete documentation index, see [llms.txt](https://perfectpool.gitbook.io/perfect-pool/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://perfectpool.gitbook.io/perfect-pool/game-contracts/club-world-cup.md). # Club World Cup ### Overview The ClubWorldCupEntry contract manages the game for a Club World Cup tournament. It provides a comprehensive system for tournament participation and prize distribution with the following key features: * Minting NFTs that represent bets on game outcomes * Managing game pots and a global jackpot * Handling prize claims for winners * Iterative processing of game results to determine winners * Integration with a GamesHub contract for role-based access control * Customizable parameters such as ticket price and prize percentage **Base Sepolia Contract**: **Base Contract**: **Hyperliquid Contract:** ### Events * **PriceChanged**: Emitted when the ticket price is changed * `newPrice`: `uint256` * **ProtocolFeeChanged**: Emitted when the protocol fee is changed * `newFee`: `uint8` * **BetPlaced**: Emitted when a new bet is placed * `user`: `address` (indexed) * `gameYear`: `uint256` * `tokenId`: `uint256` * `bets`: `uint8[47]` * **PrizeClaimed**: Emitted when a prize is claimed * `user`: `address` (indexed) * `tokenId`: `uint256` * `prize`: `uint256` * **PrizeIncreased**: Emitted when the prize pot is increased * `gameYear`: `uint256` * `amount`: `uint256` * **IterateGameData**: Emitted when game data iteration occurs * `gameYear`: `uint256` * `iterateStart`: `uint256` * `iterateEnd`: `uint256` * **IterationFinished**: Emitted when game iteration is complete * `gameYear`: `uint256` * **IterationSizeChanged**: Emitted when iteration size is changed * `iterationSize`: `uint256` * **GamePotDismissed**: Emitted when a game pot is dismissed * `gameYear`: `uint256` * `amount`: `uint256` * **TimeToDismissPotChanged**: Emitted when time to dismiss pot is changed * `timeToDismissPot`: `uint256` * **DebugGamePoints**: Emitted during game iteration to track points * `_gameYear`: `uint256` - The year of the game * `_points`: `uint8` - Current points * `_maxPoints`: `uint8` - Maximum points found ### Structs * **GameData**: Contains all data for a specific game year * `tokenIds`: `uint256[]` - List of all token IDs for the game * `pointsToTokenIds`: `mapping(uint8 => uint256[])` - Maps points to token IDs * `iterateStart`: `uint256` - Start position for iteration * `iterateEnd`: `uint256` - End position for iteration * `pot`: `uint256` - Total pot for the game * `points`: `uint8` - Maximum points achieved * `potDismissed`: `bool` - Whether pot has been dismissed ### State Variables * **gamesHub**: `IGamesHub public` - GamesHub contract interface * **token**: `IERC20 public` - USDC token contract interface * **price**: `uint256 public` - Price to mint a new token * **iterationSize**: `uint256 public` - Number of tokens to process per iteration * **protocolFee**: `uint8 public` - Fee percentage in basis points (100 = 1%) * **timeToDismissPot**: `uint256 public` - Time after game end to dismiss pot * **gameRunning**: `bool public` - Whether a game is currently running ### Modifiers * `onlyAdmin`: Requires caller to have ADMIN role * `onlyGameContract`: Requires caller to have WORLD\_CUP role * `onlyExecutor`: Requires caller to have EXECUTOR or ADMIN role ### Functions #### Constructor * Description: Initializes contract parameters * Arguments: * `_gamesHub`: `address` - Address of the GamesHub contract * `_token`: `address` - Address of the USDC token contract #### Admin Functions #### closeBets * Description: Closes the betting period for a specific game year * Arguments: * `_gameYear`: `uint256` - The year of the game * Modifiers: * `onlyGameContract` #### changePrice * Description: Changes the ticket price * Arguments: * `_newPrice`: `uint256` - New price for tickets * Modifiers: * `onlyAdmin` #### changeProtocolFee * Description: Changes the protocol fee percentage * Arguments: * `_newFee`: `uint8` - New protocol fee percentage * Modifiers: * `onlyAdmin` #### changeTimeToDismissPot * Description: Changes the time required to wait before dismissing pot * Arguments: * `_newTime`: `uint256` - New time in days (minimum 15) * Modifiers: * `onlyAdmin` #### changeIterationSize * Description: Changes the number of tokens processed per iteration * Arguments: * `_newSize`: `uint256` - New iteration size * Modifiers: * `onlyAdmin` #### User Functions #### safeMint * Description: Mints a new token and places a bet * Arguments: * `_gameYear`: `uint256` - Year of the game * `bets`: `uint8[47]` - Array of bet choices * Modifiers: * `nonReentrant` #### claimPrize * Description: Claims prize for a single token * Arguments: * `_tokenId`: `uint256` - ID of the token to claim prize for * Modifiers: * `nonReentrant` #### claimAllPrizes * Description: Claims prizes for multiple tokens at once * Arguments: * `_tokenIds`: `uint256[]` - Array of token IDs to claim prizes for * Modifiers: * `nonReentrant` #### increasePrize * Description: Increases the prize pot for a specific game year * Arguments: * `_gameYear`: `uint256` - Year of the game * `_amount`: `uint256` - Amount to add to the pot * Visibility: * `external` #### Executor Functions #### iterateGameTokenIds * Description: Processes a batch of tokens to find winners * Arguments: * `_gameYear`: `uint256` - Year of the game * `_iterateStart`: `uint256` - Start index * `_iterateEnd`: `uint256` - End index * Modifiers: * `onlyExecutor` #### dismissGamePot * Description: Dismisses unclaimed pot after waiting period * Arguments: * `_gameYear`: `uint256` - Year of the game * Modifiers: * `onlyExecutor` #### View Functions #### calculatePoints * Description: Calculates points for a specific bet * Arguments: * `tokenId`: `uint256` - ID of the token * Returns: * `points`: `uint8` - Points for the bet * `resultsArray`: `uint8[47]` - Results array (0 for not defined, 1 for correct, 2 for wrong) #### tokenURI * Description: Gets the URI for a token's metadata * Arguments: * `_tokenId`: `uint256` - ID of the token * Returns: * `string` - Token URI #### getBetData * Description: Gets bet data for a token * Arguments: * `_tokenId`: `uint256` - ID of the token * Returns: * `uint8[47]` - Array of bets #### getGameId * Description: Gets the game year for a token * Arguments: * `_tokenId`: `uint256` - ID of the token * Returns: * `uint256` - Game year #### getTeamSymbols * Description: Gets team symbols for a token's bets * Arguments: * `_tokenId`: `uint256` - ID of the token * Returns: * `string[47]` - Array of team symbols #### amountPrizeClaimed * Description: Gets prize info for a token * Arguments: * `_tokenId`: `uint256` - ID of the token * Returns: * `amountToClaim`: `uint256` - Amount available to claim * `claimed`: `bool` - Whether prize was claimed #### isGameFinished * Description: Checks if a game is finished * Arguments: * `_gameYear`: `uint256` - Year of the game * Returns: * `bool` - Whether game is finished #### getGamePot * Description: Gets total pot for a game * Arguments: * `_gameYear`: `uint256` - Year of the game * Returns: * `uint256` - Total pot amount #### getGamePlayers * Description: Gets number of players in a game * Arguments: * `_gameYear`: `uint256` - Year of the game * Returns: * `uint256` - Number of players #### getGameTokenIds * Description: Gets all token IDs for a game * Arguments: * `_gameYear`: `uint256` - Year of the game * Returns: * `uint256[]` - Array of token IDs #### getGameWinners * Description: Gets winning token IDs for a game * Arguments: * `_gameYear`: `uint256` - Year of the game * Returns: * `uint256[]` - Array of winning token IDs #### betStatus * Description: Gets the bet status for a specific year * Arguments: * `_gameYear`: `uint256` - Year of the game * Returns: * `bool` - Whether bets are closed