chore: prepare the repository for public release

Removes operator-private material from the shipped tree, corrects documentation
that had drifted from the code, deletes dead code, and applies a consistent
prose style.

Private material moved out of the public tree (docs/private/, git-ignored):
  - the wallet keyfile recovery runbook and its helper scripts, which together
    published the mainnet wallet file path, the service account, backup snapshot
    filenames, and the wallet RPC listener state. The helper duplicated the same
    constants, so relocating the document alone would not have removed them.
  - the stagenet parallel-candidate runbook and its fixtures.
  - the dated production-state record, the internal remediation plan, and the
    TODO list. None are reference documentation for an outside reader.

Redacted or genericised:
  - operator home-directory paths in shipped scripts and units. The asset build
    script now takes KENNEY_ASSETS_DIR instead of a hard-coded path.
  - private LAN addresses in tests, env examples and deploy docs, replaced with
    RFC 5737 documentation addresses.
  - the default alert sender and the notification hub example.
  - the Monero wallet unit now matches the Wownero one: a dedicated service
    account and a config file, instead of the operator's login account with the
    wallet password in argv where any local user can read it from /proc.

Ignore rules now cover every .env variant rather than the bare name, plus local
agent state. The deployment docs instruct operators to create .env.mainnet and
.env.stagenet, which the exact-name rule would have allowed to be committed.

Documentation corrected against the code: per-chain dungeon level counts, the
premium unlock rule, Tavern chat scope, backup retention, the chain-profile
fallback, the environment template location, and several sections describing
shipped work as pending.

Dead code removed: configPersistence, rpccalls, a duplicate vendored ROT.js
bundle, the unused tile-picker overlay, the unreachable legacy game-size path
and its vestigial parameter, spectator stubs that shadowed the real
SpectatorManager, and commented-out debugging. nip98 now imports the shared
nostr loader rather than duplicating it.

Prose style: em-dashes removed throughout in favour of colons, semicolons and
commas; comments restated as present-tense descriptions of the code rather than
narration of past changes.

127 suites / 1015 tests pass.
This commit is contained in:
jwinterm
2026-07-27 06:40:38 -04:00
parent 1cbbae73b2
commit ed24d43b56
207 changed files with 5023 additions and 8332 deletions
+295 -123
View File
@@ -1,6 +1,9 @@
# Wownerogue
A browser-based roguelike synchronized with Monero (XMR) and Wownero (WOW) block timing. The same codebase runs the original solo dungeon, the social Tavern, and operator-selected PvP/race rulesets, with separate free and paid leaderboards.
A browser-based roguelike synchronized with crypto block timing. A run is a race against the next
block: reach the exit before the block lands, or the house wins. The same codebase runs the solo
dungeon, the social Tavern, and operator-selected PvP/race rulesets, with separate free and paid
leaderboards.
## Such Software-operated products
@@ -11,30 +14,37 @@ Such Software (`apps@such.software`) operates only these two public products:
| `play.wowne.ro` | Wownero mainnet free play and pay-for-credits leaderboard/prestige play. Credits are non-redeemable; there are no prizes, cash-out, or payouts, and the service is not offered or marketed as gambling. Legal classification depends on applicable law. |
| `monerogue.app` | Monero **stagenet only**, with direct solo entry only. Single-player 2×/3× outcomes are test gambling mechanics using test coins with **NO REAL VALUE**. Purchased-credit entry and crypto-match payouts are off. Never send mainnet XMR. |
The repository remains generally self-hostable under the MIT License. A third-party operator is
solely responsible for its deployment, product, legal compliance, funds, players, claims, and
support. Such Software does not operate, supervise, endorse, or accept responsibility for a
third-party deployment.
The repository is self-hostable under the MIT License. A third-party operator is solely responsible
for its deployment, product, legal compliance, funds, players, claims, and support. Such Software
does not operate, supervise, endorse, or accept responsibility for a third-party deployment.
## Features
- **Provably fair** solo runs with two-party, pre-entry commitments and per-depth fingerprints
- **Live spectator mode** - watch active games in real-time
- **Persistent chat** with 30-day history
- **Transaction history** - view payment and payout records
- **Multiple game modes**: Free play, per-game payments, or credit bundles
- **Provably fair solo runs** with two-party, pre-entry seed commitments and per-depth layout
fingerprints
- **Multi-level descent** whose depth scales with the chain's block time
- **Live spectator mode**: watch active games in real time
- **Persistent chat** with a rolling 7-day server-side history
- **Transaction history**: payment and payout records per session
- **Multiple entry economies**: free play, per-run chain payment, or purchased credit bundles
- **Anonymous social Tavern** (no account required) with chat, live solo spectating, and in-place
race queues
- **Shared render kit** with Tiled, ASCII, Iso, and locally served 3D techniques across the dungeon
and Tavern
- **Real-time multiplayer races**: free, prestige-credit, or crypto winner-take-pot races every block
- Configurable difficulty with house edge tuning
- Automatic wallet RPC integration for payments and payouts
- **Shared render kit** with Tiled, ASCII, Iso, and 3D techniques across the dungeon and Tavern,
driven by an operator-owned cosmetic catalog
- **Real-time multiplayer races** (optional): free, prestige-credit, or crypto winner-take-pot
races on a per-block cadence
- **Wallet RPC integration** for payment address issuance, payment detection, and batched payouts
## Requirements
- Node.js >= 22, npm >= 10
- PostgreSQL
- A Wownero or Monero wallet RPC endpoint (only required for paid modes)
## Quick Start
```bash
git clone <repository-url>
git clone https://github.com/Such-Software/wownerogue.git
cd wownerogue/src
npm install
cp .env.example .env # Edit with your database/wallet settings
@@ -42,47 +52,55 @@ npm run db:create # Initialize PostgreSQL
npm run dev # Start development server
```
Open http://localhost:3000 to play.
Open http://localhost:3000 to play. `src/.env.example` is the full, annotated environment
template; the file at the repository root is a two-flag stub, not a starting point.
---
## Game Modes
`GAME_MODE` selects the solo entry economy for an instance.
| Mode | Cost | Payout | Leaderboard |
|------|------|--------|-------------|
| **FREE** | None | None | Pleb |
| **PAID_SINGLE** | Per-run chain payment | Profile-controlled | Paid prestige |
| **PAID_CREDITS** | Purchased credit | Profile-controlled | Paid prestige |
| `FREE` | None | None | Pleb |
| `PAID_SINGLE` | Per-run chain payment | Profile-controlled | Paid prestige |
| `PAID_CREDITS` | Purchased credit | Profile-controlled | Paid prestige |
The exact Such Software production profiles are `src/.env.mainnet.example` (credits only, every
payout path off) and `src/.env.stagenet.example` (direct-entry-only stagenet 2×/3× solo test
payouts, purchased credits and crypto-match payouts off). Each opts into a startup contract with
The Such Software production profiles are `src/.env.mainnet.example` (credits only, every payout
path off) and `src/.env.stagenet.example` (direct-entry-only stagenet 2×/3× solo test payouts,
purchased credits and crypto-match payouts off). Each opts into a startup contract with
`OPERATED_PRODUCT_PROFILE`; preflight refuses network, operator-identity, or economic-scope drift.
Generic self-hosts leave that variable unset.
Generic self-hosts leave that variable unset and are not constrained by those product decisions.
## Match Mode (Multiplayer Races)
Optional real-time multiplayer races are available when `MATCH_ENABLED=true`. A new race starts every
crypto block as long as at least two players are queued. Supported economies:
Real-time multiplayer races run when `MATCH_ENABLED=true`. A new race starts every crypto block as
long as at least two players are queued. Supported economies:
| Economy | Entry | Payout | Leaderboard |
|---|---|---|---|
| **Free** | None | None | Pleb |
| **Prestige Credits** | Credits | None | Prestige |
| **Crypto Race** | Race-entry ticket | Winner-take-pot minus house fee | Hall of Champions |
| Free | None | None | Pleb |
| Prestige Credits | Credits | None | Prestige |
| Crypto Race | Race-entry ticket | Winner-take-pot minus house fee | Hall of Champions |
See `docs/MATCH_MODE.md` for full architecture, configuration, and API details.
`MATCH_ENABLED` gates the creation of new rooms only; settlement reconciliation for existing rooms
runs regardless, so disabling it cannot strand an in-flight match. The Tavern's in-place race queue
additionally requires `TAVERN_ENABLED=true`.
For deterministic multi-bot playtesting and 16:9/9:16 ad footage, use the loopback-only,
free-only capture harness documented in [`docs/PVP_CAPTURE.md`](docs/PVP_CAPTURE.md). It drives the
real match engine over Socket.IO but cannot connect to a deployment, database, wallet, or payout path.
See [`docs/MATCH_MODE.md`](docs/MATCH_MODE.md) for architecture, configuration, and API details, and
[`docs/RULESETS.md`](docs/RULESETS.md) for the Escape Race, Last Alive, Score Attack, and Co-op
Escape rulesets.
## Difficulty & Pacing
For deterministic multi-bot playtesting and 16:9/9:16 ad footage, use the loopback-only, free-only
capture harness documented in [`docs/PVP_CAPTURE.md`](docs/PVP_CAPTURE.md). It drives the real match
engine over Socket.IO but cannot connect to a deployment, database, wallet, or payout path.
Difficulty has two levers, both keyed to the crypto network so `cryptoType` actually shapes the
game (it used to be a dead parameter).
## Difficulty and Pacing
**Presets** (`DIFFICULTY_PRESET`) — the per-level shape:
Difficulty has two levers, both keyed to the crypto network, so `cryptoType` shapes the game.
**Presets** (`DIFFICULTY_PRESET`) set the per-level shape:
| Preset | Dungeon Size | Monster | Target House Win |
|--------|--------------|---------|------------------|
@@ -91,60 +109,110 @@ game (it used to be a dead parameter).
| `hard` | 55×28 | high | ~65% |
| `casino` | 70×35 | very high | ~70% |
Defaults to `normal` for free play, `casino` for paid. Every knob is `env`-overridable
(`DUNGEON_WIDTH`, `MONSTER_SPEED`, …).
An instance with `GAME_MODE=FREE` and payments off defaults to `normal`; paid modes default to
`casino`. Every knob is env-overridable (`DUNGEON_WIDTH`, `DUNGEON_HEIGHT`, `MONSTER_SPEED`, and so
on).
**Multi-level depth (`levels`) — the pacing lever, ∝ block time.** A run *descends* N levels (each a
preset-sized dungeon with a fair monster). Reaching a non-final exit takes the stairs down; only the
final exit escapes; the treasure sits in the vault (final level). Because total run length scales
with the chain's block time, the "race the block" **timer** provides the house edge — no giant map,
no cheating-fast monster.
**Multi-level depth (`levels`)** is the pacing lever and scales with block time. A run descends N
levels, each a preset-sized dungeon with a fair monster. A non-final exit takes the stairs down;
only the final exit escapes, and the treasure sits in the vault on the final level. Because total
run length scales with the chain's block time, the block timer supplies the house edge without a
giant map or a monster that moves faster than the player.
| Chain | Block time | Levels |
|-------|-----------|--------|
| Chain | Mean block time | Levels |
|-------|-----------------|--------|
| GRIN | ~1 min | 1 |
| XMR | ~2 min | 2 |
| XMR | ~2 min | 1 |
| LTC | ~2.5 min | 2 |
| WOW | ~5 min (measured) | 4 |
| BTC | ~10 min | 8 |
| WOW | ~5 min | 2 |
| BTC | ~10 min | 3 |
Levels live in `NETWORK_TUNING` (`src/game/difficultyConfig.js`); override with `DUNGEON_LEVELS`,
disable with `NETWORK_TUNING_DISABLED=true`. The counts are sim-derived starting points — see
[`docs/BALANCE_SIM.md`](docs/BALANCE_SIM.md) for how the balance is measured and calibrated.
Level counts live in `NETWORK_TUNING` (`src/game/difficultyConfig.js`). Precedence, low to high:
preset, per-network tuning, env vars, explicit call-site overrides. Override the count with
`DUNGEON_LEVELS`; disable per-network tuning entirely with `NETWORK_TUNING_DISABLED=true`.
> **Note:** Wownero's block time is **~5 min** (measured on the live daemon), not 2 min as older
> docs/comments claimed.
Wownero's mean block time is ~5 minutes measured against the live daemon, which places it closer to
Bitcoin than to Monero for calibration purposes. Mean block times per chain are declared once in
`src/chain/chainProfile.js`. See [`docs/BALANCE_SIM.md`](docs/BALANCE_SIM.md) for how balance is
measured and calibrated, and [`docs/MULTI_LEVEL.md`](docs/MULTI_LEVEL.md) for the descent mechanic.
---
## Key Features
## Chain Profiles
### Provably Fair Gaming
`src/chain/chainProfile.js` is the single source for everything chain-specific that is not an RPC
call: decimals and atomic divisor, mean block time, adapter family, and payment URI scheme.
1. The server publishes a one-use, socket-bound SHA-256 commitment before paid entry.
2. The browser adds an independent WebCrypto client seed; neither side alone selects the final seed.
3. The effective seed deterministically generates each dungeon depth and its audit fingerprint.
4. After completion, the server seed and depth manifest are revealed at `/verify/:gameId` and
`/api/verify/:gameId`; active-game server seeds remain private.
| Chain | Decimals | Mean block time | Family | URI scheme |
|-------|----------|-----------------|--------|------------|
| WOW | 11 | 300000 ms | monero | `wownero` |
| XMR | 12 | 120000 ms | monero | `monero` |
| BTC | 8 | 600000 ms | utxo | `bitcoin` |
| LTC | 8 | 150000 ms | utxo | `litecoin` |
| GRIN | 9 | 60000 ms | mimblewimble | `grin` |
### Spectator Mode
An unrecognized `CRYPTO_TYPE` resolves to a fallback profile shaped like XMR (12 decimals, 120000 ms
mean block time, monero family) so callers never crash on a mis-set value. Adding a chain means one
entry here plus a family adapter.
Click **"👁️ Watch Games"** to see active games. Spectators receive real-time updates via Socket.IO rooms. Press ESC to exit.
Note that WOW uses 11 decimals, not Monero's 12: 1 WOW = 10^11 atomic units.
### Transaction History
---
Click **"📜 History"** to view your payment and payout records. Shows:
- Total received from payouts
- Payment history with status and credits received
- Payout history with multipliers and transaction hashes
## Provably Fair Gaming
### Session Persistence
1. The server publishes a one-use, socket-bound SHA-256 commitment to a secret server seed before
the client chooses its contribution. Issuance is separate from consumption, so the server cannot
grind its seed after seeing the player's.
2. The browser adds an independent WebCrypto client seed. Neither side alone selects the final
seed.
3. The effective seed is `HMAC-SHA256(serverSeed, clientSeed)` and deterministically generates each
dungeon depth along with its audit fingerprint.
4. After completion, the server seed and the per-depth layout manifest are revealed at
`/verify/:gameId` and `/api/verify/:gameId`. Server seeds for active games stay private.
Sessions, including anonymous Tavern entry, use an anonymous token stored in localStorage:
- ✅ Persists across refreshes, browser closes, server restarts
- ⚠️ Lost when clearing cookies/localStorage, using incognito mode, or switching browsers/devices
The proof covers layout generation. Outcome execution is a separate server-authoritative concern:
without a signed input/event transcript, the proof does not independently replay block timing,
player moves, monster turns, the declared result, or payout delivery.
A warning appears if localStorage is unavailable.
## Spectator Mode
The **WATCH GAMES** control lists active games. Spectators receive real-time updates via Socket.IO
rooms. Press ESC to exit.
## Transaction History
The **History** control shows the session's payment and payout records: total received from payouts,
payment history with status and credits received, and payout history with multipliers and
transaction hashes.
## Session Persistence
Sessions, including anonymous Tavern entry, use an anonymous token stored in `localStorage`:
- Persists across refreshes, browser closes, and server restarts.
- Lost when clearing cookies or `localStorage`, using incognito mode, or switching browsers or
devices.
A warning appears if `localStorage` is unavailable.
## Rendering and Cosmetics
The shared render kit provides four techniques: Tiled, ASCII, Iso, and 3D. Three.js is served from
the application's own origin under a versioned, immutable `/vendor/three/<version>` path, which
keeps it inside the production CSP. Setting `RENDERER_CDN_ENABLED=true` opts into third-party CDN
delivery instead and logs a warning in production.
Cosmetic packs are gated per pack, not by a blanket "has paid" flag. Each catalog entry carries a
tier and an optional lifetime-credits-purchased threshold, and a pack unlocks when either the user's
subscription tier reaches the pack's tier or their cumulative purchased credits reach its threshold.
Purchased credits are not deducted by unlocking. The default ladder is `original` (free), then
thresholds at 1, 5, 10, 20, 40, and 50 lifetime credits. In production the catalog is owned by the
`cosmetic_catalog` database table; the object in `src/multiplayer/entitlements.js` is the fallback
used when that table is unavailable.
See [`docs/RENDER_PACKS.md`](docs/RENDER_PACKS.md) and
[`docs/MONETIZATION.md`](docs/MONETIZATION.md).
---
@@ -158,25 +226,48 @@ A warning appears if localStorage is unavailable.
| `GET /health/live` | Process liveness probe |
| `GET /health/ready` | Dependency readiness probe (503 while degraded) |
| `GET /api/game-modes` | Current modes and pricing |
| `GET /api/leaderboard?board=pleb\|champions\|prestige&period=all\|week\|month` | One explicitly separated score board; an omitted `board` means `pleb`, while legacy `all`, blank, and unknown board values return 400 |
| `GET /api/user/:socketId/credits` | User credit balance |
| `GET /api/stats` | Public activity counters (short-lived cache, live online count) |
| `GET /api/disclosures` | Active commerce disclosure text for the running profile |
| `GET /api/leaderboard?board=pleb\|champions\|prestige&period=all\|week\|month` | One explicitly separated score board. An omitted `board` means `pleb`; legacy `all`, blank, and unknown board values return 400. An unknown `period` falls back to `all`. |
| `GET /api/user/:socketId/credits` | Credit balance |
| `GET /api/user/:socketId/mode` | Resolved entry mode for the user |
| `GET /api/user/:socketId/payment-options` | Available entry/payment options |
| `GET /api/user/:socketId/payments` | Payment history (paginated) |
| `GET /api/user/:socketId/payouts` | Payout history (paginated) |
| `POST /api/user/:socketId/address` | Set payout address |
| `POST /api/payment/create` | Create a payment request |
| `GET /api/payment/status/:paymentId` | Payment status |
| `GET /verify/:gameId` | Human-readable fairness verification page |
| `GET /api/verify/:gameId` | Machine-readable fairness proof |
| `GET /api/verify?serverSeed=&clientSeed=&effectiveSeed=&commitment=` | Stateless proof check for values you already hold |
`/`, `/tavern`, `/admin`, `/terms`, `/privacy`, and `/responsible-play` serve pages rather than JSON.
### Admin Endpoints
Require `X-Admin-Key` header matching `ADMIN_API_KEY` env variable.
Require an `X-Admin-Key` header matching the `ADMIN_API_KEY` environment variable.
| Endpoint | Description |
|----------|-------------|
| `POST /api/admin/refund/payment` | Request an idempotent refund; consumed grants require review |
| `POST /api/admin/credits/adjust` | Add or remove credits from a user |
| `POST /api/admin/payouts/:id/retry` | Retry a failed payout |
| `GET /api/admin/users` | List users |
| `GET /api/admin/users/search` | Search users by socket ID or address |
| `GET /api/admin/users/:id` | User detail |
| `POST /api/admin/users/:id/chat-ban` | Apply or lift a chat ban |
| `GET /api/admin/chat` | Recent chat messages |
| `DELETE /api/admin/chat/:id` | Remove a chat message |
| `GET /api/admin/queue` | Inspect the entry queue |
| `POST /api/admin/queue/remove` | Remove an entry from the queue |
| `GET /api/admin/stats/overview` | Aggregate service stats |
| `GET /api/admin/stats/games` | Game stats |
| `GET /api/admin/stats/payouts` | Payout stats |
| `GET /api/admin/stats/refunds` | Refund stats |
| `POST /api/admin/alerts/test-email` | Send a test alert email |
**Example: refund a payment**
**Example: Refund a payment**
```bash
curl -X POST http://localhost:3000/api/admin/refund/payment \
-H "Content-Type: application/json" \
@@ -184,7 +275,8 @@ curl -X POST http://localhost:3000/api/admin/refund/payment \
-d '{"paymentId": 123, "reason": "Customer request", "sendFunds": true}'
```
**Example: Adjust credits**
**Example: adjust credits**
```bash
curl -X POST http://localhost:3000/api/admin/credits/adjust \
-H "Content-Type: application/json" \
@@ -192,48 +284,92 @@ curl -X POST http://localhost:3000/api/admin/credits/adjust \
-d '{"socketId": "abc123", "amount": 5, "reason": "Compensation"}'
```
`amount` must be a non-zero safe integer in [-1000000, 1000000]; negative adjustments are applied
atomically and cannot drive a balance below zero.
### Socket.IO Events
**Client → Server**
| Event | Description |
|-------|-------------|
| `auto_start` | Start game (uses credits if available) |
| `player_move` | Move player (direction: 0-3) |
| `request_payment` | Request payment address |
| `get_active_games` | List games for spectating |
| `spectate_game` | Start spectating a game |
**Client to server**
**Server → Client**
| Event | Description |
|-------|-------------|
| `register_client` | Bind the socket to a session token and receive identity/state |
| `fairness_offer_request` | Request a fresh server-seed commitment |
| `auto_start` | Start a run, using credits when available |
| `play_free` | Start a free run |
| `join_queue` | Join the next-block entry queue |
| `early_entry` | Enter the current block instead of waiting for the next |
| `player_move` | Move the player (direction 0-3) |
| `request_payment` | Request a payment address |
| `check_payment_status` | Poll a pending payment |
| `get_user_credits` | Request the current credit balance |
| `get_active_games` | List games available for spectating |
| `spectate_game` / `leave_spectate` | Enter and leave spectator mode |
| `chat_signed` / `chat_game_queue` | Send a signed chat message; queue chat-driven entry |
| `tavern_join` / `tavern_leave` / `tavern_move` / `tavern_chat` / `tavern_match_list` | Tavern presence, movement, chat, and race listing |
| `match_queue` / `match_move` / `match_leave` / `match_reconnect` | Multiplayer race queue and play |
**Server to client**
| Event | Description |
|-------|-------------|
| `socket_registered` / `session_token` / `session_resumed` | Session lifecycle |
| `fairness_offer` / `fairness_error` | Seed commitment issuance |
| `game_start` | Game initialized with dungeon state |
| `game_update` | State after movement (incl. `depth`/`maxDepth` for multi-level descent) |
| `game_event` | Discrete event: `treasure_found`, `descend` (took the stairs down), `escaped` |
| `game_over` | Game ended |
| `payment_created` | Payment address ready |
| `game_update` | State after movement, including `depth` and `maxDepth` for multi-level descent |
| `game_event` | Discrete in-run event: `descend`, `treasure_found`, `escaped`, `monster_caught` |
| `game_over` | Run ended |
| `game_settlement_pending` | Result recorded, settlement still in flight |
| `payment_created` / `payment_detected` / `payment_confirmed` / `payment_underpaid` / `payment_error` | Payment lifecycle |
| `credits_update` | Credit balance changed |
| `spectator_update` | Spectated game state |
| `spectate_start` / `spectator_update` / `spectate_ended` | Spectator lifecycle |
| `chat_history` / `message` | Chat backlog and live messages |
| `leaderboard_update` / `win_feed` | Leaderboard and win ticker |
| `tavern_joined` / `tavern_update` / `tavern_match_tick` / `tavern_match_end` | Tavern state |
| `match_joined` / `match_end` / `match_settlement_pending` / `match_error` | Race lifecycle |
The client handles `descend` and `treasure_found` from `game_event` with an on-screen banner;
`escaped` and `monster_caught` are conveyed through `game_over`.
---
## Chat
Chat messages are persisted to the `chat_messages` table. A cleanup pass runs once per day and
deletes messages older than 7 days. Clients receive the most recent 50 messages on join. When no
database is available, chat falls back to a bounded in-memory buffer.
The Tavern prefers a shared global chat provider when one is injected. In that configuration a
Tavern message reaches every connected client, not just the Tavern room, and it is persisted along
with the rest of global chat. Only when no global provider is present does the Tavern fall back to
room-scoped, non-persisted chat.
See [`docs/CHAT_AND_NOSTR.md`](docs/CHAT_AND_NOSTR.md) for message signing and the optional nostr
relay path.
---
## Configuration
Key environment variables for a generic self-host (not an operated production profile; see
`.env.example` for the full list):
Key environment variables for a generic self-host. `src/.env.example` is the complete annotated
list.
```bash
# Core
NODE_ENV=production
PORT=3000
CRYPTO_TYPE=WOW
DIFFICULTY_PRESET=casino
# Payments
PAYMENTS_ENABLED=true
PAYMENT_MODES=direct,credits
DIRECT_GAME_PRICE=100000000000 # 1 WOW in atomic units
CREDITS_PACKAGES='[{"id":"small","credits":10,"price":"500000000000","bonus":0}]'
CREDITS_PACKAGES='[{"id":"small","credits":10,"price":"900000000000","bonus":0}]'
# Payouts
PAYOUTS_ENABLED=false
DIRECT_PAYOUTS_ENABLED=false
DIRECT_PAYOUT_ESCAPE=2.0
DIRECT_PAYOUT_TREASURE=3.0
@@ -244,6 +380,7 @@ WALLET_RPC_PASSWORD=use-a-distinct-strong-rpc-secret
# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=wownerogue
DB_USER=your_user
DB_PASSWORD=your_password
@@ -251,33 +388,49 @@ DB_PASSWORD=your_password
# Admin API (generate with: openssl rand -hex 32)
ADMIN_API_KEY=your-secure-key
# Network (Monero only - Wownero only has mainnet)
# Optional modes
TAVERN_ENABLED=true
MATCH_ENABLED=false
# Network selection (Monero only; Wownero has mainnet only)
MONERO_NETWORK=mainnet
```
Amounts use atomic units: 1 WOW = 10^11 atomic units.
Amounts are always atomic units for the configured chain. See the chain profile table above for
per-chain decimals.
`npm run preflight` validates the environment against the configured product profile without
starting the service.
---
## Production Deployment
See [docs/DEPLOY.md](docs/DEPLOY.md) for detailed production deployment instructions including:
- systemd service configuration
- Nginx/reverse proxy setup with WebSocket support
- Database permissions and security hardening
- Multi-instance deployment (running Wownero and Monero on the same server)
See [`docs/DEPLOY.md`](docs/DEPLOY.md) for production deployment, including:
The dated [`play.wowne.ro` production record](docs/PRODUCTION_STATE_2026-07-25.md) distinguishes the
live schema-neutral renderer/Tavern overlay from the still-gated full mainline migration cutover.
- systemd service configuration
- Nginx or other reverse proxy setup with WebSocket support
- Database permissions and security hardening
[`docs/DEPLOY_INSTANCES.md`](docs/DEPLOY_INSTANCES.md) covers running multiple instances, such as
Wownero and Monero, on one server.
---
## Operations
See [docs/LOGS_AND_BACKUP.md](docs/LOGS_AND_BACKUP.md) for:
- Log management with systemd/journald
- PostgreSQL automated backups
- Backup verification procedures
See [`docs/LOGS_AND_BACKUP.md`](docs/LOGS_AND_BACKUP.md) for log management with systemd/journald,
automated PostgreSQL backups, and backup verification.
`scripts/deploy/wowngeon-db-backup.sh` writes a dump and then prunes dumps older than
`BACKUP_RETENTION_DAYS` (default 14), plus interrupted temporary files older than one day. It
rejects a non-positive or non-numeric retention value rather than defaulting silently.
Financial operations are documented in
[`docs/FINANCIAL_RECONCILIATION.md`](docs/FINANCIAL_RECONCILIATION.md),
[`docs/FINANCIAL_CONSTRAINT_VALIDATION.md`](docs/FINANCIAL_CONSTRAINT_VALIDATION.md),
[`docs/FINANCIAL_EVENT_EXPORT.md`](docs/FINANCIAL_EVENT_EXPORT.md), and
[`docs/STAGENET_FINANCIAL_CANARY.md`](docs/STAGENET_FINANCIAL_CANARY.md).
---
@@ -288,7 +441,8 @@ cd src
npm test
```
Tests cover payment handlers, wallet RPC, security rules, movement logic, and integration flows.
Tests cover payment handlers, wallet RPC, security rules, movement logic, fairness verification, and
integration flows.
---
@@ -296,29 +450,47 @@ Tests cover payment handlers, wallet RPC, security rules, movement logic, and in
```
src/
├── index.js # Entry point
├── config/ # Payment config, validation
├── db/ # PostgreSQL layer
├── game/ # Dungeon, player, monster logic
├── network/ # Socket handlers, chat, queue, spectator
├── payments/ # Wallet RPC, QR codes
└── utils/ # Errors, memory management
├── index.js # Entry point, HTTP routes, static and vendor asset serving
├── auth/ # Session and wallet-based authentication
├── chain/ # Chain profile registry
├── config/ # Payment config, environment validation, product profiles
├── db/ # PostgreSQL layer
├── game/ # Dungeon generation, player, monster, fairness, mode resolution
├── middleware/ # Express middleware
├── migrations/ # Numbered SQL migrations
├── money/ # Atomic-unit arithmetic
├── multiplayer/ # Entitlements, appearance, cosmetic catalog
├── network/ # Socket handlers, chat, queue, spectator, match, Tavern
├── payments/ # Wallet RPC, QR codes
├── routes/ # Admin, auth, and leaderboard routers
├── rpc/ # Daemon and wallet clients
├── services/ # Health, alerts, refunds, payouts, subscriptions, exports
├── sim/ # Balance simulation harness
├── utils/ # Errors, memory management, nostr helpers
└── views/ # Server-rendered legal and verification pages
html/
├── index.html # Game client
├── admin.html # Admin dashboard
└── js/ # Frontend modules
├── index.html # Game client
├── tavern.html # Tavern client
├── match.html # Match client
├── admin.html # Admin dashboard
├── assets/ # Render packs and images
└── js/ # Frontend modules (core, render, network, ui, input)
test/
└── *.test.js # Jest tests
└── *.test.js # Jest tests
docs/ # Architecture, deployment, payments, and design references
scripts/ # Deployment units, backup, asset build, wallet maintenance
```
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) describes how these pieces fit together.
---
## License
The source is available under the [MIT License](LICENSE). MIT permission to use, copy, modify,
merge, publish, distribute, sublicense, and/or sell copies is subject to including the copyright
and permission notice in all copies or substantial portions. The software is provided “AS IS”,
without warranty of any kind as stated in the License.
merge, publish, distribute, sublicense, and sell copies is subject to including the copyright and
permission notice in all copies or substantial portions. The software is provided "AS IS", without
warranty of any kind, as stated in the License.
The MIT License governs rights in the source. Documentation, examples, and product disclosures are
informational only; they are not legal advice or a determination that a deployment complies with