Modes are inert JSON (shared/game/modes.ts): rule overrides on the engine's DEFAULT_RULESET, re-validated by parseRuleset; card-mapping presets from a fixed list; deck policy and limits. server/game/ publishes this node's modes, discovers configured peers' modes as data (byte cap, timeout, pinned origin), and hosts lobbies, snake drafts and matches with the deterministic engine. Finished matches are off-chain JSONL records with seed, decks and action log (replayable). Per-mode and host leaderboards. Docs in docs/game/HOSTING.md, including security notes and an on-chain host-reward proposal. One mount line in server/testnet/http.ts; no consensus changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
13 KiB
Hosting WikiDeck game modes
Anyone running a WikiDeck node can host their own game modes: their own twist on the rules, played with WikiDeck cards on their node, with visible credit for hosting them. Hosting a popular mode is the night-1 incentive to run a peer.
- Schema and validator:
shared/game/modes.ts - Node API:
server/game/(mounted at/api/gamebyserver/testnet/http.ts) - Example modes:
server/game/modes/*.json(shipped in the node image) - Tests:
tests/modes-*.test.ts
Everything here is off-chain. Hosting a mode never touches blocks, transfers, trades, validation or NFT ownership. A match never moves or burns a card.
1. Modes are data, never code
A mode is a JSON document, at most 8 KiB:
{
"schema": "wikideck.mode/1",
"id": "trending",
"version": 1,
"name": "Trending",
"description": "Live Wikipedia pageview trends power cards up or down.",
"tags": ["live-data"],
"rules": { "maxTurns": 6, "energy": { "max": 7 } },
"cards": { "preset": "trending", "percentPerPoint": 25, "maxBonus": 3, "penalise": true },
"decks": { "kind": "starter" },
"limits": { "maxConcurrentMatches": 32, "turnSeconds": 90, "lobbyMinutes": 15 }
}
| Field | Meaning |
|---|---|
id, version |
Lowercase slug and a version integer. Bump version whenever the rules change, so old match records and leaderboards stay attributable (<origin>#<id>@<version>). |
name, description, tags |
Plain text only: no control characters or < >. |
rules |
Overrides on top of the engine's DEFAULT_RULESET (see docs/game/ENGINE_API.md). Objects merge one level deep; arrays and numbers replace. The merged result then goes through the engine's strict parseRuleset, so the engine alone decides what's legal (bounded turns, lanes, deck sizes, known keywords and lane modifiers only). |
cards |
A card-mapping preset from a fixed list: standard (the at-mint snapshot), live (current stats) or trending (standard power ± a bounded bonus from the live 6-month pageview trend). The mode only picks a preset and tunes its bounded numbers. |
decks |
starter (everyone gets a seeded starter deck), draft (snake draft from a host-seeded pool of preview cards) or constructed (bring your own; see "Not yet" below). |
limits |
Concurrency, turn timer and lobby expiry for this mode on this host. |
The schema is strict: unknown fields are rejected, as are prototype keys
(__proto__, constructor, prototype) anywhere in the document, nesting deeper than two
levels inside rules, more than 48 rule keys, and oversized strings and arrays. A peer
never evaluates, imports or runs anything another peer sends. Nothing in a mode can name
a file, a URL, a script or a function.
2. Running your own modes
Configure modes with environment variables on your node:
| Variable | Default | Meaning |
|---|---|---|
WIKIDECK_MODES |
classic |
Comma list of built-in ids (classic, trending, draft) and/or paths to .json files. none hosts nothing (the node still lists its peers' modes). |
WIKIDECK_MODES_DIR |
unset | A directory: every *.json in it is loaded as a mode. |
WIKIDECK_GAME_OPERATOR |
your origin's host | The name shown as "Hosted by …". |
WIKIDECK_GAME_NOTE |
unset | A short note shown next to your name, e.g. "EU, best effort". |
WIKIDECK_GAME_PEERS |
WIKIDECK_PEERS |
Peer origins whose modes to list. Use the peers' public origins, because players open the peer's own site to play there. |
PUBLIC_ORIGIN |
http://127.0.0.1:$PORT |
Your node's identity as a host. |
At most 16 modes per node. A bad mode file stops the node at startup with a readable error, because rules are validated once with the engine's parser when the node starts.
Example for the night-1 testnet (three nodes, different modes):
# node-a: the base rules plus Trending
WIKIDECK_MODES: classic,trending
WIKIDECK_GAME_OPERATOR: Testnet A
WIKIDECK_GAME_PEERS: http://192.168.1.32:3102,http://192.168.1.32:3103
# node-b: the draft
WIKIDECK_MODES: draft
WIKIDECK_GAME_OPERATOR: Testnet B
# node-c: everything, including a custom file
WIKIDECK_MODES: classic,trending,draft,/app/data/modes/blitz.json
Writing a new mode
Start from server/game/modes/classic.json, change id, name and description, then
override rules. Some ideas within tonight's rules:
- Blitz:
"rules": { "maxTurns": 4, "energy": { "start": 3, "perTurn": 1, "max": 6 } } - Wide board:
"rules": { "lanes": 4, "laneModifiers": { "pool": ["plain","portal","narrow","plain"], "revealTurns": [1,2,3,4] } } - Big decks:
"rules": { "deck": { "min": 16, "max": 16, "maxCopiesPerPage": 2 } }
Check that a mode parses with npm test (the built-in modes are tested), or load it on a
local node: it fails at startup if the engine rejects it.
3. The node API
Everything is under /api/game, behind the node's existing /api admission budget and
global rate limit, plus stricter per-route limits.
| Method | Path | What it does |
|---|---|---|
| GET | /modes |
Publish: this node's host identity, total matches hosted, and each mode with live stats (players online, open lobbies, live matches, matches played, distinct players). |
| GET | /network/modes |
Discover: this node's list plus each configured peer's list, fetched as data. |
| GET | /hosts/leaderboard |
Hosts ranked by matches hosted (this node plus peers). |
| GET | /modes/:id/leaderboard |
Per-mode player leaderboard (wins, losses, draws). |
| GET | /modes/:id/lobbies |
Open lobbies waiting for an opponent. |
| POST | /modes/:id/lobbies |
Create a lobby: { name, secret } → { lobbyId, seat: 0, token }. |
| POST | /lobbies/:lobby/join |
Join: { name, secret } → { lobbyId, seat: 1, token }. The match (or draft) starts. |
| GET | /lobbies/:lobby |
Status. With Authorization: Bearer <token>: your PlayerView and your legalActions. |
| POST | /lobbies/:lobby/pick |
Draft pick: { index }. |
| POST | /lobbies/:lobby/actions |
Play: { action }, which must equal one of your legalActions. |
| POST | /lobbies/:lobby/resign |
Resign (or cancel a waiting lobby). |
| GET | /matches/:matchId |
A finished match record: seed, both decks, the full action log and the result. |
Players. The browser generates a random secret once and keeps it in local storage. The
host only ever stores and shows sha256("wikideck-player:" + secret) as the player id, so a
leaderboard name can't be claimed by someone else who uses the same display name. Each seat
also gets a fresh bearer token per lobby; only its hash is kept. When eom.dev accounts land
(#7), the player id can come from the account instead.
Playing on a peer's mode. The browser's CSP keeps API calls same-origin, so the lobby shows peer modes with "Hosted by …" and links to the peer's own site to play there. No node proxies another node's matches.
4. Credit for hosts
Every mode shows "Hosted by <operator>" (with the node's origin), its player counts,
its own leaderboard, and the node's total matches hosted. /hosts/leaderboard ranks nodes by
matches hosted.
Tonight these numbers are informational: each node reports its own counts. See section 6 for how they could become rewards without trusting the host's word.
5. Security notes
Limits
| Limit | Value |
|---|---|
| Mode document | 8 KiB; 48 rule keys; rule nesting depth 2; strings ≤ 64 chars inside rules |
| Modes per node / per peer response | 16 |
Peer /api/game/modes response |
192 KiB, read with a streaming byte cap; 3 s timeout; no redirects; cached 30 s; at most one refresh in flight |
| Peers | at most 16, operator-configured origins only (HTTPS, or HTTP with WIKIDECK_ALLOW_PRIVATE_PEERS=1) |
| Lobbies + matches in memory | 512 per node; maxConcurrentMatches per mode; 3 per player |
| Match length | engine bounds (maxTurns ≤ 12) plus a hard 2,000-action cap |
| Rate limits per IP | 240/min reads and plays, 60/min lobby create/join/resign, 30/min peer-discovery routes (on top of the node-wide 300/min /api limit and the RPC admission budget) |
| Request body | the node's 68 KB JSON limit |
Wikipedia lookups (trending) |
background only: one page per 3 s, at most 256 queued, never per request |
Cheating
- The client is never trusted. Each action must deep-equal one of the engine's
legalActionsfor the token's seat, so you can't act for the other seat, play cards you don't hold, overspend energy or act after the match ends. - Hidden information stays on the host. Each seat only ever receives
viewFor(state, seat); the opponent's hand and staged plays never leave the server. Spectators see status only. - Seeds are the host's. The match seed is 128 random bits chosen by the host when the lobby opens, so players can't grind for a favourable shuffle.
- Stalling forfeits: whoever still owes an action after
turnSecondsloses; if both do, the match ends as a draw. A stalled draft pick is made automatically. - Sybils and win-trading: anyone can make a new player id, and two ids controlled by the same person can feed each other wins. Tonight's leaderboards are for fun. Accounts (#7) or wallet-signed identities would raise the cost.
- Card stats. Card numbers come from the engine's card mapping. Minted stats are self-reported by the minter (see council-critic in #3); a mode can only pick a mapping preset, not supply numbers.
What a malicious host can and can't do
A host runs its own matches, so it is trusted for the matches it hosts, and only those.
A malicious host can:
- lie about its stats, its matches hosted and its leaderboards;
- rig its own matches: pick seeds, peek at hands, or ignore the rules;
- drop or stall your match, or record a false result.
A malicious host can't:
- touch your cards: matches are off-chain, and the host never receives a key or signature;
- run code on other nodes: its modes are inert data, validated with hard limits;
- make other nodes fetch anything except its own
/api/game/modes, or make them fetch it in a way that slows them down (byte cap, timeout, cache, single flight); - publish modes under another node's origin: discovery pins the origin it actually fetched;
- see your player secret: it only receives it once, over its own origin, and stores the hash. Use a different secret per host if you don't trust a host (the UI can derive one per origin).
Audit trail. Every finished match record publishes the seed, both decks and the full action
log, so anyone can re-run it with the engine's replay(ruleset, decks, seed, actions) and check
the result. A host that lies about a result can be caught; a host that peeked at hands can't.
6. Proposal: on-chain host rewards (not tonight)
Rewarding hosts on-chain is a protocol change, so it's out of scope for night 1. This is a proposal for later, to be reviewed like any consensus change.
Goal: pay hosts for matches real players actually played, without trusting the host's count.
- Signed match results. Both players sign the final result
(
matchId,<origin>#<id>@<version>, seed hash, action-log hash, winner) with their wallet keys. The host signs too. A result needs all three signatures, so a host can't invent matches or results alone, and players can't deny a match they played. - Replayable evidence. The record keeps the seed, decks and action log. Anyone can replay it with the pinned engine version to check the result. Disputes are settled by replay, not by vote.
- Batched claims. Once per epoch, a host submits one transaction committing a Merkle root of
its signed results. A new
hostClaimtransaction type would carry the root and a count. This is the protocol change: a new transaction type, its validation and its reward rule. - Rewards that resist farming. A host's reward per epoch grows with the number of distinct paired wallets (not matches), each wallet counts toward at most one host per epoch, wallets must hold at least one minted card older than N blocks, and the total is a small, capped share of block rewards. That makes sybil farms cost real mining work.
- Challenges. For a window after a claim, anyone can post a replay that contradicts a committed result, or proof that a wallet was double-counted. A successful challenge voids the host's claim for that epoch.
Open questions: who pays (a share of block rewards versus a fee from players), how to stop colluding players and hosts from farming one another, and whether the engine version must be pinned in consensus.
Not yet
constructeddecks of owned NFTs: the policy exists, but tonight the host deals starter decks for it. Playing with your own cards needs a wallet-signed ownership proof for the lobby (and then the engine'scardFromStats). That's a follow-up once accounts and wallet linking (#7) settle.- The
livepreset is accepted, but tonight it behaves likestandard. trendingnever calls Wikipedia when a match starts. The node warms a cache-only trend store in the background, one page every 3 s, through its existing enrichment cache (6 h TTL), starting with the preview-card pages. A card whose page isn't warm yet gets no bonus. This keeps load on the shared, rate-limited Wikipedia egress tiny: about 24 pages per 6 hours per node.- Spectating and rematches.