dubs-server 1.0.0

package/documentation/DEMO_API_CURL_COMMANDS.md

@@ -0,0 +1,656 @@
+# 🎮 Dubs Demo API - Complete Curl Reference
+
+**All commands ready to copy & paste!** No Postman needed!
+
+---
+
+## 🌐 **Server Info**
+
+```bash
+# Local
+http://localhost:3001
+
+# Devnet (when Heroku is back)
+https://dubs-server-dev-55d1fba09a97.herokuapp.com
+```
+
+---
+
+## 📋 **All Demo Endpoints**
+
+### **1. Health Check**
+
+```bash
+curl http://localhost:3001/health
+```
+
+**Response:**
+```json
+{"status":"ok","message":"🎮 Dubs API Server is running!"}
+```
+
+---
+
+### **2. List All Demo Wallets**
+
+```bash
+curl http://localhost:3001/api/v1/demo/wallets | python3 -m json.tool
+```
+
+**Response:**
+```json
+{
+  "wallets": [
+    {
+      "name": "creator",
+      "address": "2rHd6Fe7KzbUAJwH56iVSmAcRy4X9rdqutS2hzc1PM4d",
+      "balance": "2.0000"
+    },
+    {
+      "name": "alice",
+      "address": "GvE3wSwh2HDpER7x3WXmipqH8Q9zDmHiAc8Qc8U8jTTc",
+      "balance": "0.0000"
+    }
+  ]
+}
+```
+
+---
+
+### **3. Airdrop SOL to Player**
+
+```bash
+# Airdrop to alice
+curl -X POST http://localhost:3001/api/v1/demo/airdrop \
+  -H "Content-Type: application/json" \
+  -d '{"player":"alice"}' \
+  | python3 -m json.tool
+
+# Airdrop to bob
+curl -X POST http://localhost:3001/api/v1/demo/airdrop \
+  -H "Content-Type: application/json" \
+  -d '{"player":"bob"}' \
+  | python3 -m json.tool
+
+# Airdrop to charlie
+curl -X POST http://localhost:3001/api/v1/demo/airdrop \
+  -H "Content-Type: application/json" \
+  -d '{"player":"charlie"}' \
+  | python3 -m json.tool
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Airdropped 2 SOL to alice",
+  "address": "GvE3wSwh2HDpER7x3WXmipqH8Q9zDmHiAc8Qc8U8jTTc",
+  "balance": "2.0000"
+}
+```
+
+---
+
+### **4. Create Game**
+
+```bash
+# Standard game (no voting)
+curl -X POST http://localhost:3001/api/v1/demo/game/create \
+  -H "Content-Type: application/json" \
+  -d '{
+    "player": "creator",
+    "buyIn": 0.5,
+    "maxPlayers": 4,
+    "operatorFee": 10,
+    "operatorPlayer": "jelli"
+  }' \
+  | python3 -m json.tool
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "gameId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "message": "Game created by creator, operator: jelli",
+  "transaction": "signature...",
+  "gameAddress": "PDA..."
+}
+```
+
+**💾 SAVE THE GAME ID!**
+
+---
+
+### **5. Get Game Info**
+
+```bash
+# Replace GAME_ID with the UUID from create response
+curl http://localhost:3001/api/v1/demo/game/GAME_ID | python3 -m json.tool
+```
+
+**Response:**
+```json
+{
+  "exists": true,
+  "game": {
+    "gameId": 12345,
+    "authority": "2rHd6Fe7...",
+    "buyIn": 0.5,
+    "maxPlayers": 4,
+    "players": ["2rHd6Fe7..."],
+    "totalPot": 0.5,
+    "isActive": true,
+    "votes": [],
+    "votingEnabled": false
+  },
+  "calculated": {
+    "operatorFeeAmount": "0.0500",
+    "prizePool": "0.4500"
+  }
+}
+```
+
+---
+
+### **6. Players Join Game**
+
+```bash
+# Alice joins
+curl -X POST http://localhost:3001/api/v1/demo/game/join \
+  -H "Content-Type: application/json" \
+  -d '{
+    "player": "alice",
+    "gameId": "PASTE_GAME_ID_HERE"
+  }' \
+  | python3 -m json.tool
+
+# Bob joins
+curl -X POST http://localhost:3001/api/v1/demo/game/join \
+  -H "Content-Type: application/json" \
+  -d '{
+    "player": "bob",
+    "gameId": "PASTE_GAME_ID_HERE"
+  }' \
+  | python3 -m json.tool
+
+# Charlie joins
+curl -X POST http://localhost:3001/api/v1/demo/game/join \
+  -H "Content-Type: application/json" \
+  -d '{
+    "player": "charlie",
+    "gameId": "PASTE_GAME_ID_HERE"
+  }' \
+  | python3 -m json.tool
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "alice joined game",
+  "transaction": "signature...",
+  "playersCount": 2
+}
+```
+
+---
+
+### **7. Cast Votes** 🗳️ **NEW!**
+
+```bash
+# Creator votes for Alice
+curl -X POST http://localhost:3001/api/v1/demo/vote/cast \
+  -H "Content-Type: application/json" \
+  -d '{
+    "player": "creator",
+    "gameId": "PASTE_GAME_ID",
+    "votedFor": "GvE3wSwh2HDpER7x3WXmipqH8Q9zDmHiAc8Qc8U8jTTc"
+  }' \
+  | python3 -m json.tool
+
+# Alice votes for herself
+curl -X POST http://localhost:3001/api/v1/demo/vote/cast \
+  -H "Content-Type: application/json" \
+  -d '{
+    "player": "alice",
+    "gameId": "PASTE_GAME_ID",
+    "votedFor": "GvE3wSwh2HDpER7x3WXmipqH8Q9zDmHiAc8Qc8U8jTTc"
+  }' \
+  | python3 -m json.tool
+
+# Bob votes for Charlie
+curl -X POST http://localhost:3001/api/v1/demo/vote/cast \
+  -H "Content-Type: application/json" \
+  -d '{
+    "player": "bob",
+    "gameId": "PASTE_GAME_ID",
+    "votedFor": "B6ZDc5TA31nLeffsFffvsPx6EUbuCeDRjoo9KgcUAR5E"
+  }' \
+  | python3 -m json.tool
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "alice voted for GvE3wSwh...",
+  "transaction": "signature...",
+  "votesCount": 2,
+  "votingProgress": "2/3 votes"
+}
+```
+
+---
+
+### **8. Distribute by Vote** 🗳️ **NEW!**
+
+```bash
+curl -X POST http://localhost:3001/api/v1/demo/vote/distribute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "gameId": "PASTE_GAME_ID"
+  }' \
+  | python3 -m json.tool
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Winnings distributed by vote to 1 winners",
+  "transaction": "signature...",
+  "winners": ["GvE3wSwh2HDpER7x3WXmipqH8Q9zDmHiAc8Qc8U8jTTc"],
+  "voteCounts": {
+    "2rHd6Fe7...": 0,
+    "GvE3wSwh2HDpER7x3WXmipqH8Q9zDmHiAc8Qc8U8jTTc": 2,
+    "B6ZDc5TA31nLeff...": 1
+  },
+  "winnersCount": 1
+}
+```
+
+---
+
+### **9. Distribute Manually (Creator Chooses)**
+
+```bash
+# Get player addresses from game info first!
+curl -X POST http://localhost:3001/api/v1/demo/game/distribute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "gameId": "PASTE_GAME_ID",
+    "winners": [
+      "GvE3wSwh2HDpER7x3WXmipqH8Q9zDmHiAc8Qc8U8jTTc",
+      "AuskVDhGKzZ9xWJaY5RKWzBZzeGuEYZ6mZXCDeTQCJcw"
+    ]
+  }' \
+  | python3 -m json.tool
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Winnings distributed to 2 winners",
+  "transaction": "signature...",
+  "operatorFee": "0.1500",
+  "prizePool": "1.3500",
+  "winnersCount": 2,
+  "winnerAddresses": ["GvE3wSwh...", "AuskVDhG..."]
+}
+```
+
+---
+
+## 🎯 **Complete Test Flow (Copy All!)**
+
+### **Democratic Voting Test:**
+
+```bash
+# Step 1: Create game
+GAME_ID=$(curl -s -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,"operatorPlayer":"jelli"}' \
+  | python3 -c "import sys, json; print(json.load(sys.stdin)['gameId'])")
+
+echo "✅ Game created: $GAME_ID"
+
+# Step 2: Players join
+echo "👥 Alice joining..."
+curl -s -X POST http://localhost:3001/api/v1/demo/game/join \
+  -H "Content-Type: application/json" \
+  -d "{\"player\":\"alice\",\"gameId\":\"$GAME_ID\"}" \
+  | python3 -m json.tool
+
+echo "👥 Bob joining..."
+curl -s -X POST http://localhost:3001/api/v1/demo/game/join \
+  -H "Content-Type: application/json" \
+  -d "{\"player\":\"bob\",\"gameId\":\"$GAME_ID\"}" \
+  | python3 -m json.tool
+
+# Step 3: Get game info and player addresses
+echo "📊 Game Info:"
+curl -s http://localhost:3001/api/v1/demo/game/$GAME_ID | python3 -m json.tool
+
+# Step 4: Cast votes (COPY ALICE ADDRESS FROM ABOVE!)
+ALICE_ADDR="GvE3wSwh2HDpER7x3WXmipqH8Q9zDmHiAc8Qc8U8jTTc"
+
+echo "🗳️  Creator votes for Alice..."
+curl -s -X POST http://localhost:3001/api/v1/demo/vote/cast \
+  -H "Content-Type: application/json" \
+  -d "{\"player\":\"creator\",\"gameId\":\"$GAME_ID\",\"votedFor\":\"$ALICE_ADDR\"}" \
+  | python3 -m json.tool
+
+echo "🗳️  Alice votes for herself..."
+curl -s -X POST http://localhost:3001/api/v1/demo/vote/cast \
+  -H "Content-Type: application/json" \
+  -d "{\"player\":\"alice\",\"gameId\":\"$GAME_ID\",\"votedFor\":\"$ALICE_ADDR\"}" \
+  | python3 -m json.tool
+
+# Step 5: Distribute by vote (2/3 = majority!)
+echo "🏆 Distributing by vote..."
+curl -s -X POST http://localhost:3001/api/v1/demo/vote/distribute \
+  -H "Content-Type: application/json" \
+  -d "{\"gameId\":\"$GAME_ID\"}" \
+  | python3 -m json.tool
+
+# Step 6: Check final balances
+echo "💰 Final balances:"
+curl -s http://localhost:3001/api/v1/demo/wallets | python3 -m json.tool
+```
+
+---
+
+## 📝 **Quick Reference (Single Commands)**
+
+### **List Wallets:**
+```bash
+curl http://localhost:3001/api/v1/demo/wallets | python3 -m json.tool
+```
+
+### **Airdrop:**
+```bash
+curl -X POST http://localhost:3001/api/v1/demo/airdrop \
+  -H "Content-Type: application/json" \
+  -d '{"player":"alice"}' | python3 -m json.tool
+```
+
+### **Create Game:**
+```bash
+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}' \
+  | python3 -m json.tool
+```
+
+### **Join Game:**
+```bash
+curl -X POST http://localhost:3001/api/v1/demo/game/join \
+  -H "Content-Type: application/json" \
+  -d '{"player":"alice","gameId":"YOUR_GAME_ID"}' \
+  | python3 -m json.tool
+```
+
+### **Get Game:**
+```bash
+curl http://localhost:3001/api/v1/demo/game/YOUR_GAME_ID | python3 -m json.tool
+```
+
+### **Cast Vote:** 🗳️
+```bash
+curl -X POST http://localhost:3001/api/v1/demo/vote/cast \
+  -H "Content-Type: application/json" \
+  -d '{"player":"alice","gameId":"YOUR_GAME_ID","votedFor":"PLAYER_ADDRESS"}' \
+  | python3 -m json.tool
+```
+
+### **Distribute by Vote:** 🗳️
+```bash
+curl -X POST http://localhost:3001/api/v1/demo/vote/distribute \
+  -H "Content-Type: application/json" \
+  -d '{"gameId":"YOUR_GAME_ID"}' \
+  | python3 -m json.tool
+```
+
+### **Distribute Manually:**
+```bash
+curl -X POST http://localhost:3001/api/v1/demo/game/distribute \
+  -H "Content-Type: application/json" \
+  -d '{"gameId":"YOUR_GAME_ID","winners":["ADDR1","ADDR2"]}' \
+  | python3 -m json.tool
+```
+
+---
+
+## 🎮 **Complete Game Scenarios**
+
+### **Scenario 1: Alice Wins by Vote (2/3 Majority)**
+
+```bash
+# Setup
+GAME_ID=$(curl -s -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,"operatorPlayer":"jelli"}' \
+  | python3 -c "import sys, json; print(json.load(sys.stdin)['gameId'])")
+echo "Game ID: $GAME_ID"
+
+# Players join
+curl -X POST http://localhost:3001/api/v1/demo/game/join \
+  -H "Content-Type: application/json" \
+  -d "{\"player\":\"alice\",\"gameId\":\"$GAME_ID\"}"
+
+curl -X POST http://localhost:3001/api/v1/demo/game/join \
+  -H "Content-Type: application/json" \
+  -d "{\"player\":\"bob\",\"gameId\":\"$GAME_ID\"}"
+
+# Get player addresses
+echo "Getting player addresses..."
+curl -s http://localhost:3001/api/v1/demo/game/$GAME_ID | python3 -m json.tool
+
+# COPY ALICE ADDRESS, then:
+ALICE="GvE3wSwh2HDpER7x3WXmipqH8Q9zDmHiAc8Qc8U8jTTc"
+
+# Creator votes for Alice
+curl -X POST http://localhost:3001/api/v1/demo/vote/cast \
+  -H "Content-Type: application/json" \
+  -d "{\"player\":\"creator\",\"gameId\":\"$GAME_ID\",\"votedFor\":\"$ALICE\"}"
+
+# Alice votes for herself (2/3 majority!)
+curl -X POST http://localhost:3001/api/v1/demo/vote/cast \
+  -H "Content-Type: application/json" \
+  -d "{\"player\":\"alice\",\"gameId\":\"$GAME_ID\",\"votedFor\":\"$ALICE\"}"
+
+# Distribute (Alice wins!)
+curl -X POST http://localhost:3001/api/v1/demo/vote/distribute \
+  -H "Content-Type: application/json" \
+  -d "{\"gameId\":\"$GAME_ID\"}" \
+  | python3 -m json.tool
+
+# Check balances
+curl http://localhost:3001/api/v1/demo/wallets | python3 -m json.tool
+```
+
+---
+
+### **Scenario 2: 3-Way Tie (Equal Split)**
+
+```bash
+# After creating game and 3 players joining...
+
+# Get all 3 addresses first
+CREATOR="2rHd6Fe7KzbUAJwH56iVSmAcRy4X9rdqutS2hzc1PM4d"
+ALICE="GvE3wSwh2HDpER7x3WXmipqH8Q9zDmHiAc8Qc8U8jTTc"
+BOB="AuskVDhGKzZ9xWJaY5RKWzBZzeGuEYZ6mZXCDeTQCJcw"
+
+# Creator votes for Alice
+curl -X POST http://localhost:3001/api/v1/demo/vote/cast \
+  -H "Content-Type: application/json" \
+  -d "{\"player\":\"creator\",\"gameId\":\"$GAME_ID\",\"votedFor\":\"$ALICE\"}"
+
+# Alice votes for Bob
+curl -X POST http://localhost:3001/api/v1/demo/vote/cast \
+  -H "Content-Type: application/json" \
+  -d "{\"player\":\"alice\",\"gameId\":\"$GAME_ID\",\"votedFor\":\"$BOB\"}"
+
+# Bob votes for Creator
+curl -X POST http://localhost:3001/api/v1/demo/vote/cast \
+  -H "Content-Type: application/json" \
+  -d "{\"player\":\"bob\",\"gameId\":\"$GAME_ID\",\"votedFor\":\"$CREATOR\"}"
+
+# Distribute (All 3 tied at 1 vote each = equal split!)
+curl -X POST http://localhost:3001/api/v1/demo/vote/distribute \
+  -H "Content-Type: application/json" \
+  -d "{\"gameId\":\"$GAME_ID\"}" \
+  | python3 -m json.tool
+```
+
+**Result: All 3 players get 33% each!**
+
+---
+
+### **Scenario 3: 2-Way Tie**
+
+```bash
+# After 4 players joined...
+
+# 2 vote for Alice, 2 vote for Bob
+# Result: 50/50 split between Alice and Bob
+```
+
+---
+
+## 🔧 **Helper Commands**
+
+### **Save Game ID:**
+```bash
+# After creating game, extract gameId
+GAME_ID=$(curl -s -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}' \
+  | python3 -c "import sys, json; print(json.load(sys.stdin)['gameId'])")
+
+echo $GAME_ID
+```
+
+### **Get Player Addresses:**
+```bash
+# Extract just the players array
+curl -s http://localhost:3001/api/v1/demo/game/$GAME_ID \
+  | python3 -c "import sys, json; data=json.load(sys.stdin); print('\n'.join(data['game']['players']))"
+```
+
+### **Check Vote Counts:**
+```bash
+# See who voted for whom
+curl -s http://localhost:3001/api/v1/demo/game/$GAME_ID \
+  | python3 -c "import sys, json; data=json.load(sys.stdin); [print(f\"{v['voter'][:8]}... → {v['votedFor'][:8]}...\") for v in data['game']['votes']]"
+```
+
+---
+
+## 🗳️ **Demo Voting Endpoints**
+
+### **Cast Vote:**
+```
+POST /api/v1/demo/vote/cast
+
+Body:
+{
+  "player": "alice",           ← Demo player name
+  "gameId": "uuid",
+  "votedFor": "player-address"  ← Full Solana address
+}
+
+Response:
+{
+  "success": true,
+  "message": "alice voted for GvE3wSwh...",
+  "transaction": "signature",
+  "votesCount": 2,
+  "votingProgress": "2/3 votes"
+}
+```
+
+### **Distribute by Vote:**
+```
+POST /api/v1/demo/vote/distribute
+
+Body:
+{
+  "gameId": "uuid"
+}
+
+Response:
+{
+  "success": true,
+  "message": "Winnings distributed by vote to 1 winners",
+  "transaction": "signature",
+  "winners": ["winner-address"],
+  "voteCounts": {
+    "player1": 2,
+    "player2": 1
+  },
+  "winnersCount": 1
+}
+```
+
+---
+
+## 📊 **Wallet Addresses Reference**
+
+```
+Creator: 2rHd6Fe7KzbUAJwH56iVSmAcRy4X9rdqutS2hzc1PM4d
+Alice:   GvE3wSwh2HDpER7x3WXmipqH8Q9zDmHiAc8Qc8U8jTTc
+Bob:     AuskVDhGKzZ9xWJaY5RKWzBZzeGuEYZ6mZXCDeTQCJcw
+Charlie: B6ZDc5TA31nLeffsFffvsPx6EUbuCeDRjoo9KgcUAR5E
+Jelli:   9tMoLukuPD5cV5K3xs8medMBGjkqsS26webAzFbqPZJr
+```
+
+---
+
+## 🎉 **One-Line Full Test**
+
+```bash
+# Complete voting test in one command chain
+curl -s -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}' | python3 -c "import sys,json; gid=json.load(sys.stdin)['gameId']; print(f'Game: {gid}'); import os; os.system(f'curl -X POST http://localhost:3001/api/v1/demo/game/join -H \"Content-Type: application/json\" -d \\'{{\"player\":\"alice\",\"gameId\":\"{gid}\"}}\\''); os.system(f'curl -X POST http://localhost:3001/api/v1/demo/game/join -H \"Content-Type: application/json\" -d \\'{{\"player\":\"bob\",\"gameId\":\"{gid}\"}}\\''); os.system(f'curl -X POST http://localhost:3001/api/v1/demo/vote/cast -H \"Content-Type: application/json\" -d \\'{{\"player\":\"creator\",\"gameId\":\"{gid}\",\"votedFor\":\"GvE3wSwh2HDpER7x3WXmipqH8Q9zDmHiAc8Qc8U8jTTc\"}}\\''); os.system(f'curl -X POST http://localhost:3001/api/v1/demo/vote/cast -H \"Content-Type: application/json\" -d \\'{{\"player\":\"alice\",\"gameId\":\"{gid}\",\"votedFor\":\"GvE3wSwh2HDpER7x3WXmipqH8Q9zDmHiAc8Qc8U8jTTc\"}}\\''); os.system(f'curl -X POST http://localhost:3001/api/v1/demo/vote/distribute -H \"Content-Type: application/json\" -d \\'{{\"gameId\":\"{gid}}\\' | python3 -m json.tool')"
+```
+
+---
+
+## ⚡ **Tips**
+
+### **Pretty Print:**
+```bash
+# Always pipe to python3 -m json.tool for readable output
+curl ... | python3 -m json.tool
+```
+
+### **Save Variables:**
+```bash
+# Save game ID
+GAME_ID="paste-here"
+
+# Save addresses
+ALICE="GvE3wSwh2HDpER7x3WXmipqH8Q9zDmHiAc8Qc8U8jTTc"
+BOB="AuskVDhGKzZ9xWJaY5RKWzBZzeGuEYZ6mZXCDeTQCJcw"
+```
+
+### **Silent Mode:**
+```bash
+# Use -s flag to hide curl progress
+curl -s http://...
+```
+
+---
+
+## 🎯 **Test Everything!**
+
+**You now have ALL the commands to test the complete democratic voting system locally!**
+
+**No Postman, no Heroku, no AWS - just pure local testing! 🚀**
+
+---
+
+**Copy and paste away! 🎮🗳️**
+