🎮 Web3 Poker Game

A fully decentralized Texas Hold'em poker game built on Avalanche blockchain with AI opponents, real money stakes, and Supabase backend for persistent game history and leaderboards.

✨ Features

🎯 Core Game

• 3-Player Texas Hold'em - Play against 2 AI opponents
• AI Personalities - AGGRESSIVE, TIGHT, LOOSE, CONSERVATIVE personalities
• Smart Hand Evaluation - pokersolver library for accurate hand rankings
• Real Betting - Chip stacks, bet sliders, all-in mechanics
• Game Stages - PreFlop, Flop, Turn, River, Showdown

💰 Blockchain Integration

• Real Money Poker - Entry fees in AVAX, winner payouts from smart contract
• Wallet Support - MetaMask & Core Wallet
• Avalanche Fuji - Testnet for development (~$0.06 per game)
• Smart Contract - Solidity escrow (joinGame, payWinner, setEntryFee)
• On-Chain Transparency - All transactions logged on blockchain

🗄️ Backend & Database

• Supabase PostgreSQL - Persistent game history
• Player Profiles - Wallet-based identification
• Nodepoints Loyalty - Earn points for wins (50 base + 10×profit)
• Leaderboard - Top 10 rankings by nodepoints
• Game Analytics - W/L record, ROI, win streaks

🎨 UI/UX

• Beautiful Dark Theme - Modern gradient design
• Smooth Animations - Framer Motion transitions
• Responsive Design - Works on desktop & tablet
• Real-Time Logging - Game ledger with transaction hashes
• Settings Panel - Contract address configuration

🚀 Quick Start

Prerequisites

• Node.js 16+
• MetaMask or Core Wallet
• Test AVAX from Avalanche Faucet (free)

Installation

1. Clone & Install

   git clone <your-repo>
   cd web3-poker
   npm install

2. Setup Environment Variables

   cp .env.example .env.local
   # Add your Supabase credentials if desired
   # (Optional - game works without backend)

3. Run Locally

   npm run dev
   # Opens at http://localhost:3000

4. Deploy Smart Contract (Optional - for real stakes)

   • Go to https://remix.ethereum.org/
   • Copy PokerGame.sol
   • Deploy to Avalanche Fuji
   • Update contract address in Settings panel

📋 Technology Stack

Layer	Technology
Frontend	React 19 + TypeScript + Vite
Styling	Tailwind CSS + Motion animations
Blockchain	ethers.js v6 + Solidity + Avalanche
Backend	Supabase (PostgreSQL)
Game Logic	pokersolver + custom AI
Wallets	MetaMask + Core Wallet

📂 Project Structure

web3-poker/
├── src/
│   ├── lib/
│   │   ├── gameLogic.ts         # Poker rules & AI
│   │   ├── web3.ts              # Blockchain integration
│   │   └── supabaseClient.ts     # Database operations
│   ├── components/
│   │   ├── PokerGame.tsx        # Main game component
│   │   └── ui/                  # shadcn components
│   ├── App.tsx
│   └── main.tsx
├── PokerGame.sol                # Smart contract
├── .env.example                 # Environment template
├── vite.config.ts               # Build config
├── tsconfig.json                # TypeScript config
└── package.json

🎯 Game Rules

Hand Rankings

Follows standard poker hand rankings (High Card → Royal Flush)

Betting

• Starting chips: 1000
• Minimum bet: 10
• No limit (pot-style betting)
• All-in allowed

Stages

1. PreFlop - 2 hole cards, first betting round
2. Flop - 3 community cards, betting round
3. Turn - 4th community card, betting round
4. River - 5th community card, final betting round
5. Showdown - Best 5-card hand wins pot

🤖 AI Opponent Personalities

Type	Playstyle	Aggression
AGGRESSIVE	Bluffs often, raises frequently	90%
TIGHT	Plays premium hands only	50%
LOOSE	Plays many hands, loose calls	70%
CONSERVATIVE	Folding-heavy, risk-averse	30%

💳 Supabase Setup (Optional)

Game works perfectly without Supabase, but with setup you get persistent stats!

See SUPABASE_SETUP_GUIDE.md for detailed instructions.

Quick version:

1. Create free account at https://supabase.com
2. Get URL + Anon Key from Settings → API
3. Update .env.local with credentials
4. Run SQL schema in Supabase editor
5. Game automatically syncs player stats

🔗 Smart Contract

Deploy PokerGame.sol on Avalanche Fuji:

contract PokerGame {
  function joinGame() payable public    // Pay entry fee
  function payWinner(address winner) onlyOwner  // Payout winner
  function setEntryFee(uint256 fee) onlyOwner   // Admin control
}

See REMIX_INTEGRATION_GUIDE.md for step-by-step deployment.

🧪 Testing

npm run dev      # Start dev server
npm run build    # Compile for production
npm run preview  # Test production build locally
npm run lint     # Check TypeScript

📊 Game Statistics

• Gas Cost: ~$0.06 per game on Avalanche Fuji
• Block Time: 2-3 seconds
• UI Load Time: <2 seconds
• Hand Evaluation: Instant (<100ms)

🔐 Security Notes

• Private keys never leave your wallet
• Smart contract handles fund escrow
• Supabase auth via wallet signature (EIP-191)
• RLS policies restrict database access
• Contract is NOT audited (development version)

🎓 Architecture

User Wallet (MetaMask/Core)
    ↓
ethers.js (Web3 Library)
    ↓
PokerGame.sol (Avalanche Blockchain)
    ↓
Game Logic + AI (Client-side)
    ↓
Supabase (Optional: Game History & Stats)
    ↓
React UI (Tailwind + shadcn)

📚 Documentation

• PROJECT_STATUS.md - Complete project overview
• SUPABASE_SETUP_GUIDE.md - Backend configuration
• REMIX_INTEGRATION_GUIDE.md - Smart contract deployment
• AVALANCHE_CORE_SETUP.md - Network + wallet setup
• ON_CHAIN_DEPLOYMENT.md - 5-minute quickstart

🚀 Deployment

Testnet (Avalanche Fuji)

1. Deploy smart contract on Remix (free)
2. Set up Supabase (free tier)
3. Run npm run build
4. Deploy to Vercel/Netlify

Mainnet (Production)

• Deploy contract on Avalanche C-Chain
• Use mainnet Supabase project
• Add security policies (RLS)
• Audit smart contract before real funds

See ON_CHAIN_DEPLOYMENT.md for instructions.

🤝 Contributing

1. Fork the repo
2. Create feature branch (git checkout -b feature/amazing)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push branch (git push origin feature/amazing)
5. Open Pull Request

📄 License

MIT License - see LICENSE file

🎓 Learning Resources

• ethers.js Docs
• Avalanche Docs
• Supabase Docs
• React Docs
• Solidity Docs

🎮 Play Now

npm run dev
# Connect wallet → Play game → Earn AVAX + nodepoints!

---

Built with ❤️ using Web3 technologies. Have fun and play responsibly!