dubs-server 1.0.0

package/documentation/AUTOMATIC_MODE_ORACLE.md

@@ -0,0 +1,321 @@
+# Automatic Sports Mode - Oracle System
+
+## Overview
+The oracle system monitors automatic sports betting games and resolves them based on real-world game outcomes.
+
+## Architecture
+
+```
+┌─────────────────────┐
+│  Oracle Monitor     │  Every 5 minutes
+│  (cron/oracle       │  ─────────────────▶
+│   Monitor.js)       │
+└─────────────────────┘
+           │
+           ▼
+┌─────────────────────┐
+│  Fetch Pending      │  GET /api/auth/games/automatic/pending
+│  Games              │  ◀──────────────────
+└─────────────────────┘  dubs-games-api
+           │
+           ▼
+┌─────────────────────┐
+│  Check Live Scores  │  GET /api/livescores/:league
+│  for Each Game      │  ◀──────────────────
+└─────────────────────┘  dubs-api
+           │
+           ▼
+┌─────────────────────┐
+│  If Game is FINAL:  │
+│  - Determine Winner │
+│  - Resolve on-chain │  resolve_automatic_game instruction
+│  - Update Firebase  │  POST /api/games/:id/resolve
+└─────────────────────┘
+           │
+           ▼
+┌─────────────────────┐
+│  Winners Claim      │  claim_automatic_winnings instruction
+│  Their Payouts      │  (called by players)
+└─────────────────────┘
+```
+
+## Setup
+
+### 1. Create Oracle Wallet
+
+```bash
+npm run oracle:setup
+```
+
+This creates an oracle wallet at `wallets/oracle.json` and funds it on devnet.
+
+**Save the Oracle Public Key** - you'll need it when creating automatic games!
+
+### 2. Configure Environment
+
+Copy `env.template` to `.env`:
+
+```bash
+cp env.template .env
+```
+
+Update values:
+
+```bash
+# For local development
+SOLANA_NETWORK=http://127.0.0.1:8899
+LIVE_SCORES_API_URL=http://localhost:3000
+DUBS_GAMES_API_URL=http://localhost:3001
+
+# For production
+SOLANA_NETWORK=https://api.mainnet-beta.solana.com
+LIVE_SCORES_API_URL=https://dubs-api.herokuapp.com
+DUBS_GAMES_API_URL=https://dubs-games-api.herokuapp.com
+```
+
+### 3. Start the Oracle
+
+```bash
+# Production mode
+npm run oracle:start
+
+# Development mode (auto-restart on changes)
+npm run oracle:dev
+```
+
+The oracle will:
+- ✅ Check every 5 minutes (configurable)
+- ✅ Find games past their lock time
+- ✅ Query live scores API
+- ✅ Resolve games when sports events finish
+- ✅ Update Firebase with results
+
+## How It Works
+
+### Game Lifecycle
+
+```
+1. User Creates Automatic Game
+   - Picks upcoming sports event (e.g., Lakers vs Celtics at 7:00 PM)
+   - Sets buy-in amount
+   - Oracle wallet address is set
+   - Lock time = 6:50 PM (10 min before tip-off)
+
+2. Players Join & Pick Teams
+   - Alice picks Lakers (home) - 0.5 SOL
+   - Bob picks Celtics (away) - 0.5 SOL
+   - Carol picks Lakers (home) - 0.5 SOL
+   - Total pot: 1.5 SOL
+
+3. Lock Time Arrives (6:50 PM)
+   - Game auto-locks
+   - No more joins allowed
+
+4. Real Game Happens (7:00 PM - 9:30 PM)
+   - Lakers vs Celtics plays out
+   - Oracle monitor checks every 5 minutes
+
+5. Game Finishes (9:30 PM)
+   - Oracle detects: Lakers won 110-105
+   - Calls resolve_automatic_game on-chain
+   - Sets winning_team = Home
+   - Updates Firebase
+
+6. Winners Claim Payouts
+   - Alice calls claim_automatic_winnings → Gets 0.75 SOL
+   - Carol calls claim_automatic_winnings → Gets 0.75 SOL
+   - Bob gets nothing (picked wrong team)
+```
+
+### Score Matching Logic
+
+The oracle uses fuzzy team name matching:
+
+```javascript
+normalizeTeamName("Los Angeles Lakers") → "lakers"
+normalizeTeamName("LA Lakers") → "lakers"  
+normalizeTeamName("Lakers") → "lakers"
+```
+
+This ensures games are matched even if team names differ slightly between APIs.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `services/automaticGameOracle.js` | Oracle service class |
+| `cron/oracleMonitor.js` | Cron job runner |
+| `setup-oracle.sh` | Oracle wallet setup script |
+| `env.template` | Environment variables template |
+
+## API Integration
+
+### dubs-games-api Endpoints Used:
+
+```
+GET  /api/auth/games/automatic/pending
+POST /api/games/:gameId/resolve
+```
+
+### dubs-api Endpoints Used:
+
+```
+GET /api/livescores/:league
+```
+
+Returns:
+```json
+[
+  {
+    "date": "2025-10-27",
+    "game": "Lakers vs Celtics",
+    "status": "Final",
+    "competitors": [
+      { "name": "Los Angeles Lakers", "homeAway": "home", "score": 110 },
+      { "name": "Boston Celtics", "homeAway": "away", "score": 105 }
+    ]
+  }
+]
+```
+
+## Monitoring
+
+### Check Oracle Status
+
+```bash
+# Check if oracle process is running
+ps aux | grep oracleMonitor
+
+# View logs
+tail -f /path/to/your/logs
+```
+
+### Manual Resolution (if needed)
+
+If oracle misses a game, you can manually trigger resolution:
+
+```bash
+curl -X POST http://localhost:3001/api/games/adam-amy-001/resolve \
+  -H "Content-Type: application/json" \
+  -d '{
+    "winner": "home",
+    "homeScore": 105,
+    "awayScore": 98,
+    "resolvedBy": "manual"
+  }'
+```
+
+## Security
+
+### Oracle Authorization
+
+- Only the designated oracle wallet can resolve games
+- Validated on-chain: `require!(oracle.key() == game.oracle)`
+- Oracle private key must be kept secure
+
+### Best Practices
+
+1. **Secure the Oracle Wallet**
+   - Keep `wallets/oracle.json` in `.gitignore`
+   - Use environment variables in production
+   - Consider hardware wallet for mainnet
+
+2. **Monitor Oracle Health**
+   - Set up alerts if oracle stops
+   - Log all resolution attempts
+   - Have backup oracle wallet ready
+
+3. **Handle Edge Cases**
+   - Postponed games → Manual resolution
+   - Cancelled games → Refund all players
+   - API downtime → Retry logic
+
+## Testing
+
+### Test the Oracle Locally
+
+1. Start local validator:
+```bash
+solana-test-validator --reset
+```
+
+2. Deploy program:
+```bash
+anchor deploy
+```
+
+3. Setup oracle:
+```bash
+npm run oracle:setup
+```
+
+4. Create test game (with mock event that's already finished):
+```bash
+curl -X POST http://localhost:3001/api/auth/games/save \
+  -d '{ "gameId": "test-001", "sportsEvent": {...} }'
+```
+
+5. Start oracle:
+```bash
+npm run oracle:dev
+```
+
+6. Watch logs - oracle should detect and resolve the game!
+
+## Production Deployment
+
+### Heroku
+
+Add to `Procfile`:
+```
+web: node server.js
+oracle: node cron/oracleMonitor.js
+```
+
+Then scale:
+```bash
+heroku ps:scale web=1 oracle=1
+```
+
+### Environment Variables
+
+Set in Heroku:
+```bash
+heroku config:set ORACLE_WALLET_PATH=/app/wallets/oracle.json
+heroku config:set LIVE_SCORES_API_URL=https://dubs-api.herokuapp.com
+heroku config:set DUBS_GAMES_API_URL=https://dubs-games-api.herokuapp.com
+```
+
+## Troubleshooting
+
+### Oracle not resolving games
+
+1. Check oracle is running: `ps aux | grep oracle`
+2. Check API connectivity: `curl $LIVE_SCORES_API_URL/api/livescores/NBA`
+3. Check pending games exist: `curl $DUBS_GAMES_API_URL/api/auth/games/automatic/pending`
+4. Check oracle wallet has SOL for transactions
+
+### Games resolved with wrong winner
+
+1. Check live scores API response format
+2. Verify team name normalization logic
+3. Check date matching (timezone issues?)
+
+### Transactions failing
+
+1. Oracle wallet needs SOL for transaction fees
+2. Check program ID is correct
+3. Verify game exists on-chain
+
+## Future Enhancements
+
+- [ ] Multi-oracle consensus (2-of-3 oracles must agree)
+- [ ] Automatic refunds for postponed/cancelled games
+- [ ] Discord/Telegram notifications when games resolve
+- [ ] Dashboard for monitoring oracle health
+- [ ] Automatic oracle wallet top-up
+
+---
+
+**Phase 3: Oracle System** ✅ Complete!
+

package/documentation/BUG_FIX_COHORT_DATE_DISPLAY.md

@@ -0,0 +1,171 @@
+# 🐛 Bug Fix: Cohort Date Display - "Nov 30, 2025" Issue
+
+## Problem Identified
+
+**User Report:**
+> "How can we have more than 20 users but only 7 signups - this data makes no sense"
+
+**Screenshot showed:**
+- Cohort labeled: "December 2025" with subtitle "Nov 30, 2025"
+- 7 signups in that cohort
+- Data seemed inconsistent
+
+## Root Cause Analysis
+
+### Investigation Results (dubs-server-dev):
+
+```
+Total Unique Users: 7
+Total registration_completed Events: 11
+Date Range: Dec 14, 2025 to Dec 31, 2025
+```
+
+**All 7 users signed up in DECEMBER**, but the label showed "Nov 30, 2025"!
+
+### The Bug
+
+When PostgreSQL returns monthly cohort data:
+```sql
+DATE_TRUNC('month', '2025-12-15') 
+-- Returns: 2025-12-01T00:00:00.000Z (December 1st, UTC)
+```
+
+JavaScript's `toLocaleDateString()` without timezone specification:
+```javascript
+new Date('2025-12-01T00:00:00.000Z').toLocaleDateString('en-US')
+// In PST timezone: "Nov 30, 2025" ❌ (off by one day!)
+// Should be: "December 2025" ✅
+```
+
+**Why it happens:**
+- PostgreSQL stores dates in UTC
+- `DATE_TRUNC('month')` returns midnight UTC on the 1st of the month
+- JavaScript `toLocaleDateString()` converts to local timezone
+- In Pacific timezone (UTC-8), midnight UTC on Dec 1 = 4pm Nov 30
+- Result: **November 30 displayed instead of December!**
+
+## The Fix
+
+### Backend (routes/analyticsRoutes.js)
+
+**Before:**
+```javascript
+dateRange = cohortDate.toLocaleDateString('en-US', { month: 'long', year: 'numeric' });
+```
+
+**After:**
+```javascript
+dateRange = cohortDate.toLocaleDateString('en-US', { 
+  month: 'long', 
+  year: 'numeric', 
+  timeZone: 'UTC'  // ✅ Force UTC interpretation
+});
+```
+
+### Frontend (AnalyticsDashboard.tsx)
+
+**Before:**
+```javascript
+{new Date(cohort.signup_cohort).toLocaleDateString('en-US', { 
+  month: 'short', day: 'numeric', year: 'numeric' 
+})}
+```
+
+**After:**
+```javascript
+{new Date(cohort.signup_cohort).toLocaleDateString('en-US', { 
+  month: 'short', day: 'numeric', year: 'numeric', 
+  timeZone: 'UTC'  // ✅ Force UTC interpretation
+})}
+```
+
+## Files Changed
+
+1. **Backend:** `routes/analyticsRoutes.js`
+   - Fixed `GET /api/analytics/cohort-retention` date formatting (line ~997-1000)
+   - Fixed `GET /api/analytics/cohort-retention/csv` date formatting (line ~1166-1172)
+
+2. **Frontend:** `app/v2/components/overlay/AnalyticsDashboard.tsx`
+   - Fixed cohort subtitle date display (line ~1160)
+
+## Testing
+
+### Before Fix (Dev Database):
+```
+Cohort: December 2025
+Subtitle: Nov 30, 2025  ❌ WRONG
+Signups: 7
+```
+
+### After Fix (Expected):
+```
+Cohort: December 2025
+Subtitle: Dec 1, 2025   ✅ CORRECT
+Signups: 7
+```
+
+## Verification Steps
+
+1. **Deploy fixes to dev:**
+   ```bash
+   cd /Users/adamdahan/Developer/iheartsolana/solana-programs/dubs-server
+   git add routes/analyticsRoutes.js
+   git commit -m "fix: Cohort date display timezone bug"
+   git push heroku-dev main
+   ```
+
+2. **Refresh dashboard:**
+   - Open dubs-jackpot-spa in dev
+   - Navigate to Analytics Dashboard
+   - Expand "Cohort Retention Analysis"
+   - Verify "December 2025" shows correct date
+
+3. **Test CSV export:**
+   - Click "Export CSV"
+   - Open file
+   - Verify dates are correct
+
+## Impact
+
+**Before:**
+- ❌ Confusing "Nov 30, 2025" label for December cohort
+- ❌ Off-by-one-day errors in weekly cohorts
+- ❌ Users questioning data accuracy
+
+**After:**
+- ✅ Correct month/year labels
+- ✅ Accurate date ranges
+- ✅ Clear, trustworthy data presentation
+
+## Related Issues
+
+This timezone bug affected:
+1. Monthly cohort labels (most visible)
+2. Weekly cohort date ranges
+3. CSV export headers
+4. Frontend subtitle displays
+
+All fixed with `timeZone: 'UTC'` parameter!
+
+## Lessons Learned
+
+1. **Always specify timezone** when formatting dates from database
+2. **PostgreSQL returns UTC** - JavaScript must interpret as UTC
+3. **Test across timezones** - PST/EST/UTC can show different dates
+4. **Use UTC for cohort logic** - Business logic should be timezone-agnostic
+
+## Prevention
+
+Add to code review checklist:
+- [ ] All `toLocaleDateString()` calls have `timeZone` specified
+- [ ] Date formatting uses UTC for database timestamps
+- [ ] Test in different timezones (PST, EST, UTC)
+
+---
+
+**Status:** ✅ FIXED  
+**Deployed:** Pending (commit ready)  
+**Impact:** High (user-facing data display)  
+**Complexity:** Low (timezone parameter addition)
+
+

package/documentation/CLAIM_MIGRATION_INSTRUCTIONS.md

@@ -0,0 +1,52 @@
+# Add Claim Columns Migration
+
+## Problem
+The claim endpoint is failing with:
+```
+ERROR: column "claimed_at" of relation "user_game_refs" does not exist
+```
+
+## Solution
+Run this migration to add claim tracking columns to the `user_game_refs` table.
+
+## Run on Heroku:
+
+```bash
+# Option 1: Via Heroku CLI
+heroku pg:psql --app dubs-server-dev < scripts/add-claim-columns.sql
+
+# Option 2: Interactive
+heroku pg:psql --app dubs-server-dev
+# Then paste the SQL from add-claim-columns.sql
+```
+
+## What It Adds:
+
+| Column | Type | Purpose |
+|--------|------|---------|
+| `claimed_at` | TIMESTAMP | When user claimed prize |
+| `claim_signature` | TEXT | Solana transaction signature |
+| `claim_explorer_url` | TEXT | Explorer link for claim tx |
+| `amount_claimed` | DECIMAL(20,9) | Amount of SOL claimed |
+
+## Verify:
+
+After running, you should see:
+```
+NOTICE:  Added claimed_at column
+NOTICE:  Added claim_signature column
+NOTICE:  Added claim_explorer_url column
+NOTICE:  Added amount_claimed column
+
+ column_name         | data_type
+---------------------+-----------
+ amount_claimed      | numeric
+ claim_explorer_url  | text
+ claim_signature     | text
+ claimed_at          | timestamp
+```
+
+## Test:
+
+After migration, try claiming a prize again. It should work!
+

package/documentation/CLAIM_STATUS_FIX.md

@@ -0,0 +1,67 @@
+# Claim Status Fix - Deployed ✅
+
+## Problem
+The MyGamesWidget was showing already-claimed games as still "Claimable". When users tried to claim, they got the error: "You have already claimed your winnings for this game"
+
+## Root Cause
+The backend API endpoint `GET /api/auth/games/user/:walletAddress` was **not returning** the `claimedAt` field, even though it existed in the database. This meant the frontend had no way to detect if a game had already been claimed.
+
+## What Was Fixed
+
+### 1. Backend API Response (routes/gamesRoutes.js)
+Added claim-related fields to the API response:
+- `claimedAt` - Timestamp when user claimed
+- `claimSignature` - Solana transaction signature
+- `claimExplorerUrl` - Explorer link for the claim transaction  
+- `amountClaimed` - Amount of SOL claimed
+
+### 2. Table Schema (routes/gamesRoutes.js)
+Updated the `user_game_refs` table creation to include claim columns by default:
+- `claimed_at TIMESTAMP`
+- `claim_signature TEXT`
+- `claim_explorer_url TEXT`
+- `amount_claimed DECIMAL(20, 9)`
+- `updated_at TIMESTAMP DEFAULT NOW()`
+
+### 3. Migration Script (scripts/fix-claim-columns.js)
+Created a migration script to add these columns to existing databases.
+
+## Database Status
+✅ All claim columns already exist in the Heroku database (they were added previously)
+✅ Verified columns with correct data types
+
+## Deployment
+- **Committed**: 4e8f22e
+- **Deployed to Heroku**: v179
+- **Pushed to GitHub**: ✅
+
+## How It Works Now
+
+1. User views their games in MyGamesWidget
+2. API returns `claimedAt` field for each game
+3. Frontend checks `game.claimedAt` at line 109:
+   ```typescript
+   if (game.claimedAt) {
+     return 'claimed';
+   }
+   ```
+4. Already-claimed games show blue "✓ Claimed" status
+5. Only truly claimable games show green "💰 Claimable" status
+
+## Testing
+To test with your wallet `3sgQXvLKs4XfBTxG3jY2J2E5NougemfC6i4nZbUVx8xt`:
+
+**Expected Results:**
+- `sport-1764428545106-jeet2jl9s`: Shows as "Claimed" (claimed on Nov 29)
+- `sport-1764428315170-5bq7g8tqe`: Shows as "Claimable" (not claimed yet)
+- Other games show appropriate status based on win/loss
+
+## Next Steps
+Just refresh your dubs-jackpot app - the API is now returning the claim status correctly!
+
+
+
+
+
+
+