1 System Overview

RPS Arena is a real-time competitive multiplayer game where three players battle using Rock-Paper-Scissors mechanics in a 2D arena. The platform leverages blockchain technology for trustless payments and transparent prize distribution.

Technology Stack

2 System Architecture

High-Level Architecture

Dual-Port Architecture

The server operates on two ports for separation of concerns:

Project Structure

3 Game Mechanics

Core Gameplay

Three players compete in a real-time arena using Rock-Paper-Scissors combat mechanics. Each player is assigned a role (Rock, Paper, or Scissors) and must eliminate opponents by colliding with the role they beat.

Rock-Paper-Scissors Rules

Match Lifecycle

Physics Engine

Swept Circle Collision Detection

The physics engine uses swept circle collision detection to handle fast-moving players. This technique checks for collisions along the entire path of movement, preventing players from passing through each other.

// Collision radius = PLAYER_RADIUS * 2 = 44px
// Bounce distance: 10px standard, 25px large
// Max bounce iterations per tick: 2

function checkCollision(p1, p2, deltaTime) {
  // Calculate relative velocity and trajectory
  const relVel = subtract(p1.velocity, p2.velocity);
  // Solve quadratic for intersection time
  // Returns collision point if within frame
}

Movement System

• Input: WASD or Arrow keys (8 directions + stationary)
• Normalization: Diagonal movement divided by √2 for equal speed
• Boundary: Players clamped to arena bounds minus radius
• Authority: Server-authoritative (client sends input, server calculates)
• Frozen State: Players frozen during countdown and showdown freeze

Spawn System

Players spawn at predetermined positions based on the deterministic RNG seed for the match:

// Spawn position calculation
const spawnPoints = [
  { x: ARENA_WIDTH / 2, y: ARENA_HEIGHT * 0.2 },      // Top center
  { x: ARENA_WIDTH * 0.2, y: ARENA_HEIGHT * 0.8 },    // Bottom left
  { x: ARENA_WIDTH * 0.8, y: ARENA_HEIGHT * 0.8 }     // Bottom right
];
// Positions shuffled using seeded RNG for fairness

4 Showdown Mode

Showdown Mechanics

Showdown Protocol Messages

Heart Object Structure

{
  "id": "heart-1",
  "x": 800,
  "y": 450,
  "captured": false,
  "capturedBy": null
}

Heart Collection Details

// Heart spawn algorithm
function spawnHearts(players) {
  const hearts = [];
  for (let i = 0; i < 3; i++) {
    let pos = findValidPosition({
      minEdgePadding: 100,
      minPlayerDistance: 150,
      minHeartDistance: 100
    });
    hearts.push({ id: `heart-${i}`, x: pos.x, y: pos.y });
  }
  return hearts;
}

5 Real-Time Networking

Network Model

RPS Arena uses an authoritative server model with client-side interpolation:

Reconnection System

Connection Resilience

// Client reconnection with jittered exponential backoff
const baseDelay = 1000;       // 1 second
const maxDelay = 30000;       // 30 seconds
const maxAttempts = 5;

// Jitter prevents "thundering herd" on server restart
const jitter = Math.random() * 0.5 + 0.5;  // 50-100%
const delay = Math.min(baseDelay * Math.pow(2, attempt) * jitter, maxDelay);

Lobby Management

Lobby State Machine

6 WebSocket API Reference

Connection Parameters

const config = {
  pingInterval: 5000,       // 5 seconds
  maxMessageSize: 16384,    // 16 KB
  connectionTimeout: 10000, // 10 seconds
};

Client to Server Messages

Server to Client Messages

Error Codes

7 REST API Reference

Public Endpoints

Admin Endpoints (Port 3001 Only)

8 Database Schema

Configuration

Core Tables

users

id TEXT PRIMARY KEY, wallet_address TEXT UNIQUE, username TEXT, created_at TEXT, updated_at TEXT

sessions

id TEXT PRIMARY KEY, user_id TEXT, token TEXT UNIQUE, created_at TEXT, expires_at TEXT

lobbies (12 fixed)

id INTEGER PRIMARY KEY (1-12), status TEXT, deposit_address TEXT, deposit_private_key_encrypted TEXT, first_join_at TEXT, timeout_at TEXT, swept_at TEXT, current_match_id TEXT

lobby_players

id TEXT PRIMARY KEY, lobby_id INTEGER, user_id TEXT, payment_tx_hash TEXT, payment_confirmed_at TEXT, refund_tx_hash TEXT, refund_reason TEXT, refunded_at TEXT, joined_at TEXT

matches

id TEXT PRIMARY KEY, lobby_id INTEGER, status TEXT (countdown|running|finished|void), winner_id TEXT, rng_seed TEXT, created_at TEXT, countdown_at TEXT, running_at TEXT, ended_at TEXT, payout_amount INTEGER, payout_tx_hash TEXT

match_players

id TEXT PRIMARY KEY, match_id TEXT, user_id TEXT, role TEXT (rock|paper|scissors), spawn_x REAL, spawn_y REAL, eliminated_at TEXT, eliminated_by TEXT, final_x REAL, final_y REAL

match_state (Crash Recovery)

match_id TEXT PRIMARY KEY, version TEXT, tick INTEGER, status TEXT, state_json TEXT, updated_at TEXT

match_events (Audit)

id TEXT PRIMARY KEY, match_id TEXT, tick INTEGER, event_type TEXT (start|elimination|bounce|disconnect|end), data TEXT (JSON), created_at TEXT

player_stats (Denormalized)

wallet_address TEXT PRIMARY KEY, username TEXT, profile_photo TEXT, total_matches INTEGER, wins INTEGER, losses INTEGER, total_earnings_usdc INTEGER, total_spent_usdc INTEGER, current_win_streak INTEGER, best_win_streak INTEGER, first_match_at TEXT, last_match_at TEXT, updated_at TEXT

payout_attempts (Audit)

id TEXT PRIMARY KEY, match_id TEXT, lobby_id INTEGER, recipient_address TEXT, amount_usdc INTEGER, attempt_number INTEGER, status TEXT (pending|success|failed), tx_hash TEXT, error_message TEXT, error_type TEXT (transient|permanent), source_wallet TEXT, treasury_balance_before INTEGER, created_at TEXT

reserved_usernames

username TEXT PRIMARY KEY, reserved_by TEXT, reserved_at TEXT

paid_wallets (Airdrop Tracking)

wallet_address TEXT PRIMARY KEY, first_payment_at TEXT, last_payment_at TEXT, total_payments INTEGER

Indexes (30+)

Composite indexes optimized for: user lookups, session validation, lobby status queries, leaderboard (wins DESC, earnings DESC), match history (user + date), time-filtered stats (monthly/weekly).

9 Resilience & Error Handling

Database Resilience

Crash Recovery

RPC Fallback System

// RPC provider priority order:
1. Primary: BASE_RPC_URL (Alchemy/Infura)
2. Fallback: base.publicnode.com
3. Fallback: 1rpc.io/base
4. Fallback: mainnet.base.org

// Health checks every 60 seconds
// Tests: block number retrieval + latency
// Auto-failover on provider failure

Payment Error Handling

Game Loop Health Monitoring

• Health checks every 2 seconds
• Max staleness: 2 seconds (60 ticks at 30Hz)
• Consecutive error tracking per match
• Automatic void on unrecoverable errors

10 Blockchain Integration

Network Configuration

Wallet Architecture

// BIP-44 derivation path
const path = "m/44'/60'/0'/0/{index}";

// Treasury wallet: index 0 (from TREASURY_MNEMONIC)
// Lobby wallets: indices 1-12 (from LOBBY_WALLET_SEED)

// Private key encryption: AES-256-GCM
// Format: iv:authTag:ciphertext (hex-encoded)

Payment Verification

• Transaction confirmed with 3+ blocks
• Transaction age less than 1 hour
• Recipient matches lobby deposit address
• Amount exactly equals 1,000,000 (1 USDC)
• Token contract matches USDC address
• Transaction hash not previously used

Wallet Sweeping

After match completion, lobby wallets are swept to treasury:

• Recovers leftover USDC from deposits
• Recovers ETH for gas replenishment
• Triggered after winner payout
• Maintains treasury balance for future payouts

Low Balance Alerts

Discord alerts triggered when wallet ETH balance falls below 0.001 ETH.

11 Authentication System

SIWE (Sign-In with Ethereum)

Session Management

Wallet Support (EIP-6963)

Multi-wallet detection supporting: MetaMask, Rabby, Coinbase Wallet, Trust Wallet, and any EIP-6963 compatible wallet. Fallback to window.ethereum for legacy support.

12 Player Profiles

Profile Features

Statistics Tracked

• Total matches, wins, losses
• Win rate (calculated: wins / total_matches * 100)
• Current win streak, best win streak
• Total earnings (USDC), total spent (USDC)
• Net profit (earnings - spent)
• First match date, last match date

Leaderboards

13 Security Architecture

Security Layers

Validation Patterns

// Transaction hash validation
const TX_HASH_REGEX = /^0x[a-fA-F0-9]{64}$/;

// Admin/bot tx patterns (port 3001 only)
const ADMIN_TX_REGEX = /^0x(dev_|bot_tx_)[a-zA-Z0-9_]+$/;

// Username validation
const USERNAME_REGEX = /^[a-zA-Z0-9_]{3,20}$/;

// Wallet address validation (EIP-55 checksummed)
ethers.isAddress(address);

14 Bot System (Admin Only)

Bot Features

• Created with fake wallet addresses: 0xbot{counter}
• Unique fake tx hashes: 0xbot_tx_{timestamp}_{userId}
• AI movement targeting enemies and hearts
• Full match participation
• Marked as isBot: true in state

Bot Movement AI

// Bot targeting logic
if (showdownMode) {
  target = nearestUncapturedHeart;
} else {
  target = enemyThatBotCanBeat;
}
moveTowardTarget(bot, target);

15 Client Architecture

Module Structure

Screen States

Player Rendering

• Shape: Circle with role-specific color and border
• Colors: Rock = Orange (#FFA500), Paper = Blue (#1E90FF), Scissors = Green (#2ECC71)
• Size: 22px radius
• Effects: Glow for local player, fade + indicator for disconnected players
• Labels: Username rendered above player circle
• Preview Phase: Pulsing highlight effect during 3-second preview

16 Testing Infrastructure

Test Suites

npm Scripts

npm start              # Production server
npm run dev            # Development with nodemon
npm run init-db        # Manual database initialization
npm run test:security  # Security tests (--production flag available)
npm run test:load      # Load testing
npm run test:e2e       # End-to-end testing

17 Deployment Guide

Railway Configuration

Health Check Response

{
  "status": "healthy",
  "database": { "connected": true, "journalMode": "wal" },
  "deferredQueue": { "size": 0 },
  "gameLoop": { "healthy": true, "activeMatches": 2 }
}

Server Initialization Sequence

On startup, the server initializes components in this order:

1. Sentry: Initialize error tracking (if DSN configured)
2. Database: Initialize SQLite with WAL mode, run migrations
3. Lobby Wallets: Derive 12 HD wallets from seed, encrypt private keys
4. Lobbies: Create/verify 12 lobby records with deposit addresses
5. Match Recovery: Check for interrupted matches, void stale ones, refund players
6. HTTP Servers: Start Express on PORT (production) and ADMIN_PORT (admin)
7. WebSocket Servers: Attach WS handlers to both HTTP servers
8. RPC Provider: Initialize ethers.js with primary RPC, test connection
9. Health Monitor: Start game loop health checks (2s interval)
10. RPC Monitor: Start RPC health checks (60s interval)
11. Session Cleanup: Schedule hourly expired session cleanup
12. Backup Scheduler: Start hourly database backup job
13. Discord Alert: Send SERVER_START notification

Graceful Shutdown

On SIGTERM/SIGINT, the server shuts down in this order:

1. Stop accepting new HTTP connections
2. Stop accepting new WebSocket connections
3. Wait for in-progress payouts to complete (5s max)
4. Close existing WebSocket connections with code 1001
5. Send SERVER_SHUTDOWN Discord alert
6. Flush Sentry events (2s timeout)
7. WAL checkpoint and close database connection
8. Exit with code 0

Monitoring

Backup System

• Automated hourly backups (configurable)
• WAL checkpoint before each backup
• Integrity verification via PRAGMA integrity_check
• Retain last 24 backups (configurable)
• Stored in ./backups/ directory

18 Configuration Reference

Required Environment Variables

Optional Environment Variables