dubs-server 1.0.0

package/documentation/PNL_TRACKING_SETUP.md

@@ -0,0 +1,189 @@
+# 📊 PNL Tracking Setup Guide
+
+Complete setup for player PNL tracking with epic winner announcements!
+
+## 🚀 Quick Setup (One Command)
+
+Run this on your Heroku app to set up EVERYTHING:
+
+```bash
+heroku run node scripts/setup-pnl-tracking.js --app YOUR_APP_NAME
+```
+
+This will:
+- ✅ Add winner announcement columns to `chat_messages`
+- ✅ Create `player_stats` table
+- ✅ Create `player_history` table for charts
+- ✅ Create all necessary indexes
+
+## 📦 What Gets Created
+
+### 1. Chat Messages (Winner Announcements)
+```sql
+ALTER TABLE chat_messages ADD:
+- is_winner_announcement BOOLEAN
+- win_amount NUMERIC(20, 9)
+- round_id INTEGER
+```
+
+### 2. Player Stats Table
+```sql
+CREATE TABLE player_stats (
+  wallet_address VARCHAR(100) PRIMARY KEY,
+  total_wagered NUMERIC(20, 9),
+  total_won NUMERIC(20, 9),
+  net_pnl NUMERIC(20, 9),
+  rounds_played INTEGER,
+  rounds_won INTEGER,
+  biggest_win NUMERIC(20, 9),
+  biggest_win_round INTEGER,
+  last_played TIMESTAMP,
+  created_at TIMESTAMP
+);
+```
+
+### 3. Player History Table (For Charts)
+```sql
+CREATE TABLE player_history (
+  id SERIAL PRIMARY KEY,
+  wallet_address VARCHAR(100),
+  round_id INTEGER,
+  action VARCHAR(20),  -- 'entry' or 'win'
+  amount NUMERIC(20, 9),
+  cumulative_pnl NUMERIC(20, 9),
+  timestamp TIMESTAMP
+);
+```
+
+## 🔌 API Endpoints
+
+### Get Player Stats
+```http
+GET /stats/player/:walletAddress
+```
+
+Response:
+```json
+{
+  "success": true,
+  "stats": {
+    "walletAddress": "...",
+    "totalWagered": 12.5,
+    "totalWon": 15.3,
+    "netPNL": 2.8,
+    "roundsPlayed": 10,
+    "roundsWon": 2,
+    "winRate": "20.00",
+    "biggestWin": 8.5,
+    "biggestWinRound": 42
+  }
+}
+```
+
+### Get Player History (Chart Data)
+```http
+GET /stats/player/:walletAddress/history?limit=100
+```
+
+### Get Leaderboard
+```http
+GET /stats/leaderboard?limit=10
+```
+
+## 🎯 Automatic Tracking
+
+### Player Entries
+When a player bets, the frontend automatically calls:
+```javascript
+POST /api/keeper-webhook/player-entry
+{
+  walletAddress,
+  roundId,
+  amount  // in lamports
+}
+```
+
+### Player Wins
+When a winner is selected, the keeper automatically calls:
+```javascript
+POST /api/keeper-webhook/winner-selected
+{
+  roundId,
+  winner,
+  winAmount,  // in lamports
+  totalPot,
+  entryCount
+}
+```
+
+This will:
+1. 📊 Track the win in player_stats
+2. 🏆 Post epic winner announcement to chat
+3. 📢 Broadcast to all WebSocket clients
+
+## 🎨 Frontend Features
+
+### PNL Modal
+Click any player name to see:
+- Total wagered
+- Total won
+- Net PNL (profit/loss)
+- Win rate
+- Rounds played/won
+- Biggest win
+- **Animated chart** showing cumulative PNL over time
+
+### Epic Winner Announcements
+When someone wins, the chat shows:
+- 🔥 Laser beams sweeping across
+- 💥 Explosive particles
+- 🏆 Bouncing trophy
+- 🌈 Rainbow gradient text
+- ✨ Floating emojis
+- All with Tron-style effects!
+
+## 🧪 Testing
+
+### 1. Check Database
+```bash
+heroku pg:psql --app YOUR_APP_NAME -c "SELECT * FROM player_stats LIMIT 5;"
+```
+
+### 2. Test API
+```bash
+curl https://your-app.herokuapp.com/stats/player/WALLET_ADDRESS
+```
+
+### 3. Check Logs
+```bash
+heroku logs --tail --app YOUR_APP_NAME
+```
+
+Look for:
+- `📊 Entry recorded`
+- `🏆 Win recorded`
+- `🔥 EPIC WINNER ANNOUNCEMENT posted to chat!`
+
+## 🔄 After Setup
+
+1. **Restart the server:**
+   ```bash
+   heroku restart --app YOUR_APP_NAME
+   ```
+
+2. **Play a round** - Stats will start tracking automatically!
+
+3. **Click on any player name** in chat or roster to see their PNL modal
+
+## 🎉 Done!
+
+Your app now has:
+- ✅ Full PNL tracking
+- ✅ Beautiful animated charts
+- ✅ Epic winner announcements with lasers
+- ✅ Clickable player stats
+- ✅ Leaderboards
+- ✅ Pixelify Sans font everywhere! 🎮
+
+EVERYTHING is wired up and ready to go! 🚀
+

package/documentation/PREVENTING_LOCKUP_ERRORS.md

@@ -0,0 +1,472 @@
+# 🛡️ Preventing Jackpot Lockup Errors
+
+**Lessons learned from Round 50 lockup incident**
+
+## What Went Wrong
+
+### Primary Issues
+1. **Winner calculation bug**: Hardcoded `entries[0].player` instead of calculating from VRF
+2. **Wrong offset**: VRF result read from offset 87 instead of actual offset 51
+3. **No automated tests**: Bugs weren't caught before production
+4. **Keeper bot not running**: Manual intervention required
+5. **No monitoring**: Issue wasn't detected automatically
+
+## Prevention Strategy
+
+### 1. Automated Testing
+
+#### Unit Tests for Winner Calculation
+```javascript
+// tests/winner-calculation.test.js
+const { calculateWinner } = require('../services/winnerCalculator');
+
+describe('Winner Calculation', () => {
+  it('should calculate winner based on VRF result and cumulative weights', () => {
+    const entries = [
+      { player: 'A', weight: 10, cumulativeTo: 10 },
+      { player: 'B', weight: 20, cumulativeTo: 30 },
+      { player: 'C', weight: 20, cumulativeTo: 50 },
+    ];
+    const vrfResult = 25n;
+    const totalWeight = 50n;
+    
+    const winner = calculateWinner(vrfResult, totalWeight, entries);
+    expect(winner).toBe('B'); // 25 falls in B's range (10-30)
+  });
+  
+  it('should handle edge case at boundary', () => {
+    const entries = [
+      { player: 'A', weight: 10, cumulativeTo: 10 },
+      { player: 'B', weight: 20, cumulativeTo: 30 },
+    ];
+    const vrfResult = 10n;
+    const totalWeight = 30n;
+    
+    const winner = calculateWinner(vrfResult, totalWeight, entries);
+    expect(winner).toBe('B'); // 10 is NOT less than 10, check next
+  });
+});
+```
+
+#### Integration Tests with Live Program
+```javascript
+// tests/jackpot-integration.test.js
+describe('Jackpot Integration Tests', () => {
+  it('should complete full round lifecycle', async () => {
+    // 1. Open round
+    // 2. Add entries
+    // 3. Lock round
+    // 4. Reveal randomness
+    // 5. Resolve round
+    // 6. Verify winner matches calculation
+    // 7. Verify payout amounts
+  });
+  
+  it('should match on-chain and off-chain winner calculation', async () => {
+    // Read VRF result from chain
+    // Calculate winner off-chain
+    // Attempt resolve with calculated winner
+    // Should succeed
+  });
+});
+```
+
+#### Account Layout Tests
+```javascript
+// tests/account-layout.test.js
+describe('Round Account Layout', () => {
+  it('should read all fields at correct offsets', async () => {
+    const roundAccount = await getRoundAccount();
+    
+    expect(readU64(roundAccount, 8)).toBe(expectedRoundId);
+    expect(readU8(roundAccount, 16)).toBe(expectedStatus);
+    expect(readU64(roundAccount, 33)).toBe(expectedPot);
+    expect(readU64(roundAccount, 41)).toBe(expectedWeight);
+    expect(readOptionU128(roundAccount, 51)).toBe(expectedVrfResult);
+    expect(readU32(roundAccount, 104)).toBe(expectedEntryCount);
+    // etc...
+  });
+});
+```
+
+### 2. Account Layout Documentation
+
+Create a reference file with EXACT offsets:
+
+```javascript
+// constants/accountLayouts.js
+const ROUND_ACCOUNT_LAYOUT = {
+  discriminator: { offset: 0, size: 8, type: '[u8; 8]' },
+  roundId: { offset: 8, size: 8, type: 'u64' },
+  status: { offset: 16, size: 1, type: 'u8' }, // 0=Open, 1=Locked, 2=Resolved
+  startSlot: { offset: 17, size: 8, type: 'u64' },
+  endSlot: { offset: 25, size: 8, type: 'u64' },
+  totalPotLamports: { offset: 33, size: 8, type: 'u64' },
+  totalWeight: { offset: 41, size: 8, type: 'u64' },
+  winnerIndex: { offset: 49, size: 5, type: 'Option<u32>' },
+  winner: { offset: 54, size: 33, type: 'Option<Pubkey>' },
+  vrfResult: { offset: 87, size: 17, type: 'Option<u128>' }, // WAIT - offset 51!
+  // ^^^ THIS WAS THE BUG! Document TESTED offsets only
+};
+
+// Export helper functions
+function readVrfResult(accountData) {
+  const offset = 51; // VERIFIED through testing
+  if (accountData[offset] !== 1) return null;
+  return accountData.slice(offset + 1, offset + 17);
+}
+```
+
+### 3. Extract Winner Calculation to Separate Module
+
+```javascript
+// services/winnerCalculator.js
+
+/**
+ * Calculate winner using weighted random selection
+ * This MUST match the on-chain calculation exactly!
+ * 
+ * Algorithm (from programs/dubs_jackpot_program/src/lib.rs:283-295):
+ * 1. winner_point = vrf_result % total_weight
+ * 2. Find first entry where cumulative_to > winner_point
+ */
+function calculateWinner(vrfResult, totalWeight, entries) {
+  if (!vrfResult || !totalWeight || !entries || entries.length === 0) {
+    throw new Error('Invalid input for winner calculation');
+  }
+  
+  const winnerPoint = vrfResult % totalWeight;
+  
+  for (const entry of entries) {
+    if (BigInt(entry.cumulativeTo) > winnerPoint) {
+      return entry.player;
+    }
+  }
+  
+  throw new Error('Winner selection failed - no matching entry found');
+}
+
+module.exports = { calculateWinner };
+```
+
+### 4. Monitoring & Alerts
+
+#### Health Check Script
+```javascript
+// scripts/health-check.js
+
+async function checkJackpotHealth() {
+  const round = await getCurrentRound();
+  
+  // Check 1: Is keeper bot running?
+  if (!isProcessRunning('jackpot-keeper')) {
+    alert('🚨 KEEPER BOT NOT RUNNING!');
+  }
+  
+  // Check 2: Is round stuck?
+  if (round.status === 'Locked') {
+    const lockedDuration = currentSlot - round.endSlot;
+    if (lockedDuration > 300) { // 2 minutes
+      alert('🚨 ROUND STUCK IN LOCKED STATE!');
+    }
+  }
+  
+  // Check 3: Is API responding?
+  try {
+    await fetch('http://localhost:3001/jackpot/health');
+  } catch (e) {
+    alert('🚨 API SERVER DOWN!');
+  }
+  
+  // Check 4: Are accounts reachable?
+  const roundAccount = await connection.getAccountInfo(roundPda);
+  if (!roundAccount) {
+    alert('🚨 ROUND ACCOUNT NOT FOUND!');
+  }
+}
+
+// Run every 30 seconds
+setInterval(checkJackpotHealth, 30000);
+```
+
+#### Discord/Telegram Alerts
+```javascript
+// services/alerting.js
+
+async function sendAlert(message, severity = 'warning') {
+  // Send to Discord
+  await axios.post(DISCORD_WEBHOOK, {
+    content: `[${severity.toUpperCase()}] ${message}`,
+  });
+  
+  // Send to Telegram
+  await axios.post(`https://api.telegram.org/bot${BOT_TOKEN}/sendMessage`, {
+    chat_id: ADMIN_CHAT_ID,
+    text: message,
+  });
+  
+  // Log to file
+  fs.appendFileSync('alerts.log', `${new Date().toISOString()} [${severity}] ${message}\n`);
+}
+```
+
+### 5. Keeper Bot Reliability
+
+#### Process Manager (PM2)
+```bash
+# Install PM2
+npm install -g pm2
+
+# Start keeper bot with PM2
+pm2 start scripts/jackpot-keeper.js --name jackpot-keeper
+
+# Auto-restart on crash
+pm2 startup
+pm2 save
+
+# Monitor
+pm2 logs jackpot-keeper
+pm2 monit
+```
+
+#### Keeper Bot Health Check
+```javascript
+// Inside jackpot-keeper.js
+
+class JackpotKeeper {
+  constructor() {
+    // ... existing code ...
+    this.lastHeartbeat = Date.now();
+    this.startHeartbeat();
+  }
+  
+  startHeartbeat() {
+    setInterval(() => {
+      const uptime = Date.now() - this.startTime;
+      fs.writeFileSync('.keeper-heartbeat', JSON.stringify({
+        timestamp: Date.now(),
+        uptime,
+        lastRoundProcessed: this.lastRoundId,
+      }));
+    }, 5000);
+  }
+}
+```
+
+#### External Heartbeat Monitor
+```javascript
+// scripts/monitor-keeper.js
+
+setInterval(() => {
+  const heartbeat = JSON.parse(fs.readFileSync('.keeper-heartbeat'));
+  const age = Date.now() - heartbeat.timestamp;
+  
+  if (age > 30000) { // No heartbeat for 30 seconds
+    sendAlert('🚨 KEEPER BOT HEARTBEAT MISSING!', 'critical');
+    // Auto-restart
+    exec('pm2 restart jackpot-keeper');
+  }
+}, 10000);
+```
+
+### 6. Pre-Deployment Checklist
+
+Create a checklist that MUST be completed before deploying changes:
+
+```markdown
+## Deployment Checklist
+
+### Code Quality
+- [ ] All unit tests pass (`npm test`)
+- [ ] Integration tests pass (`npm run test:integration`)
+- [ ] Linter passes with no errors (`npm run lint`)
+- [ ] No hardcoded values (check for TODO, FIXME, TEMP)
+- [ ] Winner calculation matches smart contract logic
+
+### Account Layout
+- [ ] All offsets documented in `accountLayouts.js`
+- [ ] Offsets verified with `scripts/verify-account-layout.js`
+- [ ] VRF result offset tested on devnet
+
+### Testing
+- [ ] Tested full round lifecycle on devnet
+- [ ] Verified winner selection with 3+ entries
+- [ ] Tested edge cases (1 entry, max entries, ties)
+- [ ] Confirmed keeper bot can process locked rounds
+
+### Monitoring
+- [ ] Health check script running
+- [ ] Alerts configured and tested
+- [ ] PM2 configured for auto-restart
+- [ ] Logs being collected
+
+### Documentation
+- [ ] CHANGELOG.md updated
+- [ ] API docs updated if endpoints changed
+- [ ] README updated if setup changed
+```
+
+### 7. Development Practices
+
+#### Code Review Requirements
+```markdown
+## Code Review Checklist
+
+For any changes to jackpot logic:
+
+1. **Algorithm Verification**
+   - Does off-chain match on-chain? (Cite line numbers in Rust code)
+   - Are there unit tests?
+   - Has it been tested on devnet?
+
+2. **Account Parsing**
+   - Are offsets documented?
+   - Are they verified with tests?
+   - Do they match the Rust struct layout?
+
+3. **Error Handling**
+   - What happens if VRF result is missing?
+   - What happens if entries array is empty?
+   - What happens if keeper bot crashes mid-round?
+
+4. **Testing**
+   - Manual testing completed?
+   - Automated tests added?
+   - Edge cases covered?
+```
+
+#### Git Hooks (Pre-commit)
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+
+echo "Running pre-commit checks..."
+
+# Run tests
+npm test || {
+  echo "❌ Tests failed! Fix before committing."
+  exit 1
+}
+
+# Run linter
+npm run lint || {
+  echo "❌ Linter failed! Fix before committing."
+  exit 1
+}
+
+# Check for dangerous patterns
+if git diff --cached | grep -E "entries\[0\]\.player|FIXME|TODO.*urgent"; then
+  echo "⚠️  Warning: Suspicious patterns found. Review carefully!"
+  echo "   - Hardcoded entries[0]?"
+  echo "   - Urgent TODOs?"
+fi
+
+echo "✅ Pre-commit checks passed!"
+```
+
+### 8. Testnet-First Development
+
+```markdown
+## Development Workflow
+
+1. **Make changes on devnet**
+   - Deploy to devnet first
+   - Run for 24 hours
+   - Monitor for issues
+
+2. **Stress testing**
+   - Process 50+ rounds
+   - Test with 1, 5, 10, 50 entries
+   - Test edge cases (no entries, time boundaries)
+
+3. **Mainnet deployment**
+   - Only deploy after 24h on devnet
+   - Monitor closely for first 10 rounds
+   - Have rollback plan ready
+```
+
+### 9. Circuit Breakers
+
+Add automatic pause functionality:
+
+```javascript
+// In jackpot-keeper.js
+
+async function processRound(round) {
+  // Circuit breaker: Stop if repeated failures
+  if (this.consecutiveFailures > 5) {
+    console.error('🚨 TOO MANY FAILURES - STOPPING KEEPER BOT');
+    sendAlert('Keeper bot stopped due to repeated failures', 'critical');
+    process.exit(1);
+  }
+  
+  try {
+    // ... normal processing ...
+    this.consecutiveFailures = 0;
+  } catch (error) {
+    this.consecutiveFailures++;
+    console.error(`❌ Failure ${this.consecutiveFailures}/5:`, error.message);
+  }
+}
+```
+
+### 10. Documentation Standards
+
+Every critical function must have:
+
+```javascript
+/**
+ * Calculate winner using weighted random selection
+ * 
+ * @algorithm Matches on-chain logic from programs/dubs_jackpot_program/src/lib.rs:283-295
+ * 
+ * @param {BigInt} vrfResult - Random value from VRF oracle (u128)
+ * @param {BigInt} totalWeight - Sum of all entry weights (u64)
+ * @param {Array<Entry>} entries - Array of entries with cumulative weights
+ * @returns {string} Winner's public key
+ * 
+ * @tested tests/winner-calculation.test.js:15-45
+ * @verified 2024-11-15 on devnet round 50
+ * 
+ * @example
+ * const winner = calculateWinner(123456n, 50n, entries);
+ * // => 'FWUJCthDfPcgmTvdQWM5uofxxiYjqJFMMwiLYvS7LBFa'
+ */
+function calculateWinner(vrfResult, totalWeight, entries) {
+  // ...
+}
+```
+
+## Quick Reference
+
+### When Adding New Features
+1. Write tests FIRST
+2. Implement feature
+3. Test on devnet for 24h
+4. Get code review
+5. Update documentation
+6. Deploy to mainnet
+
+### When Debugging Production Issues
+1. Check keeper bot logs: `pm2 logs jackpot-keeper`
+2. Check round status: `curl http://localhost:3001/jackpot/round/current`
+3. Check account data: `node scripts/dump-account.js`
+4. Verify winner calculation: `node scripts/debug-winner-calc.js`
+5. Manual resolve if needed: `node scripts/resolve-direct.js`
+
+### Emergency Contacts
+- Developer: [Your contact]
+- Devops: [Your contact]
+- Alerts: check Discord #jackpot-alerts
+
+## Conclusion
+
+The Round 50 incident taught us that:
+1. **Testing is not optional** - Unit and integration tests catch bugs before production
+2. **Documentation must match reality** - Offsets must be verified, not assumed
+3. **Monitoring is critical** - Automated alerts prevent long outages
+4. **Keeper bot reliability is key** - Use process managers and health checks
+5. **Code reviews save money** - Peer review catches logic errors
+
+By following these practices, we can ensure the jackpot runs smoothly 24/7.
+