dubs-server 1.0.0

package/documentation/WEBSOCKET_ARCHITECTURE.md

@@ -0,0 +1,881 @@
+# ⚡ Real-Time WebSocket Architecture
+
+**Goal:** Instant updates across all connected users  
+**Use Case:** Player joins in Japan → Users in USA see it within 100ms  
+**Status:** Design Complete, Ready to Implement
+
+---
+
+## 🎯 Why WebSockets are CRITICAL
+
+### **Polling (Current) - NOT GOOD ENOUGH:**
+
+```
+User A joins → Transaction confirms → 0-2 second delay → User B sees it
+```
+
+**Problems:**
+- Feels sluggish
+- Not truly "live"
+- Wastes API calls
+- Battery drain on mobile
+
+### **WebSockets - SMOOTH:**
+
+```
+User A joins → Transaction confirms → <100ms → User B sees it instantly
+```
+
+**Benefits:**
+- ✅ Feels instant and live
+- ✅ True multiplayer experience
+- ✅ Lower server load
+- ✅ Battery friendly
+- ✅ Can push keeper events in real-time
+
+---
+
+## 🏗️ Architecture Design
+
+### **Components:**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    WEBSOCKET FLOW                            │
+└─────────────────────────────────────────────────────────────┘
+
+1. KEEPER BOT (Server)
+   ├─ Processes round (lock/reveal/resolve)
+   ├─ Emits events to WebSocket server
+   └─ "player_joined", "round_locked", "winner_selected"
+
+2. WEBSOCKET SERVER (dubs-server)
+   ├─ Maintains connections to all users
+   ├─ Receives events from keeper
+   ├─ Broadcasts to all connected clients
+   └─ Handles rooms (one per round)
+
+3. CAROUSEL (Frontend)
+   ├─ Connects to WebSocket
+   ├─ Listens for events
+   ├─ Updates UI instantly
+   └─ Falls back to polling if disconnected
+```
+
+---
+
+## 🔌 Implementation Plan
+
+### **Step 1: Add Socket.io to Server (30 min)**
+
+**Install:**
+```bash
+cd dubs-server
+npm install socket.io
+```
+
+**Update `server.js`:**
+```javascript
+const express = require('express');
+const http = require('http');
+const { Server } = require('socket.io');
+
+const app = express();
+const server = http.createServer(app);
+
+// Socket.io with CORS
+const io = new Server(server, {
+  cors: {
+    origin: [
+      'http://localhost:3000',
+      'https://your-netlify-app.netlify.app'
+    ],
+    methods: ['GET', 'POST']
+  }
+});
+
+// WebSocket connection handler
+io.on('connection', (socket) => {
+  console.log('🔌 Client connected:', socket.id);
+  
+  // Join current round room
+  socket.on('join_round', (roundId) => {
+    socket.join(`round_${roundId}`);
+    console.log(`👥 Client ${socket.id} joined round ${roundId}`);
+    
+    // Send current state immediately
+    getCurrentRoundState(roundId).then(state => {
+      socket.emit('round_state', state);
+    });
+  });
+  
+  socket.on('disconnect', () => {
+    console.log('🔌 Client disconnected:', socket.id);
+  });
+});
+
+// Change app.listen to server.listen
+server.listen(PORT, () => {
+  console.log(`🚀 Server running on port ${PORT}`);
+  console.log(`⚡ WebSocket ready`);
+});
+
+// Make io available globally for emitting from keeper
+global.io = io;
+```
+
+---
+
+### **Step 2: Emit Events from Keeper (15 min)**
+
+**Update `jackpot-keeper.js`:**
+
+```javascript
+class JackpotKeeper {
+  constructor() {
+    // ... existing code ...
+    this.io = null; // Will be set via setter
+  }
+  
+  setSocketServer(io) {
+    this.io = io;
+  }
+  
+  async lockRound(roundId) {
+    // ... existing lock logic ...
+    
+    // Emit event
+    if (this.io) {
+      this.io.to(`round_${roundId}`).emit('round_locked', {
+        roundId,
+        timestamp: Date.now()
+      });
+    }
+    
+    return true;
+  }
+  
+  async resolveRound(roundId) {
+    // ... existing resolve logic ...
+    
+    const winner = data.winner;
+    const winAmount = Number(totalPot) * 0.95;
+    
+    // Emit winner event
+    if (this.io) {
+      this.io.to(`round_${roundId}`).emit('winner_selected', {
+        roundId,
+        winner,
+        winAmount,
+        timestamp: Date.now()
+      });
+    }
+    
+    return true;
+  }
+  
+  async openOrResetRound(previousRoundId) {
+    // ... existing reset logic ...
+    
+    const newRoundId = data.roundId;
+    
+    // Emit new round event
+    if (this.io) {
+      // Broadcast to all clients
+      this.io.emit('round_opened', {
+        roundId: newRoundId,
+        timestamp: Date.now()
+      });
+    }
+    
+    return true;
+  }
+}
+
+// Export keeper instance
+module.exports = JackpotKeeper;
+```
+
+**In keeper startup script:**
+```javascript
+// server.js or separate keeper init
+const keeper = new JackpotKeeper();
+keeper.setSocketServer(io);
+keeper.run();
+```
+
+---
+
+### **Step 3: Listen for New Players (Real-Time)**
+
+**Add endpoint to emit when player joins:**
+
+**Update `jackpotRoutes.js`:**
+```javascript
+router.post('/enter', async (req, res) => {
+  try {
+    // ... existing enter logic ...
+    
+    const result = await jackpotService.enterRound(...);
+    
+    // Emit to all users in this round
+    if (global.io) {
+      global.io.to(`round_${roundId}`).emit('player_joined', {
+        roundId,
+        player: playerAddress,
+        weight: amount,
+        entryCount: newEntryCount,
+        totalPot: newTotalPot,
+        timestamp: Date.now()
+      });
+    }
+    
+    res.json(result);
+  } catch (error) {
+    // ... error handling ...
+  }
+});
+```
+
+---
+
+### **Step 4: Frontend WebSocket Integration (30 min)**
+
+**Install:**
+```bash
+cd dubs-jackpot
+npm install socket.io-client
+```
+
+**Create WebSocket Hook:**
+
+File: `dubs-jackpot/app/hooks/useJackpotSocket.ts`
+
+```typescript
+import { useEffect, useState, useCallback } from 'react';
+import { io, Socket } from 'socket.io-client';
+
+const API_BASE = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3001';
+
+export function useJackpotSocket(roundId: string | null) {
+  const [socket, setSocket] = useState<Socket | null>(null);
+  const [connected, setConnected] = useState(false);
+  const [players, setPlayers] = useState<any[]>([]);
+  const [roundState, setRoundState] = useState<any>(null);
+  
+  // Connect to WebSocket
+  useEffect(() => {
+    const newSocket = io(API_BASE, {
+      transports: ['websocket', 'polling'],
+      reconnection: true,
+      reconnectionDelay: 1000,
+      reconnectionAttempts: 5
+    });
+    
+    newSocket.on('connect', () => {
+      console.log('⚡ WebSocket connected');
+      setConnected(true);
+      
+      // Join current round room
+      if (roundId) {
+        newSocket.emit('join_round', roundId);
+      }
+    });
+    
+    newSocket.on('disconnect', () => {
+      console.log('🔌 WebSocket disconnected');
+      setConnected(false);
+    });
+    
+    setSocket(newSocket);
+    
+    return () => {
+      newSocket.close();
+    };
+  }, []);
+  
+  // Join round room when roundId changes
+  useEffect(() => {
+    if (socket && roundId) {
+      socket.emit('join_round', roundId);
+    }
+  }, [socket, roundId]);
+  
+  // Listen for player joined
+  useEffect(() => {
+    if (!socket) return;
+    
+    const handlePlayerJoined = (data: any) => {
+      console.log('👤 Player joined:', data);
+      
+      // Add new player to carousel
+      setPlayers(prev => {
+        // Check if already exists
+        if (prev.find(p => p.address === data.player)) {
+          return prev;
+        }
+        
+        // Add new player
+        return [...prev, {
+          address: data.player,
+          wager: data.weight / 1e9,
+          emoji: hashToEmoji(data.player),
+          username: data.player.slice(0, 4) + '...',
+          timestamp: data.timestamp
+        }];
+      });
+    };
+    
+    socket.on('player_joined', handlePlayerJoined);
+    
+    return () => {
+      socket.off('player_joined', handlePlayerJoined);
+    };
+  }, [socket]);
+  
+  // Listen for round locked
+  useEffect(() => {
+    if (!socket) return;
+    
+    const handleRoundLocked = (data: any) => {
+      console.log('🔒 Round locked:', data);
+      setRoundState({ status: 'locked', roundId: data.roundId });
+    };
+    
+    socket.on('round_locked', handleRoundLocked);
+    
+    return () => {
+      socket.off('round_locked', handleRoundLocked);
+    };
+  }, [socket]);
+  
+  // Listen for winner selected
+  useEffect(() => {
+    if (!socket) return;
+    
+    const handleWinnerSelected = (data: any) => {
+      console.log('🏆 Winner selected:', data);
+      
+      setRoundState({ 
+        status: 'resolved', 
+        winner: data.winner,
+        winAmount: data.winAmount,
+        roundId: data.roundId
+      });
+    };
+    
+    socket.on('winner_selected', handleWinnerSelected);
+    
+    return () => {
+      socket.off('winner_selected', handleWinnerSelected);
+    };
+  }, [socket]);
+  
+  // Listen for new round
+  useEffect(() => {
+    if (!socket) return;
+    
+    const handleRoundOpened = (data: any) => {
+      console.log('🎰 New round opened:', data);
+      
+      setPlayers([]); // Clear players
+      setRoundState({ 
+        status: 'open', 
+        roundId: data.roundId
+      });
+    };
+    
+    socket.on('round_opened', handleRoundOpened);
+    
+    return () => {
+      socket.off('round_opened', handleRoundOpened);
+    };
+  }, [socket]);
+  
+  return {
+    connected,
+    players,
+    roundState,
+    socket
+  };
+}
+
+// Helper
+function hashToEmoji(address: string): string {
+  const EMOJIS = ['🔥', '⚡', '🌊', '🌿', '🎮', '⭐', '💎', '🎯', '🚀', '🌟'];
+  const hash = address.split('').reduce((acc, c) => acc + c.charCodeAt(0), 0);
+  return EMOJIS[hash % EMOJIS.length];
+}
+```
+
+---
+
+### **Step 5: Use in Carousel (10 min)**
+
+**Update `JackpotCarousel.tsx`:**
+
+```typescript
+export default function JackpotCarousel() {
+  const [currentRound, setCurrentRound] = useState<any>(null);
+  
+  // Get current round ID
+  useEffect(() => {
+    fetch(`${API_BASE}/jackpot/round/current`)
+      .then(r => r.json())
+      .then(data => setCurrentRound(data.round));
+  }, []);
+  
+  // Use WebSocket hook
+  const { connected, players, roundState } = useJackpotSocket(
+    currentRound?.roundId
+  );
+  
+  // Trigger winner animation when winner selected
+  useEffect(() => {
+    if (roundState?.status === 'resolved' && roundState.winner) {
+      const winnerPlayer = players.find(p => p.address === roundState.winner);
+      
+      if (winnerPlayer) {
+        // Trigger carousel animation
+        triggerWinnerAnimation(winnerPlayer, roundState.winAmount);
+      }
+    }
+  }, [roundState]);
+  
+  return (
+    <div>
+      {/* Connection indicator */}
+      <div className="connection-status">
+        {connected ? '🟢 Live' : '🔴 Reconnecting...'}
+      </div>
+      
+      <InfiniteCarousel
+        players={players}
+        roundState={roundState}
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## ⚡ Event Types
+
+### **Server → Client Events:**
+
+1. **`player_joined`**
+   ```json
+   {
+     "roundId": "556",
+     "player": "Abc...xyz",
+     "weight": "50000000",
+     "entryCount": 5,
+     "totalPot": "250000000",
+     "timestamp": 1700000000
+   }
+   ```
+   **UI Action:** Add card to carousel (RIGHT-TO-LEFT animation)
+
+2. **`round_locked`**
+   ```json
+   {
+     "roundId": "556",
+     "timestamp": 1700000000
+   }
+   ```
+   **UI Action:** Show "Picking winner...", speed up carousel
+
+3. **`winner_selected`**
+   ```json
+   {
+     "roundId": "556",
+     "winner": "Abc...xyz",
+     "winAmount": "237500000",
+     "timestamp": 1700000000
+   }
+   ```
+   **UI Action:** Scroll to winner, show badge
+
+4. **`round_opened`**
+   ```json
+   {
+     "roundId": "557",
+     "timestamp": 1700000000
+   }
+   ```
+   **UI Action:** Reset carousel, clear players
+
+5. **`timer_update`** (every 5 seconds)
+   ```json
+   {
+     "roundId": "556",
+     "timeRemaining": 45,
+     "status": "open"
+   }
+   ```
+   **UI Action:** Update countdown
+
+---
+
+## 🎯 Implementation Strategy
+
+### **Hybrid Approach (Best of Both Worlds):**
+
+**WebSockets for:**
+- ✅ Player joins (instant!)
+- ✅ Round state changes (locked, resolved)
+- ✅ Winner announcements
+- ✅ New round notifications
+
+**Polling for:**
+- ✅ Initial load (fetch current state)
+- ✅ Fallback if WebSocket fails
+- ✅ Every 10s to verify sync (catch missed events)
+
+**Code:**
+```typescript
+export function useJackpotData(roundId: string) {
+  const socket = useJackpotSocket(roundId);
+  const [players, setPlayers] = useState([]);
+  
+  // WebSocket updates (instant)
+  useEffect(() => {
+    if (socket.players.length > 0) {
+      setPlayers(socket.players);
+    }
+  }, [socket.players]);
+  
+  // Polling fallback (every 10s to verify)
+  useEffect(() => {
+    const verify = async () => {
+      if (!socket.connected) {
+        // WebSocket down, use polling
+        const data = await fetchEntries(roundId);
+        setPlayers(data);
+      } else {
+        // WebSocket working, just verify sync
+        const data = await fetchEntries(roundId);
+        if (data.length !== players.length) {
+          console.warn('⚠️ Socket/API mismatch, resync');
+          setPlayers(data);
+        }
+      }
+    };
+    
+    const interval = setInterval(verify, 10000);
+    return () => clearInterval(interval);
+  }, [roundId, socket.connected, players.length]);
+  
+  return {
+    players,
+    connected: socket.connected,
+    roundState: socket.roundState
+  };
+}
+```
+
+---
+
+## 🔧 Server-Side Event Emission
+
+### **Where to Emit:**
+
+**1. When player enters (API endpoint):**
+```javascript
+// routes/jackpotRoutes.js
+router.post('/enter', async (req, res) => {
+  // ... process entry ...
+  
+  // Emit to all users watching this round
+  global.io.to(`round_${roundId}`).emit('player_joined', {
+    roundId,
+    player: playerAddress,
+    weight: amount,
+    entryCount: round.entryCount,
+    totalPot: round.totalPotLamports
+  });
+});
+```
+
+**2. In keeper bot:**
+```javascript
+// scripts/jackpot-keeper.js
+
+async lockRound(roundId) {
+  // ... lock logic ...
+  
+  // Broadcast to all users
+  this.io.to(`round_${roundId}`).emit('round_locked', { roundId });
+  this.io.emit('global_event', { type: 'round_locked', roundId });
+}
+
+async resolveRound(roundId) {
+  // ... resolve logic ...
+  
+  // Broadcast winner
+  this.io.to(`round_${roundId}`).emit('winner_selected', {
+    roundId,
+    winner,
+    winAmount
+  });
+}
+```
+
+**3. Timer updates (optional, every 5s):**
+```javascript
+setInterval(() => {
+  getCurrentRound().then(round => {
+    if (round) {
+      io.to(`round_${round.roundId}`).emit('timer_update', {
+        roundId: round.roundId,
+        timeRemaining: round.timeRemainingSlots * 0.4,
+        totalPot: round.totalPotLamports,
+        entryCount: round.entryCount
+      });
+    }
+  });
+}, 5000);
+```
+
+---
+
+## 🎨 Carousel Integration
+
+### **Updated InfiniteCarousel:**
+
+```typescript
+export default function InfiniteCarousel({ 
+  roundId 
+}: { roundId: string | null }) {
+  const INITIAL_SLOTS = 7;
+  const [players, setPlayers] = useState<(Player | null)[]>(Array(INITIAL_SLOTS).fill(null));
+  
+  // WebSocket hook
+  const { connected, players: realPlayers, roundState } = useJackpotSocket(roundId);
+  
+  // Sync real players to carousel
+  useEffect(() => {
+    if (realPlayers.length > 0) {
+      // Map to carousel format
+      const carouselPlayers = realPlayers.map(p => ({
+        id: p.address,
+        username: p.username,
+        emoji: p.emoji,
+        wager: p.wager,
+        address: p.address
+      }));
+      
+      // Fill slots right-to-left
+      const slots = Array(Math.max(INITIAL_SLOTS, carouselPlayers.length)).fill(null);
+      carouselPlayers.forEach((player, i) => {
+        slots[slots.length - 1 - i] = player; // Right-to-left
+      });
+      
+      setPlayers(slots);
+    }
+  }, [realPlayers]);
+  
+  // React to round state changes
+  useEffect(() => {
+    if (roundState?.status === 'locked') {
+      // Speed up carousel, show "Picking winner..."
+      setIsPickingWinner(true);
+    }
+    
+    if (roundState?.status === 'resolved' && roundState.winner) {
+      // Trigger winner animation
+      const winnerPlayer = players.find(p => p?.address === roundState.winner);
+      if (winnerPlayer) {
+        handlePickWinner(winnerPlayer);
+      }
+    }
+    
+    if (roundState?.status === 'open' && roundState.roundId !== currentRound) {
+      // New round started
+      handleReset();
+    }
+  }, [roundState]);
+  
+  return (
+    <>
+      {/* Connection indicator */}
+      <div className={`status ${connected ? 'connected' : 'disconnected'}`}>
+        {connected ? '⚡ LIVE' : '🔄 Reconnecting...'}
+      </div>
+      
+      {/* Carousel */}
+      {/* ... rest of carousel UI ... */}
+    </>
+  );
+}
+```
+
+---
+
+## 🚀 Performance Optimization
+
+### **1. Debounce Rapid Events:**
+
+```typescript
+// If 5 players join in 1 second, batch them
+const [playerQueue, setPlayerQueue] = useState([]);
+
+useEffect(() => {
+  socket.on('player_joined', (player) => {
+    setPlayerQueue(prev => [...prev, player]);
+  });
+}, [socket]);
+
+useEffect(() => {
+  if (playerQueue.length > 0) {
+    const timeout = setTimeout(() => {
+      // Add all queued players at once
+      setPlayers(prev => [...prev, ...playerQueue]);
+      setPlayerQueue([]);
+    }, 300); // 300ms debounce
+    
+    return () => clearTimeout(timeout);
+  }
+}, [playerQueue]);
+```
+
+### **2. Efficient Re-renders:**
+
+```typescript
+// Memoize players to prevent unnecessary renders
+const memoizedPlayers = useMemo(() => players, [players.length, players[0]?.id]);
+
+// Only re-render carousel when players actually change
+```
+
+### **3. Background Sync:**
+
+```typescript
+// Verify socket data matches blockchain every 30s
+useEffect(() => {
+  const verify = async () => {
+    const canonical = await fetchEntries(roundId);
+    if (canonical.length !== players.length) {
+      console.warn('Resync needed');
+      setPlayers(canonical);
+    }
+  };
+  
+  const interval = setInterval(verify, 30000);
+  return () => clearInterval(interval);
+}, [roundId]);
+```
+
+---
+
+## 🎯 Why This Will Be SMOOTH
+
+**Player joins in Tokyo:**
+```
+1. Transaction confirms (2-3s)
+2. Backend emits player_joined (instant)
+3. WebSocket pushes to all clients (<100ms)
+4. Carousel in NYC adds card (instant)
+```
+
+**Total delay: <100ms after blockchain confirmation!**
+
+**vs Polling:**
+```
+1. Transaction confirms (2-3s)
+2. User in NYC polls API (0-2s wait)
+3. Carousel updates
+```
+
+**Total delay: 0-2 seconds** 😢
+
+---
+
+## 📋 Implementation Checklist
+
+**Backend:**
+- [ ] Install socket.io
+- [ ] Add WebSocket server to server.js
+- [ ] Emit events from keeper
+- [ ] Emit events from API endpoints
+- [ ] Test events with socket.io-client
+
+**Frontend:**
+- [ ] Install socket.io-client
+- [ ] Create useJackpotSocket hook
+- [ ] Integrate with carousel
+- [ ] Add connection indicator
+- [ ] Add fallback polling
+- [ ] Test real-time updates
+
+**Testing:**
+- [ ] 2 users, different browsers
+- [ ] User A joins → User B sees instantly
+- [ ] Winner selected → Both see animation
+- [ ] Network disconnect → Falls back to polling
+- [ ] Reconnect → Resync automatically
+
+---
+
+## 🎯 Estimated Timeline
+
+**Day 1 - Backend WebSocket (3 hours):**
+- Hour 1: Add Socket.io to server
+- Hour 2: Emit events from keeper
+- Hour 3: Test with socket.io-client CLI
+
+**Day 2 - Frontend Integration (4 hours):**
+- Hour 1: Create useJackpotSocket hook
+- Hour 2: Integrate with carousel
+- Hour 3: Add fallback & error handling
+- Hour 4: Test with real rounds
+
+**Day 3 - Polish & Deploy (2 hours):**
+- Hour 1: Connection indicators, loading states
+- Hour 2: Deploy & monitor
+
+**Total: ~9 hours** for real-time multiplayer jackpot! 🚀
+
+---
+
+## 💎 The Result
+
+**Users will see:**
+
+```
+[You join from USA]
+→ Card appears instantly on your screen
+→ Card appears instantly on Tokyo user's screen (<100ms)
+
+[Tokyo user joins]
+→ Card whooshes in from right on your screen (<100ms)
+→ Feels ALIVE and multiplayer
+
+[Round locks]
+→ Everyone sees carousel speed up (synchronized)
+
+[Winner selected]
+→ Everyone sees same smooth scroll-to-winner
+→ Same winner badge animation
+→ True shared experience
+```
+
+**This is what makes it feel like a REAL multiplayer game!** 🎮
+
+---
+
+## 🎯 My Recommendation
+
+**YES, absolutely use WebSockets!**
+
+**Why:**
+1. ✅ Minimal extra effort (~3 hours backend, ~4 hours frontend)
+2. ✅ Massive UX improvement (feels alive!)
+3. ✅ Required for true multiplayer feel
+4. ✅ Socket.io handles all edge cases (reconnection, fallback)
+5. ✅ Can scale to 100s of concurrent users
+
+**With your smooth carousel + real-time WebSockets = Magic!** ✨
+
+Want me to start implementing the WebSocket system? I can have the backend ready in ~1 hour!