> 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 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://perfectpool.gitbook.io/perfect-pool/game-contracts/club-world-cup.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.