# Wownerogue

Wownerogue is a browser-based roguelike that synchronizes dungeon runs with Monero (XMR) and Wownero (WOW) block timing. The backend is a Node.js/Express server with Socket.IO for realtime play, optional payment enforcement, and automated payouts.

## Overview

- Multiplayer dungeon crawler rendered in the browser
- Three game modes with configurable pricing and payouts
- Optional crypto payments with automatic subaddress management
- **Provably fair** gaming with pre-game hash commitments
- **Live spectator mode** - watch any active game in real-time
- **Persistent chat** with 30-day history for new users
- Configurable difficulty with house edge tuning
- Centralized error handling, rate limiting, and memory management
- Jest coverage for wallet RPC interactions, payment flow, security checks, and game helpers

## Difficulty System

Dungeon difficulty is configurable via presets that control dungeon size, monster behavior, and placement:

| Preset | Dungeon Size | Monster Aggression | Target House Win Rate |
|--------|--------------|--------------------|-----------------------|
| `easy` | 30×15 | Low (60%) | 30% |
| `normal` | 45×22 | Medium (80%) | 55% |
| `hard` | 55×28 | High (90%) | 65% |
| `casino` | 60×30 | Very High (95%) | 70% |

Set `DIFFICULTY_PRESET=casino` in `.env` for paid games. The default automatically selects `casino` for paid modes and `normal` for free play.

## Provably Fair Gaming

Every game uses cryptographic verification to prove fairness:

1. **Pre-game**: Server generates a random seed and shows its SHA-256 hash to the player
2. **During game**: The seed deterministically generates dungeon layout, positions, etc.
3. **Post-game**: Server reveals the seed so players can verify hash(seed) = pre-game commitment
4. **Verification**: Players can regenerate the dungeon using the seed to confirm fairness

This prevents the server from generating unfair dungeons or changing outcomes after seeing payments.

## Spectator Mode

Watch any active game in real-time without joining the queue or paying:

1. Click the **"👁️ Watch Games"** button to see a list of active games
2. Each game shows: player ID, duration, move count, treasure status, and spectator count
3. Click **"Watch Game"** to start spectating
4. Press **ESC** or click **"Leave Spectate"** to exit

**Technical details:**
- Games list auto-refreshes every 3 seconds
- Spectators receive real-time game state updates via Socket.IO rooms
- Pagination supports 100+ simultaneous games
- Spectators cannot interact with the game (input is disabled)
- Game over events are broadcast to spectators with final status

## Chat System

Persistent chat with history for community engagement:

- **30-day message retention** in PostgreSQL with automatic cleanup
- **New users receive last 50 messages** on connect for context
- **Rate limiting** prevents spam (12 messages per 10 seconds)
- **Address detection** recognizes XMR/WOW addresses pasted in chat
- **Commands**: `hello`, `enter`, `cancel`, `confirm`, `address`, `pay`, `stats`

Chat messages are stored in the `chat_messages` table and cached in memory for fast retrieval.

## Game Modes

The unified payment config exposes two monetized modes. They map to the legacy identifiers still exposed over the socket and REST APIs.

| Legacy Identifier | Unified Key | Description | Default Cost¹ | Default Payout |
| --- | --- | --- | --- | --- |
| `FREE` | n/a | Payments disabled. Runs never require a wallet or address. | n/a | n/a |
| `PAID_SINGLE` | `direct` | Per-run charge. Requires a confirmed payout address unless `DIRECT_REQUIRES_ADDRESS=false`. | 1 WOW (1e11 atomic) | 2× escape, 3× escape+treasure |
| `PAID_CREDITS` | `credits` | Credit bundles; each run consumes one credit. Mixed mode allowed when `ALLOW_MIXED_MODE=true`. | 10 credits for 5 WOW (small bundle) | Credits only (payouts disabled) |

¹ Atomic amounts use 11 decimal places (Monero/Wownero standard). Update `DIRECT_GAME_PRICE` or `CREDITS_PACKAGES` to change pricing. Config changes take effect when the snapshot refreshes or the process restarts.

## Payment System

- **Wallet RPC service** (`walletRPCService.js`): Handles subaddress creation, monitors payments, and batches payouts. Errors are wrapped in typed exceptions for consistent handling.
- **Game Mode manager** (`gameModeManager.js`): Applies payment configuration, validates player state, and coordinates payouts.
- **Payment handlers** (`paymentHandlers.js`): Manages request lifecycle, socket notifications, and queue integration.
- **Environment validator** (`config/environmentValidator.js`): Rejects unsafe payment configs and falls back to `FREE` mode when necessary.
- **Address detection** (`network/addressManager.js`): Parses XMR/WOW addresses shared in chat and requests confirmation before storing them.

If the wallet RPC service or configuration is unavailable the backend automatically downgrades to `FREE` mode so players can still start games.

## Backend Components

- `src/index.js`: Express entry point, REST routes, Socket.IO server, payout scheduler.
- `src/network/`: Socket handlers, connection/session management, chat commands, queue logic, rate limiting.
- `src/game/`: Dungeon generation, game state, movement, mode management, lighting/FOV helpers.
- `src/payments/`: Wallet RPC integration and QR code support.
- `src/db/`: PostgreSQL access layer and migration utilities.
- `src/utils/`: Shared utilities including memory management and custom error classes.
- `src/middleware/`: Express async wrapper and error middleware.

## API Surface

### Health & Status

- `GET /health` – Server health check with uptime, memory usage, game counts, and wallet status.
- `GET /api/game-modes` – Current game modes and pricing configuration.

### User Endpoints

- `GET /api/user/:socketId/credits` – Remaining credit balance for a user.
- `GET /api/user/:socketId/mode` – User payment mode preferences and enabled features.
- `POST /api/user/:socketId/address` – Store payout address (body: `{ "address": "<XMR/WOW address>" }`).

### Payment Endpoints (Socket.IO Preferred)

The following REST endpoints exist but return `501 Not Implemented`. Payment flows are handled via Socket.IO events for real-time feedback:

- `POST /api/payment/create` – Use socket event `request_payment` instead.
- `GET /api/payment/status/:paymentId` – Use socket event `payment_status` instead.
- `POST /api/payment/callback` – Reserved for future webhook integration.

### Socket.IO Events (Primary Payment Flow)

| Client → Server | Description |
|-----------------|-------------|
| `request_payment` | Request a payment address for game entry |
| `confirm_address` | Confirm a detected payout address |
| `cancel_address` | Cancel pending address confirmation |
| `join_queue` | Join the game queue after payment |

| Server → Client | Description |
|-----------------|-------------|
| `payment_created` | Payment address and QR code ready |
| `payment_confirmed` | Payment received and confirmed |
| `address_detected` | Payout address detected in chat |
| `address_confirmed` | Payout address saved |
| `game_start` | Game session beginning |
| `credits_update` | Credit balance changed |

All gameplay functions work without wallet RPC access; only paid modes require it.

## Installation

### Prerequisites

- Node.js 16 or newer
- npm
- PostgreSQL 12+
- Optional: Monero/Wownero Wallet RPC endpoints

### Steps

1. Clone and enter the server directory.
   ```bash
   git clone <repository-url>
   cd wownerogue/src
   ```
2. Install dependencies.
   ```bash
   npm install
   ```
3. Configure the environment file.
   ```bash
   cp .env.example .env
   # edit .env to match your database and wallet settings
   ```
4. Provision the database.
   ```bash
   # Create database and user
   npm run db:create
   
   # (Optional) To reset the database later:
   # npm run db:reset
   ```
5. Start the development server.
   ```bash
   npm run dev
   ```

The default Socket.IO client served from `/html` listens on port 3000. Configure a reverse proxy if you need TLS or path routing.

## Production Deployment

### Building for Production

There is no build step required—the Node.js server runs directly. However, ensure you configure the environment correctly:

```bash
# Set production environment
export NODE_ENV=production

# Start the production server
npm start
# Or with explicit environment:
NODE_ENV=production node index.js
```

### Production vs Development

| Feature | Development (`npm run dev`) | Production (`npm start`) |
|---------|----------------------------|-------------------------|
| `NODE_ENV` | development | production |
| Console logging | Verbose | Minimal |
| Error details | Full stack traces | Safe messages only |
| Debug hotkeys | Available | Disabled |
| Simulated blocks | Auto-enabled if no RPC | Requires real daemon |

### Reverse Proxy Setup (Nginx)

For TLS termination and serving the static frontend:

```nginx
upstream wownerogue_backend {
    server 127.0.0.1:3000;
    keepalive 64;
}

server {
    listen 443 ssl http2;
    server_name play.yoursite.com;

    ssl_certificate /etc/letsencrypt/live/play.yoursite.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/play.yoursite.com/privkey.pem;

    # Static files (game client)
    location / {
        root /var/www/wownerogue/html;
        index index.html;
        try_files $uri $uri/ /index.html;
    }
    
    # Admin dashboard (restrict access!)
    location /admin.html {
        # Basic auth or IP whitelist recommended
        # auth_basic "Admin";
        # auth_basic_user_file /etc/nginx/.htpasswd;
        root /var/www/wownerogue/html;
    }

    # API and Socket.IO
    location /socket.io/ {
        proxy_pass http://wownerogue_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400;
    }

    location ~ ^/(health|api|verify) {
        proxy_pass http://wownerogue_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# HTTP redirect
server {
    listen 80;
    server_name play.yoursite.com;
    return 301 https://$server_name$request_uri;
}
```

### Reverse Proxy Setup (Caddy)

Caddy auto-provisions TLS certificates:

```caddyfile
play.yoursite.com {
    root * /var/www/wownerogue/html
    file_server

    # Admin dashboard - consider adding basicauth
    # basicauth /admin.html {
    #     admin $2a$14$hashedpassword
    # }

    # WebSocket and API proxy
    @backend {
        path /socket.io/* /health /api/* /verify/*
    }
    reverse_proxy @backend localhost:3000
}
```

### Process Management (systemd)

Create `/etc/systemd/system/wownerogue.service`:

```ini
[Unit]
Description=Wownerogue Game Server
After=network.target postgresql.service

[Service]
Type=simple
User=wownerogue
WorkingDirectory=/var/www/wownerogue/src
EnvironmentFile=/var/www/wownerogue/src/.env
ExecStart=/usr/bin/node index.js
Restart=on-failure
RestartSec=10

# Hardening
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/var/www/wownerogue/src

[Install]
WantedBy=multi-user.target
```

Enable and start:

```bash
sudo systemctl daemon-reload
sudo systemctl enable wownerogue
sudo systemctl start wownerogue
sudo systemctl status wownerogue
```

### Production Checklist

- [ ] Set `NODE_ENV=production` in `.env`
- [ ] Configure TLS via reverse proxy (Nginx/Caddy)
- [ ] Set up PostgreSQL with proper credentials (not default)
- [ ] Configure Wownero/Monero wallet-rpc with authentication
- [ ] Enable firewall rules (only expose 80/443, not 3000)
- [ ] Set up log rotation for application logs
- [ ] Configure automated database backups
- [ ] Test the full payment flow with real funds
- [ ] Protect `/admin.html` with authentication
- [ ] Review and tune rate limits for expected traffic

## Configuration

Key environment variables (see `.env.example` for the full list):

```bash
# Network selection (Monero only - Wownero only has mainnet)
MONERO_NETWORK=mainnet        # mainnet, stagenet, or testnet
# ⚠️ STAGENET: Stagenet XMR has no value! UI shows warning when not mainnet.

# Difficulty preset
DIFFICULTY_PRESET=casino      # easy, normal, hard, casino (auto-selects for paid modes)

# Unified payments
PAYMENTS_ENABLED=true
PAYMENT_MODES=direct,credits

# Direct (per-run) mode
DIRECT_PAYMENT_ENABLED=true
DIRECT_GAME_PRICE=100000000000       # 1 WOW (atomic units)
DIRECT_REQUIRES_ADDRESS=true
DIRECT_ALLOW_GUEST_PLAY=false
DIRECT_PAYOUTS_ENABLED=true
DIRECT_PAYOUT_ESCAPE=2.0
DIRECT_PAYOUT_TREASURE=3.0

# Credits mode
CREDITS_ENABLED=true
CREDITS_PER_GAME=1
CREDITS_REQUIRES_ADDRESS=true
ALLOW_MIXED_MODE=true
PREFER_CREDITS_FIRST=true
CREDITS_PACKAGES='[{"id":"small","credits":10,"price":"500000000000","bonus":0}]'
CREDITS_PAYOUTS_ENABLED=false
CREDITS_PAYOUT_BASE=50000000000
CREDITS_PAYOUT_ESCAPE=1.5
CREDITS_PAYOUT_TREASURE=2.0

# Payout processing
PAYOUTS_ENABLED=true
PAYOUT_MIN_AMOUNT=10000000000
PAYOUT_MAX_PER_GAME=10000000000000
PAYOUT_BATCH_INTERVAL=300
PAYOUT_MAX_RETRIES=3
MAX_PAYOUT_BATCH_SIZE=50

# Limits
MAX_GAMES_PER_HOUR=60
MAX_PAYOUTS_PER_DAY=100
MAX_CREDIT_PURCHASE_PER_DAY=100000000000000
GAME_COOLDOWN_SECONDS=5

# Legacy override (optional)
GAME_MODE=
SINGLE_GAME_PRICE=100000000000
CREDITS_PACKAGE_PRICE=500000000000

# Wallet RPC
PRIMARY_WALLET_ENDPOINT=http://127.0.0.1:34570
# WALLET_RPC_USER=<rpc-user>
# WALLET_RPC_PASSWORD=<rpc-password>

# Blockchain RPC
PRIMARY_RPC_ENDPOINT=http://127.0.0.1:34568
FALLBACK_RPC_ENDPOINT=http://127.0.0.1:34568
RPC_POLL_INTERVAL=2000

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=wownerogue
DB_USER=jw
DB_PASSWORD=jw

# Server
PORT=3000
NODE_ENV=development

# Block timing overrides
BLOCK_SOURCE=daemon
# SIMULATED_BLOCKS=false
# FORCE_SIMULATED_BLOCKS=false
```

- Amounts are specified in atomic units (1 WOW = 1e11) unless otherwise noted.
- Leave wallet credentials unset to enforce `FREE` mode; payments require RPC access.
- `CREDITS_PACKAGES` must be valid JSON encoded as a single-line string. Adjust the bundle list to match your pricing model.
- The legacy `GAME_MODE`, `SINGLE_GAME_PRICE`, and `CREDITS_PACKAGE_PRICE` variables remain for compatibility but are ignored when `PAYMENT_MODES` is set.

## Payment Flow Summary

**`PAID_SINGLE`**
1. Player requests a paid run.
2. Server creates a subaddress and returns the payment details.
3. Wallet RPC monitors the subaddress and signals confirmation.
4. Game starts; payouts run after successful completion.

**`PAID_CREDITS`**
1. Player buys a ten-run bundle.
2. Credits are recorded in the database on confirmation.
3. Each game consumes one credit; no automatic payouts occur.

**Address confirmation**
1. Player pastes an address in chat.
2. Regex detection flags the message and issues a warning.
3. Player confirms; the address is persisted for payouts.

## Session Persistence

Player sessions are tied to an anonymous token stored in the browser's localStorage. This token persists:

- ✅ **Across page refreshes** – Reconnecting reloads your credits and payout address.
- ✅ **After closing the browser** – The token survives normal browser sessions.
- ✅ **Server restarts** – Session data is stored in PostgreSQL, not memory.

Sessions are **lost** when:

- ⚠️ Clearing cookies or localStorage
- ⚠️ Using private/incognito browsing mode (localStorage may be disabled or ephemeral)
- ⚠️ Switching browsers or devices

**Important notes for players:**

1. Your payout address and credit balance are tied to your session token.
2. If localStorage is unavailable (private browsing), a warning appears next to the "Manage Payout Address" button.
3. There is no account system—your session token *is* your identity. Treat it carefully.

**For deployment:**

- Ensure your reverse proxy preserves WebSocket connections for token handshake.
- The `wownerogue_token` key in localStorage contains the resume token.
- Session data (credits, address) is stored in the `users` table with the token in `anon_token`.

## Testing

Run the Jest suite from `src`:

```bash
npm test
```

Tests cover payment handlers, wallet RPC error propagation, security rules, movement logic, and integration flows. Additional manual scripts live under `test/` for browser debugging and lighting verification.

## Monitoring and Operations

- Rate limiting metrics and in-memory cleanup stats are exposed through server logs and debug views.
- Optional health endpoints provide game counts, queue length, and rate limiter state.
- Structured error handling ensures failed wallet or RPC calls return consistent payloads and are logged with context.

## Socket.IO Events

### Client → Server

| Event | Payload | Description |
|-------|---------|-------------|
| `chat` | `{ id, message }` | Send chat message or command |
| `new game` | – | Request to join queue / start game |
| `cancel queue` | – | Leave the waiting queue |
| `movement` | `{ direction }` | Player movement (0–3 for N/E/S/W) |
| `get_active_games` | `{ page?, limit? }` | Request paginated list of active games |
| `spectate_game` | `{ gameId }` | Start spectating a specific game |
| `leave_spectate` | – | Stop spectating current game |

### Server → Client

| Event | Payload | Description |
|-------|---------|-------------|
| `chat message` | `{ id, message, timestamp }` | Broadcast chat message |
| `chat_history` | `{ messages: [...] }` | Last 50 messages on connect |
| `queue update` | `{ position, total }` | Queue position notification |
| `game started` | `{ gameState }` | Game initialization data |
| `game update` | `{ tiles, player, monsters, ... }` | Game state after movement |
| `game over` | `{ reason, stats }` | Game ended (death/escape/treasure) |
| `active_games` | `{ games, total, page, limit }` | Paginated active games list |
| `spectate_start` | `{ gameId, state }` | Initial state when spectating begins |
| `spectator_update` | `{ gameId, state }` | Real-time game state for spectators |
| `spectate_ended` | `{ gameId, reason }` | Game ended while spectating |

## Repository Layout

```
src/
├── index.js              # Entry point, server setup
├── config/
│   ├── environmentValidator.js
│   └── paymentConfig.js
├── db/
│   ├── databaseManager.js
│   ├── dbcalls.js
│   └── user.js
├── game/
│   ├── dungeon.js
│   ├── game.js
│   ├── gameManager.js
│   ├── gameModeManager.js
│   ├── lightingAndFov.js
│   ├── monster.js
│   ├── movementManager.js
│   └── player.js
├── network/
│   ├── addressManager.js
│   ├── broadcastManager.js
│   ├── chatHandler.js
│   ├── chatHistoryManager.js  # NEW: Persistent chat storage
│   ├── connectionHandler.js
│   ├── paymentHandlers.js
│   ├── queueHandler.js
│   ├── queueManager.js
│   ├── rateLimiter.js
│   ├── sessionManager.js
│   ├── socketHandlers.js
│   └── spectatorManager.js    # NEW: Live game spectating
├── payments/
│   ├── moneroPayService.js
│   ├── qrService.js
│   └── walletRPCService.js
├── rpc/
│   └── rpcService.js
└── utils/
    ├── errors.js
    └── memoryManager.js
html/
├── index.html
├── admin.html
└── js/
    ├── core/
    ├── display/
    ├── input/
    ├── network/
    └── ui/
test/
└── *.test.js
```

Refer to `REFACTORING_SUMMARY.md` for module-by-module details and migration history.

## Architecture Highlights

**Spectator System:**
- Uses Socket.IO rooms (`spectate:{gameId}`, `lobby`) for efficient broadcasting
- Game list cached for 2 seconds to handle 100+ concurrent games
- State broadcasts every 3 seconds plus on every move
- Spectators receive `game update` events identical to players

**Chat History:**
- PostgreSQL `chat_messages` table with 30-day retention
- In-memory cache for fast retrieval
- Automatic cleanup of old messages on startup

**Rate Limiting:**
- Per-IP sliding window for chat (12 messages/10s)
- Connection rate limits with configurable thresholds
- Queue position spam prevention

## Next Steps

- ✅ Implement spectator mode for live game watching
- ✅ Add persistent chat history for new users
- Run full payment integration test with real wallet-rpc
- Configure automated PostgreSQL backups
- Set up log rotation and monitoring alerts
- Load test rate limiting under production traffic patterns