dubs-server 1.0.0

package/documentation/ARCADE_API.md

@@ -0,0 +1,593 @@
+
+
+# 🎮 Arcade Match API Documentation
+
+Complete API reference for the Dubs Arcade Match system - head-to-head arcade game betting.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Getting Started](#getting-started)
+- [API Endpoints](#api-endpoints)
+- [Match Lifecycle](#match-lifecycle)
+- [Example Workflows](#example-workflows)
+- [Error Handling](#error-handling)
+
+---
+
+## Overview
+
+The Arcade Match API allows players to create and join head-to-head arcade game matches with stakes. Supports games like Asteroids and Snake with Best-of-1 or Best-of-3 formats.
+
+### Key Features
+
+- ✅ Create matches with SOL stakes
+- ✅ Join existing matches
+- ✅ Submit game scores
+- ✅ Automated winner determination
+- ✅ Operator fees (1%)
+- ✅ Deadline-based match expiration
+- ✅ Refunds for incomplete matches
+
+### Program Details
+
+- **Program ID**: `EiNzW28xL1a92m1i9T3MyRZqEEszMcVBtrYB3NkphwRq`
+- **Operator Wallet**: `BVZXwZpfgyzTBdRFHohkHZppPHnAyqyctRsKy3vWfQib`
+- **Operator Fee**: 1%
+
+---
+
+## Getting Started
+
+### 1. Start the Arcade Server
+
+```bash
+# Standalone mode (port 3002)
+node arcade-server.js
+
+# Custom port
+PORT=3003 node arcade-server.js
+
+# With custom RPC
+ARCADE_RPC_URL=https://api.devnet.solana.com node arcade-server.js
+```
+
+### 2. Verify Server is Running
+
+```bash
+curl http://localhost:3002/arcade/health
+```
+
+Expected response:
+```json
+{
+  "status": "healthy",
+  "service": "arcade-matches",
+  "programId": "EiNzW28xL1a92m1i9T3MyRZqEEszMcVBtrYB3NkphwRq",
+  "operatorWallet": "BVZXwZpfgyzTBdRFHohkHZppPHnAyqyctRsKy3vWfQib",
+  "timestamp": "2024-01-15T10:30:00.000Z"
+}
+```
+
+---
+
+## API Endpoints
+
+### Base URL
+```
+http://localhost:3002/arcade
+```
+
+### Match Management
+
+#### 1. Create Match
+
+**POST** `/arcade/matches/create`
+
+Create a new arcade match with a stake.
+
+**Request Body:**
+```json
+{
+  "creatorName": "player1",
+  "stake": 100000000,
+  "gameType": "asteroids",
+  "matchType": "bestOf1",
+  "deadlineMinutes": 60
+}
+```
+
+**Parameters:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| creatorName | string | Yes | Player creating the match |
+| stake | number | Yes | Stake amount in lamports (0.1 SOL = 100000000) |
+| gameType | string | No | "asteroids" or "snake" (default: "asteroids") |
+| matchType | string | No | "bestOf1" or "bestOf3" (default: "bestOf1") |
+| deadlineMinutes | number | No | Minutes until match expires (default: 60) |
+
+**Response:**
+```json
+{
+  "success": true,
+  "matchId": "550e8400-e29b-41d4-a716-446655440000",
+  "signature": "3x7ZK...",
+  "matchPDA": "DfXG...",
+  "creator": "7D47y...",
+  "stake": 100000000,
+  "gameType": "asteroids",
+  "matchType": "bestOf1",
+  "deadline": "2024-01-15T11:30:00.000Z"
+}
+```
+
+**cURL Example:**
+```bash
+curl -X POST http://localhost:3002/arcade/matches/create \
+  -H "Content-Type: application/json" \
+  -d '{
+    "creatorName": "alice",
+    "stake": 100000000,
+    "gameType": "asteroids",
+    "matchType": "bestOf1"
+  }'
+```
+
+---
+
+#### 2. Join Match
+
+**POST** `/arcade/matches/:matchId/join`
+
+Join an existing match by matching the stake.
+
+**Request Body:**
+```json
+{
+  "opponentName": "player2"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "matchId": "550e8400-e29b-41d4-a716-446655440000",
+  "signature": "4y8AL...",
+  "opponent": "8FJdh..."
+}
+```
+
+**cURL Example:**
+```bash
+curl -X POST http://localhost:3002/arcade/matches/550e8400-e29b-41d4-a716-446655440000/join \
+  -H "Content-Type: application/json" \
+  -d '{
+    "opponentName": "bob"
+  }'
+```
+
+---
+
+#### 3. Submit Score
+
+**POST** `/arcade/matches/:matchId/score`
+
+Submit a game score for a round.
+
+**Request Body:**
+```json
+{
+  "playerName": "player1",
+  "score": 15000,
+  "gameRound": 1
+}
+```
+
+**Parameters:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| playerName | string | Yes | Player submitting score |
+| score | number | Yes | Game score (0 or higher) |
+| gameRound | number | No | Round number (1-3, default: 1) |
+
+**Response:**
+```json
+{
+  "success": true,
+  "matchId": "550e8400-e29b-41d4-a716-446655440000",
+  "signature": "5z9BM...",
+  "player": "7D47y...",
+  "score": 15000,
+  "gameRound": 1
+}
+```
+
+**cURL Example:**
+```bash
+curl -X POST http://localhost:3002/arcade/matches/550e8400-e29b-41d4-a716-446655440000/score \
+  -H "Content-Type: application/json" \
+  -d '{
+    "playerName": "alice",
+    "score": 15000,
+    "gameRound": 1
+  }'
+```
+
+---
+
+#### 4. Resolve Match
+
+**POST** `/arcade/matches/:matchId/resolve`
+
+Resolve the match and distribute winnings.
+
+**Request Body:**
+```json
+{
+  "callerName": "player1"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "matchId": "550e8400-e29b-41d4-a716-446655440000",
+  "signature": "6A0CN..."
+}
+```
+
+**cURL Example:**
+```bash
+curl -X POST http://localhost:3002/arcade/matches/550e8400-e29b-41d4-a716-446655440000/resolve \
+  -H "Content-Type: application/json" \
+  -d '{
+    "callerName": "alice"
+  }'
+```
+
+---
+
+#### 5. Cancel Match
+
+**POST** `/arcade/matches/:matchId/cancel`
+
+Cancel a match if no opponent joined (after deadline).
+
+**Request Body:**
+```json
+{
+  "creatorName": "player1"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "matchId": "550e8400-e29b-41d4-a716-446655440000",
+  "signature": "7B1DO..."
+}
+```
+
+**cURL Example:**
+```bash
+curl -X POST http://localhost:3002/arcade/matches/550e8400-e29b-41d4-a716-446655440000/cancel \
+  -H "Content-Type: application/json" \
+  -d '{
+    "creatorName": "alice"
+  }'
+```
+
+---
+
+#### 6. Get Match Data
+
+**GET** `/arcade/matches/:matchId`
+
+Retrieve match information from the blockchain.
+
+**Response:**
+```json
+{
+  "success": true,
+  "match": {
+    "matchId": "550e8400-e29b-41d4-a716-446655440000",
+    "pda": "DfXG...",
+    "exists": true,
+    "lamports": 200000000
+  }
+}
+```
+
+**cURL Example:**
+```bash
+curl http://localhost:3002/arcade/matches/550e8400-e29b-41d4-a716-446655440000
+```
+
+---
+
+### Wallet Operations
+
+#### 7. Airdrop SOL
+
+**POST** `/arcade/wallet/airdrop`
+
+Airdrop SOL to a wallet (localnet/devnet only).
+
+**Request Body:**
+```json
+{
+  "playerName": "player1",
+  "amount": 2
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "player": "player1",
+  "pubkey": "7D47y...",
+  "amount": 2,
+  "signature": "8C2EP..."
+}
+```
+
+**cURL Example:**
+```bash
+curl -X POST http://localhost:3002/arcade/wallet/airdrop \
+  -H "Content-Type: application/json" \
+  -d '{
+    "playerName": "alice",
+    "amount": 2
+  }'
+```
+
+---
+
+#### 8. Get Balance
+
+**GET** `/arcade/wallet/:playerName/balance`
+
+Get a player's wallet balance.
+
+**Response:**
+```json
+{
+  "success": true,
+  "player": "player1",
+  "pubkey": "7D47y...",
+  "balance": 1.95,
+  "lamports": 1950000000
+}
+```
+
+**cURL Example:**
+```bash
+curl http://localhost:3002/arcade/wallet/alice/balance
+```
+
+---
+
+## Match Lifecycle
+
+### Phase 1: Match Creation
+1. Player A creates match with stake (e.g., 0.1 SOL)
+2. Match status: **Waiting for Opponent**
+3. Deadline set (e.g., 60 minutes)
+
+### Phase 2: Opponent Joins
+1. Player B joins and matches stake
+2. Match status: **Active**
+3. Deadline extended for gameplay (e.g., +1 hour)
+
+### Phase 3: Score Submission
+1. Both players play the game
+2. Players submit scores for each round
+3. System tracks scores on-chain
+
+### Phase 4: Resolution
+1. When all scores submitted, match can be resolved
+2. Winner determined by:
+   - **Best-of-1**: Highest single score
+   - **Best-of-3**: Best 2 out of 3 rounds
+3. Operator fee (1%) deducted
+4. Winner receives prize pool
+
+### Alternative: Deadline Expiry
+- If deadline passes without all scores:
+  - Both players get refunded
+  - No operator fee charged
+  - Match status: **Cancelled**
+
+---
+
+## Example Workflows
+
+### Example 1: Complete Best-of-1 Match
+
+```bash
+# Step 1: Fund wallets
+curl -X POST http://localhost:3002/arcade/wallet/airdrop \
+  -H "Content-Type: application/json" \
+  -d '{"playerName": "alice", "amount": 2}'
+
+curl -X POST http://localhost:3002/arcade/wallet/airdrop \
+  -H "Content-Type: application/json" \
+  -d '{"playerName": "bob", "amount": 2}'
+
+# Step 2: Alice creates match (0.1 SOL stake)
+curl -X POST http://localhost:3002/arcade/matches/create \
+  -H "Content-Type: application/json" \
+  -d '{
+    "creatorName": "alice",
+    "stake": 100000000,
+    "gameType": "asteroids",
+    "matchType": "bestOf1"
+  }'
+# Save the matchId from response
+
+# Step 3: Bob joins match
+curl -X POST http://localhost:3002/arcade/matches/MATCH_ID/join \
+  -H "Content-Type: application/json" \
+  -d '{"opponentName": "bob"}'
+
+# Step 4: Alice submits score
+curl -X POST http://localhost:3002/arcade/matches/MATCH_ID/score \
+  -H "Content-Type: application/json" \
+  -d '{
+    "playerName": "alice",
+    "score": 15000,
+    "gameRound": 1
+  }'
+
+# Step 5: Bob submits score
+curl -X POST http://localhost:3002/arcade/matches/MATCH_ID/score \
+  -H "Content-Type: application/json" \
+  -d '{
+    "playerName": "bob",
+    "score": 12000,
+    "gameRound": 1
+  }'
+
+# Step 6: Resolve match (Alice wins!)
+curl -X POST http://localhost:3002/arcade/matches/MATCH_ID/resolve \
+  -H "Content-Type: application/json" \
+  -d '{"callerName": "alice"}'
+
+# Step 7: Check balances
+curl http://localhost:3002/arcade/wallet/alice/balance
+curl http://localhost:3002/arcade/wallet/bob/balance
+```
+
+---
+
+### Example 2: Best-of-3 Match
+
+```bash
+# Create and join match (same as above, but matchType: "bestOf3")
+
+# Round 1: Alice wins
+curl -X POST http://localhost:3002/arcade/matches/MATCH_ID/score \
+  -d '{"playerName": "alice", "score": 15000, "gameRound": 1}'
+
+curl -X POST http://localhost:3002/arcade/matches/MATCH_ID/score \
+  -d '{"playerName": "bob", "score": 12000, "gameRound": 1}'
+
+# Round 2: Bob wins
+curl -X POST http://localhost:3002/arcade/matches/MATCH_ID/score \
+  -d '{"playerName": "alice", "score": 10000, "gameRound": 2}'
+
+curl -X POST http://localhost:3002/arcade/matches/MATCH_ID/score \
+  -d '{"playerName": "bob", "score": 18000, "gameRound": 2}'
+
+# Round 3: Alice wins (2-1)
+curl -X POST http://localhost:3002/arcade/matches/MATCH_ID/score \
+  -d '{"playerName": "alice", "score": 20000, "gameRound": 3}'
+
+curl -X POST http://localhost:3002/arcade/matches/MATCH_ID/score \
+  -d '{"playerName": "bob", "score": 14000, "gameRound": 3}'
+
+# Resolve match (Alice wins 2-1)
+curl -X POST http://localhost:3002/arcade/matches/MATCH_ID/resolve \
+  -d '{"callerName": "alice"}'
+```
+
+---
+
+## Error Handling
+
+### Common Errors
+
+#### 400 Bad Request
+```json
+{
+  "error": "Missing required fields: creatorName, stake"
+}
+```
+
+**Causes:**
+- Missing required parameters
+- Invalid values (negative stakes, invalid game types, etc.)
+
+---
+
+#### 404 Not Found
+```json
+{
+  "error": "Match not found"
+}
+```
+
+**Causes:**
+- Invalid match ID
+- Match hasn't been created yet
+
+---
+
+#### 500 Internal Server Error
+```json
+{
+  "error": "Failed to create match"
+}
+```
+
+**Causes:**
+- Blockchain transaction failure
+- Insufficient funds
+- Program constraint violation (e.g., deadline too short, duplicate score submission)
+
+---
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Solana RPC URL
+ARCADE_RPC_URL=http://127.0.0.1:8899
+
+# Server port
+ARCADE_PORT=3002
+
+# Solana network (fallback if ARCADE_RPC_URL not set)
+SOLANA_NETWORK=http://127.0.0.1:8899
+
+# General port (fallback)
+PORT=3002
+```
+
+---
+
+## Integration with Main Server
+
+To integrate arcade routes with the main dubs-server:
+
+```javascript
+// In server.js
+const ArcadeMatchService = require('./services/arcadeMatchService');
+const arcadeRoutes = require('./routes/arcadeRoutes');
+
+const arcadeService = new ArcadeMatchService({
+  rpcUrl: RPC_URL,
+  walletsDir: WALLETS_DIR,
+});
+
+app.use('/arcade', arcadeRoutes(arcadeService));
+```
+
+---
+
+## Support
+
+For issues or questions:
+- Check the main README.md
+- Review the Arcade Program documentation: `docs/ARCADE_MATCH_SYSTEM.md`
+- Contact the development team
+
+---
+
+**🎮 Happy Gaming!**
+