dubs-server 1.0.0

package/documentation/UNIFIED_ARCHITECTURE.md

@@ -0,0 +1,231 @@
+# 🏗️ Unified Server Architecture
+
+## Overview
+
+The Dubs server has been refactored to use a **single unified server** that handles both:
+- **Sports Betting System** (original functionality)
+- **Arcade Match System** (new functionality)
+
+This eliminates the need to run multiple servers and provides a cleaner, more maintainable architecture.
+
+---
+
+## Architecture Benefits
+
+### ✅ Before (Redundant)
+- `server.js` → Sports betting on port 3001
+- `arcade-server.js` → Arcade matches on port 3003
+- **Problem:** Two servers, two ports, duplicate code
+
+### ✅ After (Unified)
+- `server.js` → **Both systems** on port 3001
+- Arcade routes mounted at `/arcade/*`
+- **Benefits:** Single server, shared infrastructure, easier deployment
+
+---
+
+## Server Structure
+
+```
+server.js (Main Server)
+├── Sports Betting Routes
+│   ├── /api/v1/prod/*  (Production API)
+│   └── /api/v1/demo/*  (Demo/Test API)
+│
+└── Arcade Match Routes
+    └── /arcade/*        (Arcade API)
+```
+
+---
+
+## Starting the Server
+
+### Localnet
+```bash
+# Default (port 3001, localnet)
+npm start
+
+# Or directly
+node server.js
+```
+
+### Devnet
+```bash
+# Set environment and start
+SOLANA_NETWORK=https://api.devnet.solana.com npm start
+```
+
+### Development (with auto-reload)
+```bash
+npm run dev
+```
+
+---
+
+## API Endpoints
+
+### Sports Betting API
+- Base URL: `http://localhost:3001/api/v1`
+- Production: `/api/v1/prod/*`
+- Demo/Test: `/api/v1/demo/*`
+
+### Arcade Match API
+- Base URL: `http://localhost:3001/arcade`
+- Health: `GET /arcade/health`
+- Create: `POST /arcade/matches/create`
+- Join: `POST /arcade/matches/:id/join`
+- Score: `POST /arcade/matches/:id/score`
+- Resolve: `POST /arcade/matches/:id/resolve`
+- [Full API docs](./ARCADE_API.md)
+
+---
+
+## Testing
+
+### Arcade System Tests
+```bash
+# Localnet test
+npm run arcade:test
+
+# Devnet test
+npm run arcade:test:devnet
+```
+
+### Sports Betting Tests
+```bash
+# Demo API test
+npm run test:voting
+
+# CLI tool
+npm run cli
+```
+
+---
+
+## Code Organization
+
+### Services
+```
+services/
+├── arcadeMatchService.js       # Arcade match logic
+├── automaticGameOracle.js      # Sports oracle
+└── telegramNotifications.js    # Notifications
+```
+
+### Routes
+```
+routes/
+└── arcadeRoutes.js            # Arcade API routes
+```
+
+### Main Server
+```
+server.js                       # Unified server with both systems
+```
+
+---
+
+## Integration Points
+
+The arcade system is initialized in `server.js`:
+
+```javascript
+// Import arcade components
+const ArcadeMatchService = require('./services/arcadeMatchService');
+const arcadeRoutes = require('./routes/arcadeRoutes');
+
+// Initialize service
+const arcadeService = new ArcadeMatchService({
+  rpcUrl: RPC_URL,
+  walletsDir: WALLETS_DIR,
+});
+
+// Mount routes
+app.use('/arcade', arcadeRoutes(arcadeService));
+```
+
+This approach:
+- ✅ Shares the same Express app
+- ✅ Uses the same RPC connection
+- ✅ Shares the same wallet directory
+- ✅ Runs on the same port
+- ✅ Can be deployed as a single unit
+
+---
+
+## Deployment
+
+### Single Server Deployment
+```bash
+# Deploy to your hosting service
+# Only need to deploy server.js (no arcade-server.js)
+node server.js
+```
+
+### Heroku (Example)
+```
+Procfile:
+web: node server.js
+```
+
+### PM2 (Example)
+```bash
+pm2 start server.js --name dubs-api
+```
+
+---
+
+## Environment Variables
+
+```bash
+# Shared by both systems
+SOLANA_NETWORK=http://127.0.0.1:8899  # or https://api.devnet.solana.com
+PORT=3001                              # Server port
+PROGRAM_ID=8DJTkgk6MDr6...            # Sports betting program
+# Arcade program ID is hardcoded in arcadeMatchService.js
+```
+
+---
+
+## Migration Notes
+
+### What Changed
+- ✅ Deleted `arcade-server.js` (redundant)
+- ✅ Integrated arcade routes into `server.js`
+- ✅ Updated npm scripts
+- ✅ Updated test scripts (port 3003 → 3001)
+- ✅ Updated documentation
+
+### What Stayed the Same
+- ✅ All arcade endpoints still work
+- ✅ All sports betting endpoints still work
+- ✅ API contracts unchanged
+- ✅ Service logic unchanged
+
+---
+
+## Quick Reference
+
+| System | Base Path | Port | Program ID |
+|--------|-----------|------|------------|
+| Sports Betting | `/api/v1` | 3001 | `8DJTkgk6...` |
+| Arcade Matches | `/arcade` | 3001 | `EiNzW28x...` |
+
+**Both systems run on the same unified server!** 🎮
+
+---
+
+## Next Steps
+
+1. ✅ Single server for both systems
+2. ✅ Cleaner architecture
+3. ✅ Easier to deploy and maintain
+4. ⬜ Add unified monitoring/logging
+5. ⬜ Add unified authentication (if needed)
+6. ⬜ Add rate limiting
+7. ⬜ Add unified API documentation portal
+
+---
+
+**The unified architecture makes the codebase cleaner, more maintainable, and production-ready!** 🚀
+

package/documentation/VOTING_DEPLOYMENT_SUMMARY.md

@@ -0,0 +1,392 @@
+# 🎉 DEMOCRATIC VOTING - DEPLOYMENT COMPLETE!
+
+## ✅ **What We Just Deployed to Heroku**
+
+**Deployment:** `v6` - Released successfully  
+**Commit:** `7e4af95` - Add democratic voting endpoints  
+**Lines Added:** 130+ lines of voting logic  
+**Status:** ✅ **LIVE ON DEVNET**
+
+---
+
+## 🗳️ **New Endpoints (LIVE):**
+
+### **1. Cast Vote**
+```
+POST /api/v1/prod/transaction/build/cast-vote
+
+Request:
+{
+  "voterAddress": "PlayerSolanaAddress",
+  "gameId": "uuid-of-game",
+  "votedFor": "AnotherPlayerAddress"
+}
+
+Response:
+{
+  "success": true,
+  "transaction": "BASE64_UNSIGNED_TX",
+  "instructions": "Sign with your wallet..."
+}
+```
+
+### **2. Distribute by Vote**
+```
+POST /api/v1/prod/transaction/build/distribute-by-vote
+
+Request:
+{
+  "creatorAddress": "CreatorAddress",
+  "gameId": "uuid-of-game"
+}
+
+Response:
+{
+  "success": true,
+  "transaction": "BASE64_UNSIGNED_TX",
+  "winners": ["WinnerAddress1", "WinnerAddress2"],
+  "voteCounts": {
+    "Player1": 2,
+    "Player2": 1
+  }
+}
+```
+
+### **3. Updated Create Game**
+```
+POST /api/v1/prod/transaction/build/create
+
+NEW Parameter:
+{
+  ...
+  "votingEnabled": true  ← Enable democratic voting!
+}
+```
+
+### **4. Updated Game Info**
+```
+GET /api/v1/prod/game/:gameId
+
+NEW Fields in Response:
+{
+  "game": {
+    ...
+    "votes": [
+      {"voter": "Address1", "votedFor": "Address2"}
+    ],
+    "votingEnabled": true
+  }
+}
+```
+
+---
+
+## 📦 **Postman Documentation**
+
+### **Files Created:**
+```
+✅ postman/Dubs-API-v1-With-Voting.postman_collection.json
+   - Complete collection with ALL endpoints
+   - Democratic voting workflows
+   - Auto-save game IDs
+   - Example requests
+
+✅ postman/VOTING_API_GUIDE.md
+   - Complete voting documentation
+   - Workflow examples
+   - Response formats
+   - Testing tips
+
+✅ postman/QUICK_REFERENCE.md
+   - Quick endpoint reference
+   - Majority rules cheat sheet
+   - Status codes
+   - Common errors
+```
+
+### **Updated:**
+```
+✅ README.md
+   - Added voting section
+   - Updated features list
+   - Updated endpoint list
+   - Updated Postman references
+```
+
+---
+
+## 🎯 **What Each File Does:**
+
+### **Postman Collection**
+```
+Dubs-API-v1-With-Voting.postman_collection.json
+
+Contains:
+├── Health Check
+├── Production API
+│   ├── Game Management
+│   ├── Game Creation
+│   ├── Join Game
+│   ├── Democratic Voting ← NEW!
+│   ├── Manual Distribution
+│   └── Transaction Submission
+├── Demo/Test API
+├── Complete Workflows
+│   ├── Standard Game Flow
+│   └── Democratic Game Flow ← NEW!
+└── Examples & Documentation
+```
+
+### **Voting API Guide**
+```
+VOTING_API_GUIDE.md
+
+Includes:
+- Complete endpoint documentation
+- Request/response formats
+- Voting rules explained
+- Majority calculation
+- Tie handling
+- Testing workflows
+- Common errors
+```
+
+### **Quick Reference**
+```
+QUICK_REFERENCE.md
+
+Includes:
+- All endpoints at a glance
+- Curl examples
+- Response formats
+- Majority cheat sheet
+- Quick tests
+```
+
+---
+
+## 🚀 **How to Use**
+
+### **Option 1: Postman (Recommended)**
+```
+1. Import: Dubs-API-v1-With-Voting.postman_collection.json
+2. Set baseUrl: https://dubs-server-dev-55d1fba09a97.herokuapp.com
+3. Set walletAddress: YOUR_WALLET
+4. Run workflows!
+```
+
+### **Option 2: Curl**
+```bash
+# Create game with voting
+curl -X POST https://dubs-server-dev-55d1fba09a97.herokuapp.com/api/v1/prod/transaction/build/create \
+  -H "Content-Type: application/json" \
+  -d '{
+    "creatorAddress": "YOUR_ADDRESS",
+    "buyIn": 0.5,
+    "maxPlayers": 3,
+    "operatorFee": 10,
+    "votingEnabled": true
+  }'
+
+# Cast vote
+curl -X POST https://dubs-server-dev-55d1fba09a97.herokuapp.com/api/v1/prod/transaction/build/cast-vote \
+  -H "Content-Type: application/json" \
+  -d '{
+    "voterAddress": "YOUR_ADDRESS",
+    "gameId": "game-uuid",
+    "votedFor": "PLAYER_ADDRESS"
+  }'
+```
+
+### **Option 3: Mobile App (Jelli Wallet)**
+```
+✅ Already integrated!
+✅ Create game with voting toggle
+✅ Vote via VotingModal
+✅ Distribute by vote button
+✅ Full UX implemented
+```
+
+---
+
+## 🎮 **Server Changes Summary**
+
+### **Lines Added:**
+```
++6   Discriminators (VOTE, DIST_VOTE)
++53  getGameData() - Parse votes and votingEnabled
++44  /cast-vote endpoint
++65  /distribute-by-vote endpoint
++1   /create - votingEnabled parameter
+---
+169  Total lines of voting code!
+```
+
+### **Server Capabilities:**
+```
+✅ Build vote transactions
+✅ Parse vote data from blockchain
+✅ Tally votes automatically
+✅ Determine winners by majority
+✅ Handle ties (equal split)
+✅ Full error handling
+```
+
+---
+
+## 📊 **Testing Checklist**
+
+### **Postman Tests:**
+- [ ] Import collection
+- [ ] Test health endpoint
+- [ ] Test create game (voting ON)
+- [ ] Test create game (voting OFF)
+- [ ] Test join game
+- [ ] Test cast vote
+- [ ] Test get game (verify votes array)
+- [ ] Test distribute by vote
+- [ ] Test manual distribute (override)
+
+### **Mobile App Tests:**
+- [ ] Create game with voting toggle
+- [ ] Join game
+- [ ] Open VotingModal
+- [ ] Cast vote
+- [ ] See majority progress
+- [ ] Distribute by vote
+- [ ] Verify prize distributed
+
+---
+
+## 🏆 **What This Enables**
+
+### **For Users:**
+```
+✅ Democratic winner selection
+✅ Transparent on-chain voting
+✅ Fair tie handling
+✅ Majority rules (no stuck games)
+✅ Trustless distribution
+```
+
+### **For Developers:**
+```
+✅ Complete API documentation
+✅ Postman collection for testing
+✅ Example workflows
+✅ Error handling
+✅ Production ready
+```
+
+### **For Gaming:**
+```
+✅ Skill competitions
+✅ Community contests
+✅ Tournament systems
+✅ Fair play enforcement
+✅ Decentralized governance
+```
+
+---
+
+## 🎊 **Achievement Summary**
+
+| Feature | Status | Location |
+|---------|--------|----------|
+| **Smart Contract** | ✅ Deployed | Devnet |
+| **REST API** | ✅ Deployed | Heroku v6 |
+| **Mobile SDK** | ✅ Complete | Jelli SDK |
+| **Mobile UI** | ✅ Complete | Jelli App |
+| **Postman Docs** | ✅ Complete | This folder |
+| **API Docs** | ✅ Complete | README.md |
+
+---
+
+## 📚 **Documentation Files**
+
+```
+postman/
+├── Dubs-API-v1-With-Voting.postman_collection.json
+├── VOTING_API_GUIDE.md (Complete guide)
+├── QUICK_REFERENCE.md (Quick lookup)
+└── QUICKSTART.md (Original guide)
+
+Root:
+├── README.md (Updated with voting)
+└── server.js (130+ new lines)
+```
+
+---
+
+## 🌟 **What's New in v1.1**
+
+```
+🗳️ Democratic Voting
+   - cast_vote instruction
+   - distribute_by_vote instruction
+   - Majority rules (50%+)
+   - Automatic winner determination
+   - Tie handling
+   
+📡 New API Endpoints
+   - POST /cast-vote
+   - POST /distribute-by-vote
+   - Updated /create (votingEnabled)
+   - Updated /game/:id (votes array)
+   
+📱 Mobile Integration
+   - VotingModal component
+   - Voting toggle in create
+   - Vote progress tracking
+   - Distribute by vote button
+   
+📦 Documentation
+   - Complete Postman collection
+   - Voting API guide
+   - Quick reference
+   - Workflow examples
+```
+
+---
+
+## 🚀 **Next Steps**
+
+### **After Heroku Outage Resolves:**
+```
+1. Test full democratic voting flow
+2. Create game with 3+ players
+3. Each player votes
+4. Distribute by vote
+5. Verify on Solana Explorer
+```
+
+### **Future Enhancements:**
+```
+- Vote deadlines
+- Weighted voting
+- Anonymous voting
+- Vote delegation
+- Multi-round voting
+```
+
+---
+
+## 🎉 **Deployment Details**
+
+```
+Repository: dubs-server
+Branch: main
+Commit: 7e4af95
+Message: "Add democratic voting endpoints - cast vote and 
+         distribute by vote with majority rules"
+Deployed: Heroku (dubs-server-dev)
+Version: v6
+Status: ✅ Live on devnet
+```
+
+---
+
+**Postman collection ready to test! 🎮🗳️**
+
+**Import and start testing democratic gaming! 🚀**
+