dubs-server 1.0.0

package/documentation/QUICK_DEPLOY.md

@@ -0,0 +1,224 @@
+# ⚡ Quick Deploy to Heroku
+
+## 🚀 Deploy in 3 Commands
+
+```bash
+cd /Users/adamdahan/Developer/iheartsolana/solana-programs/dubs-server
+
+# 1. Setup keeper wallet (one-time only)
+./setup-heroku-keeper.sh
+
+# 2. Commit and deploy
+git add .
+git commit -m "Fix keeper for Heroku deployment"
+git push heroku-dev main
+
+# 3. Scale up keeper
+heroku ps:scale jackpot-keeper=1 -a dubs-server-dev
+
+# 4. Watch it work!
+heroku logs --tail --ps jackpot-keeper -a dubs-server-dev
+```
+
+---
+
+## ✅ What You Should See
+
+### Step 1: Setup Keeper
+```
+🔐 Setting up Jackpot Keeper on Heroku
+======================================
+
+✅ Found oracle wallet
+
+📤 Setting KEEPER_PRIVATE_KEY on Heroku...
+Setting KEEPER_PRIVATE_KEY and restarting ⬢ dubs-server-dev... done
+
+✅ Keeper wallet configured!
+```
+
+### Step 2: Deploy
+```
+Enumerating objects: 5, done.
+Counting objects: 100% (5/5), done.
+...
+remote: Verifying deploy... done.
+```
+
+### Step 3: Scale Up
+```
+Scaling dynos... done, now running jackpot-keeper at 1:Free
+```
+
+### Step 4: Logs
+```
+📂 Using wallet from KEEPER_PRIVATE_KEY environment variable
+🤖 Complete Jackpot Keeper Bot
+   Wallet: FWUJCthDfPcgmTvdQWM5uofxxiYjqJFMMwiLYvS7LBFa
+
+🚀 Keeper bot started!
+```
+
+---
+
+## 🔍 Verify It's Working
+
+```bash
+# Check process status
+heroku ps -a dubs-server-dev
+
+# Should show:
+# jackpot-keeper.1: up 2024/11/16 15:00:00 -0500 (~ 1m ago)
+
+# Check the API
+curl https://dubs-server-dev.herokuapp.com/jackpot/round/current | jq .
+
+# Should show an active round with countdown
+```
+
+---
+
+## 🐛 If Something Goes Wrong
+
+### Keeper crashes immediately
+
+**Check logs:**
+```bash
+heroku logs --tail --ps jackpot-keeper -a dubs-server-dev
+```
+
+**Common issues:**
+
+1. **"No wallet found"** → Run `./setup-heroku-keeper.sh` again
+2. **"Invalid private key"** → Check that env var is set correctly
+3. **"No active round"** → Config account needs SOL (see below)
+
+### No active round
+
+The config account may need funding:
+
+```bash
+# Check balance
+solana account CwNvZq6GuKvsEr3WDyQWhzDaTYccmsRVibdXK85FnwoW --url devnet
+
+# If low, fund it
+solana transfer CwNvZq6GuKvsEr3WDyQWhzDaTYccmsRVibdXK85FnwoW 0.5 --url devnet
+```
+
+### Keeper keeps restarting
+
+```bash
+# Check if env var is set
+heroku config:get KEEPER_PRIVATE_KEY -a dubs-server-dev
+
+# If empty or wrong, reset it
+./setup-heroku-keeper.sh
+```
+
+---
+
+## 📊 Monitor Your Keeper
+
+```bash
+# Live logs
+heroku logs --tail --ps jackpot-keeper -a dubs-server-dev
+
+# Recent logs
+heroku logs --ps jackpot-keeper -a dubs-server-dev
+
+# All logs
+heroku logs --tail -a dubs-server-dev
+
+# Process status
+heroku ps -a dubs-server-dev
+
+# Restart keeper
+heroku ps:restart jackpot-keeper -a dubs-server-dev
+```
+
+---
+
+## 🎮 Test the System
+
+Once deployed:
+
+1. Visit: https://dubs-server-dev.herokuapp.com/jackpot/health
+2. Check round: https://dubs-server-dev.herokuapp.com/jackpot/round/current
+3. Should see an active round with countdown
+4. Keeper should automatically manage rounds every ~1 minute
+
+---
+
+## 💡 Pro Tips
+
+### Check Wallet Balance
+
+```bash
+# Keeper wallet
+solana balance FWUJCthDfPcgmTvdQWM5uofxxiYjqJFMMwiLYvS7LBFa --url devnet
+
+# If low, airdrop more (devnet only)
+solana airdrop 2 FWUJCthDfPcgmTvdQWM5uofxxiYjqJFMMwiLYvS7LBFa --url devnet
+```
+
+### View All Config
+
+```bash
+heroku config -a dubs-server-dev
+```
+
+### Scale Down (to save dyno hours)
+
+```bash
+# Turn off keeper
+heroku ps:scale jackpot-keeper=0 -a dubs-server-dev
+
+# Turn back on
+heroku ps:scale jackpot-keeper=1 -a dubs-server-dev
+```
+
+---
+
+## 📋 Full Command Reference
+
+```bash
+# Setup
+./setup-heroku-keeper.sh                          # Setup wallet (one-time)
+heroku config -a dubs-server-dev                  # View all config
+
+# Deploy
+git add .                                          # Stage changes
+git commit -m "Your message"                       # Commit
+git push heroku-dev main                           # Deploy
+
+# Manage
+heroku ps -a dubs-server-dev                       # Process status
+heroku ps:scale jackpot-keeper=1 -a dubs-server-dev  # Start keeper
+heroku ps:scale jackpot-keeper=0 -a dubs-server-dev  # Stop keeper
+heroku ps:restart jackpot-keeper -a dubs-server-dev  # Restart keeper
+
+# Monitor
+heroku logs --tail -a dubs-server-dev              # All logs
+heroku logs --tail --ps jackpot-keeper -a dubs-server-dev  # Keeper only
+curl https://dubs-server-dev.herokuapp.com/jackpot/round/current | jq .
+
+# Debug
+heroku run bash -a dubs-server-dev                 # Open shell on Heroku
+heroku config:get KEEPER_PRIVATE_KEY -a dubs-server-dev  # Check env var
+```
+
+---
+
+## ✅ Success Checklist
+
+- [ ] Keeper wallet configured (`./setup-heroku-keeper.sh`)
+- [ ] Code deployed (`git push heroku-dev main`)
+- [ ] Keeper scaled up (`heroku ps:scale jackpot-keeper=1`)
+- [ ] Logs show "Keeper bot started"
+- [ ] API returns active round
+- [ ] Rounds cycling every ~1 minute
+
+---
+
+**You're ready! The keeper bot should now be managing jackpot rounds automatically on Heroku.** 🚀🎰
+

package/documentation/QUICK_FIX.md

@@ -0,0 +1,114 @@
+# 🚨 Quick Fix Guide - Round Stuck Again
+
+## What Happened
+
+Round 52 got stuck because **the API server was still running the old buggy code**. Even though we fixed the code in `services/jackpotService.js`, the server needed to be restarted to load the new code.
+
+## Immediate Actions (RIGHT NOW)
+
+### Option 1: Use the Restart Script (Easiest)
+```bash
+cd /Users/adamdahan/Developer/iheartsolana/solana-programs/dubs-server
+./RESTART_EVERYTHING.sh
+```
+
+This will:
+- Stop all processes
+- Start API server with fixed code
+- Start keeper bot
+- Verify everything is working
+
+### Option 2: Manual Restart
+```bash
+# 1. Stop everything
+pkill -f "jackpot-keeper"
+pkill -f "server.js"
+
+# 2. Start API server
+cd /Users/adamdahan/Developer/iheartsolana/solana-programs/dubs-server
+SOLANA_NETWORK=https://api.devnet.solana.com node server.js &
+
+# 3. Start keeper bot
+node scripts/jackpot-keeper.js &
+```
+
+### Option 3: PM2 (Best for Production)
+```bash
+# Install PM2 if not installed
+npm install -g pm2
+
+# Start everything
+cd /Users/adamdahan/Developer/iheartsolana/solana-programs/dubs-server
+pm2 start ecosystem.config.js
+
+# Check status
+pm2 status
+
+# View logs
+pm2 logs
+```
+
+## If Round is Currently Stuck
+
+If you have a stuck round right now:
+
+```bash
+cd /Users/adamdahan/Developer/iheartsolana/solana-programs/dubs-server
+
+# This will resolve it with the fixed code
+node scripts/resolve-direct.js
+```
+
+## Verify Everything Works
+
+```bash
+# Check API health
+curl http://localhost:3001/jackpot/health
+
+# Check current round
+curl http://localhost:3001/jackpot/round/current | python3 -m json.tool
+
+# Should see:
+# - Round status: "Open" (accepting entries)
+# - No errors in response
+```
+
+## Why This Keeps Happening
+
+**Root Cause:** Node.js doesn't automatically reload code when files change. You must restart the server after making code changes.
+
+**Solutions:**
+1. **Development:** Use `nodemon` (auto-restarts on file changes)
+2. **Production:** Use `PM2` (process manager with auto-restart)
+3. **Quick fixes:** Use `./RESTART_EVERYTHING.sh`
+
+## Prevention Checklist
+
+After fixing any bug:
+- [ ] Restart API server
+- [ ] Restart keeper bot
+- [ ] Verify with health check
+- [ ] Watch next few rounds to confirm fix works
+
+## Monitoring
+
+Add this to your terminal startup (`.bashrc` or `.zshrc`):
+
+```bash
+alias dubs-status='curl -s http://localhost:3001/jackpot/round/current | python3 -m json.tool'
+alias dubs-health='curl -s http://localhost:3001/jackpot/health | python3 -m json.tool'
+alias dubs-restart='cd /Users/adamdahan/Developer/iheartsolana/solana-programs/dubs-server && ./RESTART_EVERYTHING.sh'
+```
+
+Then you can just type:
+- `dubs-status` - Check current round
+- `dubs-health` - Check if server is up
+- `dubs-restart` - Restart everything
+
+## Questions?
+
+Check these files:
+- `documentation/PREVENTING_LOCKUP_ERRORS.md` - Complete prevention guide
+- `ecosystem.config.js` - PM2 configuration
+- `scripts/verify-account-layout.js` - Verify offsets are correct
+

package/documentation/QUICK_START.md

@@ -0,0 +1,152 @@
+# 🚀 DUBS Server - Quick Start Guide
+
+Get up and running in under 1 minute!
+
+## 🎯 First Time Setup
+
+```bash
+# 1. Install dependencies
+npm install
+
+# 2. Setup database (automated - just say yes!)
+./scripts/setup-database-fresh.sh
+
+# 3. Start server
+npm start
+```
+
+That's it! Server running at http://localhost:3001 🎉
+
+## 📋 Common Commands
+
+### Start Server
+```bash
+npm start
+```
+
+### Reset Everything (Fresh Start)
+```bash
+# Drops database, recreates, and sets up schema
+./scripts/setup-database-fresh.sh
+# Answer 'y' when prompted
+```
+
+### Clear All Data (Keep Structure)
+```bash
+# Removes all data, keeps tables intact
+./scripts/purge-all-data.sh
+# Requires double confirmation for safety
+```
+
+### Update Schema Only
+```bash
+# Updates tables without deleting data
+psql -d dubs_db -f scripts/setup-complete-database.sql
+```
+
+### Check Database Status
+```bash
+# List all tables
+psql -d dubs_db -c "\dt"
+
+# Check PostgreSQL status
+pg_isready
+
+# Start PostgreSQL if needed
+brew services start postgresql@14
+```
+
+## 🎮 Test Endpoints
+
+Once the server is running:
+
+```bash
+# Health check
+curl http://localhost:3001/jackpot/health
+
+# Get jackpot config
+curl http://localhost:3001/jackpot/config
+
+# Request auth nonce (replace with your wallet)
+curl http://localhost:3001/api/v1/auth/nonce/YOUR_WALLET_ADDRESS
+```
+
+## 🛠️ Troubleshooting
+
+### PostgreSQL Not Running?
+```bash
+brew services start postgresql@14
+```
+
+### Database Issues?
+```bash
+# Nuclear option - full reset
+./scripts/setup-database-fresh.sh
+# Answer 'y' to drop and recreate
+```
+
+### Can't Connect?
+Check your `.env` file has:
+```
+DATABASE_URL=postgresql://username@localhost:5432/dubs_db
+```
+
+### Need Fresh Data?
+```bash
+# Clear all data, keep structure
+./scripts/purge-all-data.sh
+```
+
+## 📖 Full Documentation
+
+- **Database Setup:** `documentation/DATABASE_SETUP_GUIDE.md`
+- **Script Reference:** `scripts/README.md`
+- **Complete Summary:** `DATABASE_SETUP_SUMMARY.md`
+
+## 🎯 Development Workflow
+
+```bash
+# Morning routine
+brew services start postgresql@14
+npm start
+
+# Testing something? Clear data:
+./scripts/purge-all-data.sh
+
+# Messed up schema? Reset:
+./scripts/setup-database-fresh.sh
+
+# End of day
+# PostgreSQL keeps running (that's fine)
+```
+
+## 💡 Pro Tips
+
+1. **Bookmark `setup-database-fresh.sh`** - You'll use it often
+2. **Never commit `.env`** - Already in `.gitignore`
+3. **Use `purge-all-data.sh` for testing** - Keeps structure, removes data
+4. **Full reset = setup-database-fresh.sh** - Rebuilds everything
+
+## ⚡ Super Quick Reference
+
+| Task | Command |
+|------|---------|
+| First setup | `./scripts/setup-database-fresh.sh` |
+| Start server | `npm start` |
+| Clear data | `./scripts/purge-all-data.sh` |
+| Full reset | `./scripts/setup-database-fresh.sh` (say yes) |
+| Check tables | `psql -d dubs_db -c "\dt"` |
+| Start PostgreSQL | `brew services start postgresql@14` |
+
+---
+
+**Need more help?** See `DATABASE_SETUP_GUIDE.md` for comprehensive troubleshooting!
+
+
+
+
+
+
+
+
+