dubs-server 1.0.0

package/documentation/JACKPOT_API.md

@@ -0,0 +1,521 @@
+# 🎰 Dubs Jackpot API Documentation
+
+RESTful API for interacting with the Dubs Jackpot program (Solpot-style continuous jackpot).
+
+Base URL: `http://localhost:3001/jackpot` (or your deployed URL)
+
+## Overview
+
+The Jackpot API provides endpoints for:
+- Initializing the protocol
+- Opening new rounds
+- Entering rounds with weighted odds
+- Locking rounds with commit-reveal randomness
+- Oracle randomness submission
+- Resolving rounds and paying winners
+- Querying round state and statistics
+
+## Authentication
+
+Most endpoints return **unsigned transactions** that must be signed by the appropriate wallet on the frontend.
+
+The oracle endpoint requires the oracle keypair to be present in `wallets/jackpot_oracle.json`.
+
+---
+
+## Endpoints
+
+### 🏥 Health Check
+
+#### GET `/jackpot/health`
+
+Check if the jackpot service is running.
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "service": "jackpot",
+  "programId": "bqoSjTSPLweMuqNG6jy39jmzGyZvZdWjsr4csGfD8F6",
+  "oracleWallet": "FWUJCthDfPcgmTvdQWM5uofxxiYjqJFMMwiLYvS7LBFa",
+  "timestamp": "2024-11-16T00:00:00.000Z"
+}
+```
+
+---
+
+### 📊 Query Endpoints
+
+#### GET `/jackpot/config`
+
+Get protocol configuration.
+
+**Response:**
+```json
+{
+  "success": true,
+  "config": {
+    "address": "52yV2WqLXzL7PMJKHTwQfqr5a1zsqsfVkQomtLXWqf9r",
+    "authority": "57voP1Y8U4ztX2YAcHveK3JFvVRn1n6T6iUnHdAW6xr9",
+    "treasury": "BVZXwZpfgyzTBdRFHohkHZppPHnAyqyctRsKy3vWfQib",
+    "feeBasisPoints": 500,
+    "roundDurationSlots": 1800,
+    "currentRoundId": "3",
+    "totalVolume": "5000000000",
+    "totalFeesCollected": "250000000",
+    "initialized": true
+  }
+}
+```
+
+#### GET `/jackpot/round/current`
+
+Get current active round information.
+
+**Response:**
+```json
+{
+  "success": true,
+  "round": {
+    "address": "...",
+    "roundId": "3",
+    "status": "Open",
+    "startSlot": "421837200",
+    "endSlot": "421839000",
+    "totalPotLamports": "500000000",
+    "totalWeight": "500000000",
+    "entryCount": 5,
+    "currentSlot": "421837500",
+    "timeRemainingSlots": 1500
+  }
+}
+```
+
+#### GET `/jackpot/round/:roundId`
+
+Get specific round information.
+
+**Parameters:**
+- `roundId` (path) - Round ID
+
+**Response:** Same as current round
+
+#### GET `/jackpot/round/:roundId/entries`
+
+Get all entries for a round with odds.
+
+**Response:**
+```json
+{
+  "success": true,
+  "roundId": "3",
+  "entries": [
+    {
+      "player": "ABC123...",
+      "weight": "100000000",
+      "cumulativeTo": "100000000",
+      "oddsPercent": "20.00"
+    },
+    {
+      "player": "DEF456...",
+      "weight": "400000000",
+      "cumulativeTo": "500000000",
+      "oddsPercent": "80.00"
+    }
+  ],
+  "totalEntries": 2
+}
+```
+
+#### GET `/jackpot/stats`
+
+Get overall jackpot statistics.
+
+**Response:**
+```json
+{
+  "success": true,
+  "initialized": true,
+  "config": { ... },
+  "currentRound": { ... },
+  "timestamp": "2024-11-16T00:00:00.000Z"
+}
+```
+
+---
+
+### 🏗️ Build Transaction Endpoints
+
+All build endpoints return base64-encoded unsigned transactions.
+
+#### POST `/jackpot/build/initialize`
+
+Initialize the protocol (admin only, one-time setup).
+
+**Request:**
+```json
+{
+  "adminAddress": "57voP1Y8U4ztX2YAcHveK3JFvVRn1n6T6iUnHdAW6xr9",
+  "treasuryAddress": "BVZXwZpfgyzTBdRFHohkHZppPHnAyqyctRsKy3vWfQib",
+  "feeBasisPoints": 500,
+  "roundDurationSlots": 1800
+}
+```
+
+**Response:**
+```json
+{
+  "transaction": "base64_encoded_transaction",
+  "configPda": "52yV2WqLXzL7PMJKHTwQfqr5a1zsqsfVkQomtLXWqf9r"
+}
+```
+
+**Frontend Flow:**
+```javascript
+// 1. Call API
+const { transaction } = await fetch('/jackpot/build/initialize', {...});
+
+// 2. Deserialize
+const tx = Transaction.from(Buffer.from(transaction, 'base64'));
+
+// 3. Sign with wallet
+await wallet.signTransaction(tx);
+
+// 4. Send
+await connection.sendRawTransaction(tx.serialize());
+```
+
+#### POST `/jackpot/build/open-round`
+
+Open a new round (permissionless keeper).
+
+**Request:**
+```json
+{
+  "keeperAddress": "ABC123..."
+}
+```
+
+**Response:**
+```json
+{
+  "transaction": "base64_encoded_transaction",
+  "roundId": "4",
+  "roundPda": "...",
+  "entriesPda": "..."
+}
+```
+
+#### POST `/jackpot/build/enter`
+
+Enter the current round with a bet.
+
+**Request:**
+```json
+{
+  "playerAddress": "ABC123...",
+  "amount": 100000000,
+  "roundId": null
+}
+```
+
+**Fields:**
+- `playerAddress` - Player's wallet address
+- `amount` - Bet amount in lamports (min: 10,000)
+- `roundId` - Optional, uses current round if omitted
+
+**Response:**
+```json
+{
+  "transaction": "base64_encoded_transaction",
+  "roundId": "3",
+  "amount": "100000000"
+}
+```
+
+#### POST `/jackpot/build/lock-round`
+
+Lock the round when timer expires (commit phase).
+
+**Request:**
+```json
+{
+  "keeperAddress": "ABC123...",
+  "serverSeed": "optional_32_byte_hex_string",
+  "roundId": null
+}
+```
+
+**Fields:**
+- `keeperAddress` - Keeper's wallet
+- `serverSeed` - Optional secret seed (auto-generated if omitted)
+- `roundId` - Optional, uses current round if omitted
+
+**Response:**
+```json
+{
+  "transaction": "base64_encoded_transaction",
+  "roundId": "3",
+  "serverSeedHash": "abc123...",
+  "serverSeed": "secret123..."
+}
+```
+
+**⚠️ IMPORTANT:** Store `serverSeed` for provably fair verification!
+
+#### POST `/jackpot/build/resolve`
+
+Resolve the round and pay winner.
+
+**Request:**
+```json
+{
+  "keeperAddress": "ABC123...",
+  "roundId": null
+}
+```
+
+**Response:**
+```json
+{
+  "transaction": "base64_encoded_transaction",
+  "roundId": "3",
+  "winner": "DEF456..."
+}
+```
+
+---
+
+### 🤖 Oracle Endpoints
+
+#### POST `/jackpot/oracle/reveal`
+
+Oracle submits random seed (reveal phase). **Server-side only** - requires oracle keypair.
+
+**Request:**
+```json
+{
+  "roundId": "3",
+  "oracleSeed": "optional_32_byte_hex"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "signature": "5x7y...",
+  "roundId": "3",
+  "oracleSeed": "fed789..."
+}
+```
+
+**Note:** In production, `oracleSeed` should come from Random.org API.
+
+---
+
+## Complete Round Flow
+
+### 1. Initialize Protocol (One-time)
+
+```bash
+curl -X POST http://localhost:3001/jackpot/build/initialize \
+  -H "Content-Type: application/json" \
+  -d '{
+    "adminAddress": "YOUR_ADMIN_WALLET",
+    "treasuryAddress": "YOUR_TREASURY_WALLET",
+    "feeBasisPoints": 500,
+    "roundDurationSlots": 1800
+  }'
+```
+
+### 2. Open Round (Keeper)
+
+```bash
+curl -X POST http://localhost:3001/jackpot/build/open-round \
+  -H "Content-Type: application/json" \
+  -d '{"keeperAddress": "YOUR_KEEPER_WALLET"}'
+```
+
+### 3. Players Enter
+
+```bash
+curl -X POST http://localhost:3001/jackpot/build/enter \
+  -H "Content-Type: application/json" \
+  -d '{
+    "playerAddress": "PLAYER_WALLET",
+    "amount": 100000000
+  }'
+```
+
+### 4. Check Round Status
+
+```bash
+curl http://localhost:3001/jackpot/round/current
+```
+
+### 5. Lock Round (Keeper, when timer expires)
+
+```bash
+curl -X POST http://localhost:3001/jackpot/build/lock-round \
+  -H "Content-Type: application/json" \
+  -d '{"keeperAddress": "YOUR_KEEPER_WALLET"}'
+```
+
+**Save the `serverSeed` from response!**
+
+### 6. Oracle Reveals
+
+```bash
+curl -X POST http://localhost:3001/jackpot/oracle/reveal \
+  -H "Content-Type: application/json" \
+  -d '{"roundId": "3"}'
+```
+
+### 7. Resolve Round (Keeper)
+
+```bash
+curl -X POST http://localhost:3001/jackpot/build/resolve \
+  -H "Content-Type: application/json" \
+  -d '{"keeperAddress": "YOUR_KEEPER_WALLET"}'
+```
+
+### 8. Repeat
+
+Go back to step 2!
+
+---
+
+## Frontend Integration Example
+
+```javascript
+import { Connection, Transaction } from '@solana/web3.js';
+
+// Initialize the protocol
+async function initializeJackpot(wallet) {
+  const response = await fetch('http://localhost:3001/jackpot/build/initialize', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      adminAddress: wallet.publicKey.toString(),
+      treasuryAddress: 'YOUR_TREASURY',
+      feeBasisPoints: 500,
+      roundDurationSlots: 1800,
+    }),
+  });
+  
+  const { transaction } = await response.json();
+  
+  // Deserialize and sign
+  const tx = Transaction.from(Buffer.from(transaction, 'base64'));
+  const signed = await wallet.signTransaction(tx);
+  
+  // Send
+  const connection = new Connection('https://api.devnet.solana.com');
+  const signature = await connection.sendRawTransaction(signed.serialize());
+  await connection.confirmTransaction(signature);
+  
+  console.log('✅ Initialized:', signature);
+}
+
+// Enter a round
+async function enterRound(wallet, amountSOL) {
+  const response = await fetch('http://localhost:3001/jackpot/build/enter', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      playerAddress: wallet.publicKey.toString(),
+      amount: amountSOL * 1e9, // Convert SOL to lamports
+    }),
+  });
+  
+  const { transaction, roundId } = await response.json();
+  
+  // Sign and send
+  const tx = Transaction.from(Buffer.from(transaction, 'base64'));
+  const signed = await wallet.signTransaction(tx);
+  const connection = new Connection('https://api.devnet.solana.com');
+  const signature = await connection.sendRawTransaction(signed.serialize());
+  await connection.confirmTransaction(signature);
+  
+  console.log('✅ Entered round', roundId, ':', signature);
+}
+
+// Check current round
+async function getCurrentRound() {
+  const response = await fetch('http://localhost:3001/jackpot/round/current');
+  const { round } = await response.json();
+  
+  console.log('Current Round:', round.roundId);
+  console.log('Status:', round.status);
+  console.log('Pot:', round.totalPotLamports / 1e9, 'SOL');
+  console.log('Entries:', round.entryCount);
+  
+  return round;
+}
+
+// Get entries and odds
+async function getEntries(roundId) {
+  const response = await fetch(`http://localhost:3001/jackpot/round/${roundId}/entries`);
+  const { entries } = await response.json();
+  
+  entries.forEach((entry, i) => {
+    console.log(`${i+1}. ${entry.player.slice(0,8)}... - ${entry.weight / 1e9} SOL (${entry.oddsPercent}% chance)`);
+  });
+  
+  return entries;
+}
+```
+
+---
+
+## Error Responses
+
+All endpoints return errors in this format:
+
+```json
+{
+  "error": "Error message here"
+}
+```
+
+**Common HTTP Status Codes:**
+- `400` - Bad request (validation error)
+- `404` - Resource not found
+- `500` - Server error
+
+---
+
+## Rate Limits
+
+No rate limits currently implemented. Add as needed for production.
+
+---
+
+## Webhooks / Events
+
+To be implemented - will notify when:
+- Round opens
+- Round locks
+- Winner selected
+- Large entries placed
+
+---
+
+## Program Info
+
+- **Program ID**: `bqoSjTSPLweMuqNG6jy39jmzGyZvZdWjsr4csGfD8F6`
+- **Network**: Devnet (update for mainnet)
+- **Oracle**: `FWUJCthDfPcgmTvdQWM5uofxxiYjqJFMMwiLYvS7LBFa`
+- **Min Entry**: 10,000 lamports (0.00001 SOL)
+- **Max Entries**: 1,000 per round
+
+---
+
+## Testing
+
+See `scripts/test-jackpot-api.sh` for complete API test examples.
+
+
+
+