feat: Implement tic-tac-toe game tournament

[psychemist]

Tic Tac Toe Game Full Feature Upgrade: Tournament Integration

Summary

A comprehensive tournament upgrade to the tic-tac-toe game system, integrating smart contracts, frontend, and developer tooling for a seamless competitive experience. The changes include new contract logic for creating tournament games, automatic round advancement, robust frontend tournament management, and scripts for deployment and contract setup.

What's New

• Smart Contracts

  • tic_tac_toe_tournament.clar: Added functions for creating, joining, and starting tournaments, automatic bracket advancement, next-round match creation, and improved error handling.
  • tic_tac_toe.clar: Enhanced integrated tournament game logic, winner reporting, and rematch creation for ties.
  • game-tournament-trait.clar: Trait-based contract calls to avoid circular references.

• Frontend

  • Tournament creation, registration, bracket, and match play UI.
  • Caching and rate-limit mitigation for contract calls.
  • Improved wallet integration (Leather/Xverse) and network handling.
  • Components for tournament list, registration, bracket, and active match display.

• Scripts & Tooling

  • setup-tournament.js: Script for setting tournament contract principal post-deployment.
  • Devnet/testnet deployment plans and .env integration.

• Testing & Developer Experience

  • Full integration tests for tournament and game contracts.
  • Clarinet simnet/devnet support for local testing.
  • Improved error messages and contract checks.

Key Features

1. Automatic Round Advancement: Tournament contract now starts new rounds and matches automatically after each bracket is completed.
2. Rematch on Tie: Game contract creates rematch games for tournament matches that end in a tie.
3. Winner Reporting: Game contract reports winners to the tournament contract for bracket progression.
4. Frontend Tournament Management: Users can create, join, and play tournament matches with real-time bracket updates.
5. Rate-Limit & Caching: Frontend caches contract calls and staggers requests to avoid API rate limits.
6. Wallet & Network Fixes: Improved handling for testnet/mainnet addresses and wallet connection edge cases.

Technical Implementation

Smart Contracts

• Written in Clarity v3
• Public functions for tournament creation, joining, starting, and winner reporting
• Private helpers for round/match management and error handling
• Trait-based contract calls to avoid circular references

Frontend

• Next.js 14 App Router, TypeScript, React
• Tournament pages:bcreate, view, bracket, play
• Components: tournament list, registration, bracket, and play-game
• Hooks: use-tournaments and use-stacks for conntract interaction
• Caching and error handling for contract calls

Deployment

• Contracts deployable to Devnet, Simnet, and Testnet
• Example addresses: ST16*******QXRW88.tic_tac_toe
• Deployment plans: deployments/default.devnet-plan.yaml, deployments/default.simnet-plan.yaml, deployments/default.testnet-plan.yaml

Tournament Flow Diagram

+----------+     +------+     +-------+     +------------+     +----------------+
| Create   | --> | Join | --> | Start | --> | Play Match | --> | Match Outcome? |
|Tournament|     |      |     |       |     +------------+     +----------------+
+----------+     +------+     +-------+           ^                    |
                                                  |                    |
     +--------------------------------------------+                    |
     |                                                                 |
     |                                                                 v
+----v-----+                                                      +----+----+
| Rematch  |                                                      |   Tie?  |
+----------+                                                      +----+----+
     ^                                                                 |
     |                                                                 |
     +-----------------------------------------------------------------+
                               Yes                                     | No
                                                                       v
                                                               +-------+-------+
                                                               | Report Winner |
                                                               +-------+-------+
                                                                       |
                                                                       v
                                                             +---------+---------+
                                                             |   All matches in  |
                                                             |   round finished? |
                                                             +---------+---------+
                                                                       |
                                                              +--------+--------+
                                                              | Yes             | No
                                                              v                 v
                                                        +-------+-------+     +--------+--------+
                                                        |  Is this the  |     |  Wait for other |
                                                        | Final Round?  |     |     players     |
                                                        +-------+-------+     +--------+--------+
                                                                |
                                                       +--------+--------+
                                                       | Yes             | No
                                                       v                 v
                                               +-------+-------+     +--------+--------+
                                               |   Tournament  |     |    Advance to   |
                                               |    Winner!    |     |    Next Round   |
                                               +---------------+     +--------+--------+
                                                                              |
                                                                              |
                                           (Back to Play Match) <-------------+

Step-by-Step Tournament Gameplay Flow:

1. Create Tournament: A user creates a new tournament.
2. Join Tournament: Players join the tournament until it's full or the registration period ends.
3. Start Tournament: The tournament begins, and the first round of matches is generated.
4. Play Match: Players play their assigned matches.
5. Match Outcome: After a match, the result is determined.
6. Tie: If the match is a tie, a rematch is created, and the players play again.
7. Win/Loss: If there is a winner, the result is reported.
8. Round Completion: The system checks if all matches in the current round are finished.
9. Advance Round: If the round is complete and it's not the final round, the tournament advances to the next round, and new matches are created.
10. Final Round: If the round is complete and it is the final round, the winner of the final match is the tournament winner.
11. Tournament Winner: The tournament concludes, and a winner is declared.

How to Test

Run Contract Checks

clarinet check

Run Unit & Integration Tests

npm install
npm run test

Deploy to Devnet

clarinet devnet start
clarinet deployments apply --devnet

Deploy to Testnet

• Add mnemonic (seed phrase) to settings/Testnet.toml

clarinet deployments apply --testnet

Use Setup Script

cp .env.example .env

• Fill in environment variables in .env file

node scripts/setup-tournament.js

Run Frontend Locally

cd frontend
npm install
npm run dev

• Navigate to localhost:3000/tournaments on your machine.
• Connect your wallets, join an tournament and play tic-tac-toe game to your heart's content.

File-by-File Change Summary

• contracts/tic_tac_toe_tournament.clar: Added automatic round advancement, next-round match creation, improved error handling, and trait-based contract calls.
• contracts/tic_tac_toe.clar: Enhanced tournament game logic, winner reporting, rematch creation for ties, and trait-based contract calls.
• contracts/game-tournament-trait.clar: Defined trait for tournament-game contract interaction.
• frontend/lib/tournament-contract.ts: Added contract call functions for tournament creation, joining, starting, round advancement, winner reporting, and bracket management. Integrated caching and error handling.
• frontend/lib/contract.ts: Updated game creation logic to support tournament context and contract integration.
• frontend/components/tournament-registration.tsx: Implemented registration UI, entry fee display, and player list. Added logic to prevent joining full tournaments.
• frontend/components/tournament-bracket.tsx: Built bracket visualization, match navigation, and round status display.
• frontend/components/tournament-list.tsx: Created tournament list/grid UI, status badges, and navigation to detail pages.
• frontend/hooks/use-tournaments.ts: Added hooks for tournament state management, contract calls, and polling for updates.
• frontend/hooks/use-stacks.ts: Improved wallet connection logic, network handling, and contract call integration.
• frontend/app/tournaments/[tournamentId]/page.tsx: Tournament detail page, bracket visualization, registration, and active match display.
• frontend/app/tournaments/create/page.tsx: Tournament creation form, input validation, and contract call integration.
• frontend/app/tournaments/page.tsx: Tournament lobby, listing, and navigation.
• scripts/setup-tournament.js: Script for setting tournament contract principal post-deployment, .env integration, and improved error handling.
• deployments/default.devnet-plan.yaml: Deployment plan for Devnet, contract order and addresses.
• deployments/default.testnet-plan.yaml: Deployment plan for Testnet, contract order and addresses.
• deployments/default.simnet-plan.yaml: Deployment plan for Simnet, contract order and addresses.
• Clarinet.toml: Updated contract paths, deployment settings, and environment configuration.