dubs-server 1.0.0

package/documentation/JACKPOT_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,362 @@
+# 🎰 Jackpot Deployment Guide
+
+Complete guide for deploying the Jackpot system to Heroku (devnet & mainnet).
+
+## Overview
+
+| Environment | Heroku App | Solana Network | Program ID |
+|-------------|------------|----------------|------------|
+| **Development** | `dubs-server-dev` | Devnet | `BHidyz25KWkNPdTHgeANzMg25MM2KEiNnG4yE5F46XUz` |
+| **Production** | `dubs-server-prod` | Mainnet | `<DEPLOY TO MAINNET>` |
+
+## Pre-Deployment Checklist
+
+### 1. Solana Program (On-Chain)
+
+- [ ] Program deployed to target network
+- [ ] Config PDA initialized with fee settings
+- [ ] Config PDA funded (minimum 0.5 SOL for keeper rewards)
+- [ ] Round PDA funded (minimum 0.01 SOL for rent)
+
+### 2. Wallet Setup
+
+- [ ] Oracle wallet created (or reuse existing)
+- [ ] Oracle wallet funded (for transaction fees)
+- [ ] Private key exported for Heroku
+
+### 3. Heroku App
+
+- [ ] App created on Heroku
+- [ ] PostgreSQL addon attached
+- [ ] Environment variables configured
+
+---
+
+## Step 1: Deploy Solana Program (if needed)
+
+### Devnet (Already Done ✅)
+
+```bash
+# Program already deployed at:
+# BHidyz25KWkNPdTHgeANzMg25MM2KEiNnG4yE5F46XUz
+```
+
+### Mainnet (New Deployment Required)
+
+```bash
+cd /Users/adamdahan/Developer/iheartsolana/solana-programs/dubs
+
+# Build the program
+cargo build-sbf
+
+# Deploy to mainnet (requires SOL for deployment ~2-3 SOL)
+solana program deploy \
+  target/deploy/dubs_jackpot_program.so \
+  --url mainnet-beta \
+  --keypair ~/.config/solana/id.json \
+  --program-id target/deploy/dubs_jackpot_program-keypair.json
+
+# Save the program ID!
+# Example: ABCxyz123...
+```
+
+---
+
+## Step 2: Initialize Program Config
+
+### For New Deployment (One-Time Setup)
+
+```bash
+# You'll need to call the initialize instruction
+# This sets up:
+# - Fee percentage (e.g., 500 = 5%)
+# - Round duration in slots (e.g., 150 = ~1 minute)
+# - Treasury wallet for fees
+
+# Use the CLI or a script to initialize
+```
+
+### Fund the PDAs
+
+```bash
+# Get PDA addresses
+CONFIG_PDA="6CtBNYPTkQWBuAR25n5PwJWCkfHM8WDjy4FhNPgK4wDs"  # Devnet
+ROUND_PDA="Ba7qZWQ42kPStqkz4htMHiYNwwBDCoPMrTQGo4d2T2ET"    # Devnet
+
+# Fund Config PDA (for keeper rewards)
+# Each played round costs 0.003 SOL, empty rounds are FREE
+solana transfer $CONFIG_PDA 1.0 --url devnet
+
+# Fund Round PDA (for rent)
+solana transfer $ROUND_PDA 0.01 --url devnet
+```
+
+---
+
+## Step 3: Export Keeper Private Key
+
+```bash
+# Get the private key as JSON array
+cat /Users/adamdahan/Developer/iheartsolana/solana-programs/dubs-server/wallets/oracle.json
+
+# Output will look like:
+# [123,45,67,89,...] (64 numbers)
+
+# Copy this ENTIRE array including brackets
+```
+
+---
+
+## Step 4: Configure Heroku Environment Variables
+
+### For Devnet (dubs-server-dev)
+
+```bash
+# Set Solana network
+heroku config:set SOLANA_NETWORK=https://api.devnet.solana.com -a dubs-server-dev
+
+# Set Jackpot Program ID (devnet)
+heroku config:set JACKPOT_PROGRAM_ID=BHidyz25KWkNPdTHgeANzMg25MM2KEiNnG4yE5F46XUz -a dubs-server-dev
+
+# Set Oracle Wallet
+heroku config:set JACKPOT_ORACLE_WALLET=FWUJCthDfPcgmTvdQWM5uofxxiYjqJFMMwiLYvS7LBFa -a dubs-server-dev
+
+# Set Keeper Private Key (CRITICAL!)
+# Paste the ENTIRE JSON array from oracle.json
+heroku config:set KEEPER_PRIVATE_KEY='[123,45,67,89,...]' -a dubs-server-dev
+
+# Set API Base URL (for keeper to call server)
+heroku config:set API_BASE_URL=https://dubs-server-dev.herokuapp.com -a dubs-server-dev
+```
+
+### For Mainnet (dubs-server-prod)
+
+```bash
+# Set Solana network
+heroku config:set SOLANA_NETWORK=https://api.mainnet-beta.solana.com -a dubs-server-prod
+
+# Set Jackpot Program ID (MAINNET - deploy first!)
+heroku config:set JACKPOT_PROGRAM_ID=<YOUR_MAINNET_PROGRAM_ID> -a dubs-server-prod
+
+# Set Oracle Wallet (can be same or different for mainnet)
+heroku config:set JACKPOT_ORACLE_WALLET=<YOUR_MAINNET_ORACLE_WALLET> -a dubs-server-prod
+
+# Set Keeper Private Key (use MAINNET wallet!)
+heroku config:set KEEPER_PRIVATE_KEY='[...]' -a dubs-server-prod
+
+# Set API Base URL
+heroku config:set API_BASE_URL=https://dubs-server-prod.herokuapp.com -a dubs-server-prod
+```
+
+---
+
+## Step 5: Deploy to Heroku
+
+### Deploy Code
+
+```bash
+cd /Users/adamdahan/Developer/iheartsolana/solana-programs/dubs-server
+
+# Commit changes
+git add .
+git commit -m "Jackpot deployment ready"
+
+# Deploy to devnet
+git push heroku-dev main
+
+# Deploy to mainnet
+git push heroku-prod main
+```
+
+### Enable Keeper Dyno
+
+```bash
+# For devnet
+heroku ps:scale jackpot-keeper=1 -a dubs-server-dev
+
+# For mainnet
+heroku ps:scale jackpot-keeper=1 -a dubs-server-prod
+```
+
+---
+
+## Step 6: Verify Deployment
+
+### Health Checks
+
+```bash
+# Devnet
+curl https://dubs-server-dev.herokuapp.com/jackpot/health | jq .
+curl https://dubs-server-dev.herokuapp.com/jackpot/round/current | jq .
+
+# Mainnet
+curl https://dubs-server-prod.herokuapp.com/jackpot/health | jq .
+curl https://dubs-server-prod.herokuapp.com/jackpot/round/current | jq .
+```
+
+### Check Logs
+
+```bash
+# Devnet keeper logs
+heroku logs --tail --ps jackpot-keeper -a dubs-server-dev
+
+# Mainnet keeper logs
+heroku logs --tail --ps jackpot-keeper -a dubs-server-prod
+```
+
+### Expected Log Output
+
+```
+🤖 Complete Jackpot Keeper Bot
+   Wallet: FWUJCthDfPcgmTvdQWM5uofxxiYjqJFMMwiLYvS7LBFa
+
+🚀 Keeper bot started!
+
+🔧 Checking for stuck rounds...
+✅ No stuck rounds found
+
+⏳ Round 117 in progress...
+   Status: Open
+   Time remaining: 45 slots
+   Entries: 0
+   Pot: 0 SOL
+```
+
+---
+
+## Environment Variables Reference
+
+| Variable | Required | Description | Example |
+|----------|----------|-------------|---------|
+| `SOLANA_NETWORK` | ✅ | RPC endpoint | `https://api.devnet.solana.com` |
+| `JACKPOT_PROGRAM_ID` | ✅ | On-chain program ID | `BHidyz25...` |
+| `JACKPOT_ORACLE_WALLET` | ✅ | Oracle public key | `DU4CHE...` |
+| `KEEPER_PRIVATE_KEY` | ✅ | Oracle secret key (JSON) | `[1,2,3,...]` |
+| `API_BASE_URL` | ✅ | Server URL for keeper | `https://...` |
+| `DATABASE_URL` | ✅ | PostgreSQL connection | Auto-set by Heroku |
+
+---
+
+## Dyno Configuration
+
+| Process | Purpose | Scale |
+|---------|---------|-------|
+| `web` | API server | 1 |
+| `oracle` | Sports betting oracle | 0-1 |
+| `jackpot-keeper` | Jackpot round manager | 1 |
+
+### Scale Commands
+
+```bash
+# Check current scaling
+heroku ps -a dubs-server-dev
+
+# Scale up/down
+heroku ps:scale web=1 oracle=1 jackpot-keeper=1 -a dubs-server-dev
+```
+
+---
+
+## Costs & Economics
+
+### Keeper Rewards (from Config PDA)
+
+| Round Type | Cost | Notes |
+|------------|------|-------|
+| Empty round | **FREE** | No keeper reward paid |
+| Played round | 0.003 SOL | lock + resolve + reset |
+
+### Self-Sustaining Model
+
+- Played rounds replenish Config via 20% of fees
+- With 5% fee on 1 SOL pot: 0.01 SOL back to Config
+- Net profit per played round: ~0.007 SOL
+
+### Recommended Funding
+
+| Environment | Config PDA | Round PDA |
+|-------------|------------|-----------|
+| Devnet | 1.0 SOL | 0.01 SOL |
+| Mainnet | 5.0 SOL | 0.1 SOL |
+
+---
+
+## Troubleshooting
+
+### Keeper Not Starting
+
+```bash
+# Check if private key is set
+heroku config:get KEEPER_PRIVATE_KEY -a dubs-server-dev
+
+# Check logs for errors
+heroku logs --tail --ps jackpot-keeper -a dubs-server-dev
+```
+
+### "InsufficientFundsForRent" Error
+
+Config PDA is depleted. Fund it:
+
+```bash
+solana transfer 6CtBNYPTkQWBuAR25n5PwJWCkfHM8WDjy4FhNPgK4wDs 1.0 --url devnet
+```
+
+### Rounds Not Advancing
+
+1. Check keeper logs
+2. Verify program ID matches
+3. Check PDA balances
+4. Restart keeper: `heroku ps:restart jackpot-keeper -a dubs-server-dev`
+
+---
+
+## Mainnet Deployment Checklist
+
+Before going live on mainnet:
+
+- [ ] Deploy Solana program to mainnet-beta
+- [ ] Initialize program config with production settings
+- [ ] Create/fund mainnet oracle wallet
+- [ ] Fund Config PDA with 5+ SOL
+- [ ] Fund Round PDA with 0.1+ SOL
+- [ ] Configure dubs-server-prod with mainnet env vars
+- [ ] Deploy and enable jackpot-keeper dyno
+- [ ] Test with small amounts first
+- [ ] Monitor logs for 24 hours
+- [ ] Set up alerts for PDA balance monitoring
+
+---
+
+## Quick Commands Reference
+
+```bash
+# === DEVNET ===
+# Deploy
+git push heroku-dev main
+
+# Logs
+heroku logs --tail -a dubs-server-dev
+heroku logs --tail --ps jackpot-keeper -a dubs-server-dev
+
+# Restart
+heroku ps:restart jackpot-keeper -a dubs-server-dev
+
+# Scale
+heroku ps:scale jackpot-keeper=1 -a dubs-server-dev
+
+# === MAINNET ===
+# Deploy
+git push heroku-prod main
+
+# Logs
+heroku logs --tail -a dubs-server-prod
+heroku logs --tail --ps jackpot-keeper -a dubs-server-prod
+
+# Restart
+heroku ps:restart jackpot-keeper -a dubs-server-prod
+
+# Scale
+heroku ps:scale jackpot-keeper=1 -a dubs-server-prod
+```
+
+