dubs-server 1.0.0

package/documentation/LATEST_PRODUCTION_SETUP.md

@@ -0,0 +1,387 @@
+# 🚀 DUBS Server Production Setup
+
+**Created:** December 14, 2025  
+**Last Updated:** December 14, 2025
+
+This document contains critical operational information for the `dubs-server-prod` Heroku application.
+
+---
+
+## 📋 Quick Reference
+
+| Field | Value |
+|-------|-------|
+| **App Name** | `dubs-server-prod` |
+| **Production URL** | https://dubs-server-prod-9c91d3f01199.herokuapp.com/ |
+| **Git Remote** | `heroku-prod` |
+| **Team** | dubs |
+| **Region** | US |
+| **Stack** | heroku-24 |
+
+---
+
+## 🖥️ Infrastructure
+
+### Dynos (Compute)
+
+| Dyno | Type | Size | Purpose |
+|------|------|------|---------|
+| `web.1` | Standard-1X | 512MB RAM | Express.js API server |
+| `oracle.1` | Standard-1X | 512MB RAM | Automatic game resolution oracle |
+
+### Database
+
+| Field | Value |
+|-------|-------|
+| **Addon** | `postgresql-regular-65857` |
+| **Plan** | Standard-0 |
+| **Cost** | $50/month |
+| **Storage** | 10GB |
+| **Max Connections** | 200 |
+| **Region** | US East (AWS) |
+
+---
+
+## 🗄️ Database Access
+
+### Connect via Heroku CLI (Recommended)
+
+```bash
+# Interactive psql session
+heroku pg:psql --app dubs-server-prod
+
+# Run a single query
+heroku pg:psql --app dubs-server-prod -c "SELECT COUNT(*) FROM users;"
+
+# Run a SQL file
+heroku pg:psql --app dubs-server-prod < scripts/some-migration.sql
+```
+
+### Get Connection String
+
+```bash
+# View DATABASE_URL (contains credentials)
+heroku config:get DATABASE_URL --app dubs-server-prod
+```
+
+### Connect with External Tools (pgAdmin, DBeaver, TablePlus)
+
+```bash
+# Get connection info
+heroku pg:credentials:url --app dubs-server-prod
+```
+
+The output will give you:
+- **Host**: `ec2-XX-XXX-XXX-XXX.compute-1.amazonaws.com`
+- **Port**: `5432`
+- **Database**: `d6jpka002e1ept`
+- **User**: `uddg5sp8vh4l8g`
+- **Password**: (shown in output)
+
+⚠️ **Important:** Heroku Postgres requires SSL. Set `sslmode=require` in your connection.
+
+### Database Backup & Restore
+
+```bash
+# Create manual backup
+heroku pg:backups:capture --app dubs-server-prod
+
+# List backups
+heroku pg:backups --app dubs-server-prod
+
+# Download latest backup
+heroku pg:backups:download --app dubs-server-prod
+
+# Restore from backup
+heroku pg:backups:restore b001 DATABASE_URL --app dubs-server-prod
+```
+
+### Database Maintenance
+
+```bash
+# View database info
+heroku pg:info --app dubs-server-prod
+
+# View active connections
+heroku pg:psql --app dubs-server-prod -c "SELECT * FROM pg_stat_activity WHERE datname = current_database();"
+
+# Kill idle connections (if needed)
+heroku pg:killall --app dubs-server-prod
+```
+
+---
+
+## ⚙️ Configuration Variables
+
+### Solana / Blockchain
+
+| Variable | Value | Description |
+|----------|-------|-------------|
+| `PROGRAM_ID` | `85wJGp9uc8w2FeKX9CEHsudTo1UVCrmuRFy37oCcaoG1` | Mainnet program ID |
+| `JACKPOT_PROGRAM_ID` | `85wJGp9uc8w2FeKX9CEHsudTo1UVCrmuRFy37oCcaoG1` | Same as PROGRAM_ID |
+| `SOLANA_NETWORK` | `https://api.mainnet-beta.solana.com` | Mainnet RPC endpoint |
+| `ORACLE_WALLET_JSON` | `[...]` | Oracle keypair (JSON array) |
+| `KEEPER_PRIVATE_KEY` | `[...]` | Keeper keypair (JSON array) |
+
+### API Endpoints
+
+| Variable | Value |
+|----------|-------|
+| `API_BASE_URL` | `https://dubs-server-prod-9c91d3f01199.herokuapp.com` |
+| `DUBS_SERVER_URL` | `https://dubs-server-prod-9c91d3f01199.herokuapp.com` |
+| `LIVE_SCORES_API_URL` | `https://dubs-api-prod-9e38ab6733f8.herokuapp.com` |
+| `DUBS_GAMES_API_URL` | `https://dubs-games-api-prod-e41f330fdacc.herokuapp.com` |
+| `TELEGRAM_BOT_URL` | `https://dubs-telegram-bot-eb6ad9ec87b7.herokuapp.com` |
+
+### Timing Configuration
+
+| Variable | Value | Description |
+|----------|-------|-------------|
+| `ORACLE_CHECK_INTERVAL` | `60000` | Check games every 60 seconds |
+| `LIVE_GAME_DISCOVERY_INTERVAL` | `60000` | Discover new games every 60 seconds |
+| `LIVE_GAME_POLL_INTERVAL` | `5000` | Poll live scores every 5 seconds |
+| `LIVE_GAME_STATS_INTERVAL` | `30000` | Update stats every 30 seconds |
+
+### View All Config
+
+```bash
+heroku config --app dubs-server-prod
+```
+
+### Update Config
+
+```bash
+# Set single variable
+heroku config:set VARIABLE_NAME=value --app dubs-server-prod
+
+# Set multiple variables
+heroku config:set VAR1=value1 VAR2=value2 --app dubs-server-prod
+```
+
+---
+
+## 🚀 Deployment
+
+### Deploy from Local
+
+```bash
+cd /path/to/dubs-server
+
+# Deploy main branch to production
+git push heroku-prod main
+
+# Deploy specific branch
+git push heroku-prod feature-branch:main
+```
+
+### Rollback
+
+```bash
+# View releases
+heroku releases --app dubs-server-prod
+
+# Rollback to previous release
+heroku rollback --app dubs-server-prod
+
+# Rollback to specific version
+heroku rollback v10 --app dubs-server-prod
+```
+
+---
+
+## 📊 Monitoring & Logs
+
+### View Logs
+
+```bash
+# Tail all logs
+heroku logs --tail --app dubs-server-prod
+
+# View specific dyno logs
+heroku logs --tail --dyno web.1 --app dubs-server-prod
+heroku logs --tail --dyno oracle.1 --app dubs-server-prod
+
+# View last N lines
+heroku logs -n 500 --app dubs-server-prod
+
+# Filter by source
+heroku logs --source app --app dubs-server-prod
+heroku logs --source heroku --app dubs-server-prod
+```
+
+### Check Dyno Status
+
+```bash
+# View running dynos
+heroku ps --app dubs-server-prod
+
+# Restart all dynos
+heroku restart --app dubs-server-prod
+
+# Restart specific dyno
+heroku restart web.1 --app dubs-server-prod
+heroku restart oracle.1 --app dubs-server-prod
+```
+
+### Database Monitoring
+
+```bash
+# View database metrics
+heroku pg:info --app dubs-server-prod
+
+# View slow queries (requires pg:diagnose)
+heroku pg:diagnose --app dubs-server-prod
+
+# View table sizes
+heroku pg:psql --app dubs-server-prod -c "
+SELECT 
+  schemaname,
+  tablename,
+  pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) as size
+FROM pg_tables 
+WHERE schemaname = 'public' 
+ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;
+"
+```
+
+---
+
+## 🔐 Security Notes
+
+### Sensitive Variables
+
+The following variables contain sensitive data - **NEVER commit to git**:
+
+- `DATABASE_URL` - Database connection string with password
+- `JWT_SECRET` - Token signing secret
+- `ORACLE_WALLET_JSON` - Oracle private key
+- `KEEPER_PRIVATE_KEY` - Keeper private key
+- `TELEGRAM_BOT_TOKEN` - Bot authentication token
+- `AWS_SECRET_ACCESS_KEY` - AWS S3 access
+
+### Oracle Wallet
+
+The oracle wallet is stored in `ORACLE_WALLET_JSON` as a JSON array (Solana keypair format).
+
+**Public Key:** `DU4CHEHUJ2EeezAXyfyi8vLB7dmXKq41myKnA5DZ9Mru`
+
+This wallet is hardcoded in the Solana program and receives 0.2% oracle fees.
+
+---
+
+## 🔧 Maintenance Tasks
+
+### Run Database Migrations
+
+```bash
+# Run complete schema setup
+heroku pg:psql --app dubs-server-prod < scripts/setup-complete-database.sql
+
+# Run specific migration
+heroku pg:psql --app dubs-server-prod < scripts/add-preferred-currency.sql
+```
+
+### Scale Dynos
+
+```bash
+# Scale up (more dynos or bigger size)
+heroku ps:scale web=2:standard-2x --app dubs-server-prod
+
+# Scale down
+heroku ps:scale web=1:standard-1x --app dubs-server-prod
+
+# Turn off oracle (if needed)
+heroku ps:scale oracle=0 --app dubs-server-prod
+```
+
+### Run One-Off Commands
+
+```bash
+# Run a script
+heroku run node scripts/some-script.js --app dubs-server-prod
+
+# Open a shell
+heroku run bash --app dubs-server-prod
+```
+
+---
+
+## 🚨 Troubleshooting
+
+### App Not Responding
+
+1. Check dyno status: `heroku ps --app dubs-server-prod`
+2. Check logs: `heroku logs --tail --app dubs-server-prod`
+3. Restart: `heroku restart --app dubs-server-prod`
+
+### Database Connection Issues
+
+1. Check connection count: `heroku pg:info --app dubs-server-prod`
+2. Kill idle connections: `heroku pg:killall --app dubs-server-prod`
+3. Restart app: `heroku restart --app dubs-server-prod`
+
+### Oracle Not Resolving Games
+
+1. Check oracle logs: `heroku logs --tail --dyno oracle.1 --app dubs-server-prod`
+2. Verify `ORACLE_WALLET_JSON` is set correctly
+3. Check Solana RPC endpoint is responsive
+4. Verify oracle wallet has SOL for transaction fees
+
+### High Memory Usage
+
+1. Check metrics: `heroku ps --app dubs-server-prod`
+2. Scale to larger dyno: `heroku ps:scale web=1:standard-2x --app dubs-server-prod`
+
+---
+
+## 💰 Cost Summary
+
+| Resource | Monthly Cost |
+|----------|--------------|
+| Postgres Standard-0 | $50 |
+| Standard-1X Dyno (web) | ~$25 |
+| Standard-1X Dyno (oracle) | ~$25 |
+| **Total Estimated** | **~$100/month** |
+
+---
+
+## 🔗 Related Resources
+
+- **Mainnet Deployment Docs:** `../dubs/docs/LATEST_MAINNET_DEPLOYMENT.md`
+- **Program ID:** `85wJGp9uc8w2FeKX9CEHsudTo1UVCrmuRFy37oCcaoG1`
+- **Solana Explorer:** https://explorer.solana.com/address/85wJGp9uc8w2FeKX9CEHsudTo1UVCrmuRFy37oCcaoG1
+
+---
+
+## 📞 Quick Commands Cheat Sheet
+
+```bash
+# Logs
+heroku logs --tail --app dubs-server-prod
+
+# Restart
+heroku restart --app dubs-server-prod
+
+# Deploy
+git push heroku-prod main
+
+# Database shell
+heroku pg:psql --app dubs-server-prod
+
+# Config
+heroku config --app dubs-server-prod
+
+# Status
+heroku ps --app dubs-server-prod
+
+# Open in browser
+heroku open --app dubs-server-prod
+```
+
+---
+
+**Document maintained by:** Dubs Team  
+**For questions:** Check Heroku dashboard or logs first
+
+
+

package/documentation/LOCAL_VOTING_TEST.md

@@ -0,0 +1,279 @@
+# 🧪 LOCAL VOTING TEST - COMPLETE GUIDE
+
+## ✅ **Local Environment Running:**
+
+```
+✅ solana-test-validator → localhost:8899
+✅ Dubs program (with voting) → Deployed locally
+✅ dubs-server → http://localhost:3001
+```
+
+---
+
+## 🎮 **Complete Test Flow**
+
+### **Step 1: Create Game with Voting**
+```bash
+POST http://localhost:3001/api/v1/demo/game/create
+
+{
+  "player": "creator",
+  "buyIn": 0.5,
+  "maxPlayers": 3,
+  "operatorFee": 10
+}
+
+Response:
+{
+  "success": true,
+  "gameId": "uuid-here",  ← SAVE THIS!
+  "transaction": "signature",
+  "gameAddress": "PDA"
+}
+```
+
+---
+
+### **Step 2: Players Join**
+```bash
+# Alice joins
+POST http://localhost:3001/api/v1/demo/game/join
+{
+  "player": "alice",
+  "gameId": "SAVED_GAME_ID"
+}
+
+# Bob joins
+POST http://localhost:3001/api/v1/demo/game/join
+{
+  "player": "bob",
+  "gameId": "SAVED_GAME_ID"
+}
+```
+
+---
+
+### **Step 3: Check Game State**
+```bash
+GET http://localhost:3001/api/v1/demo/game/SAVED_GAME_ID
+
+Response shows:
+{
+  "game": {
+    "players": [
+      "CreatorAddress...",
+      "AliceAddress...",
+      "BobAddress..."
+    ],
+    "totalPot": 1.5,
+    "votes": [],
+    "votingEnabled": true  ← Confirmed!
+  }
+}
+```
+
+**Copy the 3 player addresses from response!**
+
+---
+
+### **Step 4: Cast Votes** 🗳️
+```bash
+# Creator votes for Alice
+POST http://localhost:3001/api/v1/demo/vote/cast
+{
+  "player": "creator",
+  "gameId": "SAVED_GAME_ID",
+  "votedFor": "ALICE_ADDRESS_FROM_GAME_INFO"
+}
+
+# Alice votes for Alice (vote for herself!)
+POST http://localhost:3001/api/v1/demo/vote/cast
+{
+  "player": "alice",
+  "gameId": "SAVED_GAME_ID",
+  "votedFor": "ALICE_ADDRESS_FROM_GAME_INFO"
+}
+
+Response:
+{
+  "success": true,
+  "message": "alice voted for...",
+  "votesCount": 2,
+  "votingProgress": "2/3 votes"  ← Majority reached!
+}
+```
+
+---
+
+### **Step 5: Check Voting Results**
+```bash
+GET http://localhost:3001/api/v1/demo/game/SAVED_GAME_ID
+
+Response:
+{
+  "game": {
+    "votes": [
+      {"voter": "Creator...", "votedFor": "Alice..."},
+      {"voter": "Alice...", "votedFor": "Alice..."}
+    ],
+    "votingEnabled": true
+  }
+}
+
+Alice has 2 votes! (Majority reached with 2/3 players!)
+```
+
+---
+
+### **Step 6: Distribute by Vote** 🏆
+```bash
+POST http://localhost:3001/api/v1/demo/vote/distribute
+{
+  "gameId": "SAVED_GAME_ID"
+}
+
+Response:
+{
+  "success": true,
+  "message": "Winnings distributed by vote to 1 winners",
+  "transaction": "signature",
+  "winners": ["AliceAddress..."],
+  "voteCounts": {
+    "CreatorAddress": 0,
+    "AliceAddress": 2,  ← WINNER!
+    "BobAddress": 0
+  },
+  "winnersCount": 1
+}
+```
+
+**🎉 ALICE WINS BY DEMOCRATIC VOTE!**
+
+---
+
+### **Step 7: Verify Results**
+```bash
+GET http://localhost:3001/api/v1/demo/wallets
+
+Response shows:
+- Creator: balance (paid buy-in, didn't win)
+- Alice: balance (WON! Prize pool added!)
+- Bob: balance (paid buy-in, didn't win)
+- Operator: balance (received 10% fee!)
+```
+
+---
+
+## 🎯 **Testing Scenarios**
+
+### **Scenario 1: Clear Winner**
+```
+3 players vote:
+- Creator votes for Alice
+- Alice votes for Alice  
+- Bob votes for Alice
+→ Alice gets 100% (all 3 voted for her!)
+```
+
+### **Scenario 2: Tie (Equal Split)**
+```
+3 players vote:
+- Creator votes for Alice
+- Alice votes for Bob
+- Bob votes for Creator
+→ All tied at 1 vote each!
+→ Prize split 33/33/33
+```
+
+### **Scenario 3: Majority (2/3 votes)**
+```
+Only 2 players vote:
+- Creator votes for Alice
+- Alice votes for Alice
+→ Majority reached (2/3)!
+→ Alice wins!
+→ Bob never voted (doesn't matter!)
+```
+
+---
+
+## 🗳️ **Demo Voting Endpoints**
+
+### **NEW Demo Endpoints:**
+```
+POST /api/v1/demo/vote/cast
+Body: {
+  player: "alice",
+  gameId: "uuid",
+  votedFor: "player-address"
+}
+
+POST /api/v1/demo/vote/distribute
+Body: {
+  gameId: "uuid"
+}
+```
+
+---
+
+## 📊 **Test Checklist**
+
+- [ ] Start local validator
+- [ ] Deploy program locally
+- [ ] Start dubs-server (localhost:3001)
+- [ ] Create game with voting
+- [ ] 3 players join
+- [ ] Get player addresses
+- [ ] Cast votes (2-3 players)
+- [ ] Check vote counts
+- [ ] Distribute by vote
+- [ ] Verify balances
+- [ ] Test tie scenario
+- [ ] Test majority scenario
+
+---
+
+## 🚀 **Quick Commands**
+
+### **Start Everything:**
+```bash
+# Terminal 1: Validator
+solana-test-validator --reset
+
+# Terminal 2: Deploy & Start Server
+cd dubs
+solana program deploy target/deploy/hello_world.so --url localhost
+
+cd ../dubs-server
+node server.js
+```
+
+### **Test with Curl:**
+```bash
+# Create 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,"operatorFee":10}'
+
+# Cast vote
+curl -X POST http://localhost:3001/api/v1/demo/vote/cast \
+  -H "Content-Type: application/json" \
+  -d '{"player":"alice","gameId":"GAME_ID","votedFor":"ALICE_ADDRESS"}'
+
+# Distribute by vote
+curl -X POST http://localhost:3001/api/v1/demo/vote/distribute \
+  -H "Content-Type: application/json" \
+  -d '{"gameId":"GAME_ID"}'
+```
+
+---
+
+## 🎉 **NO HEROKU NEEDED!**
+
+**Test the complete democratic voting system RIGHT NOW on your local machine!**
+
+**Everything works offline! No waiting for outage! 🚀**
+
+---
+
+**Ready to test? Fire up Postman and point it to `localhost:3001`! 🎮🗳️**