dubs-server 1.0.0

package/documentation/REFEREE_MODE_GUIDE.md

@@ -0,0 +1,392 @@
+# ⚖️ Referee Mode - Complete Guide
+
+## 🎯 **What is Referee Mode?**
+
+**Hire an expert to judge your competition and earn a commission!**
+
+Referee Mode is the **3rd game mode** alongside Manual and Democratic voting, enabling professional judging for competitions where an expert's opinion matters.
+
+---
+
+## 🏗️ **3 Game Modes:**
+
+| Mode | Who Decides | Best For | Commission |
+|------|-------------|----------|------------|
+| **👑 Manual** | Creator chooses | Friends, casual | 0% |
+| **🗳️ Democratic** | Players vote (majority) | 3+ players, community | 0% |
+| **⚖️ Referee** | Expert judge | Competitions, any size | 10-20% |
+
+---
+
+## ⚖️ **How Referee Mode Works:**
+
+### **Setup:**
+```
+Creator creates game:
+├── Game Mode: 2 (Referee)
+├── Referee Address: ExpertJudgeAddress
+├── Referee Commission: 15%
+├── Operator Fee: 10%
+├── Buy-in: 1 SOL
+└── Max Players: 5
+
+Economics (5 players):
+Total Pot: 5 SOL
+- Operator Fee (10%): 0.5 SOL
+- Referee Commission (15%): 0.75 SOL
+- Prize Pool: 3.75 SOL
+```
+
+### **Flow:**
+```
+1. Creator sets referee & commission
+2. Players join (referee CANNOT join!)
+3. Competition happens
+4. ONLY referee can vote/judge
+5. Referee picks winner
+6. Distribution:
+   - Winner: 3.75 SOL
+   - Referee: 0.75 SOL
+   - Operator: 0.5 SOL
+```
+
+---
+
+## 🔒 **Critical Rules:**
+
+### **1. Referee Cannot Join as Player** ✅
+```
+Smart contract enforces:
+- If player address === referee address
+→ Join transaction fails
+→ Prevents conflict of interest!
+```
+
+### **2. Only Referee Can Vote** ✅
+```
+In Referee mode:
+- Players try to vote → Transaction fails
+- Referee votes → Success!
+→ Expert decision only!
+```
+
+### **3. Referee Must Earn Commission** ✅
+```
+Validation:
+- refereeCommission must be > 0
+- operatorFee + refereeCommission ≤ 100%
+→ Fair compensation guaranteed!
+```
+
+### **4. No Creator Override in Referee Mode** ✅
+```
+If you hire a referee, you trust them:
+- Creator CANNOT override in Referee mode
+- Referee's decision is final
+→ Maintains referee credibility!
+```
+
+---
+
+## 📡 **API Endpoints:**
+
+### **Create Referee Game:**
+```javascript
+POST /api/v1/prod/transaction/build/create
+
+Body:
+{
+  "creatorAddress": "YOUR_ADDRESS",
+  "buyIn": 1.0,
+  "maxPlayers": 5,
+  "operatorFee": 10,
+  "votingEnabled": true,
+  "gameMode": 2,  ← Referee mode!
+  "refereeAddress": "EXPERT_JUDGE_ADDRESS",
+  "refereeCommission": 15
+}
+
+Response:
+{
+  "success": true,
+  "gameId": "uuid",
+  "transaction": "base64_unsigned_tx",
+  "gameAddress": "PDA"
+}
+```
+
+### **Referee Casts Vote:**
+```javascript
+POST /api/v1/prod/transaction/build/cast-vote
+
+Body:
+{
+  "voterAddress": "REFEREE_ADDRESS",  ← Must be the referee!
+  "gameId": "uuid",
+  "votedFor": "WINNING_PLAYER_ADDRESS"
+}
+
+Response:
+{
+  "success": true,
+  "transaction": "base64_unsigned_tx"
+}
+```
+
+### **Distribute (After Referee Decides):**
+```javascript
+POST /api/v1/prod/transaction/build/distribute-by-vote
+
+Body:
+{
+  "playerAddress": "ANY_PLAYER_ADDRESS",  ← Anyone can trigger!
+  "gameId": "uuid"
+}
+
+Response:
+{
+  "success": true,
+  "transaction": "base64_unsigned_tx",
+  "winners": ["WinnerAddress"],
+  "voteCounts": {
+    "WinnerAddress": 1
+  }
+}
+```
+
+### **Get Game Info:**
+```javascript
+GET /api/v1/prod/game/:gameId
+
+Response (Referee Mode):
+{
+  "exists": true,
+  "game": {
+    "gameId": "uuid",
+    "authority": "Creator...",
+    "buyIn": 1.0,
+    "maxPlayers": 5,
+    "players": ["P1", "P2", "P3"],
+    "totalPot": 3.0,
+    "isActive": true,
+    "votes": [
+      {"voter": "Referee...", "votedFor": "P2"}
+    ],
+    "votingEnabled": true,
+    "gameMode": 2,  ← Referee mode!
+    "referee": "RefereeAddress...",
+    "refereeCommission": 15
+  }
+}
+```
+
+---
+
+## 🎮 **Use Cases:**
+
+### **🎨 Art Contest:**
+```
+Setup:
+- 10 artists pay 2 SOL each = 20 SOL
+- Famous artist as referee
+- Referee commission: 15%
+- Operator: 5%
+
+Payout:
+- Winner: 16 SOL (80%)
+- Referee: 3 SOL (15%)
+- Operator: 1 SOL (5%)
+```
+
+### **🎤 Talent Show:**
+```
+Setup:
+- 20 performers pay 0.5 SOL = 10 SOL
+- Celebrity judge
+- Referee commission: 20%
+- Top 3 winners
+
+Payout:
+- 1st: 4 SOL (50%)
+- 2nd: 2 SOL (25%)  
+- 3rd: 2 SOL (25%)
+- Celebrity: 2 SOL (20%)
+```
+
+### **⚽ Sports Match:**
+```
+Setup:
+- 2 teams pay 5 SOL = 10 SOL
+- Certified referee
+- Referee commission: 10%
+
+Payout:
+- Winner: 8 SOL (80%)
+- Referee: 1 SOL (10%)
+- Operator: 1 SOL (10%)
+```
+
+---
+
+## 🔄 **Complete Workflow:**
+
+### **Creator Side:**
+```
+1. Create game with gameMode: 2
+2. Set referee address
+3. Set referee commission (15%)
+4. Share game ID with:
+   - Referee (so they can view/judge)
+   - Players (so they can join)
+5. Wait for competition
+6. After referee judges → Distribution happens
+```
+
+### **Referee Side:**
+```
+1. Receive game ID from creator
+2. Paste in "Join Game"
+3. See "⚖️ View as Referee" button
+4. Tap → Game added to list (no payment!)
+5. Monitor game (see players join)
+6. When ready, tap "⚖️ Judge Winner"
+7. Select winner
+8. Distribution happens → Earn commission!
+```
+
+### **Player Side:**
+```
+1. Receive game ID
+2. Join game (pay buy-in)
+3. Compete
+4. See golden referee card (who's judging)
+5. Wait for referee decision
+6. Winner gets prize!
+```
+
+---
+
+## 🎯 **Key Features:**
+
+```
+✅ Referee cannot join as player (conflict of interest protection)
+✅ Only referee can vote (expert opinion only)
+✅ Referee earns automatic commission
+✅ Any player can trigger distribution (trustless)
+✅ Creator cannot override (referee decision is final)
+✅ All on-chain and transparent
+✅ Commission paid automatically
+```
+
+---
+
+## 💰 **Economics:**
+
+### **Fee Breakdown:**
+```
+Total Pot: 10 SOL
+
+Fees:
+- Operator: 10% = 1 SOL
+- Referee: 15% = 1.5 SOL
+- Prize Pool: 75% = 7.5 SOL
+
+Validation:
+✅ operator + referee ≤ 100%
+✅ referee > 0 in Referee mode
+```
+
+---
+
+## 🧪 **Testing Referee Mode:**
+
+### **With CLI:**
+```bash
+npm run cli
+
+# Create referee game
+curl -X POST http://localhost:3001/api/v1/demo/game/create \
+  -H "Content-Type: application/json" \
+  -d '{
+    "player": "creator",
+    "buyIn": 0.5,
+    "maxPlayers": 3,
+    "gameMode": 2,
+    "refereePlayer": "jelli",
+    "refereeCommission": 15
+  }'
+
+# Players join
+# Referee votes (as "jelli")
+# Distribute by vote
+```
+
+---
+
+## 🚀 **Deployment Status:**
+
+```
+✅ Smart Contract: Deployed to devnet
+✅ Server Endpoints: Live on Heroku v10
+✅ Mobile SDK: Complete with UI
+✅ Documentation: Updated
+✅ Postman: Examples included
+```
+
+---
+
+## 📊 **Error Codes:**
+
+```
+RefereeCannotBePlayer: Referee tried to join
+OnlyRefereeCanVote: Player tried to vote in Referee mode
+RefereeModeRequiresReferee: No referee address provided
+InvalidRefereeCommission: Commission not 0-100
+TotalFeesExceed100: operator + referee > 100%
+```
+
+---
+
+## 🎊 **Why Referee Mode is Genius:**
+
+```
+✅ Solves 2-player voting problem
+✅ Enables expert monetization
+✅ Professional competitions possible
+✅ Influencer economy
+✅ Still 100% on-chain
+✅ Still transparent
+✅ Still trustless (referee can't steal)
+✅ Creates new use cases
+```
+
+---
+
+## 🌟 **Examples:**
+
+### **Crypto Art Contest:**
+```
+- 20 artists × 2 SOL = 40 SOL pot
+- Famous crypto artist judges
+- 20% referee commission = 8 SOL
+- Winner gets 28 SOL (after 10% operator fee)
+- Referee earns 8 SOL for their expertise!
+```
+
+### **Gaming Tournament:**
+```
+- 100 players × 0.1 SOL = 10 SOL pot
+- Pro gamer as referee  
+- 10% referee commission = 1 SOL
+- Top 10 split 8.5 SOL
+- Referee earns 1 SOL
+```
+
+---
+
+**Referee Mode enables a whole new economy of expert judges earning from their expertise! ⚖️💰**
+
+---
+
+**Built with ❤️ - Making decentralized gaming fair and professional!**
+

package/documentation/RETENTION_CORE_ACTION_UPDATE.md

@@ -0,0 +1,313 @@
+# 🎯 Retention Metric Update: Core Action Retention
+
+## Change Summary
+
+**Updated:** Cohort retention calculation to use **Core Action Retention** instead of generic activity.
+
+**Impact:** Retention percentages will be **lower but more meaningful** - only users who actually place bets count as "retained."
+
+---
+
+## What Changed
+
+### **Before (Generic Activity Retention):**
+
+A user was counted as "retained" if they did **ANY** activity:
+- ✅ Opened the app
+- ✅ Viewed a page  
+- ✅ Sent a chat message
+- ✅ Placed a bet
+
+**Problem:** Non-revenue-generating activity inflated retention numbers.
+
+### **After (Core Action Retention):**
+
+A user is ONLY counted as "retained" if they do **revenue-generating actions**:
+- ✅ `bet_creation_completed` - Created a sports bet
+- ✅ `join_game_completed` - Joined an existing bet
+- ✅ `billiards_create_completed` - Created a pool game
+- ✅ `billiards_join_completed` - Joined a pool game
+
+**Benefit:** Measures **true business value** and user engagement.
+
+---
+
+## Why This Matters
+
+### For a Betting/Gaming App:
+
+**Generic Activity:**
+```
+User signs up → Opens app next day → Looks around → Leaves
+❌ Counted as "retained" but generated $0 revenue
+```
+
+**Core Action:**
+```
+User signs up → Opens app next day → Looks around → Leaves
+✅ NOT counted as retained (correct!)
+
+User signs up → Opens app next day → Places a bet
+✅ Counted as retained (generates revenue!)
+```
+
+### Expected Impact on Numbers:
+
+| Metric | Before (Any Activity) | After (Bets Only) | Change |
+|--------|----------------------|-------------------|--------|
+| D1 | 45% | 30% | ↓ 15% |
+| D7 | 25% | 15% | ↓ 10% |
+| D14 | 20% | 12% | ↓ 8% |
+| D30 | 15% | 10% | ↓ 5% |
+
+**Numbers will drop, but they're now accurate!**
+
+---
+
+## Events Counted as "Retained"
+
+### **Sports Betting:**
+```sql
+'bet_creation_completed'  -- User created a bet
+'join_game_completed'     -- User joined someone else's bet
+```
+
+### **Pool/Billiards:**
+```sql
+'billiards_create_completed'  -- User created a pool game
+'billiards_join_completed'    -- User joined a pool game
+```
+
+### **NOT Counted:**
+- ❌ Page views
+- ❌ Chat messages
+- ❌ Profile updates
+- ❌ Social interactions
+- ❌ Just opening the app
+- ❌ Failed bet attempts
+
+---
+
+## Code Changes
+
+### File: `routes/analyticsRoutes.js`
+
+**Before:**
+```sql
+LEFT JOIN audit_logs al ON al.user_id = c.user_id
+  AND DATE(al.created_at) >= c.signup_date
+```
+
+**After:**
+```sql
+LEFT JOIN audit_logs al ON al.user_id = c.user_id
+  AND DATE(al.created_at) >= c.signup_date
+  -- ONLY count bet-related actions as "retained"
+  AND al.log_type IN (
+    'bet_creation_completed',
+    'join_game_completed',
+    'billiards_create_completed',
+    'billiards_join_completed'
+  )
+```
+
+**Updated Endpoints:**
+1. `GET /api/analytics/cohort-retention` (line ~921-940)
+2. `GET /api/analytics/cohort-retention/csv` (line ~1087-1106)
+
+---
+
+## Comparison Chart
+
+### Example Cohort (10 users signed up):
+
+| User | Day 1 Activity | Day 7 Activity | Old D1 | New D1 | Old D7 | New D7 |
+|------|---------------|----------------|--------|--------|--------|--------|
+| User A | Opened app | Placed bet | ✅ | ❌ | ✅ | ✅ |
+| User B | Placed bet | Opened app | ✅ | ✅ | ✅ | ❌ |
+| User C | Chat message | Nothing | ✅ | ❌ | ❌ | ❌ |
+| User D | Placed bet | Placed bet | ✅ | ✅ | ✅ | ✅ |
+| User E | Nothing | Nothing | ❌ | ❌ | ❌ | ❌ |
+
+**Old Method:**
+- D1 = 80% (4/5 did something)
+- D7 = 60% (3/5 did something)
+
+**New Method:**
+- D1 = 40% (2/5 placed bets) ✅ More accurate!
+- D7 = 40% (2/5 placed bets) ✅ Shows true engagement!
+
+---
+
+## Industry Best Practices
+
+### What Other Gaming Apps Track:
+
+**Casual Games:**
+- Core Action = "Completed a level"
+- Not: Just opened the game
+
+**Social Apps:**
+- Core Action = "Sent a message" or "Made a post"
+- Not: Just scrolled the feed
+
+**Betting Apps (like Dubs):**
+- Core Action = "Placed a bet"
+- Not: Just browsed games
+
+**This is the industry standard!**
+
+---
+
+## Benchmarks (Updated)
+
+### With Core Action Retention:
+
+| Metric | Poor | Average | Good | Excellent |
+|--------|------|---------|------|-----------|
+| **D1 Betting** | <20% | 20-30% | 30-45% | 45%+ |
+| **D7 Betting** | <10% | 10-20% | 20-30% | 30%+ |
+| **D14 Betting** | <8% | 8-15% | 15-25% | 25%+ |
+| **D30 Betting** | <5% | 5-12% | 12-20% | 20%+ |
+
+**Note:** These are lower than generic activity benchmarks, but more valuable!
+
+---
+
+## How to Interpret New Data
+
+### Scenario 1: High Activity, Low Betting
+```
+Old D1 = 60% (generic activity)
+New D1 = 25% (bets only)
+
+→ Users open the app but don't place bets
+→ ACTION: Improve onboarding, reduce friction, add incentives
+```
+
+### Scenario 2: Both Low
+```
+Old D1 = 30% (generic activity)
+New D1 = 15% (bets only)
+
+→ Users aren't even opening the app
+→ ACTION: Fix notifications, improve value prop
+```
+
+### Scenario 3: Both High
+```
+Old D1 = 70% (generic activity)
+New D1 = 55% (bets only)
+
+→ Users return AND place bets - excellent!
+→ ACTION: Keep doing what you're doing
+```
+
+---
+
+## Testing the Change
+
+### 1. Check Current Dev Data:
+
+```bash
+cd /Users/adamdahan/Developer/iheartsolana/solana-programs/dubs-server
+heroku config:get DATABASE_URL --app dubs-server-dev | \
+  xargs -I {} env DATABASE_URL={} node -e "
+    const { Pool } = require('pg');
+    const pool = new Pool({ connectionString: '{}', ssl: { rejectUnauthorized: false } });
+    
+    // Count users with ANY activity on D1
+    pool.query(\`
+      SELECT COUNT(DISTINCT user_id) FROM audit_logs 
+      WHERE DATE(created_at) = CURRENT_DATE - 1
+    \`).then(r => console.log('Any activity:', r.rows[0].count));
+    
+    // Count users with BET activity on D1
+    pool.query(\`
+      SELECT COUNT(DISTINCT user_id) FROM audit_logs 
+      WHERE DATE(created_at) = CURRENT_DATE - 1
+      AND log_type IN ('bet_creation_completed', 'join_game_completed', 
+                       'billiards_create_completed', 'billiards_join_completed')
+    \`).then(r => {
+      console.log('Bet activity:', r.rows[0].count);
+      pool.end();
+    });
+  "
+```
+
+### 2. Compare Before/After:
+
+Deploy and compare cohort metrics:
+- Old system: Higher percentages
+- New system: Lower but more accurate percentages
+
+---
+
+## FAQ
+
+### Q: Why did my retention numbers drop?
+**A:** They didn't drop - they're now **accurate**. Before, we were counting "window shoppers" as engaged users.
+
+### Q: What if I want to see both metrics?
+**A:** You can add a toggle in the dashboard:
+- "Core Action Retention" (bets only) - Default
+- "Activation Retention" (any activity) - Optional view
+
+### Q: Should I track other actions too (chat, social)?
+**A:** Those are important, but for **business metrics** (retention, LTV, ROI), bet actions matter most. You can track engagement separately.
+
+### Q: What about users who onboard but never bet?
+**A:** They'll show up in signups but 0% retention. This is correct - they're not retained users if they don't use the core feature!
+
+---
+
+## Migration Notes
+
+### No Database Changes Needed ✅
+- Only the query logic changed
+- All data is already in `audit_logs`
+- Backward compatible
+
+### What to Tell Your Community Manager:
+
+> "We updated retention metrics to only count users who **actually place bets**, not just open the app. Numbers may appear lower, but they're now accurate and align with industry standards. This helps us focus on real user engagement and revenue."
+
+### What to Tell Stakeholders:
+
+> "We shifted from vanity metrics (any activity) to actionable metrics (revenue-generating actions). This gives us better insights into product-market fit and helps prioritize features that drive actual usage."
+
+---
+
+## Deployment
+
+```bash
+# Backend
+cd /Users/adamdahan/Developer/iheartsolana/solana-programs/dubs-server
+git add routes/analyticsRoutes.js
+git commit -m "feat: Update cohort retention to core action (bets only)
+
+- Change retention definition from any activity to bet placement
+- Only count: bet_creation_completed, join_game_completed, billiards_*_completed
+- Aligns with industry best practices for gaming apps
+- Provides more accurate business metrics"
+git push heroku-dev main
+```
+
+---
+
+## Impact Summary
+
+| Aspect | Change |
+|--------|--------|
+| **Accuracy** | ↑ Much more accurate |
+| **Percentages** | ↓ Will be lower (but real) |
+| **Business Value** | ↑ Directly tied to revenue |
+| **Actionability** | ↑ Can optimize for bets, not just opens |
+| **Industry Alignment** | ✅ Matches gaming app standards |
+
+---
+
+**Status:** ✅ IMPLEMENTED  
+**Recommended By:** Product best practices + User feedback  
+**Breaking Change:** No (only changes calculation, not data structure)
+