A WebSocket-based chess platform where multiple rooms can host individual games. Each room has a specific entry fee, and exactly two players can join each room.
================================================================================
CHESS DUEL PREDICTION MARKET
Web3 Gaming & Betting Platform
================================================================================
PROJECT OVERVIEW
----------------
Chess Duel Prediction Market is a revolutionary Web3 platform that combines
real-time chess gameplay with decentralized prediction markets. Players can
compete in chess duels while spectators and participants can bet on match
outcomes using blockchain-based smart contracts. The platform features
multi-chain support, real-time WebSocket communication, and a comprehensive
betting ecosystem.
================================================================================
KEY FEATURES
================================================================================
1. REAL-TIME CHESS GAMEPLAY
- Live chess matches with WebSocket-based real-time synchronization
- Full chess.js integration for move validation and game logic
- Interactive chess board with react-chessboard
- Support for multiple concurrent game rooms
- Spectator mode for watching live matches
- Complete move history tracking
2. DECENTRALIZED PREDICTION MARKETS
- Create prediction markets for any chess match
- Bet on three possible outcomes: Player 1 Win, Player 2 Win, or Draw
- Dynamic odds based on betting pool distribution
- Automatic reward distribution to winning bettors
- Transparent, on-chain betting with smart contracts
- Real-time market statistics and pool tracking
3. ESCROW SYSTEM FOR MATCHES
- Secure entry fee deposits using blockchain escrow contracts
- Winner-takes-all payout system (minus platform fee)
- Draw resolution with split refunds
- Automatic payout distribution upon match resolution
- Multi-signature support for secure fund management
4. MULTI-CHAIN SUPPORT
- Aptos blockchain integration with Move smart contracts
- Mantle blockchain integration with Solidity smart contracts
- Cross-chain wallet connectivity (Privy, Wagmi)
- ERC20 token support for betting markets
- Flexible deployment across multiple networks
5. USER EXPERIENCE
- Modern, responsive React frontend with Tailwind CSS
- Wallet connection via Privy (supports multiple wallet types)
- User registration and profile management
- Portfolio tracking for betting positions
- Match history and statistics
- Real-time market updates via WebSocket
6. ROOM & MATCH MANAGEMENT
- Create custom game rooms with entry fees
- Two-player match system
- Room status tracking (Waiting, Active, Finished)
- Automatic match result detection (checkmate, draw, stalemate)
- Player color assignment (first player = White, second = Black)
================================================================================
TECHNICAL ARCHITECTURE
================================================================================
FRONTEND STACK
--------------
- React 18 with TypeScript
- Vite for build tooling and development
- Tailwind CSS for styling
- React Router for navigation
- Socket.IO Client for real-time communication
- Wagmi & Viem for Ethereum/Mantle blockchain interaction
- Privy for wallet authentication and management
- React Query (TanStack Query) for data fetching
- Chess.js for client-side game logic
- React Chessboard for UI components
BACKEND STACK
-------------
- Node.js with TypeScript
- Express.js REST API
- Socket.IO for WebSocket server
- MongoDB with Mongoose ODM
- Chess.js for server-side game validation
- Netlify Functions for serverless deployment
- Morgan for HTTP request logging
- CORS enabled for cross-origin requests
SMART CONTRACTS
---------------
Aptos (Move Language):
- chess_escrow.move: Escrow contract for match entry fees
- prediction_market.move: Prediction market contract for betting
Mantle (Solidity):
- Duel.sol: ERC20 token contract (DUEL token)
- PredictionMarket.sol: Prediction market contract
- ChessEscrow.sol: Escrow contract for matches
- Counter.sol: Example/test contract
DATABASE SCHEMA
---------------
- User: Player profiles and wallet addresses
- Match: Chess match data and status
- GameMove: Individual chess moves with timestamps
- PlayerMatchStat: Player statistics per match
================================================================================
PROJECT STRUCTURE
================================================================================
duel-prediction-market/
├── frontend/ # React frontend application
│ ├── src/
│ │ ├── components/ # React components
│ │ │ ├── ChessBoard.tsx
│ │ │ ├── BettingInterface.tsx
│ │ │ ├── MarketCard.tsx
│ │ │ ├── RoomList.tsx
│ │ │ ├── CreateRoom.tsx
│ │ │ ├── SpectatorView.tsx
│ │ │ └── UserRegistration.tsx
│ │ ├── pages/ # Route pages
│ │ │ ├── Browse.tsx
│ │ │ ├── MarketDetail.tsx
│ │ │ ├── MatchDetail.tsx
│ │ │ ├── MatchHistory.tsx
│ │ │ └── Portfolio.tsx
│ │ ├── hooks/ # Custom React hooks
│ │ │ ├── blockchain/ # Web3 hooks
│ │ │ │ ├── useMatch.ts
│ │ │ │ ├── useMatchActions.ts
│ │ │ │ ├── useMatchContract.ts
│ │ │ │ ├── useMatchReads.ts
│ │ │ │ └── useWalletBalance.ts
│ │ │ ├── useMarketUpdates.ts
│ │ │ └── useOnchainHooks.ts
│ │ ├── services/ # API and service layers
│ │ │ ├── bettingService.ts
│ │ │ ├── matchService.ts
│ │ │ ├── socketService.ts
│ │ │ └── userService.ts
│ │ ├── config/ # Configuration
│ │ │ ├── chains.ts
│ │ │ ├── queryClient.ts
│ │ │ └── wagmi.ts
│ │ └── contracts/ # Contract ABIs
│ │ ├── PREDICTION_MARKET.json
│ │ ├── CHESS_ESCROW.json
│ │ └── PredictionMarketABI.ts
│ └── package.json
│
├── backend/ # Node.js backend server
│ ├── src/
│ │ ├── app.ts # Express app setup
│ │ ├── server.ts # HTTP & WebSocket server
│ │ ├── controllers/ # Route controllers
│ │ │ ├── match.controller.ts
│ │ │ └── user.controller.ts
│ │ ├── services/ # Business logic
│ │ │ ├── chess.service.ts
│ │ │ ├── match.service.ts
│ │ │ ├── market.service.ts
│ │ │ ├── match.result.service.ts
│ │ │ ├── room.service.ts
│ │ │ └── user.service.ts
│ │ ├── routes/ # API routes
│ │ │ ├── match.routes.ts
│ │ │ ├── user.routes.ts
│ │ │ ├── markets.ts
│ │ │ └── positions.ts
│ │ ├── sockets/ # WebSocket handlers
│ │ │ └── index.ts
│ │ ├── models/ # MongoDB models
│ │ │ ├── User.ts
│ │ │ ├── Match.ts
│ │ │ ├── GameMove.ts
│ │ │ └── PlayerMatchStat.ts
│ │ ├── workers/ # Background workers
│ │ │ └── matchStatusWorker.ts
│ │ └── config/
│ │ └── database.ts
│ ├── netlify/
│ │ └── functions/
│ │ └── api.ts # Serverless functions
│ └── package.json
│
├── contracts/ # Aptos Move contracts
│ ├── sources/
│ │ ├── chess_escrow.move
│ │ └── prediction_market.move
│ └── tests/
│ ├── escrow_tests.move
│ └── prediction_market_tests.move
│
├── mantleContracts/ # Mantle Solidity contracts
│ ├── contracts/
│ │ ├── Duel.sol
│ │ ├── PredictionMarket.sol
│ │ ├── ChessEscrow.sol
│ │ └── Counter.sol
│ ├── test/
│ │ ├── PredictionMarket.t.sol
│ │ ├── ChessEscrow.t.sol
│ │ └── Duel.t.sol
│ └── hardhat.config.ts
│
└── scripts/ # Utility scripts
├── prediction-market.ts
├── escrow.ts
└── test-prediction-market.ts
================================================================================
SMART CONTRACT FUNCTIONALITY
================================================================================
PREDICTION MARKET CONTRACT
--------------------------
Functions:
- create_market(): Create a new prediction market for a match
- bet(): Place a bet on a specific outcome (Player 1, Player 2, or Draw)
- resolve_market(): Resolve the market with the winning outcome
- claim_rewards(): Claim winnings after market resolution
- get_market_info(): Query market statistics and pool sizes
Features:
- Automatic odds calculation based on pool distribution
- Proportional reward distribution to winners
- Secure fund escrow until market resolution
- Prevention of betting after market resolution
- One-time reward claiming per user
ESCROW CONTRACT
---------------
Functions:
- create_escrow(): Create escrow for a match with entry fee
- deposit(): Players deposit their entry fees
- resolve_win(): Distribute winnings to match winner (minus 5% fee)
- resolve_draw(): Split funds between players in case of draw (minus 5% fee)
Features:
- Two-player deposit requirement
- Winner-takes-all payout system
- Draw resolution with equal split
- Platform fee (5%) for sustainability
- Secure fund holding until match completion
================================================================================
REAL-TIME FEATURES
================================================================================
WEBSOCKET EVENTS (Socket.IO)
----------------------------
Client → Server:
- create_room: Create a new game room
- join_room: Join an existing room
- make_move: Submit a chess move
- get_rooms: Fetch available rooms
- get_game_state: Get current game state
Server → Client:
- room_created: Room successfully created
- room_joined: Successfully joined room
- move_made: Chess move broadcasted
- game_state: Updated game state
- rooms_updated: Available rooms list updated
- error: Error notifications
REAL-TIME UPDATES
-----------------
- Live chess move synchronization
- Instant market statistics updates
- Real-time betting pool changes
- Match status notifications
- Portfolio balance updates
================================================================================
USE CASES & SCENARIOS
================================================================================
1. PLAYER CREATES A MATCH
- Player connects wallet and registers
- Creates a new chess room with entry fee
- Deposits entry fee via escrow contract
- Waits for opponent to join
2. PLAYER JOINS A MATCH
- Browse available matches
- Select a match and join
- Deposit entry fee via escrow
- Game begins automatically
3. SPECTATORS BET ON MATCHES
- View live matches in progress
- Analyze player statistics
- Place bets on predicted outcome
- Monitor betting pool and odds
- Claim rewards after match resolution
4. MATCH RESOLUTION
- Game ends (checkmate, draw, or stalemate)
- Backend detects result automatically
- Escrow contract distributes winnings
- Prediction market resolves
- Winners can claim rewards
5. PORTFOLIO MANAGEMENT
- View all active betting positions
- Track potential winnings
- Monitor match outcomes
- Claim rewards from resolved markets
- View betting history
================================================================================
BLOCKCHAIN INTEGRATION
================================================================================
WALLET CONNECTIVITY
-------------------
- Privy integration for multi-wallet support
- Wagmi hooks for Ethereum/Mantle interaction
- Viem for low-level blockchain operations
- Support for MetaMask, WalletConnect, Coinbase Wallet, etc.
ON-CHAIN OPERATIONS
-------------------
- Token balance queries
- Smart contract function calls
- Transaction signing and submission
- Event listening for contract updates
- Gas estimation and optimization
MULTI-CHAIN DEPLOYMENT
----------------------
- Aptos: Move contracts for escrow and prediction markets
- Mantle: Solidity contracts with ERC20 token support
- Configurable chain selection in frontend
- Network-specific contract addresses
================================================================================
SECURITY FEATURES
================================================================================
- Smart contract access control (admin roles)
- Input validation on all contract functions
- Reentrancy protection
- Secure fund escrow until match resolution
- One-time reward claiming prevention
- Move validation to prevent invalid chess moves
- WebSocket authentication and room access control
================================================================================
DEPLOYMENT & INFRASTRUCTURE
================================================================================
FRONTEND DEPLOYMENT
-------------------
- Vite build for optimized production bundle
- Static hosting ready (Vercel, Netlify, etc.)
- Environment variable configuration
- Contract address configuration per network
BACKEND DEPLOYMENT
------------------
- Netlify Functions for serverless deployment
- MongoDB Atlas for database hosting
- Socket.IO server for WebSocket connections
- Environment-based configuration
SMART CONTRACT DEPLOYMENT
-------------------------
- Aptos: Move package deployment
- Mantle: Hardhat deployment scripts
- Testnet and mainnet support
- Contract verification on block explorers
================================================================================
FUTURE ENHANCEMENTS
================================================================================
- Tournament system with brackets
- Elo rating system for players
- Chat functionality during matches
- Advanced analytics and statistics
- Mobile app development
- Cross-chain bridge integration
- NFT rewards for achievements
- Governance token for platform decisions
- Staking mechanism for platform rewards
================================================================================
TECHNICAL HIGHLIGHTS
================================================================================
✅ Full-stack TypeScript application
✅ Real-time WebSocket communication
✅ Multi-chain blockchain integration
✅ Smart contract development (Move & Solidity)
✅ Decentralized prediction markets
✅ Secure escrow system
✅ Modern React frontend with hooks
✅ RESTful API with Express.js
✅ MongoDB database with Mongoose
✅ Wallet connectivity (Privy, Wagmi)
✅ Responsive UI with Tailwind CSS
✅ Chess game logic integration
✅ Serverless deployment ready
================================================================================
DEMONSTRATION VALUE
================================================================================
This project demonstrates:
- Advanced Web3 development skills
- Smart contract architecture and security
- Real-time application development
- Multi-chain blockchain integration
- Full-stack development capabilities
- Modern React patterns and hooks
- Database design and management
- WebSocket real-time communication
- Game development integration
- DeFi/prediction market mechanics
================================================================================
TEAM & DEVELOPMENT
================================================================================
Built for hackathon demonstration with focus on:
- Complete end-to-end functionality
- Production-ready code quality
- Comprehensive feature set
- Modern development practices
- Scalable architecture
- User experience optimization
================================================================================
LICENSE
================================================================================
ISC License
================================================================================
END OF PROJECT DESCRIPTION
================================================================================