dubs-server 1.0.0

package/postman/VOTING_API_GUIDE.md

@@ -0,0 +1,426 @@
+# 🗳️ Dubs API - Democratic Voting Guide
+
+## 📦 **Postman Collection**
+
+**Import:** `Dubs-API-v1-With-Voting.postman_collection.json`
+
+This collection includes **ALL endpoints** for the complete Dubs wager game system with democratic voting!
+
+---
+
+## 🌐 **Base URLs**
+
+### **Devnet (Current)**
+```
+https://dubs-server-dev-55d1fba09a97.herokuapp.com
+```
+
+### **Local Development**
+```
+http://localhost:3001
+```
+
+---
+
+## 📋 **Complete Endpoint List**
+
+### **Health & Info**
+```
+GET  /                  - API overview
+GET  /health            - Health check
+```
+
+### **Production API (`/api/v1/prod/`)**
+
+#### **Game Management:**
+```
+GET  /api/v1/prod/game/:gameId
+     Returns: Game state, players, pot, votes, votingEnabled
+```
+
+#### **Game Creation:**
+```
+POST /api/v1/prod/transaction/build/create
+     Body: {
+       creatorAddress: string,
+       buyIn: number (SOL),
+       maxPlayers: number (2-20),
+       operatorFee: number (0-100),
+       operatorAddress?: string (optional),
+       votingEnabled: boolean  ← NEW!
+     }
+     Returns: Unsigned transaction, gameId, gameAddress
+```
+
+#### **Join Game:**
+```
+POST /api/v1/prod/transaction/build/join
+     Body: {
+       playerAddress: string,
+       gameId: string (UUID)
+     }
+     Returns: Unsigned transaction
+```
+
+#### **Democratic Voting (NEW!):**
+```
+POST /api/v1/prod/transaction/build/cast-vote
+     Body: {
+       voterAddress: string,
+       gameId: string,
+       votedFor: string (player address)
+     }
+     Returns: Unsigned vote transaction
+
+POST /api/v1/prod/transaction/build/distribute-by-vote
+     Body: {
+       creatorAddress: string,
+       gameId: string
+     }
+     Returns: Unsigned transaction, winners[], voteCounts{}
+```
+
+#### **Manual Distribution:**
+```
+POST /api/v1/prod/transaction/build/distribute
+     Body: {
+       creatorAddress: string,
+       gameId: string,
+       winners: string[] (player addresses)
+     }
+     Returns: Unsigned transaction
+```
+
+#### **Transaction Submission:**
+```
+POST /api/v1/prod/transaction/submit
+     Body: {
+       signedTransaction: string (base64)
+     }
+     Returns: Transaction signature, confirmation
+```
+
+### **Demo API (`/api/v1/demo/`)** - Server-Managed Wallets
+```
+GET  /api/v1/demo/game/:gameId
+GET  /api/v1/demo/wallets
+POST /api/v1/demo/game/create
+POST /api/v1/demo/game/join
+POST /api/v1/demo/game/distribute
+POST /api/v1/demo/airdrop
+```
+
+---
+
+## 🎮 **Workflow Examples**
+
+### **Workflow 1: Standard Game (No Voting)**
+
+1. **Build Create Transaction**
+   ```json
+   POST /api/v1/prod/transaction/build/create
+   {
+     "creatorAddress": "YourAddress",
+     "buyIn": 0.5,
+     "maxPlayers": 4,
+     "operatorFee": 10,
+     "votingEnabled": false
+   }
+   ```
+   → Sign with Phantom
+   → Submit via `/transaction/submit`
+
+2. **Players Join**
+   → Each player builds join transaction
+   → Signs and submits
+
+3. **Creator Distributes**
+   ```json
+   POST /api/v1/prod/transaction/build/distribute
+   {
+     "creatorAddress": "YourAddress",
+     "gameId": "saved-game-id",
+     "winners": ["Player1", "Player2"]
+   }
+   ```
+
+---
+
+### **Workflow 2: Democratic Game (With Voting)**
+
+1. **Create Game with Voting**
+   ```json
+   POST /api/v1/prod/transaction/build/create
+   {
+     "creatorAddress": "YourAddress",
+     "buyIn": 0.5,
+     "maxPlayers": 3,
+     "operatorFee": 10,
+     "votingEnabled": true  ← Enable democracy!
+   }
+   ```
+
+2. **Players Join**
+   → Same as above
+
+3. **Players Vote** (NEW!)
+   ```json
+   POST /api/v1/prod/transaction/build/cast-vote
+   {
+     "voterAddress": "Player1Address",
+     "gameId": "saved-game-id",
+     "votedFor": "Player2Address"
+   }
+   ```
+   → Repeat for each player
+   → Need majority (50%+) to distribute
+
+4. **Check Voting Progress**
+   ```json
+   GET /api/v1/prod/game/:gameId
+   
+   Response includes:
+   {
+     "votes": [
+       {"voter": "Player1...", "votedFor": "Player2..."},
+       {"voter": "Player2...", "votedFor": "Player2..."}
+     ],
+     "votingEnabled": true
+   }
+   ```
+
+5. **Distribute by Vote** (When Majority Reached)
+   ```json
+   POST /api/v1/prod/transaction/build/distribute-by-vote
+   {
+     "creatorAddress": "YourAddress",
+     "gameId": "saved-game-id"
+   }
+   
+   Response:
+   {
+     "transaction": "...",
+     "winners": ["Player2Address"],
+     "voteCounts": {
+       "Player1Address": 1,
+       "Player2Address": 2
+     }
+   }
+   ```
+
+---
+
+## 🗳️ **Voting Rules**
+
+### **Majority Calculation:**
+```javascript
+Total Players: 3
+Majority: (3 / 2) + 1 = 2 votes
+
+Total Players: 4
+Majority: (4 / 2) + 1 = 3 votes
+
+Total Players: 2
+Majority: (2 / 2) + 1 = 2 votes (both must vote)
+```
+
+### **Tie Handling:**
+```
+If multiple players tied for most votes:
+→ Prize split equally among tied winners
+
+Example:
+Player A: 2 votes
+Player B: 2 votes
+→ Both win, 50/50 split
+```
+
+### **Vote Changes:**
+```
+✅ Players can change votes before majority
+✅ Latest vote overwrites previous vote
+✅ Votes stored on-chain
+```
+
+---
+
+## 🔧 **Setup Instructions**
+
+### **1. Import Collection**
+```
+1. Open Postman
+2. File → Import
+3. Select: Dubs-API-v1-With-Voting.postman_collection.json
+4. Collection imported!
+```
+
+### **2. Set Variables**
+```
+baseUrl: https://dubs-server-dev-55d1fba09a97.herokuapp.com
+walletAddress: YOUR_SOLANA_WALLET_ADDRESS
+gameId: (auto-saved after creating game)
+```
+
+### **3. Test Flow**
+```
+Production API → Democratic Game Flow → 
+1️⃣ Build Create Game (Voting ON)
+→ Copy transaction
+→ Sign with Phantom
+→ Submit via transaction/submit
+```
+
+---
+
+## 📊 **Response Formats**
+
+### **Game Info (With Voting):**
+```json
+{
+  "exists": true,
+  "game": {
+    "gameId": 12345,
+    "authority": "CreatorAddress...",
+    "buyIn": 0.5,
+    "maxPlayers": 3,
+    "operatorWallet": "OperatorAddress...",
+    "operatorFeePercentage": 10,
+    "players": ["Player1...", "Player2...", "Player3..."],
+    "totalPot": 1.5,
+    "isActive": true,
+    "votes": [
+      {"voter": "Player1...", "votedFor": "Player2..."},
+      {"voter": "Player2...", "votedFor": "Player2..."}
+    ],
+    "votingEnabled": true
+  },
+  "calculated": {
+    "operatorFeeAmount": "0.1500",
+    "prizePool": "1.3500"
+  }
+}
+```
+
+### **Distribute by Vote Response:**
+```json
+{
+  "success": true,
+  "transaction": "BASE64_UNSIGNED_TRANSACTION",
+  "winners": ["Player2Address..."],
+  "voteCounts": {
+    "Player1Address": 1,
+    "Player2Address": 2,
+    "Player3Address": 0
+  },
+  "instructions": "Sign this transaction..."
+}
+```
+
+---
+
+## 🎯 **Testing Tips**
+
+### **For Manual Testing:**
+1. Use Demo API for quick testing
+2. Use Production API for real wallet testing
+3. Save gameId from create response (auto-saved in collection)
+4. Copy player addresses from game info for voting
+
+### **For Voting Tests:**
+1. Create game with `votingEnabled: true`
+2. Get player addresses from game info
+3. Build vote transactions for each player
+4. Check voting progress in game info
+5. When majority reached, distribute by vote
+
+### **For Tie Testing:**
+```
+Create 4-player game
+Have 2 vote for Player A
+Have 2 vote for Player B
+→ Test equal split distribution
+```
+
+---
+
+## 🚨 **Common Errors**
+
+### **Insufficient Lamports:**
+```
+Error: Transfer: insufficient lamports...
+
+Fix: Use smaller buy-in or airdrop more SOL
+```
+
+### **Voting Incomplete:**
+```
+Error: Voting incomplete - need majority
+
+Fix: Need (players/2)+1 votes before distributing
+```
+
+### **Game Not Found:**
+```
+Error: Game does not exist
+
+Fix: Check gameId, might be from old program version
+```
+
+---
+
+## 🌟 **New Features in v1.1**
+
+```
+✅ Democratic voting system
+✅ cast-vote endpoint
+✅ distribute-by-vote endpoint
+✅ Majority rules logic
+✅ Tie handling
+✅ votingEnabled flag in game creation
+✅ votes array in game state
+✅ Vote count tallying
+```
+
+---
+
+## 📖 **Full Documentation**
+
+- **API Docs:** See `../README.md`
+- **Smart Contract:** See `../../dubs/programs/hello_world/src/lib.rs`
+- **Mobile Integration:** See Jelli Wallet SDK docs
+
+---
+
+## 🎊 **Collection Organization**
+
+```
+├── Health Check
+├── Production API (Real Wallets)
+│   ├── 1. Game Management
+│   ├── 2. Game Creation
+│   ├── 3. Join Game
+│   ├── 4. Democratic Voting (NEW!)
+│   ├── 5. Manual Distribution
+│   └── 6. Transaction Submission
+├── Demo/Test API (Server-Managed)
+├── Complete Workflows
+│   ├── 🎮 Standard Game Flow
+│   └── 🗳️ Democratic Game Flow (NEW!)
+└── Examples & Documentation
+```
+
+---
+
+## 🚀 **Quick Start**
+
+1. Import collection
+2. Set `baseUrl` to devnet URL
+3. Run "Complete Workflows" → "Democratic Game Flow"
+4. Watch democracy in action! 🗳️
+
+---
+
+**Happy Testing! 🎮**
+
+*Built with ❤️ on Solana with democratic principles* 🗳️⛓️
+

package/refactor/Animations.md

@@ -0,0 +1,148 @@
+# Animation System Refactor
+
+## Overview
+Optimizing the Dubs animation system for mobile performance and better UX.
+
+**Date**: 2025-02-01
+**Status**: In Progress
+
+---
+
+## Current Architecture
+
+### Files
+| File | Lines | Purpose |
+|------|-------|---------|
+| `AnimationOverlay.tsx` | 150 | Master controller |
+| `MakeItRainAnimation.tsx` | 104 | Falling Solana logos |
+| `MuhahaAnimation.tsx` | 116 | Evil laugh + particles |
+| `GameTimeAnimation.tsx` | 298 | Countdown + team badges |
+| `PaymentReceivedAnimation.tsx` | 291 | Payment celebrations |
+| `PaymentAnimationOverlay.tsx` | 101 | Payment event listener |
+
+**Location**: `app/v2/components/animations/`
+
+### Available Animations
+| Animation | Hashtag | Duration | Particle Count |
+|-----------|---------|----------|----------------|
+| makeitrain | #makeitrain | 5s | 30-50 |
+| muhaha | #muhaha | 4s | 30 |
+| explosion | #boom | 3s | 1 |
+| confetti | #party | 4s | 100 |
+| fire | #fire | 4s | 30 |
+| gametime | #gametime | 6s | 70 |
+
+### Trigger Flow
+```
+User sends message with #animation
+    ↓
+ChatSocket → Backend broadcasts animation:trigger
+    ↓
+ChatContext dispatches window event
+    ↓
+AnimationOverlay renders component
+    ↓
+Auto-closes after duration
+```
+
+---
+
+## Issues Identified
+
+### 1. Mobile Performance
+- **Too many particles**: 30-100 elements animating simultaneously
+- **Fixed particle counts**: Same on iPhone SE as on desktop
+- **No device detection**: Same animations for all devices
+- **Long durations**: 5-6s feels slow on mobile
+
+### 2. Mobile Responsiveness
+- **Text overflow**: "GAME TIME!" at 8rem overflows small screens
+- **Fixed positioning**: Particles use `Math.random() * 100%` regardless of viewport
+- **No orientation handling**: Landscape vs portrait not considered
+
+### 3. Accessibility
+- **No `prefers-reduced-motion`**: Motion-sensitive users can't disable
+- **No skip button**: Users must wait for animation to complete
+- **High contrast issues**: Some animations may be hard to see
+
+### 4. Performance Overhead
+- **Math.random() on render**: Creates new values each render
+- **No memoization**: Particle arrays regenerated
+- **setTimeout chains**: Less predictable than requestAnimationFrame
+
+---
+
+## Optimization Plan
+
+### Phase 1: Mobile Particle Reduction
+- [ ] Detect mobile devices
+- [ ] Reduce particle counts by 50% on mobile
+- [ ] Shorter durations on mobile (5s → 3s)
+
+### Phase 2: Accessibility
+- [ ] Add `prefers-reduced-motion` support
+- [ ] Simpler/static animation for reduced motion users
+- [ ] Optional skip button
+
+### Phase 3: Performance
+- [ ] Memoize particle arrays with useMemo
+- [ ] Use CSS `contain: strict` for paint isolation
+- [ ] Add `will-change` hints
+
+### Phase 4: Mobile UX
+- [ ] Viewport-aware particle positioning
+- [ ] Responsive text sizes that don't overflow
+- [ ] Touch-to-dismiss option
+
+---
+
+## Implementation Progress
+
+### 2025-02-01: Mobile Optimization
+
+**Created**: `app/v2/utils/animationConfig.ts`
+- Device detection utilities (`isMobileDevice`, `prefersReducedMotion`)
+- Centralized particle counts for desktop/mobile
+- Helper functions for optimized values
+
+**Optimized**: `MakeItRainAnimation.tsx`
+- Desktop: 35 particles → Mobile: 15 particles
+- Desktop: 5s duration → Mobile: 3s duration
+- Added `prefers-reduced-motion` support
+- Responsive text sizing
+
+**Optimized**: `PaymentReceivedAnimation.tsx`
+- Coins: 40 → 15 on mobile
+- Dollar signs: 20 → 8 on mobile
+- Sparkles: 30 → 10 on mobile
+- **Total: 90 elements → 33 elements (63% reduction)**
+- Pre-generated particles (no Math.random() in render)
+- Added `prefers-reduced-motion` support
+
+**Optimized**: `MuhahaAnimation.tsx`
+- Smoke particles: 20 → 8 on mobile
+- Emojis: 10 → 5 on mobile
+- Pre-generated particles
+- Responsive text sizing
+
+---
+
+## Files Modified
+
+| File | Changes |
+|------|---------|
+| `app/v2/utils/animationConfig.ts` | NEW - Device detection & config |
+| `MakeItRainAnimation.tsx` | Mobile particle reduction, responsive text |
+| `PaymentReceivedAnimation.tsx` | 63% particle reduction on mobile |
+| `MuhahaAnimation.tsx` | Mobile particle reduction, responsive text |
+
+---
+
+## Testing Checklist
+
+- [ ] iPhone SE (small screen)
+- [ ] iPhone Pro Max (large screen)
+- [ ] Android mid-range device
+- [ ] Desktop Chrome
+- [ ] Reduced motion preference enabled
+- [ ] Low-end device performance