mirror of
https://github.com/Such-Software/wownerogue.git
synced 2026-11-18 13:03:55 +01:00
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.
500 lines
22 KiB
Markdown
500 lines
22 KiB
Markdown
# Wownerogue
|
||
|
||
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
|
||
|
||
Such Software (`apps@such.software`) operates only these two public products:
|
||
|
||
| Service | Operated scope |
|
||
|---|---|
|
||
| `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 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 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 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 https://github.com/Such-Software/wownerogue.git
|
||
cd wownerogue/src
|
||
npm install
|
||
cp .env.example .env # Edit with your database/wallet settings
|
||
npm run db:create # Initialize PostgreSQL
|
||
npm run dev # Start development server
|
||
```
|
||
|
||
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 |
|
||
|
||
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 and are not constrained by those product decisions.
|
||
|
||
## Match Mode (Multiplayer Races)
|
||
|
||
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 |
|
||
|
||
`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`.
|
||
|
||
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.
|
||
|
||
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 and Pacing
|
||
|
||
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 |
|
||
|--------|--------------|---------|------------------|
|
||
| `easy` | 30×15 | low | ~30% |
|
||
| `normal` | 45×22 | medium | ~55% |
|
||
| `hard` | 55×28 | high | ~65% |
|
||
| `casino` | 70×35 | very high | ~70% |
|
||
|
||
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`)** 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 | Mean block time | Levels |
|
||
|-------|-----------------|--------|
|
||
| GRIN | ~1 min | 1 |
|
||
| XMR | ~2 min | 1 |
|
||
| LTC | ~2.5 min | 2 |
|
||
| WOW | ~5 min | 2 |
|
||
| BTC | ~10 min | 3 |
|
||
|
||
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`.
|
||
|
||
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.
|
||
|
||
---
|
||
|
||
## Chain Profiles
|
||
|
||
`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.
|
||
|
||
| 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` |
|
||
|
||
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.
|
||
|
||
Note that WOW uses 11 decimals, not Monero's 12: 1 WOW = 10^11 atomic units.
|
||
|
||
---
|
||
|
||
## Provably Fair Gaming
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
## 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).
|
||
|
||
---
|
||
|
||
## API Reference
|
||
|
||
### Public Endpoints
|
||
|
||
| Endpoint | Description |
|
||
|----------|-------------|
|
||
| `GET /health` | Redacted dependency/readiness summary |
|
||
| `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/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 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**
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3000/api/admin/refund/payment \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-Admin-Key: your-admin-key" \
|
||
-d '{"paymentId": 123, "reason": "Customer request", "sendFunds": true}'
|
||
```
|
||
|
||
**Example: adjust credits**
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3000/api/admin/credits/adjust \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-Admin-Key: your-admin-key" \
|
||
-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 to server**
|
||
|
||
| 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, 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 |
|
||
| `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. `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":"900000000000","bonus":0}]'
|
||
|
||
# Payouts
|
||
PAYOUTS_ENABLED=false
|
||
DIRECT_PAYOUTS_ENABLED=false
|
||
DIRECT_PAYOUT_ESCAPE=2.0
|
||
DIRECT_PAYOUT_TREASURE=3.0
|
||
|
||
# Wallet RPC (required for paid modes)
|
||
PRIMARY_WALLET_ENDPOINT=http://127.0.0.1:34570
|
||
WALLET_RPC_USER=user
|
||
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
|
||
|
||
# Admin API (generate with: openssl rand -hex 32)
|
||
ADMIN_API_KEY=your-secure-key
|
||
|
||
# Optional modes
|
||
TAVERN_ENABLED=true
|
||
MATCH_ENABLED=false
|
||
|
||
# Network selection (Monero only; Wownero has mainnet only)
|
||
MONERO_NETWORK=mainnet
|
||
```
|
||
|
||
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 production deployment, including:
|
||
|
||
- 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,
|
||
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).
|
||
|
||
---
|
||
|
||
## Testing
|
||
|
||
```bash
|
||
cd src
|
||
npm test
|
||
```
|
||
|
||
Tests cover payment handlers, wallet RPC, security rules, movement logic, fairness verification, and
|
||
integration flows.
|
||
|
||
---
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
src/
|
||
├── 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
|
||
├── 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
|
||
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 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
|
||
applicable law. Such Software operates only the two products and scopes listed above. The MIT
|
||
License does not make an independent deployment a Such Software service or authorize it to claim
|
||
Such Software sponsorship or endorsement; its operator remains solely responsible for the service.
|