Compare commits

..
Author SHA1 Message Date
claude 6a14d32033 Merge night/2026-11-17 into night2/ui-pvp/board-wiring 2026-11-18 11:15:17 -05:00
claude e65cbc1da1 Merge pull request '[host-pvp] Part 2: duel engine in the host, duel modes, time bank, collection mount (#56)' (#81) from night2/host-pvp/part2-wip into night/2026-11-17 2026-11-18 16:15:08 +00:00
claude c6d9b770ec Merge night/2026-11-17 into host-pvp part 2 2026-11-18 11:15:00 -05:00
claude 87090e7c32 Merge pull request '[duel-core] Duel engine alpha with balance v1 defaults (#55)' (#80) from night2/duel-core/engine-wip into night/2026-11-17 2026-11-18 16:14:34 +00:00
claude c6e51a00dc Merge pull request '[ui-duel] Duel board, MTG card faces, combat declaration, DuelBoard/DuelBotMatch mount points (#58)' (#79) from night2/ui-duel/board into night/2026-11-17 2026-11-18 16:14:11 +00:00
claude c85176b690 Merge pull request '[mobile-mining] Android app can mine (native RandomX, sideload build)' (#78) from night2/mobile-mining/android-miner into night/2026-11-17 2026-11-18 16:14:02 +00:00
claude d29db7b456 Merge pull request '[testnet-ops] testnet compose: WIKIDECK_WIKIMEDIA_NODES_PER_IP=3, operator contact' (#75) from night2/testnet-ops/compose-wikimedia into night/2026-11-17 2026-11-18 16:13:57 +00:00
claude b20fbc1ab9 Merge pull request '[sim-balance] Duel bots (heuristic, MC) and duel simulation harness' (#71) from night2/sim-balance/duel-harness into night/2026-11-17 2026-11-18 16:13:50 +00:00
claude 5671cfbedc Merge pull request '[testnet-ops] Card identity store + pre-bake script (WS E), TESTNET.md' (#68) from night2/testnet-ops/identity into night/2026-11-17 2026-11-18 16:13:44 +00:00
claude ebb34eef0d Merge pull request '[testnet-ops] autodeploy follows night/2026-11-17' (#67) from night2/testnet-ops/autodeploy into night/2026-11-17 2026-11-18 16:13:34 +00:00
claude 3617d928f5 Merge pull request '[ui-pvp] PvP-first Play: owned-card eligibility, deck picker, quick match/invites, ladder, battle recap page (#65)' (#76) from night2/ui-pvp/collection-lobby into night/2026-11-17 2026-11-18 16:13:26 +00:00
claude db578a44b4 Merge night/2026-11-17 into #76 (resolve src/App.tsx with #74)
# Conflicts:
#	src/App.tsx
2026-11-18 11:13:06 -05:00
claude 93de4d0630 Merge pull request '[host-pvp] Multi-engine host, owned-deck account seats, invites, quick match, Elo, ?v= polling (#56)' (#77) from night2/host-pvp/multi-engine-host into night/2026-11-17 2026-11-18 16:12:59 +00:00
claude 2285f49903 Merge night/2026-11-17 into #77 (resolve server/game/index.ts with #74)
# Conflicts:
#	server/game/index.ts
2026-11-18 11:12:44 -05:00
claude 4c85cc865d Merge pull request '[ownership] Server-side deck ownership, collection API, 40-card eligibility (#57)' (#74) from night2/ownership/collection into night/2026-11-17 2026-11-18 16:12:32 +00:00
claude c2ea57966e Merge pull request '[wikimedia] Polite Wikimedia client, mint-path fix, disk cache, mining prefetch pool (#62)' (#73) from night2/wikimedia/client into night/2026-11-17 2026-11-18 16:12:26 +00:00
claude 1c22ad1df5 Merge pull request '[duel-design] shared/duel/story: match log + "Battle of X (2026)" recap' (#69) from night2/duel-design/story into night/2026-11-17 2026-11-18 16:12:19 +00:00
claude c12e792dcb Merge pull request '[duel-cards] Card profiles: type, Portal, stats, keywords, effects, rules text (shared/duel)' (#70) from night2/duel-cards/profiles into night/2026-11-17 2026-11-18 16:12:11 +00:00
claude 9aba28f59e Merge pull request '[duel-design] DUEL_DESIGN.md v1 (contract for 22:15)' (#66) from night2/duel-design/design-v1 into night/2026-11-17 2026-11-18 16:12:02 +00:00
claude 52551ba9aa Merge pull request '[duel-core] Duel contracts: shared/duel/types.ts, ruleset.ts, DUEL_API.md' (#72) from night2/duel-core/contracts into night/2026-11-17 2026-11-18 16:11:53 +00:00
claude 983552c086 http.ts: restore CRLF line endings (night-review) 2026-11-18 01:07:18 -05:00
claude ae2805067a HOSTING.md: duel card typing (identity vs on-chain fallback) and the clock 2026-11-18 00:56:33 -05:00
claudeandClaude Opus 5.5 5076299e7c [duel-cards] classify: on-chain fallback (extract definition, title, mint category) before Doctrine
An empty profile typed every card as Doctrine (night-review on #61). derive() now passes
chain.article to classify/subtypeFor; full-profile results are unchanged (fixture identical).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 00:50:13 -05:00
claude dfb8abe0e2 host-pvp: toDuelCard fallback types cards from on-chain data (extract sentence, mint category hint), not all Doctrine (night-review P1) 2026-11-18 00:45:50 -05:00
claude 56f1446d8f host-pvp: mount GET /collection in gameRouter with the toDuelCard hook; one identity store (ownership's proposal) 2026-11-18 00:33:04 -05:00
claude 52df0f0120 host-pvp: per-seat time bank (bankSeconds), clock in the seat view; tested on engine-wip 2026-11-18 00:21:08 -05:00
claude cb0dc294f7 Merge remote-tracking branch 'origin/night2/duel-core/engine-wip' into local/preview 2026-11-18 00:19:35 -05:00
claudeandClaude Opus 5.5 0eb80d23d7 duel-core: balance v1 defaults from sim-balance (#64): secondPlayerCitations 1, turnCap 40
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 00:12:25 -05:00
claudeandClaude Opus 5.5 f881e2cd54 DUEL_DESIGN: list secondPlayerCitations among house-rule keys
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 00:03:44 -05:00
claudeandClaude Opus 5.5 5121fd0418 DUEL_DESIGN v1.3: balance v1 = secondPlayerCitations 1 + turnCap 40; Location rider rejected (#64)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 00:03:38 -05:00
claudeandClaude Opus 5.5 6e97e2c8ee DUEL_DESIGN v1.2: secondPlayerCitations 1 (balance v1, #64), targets, Location finding
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 23:43:18 -05:00
claudeandClaude Opus 5.5 3e6d597aef ui-duel: document that browser bot matches are unrated (#79 review)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 23:38:42 -05:00
claudeandClaude Opus 5.5 067de837a8 [duel-cards] Doctrines: attach + static pump on attached (DUEL_API encoding); the buff was ignored by the engine
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 23:23:29 -05:00
claudeandClaude Opus 5.5 ff6c93c808 ui-duel: QA fixes from night-review (#58): hand overflow cue (+N, edge fade), Garrison 0/T in preview, taller cards and 3-line titles on tall phones, larger Doctrine badge
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 23:10:06 -05:00
claudeandClaude Opus 5.5 4623930e8f duel-core: secondPlayerCitations ruleset lever (default 0) for first-player balance
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 23:08:53 -05:00
claudeandClaude Opus 5.5 b5e4caa44d [ui-pvp] online duels render ui-duel's DuelBoard (placeholder kept only when the host sends no view)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 23:03:40 -05:00
claude 5e80259fb8 Merge remote-tracking branch 'origin/night2/ui-duel/board' into prep/board 2026-11-17 23:03:17 -05:00
claudeandClaude Opus 5.5 26ad4af02e identity-source: WikidataEntity matches #70's shape exactly
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:59:46 -05:00
claudeandClaude Opus 5.5 c9197e1a9f testnet-ops: live identity source (background lane only), deps injected structurally
wikimediaIdentitySource() takes the wikimedia client (#73), the page enrichment and
duel-cards' profile builder (#70) as structural deps, so it imports nothing unmerged.
About 2 Wikidata requests per 50 new cards; transport failures leave cards unknown.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:59:19 -05:00
claudeandClaude Opus 5.5 0f924b7732 ui-duel: even battlefield slots with few cards; keyword icons on two-keyword hand cards; game-over note wraps (#58)
Found by rendering duel-core's engine-wip mid-game locally.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:56:40 -05:00
claudeandClaude Opus 5.5 848cfbbaf1 ui-duel: view-only fallback duel bots (Easy, Normal) for the browser bot match (#58)
Checked locally against duel-core's engine-wip: 40 full games through the board
pipeline (adapter, declaration reducers, expand) with every sent action legal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:55:08 -05:00
claudeandClaude Opus 5.5 5cd0ffb0c9 duel-core: engine alpha (createDuel, legalActions, applyAction, viewFor, logFor, replay, duelEnginePort)
Effect interpreter for DUEL_DESIGN T1-T12, keywords, Connected/rivalry,
tokens, fight, Doctrines, Garrisons, turnCap, timeouts. Structural
clone-on-apply (~0.05 ms/action). Refs #55.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:53:15 -05:00
claudeandClaude Opus 5.5 a032c6e5d6 [ui-pvp] follow host-pvp #77: POST /invites/:code/join, drafting phase, record decks as strength
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:52:40 -05:00
claude 907d969a17 preview: merge #77 + wip part 2 2026-11-17 22:52:38 -05:00
claudeandClaude Opus 5.5 ae14bc7b89 [duel-cards] connect.qid is optional (omitted without a Wikidata item), matching #72's ConnectKeys
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:52:35 -05:00
claudeandClaude Opus 5.5 15470d5130 MOBILE_MINING.md: record the wallet keep-alive trade-off (review on #78)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:51:57 -05:00
claude de71817fd0 Merge remote-tracking branch 'origin/night2/ownership/collection' into local/preview 2026-11-17 22:49:48 -05:00
claude 2d2bfc6814 Merge remote-tracking branch 'origin/night2/testnet-ops/identity' into local/preview 2026-11-17 22:49:48 -05:00
claude 81bf113ed5 Merge remote-tracking branch 'origin/night2/duel-cards/profiles' into local/preview 2026-11-17 22:49:48 -05:00
claudeandClaude Opus 5.5 9c26b8d560 ui-duel: mirror the used slice of duel-core's contract (#72) locally so this PR doesn't stack (#58)
contract.ts copies the unions and fields verbatim; a compile check confirmed
duel-core's PlayerView, DuelAction (both ways), LogEvent, DuelEngineApi and
DuelRuleset are assignable to it. It becomes re-exports once #72 merges.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:49:19 -05:00
claudeandClaude Opus 5.5 4f9cbfeaae TESTNET.md: test wallets are readable by anyone with issue access
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:41:21 -05:00
claudeandClaude Opus 5.5 c35db68c20 testnet-ops: TESTNET.md secure-context workaround and counts; identity store under WIKIDECK_DATA_DIR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:40:59 -05:00
claudeandClaude Opus 5.5 53736e12a0 [ui-pvp] review notes: neutral 'victory' wording in the fallback recap; /recap/<id> is canonical (/battle/<id> kept as alias)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:40:11 -05:00
claudeandClaude Opus 5.5 3da3e5ab84 host-pvp: quick match skips stale lobbies; draft pool only for seats (review on #77)
Re-resolve the creator's deck before seating the joiner, so a stale lobby
expires without listing the joiner, and quick match moves on to the next
candidate (or opens a lobby) instead of failing the quick-matcher.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:39:00 -05:00
claudeandClaude Opus 5.5 8694239d7c MOBILE_MINING.md: emulator mined accepted testnet block #92
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:37:35 -05:00
claudeandClaude Opus 5.5 2e4836f5e8 Android app can mine: native RandomX engine, WikiDeckMiner plugin, mobile panel
- scripts/build-randomx-android.sh: NDK cross-build of the pinned native/ engine
  (light mode) for arm64-v8a and x86_64, packaged as jniLibs/<abi>/libwikideck_randomx.so
- MinerPlugin.java (Capacitor "WikiDeckMiner"): runs engine processes over the
  line protocol, on-device self-test, and halts on background, battery saver,
  thermal, hot or low battery. Never receives wallet keys.
- src/mobile-miner.ts: template -> mine -> sign -> submit loop in the WebView,
  byte-identical to consensus miningBlob/mintId (tests/mobile-mining-miner.test.ts)
- src/MobileMiningPanel.tsx: consent, intensity (1 thread default; Max = 4 only
  while charging), live hashrate/status; testnet-only (disabled on mainnet builds)
- docs/night2/MOBILE_MINING.md: how it works, safeguards, measured hashrate,
  store policies (sideload APK only), options for Eric

No protocol, consensus or server changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:32:51 -05:00
claudeandClaude Opus 5.5 adc78409fe host-pvp: multi-engine host, owned-deck seats, invites, quick match, Elo, ?v= polling (#56)
- Mode schema wikideck.mode/2: required `engine` (editwar | duel); Night 1
  wikideck.mode/1 documents are rejected with a clear message. Deck policies:
  constructed (owned NFT token ids, minConfirmations), starter (Edit War only),
  draft with source preview (Edit War only) or collections. limits.rated and
  limits.accountsOnly.
- ModeHost runs every engine it is given, chosen per mode. Duel modes refuse
  loaner policies at startup (BRIEF decision 1).
- Seats: eom.dev account via Dex ID token (body or JWT bearer on seat-creating
  routes), player id sha256('acct:'+iss+'\n'+sub); guests only in Edit War.
- Constructed decks resolved through an injected OwnershipPort (#57), cards built
  by the engine's fromChain; creator's deck re-resolved at join.
- Private lobbies + invite codes (GET /invites/:code, POST /invites/:code/join),
  quick match (POST /modes/:id/quick), lobby state version with 204 on ?v=.
- Elo (1200, K 24) per mode for rated account-vs-account matches, recomputed
  from matches.jsonl; records carry engine, rated, tokens. /modes/:id/ladder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:27:37 -05:00
claudeandClaude Opus 5.5 2e88a8dbf0 [ui-pvp] recap infobox cells wrap
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:23:45 -05:00
claudeandClaude Opus 5.5 2ad4d022aa docs: note the deliberate 1 req/s REST rate (review on #73)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:20:21 -05:00
claudeandClaude Opus 5.5 a57698a7e2 ui-duel: accept untyped duel profiles from the collection and shape-check them (#58)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:17:44 -05:00
claudeandClaude Opus 5.5 39ffe409cb story: lifeGain event, authoritative gameOver.life, document story seed (night-review #69 notes)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:16:56 -05:00
claudeandClaude Opus 5.5 79041990ed duel-core: ConnectKeys qid/cites for claim-based Linked; seed secrecy rule
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:10:16 -05:00
claudeandClaude Opus 5.5 83a3afef1b story: tokens (never cited) and drawn matches, for duel-core's LogEvent shape
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:04:39 -05:00
claudeandClaude Opus 5.5 51bdbe0fa3 [sim-balance] easy duel bot (heuristic with 30% blunders) for the UI
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:04:09 -05:00
claudeandClaude Opus 5.5 9943de3b53 [ownership] collectionRouter: optional injected duelCard hook (#57)
Attaches duel: DuelCard to collection cards when the server has a frozen
profile (requested by ui-duel); omitted while pending, never fetches.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:02:50 -05:00
claudeandClaude Opus 5.5 c136c500a3 [ui-pvp] onAct resolves on host acceptance; collection passes through the server duel profile
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:02:11 -05:00
claudeandClaude Opus 5.5 3db3ff7858 [ui-pvp] placeholder board labels follow duel-core action fields
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:01:43 -05:00
claudeandClaude Opus 5.5 0875573cd7 [ui-pvp] PvP-first Play: owned-card eligibility, deck picker, quick match, invites, ladder, battle recap page
- src/game/collection/: collection model (GET /api/game/collection, local fallback), 40-card
  eligibility with the 4-per-article copy limit, "23 / 40 cards. Mine to play" gate, constructed
  deck picker. No loaners, starters or borrowed decks (BRIEF decisions 1-2).
- PlaySection: PvP hub with quick match, private lobby + invite link, join by link, ladder;
  bot match slot waits for ui-duel's board.
- online.ts / OnlinePlay.tsx: duel PvP client against host-pvp's routes (idToken in body,
  Bearer seat token, ?v= polling with 204), validated responses.
- Leaderboards: Elo ladder with W/L fallback.
- src/game/recap/: /battle/<id> (and /recap/<id>) standalone page rendering duel-design's
  RecapDoc shape; deterministic template fallback over real match data until #69 merges.
- App: /play/invite/<code> and /battle/<id> deep links; session.idToken().
- tests/ui-pvp-*.test.ts, tests/e2e/ui-pvp-smoke.mjs (Playwright, stubbed API).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:01:28 -05:00
claudeandClaude Opus 5.5 da37378181 deploy/night: testnet nodes share one egress IP for the wikimedia client (#62)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:58:43 -05:00
claudeandClaude Opus 5.5 57d2fc2fc7 [duel-cards] Match duel-core's contract (#72): template ids, description, maxTokens = fewer than N
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:58:37 -05:00
claudeandClaude Opus 5.5 75ce8f5ba5 ui-duel: DuelBotMatch (eligible players only, bot sees viewFor only) (#58)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:56:22 -05:00
claudeandClaude Opus 5.5 a7e46583fb ui-duel: DuelBotMatch (eligible players only, bot sees viewFor only) (#58)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:56:01 -05:00
claudeandClaude Opus 5.5 5ff448682e [sim-balance] Duel bots choose from the observation's legal list; stand-in can use duel-cards' fixture
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:55:40 -05:00
claudeandClaude Opus 5.5 0ca7704767 story: public discards, factual rivalry wording, Portal ties, fixture Portals per duel-cards #70
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:55:25 -05:00
claudeandClaude Opus 5.5 6182dff1cd DUEL_DESIGN v1.1: night-review nits (public Deleted, Garrison vs Featured, clock, rivalry wording), align with duel-cards #70
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:54:35 -05:00
claudeandClaude Opus 5.5 4160086d16 ui-duel: duel-core adapter and DuelBoard (PlayerView + DuelAction[]) for ui-pvp (#58)
Board intents expand to duel-core's atomic actions (toggleAttacker x N,
confirmAttack; block x N, confirmBlocks), sent in order and awaited.
Fallback log uses the first DUEL_DESIGN 8.2 variant until the story
renderer reads engine events.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:54:04 -05:00
claudeandClaude Opus 5.5 0fcf0b0a73 ui-duel: follow duel-core contract phases; multi-step targets incl. players (#58)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:51:55 -05:00
claudeandClaude Opus 5.5 f544019bfe Polite Wikimedia client, mint-path fix, disk cache and mining prefetch pool (#62)
- server/wikimedia/client.ts: one process-wide client. Per-host token bucket
  (1 req/s, burst 3), 1 in flight per host, mint > interactive > background
  lanes with a bounded queue, maxlag=5 on Action API requests, Retry-After
  and backoff, a circuit breaker after 3 consecutive 429s, a daily cap, and
  a per-egress-IP budget (WIKIDECK_WIKIMEDIA_NODES_PER_IP).
- server/wikimedia/cache.ts: node:sqlite HTTP cache with ETag/If-None-Match,
  stale-while-revalidate on the background lane. Mint reads never use it.
- Mint fix: a 429/5xx/timeout/non-JSON reply on pageviews now fails getFresh()
  (template 503, miner retries) instead of minting attention: null forever.
- server/wikimedia/pool.ts: per-tip article+snapshot prefetch pool for
  /api/mining/template, about 3 requests per block regardless of miner count.
- User-Agent with an operator contact (WIKIDECK_OPERATOR_CONTACT or
  PUBLIC_ORIGIN) and a start-up warning when it is unset.
- Mint request parameters are byte-identical apart from maxlag (golden test).
  No consensus, block or protocol changes. Tests use fake fetch only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:51:20 -05:00
claudeandClaude Opus 5.5 5d5eaa5488 duel-core: adopt duel-cards card/effect shape and DUEL_DESIGN log kinds
Connected computed by the engine from frozen connect keys; tokens, fight,
multi-target plays, locationsPerTurn, timeoutsToConcede.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:49:52 -05:00
claudeandClaude Opus 5.5 0666b08829 ui-duel: engine-agnostic local match driver; Connected icon; game-over uses the engine's log line (#58)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:47:59 -05:00
claudeandClaude Opus 5.5 a8468dd96c [duel-cards] profile.ts: build the frozen CardProfile from enrichment + wbgetentities (pure, no fetch)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:47:00 -05:00
claudeandClaude Opus 5.5 2fe16a66c8 ui-duel: eligibility gate, DuelCard to board card mapping, zoom face fixes (#58)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:46:26 -05:00
claudeandClaude Opus 5.5 47cab9f619 testnet-ops: identity fields match duel-cards CardProfile (links as pageIds, years, cites, subclassOf, description); toProfile()
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:46:09 -05:00
claudeandClaude Opus 5.5 5a7cfba124 ui-duel: duel table, MTG card faces, combat declaration and preview scenes (#58)
Presentational board on its own view model (src/game/duel/model.ts), 360 x 740 first:
both players' Notability, Citations, library and hand always visible; attack in one
tap, block in two, preview then confirm; tap-to-zoom card sheet with rules text,
flavour and an [n] article link; log ticker on phones, log column on desktop.
#duel-preview renders static scenes from card-sample.json for review.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:44:33 -05:00
claudeandClaude Opus 5.5 3c70f643f2 [duel-cards] Card profiles: classify, derive, effects, rules text from real data
shared/duel/classify.ts: Q-id anchors -> P31 label regex (^human$) -> P279 -> categories -> description -> Doctrine.
shared/duel/derive.ts: pure derive(chain, profile) -> DuelCard: fame cost 1-6, P+T budget per cost,
DUEL_DESIGN §4 keywords (<=2, Figures only, taxed), Portals, Connected keys and tiers, flavour.
shared/duel/effects.ts + text.ts: T1-T12 templates as EffectSpec data, MTG-register rules text.
shared/duel/sample.ts + docs/game/duel-card-sample.json: 236-card DuelCard fixture.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:43:59 -05:00
claudeandClaude Opus 5.5 26ca8e2f27 shared/duel/story: deterministic match log and Battle of X recap, golden tests
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:43:32 -05:00
claudeandClaude Opus 5.5 fcdd05f2b1 [ownership] Server-side deck ownership, collection API, 40-card eligibility (#57)
- server/game/ownership.ts: verifyAccount, resolveDeck (token ids only; canonical
  owner in linked wallets, confirmations, exact deckSize, 4 copies per pageId,
  cards rebuilt from their block), collection (all linked wallets, paged at one
  tip, no 128-block cap). Signature agreed with host-pvp on #57.
- server/game/collection.ts: GET /api/game/collection (Dex bearer) with owned,
  playable, needed, eligible.
- account router exports accountVerifier; http.ts shares one AccountStore and
  DexKeys between the account and game routes and passes gameRouter({ownership}).
- App.tsx: My collection counts cards in every wallet linked to the account.
- tests/ownership-deck.test.ts: in-memory ledger fixture, no network.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:42:28 -05:00
claudeandClaude Opus 5.5 36cbaccd42 testnet-ops: card identity store, pre-bake script, testnet guide
server/game/identity.ts freezes each card's off-chain identity (P31, categories,
country, dates, coords, outlinks hash) once per tokenId in node:sqlite and never
rewrites it. scripts/night2/prebake-identity.ts reads the canonical chain from one
node and freezes from cached card files only; live facts plug in via an
IdentitySource on the wikimedia client's background lane (#62). Tests make zero
network calls. docs/night2/TESTNET.md: nodes, wallets, login, mining, autodeploy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:42:23 -05:00
claudeandClaude Opus 5.5 038e079ce8 [sim-balance] Duel bots (heuristic, MC) and duel simulation harness
Engine-agnostic duel bots over a DuelLens, a 40-card deck builder from the
236 sample cards with type/curve-skewed archetypes, a <=4-worker sim runner
and DUEL_BALANCE metrics. Runs on a small stand-in duel engine until
duel-core's shared/duel alpha lands; then shared/bots/duel-adapter.ts binds it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:39:48 -05:00
claudeandClaude Opus 5.5 4daf87edde duel-core: monotonic attack/block declarations; optional permanent counters
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:36:41 -05:00
claudeandClaude Opus 5.5 5365611c4a duel-core: shared/duel contracts (types, ruleset) and DUEL_API.md
Refs #55.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:35:37 -05:00
claudeandClaude Opus 5.5 bac186470d DUEL_DESIGN.md v1: rules, keywords, templates, Connected, modes, tone, worked cards
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:35:07 -05:00
claudeandClaude Opus 5.5 2f494e399c deploy/night: autodeploy follows night/2026-11-17 by default
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:35:00 -05:00
claudeandClaude Opus 5.5 2af2e7f06f Night 2 handbook: night-lead runs on tower-plus
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 13:08:17 -05:00
claudeandClaude Opus 5.5 57dc1e60aa Night 2 handbook: ui-pvp runs on inspiron-3670
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 13:07:59 -05:00
claudeandClaude Opus 5.5 dbf385d217 Night 2: data analyst scripts behind reviews/data.md
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 13:07:31 -05:00
claudeandClaude Opus 5.5 e34b09d06d Night 2: plan, design brief, handbook and plan reviews
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 13:05:42 -05:00
claudeanderic 4f7a8a7c74 Night 1: Edit War card game, eom.dev accounts, peer-hosted modes, Android and iOS apps (#22)
Overnight build by 17 Claude agents (2026-11-16 22:45 → 01:30 EST), coordinated in [claude/wikideck milestone 63](https://gitea.eom.dev/claude/wikideck/milestone/63). **For Eric's review. Do not merge without it.** The full write-up is in `docs/night/REPORT.md`.

**What's in it** (38 reviewed PRs, squash-merged into `night/2026-11-16`):
- **Edit War:**
  - a 3-lane, 6-turn card game built on what WikiDeck cards actually hold
  - a pure, deterministic, off-chain rules engine (`shared/game/`, with the API in `docs/game/ENGINE_API.md`); rules are data and v1.1 is the default
  - a mobile-first Play UI with a lobby, deck builder, four loaner starter decks, a match against the AI, results and a tutorial
  - a landing page (fixes #3)
- **Design and balance:** `docs/game/DESIGN.md`, `CARD_DATA.md` (236 sampled articles) and `BALANCE.md` (bot simulations). Starter pairings went from 23–77% on v1 to roughly even on v1.1.
- **eom.dev accounts:** Dex OIDC with PKCE, plus off-chain wallet linking, where the client builds the message it signs (`server/account/`, `src/auth/`).
- **Peer-hosted game modes:** modes are JSON data, never code. Node API at `/api/game/*`, with host credit and leaderboards. Three example modes (`shared/game/modes.ts`, `server/game/`, `docs/game/HOSTING.md`).
- **Mobile:** Capacitor 7 Android app (a debug APK played a full match against the AI in the emulator), and an iOS project waiting on Xcode (`docs/night/ANDROID.md`, `docs/night/IOS.md`).
- **Testnet tooling:** `deploy/night/` (LAN-only, 3 nodes) and an optional `WIKIDECK_USER_AGENT` (the default is unchanged).

**Not touched:** consensus and protocol (`server/chain.ts`, `shared/protocol.ts`, `server/testnet/{consensus,ledger,…}.ts`, `native/`), the live deployment and mainnet. Matches run off-chain and never move or burn NFTs.

**Checks:** the final integration gate passed in `node:24-alpine`: `npm test` 241/242 with 0 fail (1 skipped), and `npm run build` passes. The repo needs Node 24, because Node 20 fails 12 tests falsely.

**Decisions for Eric** (see REPORT.md, Known issues and Next steps):
1. whether the live node should set `WIKIDECK_USER_AGENT`
2. the Xcode licence, which you should accept yourself
3. #49 in the fork, a bot change held after the freeze
4. on-chain host rewards (proposal only, in HOSTING.md)

🤖 Generated with [Claude Code](https://claude.com/claude-code)Reviewed-on: WikiDeck/wikideck#22

Co-authored-by: Claude <claude@eom.dev>
2026-11-17 17:40:58 +00:00
eric 636f5b9c77 V2.1 (#21)
Working version Reviewed-on: WikiDeck/wikideck#21
2026-11-01 22:07:51 +00:00
eric 1edf2e6200 Merge pull request 'More cards' (#20) from v2 into main
Reviewed-on: WikiDeck/wikideck#20
2026-10-19 22:57:02 +00:00
460 changed files with 61250 additions and 17553 deletions
+4
View File
@@ -28,3 +28,7 @@ dist-ssr
*.njsproj
*.sln
*.sw?
# Native RandomX engine for the app (scripts/build-randomx-android.sh)
native/build-android-*/
android/app/src/main/jniLibs/
+16 -17
View File
@@ -12,12 +12,19 @@ WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
ARG WIKIDECK_NETWORK=testnet
ARG WIKIDECK_NETWORK=mainnet
ARG WIKIDECK_GENESIS_TIME=1793491200
ENV VITE_WIKIDECK_NETWORK=$WIKIDECK_NETWORK
ENV VITE_WIKIDECK_GENESIS_TIME=$WIKIDECK_GENESIS_TIME
RUN npm run build
FROM build AS test
RUN apk add --no-cache libstdc++ postgresql-client openssl
RUN apk add --no-cache libstdc++
ENV WIKIDECK_NETWORK=testnet \
WIKIDECK_GENESIS_TIME=1792411200 \
VITE_WIKIDECK_NETWORK=testnet \
VITE_WIKIDECK_GENESIS_TIME=1792411200
RUN npm run build
COPY --from=randomx-build /native/build/wikideck-randomx /app/native/wikideck-randomx
ENV RANDOMX_BINARY=/app/native/wikideck-randomx
CMD ["npm", "test"]
@@ -29,11 +36,17 @@ RUN npm ci --omit=dev --ignore-scripts && npm cache clean --force
FROM node:24-alpine AS runtime
RUN apk add --no-cache libstdc++
ARG WIKIDECK_NETWORK=mainnet
ARG WIKIDECK_GENESIS_TIME=1793491200
ENV NODE_ENV=production \
HOST=0.0.0.0 \
PORT=3001 \
WIKIDECK_DATA_DIR=/app/data \
RANDOMX_BINARY=/app/native/wikideck-randomx
RANDOMX_BINARY=/app/native/wikideck-randomx \
WIKIDECK_NETWORK=$WIKIDECK_NETWORK \
WIKIDECK_GENESIS_TIME=$WIKIDECK_GENESIS_TIME \
WIKIDECK_IMAGE_NETWORK=$WIKIDECK_NETWORK \
WIKIDECK_IMAGE_GENESIS_TIME=$WIKIDECK_GENESIS_TIME
WORKDIR /app
COPY --from=production-deps /app/node_modules ./node_modules
COPY package.json ./
@@ -42,13 +55,6 @@ COPY server ./server
COPY shared ./shared
COPY scripts/node-backup.ts ./scripts/node-backup.ts
COPY scripts/ops-check.ts ./scripts/ops-check.ts
COPY scripts/custody-db.ts ./scripts/custody-db.ts
COPY scripts/monero-observer-worker.ts ./scripts/monero-observer-worker.ts
COPY scripts/custody-deployment-init.ts ./scripts/custody-deployment-init.ts
COPY scripts/custody-deployment-check.ts ./scripts/custody-deployment-check.ts
COPY scripts/monero-daemon-check.ts ./scripts/monero-daemon-check.ts
COPY scripts/pilot-monero-deposit-address.ts ./scripts/pilot-monero-deposit-address.ts
COPY scripts/pilot-monero-observe-once.ts ./scripts/pilot-monero-observe-once.ts
COPY --from=randomx-build /native/build/wikideck-randomx ./native/wikideck-randomx
RUN mkdir -p /app/data && chown node:node /app/data
USER node
@@ -58,10 +64,3 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
# Node 24 strips the server's erasable TypeScript; no tsx/dev dependencies at runtime.
CMD ["node", "--experimental-strip-types", "server/index.ts"]
# Explicit one-shot maintenance image, derived from runtime so it has no development dependencies.
FROM runtime AS custody-backup
USER root
RUN apk add --no-cache postgresql-client
COPY scripts/custody-pair-backup.ts ./scripts/custody-pair-backup.ts
USER node
ENTRYPOINT ["node", "--experimental-strip-types", "scripts/custody-pair-backup.ts"]
+4
View File
@@ -0,0 +1,4 @@
FROM node:24-alpine
WORKDIR /app
COPY package.json ./
RUN npm install --package-lock-only --ignore-scripts
+46 -48
View File
@@ -1,42 +1,53 @@
# Wikideck
**Production roadmap:** see the [production delivery plan](docs/production-plan.md) for XMR-native pricing, custodial-market implementation, fixed-price-first launch scope and release gates. New v3 listings use exact native-XMR prices; historical v2 USD records keep their original terms. All payments remain simulated. The [custodial design and implementation status](docs/custodial-market-design.md) distinguish the sandbox ledger from future live custody.
Wikideck is an experimental blockchain game about **mining, collecting, and trading illustrated Wikipedia cards**. Mine a block with the native RandomX CPU miner to earn a card, build a collection in a local wallet, and trade cards directly with another player.
Wikideck is an NFT blockchain where mining a block rewards the miner with a collectible card based on a Wikipedia page. Build collections, trade cards with other collectors, or host a peer with its own marketplace. Trading card games (TCGs), including custom games hosted by peers, are planned for a later release.
**Mainnet-first, still NO-GO:** the default image, runtime profile, and Compose service are mainnet, but the network is experimental, unaudited, and not launched. A local build is not production approval. See the [card-only production plan](docs/card-only-production-plan.md) and [mainnet launch gates](docs/mainnet-launch.md).
Mining uses **RandomX, the proof-of-work algorithm also used by Monero**, designed to keep general-purpose consumer CPUs competitive. Wikideck is an independent blockchain, not part of Monero or its mining/security network. Hardware, total network hashpower and difficulty determine results; no particular mining reward rate or profitability is guaranteed.
**This is a local test network, not a public mainnet or an investment product.** No public bootnodes or hosted network are provided. Test NFTs have no promised value. Do not use funds or valuable assets. This project is not affiliated with Wikipedia or the Wikimedia Foundation.
**Mainnet is a gated candidate, not an operating public network or an investment product.** There are no hosted nodes, public bootnodes, or automatic peer discovery. No external audit is planned; the operator accepts that residual risk. Cards have no promised monetary value. Do not use funds or valuable assets. This project is not affiliated with Wikipedia or the Wikimedia Foundation.
## Collect, trade, and build your own community
## Mine, collect, and trade cards
- **Mine Wikipedia cards.** Each accepted block mints a native NFT for the miner from a random illustrated English Wikipedia article. The card records the article snapshot and mint-time statistics. The same page can appear on more than one distinct card. The reward is a card representing a page—not ownership of the page, its copyright, or a payment to Wikipedia.
- **Build collections.** Assemble a broad cabinet of discoveries or focus on a subject, series or theme. Browse public decks and exchange up to eight cards on each side in one atomic trade.
- **Buy and sell in peer-hosted markets.** Running a peer lets you host a market for the shared chain's cards. Your community can be general-purpose or focus on a particular collection. Listings, auctions and orders belong to that market host; card ownership and mined transfers are shared through the blockchain.
- **Support the host and project author.** Sales allocate a configurable hosting fee to the peer's market operator (2.5% by default) and a separate hardcoded **1% author fee** to the project's fixed XMR address. Both are deducted from seller proceeds; the default total is 3.5%. In the intended cryptocurrency settlement model the host retains its fee, while the author allocation is paid separately. Today all payment, fee and payout accounting is simulated.
- **Cryptocurrency checkout.** New market prices are quoted directly in **Monero (XMR)** atomic units. The current testnet checkout is mock-only: no real cryptocurrency is accepted or sent.
- **Play TCGs — planned.** The roadmap is to use these same cards in trading card games and let peers host custom TCG experiences. There is no playable game engine, match system, deck legality or custom rules hosting yet. Current card stats are not a promise of future game balance.
- **Build collections.** Browse chain discoveries or focus on a subject, series, or theme. Cards are controlled by your encrypted local wallet.
- **Trade directly.** Look up another public wallet and exchange up to eight cards on each side in one signed, atomic trade. Offers are shared between the two players; the app does not list cards for sale or process payments.
- **Gameplay is not included yet.** The current release supports mining, collecting, transfers, and direct trades. Playable card games are future work.
## Peer ownership and customization
**Understand the market before trading:** [Payment flow and buyer/seller protections](docs/market-transparency.md) explains who controls cards and funds, both fees, deadlines, refund/reorg limits, privacy and host accountability. Current payments are mock-only; seller delivery still transfers the actual card. No guaranteed refund, insurance or built-in arbitration is provided.
The project's open-source direction is to give peer operators substantial freedom to adapt their own market: presentation, community focus, curation and future game rules. A collection-focused community can run the current general listing interface today; built-in collection filters, moderation/admission tooling and custom TCG hosting are future work, not existing operator controls. Operators can already configure their hosting fee and run their own local marketplace journal.
Market customization does not let one peer rewrite shared NFT ownership or unilaterally change consensus for other peers. Compatible peers must follow the same network rules. The author fee is hardcoded in the distributed implementation; it is not a hosting configuration option. Any source modifications and redistribution must respect the eventual project license and third-party licenses.
**Licensing status:** this checkout does not yet contain a project LICENSE file. Source availability alone does not grant open-source modification/redistribution rights. Publishing an appropriate license is still required before describing those freedoms as legally granted. Wikipedia text/images and dependencies retain their separate licenses; a Wikideck software license would not replace them.
**Licensing status:** this checkout does not yet contain a project LICENSE file. Source availability alone does not grant open-source modification/redistribution rights. Wikipedia text/images and dependencies retain their separate licenses.
## What's available now
| Available in the testnet | Planned / not enabled |
| Available in the mainnet-first codebase | Not included |
| --- | --- |
| RandomX mining and illustrated Wikipedia NFT rewards | Reviewed production network launch |
| Encrypted local wallets, collections and atomic card trades | Playable TCGs and peer-hosted custom games |
| Per-peer fixed-price listings and timed auctions | Built-in collection-specific curation/admission controls |
| Mock native-XMR checkout and host/author fee accounting | Real cryptocurrency settlement and production custody operations |
| RandomX mining and illustrated Wikipedia card rewards | Playable card games |
| Encrypted local wallets, collections, transfers, and atomic card trades | Production network launch |
| Mainnet candidate by default; testnet only as an explicit local development fixture | Public bootstrap network or production readiness |
## Run the three-node testnet (Docker)
## Default: mainnet candidate (Docker)
The default mainnet genesis is fixed at **November 1, 2026, 00:00 UTC**
(`1793491200`). Rebuilding the current Dockerfile requires no special genesis
argument and no wait until January. Publish the rebuilt image as
`ericomeehan/wikideck:latest` before using the three-node Ansible playbook; it reads
the chain ID automatically and configures the risk acknowledgment and internal
peers. This updates source defaults, not an already published image or an existing
ledger's chain identity. Create/unlock a wallet in the deployed HTTPS UI and run
the native miner to produce cards and confirm transfers/trades.
Install Docker Desktop with Linux containers and Docker Compose v2. From the repository root:
```sh
docker compose up --build -d
docker compose ps
```
The default Compose service is mainnet-first and binds only to **http://127.0.0.1:3201** behind a separately configured HTTPS edge. It intentionally exits until the exact chain approval, explicit unaudited-risk acceptance, genesis time, HTTPS origin, and at least two valid public HTTPS peers are configured. Do not set these to placeholders just to make the process start. See [mainnet launch gates](docs/mainnet-launch.md). The node does not mine automatically. Stop it with `docker compose down`; the ledger volume remains. **Do not add `-v` unless you intend to delete that data.**
For isolated development, use the explicitly testnet-only [three-node fixture](#explicit-testnet-development-fixture-docker). `npm run dev` also pins both the API and Vite browser build to that testnet fixture; it does not silently change a production build.
## Explicit testnet development fixture (Docker)
Install Docker Desktop with Linux containers and Docker Compose v2. From the repository root, start three connected nodes:
@@ -56,20 +67,10 @@ docker compose -f compose.testnet.yaml down
The target block interval is **15 minutes**. The volumes persist across stops and rebuilds. **Do not add `-v` unless you intend to delete all three ledgers.** Back up wallets separately. Protocol v6 adds atomic multi-card trades and a new chain identity; earlier v2–v5 ledgers and encrypted backups are not compatible. To keep old Docker data intact while trying v6, use a separate Compose project name, for example `docker compose -p wikideck-v6 -f compose.testnet.yaml up --build -d`, and use the same `-p wikideck-v6` for subsequent Compose commands. The default `docker compose up --build -d` uses [compose.yaml](compose.yaml): it starts one isolated node on port 3001 with a different volume.
For an existing host install, keep the old data directory intact and set `WIKIDECK_DATA_DIR` to a new empty directory before starting protocol v6. The node intentionally fails closed on an old-protocol ledger; it does not reset or migrate it. A v6 JSON ledger is imported into SQLite on first startup and left in place as a recovery copy.
For an existing host install, keep the old data directory intact and set `WIKIDECK_DATA_DIR` to a new empty directory before starting protocol v6. The node intentionally fails closed on an old-protocol ledger; it does not reset or migrate it. A v6 JSON ledger is imported into SQLite on first startup and left in place as a recovery copy. `npm start` defaults to the gated mainnet identity; use `npm run dev` only for local testnet development.
## Run on your host
### Optional custody accounting preview
**Optional market hosting:** set `WIKIDECK_MARKET_ENABLED=0` to suppress public listings/new trading, or `WIKIDECK_MARKET_TRADING_ENABLED=0` for a browsable paused market. Configure hosting-fee payouts with `WIKIDECK_MARKET_HOST_FEE_ADDRESS` (defaults to the author wallet); the fixed 1% author fee remains separate. Existing orders/balance resolution stay accessible. See [host configuration](docs/market-host-configuration.md) for strict values, signed recipient snapshots and safe container recreation.
For a **persistent PostgreSQL-backed local stack**, use [the deployment guide](docs/persistent-custody-sandbox.md) and [compose.custody.yaml](compose.custody.yaml), or the VS Code **Start persistent custody sandbox** task. It starts PostgreSQL plus Wikideck at port 3422, with generated scoped credentials, verified database TLS and explicit migrations. Existing single/three-node commands are unchanged. This uses separate volumes and does not migrate existing SQLite custody or enable real payments.
The marketplace's **Custody preview** tab is separate from existing mock checkout. Explicit `WIKIDECK_CUSTODY_MODE=sandbox` on the server enables fictitious test balances, signed fixed-price reservations and withdrawal holds on testnet only. Default is `off`; live modes and mainnet sandbox fail closed. Use a disposable data directory and configure `PUBLIC_ORIGIN` to the exact browser origin. No Monero addresses, wallet RPC or real withdrawals are available. [PostgreSQL financial storage](docs/postgres-financial-storage.md) is selectable with `WIKIDECK_CUSTODY_STORAGE=postgres`, explicit schema/role setup and a secret-file connection configuration; existing SQLite custody requires a stopped-node import, never automatic fallback.
Reservations stop at `awaiting-lock` because reviewed NFT sale-lock consensus rules are not implemented. They can be cancelled while their outbox intent is blocked; they do not deliver cards. Local SQLite custody is included by stopped-node backup/restore when present; PostgreSQL-bound nodes require coordinated database/node backups and the SQLite-only backup command refuses them. Real treasury observation/settlement, signing controls and production review remain future work. See [the implementation record](docs/custodial-market-design.md).
Requirements: Node.js 24, npm, Git, CMake 3.24+, and a C/C++17 toolchain. The first native-engine configuration downloads the pinned RandomX source over HTTPS. On Windows, install a compatible toolchain (for example, MinGW-w64 and make) and use the matching CMake generator. Do not change generators in an existing `native/build` directory; use a fresh build directory when switching toolchains.
Install dependencies and build the native RandomX engine:
@@ -91,19 +92,19 @@ The node listens at **http://127.0.0.1:3001** by default. For development, `npm
Open the wallet panel to explicitly create an encrypted local P-256 wallet, unlock an existing vault, or encrypt a legacy plaintext wallet without changing its identity. Nothing is silently generated or unlocked at startup. Choose a strong local password of at least 12 characters. **Wallet backup & recovery** downloads a separately password-encrypted portable backup; keep the file outside the repository and its password separately, and test recovery in another browser profile.
New/migrated local vaults encrypt the key in IndexedDB; the unlocked key remains exportable in tab memory for signing and backup. Manual locking, five-minute inactivity, a four-hour absolute lifetime, reload, or hiding/leaving the tab ends the session. Same-origin compromise can still capture passwords or abuse an unlocked signer. Forgotten local passwords cannot be reset: recover from a usable backup. Legacy disk copies may retain old plaintext keys even after migration. Wallets are scoped to an origin (scheme, hostname, and port), so a backup must be restored at another origin to use the same identity there. Recovery does not move assets between chains. See [encrypted wallet lifecycle and remaining risks](docs/wallet-security.md).
New/migrated local vaults encrypt the key in an IndexedDB database scoped to the exact chain ID; v2 encrypted backups authenticate that same chain ID. Original fixed-testnet v1 backups remain recoverable only on that original testnet. The unlocked key remains exportable in tab memory for signing and backup. Manual locking, five-minute inactivity, a four-hour absolute lifetime, reload, or hiding/leaving the tab ends the session. Same-origin compromise can still capture passwords or abuse an unlocked signer. Forgotten local passwords cannot be reset: recover from a usable backup. Legacy disk copies may retain old plaintext keys even after migration. Wallets are scoped to an origin (scheme, hostname, and port), so a backup must be restored at another origin to use the same identity there. Recovery does not move assets between chains. See [encrypted wallet lifecycle and remaining risks](docs/wallet-security.md).
The current testnet wallet is separate from any wallet used by an older demo. There is no automatic migration. See [consensus, wallets, and operational limits](docs/testnet-consensus.md) and the in-app backup warnings for more detail.
Each genesis has a separate browser wallet store, and backups cannot cross chain identities. Testnet remains only as an explicit development fixture; there is no automatic migration from older demos. See [consensus, wallets, and operational limits](docs/testnet-consensus.md) and the in-app backup warnings for more detail.
## Mine Wikipedia cards with RandomX
Mining uses the native CPU RandomX engine. First build the engine, download an encrypted wallet backup, then run the CLI from an interactive terminal and enter the password at its hidden prompt:
```sh
npm run miner -- --wallet "path/to/encrypted-backup.json" --consent --node http://127.0.0.1:3101 --blocks 3
npm run miner:testnet -- --wallet "path/to/encrypted-backup.json" --consent --node http://127.0.0.1:3101 --blocks 3
```
Use port 3001 for the default single host/Docker node, or 3101–3103 for the three-node Docker testnet. The command above uses node-a. The miner defaults to one worker, light mode, and one block; `--blocks 3` requests up to three accepted blocks. Press **Ctrl+C** to stop it. Do not put the backup password in a command, environment variable, or repository file. The backup and password are decrypted locally and are not sent to the node.
The example is intentionally testnet-only and uses node-a; the dedicated command pins that profile and its fixed genesis. For mainnet, use `npm run miner` with a chain-bound mainnet backup and the configured HTTPS node origin after satisfying the mainnet launch gates. The miner defaults to one worker, light mode, and one block; `--blocks 3` requests up to three accepted blocks. Press **Ctrl+C** to stop it. Do not put the backup password in a command, environment variable, or repository file. The backup and password are decrypted locally and are not sent to the node.
Each template request asks English Wikipedia for up to ten random pages and retries at most three times to find one with an image and readable extract. The same page may be selected again. The node also captures page size, language-link count, revision, pageviews, and derived scores for the mint-time snapshot. If Wikipedia cannot supply the article or its metadata, template creation returns an error; there is no fixed-article fallback. Validators check and commit the included snapshot without contacting Wikipedia during consensus validation.
@@ -114,8 +115,7 @@ Light mode needs a 256 MiB cache plus scratchpad and process overhead. `--fast`
- **Discover** shows preview examples until the node has mined blocks; previews are not owned NFTs. Minted cards can reference the same page, but each carries its own captured stats snapshot.
- **My collection** shows NFTs owned by the active local wallet on the connected node's canonical chain.
- **Block explorer** distinguishes block IDs, NFT token IDs, and RandomX proof hashes. A submitted transfer is pending until a block confirms it. Reorganizations can change canonical ownership and confirmations.
- **Trade decks** lets you look up another public wallet by receive address, select up to eight cards on each side, prepare a signed offer, and accept another player's offer. Offers are shared as JSON for the other player to review; they are not submitted until accepted. The two parties sign the same card list, and validators apply the whole bundle atomically or reject it entirely. Offers are not reservations: before acceptance the app re-checks ownership, maturity, sequences, and pending activity; stale offers must be recreated.
- **Marketplace** is the connected peer's market: new fixed-price listings and timed auctions use native XMR amounts; historical USD listings remain read-only. Checkout, fees and payouts are simulated. Sales allocate a configurable fee to the hosting operator (default 2.5%) and a hardcoded 1% author fee (3.5% total by default). Sellers still sign real card delivery after the mock payment step. **Never send real XMR: no payable checkout address or live processor is enabled.** Listings/orders are local to the selected market host, not gossiped; listing does not lock a card on-chain. See [peer markets, fees and payment status](docs/marketplace.md).
- **Trade cards** lets you look up another public wallet by receive address, select up to eight cards on each side, prepare a signed offer, and accept another player's offer. Offers are shared as JSON for the other player to review; they are not submitted until accepted. The two parties sign the same card list, and validators apply the whole bundle atomically or reject it entirely. Offers are not reservations: before acceptance the app re-checks ownership, maturity, sequences, and pending activity; stale offers must be recreated.
- Each minted card shows current Wikipedia statistics alongside its immutable at-mint snapshot: pageviews, article size, language links, revision, and derived scores. Current values may change; at-mint values are committed to the block. Missing pageview data stays unavailable, not zero.
- The appearance selector offers Catppuccin Mocha, Macchiato, Frappé, and Latte themes.
@@ -123,9 +123,9 @@ The browser interface trusts the connected node's reported state. It does not in
## Mainnet candidate · launch gated
**Production status: NO-GO pending remediation and independent review.** See the [security review](docs/security-review.md) and [operator launch checklist](docs/operator-launch.md). A read-only `launch:preflight` script reports blockers and local gate status without launching or granting approval.
**Production status: NO-GO pending network, capacity, deployment, and recovery evidence.** External audits are not planned; the operator accepts the residual risk, and the candidate must not be described as audited or certified. See the [security review](docs/security-review.md) and [operator launch checklist](docs/operator-launch.md). A read-only `launch:preflight` script reports blockers and local gate status without launching or granting approval.
A separate mainnet profile has its own network/genesis identity, ledger and market directories, browser wallet, backup checks, and opt-in [Compose definition](compose.mainnet.yaml). It preserves the existing testnet chain and does not migrate testnet cards. **No production network has been launched or certified by this work.** Startup requires explicit chain-specific approval, an operator review attestation, the candidate genesis time, HTTPS origins and multiple configured peers. Real payments remain blocked even then. See [the candidate launch gates and production checklist](docs/mainnet-launch.md).
The mainnet profile is the default and has a deployment-pinned network/genesis identity, separate ledger directory, chain-ID-scoped browser wallet, and chain-bound backups. The alternate [Compose definition](compose.mainnet.yaml) is also explicitly mainnet. Testnet is available only through the dedicated development/test harness. **No production network has been launched or certified by this work.** Startup requires explicit chain-specific approval, explicit unaudited-risk acceptance, the chosen genesis time in the built image, HTTPS origin, and multiple configured public peers. See [the mainnet launch gates and production checklist](docs/mainnet-launch.md).
## Tests and development checks
@@ -151,15 +151,13 @@ This mines three real blocks using disposable identities. It changes the testnet
## Network and safety limits
Live XMR payments are not implemented. The selected custody design uses direct Monero wallet/daemon observation and a pooled liability ledger; no real deposits, credits, withdrawals, or sale settlement are enabled. See the [custodial market design](docs/custodial-market-design.md) and [launch hold points](docs/operator-launch.md).
[Deployment and recovery preparation](docs/operations-recovery.md) includes explicit trusted-proxy configuration, opt-in loopback-only diagnostics and `ops:check`, plus stopped-node paired `node:backup` create/verify/new-directory restore tooling. Backups contain sensitive market data and require external encryption/access control. Tools do not configure TLS/alerts or authorize production launch/restore.
[Deployment and recovery preparation](docs/operations-recovery.md) includes explicit trusted-proxy configuration, opt-in loopback-only diagnostics and `ops:check`, plus stopped-node `node:backup` create/verify/new-directory restore tooling. New backups contain the ledger only; creation refuses to proceed if legacy financial journals or bindings remain, so archive those separately before retiring old deployments. Tools do not configure TLS/alerts or authorize production launch/restore.
[Stage-1 node resource controls](docs/node-resources.md) bound global RPC admission, response bytes and canonical page sizes. The UI reuses paged history; legacy full-state responses stop beyond 128 blocks. A consent-gated loopback-only smoke-load script is available as `test:rpc-load`. This does not resolve long-chain/DAG storage limits or establish production capacity.
Nodes use only explicitly configured peers; there is no discovery service or public bootstrap network. The peer, storage, and HTTP configuration is documented in [docs/testnet-consensus.md](docs/testnet-consensus.md). The implementation is experimental: it has no consensus transaction fees or established economic security (market fees are off-chain simulations), and remains vulnerable to resource exhaustion, isolation/eclipsing, censorship, majority-hashpower attacks, and reorganizations. The ledger now uses transactional SQLite/WAL storage and sparse per-block NFT-state deltas, but nodes still retain DAG block records in memory, rebuild state roots over the full NFT set, and revalidate all proofs at startup. It is not yet an archival-scale production design. HTTPS, container hardening, and passing tests do not constitute a security audit.
Nodes use only explicitly configured peers; there is no discovery service or public bootstrap network. The peer, storage, and HTTP configuration is documented in [docs/testnet-consensus.md](docs/testnet-consensus.md). The implementation is experimental: it has no established economic security and remains vulnerable to resource exhaustion, isolation/eclipsing, censorship, majority-hashpower attacks, and reorganizations. The ledger now uses transactional SQLite/WAL storage and sparse per-block NFT-state deltas, but nodes still retain DAG block records in memory, rebuild state roots over the full NFT set, and revalidate all proofs at startup. It is not yet an archival-scale production design. HTTPS, container hardening, and passing tests do not constitute a security audit.
Before considering any broader deployment, the protocol and cryptography would need independent audits, adversarial network testing, hardened abuse controls, and tested recovery procedures. Do not expose a public node or use valuable assets on this experimental network.
Before considering any broader deployment, complete adversarial network testing, hardened abuse controls, and recovery procedures. External protocol/cryptography audits are not planned; this leaves accepted residual risk. Do not expose a public node or use valuable assets on this experimental network.
## Attribution
+101
View File
@@ -0,0 +1,101 @@
# Using Android gitignore template: https://github.com/github/gitignore/blob/HEAD/Android.gitignore
# Built application files
*.apk
*.aar
*.ap_
*.aab
# Files for the ART/Dalvik VM
*.dex
# Java class files
*.class
# Generated files
bin/
gen/
out/
# Uncomment the following line in case you need and you don't have the release build type files in your app
# release/
# Gradle files
.gradle/
build/
# Local configuration file (sdk path, etc)
local.properties
# Proguard folder generated by Eclipse
proguard/
# Log Files
*.log
# Android Studio Navigation editor temp files
.navigation/
# Android Studio captures folder
captures/
# IntelliJ
*.iml
.idea/workspace.xml
.idea/tasks.xml
.idea/gradle.xml
.idea/assetWizardSettings.xml
.idea/dictionaries
.idea/libraries
# Android Studio 3 in .gitignore file.
.idea/caches
.idea/modules.xml
# Comment next line if keeping position of elements in Navigation Editor is relevant for you
.idea/navEditor.xml
# Keystore files
# Uncomment the following lines if you do not want to check your keystore files in.
#*.jks
#*.keystore
# External native build folder generated in Android Studio 2.2 and later
.externalNativeBuild
.cxx/
# Google Services (e.g. APIs or Firebase)
# google-services.json
# Freeline
freeline.py
freeline/
freeline_project_description.json
# fastlane
fastlane/report.xml
fastlane/Preview.html
fastlane/screenshots
fastlane/test_output
fastlane/readme.md
# Version control
vcs.xml
# lint
lint/intermediates/
lint/generated/
lint/outputs/
lint/tmp/
# lint/reports/
# Android Profiling
*.hprof
# Cordova plugins for Capacitor
capacitor-cordova-android-plugins
# Copied web assets
app/src/main/assets/public
# Generated Config files
app/src/main/assets/capacitor.config.json
app/src/main/assets/capacitor.plugins.json
app/src/main/res/xml/config.xml
+2
View File
@@ -0,0 +1,2 @@
/build/*
!/build/.npmkeep
+61
View File
@@ -0,0 +1,61 @@
apply plugin: 'com.android.application'
android {
namespace "dev.eom.wikideck"
compileSdk rootProject.ext.compileSdkVersion
defaultConfig {
applicationId "dev.eom.wikideck"
minSdkVersion rootProject.ext.minSdkVersion
targetSdkVersion rootProject.ext.targetSdkVersion
versionCode 1
versionName "1.0"
testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
aaptOptions {
// Files and dirs to omit from the packaged assets dir, modified to accommodate modern web apps.
// Default: https://android.googlesource.com/platform/frameworks/base/+/282e181b58cf72b6ca770dc7ca5f91f135444502/tools/aapt/AaptAssets.cpp#61
ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
}
}
packagingOptions {
jniLibs {
// The RandomX engine (jniLibs/<abi>/libwikideck_randomx.so) is an executable, not a JNI library.
// Android may exec it only from the extracted nativeLibraryDir, so keep legacy extraction.
useLegacyPackaging true
}
}
buildTypes {
release {
minifyEnabled false
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
}
}
}
repositories {
flatDir{
dirs '../capacitor-cordova-android-plugins/src/main/libs', 'libs'
}
}
dependencies {
implementation fileTree(include: ['*.jar'], dir: 'libs')
implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
implementation "androidx.coordinatorlayout:coordinatorlayout:$androidxCoordinatorLayoutVersion"
implementation "androidx.core:core-splashscreen:$coreSplashScreenVersion"
implementation project(':capacitor-android')
testImplementation "junit:junit:$junitVersion"
androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
implementation project(':capacitor-cordova-android-plugins')
}
apply from: 'capacitor.build.gradle'
try {
def servicesJSON = file('google-services.json')
if (servicesJSON.text) {
apply plugin: 'com.google.gms.google-services'
}
} catch(Exception e) {
logger.info("google-services.json not found, google-services plugin not applied. Push Notifications won't work")
}
+20
View File
@@ -0,0 +1,20 @@
// DO NOT EDIT THIS FILE! IT IS GENERATED EACH TIME "capacitor update" IS RUN
android {
compileOptions {
sourceCompatibility JavaVersion.VERSION_21
targetCompatibility JavaVersion.VERSION_21
}
}
apply from: "../capacitor-cordova-android-plugins/cordova.variables.gradle"
dependencies {
implementation project(':capacitor-app')
implementation project(':capacitor-browser')
}
if (hasProperty('postBuildExtras')) {
postBuildExtras()
}
+21
View File
@@ -0,0 +1,21 @@
# Add project specific ProGuard rules here.
# You can control the set of applied configuration files using the
# proguardFiles setting in build.gradle.
#
# For more details, see
# http://developer.android.com/guide/developing/tools/proguard.html
# If your project uses WebView with JS, uncomment the following
# and specify the fully qualified class name to the JavaScript interface
# class:
#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
# public *;
#}
# Uncomment this to preserve the line number information for
# debugging stack traces.
#-keepattributes SourceFile,LineNumberTable
# If you keep the line number information, uncomment this to
# hide the original source file name.
#-renamesourcefileattribute SourceFile
@@ -0,0 +1,26 @@
package com.getcapacitor.myapp;
import static org.junit.Assert.*;
import android.content.Context;
import androidx.test.ext.junit.runners.AndroidJUnit4;
import androidx.test.platform.app.InstrumentationRegistry;
import org.junit.Test;
import org.junit.runner.RunWith;
/**
* Instrumented test, which will execute on an Android device.
*
* @see <a href="http://d.android.com/tools/testing">Testing documentation</a>
*/
@RunWith(AndroidJUnit4.class)
public class ExampleInstrumentedTest {
@Test
public void useAppContext() throws Exception {
// Context of the app under test.
Context appContext = InstrumentationRegistry.getInstrumentation().getTargetContext();
assertEquals("com.getcapacitor.app", appContext.getPackageName());
}
}
+51
View File
@@ -0,0 +1,51 @@
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:roundIcon="@mipmap/ic_launcher_round"
android:supportsRtl="true"
android:usesCleartextTraffic="true"
android:theme="@style/AppTheme">
<activity
android:windowSoftInputMode="adjustResize"
android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation"
android:name=".MainActivity"
android:label="@string/title_activity_main"
android:theme="@style/AppTheme.NoActionBarLaunch"
android:launchMode="singleTask"
android:exported="true">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
<!-- SSO redirect (RFC 8252 private-use scheme, registered with Dex as dev.eom.wikideck:/oauth/callback) -->
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="dev.eom.wikideck" />
</intent-filter>
</activity>
<provider
android:name="androidx.core.content.FileProvider"
android:authorities="${applicationId}.fileprovider"
android:exported="false"
android:grantUriPermissions="true">
<meta-data
android:name="android.support.FILE_PROVIDER_PATHS"
android:resource="@xml/file_paths"></meta-data>
</provider>
</application>
<!-- Permissions -->
<uses-permission android:name="android.permission.INTERNET" />
</manifest>
@@ -0,0 +1,14 @@
package dev.eom.wikideck;
import android.os.Bundle;
import com.getcapacitor.BridgeActivity;
public class MainActivity extends BridgeActivity {
@Override
public void onCreate(Bundle savedInstanceState) {
// Local plugins must be registered before the bridge starts.
registerPlugin(MinerPlugin.class);
super.onCreate(savedInstanceState);
}
}
@@ -0,0 +1,264 @@
package dev.eom.wikideck;
import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;
import android.content.IntentFilter;
import android.os.BatteryManager;
import android.os.Build;
import android.os.PowerManager;
import com.getcapacitor.JSObject;
import com.getcapacitor.Plugin;
import com.getcapacitor.PluginCall;
import com.getcapacitor.PluginMethod;
import com.getcapacitor.annotation.CapacitorPlugin;
import java.io.BufferedReader;
import java.io.File;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;
import java.util.regex.Pattern;
/**
* Native RandomX engine for the WikiDeck app (sideload build only, see docs/night2/MOBILE_MINING.md).
*
* The plugin only runs the pinned `wikideck-randomx` executable (shipped as jniLibs/<abi>/libwikideck_randomx.so)
* in LIGHT mode and speaks its line protocol (docs/randomx-native.md). It never sees wallet keys: the WebView builds
* the work blob, signs the block claim with the web wallet, and submits it to the node. This class also enforces the
* device safeguards: engines are killed when the app goes to the background, on battery saver, when the device is
* hot, or when the battery is low and not charging. Each stop is reported to the WebView as a `halted` event.
*/
@CapacitorPlugin(name = "WikiDeckMiner")
public class MinerPlugin extends Plugin {
private static final String BINARY = "libwikideck_randomx.so";
private static final int MAX_THREADS = 4;
/** At or above Android's THERMAL_STATUS_MODERATE we stop. */
private static final int THERMAL_LIMIT = 2;
/** Battery temperature limit in tenths of a degree Celsius. */
private static final int BATTERY_TEMP_LIMIT = 400;
private static final int LOW_BATTERY_PERCENT = 20;
private static final Pattern HEX = Pattern.compile("^[0-9a-f]+$");
private final List<Engine> engines = new ArrayList<>();
private BroadcastReceiver receiver;
private Object thermalListener;
/** One long-lived engine process with exactly one outstanding command (it is strictly request/response). */
private static final class Engine {
final Process process;
final OutputStream in;
final BufferedReader out;
final ExecutorService worker = Executors.newSingleThreadExecutor();
Engine(Process process) {
this.process = process;
this.in = process.getOutputStream();
this.out = new BufferedReader(new InputStreamReader(process.getInputStream(), StandardCharsets.US_ASCII));
}
String command(String line) throws Exception {
in.write((line + "\n").getBytes(StandardCharsets.US_ASCII));
in.flush();
String reply = out.readLine();
if (reply == null) throw new Exception("RandomX engine exited");
return reply;
}
void kill() {
worker.shutdownNow();
try { in.close(); } catch (Exception ignored) { }
process.destroy();
try { if (!process.waitFor(1, TimeUnit.SECONDS)) process.destroyForcibly(); } catch (InterruptedException ignored) { }
}
}
private File binary() {
return new File(getContext().getApplicationInfo().nativeLibraryDir, BINARY);
}
@Override
public void load() {
receiver = new BroadcastReceiver() {
@Override public void onReceive(Context context, Intent intent) { checkAndHalt(); }
};
IntentFilter filter = new IntentFilter();
filter.addAction(PowerManager.ACTION_POWER_SAVE_MODE_CHANGED);
filter.addAction(Intent.ACTION_BATTERY_CHANGED);
getContext().registerReceiver(receiver, filter);
if (Build.VERSION.SDK_INT >= 29) {
PowerManager pm = (PowerManager) getContext().getSystemService(Context.POWER_SERVICE);
PowerManager.OnThermalStatusChangedListener l = status -> checkAndHalt();
pm.addThermalStatusListener(l);
thermalListener = l;
}
}
@Override
protected void handleOnPause() {
halt("background");
super.handleOnPause();
}
@Override
protected void handleOnDestroy() {
halt("closed");
try { getContext().unregisterReceiver(receiver); } catch (Exception ignored) { }
if (Build.VERSION.SDK_INT >= 29 && thermalListener != null) {
PowerManager pm = (PowerManager) getContext().getSystemService(Context.POWER_SERVICE);
pm.removeThermalStatusListener((PowerManager.OnThermalStatusChangedListener) thermalListener);
}
super.handleOnDestroy();
}
/** Current device state and, if mining must not run, the reason. */
private JSObject conditionsObject() {
PowerManager pm = (PowerManager) getContext().getSystemService(Context.POWER_SERVICE);
Intent battery = getContext().registerReceiver(null, new IntentFilter(Intent.ACTION_BATTERY_CHANGED));
int temp = battery == null ? -1 : battery.getIntExtra(BatteryManager.EXTRA_TEMPERATURE, -1);
int level = battery == null ? -1 : battery.getIntExtra(BatteryManager.EXTRA_LEVEL, -1);
int scale = battery == null ? -1 : battery.getIntExtra(BatteryManager.EXTRA_SCALE, -1);
int plugged = battery == null ? 0 : battery.getIntExtra(BatteryManager.EXTRA_PLUGGED, 0);
int percent = level >= 0 && scale > 0 ? Math.round(100f * level / scale) : -1;
int thermal = Build.VERSION.SDK_INT >= 29 ? pm.getCurrentThermalStatus() : 0;
boolean powerSave = pm.isPowerSaveMode();
String block = null;
if (powerSave) block = "battery-saver";
else if (thermal >= THERMAL_LIMIT) block = "thermal";
else if (temp >= BATTERY_TEMP_LIMIT) block = "battery-hot";
else if (plugged == 0 && percent >= 0 && percent < LOW_BATTERY_PERCENT) block = "battery-low";
JSObject o = new JSObject();
o.put("powerSave", powerSave);
o.put("thermalStatus", thermal);
o.put("batteryTempC", temp < 0 ? null : temp / 10.0);
o.put("batteryPercent", percent);
o.put("charging", plugged != 0);
o.put("cores", Runtime.getRuntime().availableProcessors());
o.put("abi", Build.SUPPORTED_ABIS.length > 0 ? Build.SUPPORTED_ABIS[0] : "unknown");
o.put("engineInstalled", binary().canExecute());
o.put("blocked", block);
return o;
}
private void checkAndHalt() {
String block = conditionsObject().getString("blocked");
if (block != null) halt(block);
}
private synchronized void halt(String reason) {
if (engines.isEmpty()) return;
for (Engine e : engines) e.kill();
engines.clear();
JSObject event = new JSObject();
event.put("reason", reason);
notifyListeners("halted", event);
}
@PluginMethod
public void conditions(PluginCall call) {
call.resolve(conditionsObject());
}
/** Runs upstream's known-vector test (Hash test 1a/2a) on this device. */
@PluginMethod
public void selfTest(PluginCall call) {
new Thread(() -> {
try {
Process p = new ProcessBuilder(binary().getAbsolutePath(), "--self-test").redirectErrorStream(true).start();
p.getOutputStream().close();
StringBuilder text = new StringBuilder();
BufferedReader r = new BufferedReader(new InputStreamReader(p.getInputStream(), StandardCharsets.UTF_8));
for (String line; (line = r.readLine()) != null && text.length() < 2000; ) text.append(line).append('\n');
boolean done = p.waitFor(120, TimeUnit.SECONDS);
if (!done) p.destroyForcibly();
JSObject o = new JSObject();
o.put("ok", done && p.exitValue() == 0);
o.put("output", text.toString().trim());
call.resolve(o);
} catch (Exception e) {
call.reject("Self-test failed to run: " + e.getMessage());
}
}).start();
}
/** Starts 1..4 light-mode engines (more than 2 only while charging) (each needs about 256 MiB). Refuses if a safeguard is active. */
@PluginMethod
public synchronized void start(PluginCall call) {
int threads = call.getInt("threads", 1);
if (threads < 1 || threads > MAX_THREADS || threads > Runtime.getRuntime().availableProcessors()) { call.reject("threads must be 1 to " + MAX_THREADS + " and at most the core count"); return; }
String block = conditionsObject().getString("blocked");
if (block == null && threads > 2 && !conditionsObject().getBool("charging")) block = "max-needs-charging";
if (block != null) { call.reject("Mining is paused: " + block, block); return; }
if (!engines.isEmpty()) { for (Engine e : engines) e.kill(); engines.clear(); }
try {
for (int i = 0; i < threads; i++) {
// No arguments = LIGHT mode. `--fast` (about 2 GiB) is never used on phones.
Process p = new ProcessBuilder(binary().getAbsolutePath()).redirectError(ProcessBuilder.Redirect.to(new File("/dev/null"))).start();
engines.add(new Engine(p));
}
} catch (Exception e) {
for (Engine en : engines) en.kill();
engines.clear();
call.reject("Could not start the RandomX engine: " + e.getMessage());
return;
}
JSObject o = new JSObject();
o.put("threads", threads);
call.resolve(o);
}
@PluginMethod
public synchronized void stop(PluginCall call) {
for (Engine e : engines) e.kill();
engines.clear();
call.resolve();
}
/**
* One bounded batch on engine `lane`: `mine <key> <blob> <target> <nonceOffset> <maxAttempts>`.
* Resolves {found:false} on exhaustion or {found:true, hash, nonce} (nonce as a decimal string).
*/
@PluginMethod
public void mine(PluginCall call) {
String key = call.getString("key", ""), blob = call.getString("blob", ""), target = call.getString("target", "");
int lane = call.getInt("lane", 0), offset = call.getInt("nonceOffset", -1), attempts = call.getInt("maxAttempts", 0);
if (key.length() != 64 || target.length() != 64 || blob.length() < 2 || blob.length() > 16384 || blob.length() % 2 != 0
|| !HEX.matcher(key).matches() || !HEX.matcher(target).matches() || !HEX.matcher(blob).matches()
|| offset < 0 || offset + 8 > blob.length() / 2 || attempts < 1 || attempts > 10000) {
call.reject("Invalid mining request");
return;
}
final Engine engine;
synchronized (this) {
if (lane < 0 || lane >= engines.size()) { call.reject("Miner is not running", "stopped"); return; }
engine = engines.get(lane);
}
String line = "mine " + key + " " + blob + " " + target + " " + offset + " " + attempts;
try {
engine.worker.execute(() -> {
try {
String reply = engine.command(line);
JSObject o = new JSObject();
if (reply.equals("exhausted")) {
o.put("found", false);
} else {
String[] parts = reply.split(" ");
if (parts.length != 3 || !parts[0].equals("found") || parts[1].length() != 64 || !HEX.matcher(parts[1]).matches()
|| !parts[2].matches("^[0-9]{1,20}$")) throw new Exception("Malformed engine reply");
o.put("found", true);
o.put("hash", parts[1]);
o.put("nonce", parts[2]);
}
call.resolve(o);
} catch (Exception e) {
call.reject("Miner stopped: " + e.getMessage(), "stopped");
}
});
} catch (Exception e) {
call.reject("Miner is not running", "stopped");
}
}
}
Binary file not shown.

After

Width:  |  Height:  |  Size: 7.5 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.9 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 9.0 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 14 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 17 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 7.7 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.0 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 9.6 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 13 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 17 KiB

@@ -0,0 +1,34 @@
<vector xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:aapt="http://schemas.android.com/aapt"
android:width="108dp"
android:height="108dp"
android:viewportHeight="108"
android:viewportWidth="108">
<path
android:fillType="evenOdd"
android:pathData="M32,64C32,64 38.39,52.99 44.13,50.95C51.37,48.37 70.14,49.57 70.14,49.57L108.26,87.69L108,109.01L75.97,107.97L32,64Z"
android:strokeColor="#00000000"
android:strokeWidth="1">
<aapt:attr name="android:fillColor">
<gradient
android:endX="78.5885"
android:endY="90.9159"
android:startX="48.7653"
android:startY="61.0927"
android:type="linear">
<item
android:color="#44000000"
android:offset="0.0" />
<item
android:color="#00000000"
android:offset="1.0" />
</gradient>
</aapt:attr>
</path>
<path
android:fillColor="#FFFFFF"
android:fillType="nonZero"
android:pathData="M66.94,46.02L66.94,46.02C72.44,50.07 76,56.61 76,64L32,64C32,56.61 35.56,50.11 40.98,46.06L36.18,41.19C35.45,40.45 35.45,39.3 36.18,38.56C36.91,37.81 38.05,37.81 38.78,38.56L44.25,44.05C47.18,42.57 50.48,41.71 54,41.71C57.48,41.71 60.78,42.57 63.68,44.05L69.11,38.56C69.84,37.81 70.98,37.81 71.71,38.56C72.44,39.3 72.44,40.45 71.71,41.19L66.94,46.02ZM62.94,56.92C64.08,56.92 65,56.01 65,54.88C65,53.76 64.08,52.85 62.94,52.85C61.8,52.85 60.88,53.76 60.88,54.88C60.88,56.01 61.8,56.92 62.94,56.92ZM45.06,56.92C46.2,56.92 47.13,56.01 47.13,54.88C47.13,53.76 46.2,52.85 45.06,52.85C43.92,52.85 43,53.76 43,54.88C43,56.01 43.92,56.92 45.06,56.92Z"
android:strokeColor="#00000000"
android:strokeWidth="1" />
</vector>
@@ -0,0 +1,170 @@
<?xml version="1.0" encoding="utf-8"?>
<vector xmlns:android="http://schemas.android.com/apk/res/android"
android:width="108dp"
android:height="108dp"
android:viewportHeight="108"
android:viewportWidth="108">
<path
android:fillColor="#26A69A"
android:pathData="M0,0h108v108h-108z" />
<path
android:fillColor="#00000000"
android:pathData="M9,0L9,108"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M19,0L19,108"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M29,0L29,108"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M39,0L39,108"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M49,0L49,108"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M59,0L59,108"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M69,0L69,108"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M79,0L79,108"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M89,0L89,108"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M99,0L99,108"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M0,9L108,9"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M0,19L108,19"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M0,29L108,29"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M0,39L108,39"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M0,49L108,49"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M0,59L108,59"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M0,69L108,69"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M0,79L108,79"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M0,89L108,89"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M0,99L108,99"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M19,29L89,29"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M19,39L89,39"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M19,49L89,49"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M19,59L89,59"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M19,69L89,69"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M19,79L89,79"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M29,19L29,89"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M39,19L39,89"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M49,19L49,89"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M59,19L59,89"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M69,19L69,89"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
<path
android:fillColor="#00000000"
android:pathData="M79,19L79,89"
android:strokeColor="#33FFFFFF"
android:strokeWidth="0.8" />
</vector>
Binary file not shown.

After

Width:  |  Height:  |  Size: 3.9 KiB

@@ -0,0 +1,12 @@
<?xml version="1.0" encoding="utf-8"?>
<androidx.coordinatorlayout.widget.CoordinatorLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent"
tools:context=".MainActivity">
<WebView
android:layout_width="match_parent"
android:layout_height="match_parent" />
</androidx.coordinatorlayout.widget.CoordinatorLayout>
@@ -0,0 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
<background android:drawable="@color/ic_launcher_background"/>
<foreground android:drawable="@mipmap/ic_launcher_foreground"/>
</adaptive-icon>
@@ -0,0 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
<background android:drawable="@color/ic_launcher_background"/>
<foreground android:drawable="@mipmap/ic_launcher_foreground"/>
</adaptive-icon>
Binary file not shown.

After

Width:  |  Height:  |  Size: 2.7 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.4 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.2 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.8 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.1 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.7 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.9 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.9 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.4 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.5 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 9.6 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 10 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 9.2 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 16 KiB

@@ -0,0 +1,8 @@
<?xml version="1.0" encoding="utf-8"?>
<resources>
<color name="colorPrimary">#1e1e2e</color>
<color name="colorPrimaryDark">#11111b</color>
<color name="colorAccent">#cba6f7</color>
<!-- Behind the status and navigation bars: matches the dark app header. -->
<color name="wikideckChrome">#11111b</color>
</resources>
@@ -0,0 +1,4 @@
<?xml version="1.0" encoding="utf-8"?>
<resources>
<color name="ic_launcher_background">#FFFFFF</color>
</resources>
@@ -0,0 +1,7 @@
<?xml version='1.0' encoding='utf-8'?>
<resources>
<string name="app_name">WikiDeck</string>
<string name="title_activity_main">WikiDeck</string>
<string name="package_name">dev.eom.wikideck</string>
<string name="custom_url_scheme">dev.eom.wikideck</string>
</resources>
@@ -0,0 +1,25 @@
<?xml version="1.0" encoding="utf-8"?>
<resources>
<!-- Base application theme. -->
<style name="AppTheme" parent="Theme.AppCompat.Light.DarkActionBar">
<!-- Customize your theme here. -->
<item name="colorPrimary">@color/colorPrimary</item>
<item name="colorPrimaryDark">@color/colorPrimaryDark</item>
<item name="colorAccent">@color/colorAccent</item>
</style>
<style name="AppTheme.NoActionBar" parent="Theme.AppCompat.DayNight.NoActionBar">
<item name="windowActionBar">false</item>
<item name="windowNoTitle">true</item>
<item name="android:background">@null</item>
<!-- Dark behind the status/navigation bars (edge-to-edge margins) to match the app chrome. -->
<item name="android:windowBackground">@color/wikideckChrome</item>
<item name="android:windowLightStatusBar">false</item>
</style>
<style name="AppTheme.NoActionBarLaunch" parent="Theme.SplashScreen">
<item name="android:background">@drawable/splash</item>
</style>
</resources>
@@ -0,0 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<paths xmlns:android="http://schemas.android.com/apk/res/android">
<external-path name="my_images" path="." />
<cache-path name="my_cache_images" path="." />
</paths>
@@ -0,0 +1,18 @@
package com.getcapacitor.myapp;
import static org.junit.Assert.*;
import org.junit.Test;
/**
* Example local unit test, which will execute on the development machine (host).
*
* @see <a href="http://d.android.com/tools/testing">Testing documentation</a>
*/
public class ExampleUnitTest {
@Test
public void addition_isCorrect() throws Exception {
assertEquals(4, 2 + 2);
}
}
+16
View File
@@ -0,0 +1,16 @@
#!/bin/sh
# Build the WikiDeck debug APK against the private Night-1 testnet.
# Needs ANDROID_HOME (with an NDK and CMake for the RandomX engine) and a JDK 21 (JAVA_HOME). Output: android/app/build/outputs/apk/debug/app-debug.apk
set -eu
cd "$(dirname "$0")/.."
export VITE_WIKIDECK_NETWORK="${VITE_WIKIDECK_NETWORK:-testnet}"
export VITE_WIKIDECK_GENESIS_TIME="${VITE_WIKIDECK_GENESIS_TIME:-1792411200}"
export VITE_NODE_URL="${VITE_NODE_URL:-http://192.168.1.32:3101}"
# Native RandomX engine (jniLibs/<abi>/libwikideck_randomx.so); built once, reused after (scripts/build-randomx-android.sh).
for abi in ${ABIS:-arm64-v8a x86_64}; do
[ -x "android/app/src/main/jniLibs/$abi/libwikideck_randomx.so" ] || ABIS="$abi" sh scripts/build-randomx-android.sh
done
npm run build
npx cap sync android
cd android && ./gradlew --no-daemon -q assembleDebug
ls -l app/build/outputs/apk/debug/app-debug.apk
+29
View File
@@ -0,0 +1,29 @@
// Top-level build file where you can add configuration options common to all sub-projects/modules.
buildscript {
repositories {
google()
mavenCentral()
}
dependencies {
classpath 'com.android.tools.build:gradle:8.7.2'
classpath 'com.google.gms:google-services:4.4.2'
// NOTE: Do not place your application dependencies here; they belong
// in the individual module build.gradle files
}
}
apply from: "variables.gradle"
allprojects {
repositories {
google()
mavenCentral()
}
}
task clean(type: Delete) {
delete rootProject.buildDir
}
+9
View File
@@ -0,0 +1,9 @@
// DO NOT EDIT THIS FILE! IT IS GENERATED EACH TIME "capacitor update" IS RUN
include ':capacitor-android'
project(':capacitor-android').projectDir = new File('../node_modules/@capacitor/android/capacitor')
include ':capacitor-app'
project(':capacitor-app').projectDir = new File('../node_modules/@capacitor/app/android')
include ':capacitor-browser'
project(':capacitor-browser').projectDir = new File('../node_modules/@capacitor/browser/android')
+22
View File
@@ -0,0 +1,22 @@
# Project-wide Gradle settings.
# IDE (e.g. Android Studio) users:
# Gradle settings configured through the IDE *will override*
# any settings specified in this file.
# For more details on how to configure your build environment visit
# http://www.gradle.org/docs/current/userguide/build_environment.html
# Specifies the JVM arguments used for the daemon process.
# The setting is particularly useful for tweaking memory settings.
org.gradle.jvmargs=-Xmx1536m
# When configured, Gradle will run in incubating parallel mode.
# This option should only be used with decoupled projects. More details, visit
# http://www.gradle.org/docs/current/userguide/multi_project_builds.html#sec:decoupled_projects
# org.gradle.parallel=true
# AndroidX package structure to make it clearer which packages are bundled with the
# Android operating system, and which are packaged with your app's APK
# https://developer.android.com/topic/libraries/support-library/androidx-rn
android.useAndroidX=true
Binary file not shown.
+7
View File
@@ -0,0 +1,7 @@
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-all.zip
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
Vendored Executable
+252
View File
@@ -0,0 +1,252 @@
#!/bin/sh
#
# Copyright © 2015-2021 the original authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# SPDX-License-Identifier: Apache-2.0
#
##############################################################################
#
# Gradle start up script for POSIX generated by Gradle.
#
# Important for running:
#
# (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is
# noncompliant, but you have some other compliant shell such as ksh or
# bash, then to run this script, type that shell name before the whole
# command line, like:
#
# ksh Gradle
#
# Busybox and similar reduced shells will NOT work, because this script
# requires all of these POSIX shell features:
# * functions;
# * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,
# «${var#prefix}», «${var%suffix}», and «$( cmd )»;
# * compound commands having a testable exit status, especially «case»;
# * various built-in commands including «command», «set», and «ulimit».
#
# Important for patching:
#
# (2) This script targets any POSIX shell, so it avoids extensions provided
# by Bash, Ksh, etc; in particular arrays are avoided.
#
# The "traditional" practice of packing multiple parameters into a
# space-separated string is a well documented source of bugs and security
# problems, so this is (mostly) avoided, by progressively accumulating
# options in "$@", and eventually passing that to Java.
#
# Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,
# and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;
# see the in-line comments for details.
#
# There are tweaks for specific operating systems such as AIX, CygWin,
# Darwin, MinGW, and NonStop.
#
# (3) This script is generated from the Groovy template
# https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
# within the Gradle project.
#
# You can find Gradle at https://github.com/gradle/gradle/.
#
##############################################################################
# Attempt to set APP_HOME
# Resolve links: $0 may be a link
app_path=$0
# Need this for daisy-chained symlinks.
while
APP_HOME=${app_path%"${app_path##*/}"} # leaves a trailing /; empty if no leading path
[ -h "$app_path" ]
do
ls=$( ls -ld "$app_path" )
link=${ls#*' -> '}
case $link in #(
/*) app_path=$link ;; #(
*) app_path=$APP_HOME$link ;;
esac
done
# This is normally unused
# shellcheck disable=SC2034
APP_BASE_NAME=${0##*/}
# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s
' "$PWD" ) || exit
# Use the maximum available, or set MAX_FD != -1 to use that value.
MAX_FD=maximum
warn () {
echo "$*"
} >&2
die () {
echo
echo "$*"
echo
exit 1
} >&2
# OS specific support (must be 'true' or 'false').
cygwin=false
msys=false
darwin=false
nonstop=false
case "$( uname )" in #(
CYGWIN* ) cygwin=true ;; #(
Darwin* ) darwin=true ;; #(
MSYS* | MINGW* ) msys=true ;; #(
NONSTOP* ) nonstop=true ;;
esac
CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
# Determine the Java command to use to start the JVM.
if [ -n "$JAVA_HOME" ] ; then
if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
# IBM's JDK on AIX uses strange locations for the executables
JAVACMD=$JAVA_HOME/jre/sh/java
else
JAVACMD=$JAVA_HOME/bin/java
fi
if [ ! -x "$JAVACMD" ] ; then
die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
Please set the JAVA_HOME variable in your environment to match the
location of your Java installation."
fi
else
JAVACMD=java
if ! command -v java >/dev/null 2>&1
then
die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
Please set the JAVA_HOME variable in your environment to match the
location of your Java installation."
fi
fi
# Increase the maximum file descriptors if we can.
if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
case $MAX_FD in #(
max*)
# In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
# shellcheck disable=SC2039,SC3045
MAX_FD=$( ulimit -H -n ) ||
warn "Could not query maximum file descriptor limit"
esac
case $MAX_FD in #(
'' | soft) :;; #(
*)
# In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
# shellcheck disable=SC2039,SC3045
ulimit -n "$MAX_FD" ||
warn "Could not set maximum file descriptor limit to $MAX_FD"
esac
fi
# Collect all arguments for the java command, stacking in reverse order:
# * args from the command line
# * the main class name
# * -classpath
# * -D...appname settings
# * --module-path (only if needed)
# * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.
# For Cygwin or MSYS, switch paths to Windows format before running java
if "$cygwin" || "$msys" ; then
APP_HOME=$( cygpath --path --mixed "$APP_HOME" )
CLASSPATH=$( cygpath --path --mixed "$CLASSPATH" )
JAVACMD=$( cygpath --unix "$JAVACMD" )
# Now convert the arguments - kludge to limit ourselves to /bin/sh
for arg do
if
case $arg in #(
-*) false ;; # don't mess with options #(
/?*) t=${arg#/} t=/${t%%/*} # looks like a POSIX filepath
[ -e "$t" ] ;; #(
*) false ;;
esac
then
arg=$( cygpath --path --ignore --mixed "$arg" )
fi
# Roll the args list around exactly as many times as the number of
# args, so each arg winds up back in the position where it started, but
# possibly modified.
#
# NB: a `for` loop captures its iteration list before it begins, so
# changing the positional parameters here affects neither the number of
# iterations, nor the values presented in `arg`.
shift # remove old arg
set -- "$@" "$arg" # push replacement arg
done
fi
# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
# Collect all arguments for the java command:
# * DEFAULT_JVM_OPTS, JAVA_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,
# and any embedded shellness will be escaped.
# * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be
# treated as '${Hostname}' itself on the command line.
set -- \
"-Dorg.gradle.appname=$APP_BASE_NAME" \
-classpath "$CLASSPATH" \
org.gradle.wrapper.GradleWrapperMain \
"$@"
# Stop when "xargs" is not available.
if ! command -v xargs >/dev/null 2>&1
then
die "xargs is not available"
fi
# Use "xargs" to parse quoted args.
#
# With -n1 it outputs one arg per line, with the quotes and backslashes removed.
#
# In Bash we could simply go:
#
# readarray ARGS < <( xargs -n1 <<<"$var" ) &&
# set -- "${ARGS[@]}" "$@"
#
# but POSIX shell has neither arrays nor command substitution, so instead we
# post-process each arg (as a line of input to sed) to backslash-escape any
# character that might be a shell metacharacter, then use eval to reverse
# that process (while maintaining the separation between arguments), and wrap
# the whole thing up as a single "set" statement.
#
# This will of course break if any of these variables contains a newline or
# an unmatched quote.
#
eval "set -- $(
printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" |
xargs -n1 |
sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' |
tr '\n' ' '
)" '"$@"'
exec "$JAVACMD" "$@"
+94
View File
@@ -0,0 +1,94 @@
@rem
@rem Copyright 2015 the original author or authors.
@rem
@rem Licensed under the Apache License, Version 2.0 (the "License");
@rem you may not use this file except in compliance with the License.
@rem You may obtain a copy of the License at
@rem
@rem https://www.apache.org/licenses/LICENSE-2.0
@rem
@rem Unless required by applicable law or agreed to in writing, software
@rem distributed under the License is distributed on an "AS IS" BASIS,
@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@rem See the License for the specific language governing permissions and
@rem limitations under the License.
@rem
@rem SPDX-License-Identifier: Apache-2.0
@rem
@if "%DEBUG%"=="" @echo off
@rem ##########################################################################
@rem
@rem Gradle startup script for Windows
@rem
@rem ##########################################################################
@rem Set local scope for the variables with windows NT shell
if "%OS%"=="Windows_NT" setlocal
set DIRNAME=%~dp0
if "%DIRNAME%"=="" set DIRNAME=.
@rem This is normally unused
set APP_BASE_NAME=%~n0
set APP_HOME=%DIRNAME%
@rem Resolve any "." and ".." in APP_HOME to make it shorter.
for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m"
@rem Find java.exe
if defined JAVA_HOME goto findJavaFromJavaHome
set JAVA_EXE=java.exe
%JAVA_EXE% -version >NUL 2>&1
if %ERRORLEVEL% equ 0 goto execute
echo. 1>&2
echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
echo. 1>&2
echo Please set the JAVA_HOME variable in your environment to match the 1>&2
echo location of your Java installation. 1>&2
goto fail
:findJavaFromJavaHome
set JAVA_HOME=%JAVA_HOME:"=%
set JAVA_EXE=%JAVA_HOME%/bin/java.exe
if exist "%JAVA_EXE%" goto execute
echo. 1>&2
echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
echo. 1>&2
echo Please set the JAVA_HOME variable in your environment to match the 1>&2
echo location of your Java installation. 1>&2
goto fail
:execute
@rem Setup the command line
set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
@rem Execute Gradle
"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %*
:end
@rem End local scope for the variables with windows NT shell
if %ERRORLEVEL% equ 0 goto mainEnd
:fail
rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
rem the _cmd.exe /c_ return code!
set EXIT_CODE=%ERRORLEVEL%
if %EXIT_CODE% equ 0 set EXIT_CODE=1
if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
exit /b %EXIT_CODE%
:mainEnd
if "%OS%"=="Windows_NT" endlocal
:omega
+5
View File
@@ -0,0 +1,5 @@
include ':app'
include ':capacitor-cordova-android-plugins'
project(':capacitor-cordova-android-plugins').projectDir = new File('./capacitor-cordova-android-plugins/')
apply from: 'capacitor.settings.gradle'
+16
View File
@@ -0,0 +1,16 @@
ext {
minSdkVersion = 23
compileSdkVersion = 35
targetSdkVersion = 35
androidxActivityVersion = '1.9.2'
androidxAppCompatVersion = '1.7.0'
androidxCoordinatorLayoutVersion = '1.2.0'
androidxCoreVersion = '1.15.0'
androidxFragmentVersion = '1.8.4'
coreSplashScreenVersion = '1.0.1'
androidxWebkitVersion = '1.12.1'
junitVersion = '4.13.2'
androidxJunitVersion = '1.2.1'
androidxEspressoCoreVersion = '3.6.1'
cordovaAndroidVersion = '10.1.1'
}
+26
View File
@@ -0,0 +1,26 @@
import type { CapacitorConfig } from '@capacitor/cli';
// WikiDeck mobile shell. Build the web UI with the node URL baked in, then sync:
// VITE_WIKIDECK_NETWORK=testnet VITE_WIKIDECK_GENESIS_TIME=1792411200 \
// VITE_NODE_URL=http://192.168.1.32:3101 npm run build && npx cap sync android
// (see android/build-debug.sh)
const config: CapacitorConfig = {
appId: 'dev.eom.wikideck',
appName: 'WikiDeck',
webDir: 'dist',
server: {
androidScheme: 'https',
// The private testnet node is plain HTTP on the LAN.
cleartext: true,
},
android: {
// Android 15 (targetSdk 35) draws edge-to-edge; keep the WebView clear of the system bars.
adjustMarginsForEdgeToEdge: 'auto',
},
plugins: {
// Route fetch through native HTTP: avoids CORS and the node's browser Origin check.
CapacitorHttp: { enabled: true },
},
};
export default config;
-48
View File
@@ -1,48 +0,0 @@
# Explicit local sandbox backup helper. Start the persistent stack first, then stop only wikideck.
# Requires WIKIDECK_BACKUP_DIR (existing restricted host directory) and WIKIDECK_BACKUP_NAME (new leaf name).
# For verification, override the service command with: verify --source /backups/<name>.
services:
backup:
image: wikideck:custody-backup
build:
context: .
dockerfile: Dockerfile
target: custody-backup
environment:
WIKIDECK_NETWORK: testnet
WIKIDECK_CUSTODY_STORAGE: postgres
WIKIDECK_CUSTODY_PG_URL_FILE: /secrets/runtime/url
WIKIDECK_CUSTODY_PG_BACKUP_URL_FILE: /secrets/backup/url
WIKIDECK_CUSTODY_PG_CA_FILE: /secrets/backup/ca.crt
command: ["create", "--source", "/app/data", "--destination", "/backups/${WIKIDECK_BACKUP_NAME:?Set a new backup leaf name}", "--consent"]
volumes:
- custody-node:/app/data
- pg-runtime:/secrets/runtime:ro
- pg-backup:/secrets/backup:ro
- type: bind
source: ${WIKIDECK_BACKUP_DIR:?Set an existing restricted host backup directory}
target: /backups
bind:
create_host_path: false
networks: [financial]
read_only: true
tmpfs: ["/tmp:mode=1777,size=32m,noexec,nosuid"]
cap_drop: [ALL]
security_opt: [no-new-privileges:true]
pids_limit: 32
mem_limit: 512m
restart: "no"
networks:
financial:
external: true
name: wikideck-custody-local_financial
volumes:
custody-node:
external: true
name: wikideck-custody-local_custody-node
pg-runtime:
external: true
name: wikideck-custody-local_pg-runtime
pg-backup:
external: true
name: wikideck-custody-local_pg-backup
-209
View File
@@ -1,209 +0,0 @@
# Private mock-only pilot profile. Start with a distinct Compose project name;
# this stack intentionally contains no Monero daemon, Wallet-RPC, or observer.
services:
provision:
image: wikideck:pilot-provision
build:
context: .
dockerfile: deploy/postgres/Dockerfile
volumes:
- pg-admin:/secrets/admin
- pg-owner:/secrets/owner
- pg-runtime:/secrets/runtime
- pg-backup:/secrets/backup
- pg-tls:/secrets/tls
network_mode: none
read_only: true
tmpfs: ["/tmp:mode=1777,size=16m"]
restart: "no"
database:
image: wikideck:postgres-pilot
build:
context: .
dockerfile: deploy/postgres/database.Dockerfile
depends_on:
provision:
condition: service_completed_successfully
environment:
POSTGRES_DB: wikideck_custody
POSTGRES_USER: postgres
POSTGRES_PASSWORD_FILE: /secrets/admin/password
POSTGRES_INITDB_ARGS: --auth-host=scram-sha-256
command: [postgres, -c, ssl=on, -c, ssl_min_protocol_version=TLSv1.2,
-c, ssl_cert_file=/tls/server.crt, -c, ssl_key_file=/tls/server.key,
-c, hba_file=/etc/wikideck/pg_hba.conf, -c, log_statement=none,
-c, log_min_error_statement=panic, -c, log_parameter_max_length_on_error=0]
volumes:
- pg-data:/var/lib/postgresql/data
- pg-admin:/secrets/admin:ro
- pg-tls:/tls:ro
networks: [financial]
healthcheck:
test: [CMD-SHELL, "pg_isready -U postgres -d wikideck_custody"]
interval: 3s
timeout: 3s
retries: 30
restart: unless-stopped
shm_size: 128m
stop_grace_period: 30s
migrate:
image: wikideck:private-pilot
build:
context: .
target: runtime
args:
WIKIDECK_NETWORK: pilot
depends_on:
database:
condition: service_healthy
environment:
WIKIDECK_NETWORK: pilot
WIKIDECK_LOCAL_PG_BOOTSTRAP: sandbox-only
command: [node, --experimental-strip-types, scripts/custody-deployment-init.ts]
volumes:
- pg-admin:/secrets/admin:ro
- pg-owner:/secrets/owner:ro
- pg-runtime:/secrets/runtime:ro
- pg-backup:/secrets/backup:ro
networks: [financial]
read_only: true
cap_drop: [ALL]
security_opt: [no-new-privileges:true]
restart: "no"
wikideck:
image: wikideck:private-pilot
build:
context: .
target: runtime
args:
WIKIDECK_NETWORK: pilot
depends_on:
migrate:
condition: service_completed_successfully
ports: ["127.0.0.1:${WIKIDECK_PILOT_PORT:-3423}:3001"]
environment:
WIKIDECK_NETWORK: pilot
WIKIDECK_PILOT_MODE: private-mock-only
WIKIDECK_PAYMENT_MODE: mock
WIKIDECK_MARKET_ENABLED: "${WIKIDECK_MARKET_ENABLED:-1}"
WIKIDECK_MARKET_TRADING_ENABLED: "${WIKIDECK_MARKET_TRADING_ENABLED:-1}"
WIKIDECK_MARKET_HOST_FEE_ADDRESS: "${WIKIDECK_MARKET_HOST_FEE_ADDRESS:-44xHcCdFhW4b951yBHpkTPdLSJ85qTCnFQ8N7m96TtqqRL3dbhzbEH4fe2SJ3a6ESHcNyzCYH5nYJ9ActR1JtkeA7QYGbQv}"
WIKIDECK_CUSTODY_MODE: sandbox
WIKIDECK_CUSTODY_STORAGE: postgres
WIKIDECK_CUSTODY_PG_URL_FILE: /secrets/runtime/url
WIKIDECK_CUSTODY_PG_CA_FILE: /secrets/runtime/ca.crt
PUBLIC_ORIGIN: "http://127.0.0.1:${WIKIDECK_PILOT_PORT:-3423}"
volumes:
- custody-node:/app/data
- pg-runtime:/secrets/runtime:ro
networks: [financial, web]
init: true
restart: unless-stopped
read_only: true
tmpfs: ["/tmp:mode=1777,size=32m,noexec,nosuid"]
cap_drop: [ALL]
security_opt: [no-new-privileges:true]
pids_limit: 128
mem_limit: 1g
stop_grace_period: 30s
daemon-check:
image: wikideck:private-pilot
profiles: ["monero-check"]
build:
context: .
target: runtime
args:
WIKIDECK_NETWORK: pilot
entrypoint: [node, --experimental-strip-types, scripts/monero-daemon-check.ts]
environment:
WIKIDECK_MONERO_DAEMON_CONFIG_FILE: /run/monero/daemon.json
volumes:
- type: bind
source: "${WIKIDECK_MONERO_DAEMON_CONFIG_HOST:-./private/monero-daemon.json}"
target: /run/monero/daemon.json
read_only: true
networks: [web]
read_only: true
cap_drop: [ALL]
security_opt: [no-new-privileges:true]
pids_limit: 32
mem_limit: 128m
restart: "no"
pilot-observer:
image: wikideck:private-pilot
profiles: ["pilot-observer"]
build:
context: .
target: runtime
args:
WIKIDECK_NETWORK: pilot
entrypoint: [node, --experimental-strip-types, scripts/pilot-monero-observe-once.ts]
environment:
WIKIDECK_NETWORK: pilot
WIKIDECK_PILOT_MODE: private-mock-only
WIKIDECK_PILOT_CUSTODY_OPERATIONS: pilot-observation-only-no-credit
WIKIDECK_PILOT_CUSTODIAN_ID: "${WIKIDECK_PILOT_CUSTODIAN_ID:-}"
WIKIDECK_MONERO_WALLET_GENERATION_ID: "${WIKIDECK_MONERO_WALLET_GENERATION_ID:-}"
WIKIDECK_MONERO_WALLET_FINGERPRINT: "${WIKIDECK_MONERO_WALLET_FINGERPRINT:-}"
WIKIDECK_PILOT_OBSERVER_PG_URL_FILE: /run/secrets/pilot-observer-db-url
WIKIDECK_PILOT_OBSERVER_PG_CA_FILE: /run/secrets/pilot-observer-db-ca.crt
WIKIDECK_MONERO_WALLET_RPC_CONFIG_FILE: /run/monero/wallet-rpc.json
WIKIDECK_MONERO_MTLS_CONFIG_FILE: /run/monero/mtls.json
WIKIDECK_PILOT_OBSERVER_MAX_BLOCKS: "${WIKIDECK_PILOT_OBSERVER_MAX_BLOCKS:-5000}"
WIKIDECK_PILOT_OBSERVER_OVERLAP: "${WIKIDECK_PILOT_OBSERVER_OVERLAP:-100}"
volumes:
- type: bind
source: "${WIKIDECK_PILOT_OBSERVER_PG_URL_HOST:-./private/monero-pilot/observer-db-url}"
target: /run/secrets/pilot-observer-db-url
read_only: true
bind: {create_host_path: false}
- type: bind
source: "${WIKIDECK_PILOT_OBSERVER_PG_CA_HOST:-./private/monero-pilot/observer-db-ca.crt}"
target: /run/secrets/pilot-observer-db-ca.crt
read_only: true
bind: {create_host_path: false}
- type: bind
source: "${WIKIDECK_PILOT_OBSERVER_WALLET_CONFIG_HOST:-./private/monero-pilot/wallet-rpc.json}"
target: /run/monero/wallet-rpc.json
read_only: true
bind: {create_host_path: false}
- type: bind
source: "${WIKIDECK_PILOT_OBSERVER_MTLS_CONFIG_HOST:-./private/monero-pilot/mtls.json}"
target: /run/monero/mtls.json
read_only: true
bind: {create_host_path: false}
- type: bind
source: "${WIKIDECK_PILOT_OBSERVER_CLIENT_CERT_HOST:-./private/monero-pilot/observer-client.crt}"
target: /run/secrets/observer-client.crt
read_only: true
bind: {create_host_path: false}
- type: bind
source: "${WIKIDECK_PILOT_OBSERVER_CLIENT_KEY_HOST:-./private/monero-pilot/observer-client.key}"
target: /run/secrets/observer-client.key
read_only: true
bind: {create_host_path: false}
- type: bind
source: "${WIKIDECK_PILOT_OBSERVER_GATEWAY_CA_HOST:-./private/monero-pilot/gateway-ca.crt}"
target: /run/secrets/observer-gateway-ca.crt
read_only: true
bind: {create_host_path: false}
networks: [observer-egress]
read_only: true
tmpfs: ["/tmp:mode=1777,size=16m,noexec,nosuid"]
cap_drop: [ALL]
security_opt: [no-new-privileges:true]
pids_limit: 32
mem_limit: 256m
restart: "no"
networks:
financial: {internal: true}
web: {}
observer-egress: {}
volumes:
pg-data:
pg-admin:
pg-owner:
pg-runtime:
pg-backup:
pg-tls:
custody-node:
-109
View File
@@ -1,109 +0,0 @@
# Persistent LOCAL testnet sandbox. Separate stack/data from existing single/three-node compose files.
# Invoke this file explicitly. Never combine it with the disposable PostgreSQL test fixture.
services:
provision:
build:
context: .
dockerfile: deploy/postgres/Dockerfile
volumes:
- pg-admin:/secrets/admin
- pg-owner:/secrets/owner
- pg-runtime:/secrets/runtime
- pg-backup:/secrets/backup
- pg-tls:/secrets/tls
network_mode: none
read_only: true
tmpfs: ["/tmp:mode=1777,size=16m"]
restart: "no"
database:
image: wikideck:postgres-sandbox
build:
context: .
dockerfile: deploy/postgres/database.Dockerfile
depends_on:
provision:
condition: service_completed_successfully
environment:
POSTGRES_DB: wikideck_custody
POSTGRES_USER: postgres
POSTGRES_PASSWORD_FILE: /secrets/admin/password
POSTGRES_INITDB_ARGS: --auth-host=scram-sha-256
command: [postgres, -c, ssl=on, -c, ssl_min_protocol_version=TLSv1.2,
-c, ssl_cert_file=/tls/server.crt, -c, ssl_key_file=/tls/server.key,
-c, hba_file=/etc/wikideck/pg_hba.conf, -c, log_statement=none,
-c, log_min_error_statement=panic, -c, log_parameter_max_length_on_error=0]
volumes:
- pg-data:/var/lib/postgresql/data
- pg-admin:/secrets/admin:ro
- pg-tls:/tls:ro
networks: [financial]
healthcheck:
test: [CMD-SHELL, "pg_isready -U postgres -d wikideck_custody"]
interval: 3s
timeout: 3s
retries: 30
restart: unless-stopped
shm_size: 128m
stop_grace_period: 30s
migrate:
image: wikideck:custody-sandbox
build: {context: ., target: runtime}
depends_on:
database:
condition: service_healthy
environment:
WIKIDECK_NETWORK: testnet
WIKIDECK_LOCAL_PG_BOOTSTRAP: sandbox-only
command: [node, --experimental-strip-types, scripts/custody-deployment-init.ts]
volumes:
- pg-admin:/secrets/admin:ro
- pg-owner:/secrets/owner:ro
- pg-runtime:/secrets/runtime:ro
- pg-backup:/secrets/backup:ro
networks: [financial]
read_only: true
cap_drop: [ALL]
security_opt: [no-new-privileges:true]
restart: "no"
wikideck:
image: wikideck:custody-sandbox
build: {context: ., target: runtime}
depends_on:
migrate:
condition: service_completed_successfully
ports: ["127.0.0.1:${WIKIDECK_CUSTODY_PORT:-3422}:3001"]
environment:
WIKIDECK_NETWORK: testnet
WIKIDECK_PAYMENT_MODE: mock
WIKIDECK_MARKET_ENABLED: "${WIKIDECK_MARKET_ENABLED:-1}"
WIKIDECK_MARKET_TRADING_ENABLED: "${WIKIDECK_MARKET_TRADING_ENABLED:-1}"
WIKIDECK_MARKET_HOST_FEE_ADDRESS: "${WIKIDECK_MARKET_HOST_FEE_ADDRESS:-44xHcCdFhW4b951yBHpkTPdLSJ85qTCnFQ8N7m96TtqqRL3dbhzbEH4fe2SJ3a6ESHcNyzCYH5nYJ9ActR1JtkeA7QYGbQv}"
WIKIDECK_CUSTODY_MODE: sandbox
WIKIDECK_CUSTODY_STORAGE: postgres
WIKIDECK_CUSTODY_PG_URL_FILE: /secrets/runtime/url
WIKIDECK_CUSTODY_PG_CA_FILE: /secrets/runtime/ca.crt
PUBLIC_ORIGIN: "http://127.0.0.1:${WIKIDECK_CUSTODY_PORT:-3422}"
volumes:
- custody-node:/app/data
- pg-runtime:/secrets/runtime:ro
networks: [financial, web]
init: true
restart: unless-stopped
read_only: true
tmpfs: ["/tmp:mode=1777,size=32m,noexec,nosuid"]
cap_drop: [ALL]
security_opt: [no-new-privileges:true]
pids_limit: 128
mem_limit: 1g
stop_grace_period: 30s
networks:
financial: {internal: true}
web: {}
volumes:
pg-data:
pg-admin:
pg-owner:
pg-runtime:
pg-backup:
pg-tls:
custody-node:
+4 -9
View File
@@ -1,31 +1,26 @@
# Gated candidate profile, NOT an announcement of a production-ready or launched network.
# Keep payments mocked. Review docs/mainnet-launch.md before attempting activation.
# Review docs/mainnet-launch.md before attempting activation.
services:
mainnet:
profiles: [mainnet]
build:
context: .
target: runtime
args:
WIKIDECK_NETWORK: mainnet
WIKIDECK_GENESIS_TIME: "${WIKIDECK_GENESIS_TIME:-1793491200}"
ports:
- "127.0.0.1:${WIKIDECK_MAINNET_PORT:-3201}:3001"
environment:
WIKIDECK_NETWORK: mainnet
WIKIDECK_PAYMENT_MODE: mock
WIKIDECK_MARKET_ENABLED: "${WIKIDECK_MARKET_ENABLED:-1}"
WIKIDECK_MARKET_TRADING_ENABLED: "${WIKIDECK_MARKET_TRADING_ENABLED:-1}"
WIKIDECK_MARKET_HOST_FEE_ADDRESS: "${WIKIDECK_MARKET_HOST_FEE_ADDRESS:-44xHcCdFhW4b951yBHpkTPdLSJ85qTCnFQ8N7m96TtqqRL3dbhzbEH4fe2SJ3a6ESHcNyzCYH5nYJ9ActR1JtkeA7QYGbQv}"
WIKIDECK_GENESIS_TIME: "${WIKIDECK_GENESIS_TIME:-1793491200}"
PUBLIC_ORIGIN: "${WIKIDECK_MAINNET_ORIGIN:-}"
WIKIDECK_PEERS: "${WIKIDECK_MAINNET_PEERS:-}"
WIKIDECK_MAINNET_LAUNCH: "${WIKIDECK_MAINNET_LAUNCH:-}"
WIKIDECK_MAINNET_REVIEW_ACK: "${WIKIDECK_MAINNET_REVIEW_ACK:-}"
WIKIDECK_MAINNET_RISK_ACK: "${WIKIDECK_MAINNET_RISK_ACK:-}"
WIKIDECK_ALLOW_PRIVATE_PEERS: "0"
# Empty by default; set only the actual edge-to-container source IP/CIDR after topology review.
WIKIDECK_TRUSTED_PROXIES: "${WIKIDECK_TRUSTED_PROXIES:-}"
# Diagnostics are deliberately disabled here. Never publish an operations port.
WIKIDECK_MARKET_FEE_BPS: "${WIKIDECK_MARKET_FEE_BPS:-250}"
WIKIDECK_MARKET_CONFIRMATIONS: "${WIKIDECK_MARKET_CONFIRMATIONS:-10}"
volumes:
- mainnet-candidate-data:/app/data
init: true
-30
View File
@@ -1,30 +0,0 @@
# Disposable isolated integration fixture ONLY. No persistent/host database ports or credentials.
# Trust auth is confined to this temporary internal network and is never a deployment example.
services:
database:
image: postgres:17-alpine
environment:
POSTGRES_DB: custody_test
POSTGRES_HOST_AUTH_METHOD: trust
tmpfs:
- /var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres -d custody_test"]
interval: 1s
timeout: 3s
retries: 30
networks: [fixture]
tests:
image: wikideck-custody-test
network_mode: service:database
depends_on:
database:
condition: service_healthy
environment:
WIKIDECK_PG_DISPOSABLE_TEST: "1"
WIKIDECK_CUSTODY_CANONICAL_REHEARSAL: "1"
NODE_ENV: test
command: ["npx", "tsx", "--test", "--test-concurrency=1", "tests/postgres/*.test.ts"]
networks:
fixture:
internal: true
+16 -13
View File
@@ -1,19 +1,16 @@
# Three independent validators, separate volumes, no miner auto-starts.
x-market-environment: &market-environment
x-node-environment: &node-environment
WIKIDECK_NETWORK: testnet
WIKIDECK_PAYMENT_MODE: mock
WIKIDECK_MARKET_ENABLED: "${WIKIDECK_MARKET_ENABLED:-1}"
WIKIDECK_MARKET_TRADING_ENABLED: "${WIKIDECK_MARKET_TRADING_ENABLED:-1}"
WIKIDECK_MARKET_HOST_FEE_ADDRESS: "${WIKIDECK_MARKET_HOST_FEE_ADDRESS:-44xHcCdFhW4b951yBHpkTPdLSJ85qTCnFQ8N7m96TtqqRL3dbhzbEH4fe2SJ3a6ESHcNyzCYH5nYJ9ActR1JtkeA7QYGbQv}"
WIKIDECK_MARKET_FEE_BPS: "${WIKIDECK_MARKET_FEE_BPS:-250}"
WIKIDECK_MARKET_CONFIRMATIONS: "${WIKIDECK_MARKET_CONFIRMATIONS:-10}"
services:
node-a:
image: wikideck:testnet
build: { context: ., target: runtime }
build:
context: .
target: runtime
args: { WIKIDECK_NETWORK: testnet, WIKIDECK_GENESIS_TIME: "1792411200" }
ports: ["127.0.0.1:3101:3001"]
environment:
<<: *market-environment
<<: *node-environment
PUBLIC_ORIGIN: http://127.0.0.1:3101
WIKIDECK_PEERS: http://node-b:3001,http://node-c:3001
WIKIDECK_ALLOW_PRIVATE_PEERS: "1"
@@ -29,10 +26,13 @@ services:
stop_grace_period: 30s
node-b:
image: wikideck:testnet
build: { context: ., target: runtime }
build:
context: .
target: runtime
args: { WIKIDECK_NETWORK: testnet, WIKIDECK_GENESIS_TIME: "1792411200" }
ports: ["127.0.0.1:3102:3001"]
environment:
<<: *market-environment
<<: *node-environment
PUBLIC_ORIGIN: http://127.0.0.1:3102
WIKIDECK_PEERS: http://node-a:3001,http://node-c:3001
WIKIDECK_ALLOW_PRIVATE_PEERS: "1"
@@ -48,10 +48,13 @@ services:
stop_grace_period: 30s
node-c:
image: wikideck:testnet
build: { context: ., target: runtime }
build:
context: .
target: runtime
args: { WIKIDECK_NETWORK: testnet, WIKIDECK_GENESIS_TIME: "1792411200" }
ports: ["127.0.0.1:3103:3001"]
environment:
<<: *market-environment
<<: *node-environment
PUBLIC_ORIGIN: http://127.0.0.1:3103
WIKIDECK_PEERS: http://node-a:3001,http://node-b:3001
WIKIDECK_ALLOW_PRIVATE_PEERS: "1"
+16 -15
View File
@@ -3,24 +3,25 @@ services:
build:
context: .
target: runtime
args:
WIKIDECK_NETWORK: mainnet
WIKIDECK_GENESIS_TIME: "${WIKIDECK_GENESIS_TIME:-1793491200}"
ports:
# Keep the prototype private; listen on all interfaces only inside the container.
- "127.0.0.1:${WIKIDECK_PORT:-3001}:3001"
# Loopback only; terminate reviewed HTTPS at the operator's edge.
- "127.0.0.1:${WIKIDECK_MAINNET_PORT:-3201}:3001"
environment:
WIKIDECK_NETWORK: testnet
PUBLIC_ORIGIN: "${PUBLIC_ORIGIN:-http://127.0.0.1:${WIKIDECK_PORT:-3001}}"
WIKIDECK_PEERS: "${WIKIDECK_PEERS:-}"
WIKIDECK_ALLOW_PRIVATE_PEERS: "${WIKIDECK_ALLOW_PRIVATE_PEERS:-0}"
WIKIDECK_PAYMENT_MODE: mock
WIKIDECK_MARKET_ENABLED: "${WIKIDECK_MARKET_ENABLED:-1}"
WIKIDECK_MARKET_TRADING_ENABLED: "${WIKIDECK_MARKET_TRADING_ENABLED:-1}"
WIKIDECK_MARKET_HOST_FEE_ADDRESS: "${WIKIDECK_MARKET_HOST_FEE_ADDRESS:-44xHcCdFhW4b951yBHpkTPdLSJ85qTCnFQ8N7m96TtqqRL3dbhzbEH4fe2SJ3a6ESHcNyzCYH5nYJ9ActR1JtkeA7QYGbQv}"
WIKIDECK_MARKET_FEE_BPS: "${WIKIDECK_MARKET_FEE_BPS:-250}"
WIKIDECK_MARKET_CONFIRMATIONS: "${WIKIDECK_MARKET_CONFIRMATIONS:-10}"
WIKIDECK_NETWORK: mainnet
WIKIDECK_GENESIS_TIME: "${WIKIDECK_GENESIS_TIME:-1793491200}"
PUBLIC_ORIGIN: "${WIKIDECK_MAINNET_ORIGIN:-}"
WIKIDECK_PEERS: "${WIKIDECK_MAINNET_PEERS:-}"
WIKIDECK_MAINNET_LAUNCH: "${WIKIDECK_MAINNET_LAUNCH:-}"
WIKIDECK_MAINNET_RISK_ACK: "${WIKIDECK_MAINNET_RISK_ACK:-}"
WIKIDECK_ALLOW_PRIVATE_PEERS: "0"
WIKIDECK_TRUSTED_PROXIES: "${WIKIDECK_TRUSTED_PROXIES:-}"
volumes:
- wikideck-data:/app/data
- wikideck-mainnet-data:/app/data
init: true
restart: unless-stopped
restart: "no"
read_only: true
tmpfs:
- /tmp:size=32m,mode=1777,noexec,nosuid
@@ -34,4 +35,4 @@ services:
stop_grace_period: 30s
volumes:
wikideck-data:
wikideck-mainnet-data:
+45
View File
@@ -0,0 +1,45 @@
# Kubernetes mainnet preparation
This directory intentionally contains no apply-ready manifests yet. The code is mainnet-first and supports a genesis frozen into the browser bundle and runtime image, but the current launch gate requires deployment facts that were not supplied. Placeholder origins, approval IDs, TLS secrets, or storage settings would not produce a working or safe deployment.
## Required topology for this implementation
- Build and publish one immutable image with `WIKIDECK_NETWORK=mainnet` and one chosen `WIKIDECK_GENESIS_TIME`. Give every peer and browser bundle that same chain identity. A runtime-only genesis override is rejected by the image manifest check.
- Give each node a stable, unique public HTTPS origin. TLS must terminate at an operator-managed ingress/reverse proxy; the application listener itself is HTTP on port 3001.
- Configure at least two other distinct public HTTPS peer origins per node for public peering. Private IPs/DNS and HTTP are rejected by default. An operator-controlled private candidate cluster may explicitly set `WIKIDECK_ALLOW_PRIVATE_PEERS=1` and use distinct per-node ClusterIP DNS origins. This opt-in does not change the exact chain-ID/risk/genesis gates or the HTTPS browser-origin requirement.
- Route each public peer hostname deterministically to exactly one node. A shared load-balanced hostname is not a stable peer identity. Separate per-peer Deployments/Services/Ingress routes are the simplest current shape; each node must exclude its own origin from its peer list.
- Give every node an exclusive persistent volume mounted at `/app/data`. Never share a ledger volume between pods. Agree the storage class, capacity, backup/restore procedure, resource limits, failure domains, and upgrade/reorg policy before enabling the launch approval.
- Configure the exact manifest `CHAIN_ID` as `WIKIDECK_MAINNET_LAUNCH`, and explicitly set `WIKIDECK_MAINNET_RISK_ACK=operator-accepts-unaudited-risk`. The latter accepts unaudited residual risk; it is not an audit or readiness check.
## Pod hardening baseline
Use a dedicated namespace and least-privilege service account (or disable token automount if no Kubernetes API access is needed), non-root execution matching the image's `node` user, read-only root filesystem, dropped Linux capabilities, `allowPrivilegeEscalation: false`, `seccompProfile: RuntimeDefault`, and a bounded writable `/tmp` volume. Use resource requests and limits based on measured RandomX/replay/sync behavior, not guesses. Readiness/liveness should use `/healthz`; allow a startup grace period for ledger replay and native engine initialization. Restrict ingress to the reviewed edge and egress to DNS, the configured public peers, and required Wikimedia endpoints. Add NetworkPolicy, TLS, image provenance/signature enforcement, monitoring, and tested encrypted backups through the cluster's established platform controls.
Do not make the public origin or configured peers imply that peers are independent or that the network is secure. This software has no external audit, public bootstrap service, peer discovery, or demonstrated production capacity.
## Private candidate cluster
Deploy the public node and two internal peers as three separate single-replica
role instances, each with its own Service and PVC. Configure each peer list with
the other two Services, for example `http://wikideck-peer-a.wikideck.svc.cluster.local:80`.
Allow same-namespace validator pods on target TCP 3001 through both ingress and
egress NetworkPolicy; Service port 80 is translated to that target port. Only the
public node needs ingress; all nodes may use the public node's HTTPS browser
origin. Keep API credentials and wallet keys out of validator pods.
Read `--network-manifest` from the exact published image to obtain the candidate
chain ID without opening storage or starting a listener. Its
`privatePeersSupported: true` capability distinguishes updated images from older
images that reject this topology. Do not override genesis at runtime. The default
image genesis is now fixed at November 1, 2026, 00:00 UTC (`1793491200`), so no
January wait or custom build argument is needed. Rebuild and publish the updated
image; an older published image still contains its previous genesis. Existing
ledgers and wallets must retain their original chain identity.
Private peer RPC is unauthenticated and, with HTTP, unencrypted. Use a trusted
cluster boundary and scoped policies; add mesh transport protection if needed.
This topology does not demonstrate independent peers/miners or production readiness.
## Values needed before manifests can be finalized
Choose the genesis timestamp and image registry/digest; provide the namespace, ingress class and TLS/certificate mechanism, public DNS name per node, peer topology, storage class/size, resource budget, network-policy egress model, backup destination/retention, and desired availability/recovery behavior. Then calculate and publish the exact manifest and chain approval. Until those values and the peer topology are available, this checklist is the safe preparation artifact rather than a misleading runnable YAML template.
+22
View File
@@ -0,0 +1,22 @@
# Night 1 private testnet (sim-testnet)
A 3-node **testnet-only** fixture on poweredge-r350. It is reachable on the LAN only, and uses the Docker project `wikideck-night`.
| node | URL |
|---|---|
| node-a | http://192.168.1.32:3101 |
| node-b | http://192.168.1.32:3102 |
| node-c | http://192.168.1.32:3103 |
- `compose.lan.yaml` overrides only the published ports (bound to `192.168.1.32`, never `0.0.0.0`) and `PUBLIC_ORIGIN`. It changes nothing in consensus or the image.
- `mine.ts` is a multi-worker native RandomX miner. It runs inside the `wikideck:testnet` image, which ships the native engine, so the host needs no cmake.
- It mines to 4 disposable wallets (alice, bob, carol, dave) and writes chain-bound encrypted browser backups to `$STATE_DIR/wallets/`.
- It never changes consensus code. Speed comes from the protocol's own testnet parameters: the initial target accepts 1/16 of hashes, and each 10-block retarget at most quadruples the difficulty.
- Each template costs several Wikipedia API calls, and Wikipedia rate-limits our egress IP. The miner therefore paces templates (`MIN_GAP`, default 45 s) and backs off exponentially on failure.
- `compose.lan.yaml` also sets, per node:
- `WIKIDECK_USER_AGENT`, a Wikimedia-policy UA with a project URL (#19). Without it, Wikipedia returned 429 to our egress and templates failed.
- the game-mode env from #22: A = classic and trending, B = draft, C = all three.
- `autodeploy.sh` follows the integration branch. Run it from a dedicated detached worktree: `git worktree add --detach ../deploy-src origin/night/2026-11-17 && cd ../deploy-src && deploy/night/autodeploy.sh`. It polls the Gitea API every 3 min and redeploys whenever the head moves.
- `testnet.sh` has `up`, `mine N [workers]`, `status` and `down`. Run it from the repo root on a checkout of the integration branch. `up` rebuilds the image from that checkout; the ledgers persist in the named volumes.
Never point this at mainnet or the live `wikideck` namespace.
+40
View File
@@ -0,0 +1,40 @@
#!/bin/sh
# sim-testnet: keep the wikideck-night testnet on the integration branch head.
# Run from the root of a *dedicated* checkout (e.g. a detached git worktree): it checks out
# each new head of $BRANCH and runs `deploy/night/testnet.sh rolling` (ledgers persist in the volumes):
# nodes restart one at a time, and deploys wait (up to FORCE_AFTER) while matches or lobbies are live,
# because lobbies are in memory and a restart ends games in progress.
# Head detection uses the public Gitea API, which also works where SSH auth isn't available.
set -u
BRANCH=${BRANCH:-night/2026-11-17}
API=${API:-https://gitea.eom.dev/api/v1/repos/claude/wikideck}
INTERVAL=${INTERVAL:-180}
LOG=${LOG:-/tmp/wikideck-night-autodeploy.log}
FORCE_AFTER=${FORCE_AFTER:-900} # defer while matches/lobbies are live, but at most this many seconds
deferred_since=
enc=$(printf %s "$BRANCH" | sed 's#/#%2F#g')
while :; do
new=$(node -e "fetch('$API/branches/$enc',{signal:AbortSignal.timeout(15000)}).then(r=>r.json()).then(b=>console.log(b.commit.id)).catch(()=>{})")
cur=$(git rev-parse HEAD)
if [ -z "$new" ]; then echo "WARN branch API failed"
elif [ "$new" != "$cur" ]; then
if ! git fetch -q origin "+refs/heads/$BRANCH:refs/remotes/origin/$BRANCH" 2>"$LOG"; then
echo "WARN fetch failed: $(tail -1 "$LOG")"
else
busy=$(deploy/night/testnet.sh busy 2>/dev/null || echo 0)
now=$(date +%s)
if [ "${busy:-0}" -gt 0 ] && { [ -z "$deferred_since" ] || [ $((now - deferred_since)) -lt "$FORCE_AFTER" ]; }; then
[ -z "$deferred_since" ] && { deferred_since=$now; echo "DEFER ${new%"${new#???????}"}: $busy live matches/lobbies"; }
sleep 60; continue
fi
[ -n "$deferred_since" ] && [ "${busy:-0}" -gt 0 ] && echo "FORCE deploy after ${FORCE_AFTER}s ($busy still live)"
deferred_since=
git checkout -q --detach "$new"
echo "DEPLOY start $(git log --oneline -1 | cut -c1-90)"
if deploy/night/testnet.sh rolling >"$LOG" 2>&1; then
sleep 20; echo "DEPLOY ok $(git rev-parse --short HEAD): $(deploy/night/testnet.sh status 2>&1 | tr '\n' ' ')"
else echo "DEPLOY FAILED $(git rev-parse --short HEAD): $(tail -3 "$LOG" | tr '\n' ' ')"; fi
fi
fi
sleep "$INTERVAL"
done
+36
View File
@@ -0,0 +1,36 @@
# sim-testnet override: publish the fixture on r350's LAN address only (not 0.0.0.0).
# WIKIDECK_USER_AGENT identifies the testnet to Wikimedia (UA policy; no personal contact info).
# Game-mode env (modes team, #6) is inert until night/modes/hosting merges.
# WIKIDECK_WIKIMEDIA_NODES_PER_IP / WIKIDECK_OPERATOR_CONTACT (#62): the 3 nodes share one egress IP, so the
# polite client splits its rate and daily cap 3 ways. Inert until the wikimedia client merges.
services:
node-a:
ports: !override ["192.168.1.32:3101:3001"]
environment:
PUBLIC_ORIGIN: http://192.168.1.32:3101
WIKIDECK_USER_AGENT: &ua WikiDeck-testnet/0.1 (https://gitea.eom.dev/claude/wikideck; private testnet)
WIKIDECK_WIKIMEDIA_NODES_PER_IP: &perip "3"
WIKIDECK_OPERATOR_CONTACT: &contact https://gitea.eom.dev/claude/wikideck
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:
ports: !override ["192.168.1.32:3102:3001"]
environment:
PUBLIC_ORIGIN: http://192.168.1.32:3102
WIKIDECK_USER_AGENT: *ua
WIKIDECK_WIKIMEDIA_NODES_PER_IP: *perip
WIKIDECK_OPERATOR_CONTACT: *contact
WIKIDECK_MODES: draft
WIKIDECK_GAME_OPERATOR: Testnet B
WIKIDECK_GAME_PEERS: http://192.168.1.32:3101,http://192.168.1.32:3103
node-c:
ports: !override ["192.168.1.32:3103:3001"]
environment:
PUBLIC_ORIGIN: http://192.168.1.32:3103
WIKIDECK_USER_AGENT: *ua
WIKIDECK_WIKIMEDIA_NODES_PER_IP: *perip
WIKIDECK_OPERATOR_CONTACT: *contact
WIKIDECK_MODES: classic,trending,draft
WIKIDECK_GAME_OPERATOR: Testnet C
WIKIDECK_GAME_PEERS: http://192.168.1.32:3101,http://192.168.1.32:3102
+100
View File
@@ -0,0 +1,100 @@
// sim-testnet: multi-worker native RandomX miner for the PRIVATE wikideck-night testnet.
// Runs inside the wikideck:testnet image (which ships the native engine). Testnet only.
// Usage: node --experimental-strip-types /night/mine.ts <blocks> <workers>
import { mkdirSync, readFileSync, writeFileSync, existsSync, appendFileSync } from 'node:fs';
import { randomInt, webcrypto } from 'node:crypto';
import { RandomX } from '/app/server/testnet/randomx.ts';
import { CHAIN_ID, sha256, miningBlob, mintId, blockSchema, address } from '/app/server/testnet/consensus.ts';
import { blockClaimMessage, NETWORK, type MiningTemplate, type TestnetBlock } from '/app/shared/testnet.ts';
import { encryptWallet } from '/app/shared/wallet-backup.ts';
if (!NETWORK.includes('testnet')) throw new Error('testnet only');
const blocks = Number(process.argv[2] ?? 45), workers = Number(process.argv[3] ?? 4);
if (!(workers >= 1 && workers <= 8)) throw new Error('1..8 workers');
const NODES = ['http://node-a:3001', 'http://node-b:3001', 'http://node-c:3001'];
const WALLET_NAMES = ['alice', 'bob', 'carol', 'dave'];
// PUBLIC, TESTNET-ONLY password for the disposable wallets' browser backups (posted on #4). Never reuse.
const PASSWORD = process.env.TESTNET_WALLET_PASSWORD ?? 'wikideck-night-testnet';
const STATE = process.env.STATE_DIR ?? '/state';
const dir = `${STATE}/wallets`;
mkdirSync(dir, { recursive: true });
const subtle = webcrypto.subtle;
type W = { name: string; address: string; publicKey: string; privateKey: CryptoKey };
async function loadOrCreate(name: string): Promise<W> {
const keyFile = `${dir}/${name}.jwk.json`;
let jwk: JsonWebKey;
if (existsSync(keyFile)) jwk = JSON.parse(readFileSync(keyFile, 'utf8'));
else {
const kp = await subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, true, ['sign', 'verify']) as CryptoKeyPair;
jwk = await subtle.exportKey('jwk', kp.privateKey);
writeFileSync(keyFile, JSON.stringify(jwk), { mode: 0o600 });
}
const privateKey = await subtle.importKey('jwk', jwk, { name: 'ECDSA', namedCurve: 'P-256' }, true, ['sign']);
const pubJwk = { kty: jwk.kty, crv: jwk.crv, x: jwk.x, y: jwk.y };
const pub = await subtle.importKey('jwk', pubJwk, { name: 'ECDSA', namedCurve: 'P-256' }, true, ['verify']);
const publicKey = Buffer.from(await subtle.exportKey('spki', pub)).toString('base64');
const w = { name, address: address(publicKey), publicKey, privateKey };
const backupFile = `${dir}/${name}.backup.json`;
if (!existsSync(backupFile)) writeFileSync(backupFile, JSON.stringify(await encryptWallet(privateKey, publicKey, PASSWORD), null, 2));
return w;
}
const wallets = await Promise.all(WALLET_NAMES.map(loadOrCreate));
writeFileSync(`${dir}/addresses.json`, JSON.stringify(Object.fromEntries(wallets.map(w => [w.name, w.address])), null, 2));
console.log(`chain ${CHAIN_ID}; wallets: ${wallets.map(w => `${w.name}=${w.address.slice(0, 12)}`).join(' ')}`);
async function api(node: string, path: string, body?: unknown) {
const r = await fetch(node + path, { method: body ? 'POST' : 'GET', redirect: 'error', signal: AbortSignal.timeout(60000),
headers: body ? { 'Content-Type': 'application/json' } : {}, body: body ? JSON.stringify(body) : undefined });
const data = await r.json();
if (!r.ok) throw new Error(data.error ?? `HTTP ${r.status}`);
return data;
}
const engines = Array.from({ length: workers }, () => new RandomX());
const close = () => { for (const e of engines) e.close(); };
process.once('SIGTERM', () => { close(); process.exit(0); });
let accepted = 0, round = 0, fails = 0;
// Each template costs several Wikipedia API calls, and Wikipedia rate-limits this egress IP:
// pace templates (>= MIN_GAP s apart) and back off exponentially on failure.
const MIN_GAP = Number(process.env.MIN_GAP ?? 45), sleep = (s: number) => new Promise(r => setTimeout(r, s * 1000));
let lastTemplate = 0;
try {
while (accepted < blocks) {
const wait = lastTemplate + MIN_GAP * 1000 - Date.now(); if (wait > 0) await sleep(wait / 1000);
lastTemplate = Date.now();
const node = NODES[round % NODES.length], w = wallets[accepted % wallets.length]; round++;
let template: MiningTemplate;
try { template = await api(node, '/api/mining/template', { owner: w.address, publicKey: w.publicKey }); fails = 0; }
catch (e) { fails++; const b = Math.min(60 * 2 ** (fails - 1), 600); console.error(`template ${node}: ${(e as Error).message} (fail ${fails}, backoff ${b}s)`); await sleep(b); continue; }
const h = template.header; if (h.chainId !== CHAIN_ID) throw new Error('wrong chain');
const started = Date.now(); let attempts = 0; let found: { hash: string; nonce: number } | null = null;
let base = randomInt(0, 2 ** 40); const BATCH = 64;
while (!found) {
const results = await Promise.all(engines.map((e, i) => {
const hdr = { ...h, nonce: base + i * BATCH };
return e.mine(h.key, miningBlob(hdr), h.target, 32, BATCH);
}));
attempts += BATCH * workers; base += BATCH * workers;
found = results.find(Boolean) ?? null;
if (!found && Date.now() / 1000 - h.createdAt > 600) break; // stale template
}
if (!found) continue;
h.nonce = found.nonce;
const hash = sha256(miningBlob(h));
const signature = Buffer.from(await subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, w.privateKey,
new TextEncoder().encode(blockClaimMessage(hash)))).toString('base64');
const block: TestnetBlock = { ...h, hash, tokenId: mintId(h), powHash: found.hash, signature, transactions: template.transactions };
blockSchema.parse(block);
try {
const res = await api(node, '/api/blocks', block);
if (!res.accepted) { console.error(`not accepted: ${JSON.stringify(res).slice(0, 200)}`); continue; }
accepted++;
const secs = (Date.now() - started) / 1000;
const line = `#${h.height} ${w.name} "${h.article.title}" token=${block.tokenId} via=${node} ${attempts}H ${(attempts / secs).toFixed(0)}H/s`;
console.log(`[${accepted}/${blocks}] ${line}`);
appendFileSync(`${STATE}/mined.log`, `${new Date().toISOString()} ${line}\n`);
} catch (e) { console.error(`submit: ${(e as Error).message}`); }
}
} finally { close(); }
console.log('done');
+49
View File
@@ -0,0 +1,49 @@
#!/bin/sh
# sim-testnet: private 3-node testnet fixture for WikiDeck Night 1 (poweredge-r350, LAN only).
# Usage (from the repo root):
# deploy/night/testnet.sh up build the image from this checkout and (re)start the 3 nodes
# deploy/night/testnet.sh rolling build, then restart node-a, b, c one at a time (waits for /healthz)
# deploy/night/testnet.sh busy print live matches + open lobbies across the 3 nodes
# deploy/night/testnet.sh mine N [W] mine N real RandomX blocks with W workers (default 4, max 8)
# deploy/night/testnet.sh status tip/height of each node
# deploy/night/testnet.sh down stop the nodes (volumes, i.e. the ledgers, are kept)
# STATE_DIR (default ~/.local/share/wikideck-night) holds the disposable testnet wallets and mined.log.
# It is outside the repo on purpose: never commit wallets.
set -eu
P=wikideck-night
LAN_IP=${LAN_IP:-192.168.1.32}
STATE_DIR=${STATE_DIR:-$HOME/.local/share/wikideck-night}
DC="docker compose -p $P -f compose.testnet.yaml -f deploy/night/compose.lan.yaml"
case "${1:-}" in
up) $DC build node-a && $DC up -d --no-build ;;
down) $DC down ;;
rolling)
# Never take the whole testnet dark: one node at a time, each must pass /healthz before the next.
$DC build node-a
for n in a b c; do
port=$(( 3100 + $(printf %d "'$n") - 96 ))
$DC up -d --no-build --no-deps node-$n
i=0
until node -e "fetch('http://$LAN_IP:$port/healthz',{signal:AbortSignal.timeout(3000)}).then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"; do
i=$((i+1)); [ $i -ge 60 ] && { echo "node-$n not healthy after 120 s"; exit 1; }; sleep 2
done
echo "node-$n healthy"
done ;;
busy)
# Sum of liveMatches + openLobbies over all hosted modes on all nodes (unreachable node counts 0).
node -e "Promise.all([3101,3102,3103].map(p=>fetch('http://$LAN_IP:'+p+'/api/game/modes',{signal:AbortSignal.timeout(5000)}).then(r=>r.json()).then(m=>m.modes.reduce((t,x)=>t+(x.stats?.liveMatches??0)+(x.stats?.openLobbies??0),0)).catch(()=>0))).then(v=>console.log(v.reduce((a,b)=>a+b,0)))" ;;
mine)
mkdir -p "$STATE_DIR"
W=${3:-4}
docker rm -f $P-miner >/dev/null 2>&1 || true
docker run -d --name $P-miner --network ${P}_default --cpus "$W" --memory 1600m \
--user "$(id -u):$(id -g)" -e WIKIDECK_NETWORK=testnet -e WIKIDECK_GENESIS_TIME=1792411200 \
-e MIN_GAP="${MIN_GAP:-45}" -v "$STATE_DIR":/state -v "$PWD/deploy/night":/night:ro \
wikideck:testnet node --experimental-strip-types /night/mine.ts "$2" "$W"
echo "follow with: docker logs -f $P-miner" ;;
status)
for port in 3101 3102 3103; do
docker run --rm --network host wikideck:testnet node -e "fetch('http://$LAN_IP:$port/p2p/status').then(r=>r.json()).then(s=>console.log($port,'blocks',s.size,'tip',s.tip.slice(0,16))).catch(e=>console.log($port,'DOWN',e.message))"
done ;;
*) sed -n 2,11p "$0"; exit 1 ;;
esac
-4
View File
@@ -1,4 +0,0 @@
FROM node:24-alpine
RUN apk add --no-cache openssl
COPY deploy/postgres/setup.mjs /setup.mjs
CMD ["node", "/setup.mjs"]
-2
View File
@@ -1,2 +0,0 @@
FROM postgres:17-alpine
COPY deploy/postgres/pg_hba.conf /etc/wikideck/pg_hba.conf
-8
View File
@@ -1,8 +0,0 @@
# Unix socket is for the official local bootstrap only; no database host port is published.
local all all trust
hostnossl all all all reject
hostssl wikideck_custody postgres all scram-sha-256
hostssl wikideck_custody custody_owner all scram-sha-256
hostssl wikideck_custody custody_runtime all scram-sha-256
hostssl wikideck_custody custody_backup all scram-sha-256
host all all all reject
-61
View File
@@ -1,61 +0,0 @@
import { randomBytes } from 'node:crypto';
import { execFileSync } from 'node:child_process';
import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync, chownSync, openSync, fsyncSync, closeSync, renameSync } from 'node:fs';
// Local SANDBOX provisioning only. No secrets pass through logs, command arguments or source control.
const roots = ['/secrets/admin', '/secrets/owner', '/secrets/runtime', '/secrets/backup', '/secrets/tls'];
for (const root of roots) mkdirSync(root, { recursive: true, mode: 0o755 });
const files = ['/secrets/admin/password', '/secrets/admin/url', '/secrets/owner/url', '/secrets/runtime/url',
'/secrets/tls/server.key', '/secrets/tls/server.crt', '/secrets/owner/ca.crt', '/secrets/runtime/ca.crt', '/secrets/admin/ca.crt'];
const backupFiles = ['/secrets/backup/url', '/secrets/backup/ca.crt'];
const marker = '/secrets/admin/complete';
const put = (file, text, mode = 0o600) => {
writeFileSync(file, text, { flag: 'wx', mode }); chownSync(file, 1000, 1000);
const fd = openSync(file, 'r'); try { fsyncSync(fd); } finally { closeSync(fd); }
};
const provisionBackupRole = () => {
if (backupFiles.some(existsSync)) throw new Error('Partial backup-role secret initialization; preserve volumes for inspection');
const backup = randomBytes(32).toString('hex');
put('/secrets/backup/url', `postgresql://custody_backup:${backup}@database:5432/wikideck_custody`);
put('/secrets/backup/ca.crt', readFileSync('/secrets/admin/ca.crt'), 0o644);
};
if (existsSync(marker)) {
const version = readFileSync(marker, 'utf8');
if (!['wikideck-local-pg-v1', 'wikideck-local-pg-v2'].includes(version) || files.some(f => !existsSync(f))) {
throw new Error('Incomplete secret volumes; restore the matching volumes, never regenerate over an existing database');
}
execFileSync('openssl', ['x509', '-checkend', '86400', '-noout', '-in', '/secrets/tls/server.crt'], { stdio: 'ignore' });
if (version === 'wikideck-local-pg-v1') {
provisionBackupRole();
const tempMarker = `${marker}.upgrade`;
writeFileSync(tempMarker, 'wikideck-local-pg-v2', { flag: 'wx', mode: 0o644 });
renameSync(tempMarker, marker);
} else if (backupFiles.some(f => !existsSync(f))) {
throw new Error('Backup-role secret volumes are incomplete; preserve existing database and inspect volumes');
}
console.log('Existing local sandbox credentials/certificate retained; read-only backup role available.');
} else {
if (files.some(existsSync) || backupFiles.some(existsSync)) throw new Error('Partial secret initialization; inspect preserved volumes before retrying');
const admin = randomBytes(32).toString('hex'), owner = randomBytes(32).toString('hex'), runtime = randomBytes(32).toString('hex'), backup = randomBytes(32).toString('hex');
// PostgreSQL's unprivileged entrypoint also reads POSTGRES_PASSWORD_FILE. This separate scoped
// admin volume is never mounted into the application; the password file must be readable there.
put('/secrets/admin/password', admin, 0o644);
put('/secrets/admin/url', `postgresql://postgres:${admin}@database:5432/wikideck_custody`);
put('/secrets/owner/url', `postgresql://custody_owner:${owner}@database:5432/wikideck_custody`);
put('/secrets/runtime/url', `postgresql://custody_runtime:${runtime}@database:5432/wikideck_custody`);
put('/secrets/backup/url', `postgresql://custody_backup:${backup}@database:5432/wikideck_custody`);
execFileSync('openssl', ['req', '-x509', '-newkey', 'rsa:3072', '-sha256', '-nodes', '-days', '30',
'-subj', '/CN=Wikideck local sandbox CA', '-keyout', '/tmp/ca.key', '-out', '/tmp/ca.crt',
'-addext', 'basicConstraints=critical,CA:TRUE', '-addext', 'keyUsage=critical,keyCertSign,cRLSign'], { stdio: 'ignore' });
execFileSync('openssl', ['req', '-new', '-newkey', 'rsa:3072', '-nodes', '-subj', '/CN=database',
'-keyout', '/secrets/tls/server.key', '-out', '/tmp/server.csr'], { stdio: 'ignore' });
writeFileSync('/tmp/extensions', 'subjectAltName=DNS:database\nbasicConstraints=critical,CA:FALSE\nkeyUsage=critical,digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth\n');
execFileSync('openssl', ['x509', '-req', '-in', '/tmp/server.csr', '-CA', '/tmp/ca.crt', '-CAkey', '/tmp/ca.key',
'-CAcreateserial', '-days', '30', '-sha256', '-extfile', '/tmp/extensions', '-out', '/secrets/tls/server.crt'], { stdio: 'ignore' });
for (const root of ['admin', 'owner', 'runtime', 'backup']) put(`/secrets/${root}/ca.crt`, readFileSync('/tmp/ca.crt'), 0o644);
// postgres:17-alpine runs as UID/GID 70. Private key never mounted into Wikideck or migrator.
chownSync('/secrets/tls/server.key', 70, 70); chmodSync('/secrets/tls/server.key', 0o600);
chmodSync('/secrets/tls/server.crt', 0o644);
put(marker, 'wikideck-local-pg-v2', 0o644);
console.log('Provisioned fresh local sandbox credentials and verified-TLS certificate; no secrets logged.');
}
-50
View File
@@ -1,50 +0,0 @@
# Monero observer service (single Linux host)
This is a supervised **observation-only** process for a dedicated Linux host. It is not a public API, deposit-address service, credit worker, withdrawal signer, or production-launch approval. It requires an independently deployed PostgreSQL instance and a private TLS 1.3 mTLS Wallet-RPC gateway. Do not point it at public Wallet RPC or expose either dependency to the Internet.
## Deployment prerequisites
- Linux x86-64 with systemd, Node.js 24, a dedicated `wikideck-observer` user/group, and a reviewed immutable application release installed read-only at `/opt/wikideck/current`.
- A production PostgreSQL database reachable only on a private network, with verified TLS, encryption at rest, restricted administrative access, encrypted backups and a tested restore. Do not reuse the local sandbox database or runtime credential.
- A mainnet Monero full node and watch-only Wallet RPC behind the already-tested mTLS method-allowlisting gateway. Network policy/firewall must permit the observer host to reach only the intended PostgreSQL and gateway addresses/ports. The gateway must not expose Wallet RPC directly.
- Protected wallet observer/mTLS JSON and credential files owned by `wikideck-observer`, mode `0600`. Keep the mTLS private key and PostgreSQL URL out of shell history, process arguments, environment values, source control and logs. Store host disks and backups encrypted; define and test certificate rotation before use.
- The chosen wallet is independently verified as the intended mainnet watch-only wallet; its spending key is not present on this host. A config endpoint match is not proof that the remote service is the intended wallet.
The example JSON files in this directory are templates only. Copy them to `/etc/wikideck/monero-observer/`, replace the gateway hostname, and install the matching client certificate/key and gateway CA there. The endpoint in both configs must be identical and the certificate chain must be checked for validity dates, key strength and SHA-2 signatures. The application's certificate loader requires owner-only POSIX file permissions.
## One-time database preparation
Use the dedicated schema-owner PostgreSQL credential file and CA file in a restricted operator session. The operation below is explicit, transactional, digest-checked and idempotent; it does **not** create the observer login, add a runtime grant, or enable deposits. Do not run it against a database with unrelated or valuable data before reviewing its schema and backup.
```sh
WIKIDECK_NETWORK=mainnet \
WIKIDECK_CUSTODY_PG_URL_FILE=/secure/operator/schema-owner-url \
WIKIDECK_CUSTODY_PG_CA_FILE=/secure/operator/postgres-ca.crt \
WIKIDECK_MAINNET_SCHEMA_MIGRATION=explicit-schema-migration-only \
node --experimental-strip-types scripts/custody-db.ts migrate-mainnet-schema
```
Have the database administrator create a separate `LOGIN` role with no administrative attributes and no role memberships, and place its TLS PostgreSQL URL in `postgres-url`. Then issue only the observer grants using the schema-owner credential:
```sh
WIKIDECK_NETWORK=mainnet \
WIKIDECK_CUSTODY_PG_URL_FILE=/secure/operator/schema-owner-url \
WIKIDECK_CUSTODY_PG_CA_FILE=/secure/operator/postgres-ca.crt \
node --experimental-strip-types scripts/custody-db.ts grant-monero-observer-runtime wikideck_observer
```
The role name in the command must exactly match the separately provisioned login. The worker role cannot read journals or balances, allocate addresses, post credits/releases, or submit transfers. Restrict the schema-owner credential to this one-time operation and remove it from the host afterward. `custody-db` continues to refuse all other mainnet financial actions.
## Install and operate
Install the service unit from this directory at `/etc/systemd/system/wikideck-monero-observer.service`. Create `/etc/wikideck/monero-observer/` with owner `wikideck-observer` and mode `0700`. Install the two runtime JSON files and all referenced certificates/keys plus `postgres-url` and `postgres-ca.crt`, each owned by that user and mode `0600`. The PostgreSQL URL must use the observer role and must not contain TLS downgrade parameters. Ensure the `current` application release is root-owned and not writable by the service account.
After reviewing the unit against the host's systemd version, reload systemd and start the unit. Confirm the process is running and that logs contain only bounded scan aggregates; logs intentionally omit wallet addresses, transaction IDs, amounts and credentials. Configure an alert outside this host for service exits, sustained scan lag, database/gateway unavailability, WAL/disk pressure and unexpected worker restarts. The worker itself does not deliver alerts.
The service uses a PostgreSQL session advisory lock so a second instance cannot scan concurrently. SIGTERM/SIGINT stops its polling loop and releases the lock. A failed RPC/database batch is retried; a failed scan does not advance the durable cursor. Logs are available through the system journal under identifier `wikideck-monero-observer`.
## Release boundary
This deployment only persists read-only chain observations and scan progress. It does **not** issue customer deposit addresses, expose an address to a user, calculate customer credit, release pending liabilities, enable marketplace checkout, or move XMR. There is no public endpoint or UI connected to these rows. A scan is not proof of solvency or authorization to accept deposits.
The repository still lacks a production Monero daemon/Wallet-RPC/gateway deployment, certificate and secret lifecycle automation, nonempty owned-output validation against the deployed topology, external monitoring/restore evidence, a reviewed customer deposit/withdrawal policy, and live settlement integration. The mainnet candidate is independently marked NO-GO and its current candidate genesis time is 2027-01-01; deploying this worker does not clear any launch gate. The service file is a starting deployment contract, not a certification or instruction to accept funds.
-6
View File
@@ -1,6 +0,0 @@
{
"url": "https://monero-rpc.internal.example/json_rpc",
"clientCertificateFile": "/etc/wikideck/monero-observer/client.crt",
"clientPrivateKeyFile": "/etc/wikideck/monero-observer/client.key",
"serverCaFile": "/etc/wikideck/monero-observer/gateway-ca.crt"
}
-4
View File
@@ -1,4 +0,0 @@
{
"network": "mainnet",
"url": "https://monero-rpc.internal.example/json_rpc"
}
@@ -1,50 +0,0 @@
[Unit]
Description=Wikideck read-only Monero mainnet observation worker
Wants=network-online.target
After=network-online.target
StartLimitIntervalSec=300
StartLimitBurst=5
[Service]
Type=simple
User=wikideck-observer
Group=wikideck-observer
WorkingDirectory=/opt/wikideck/current
Environment=WIKIDECK_MONERO_OBSERVER_WORKER=1
Environment=WIKIDECK_MONERO_OBSERVER=1
Environment=WIKIDECK_MONERO_WALLET_RPC_CONFIG_FILE=/etc/wikideck/monero-observer/wallet-rpc.json
Environment=WIKIDECK_MONERO_MTLS_CONFIG_FILE=/etc/wikideck/monero-observer/mtls.json
Environment=WIKIDECK_CUSTODY_PG_URL_FILE=/etc/wikideck/monero-observer/postgres-url
Environment=WIKIDECK_CUSTODY_PG_CA_FILE=/etc/wikideck/monero-observer/postgres-ca.crt
Environment=WIKIDECK_MONERO_OBSERVER_POLL_MS=30000
ExecStart=/usr/bin/node --experimental-strip-types /opt/wikideck/current/scripts/monero-observer-worker.ts
Restart=on-failure
RestartSec=10s
TimeoutStopSec=40s
KillSignal=SIGTERM
UMask=0077
StandardOutput=journal
StandardError=journal
SyslogIdentifier=wikideck-monero-observer
NoNewPrivileges=true
CapabilityBoundingSet=
AmbientCapabilities=
PrivateTmp=true
PrivateDevices=true
ProtectSystem=strict
ProtectHome=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectKernelLogs=true
ProtectControlGroups=true
ProtectClock=true
ProtectHostname=true
RestrictSUIDSGID=true
RestrictRealtime=true
RestrictNamespaces=true
LockPersonality=true
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
[Install]
WantedBy=multi-user.target
+9 -50
View File
@@ -1,58 +1,17 @@
# M2 increment — canonical indexes and recoverable market observation
# Canonical ledger indexes
Status: implemented local infrastructure, **not full M2 acceptance or production authorization**. Evidence date: 2026-10-21. Related: [production plan](production-plan.md), [custodial design](custodial-market-design.md).
The ledger maintains SQLite indexes for canonical NFT ownership/sequence, mint ordering, block identity, and transaction inclusion. The UI uses these indexes for wallet decks, NFT metadata, and current-chain pagination; they do not change consensus rules or replace proof validation.
## Delivered
## Persistence and reorganization behavior
- [Canonical index](../server/testnet/canonical-index.ts) stores current NFT ownership/sequence, canonical mint/block identity and transaction inclusion in SQLite. Owner/mint ordering and transaction indexes replace whole-chain scans for deck, NFT and marketplace queries.
- [Ledger persistence](../server/testnet/ledger.ts) commits accepted blocks, pending transactions, index connect/disconnect undo and canonical events in **one SQLite transaction**. A losing side branch or mempool submission does not create a canonical event. Disconnects run tip-first; connects run ancestor-first. No await separates the database commit from updating the in-memory tip.
- Events contain sequence, connect/disconnect type, block identity/height/parent, transaction IDs and a hash chained to the previous event. An independently generated local stream ID binds the history; it is **not consensus data or a public proof of honest observation**. Pages contain at most 64 events and no article payloads. Financial/chain history is not silently pruned.
- On first open, original blocks are replayed and independently proof/state validated before additive local index backfill. Later opens compare indexed block identity, ownership, transaction inclusion and event continuity/anchors to that validated chain. Inconsistent state fails closed; existing consensus version, genesis, signatures and free-transfer/trade rules are unchanged.
- [Market reconciliation](../server/market/store.ts) uses indexed current delivery/ownership queries and a persisted `(stream ID, sequence, anchor)` checkpoint. Every observed disconnect of a previously completed order causes a durable review hold, even if delivery reappeared before polling. Review is never automatically repaid. Hold updates and checkpoint advancement commit together in the market database.
- Order and listing review now uses stable-ID keyset batches capped at 32 rows each. A strict, durable job record stores stage, continuation ID, observed time, chain tip/revision, and the bounded canonical event page. Each batch commits row effects and its continuation atomically; the canonical event cursor advances only after both tables finish. A chain tip/revision change during a multi-batch scan rewinds the job and captures a fresh event page, preventing a mixed-view scan from being marked caught up. Completion checks the current event head so events appended during the scan remain behind the write fence.
- While any job/event backlog exists, ordinary market mutations and time-dependent payout/expiry decisions stop; diagnostic/read access remains available. Requests advance one bounded slice, and an unref'd HTTP-lifecycle pump drains remaining work without depending on page loads. The production HTTP process enables a single persistent Node worker thread to select rows, read canonical transaction/NFT/mempool facts from its own SQLite read-only Ledger connection under a consistent read transaction, evaluate order/listing transitions, and atomically persist market row changes plus job progress. The main thread retains event-page acquisition and post-batch tip/revision/event-head/mempool fencing; if observations changed, it rewinds before cursor advancement. This moves fact collection and per-row JSON/status work off-loop, but final fences still run on the request event loop. Worker failure leaves the durable job/cursor intact, fails closed, and requires process restart to retry; there is no horizontal-worker safety claim.
- Reconciliation restart, mid-job event append/reorg fencing, disconnect review, and injected SQLite batch/cursor failures are tested. A failed batch leaves both order effects and durable keyset progress unchanged; restart resumes committed work. Restore mismatch (different stream, different history anchor or a cursor ahead of the restored ledger) is refused rather than resetting the cursor. Restore the matching stopped-node ledger/market backup; any alternative recovery requires reviewed evidence, not deleting a checkpoint.
- [HTTP NFT lookup and custody card checks](../server/testnet/http.ts) use the same index. Wallet deck pagination accepts an optional `tip` query; stale tips return 409. Existing callers without `tip` remain compatible. There is no new public event/admin endpoint, no payment observer and no NFT-lock signer.
Accepted blocks, pending transactions, index connect/disconnect updates, undo records, and canonical event history commit in one SQLite transaction. Losing side branches and mempool submissions do not create canonical ownership events. On a reorganization, disconnects apply tip-first and connects ancestor-first. A failed write leaves both the stored ledger and in-memory tip unchanged.
## Tests and measurements
On initial open, stored blocks are replayed and validated before the local index is built or checked. Later opens verify indexed block identity, ownership, transaction inclusion, and event continuity against that validated chain. Inconsistent state fails closed; no automatic reset or history pruning occurs. These local indexes and event records are not consensus data or a public proof that a node observed an honest network.
The final Docker test-target build passed TypeScript/Vite compilation. All **183 offline tests passed, zero failures/skips**, including native RandomX multi-process HTTP/peer/restart, backup rehearsal and five offline Monero observer contract/security tests. The focused market suite passed **27 tests**. The disposable PostgreSQL suite most recently passed **33/33**, including v1→v2 schema migration and observation persistence.
Wallet-deck results are paged and can be pinned to a canonical tip; stale tips return HTTP 409. Canonical block pages are bounded. Direct trades continue to be validated as complete atomic transactions against the canonical ownership state. No market journal, reconciliation worker, payment observer, or NFT sale-lock signer is part of this design.
- indexed ownership/sequence versus full replay for transfers, multi-card trades and forks;
- append/disconnect/reconnect ordering, side-branch/mempool exclusion, bounded defensive-copy pages and durable restart;
- injected event-write failure rolling back blocks, indexes and mempool together;
- additive migration of a prior-schema copy, refusing corrupt ownership and event records;
- production market adapter exercised with full snapshots forbidden;
- multi-page catch-up and persisted restart checkpoint;
- 32-row order/listing keyset progress, restart continuation, and a new canonical event arriving during an in-flight job;
- chain revision change fencing that resets continuation and refreshes the event page before the scan continues;
- injected batch-write failure rolling back order effects and keyset progress, plus cursor-write failure rolling back checkpoint advancement while preserving committed review holds;
- worker-owned row evaluation/batch/finalize transaction with injected failure, mutation fence and restart continuation;
- canonical event arrival during an in-flight worker batch forces a fresh bounded event page before the cursor reaches the new head;
- separate worker read-only Ledger connection supplies canonical NFT and delivery facts and re-fences when an event arrives during that snapshot;
- main-thread timer fires while a large worker reconciliation backlog remains in flight;
- numeric cursor reuse with a different historical hash rejected;
- real HTTP NFT results and stale-tip deck pagination.
## Validation and capacity limits
[Benchmark script](../scripts/benchmark-canonical-index.ts), available as `npm run benchmark:index -- 10000`, creates/removes its own temporary SQL database. Input is bounded to 1–100,000 synthetic blocks; **these are not valid mined blocks** and are never submitted to a ledger/peer. It measures only derived index behavior, not PoW, network throughput or operating capacity.
The regression suite covers indexed ownership and sequence against replay for transfers, atomic multi-card trades and forks; append/disconnect/reconnect ordering; side-branch and mempool exclusion; durable restart; failed writes; and stale-tip pagination.
Observed in the development Docker environment:
| Metric | Result |
| --- | --- |
| Fixture | 10,000 NFTs/blocks, 9,998 transfers, 16 owner identities |
| SQL fixture build (single transaction) | 5,096 ms |
| 1,000 query groups (NFT + 24-item owner page + optional transaction lookup), median / p95 | 0.619 / 1.167 ms |
| Read all events, maximum 64 per page | 157 pages, 54.5 ms total |
| Verify derived indexes and anchored history | 524 ms |
| Database plus WAL before close | 76,856,784 bytes |
These numbers are a reproducible **baseline**, not acceptance SLOs: host CPU/storage and production concurrency were not selected, outputs include synthetic article payloads, warm caches apply, one transaction amortizes insertion fsync, and real validation/startup/HTTP/market workloads are excluded. They do not establish a supported production envelope.
The synthetic market-journal harness [benchmark](../scripts/benchmark-market-reconciliation.ts), available as `npm run benchmark:market -- 10000 [terminal|confirmed-delivery] [worker] [http]`, measures terminal and confirmed-delivery reconciliation in its own temporary SQLite directory. Both modes use the same Ledger-shaped fixture; worker mode reads it through a separate read-only SQLite connection and performs market row selection, canonical transaction/NFT fact reads, status evaluation and market commits on the worker. In the latest development Docker run, synchronous 32-row batches processed 10,000 terminal orders plus 10,000 listings in 4,100 ms (about 4,878 records/s; sampled event-loop-delay p95/max 18.43/21.95 ms), and confirmed delivery in 5,853 ms (about 3,417 records/s; 21.64/55.67 ms). Worker-owned selection/evaluation/fact reads/commits took 4,508 ms for terminal rows (about 4,437 records/s; delay p95/max 10.93/13.40 ms) and 4,088 ms for confirmed delivery (about 4,893 records/s; 10.80/12.48 ms). Thus worker execution reduced sampled delay, improved this delivery fixture, and slightly slowed terminal-only work. A new optional loopback HTTP mode issues 160 health/market requests during catch-up: worker run request p50/p95/max was 285/322/324 ms, versus 1,416/2,844/2,971 ms for synchronous reconciliation. These two runs are preliminary, local, synthetic, and lack repeated confidence intervals or a representative arrival distribution; the latency is not an SLO. SQLite fixture data is not validated Ledger evidence. All measurements exclude real concurrent users, PostgreSQL and adversarial workloads.
## Remaining gates
M2 still needs target-hardware/data/SLO decisions, repeated concurrent HTTP tests with realistic request mix/rates, multi-instance/restart/in-flight-worker fencing evidence, production financial database/schema and measured recovery/retention/storage growth. The worker removes row selection, canonical fact reads and per-row evaluation from the request event loop, but event-page acquisition and post-batch consistency fencing remain on-loop; horizontally shared job ownership has not been implemented. Ledger PoW replay and DAG state memory still scale with retained history; indexed queries do not solve those costs. Startup validation checks undo-record counts but not every possible future undo mutation against a second reconstructed undo model; comprehensive corruption/fuzz coverage and independent review remain required.
Custodial reservations still stop at `awaiting-lock`. This increment does **not** consume ordinary transfers as custodial settlement evidence: doing that would bypass the reviewed sale-lock/cancel protocol. Real Monero deposit/withdrawal integration, production treasury keys, host attestations and a reviewed versioned NFT lock/completion/cancellation specification remain blocked. No real funds, credentials, external processor or genesis change were used.
The [canonical-index benchmark](../scripts/benchmark-canonical-index.ts), available as `npm run benchmark:index -- 10000`, creates and removes its own temporary SQL fixture. Its synthetic results are a baseline only—not production acceptance limits. Real PoW validation, startup replay, full DAG memory, concurrent HTTP load, and the intended deployment hardware must be measured independently. Indexes improve lookups but do not solve the retained-DAG and full-state costs described in the [consensus reference](testnet-consensus.md) and [production plan](card-only-production-plan.md).
+113
View File
@@ -0,0 +1,113 @@
# Card-only production readiness plan
**Status:** proposed readiness plan, updated 2026-10-28. This is not launch approval, security certification, or permission to expose a public node.
## Product and release boundary
Wikideck's current product scope is **RandomX mining, collecting cards, and direct player-to-player card transfers/trades**. This release will not implement or offer a marketplace, auctions, sales, custody, XMR deposits/withdrawals, or real-money checkout. Direct card trades are signed and applied atomically by the chain; they are not paid orders.
The nearest reasonable release target is a **publicly hosted, non-monetary testnet beta**. It must be labeled experimental and valueless. It is not a mainnet launch, a promise of ownership permanence, an investment product, or an independently secured network. Mining consumes compute, electricity, and time; no reward rate or profitability is promised.
Mainnet or valuable-card use is a separate, higher bar. It remains **NO-GO** until consensus, wallet, network, capacity, deployment, and operator risk-acceptance gates below have evidence and named sign-off. The operator has chosen not to commission external audits; this is a conscious acceptance of additional residual risk, not evidence that the protocol or implementation is secure.
## Current starting point
- Mining, local encrypted wallets, collections, transfers, and atomic card-for-card trades are implemented for the experimental testnet.
- Marketplace, custody, sale-settlement, and Monero payment source, UI, APIs, deployment profiles, active tests, and operator documentation have been removed from the supported repository. Direct on-chain card transfers/trades remain core functionality.
- Existing runtime volumes and historical backup packages may contain local financial journals or external database bindings. Removing source code does not delete or resolve those records; preserve them separately and do not claim new ledger-only backups include them.
- The current network has no public bootnodes or automatic peer discovery. Peers must be configured by operators; containers on one host do not provide independent network security.
- The inherited initial proof-of-work target accepts one in sixteen hashes, and the ten-block retarget is not production-calibrated. Nodes retain the DAG in memory, rebuild state roots across the NFT set, and revalidate stored proofs at startup.
- Browser-wallet encryption is implemented, but same-origin code can abuse an unlocked wallet; old plaintext copies and cross-browser recovery remain concerns.
See the [mainnet launch limitations](mainnet-launch.md), [consensus reference](testnet-consensus.md), [wallet limitations](wallet-security.md), and [security review](security-review.md). Existing passing tests and local rehearsals are useful evidence, not production certification.
## Ordered release gates
### Gate 0 — freeze the card-only scope · implemented
- Publish the scope above in the product and operator docs. Market/custody/payment source, UI, APIs, dependencies, tests, deployment files, and operator tasks are removed from the supported repository.
- Preserve existing node and financial data during retirement. Do not remove Compose volumes, old journals, PostgreSQL schemas, or historical backups. Review/archive any existing market journal before stopping a market deployment; the card-only node will not reconcile or resolve it.
- Version the node backup contract for ledger-only backups. Refuse to create a ledger-only package if legacy financial data or a PostgreSQL custody binding remains in the selected data directory. Keep old paired backup verification/restore available as a data-preservation path; restored legacy files are inert and are not reopened by the card-only application.
- Update the production plan, operator launch checklist, security scope, support text, and release notes so they no longer imply that market, custody, or payment work is part of this release.
- Choose and document the only supported launch target: testnet beta or a separately reviewed mainnet. Do not mix the two identities or reuse testnet data/backups as mainnet state.
**Exit evidence:** scope owner approval is still required. Source/deployment removals are complete; API regression checks cover removed routes while preserving card trades; backup v2 and legacy-data refusal are covered; old paired backups remain portable. No active product docs promise sales or payments.
### Gate 1 — internal protocol and application review · complete by operator decision
**Operator decision (2026-10-28):** no external audit or independent review will be commissioned for this release. The product will proceed using internal code review, regression tests, local adversarial exercises, and explicit operator risk acceptance. This does not certify the software or establish that undiscovered critical defects are absent.
Internal source-assisted review covered consensus serialization/validation, signatures, state commitments, fork choice, timestamps/retarget, peer URL/DNS/pagination/response handling, RandomX native boundary, wallet signing/recovery documentation and tests.
Internal findings and dispositions:
- **Clock rollback could strand accepted SQLite history.** Startup replay applied the live future-skew admission bound to every persisted block. A block accepted at the allowed future edge could fail replay if the clock later moved backward. Startup now replays previously accepted SQLite history without reapplying that live-time bound. New blocks imported from legacy JSON retain a pinned import-time clock and imported-block cutoff; their future timestamps are checked on import and on later replays, so an untrusted legacy file cannot seed arbitrarily future-dated history. Regression tests cover both rollback recovery and repeated rejection of future-dated legacy data.
- **Invalid work reached full NFT-state materialization.** Block validation computed the state transition/root before checking the claimed and actual RandomX proof. Cheap commitment/signature/claimed-target checks now precede native proof verification, and the complete state transition/root is computed only after the native proof matches. A regression uses an instrumented state to assert that a wrong claimed proof is rejected before NFT-state enumeration.
- Added a deterministic 30-block versus 16-block competing-fork regression: equal cumulative work keeps the current tip, and a strictly higher-work branch then causes a 30-block reorganization while preserving both DAG branches. This is a local FakePow consensus-state test, not a multi-host security rehearsal.
Current validation evidence: the Docker test image and TypeScript/Vite build succeeded; the complete offline suite passed **95/95** with the native RandomX HTTP integration; the packaged native engine's upstream known-vector self-test passed. Tests cover signatures/transaction replay, atomic trades, commitments, retarget/key boundaries, equal-work fork choice, reorg/requeue, malformed schemas, peer DNS/manifest/pagination/response rejection, mempool and RPC bounds, wallet backup crypto, and restart/revalidation. These checks are the selected assurance approach; they are not a security certification.
**Residual risks carried forward:** no external auditor or independent reviewer will sign off. The candidate is not frozen. Multi-host eclipse/partition and clock-skew rehearsals, hostile populated-state load/reorg tests, and broad browser-wallet/XSS/recovery exercises remain open engineering work for Gates 2–5. The operator accepts proceeding without external audit; do not describe the result as audited or independently certified.
**Exit evidence:** internal findings fixed with regression coverage; current build, offline suite and native known-vector results recorded; operator accepts the unaudited-risk boundary. Gate 1 is **complete under this explicitly reduced scope**. This completion is not external assurance, and its remaining multi-host/load/wallet exercises continue under the following gates.
### Gate 2 — establish a credible network · in progress
- **Mainnet candidate inspection (2026-10-28, read-only):** `wikideck-randomx-mainnet-1`, candidate chain ID `3ef36901f49d57127ebb0bf43625c7334e9b8ef817fd31953761723b5474ef6c`, genesis `72be7cdac8e625562bc8a49a82a406f41b96a6fde285c9961dceafdbaca8cd1d`, candidate genesis time 2027-01-01 00:00 UTC. The genesis time has not arrived; this is a candidate manifest, not an announced launch. No production node was started and no approval or data volume was created.
- **Repeat benchmark (2026-10-28):** same executable and container limits, 32 hashes measured 25.11 H/s warm (p50 39.13 ms, p95 48.18 ms), 883 ms cold initialization, and 642 ms for a key/cache switch. These two short samples are not a confidence interval and do not establish normal host variability. Both are verification-path hashes, not miner throughput, dedicated-host measurements, aggregate network hashpower, or a security budget. Do not extrapolate them to choose consensus parameters.
- The first bounded sample in the same container was 23.35 H/s warm (p50 41.09 ms, p95 55.81 ms), 796 ms cold initialization, and 594 ms for a key/cache switch. Together these two observations show run-to-run variation only; they are not intended-host miner measurements.
- **Bootstrap policy for the first beta:** use a fixed, operator-curated HTTPS peer allowlist supplied as `WIKIDECK_PEERS`; do not add DHT, automatic discovery, or peers learned from untrusted network messages. Treat configured peers as trust/bootstrap contacts only; each node independently validates every block and transaction. The current protocol provides no peer identity or independent-operation proof beyond the configured URL and TLS connection.
- **Local rehearsal status:** the complete offline suite's native RandomX HTTP integration syncs two separately started node processes over loopback, gossips a mined transfer, and verifies restart/replay. This is local functional evidence only. A disposable three-node Compose attempt on 2026-10-28 could not allocate a Docker bridge subnet because the configured address pools were exhausted; Compose failed before creating services or volumes. No multi-host/failure-domain rehearsal has been performed.
- **Mainnet peer configuration remains empty/unverified:** the repository has no operator-supplied public HTTPS origins, ownership/failure-domain evidence, or exercised TLS endpoints for the two required mainnet peers. The compose profile only forwards operator-provided peers and origin; placeholders are not launch infrastructure.
- For a multi-node rehearsal, use at least three separately administered nodes across distinct failure domains and network providers; record operator, host/region/provider, address/origin, chain ID, software digest, availability window, and which node supplies each bootstrap connection. Three containers or aliases on one host do not count as independent.
- Measure expected and adversarial hashpower on intended hardware; quantify rewrite costs and concentration risk. Decide whether this experimental beta retains the current easy target or whether a future mainnet identity needs different initial difficulty, retarget, timestamp, and stall-recovery rules. Do not alter a launched chain's consensus.
- Rehearse bootstrap with an empty node, peer loss/recovery, partition/rejoin, conflicting branches, stale/malicious configured peer, and independent mining. Record the observed tips, cumulative work, sync lag, and recovery time. Peer URL count alone is not evidence that peers are online or independent.
- State the finality/reorganization limits honestly. There is no formal finality today; a confirmation count is not an absolute guarantee.
**Exit evidence:** explicit testnet-only beta decision (or separately approved mainnet candidate), documented bootstrap peer allowlist and ownership/failure domains, repeated intended-hardware hashrate data with variance, multi-host partition/reorg/stall rehearsal, a written risk/attack-cost estimate, and an operator-owned peer/upgrade/incident plan. Internal sign-off only; no external audit is planned.
### Gate 3 — demonstrate capacity and recovery limits
- Define the expected chain length, block rate, peer count, user/API load, disk budget, memory ceiling, startup time, and latency/error objectives.
- Run repeated tests on populated long-chain fixtures and the intended hardware, with concurrent mining, peer sync, wallet/deck reads, transfers/trades, reorgs, and hostile traffic. Measure tail latency, memory, CPU, disk/WAL growth, and restart/revalidation time.
- Test clean shutdown, process crash, disk pressure, corrupted/stale state, isolated restore, and replay using the exact release binary. Do not treat `/healthz` alone as readiness.
- Define and test an archival, pruning, or capacity transition before resource growth can make nodes unable to sync or restart. Do not alter consensus history silently to reclaim storage.
**Exit evidence:** reproducible benchmark report with workload and limits, enforced resource budgets, failure/reorg results, and a successful isolated restore/replay drill.
### Gate 4 — wallet, trades, and user protection
- Test create, lock, unlock, backup, restore in a fresh browser/profile, and recovery after app/browser upgrade across the supported browser matrix. Test signed transfer/trade review, stale offers, pending state, and reorg outcomes.
- Perform an internal threat review of same-origin script compromise, extensions, password entry, old plaintext-wallet migration, downloaded backup handling, and key-loss support. Decide whether the beta accepts browser-only signing; document residual risks rather than implying external wallet assurance.
- Publish experimental/no-value disclosures, mining resource risks, irreversible-transfer warnings, privacy/data-retention terms, Wikipedia text/image attribution and license handling, support contact, abuse-report path, and stop conditions.
- Select and publish an appropriate project software license before public distribution. A Wikideck license does not replace Wikipedia or dependency licenses.
**Exit evidence:** internal wallet threat review, verified recovery drill, tested trade flows, reviewed participant disclosures, public support/abuse contacts, and license decision.
### Gate 5 — operate and release safely
- Prefer a managed host unless the intended self-hosted site proves ISP permission, reachable ingress/CGNAT handling, DNS/TLS renewal, trusted-proxy correctness, no direct backend exposure, firewalling, restricted administration, patching, and power/network resilience.
- Deploy independent monitoring and alert delivery for peer/tip freshness, reorgs, native miner failures, latency/queue saturation, disk/WAL growth, and service availability. Assign a real responder and incident/rollback procedure; do not imply HA or 24/7 response without it.
- Encrypt backups off-host and rehearse cold restore. Define and meet recovery point/time objectives; protect wallet recovery separately from node data. Preserve database/WAL consistency and verify restored proofs/ownership before resuming service.
- Freeze the release artifact: reviewed base-image digest, dependency/native versions, SBOM, vulnerability and native-code scans, build provenance/signature, configuration manifest, and rollback image. Re-run the complete suite and smoke test against that exact artifact.
- Run a limited, non-monetary soak and record go/no-go, known risks, release hashes, operator, reviewer, and stop criteria. Do not convert a beta into mainnet by changing an environment variable or changing the chain identity after launch.
**Exit evidence:** intended-host deployment test, alert drill, off-host restore result with measured RPO/RTO, signed/frozen artifacts, exact-release test report, and recorded operator/reviewer approval for the beta's limited exposure.
## Release decisions
### Non-monetary public beta
May be considered only after all applicable gates pass, the node remains on the explicitly labeled experimental testnet, cards are not represented as valuable, and the operator accepts the single-host or stated availability limits. This is a production-hosted beta, not production chain security.
### Mainnet or valuable cards
Requires all gates plus measured and operator-accepted consensus/economic risks, calibrated and frozen consensus parameters, a credible peer/miner topology, reviewed wallet protections, sustained capacity and adversarial evidence, and explicit governance/upgrade and incident procedures. External audit is intentionally not a requirement under the operator's decision, so residual risk remains higher and must be explicitly accepted before any mainnet activation. Until then, retain **NO-GO**.
### Markets and real money
Out of scope for this product plan. No market/custody/payment milestone is a prerequisite to the card-only beta. Any later decision to add sales or funds requires a new product scope, threat model, legal review, settlement/custody design, and separately approved release plan; it must not be inferred from this document.
## Evidence record
For every gate, record an owner, exact release/manifest, test or rehearsal, measured result, artifact location/hash, reviewer, residual risk, and disposition. Missing evidence is **unverified**, not passed. A successful build, local container startup, peer count, test total, or environment flag is never launch approval by itself.
+4 -4
View File
@@ -1,6 +1,6 @@
# Consensus calibration and adversarial analysis — stage 3
**Decision remains NO-GO.** This stage supplies reproducible offline tools and bounded measurements, not new launch parameters, an independent audit or an operational network. Consensus, initial target, genesis, chain identity and approval/payment gates are unchanged.
**Decision remains NO-GO.** This stage supplies reproducible offline tools and bounded measurements, not new launch parameters or an operational network. Consensus, initial target, genesis, and chain identity are unchanged.
## Tools and safety boundaries
@@ -17,7 +17,7 @@ Wikideck interprets the 256-bit RandomX output as a big-endian integer and accep
The current `0fff…ffff` maximum/initial target requires **16 expected hashes**. The 15-minute setting controls the retarget goal; it does not force miners to wait 15 minutes before submitting an initially easy block. For a specified integer network rate H and goal S seconds, the analysis computes `floor(2^256 / (H*S)) - 1`, bounded by the existing allowed target range. This formula assumes stable aggregate honest work and does not choose a safe launch rate, security budget, or rounding-independent exact interval.
The report also includes `(q/(1-q))^z` for q < 0.5 (1 for q >= 0.5), under an idealized fixed-difficulty Poisson race with attacker share q and a **known current deficit** of z blocks. This is the probability of ever catching up under those assumptions, **not** double-spend probability after z observed confirmations: attacker progress during confirmation waiting is not modeled. There is no network latency, eclipse, selfish mining, timestamp manipulation, adaptive difficulty, economic cost or attack detection model. Do not derive a payment finality policy from this table.
The report also includes `(q/(1-q))^z` for q < 0.5 (1 for q >= 0.5), under an idealized fixed-difficulty Poisson race with attacker share q and a **known current deficit** of z blocks. This is the probability of ever catching up under those assumptions, **not** a guarantee that a block is final: attacker progress while a block accumulates confirmations is not modeled. There is no network latency, eclipse, selfish mining, timestamp manipulation, adaptive difficulty, economic cost or attack detection model.
## Local native measurement (2026-10-20)
@@ -56,7 +56,7 @@ Before production calibration can be approved:
- Benchmark the exact final native/image build on multiple intended independent miner/validator hosts; record CPU model, operating mode, effective quotas, competing load, cold/warm/cache-switch distributions and batch-miner throughput. Use repeated runs and documented confidence/variance, not this single sample.
- Establish credible aggregate honest hashrate, launch ramp/surge/drop ranges and attack/rewrite cost assumptions; independently review target choice and the inherited ten-block/clamped endpoint retarget, including gaps across windows and timestamp attacks.
- Add stochastic mining/partition/clock/adaptive-hashpower models and sustained multi-host rehearsals with valid reference proofs, full state commitments, mempool/reorg persistence, networking and realistic resource pressure.
- Freeze reviewed rules and actual genesis date with a new identity where required. Publish the manifest/artifact hashes and obtain independent review and explicit operator sign-off. Do not patch an active chain's rules in place.
- Decide payment holds/reserves/disputes independently; ten confirmations cannot be sold as absolute finality on an unbootstrapped PoW chain. Real payments remain blocked.
- Freeze the selected rules and actual genesis date with a new identity where required. Publish the manifest/artifact hashes and record internal findings plus explicit operator risk acceptance. Do not patch an active chain's rules in place.
- Document reorganization and confirmation limitations honestly; no finite confirmation count is absolute finality on this unbootstrapped PoW chain.
See [security review](security-review.md), [launch evidence register](operator-launch.md) and the read-only preflight. The calibration blocker remains open.
-158
View File
@@ -1,158 +0,0 @@
# ADR 002 — Custodial XMR balances and marketplace settlement
Status: **implementation authorized; sandbox accounting foundation implemented, live custody disabled**. Updated 2026-10-20. Supersedes the preferred research direction in [ADR 001](settlement-feasibility.md), not its evidence or security warnings. Related: [production plan](production-plan.md).
## 1. Recommendation and scope
Use one accountable custodian per market, a pooled Monero treasury with deposit subaddresses, and an internal double-entry XMR ledger. Purchases move liabilities between ledger accounts; only deposits, withdrawals and treasury movements touch Monero. Start with fixed-price sales, one authoritative financial writer and no cross-host credit, user-to-user balance transfers, lending or live auctions.
The operator has authorized proceeding with implementation instead of the previously preferred arbitrated multisig route. The first increment below is an isolated sandbox; no wallets, payable addresses, live deposits, keys or funds were accessed. Production treasury infrastructure and new NFT consensus rules are not activated. Current mock v3 terms and historical v2 orders remain unchanged.
### Implemented first increment
- [Custody command domain](../shared/custody.ts): strict versioned sandbox consent, exact atomic amounts, custodian/network/actor/expiry/nonce binding and fixed author policy. Existing market signatures cannot debit custody balances.
- [Custody engine](../server/market/custody.ts): isolated testnet SQLite/WAL/FULL-sync financial model, transactional double-entry postings, immutable-entry triggers, startup replay audits, durable receipts, one-time fictitious credits, exclusive fixed-price reservations, blocked outbox and cancellation of unstarted intents. Resource budgets stop new work without blocking release of existing holds. PostgreSQL remains the planned production store; this SQLite implementation is not approved for real custody.
- [Custody UI](../src/CustodyPanel.tsx): marketplace “Custody preview” tab with reviewed signatures, private/paged balances and activity, test funding, listing/reservation and withdrawal-hold cancellation. A lost response retains the original signed envelope for replay rather than creating a new debit nonce.
- HTTP endpoints `/api/custody` and `/api/custody/command` are off by default; explicit `WIKIDECK_CUSTODY_MODE=sandbox` enables testnet only. All other enabled modes and mainnet sandbox are rejected before node resources open. Requests use the node's origin/admission/body limits, per-route mutation throttling and sanitized errors. No observer/admin settlement or balance-credit endpoint exists.
- [Stopped-node recovery](../server/recovery.ts) includes the optional custody sandbox database and its identity while continuing to accept existing two-database backups. Financial receipts are not pruned. Restore/startup checks do not substitute for production reconciliation.
- Offline SQLite fixture methods exercise fee allocation and prepared-withdrawal identity/retry/cancellation boundaries. They never access Monero and are not callable through HTTP. Public reservations stop at `awaiting-lock`; there is **no automatic NFT delivery or settled sale** in this increment. Monero address allocation and read-only observation groundwork now exist, but no deposit scan worker, customer credit, live withdrawal, signer, author payout or reorg compensation is wired or enabled.
- **Financial storage update:** [ADR 003](postgres-financial-storage.md) selects PostgreSQL and records the integrated asynchronous custody backend, restricted runtime/schema roles, deferred accounting constraints, explicit SQLite freeze/import, and full dump/restore rehearsal. SQLite remains an opt-in-compatible local sandbox default, not an automatic fallback. Real custody and production operating acceptance remain blocked.
**Monero observation and deposit-address allocation groundwork:** [server/market/monero-observer.ts](../server/market/monero-observer.ts) keeps the observer strictly read-only, with bounded requests, strict HTTPS/literal-loopback-only HTTP, no redirects, bounded responses/deadlines, JSON-RPC ID validation and lossless integer handling. A separate, narrow `createMoneroDepositAddressRpc()` capability verifies a mainnet primary address with `get_address` plus `validate_address`, then derives a domain-separated fingerprint. It can inspect one indexed subaddress or request exactly one labeled subaddress; it exposes no transfer, relay, sweep or withdrawal operation. The allocator [server/market/monero-deposit-allocation-store.ts](../server/market/monero-deposit-allocation-store.ts) uses PostgreSQL v3 beneficiary/index reservations: it reserves first, serializes cooperating allocators per wallet/account, checks the live wallet fingerprint and exact reserved index, and recovers a lost `create_address` response by looking up the deterministic label before retrying. Actual v0.18.5.4 testing confirmed `get_wallet_info` is unavailable and an unused address index returns RPC error `-15` (“address index is out of bound”); the client recognizes only that precise unused-index response. Watch-only provisioning remains a deployment requirement. PostgreSQL v4 now records a per-output public key and global index while preserving historical observations without a creditable output identity. The observer joins transaction-level `get_transfers` metadata to bounded `incoming_transfers` output records and identifies each output as `txid:pubkey`; the gateway allows only bounded read parameters. The source-contract parser and fixtures were updated, and the actual v0.18.5.4 Stagenet rehearsal confirmed the gateway permits `incoming_transfers`; for an empty address the wallet emits `{}` without default empty fields, which the parser handles as an empty array. The offline, unfunded rehearsal did not exercise non-empty owned output parsing, so that remains fixture-tested. The app does not start the gateway, observer, or allocator; no output assessment/credit journal, customer deposit API, withdrawal worker or sale-settlement path is wired. No financial journal can be posted by the Monero observer or allocator. This is integration groundwork, not a live payment path.
**Reviewed pending-deposit stage:** an isolated coordinator can stage an operator-reviewed observation into a distinct non-spendable pending liability, then perform a second signed review to release it into `available`. Both steps use the immutable output identity and beneficiary allocation. Reorg observations create output-scoped holds; new purchases and withdrawals for that beneficiary stop until the output is re-observed as present, unlocked, sufficiently confirmed, and an allow-listed reviewer signs a resolution. Hold resolutions and release journals are append-only; no automatic journal reversal occurs. These functions are not exposed through HTTP or wired to startup, and the required reviewer keys are not provisioned. This is sandbox accounting machinery, not proof of treasury backing or permission to accept live deposits. Automatic scanning/hold operations, production deposit observation, withdrawals, and sale settlement remain unimplemented.
## 2. Identity and trust boundaries
- A balance belongs to `(custodianId, Wikideck network, chainId, Wikideck public-key identity, Monero network)`. Identical user keys at different hosts do not create shared balances. The UI must name the custodian and networks before any deposit.
- Allocate a deposit subaddress lazily after authenticated proof of Wikideck key possession and custody-term acceptance. Store wallet generation/ID, account index, subaddress index, address and immutable beneficiary mapping **before** displaying it. Never reassign an old address; rotated addresses remain monitored. Bound allocations to prevent lookahead/storage abuse.
- Subaddresses identify incoming outputs; wallet RPC can report output balances per subaddress, but these are **not the marketplace entitlement ledger**. After internal sales or pooled withdrawals those figures no longer represent what a customer is owed. There is no on-chain subaddress-to-subaddress purchase transfer.
- Keep Wikideck wallet identity keys client-held. Monero spending keys are operator-held, separate from the market attestation key, admin credentials and application deployment credentials. A deposit proof does not authenticate its sender; deposits credit the preassigned beneficiary, not an arbitrary claimant supplying a txid.
- Lost Wikideck keys are not recovered by publishing a Monero proof. Recommend an optional separately enrolled recovery credential and delayed, audited dual-control recovery; absent an approved recovery policy, no unilateral support reassignment. Withdrawal authorization requires fresh key proof and an independently enrolled second factor. Browser key storage/session security must be reviewed before custody.
## 3. Components and storage
| Component | Responsibility / access |
| --- | --- |
| Market API | Validates signed, versioned intents; presents balances, deposit details and receipts. No treasury spending key or generic wallet RPC proxy. |
| Ledger and order coordinator | Sole authoritative transactional writer for reservations, entries, order transitions, inbox/outbox and receipt/idempotency records. |
| Deposit observer | Private wallet scanner and owned Monero daemon; observes output identity, canonical inclusion and unlock state. Prefer view-only operation; spent-state reconciliation requires current signed key images or another reviewed spend-aware source. |
| Wikideck observer / relayer | Tracks canonical lock, completion, cancellation and reorg events using durable cursors; retries exact stored messages. Cannot edit financial balances. |
| Treasury worker / isolated signer | Serializes spend construction, validates approved withdrawal intents, destination, amount, fee cap and policy; persists prepared transactions before relay. Independent limits and approvals, not blind signing for API requests. |
| Reconciler and operations | Independently compares ledger, wallet and chain observations; alerts/halts affected operations; administers reviewed compensations, not arbitrary balance edits. |
PostgreSQL is now selected and integrated for the custody sandbox under [ADR 003](postgres-financial-storage.md): exact `NUMERIC` with explicit integer checks (avoiding silent scale rounding), transactional row/advisory locking, unique constraints and separately reviewed backup/PITR operations. SQLite remains suitable for disposable compatibility models; no automatic promotion/fallback occurs. Financial order transitions and journal entries share one PostgreSQL transaction; external chain/wallet effects require a durable outbox, never a cross-database pretend transaction. One financial writer at a time initially; readers use coherent snapshots. Future treasury failover must fence the old worker before spending resumes.
Minimal entities: custodians/network bindings, authenticated customer identities/recovery enrollment, deposit address mappings, observed outputs and inclusion history, ledger accounts/journals/entries, immutable sale terms, purchase reservations, chain events/cursors, withdrawal intents/attempts/prepared transactions, outbox/inbox, signed receipts and audited cases/approvals. Mutable projections are rebuildable; history and external-effect identity are not discarded.
Use canonical atomic-unit strings in APIs and signatures and `bigint` internally; never parse RPC monetary JSON through JavaScript `Number`. Pin and test an exact-integer RPC codec. Individual amounts and aggregate balances need explicit bounds; aggregate liabilities must not inherit a per-order bound accidentally.
## 4. Accounting model and invariants
Customer balances are liabilities, partitioned into `available`, `purchase-reserved`, `sale-pending` and `withdrawal-reserved`. Show uncredited deposit observations separately. Keep author commission liabilities, operating revenue, treasury assets, withdrawal-in-flight clearing, network expense and operator capital distinct. Pending credits are not spendable.
Example postings (debits/credits follow normal asset/liability conventions):
| Event | Debit | Credit |
| --- | --- | --- |
| Eligible deposit | Treasury XMR asset | Customer available liability |
| Purchase reservation | Buyer available liability | Buyer order-reserved liability |
| Mature canonical sale | Buyer order-reserved liability | Seller available liability + author payable liability + earned host commission |
| Safe cancellation | Buyer order-reserved liability | Buyer available liability |
| Withdrawal reserve | Customer available liability | Customer withdrawal-reserved liability |
| Confirmed withdrawal | Customer withdrawal-reserved liability | Treasury XMR asset (recipient amount + approved actual network fee) |
For the withdrawal row, reserve recipient amount plus a signed maximum fee first, release unused fee allowance in a balanced posting, and retain an in-flight asset/liability reconciliation bridge between relay and confirmation. A treasury movement between operator wallets is an asset reclassification, not a customer deposit. The detailed chart of accounts, fee clearing and accounting recognition timing require review before implementation.
Mandatory invariants:
- Every posted journal balances exactly in atomic XMR; journals are immutable. Corrections are linked compensating entries with reason and approval.
- No spendable customer account goes negative; reservation checks, posting and order state change commit together. Concurrent purchases/withdrawals cannot spend the same available balance.
- Every order reserves at most one gross and settles or cancels once. A nonce reused with different content is rejected; retries return the original receipt.
- Count each economic deposit once using wallet/network plus transaction/output identity (not txid alone or a reorg-sensitive global index). Pin the supported RPC representation and output-key/index mapping in fixtures; aggregated reports must not duplicate individual outputs. Spending the pooled output later does not erase its customer's credited liability.
- Maintain at least 100% backing of recognized customer/author liabilities, plus separately funded operating/fee/loss capital. Reconcile assets and liabilities on the same snapshot with in-flight withdrawals, locked change and internal treasury transfers accounted exactly once. Locked assets can provide backing but not immediate withdrawal liquidity.
- Never borrow customer funds to fund expenses, reserves or promised compensation. Revenue withdrawal is blocked if backing/liquidity limits fail. Reserve proofs alone do not prove liabilities or solvency.
## 5. Deposit lifecycle
`observed → confirming/locked → available`, or `orphaned / quarantined`.
Scan authoritative wallet-owned outputs, not buyer screenshots, tx proofs or callbacks. Require healthy daemon/wallet synchronization, accepted canonical inclusion, a versioned confirmation threshold and actual wallet-reported unlock eligibility. No mempool credit; no wall-clock-only maturity. Persist inclusion block hashes and rescan overlapping ranges after restarts/reorgs; maintain wallet allocation lookahead from backed-up mappings. Unknown deposits go to a suspense queue, not operating revenue.
Multiple/partial deposits simply accumulate when individually eligible; deposits are not invoices and do not reserve a listing. Credit the actual valid amount, with no conversion or hidden deposit fee in the proposed baseline. Tiny output handling must be resource-bounded without silently confiscating legitimate funds. Disabling new deposit displays cannot stop payments to previously issued addresses: continue monitoring and handling those liabilities.
If a previously credited deposit is orphaned, append a reversal/restricted-balance case and freeze affected spending. Do not silently debit unrelated customers or pretend a completed withdrawal can be undone. Record any already-consumed shortfall as an operator loss/receivable under approved policy, with incident exposure capped by funded capital. Deep reorg risk is residual, not eliminated by confirmations.
## 6. Fixed-price sale lifecycle and NFT coordination
Proposed order states: `funds-reserved → lock-pending → locked → completion-submitted → delivery-confirming → settled`; alternatives: `cancel-pending → cancelled`, or `review` at any uncertain boundary. Seller proceeds are not spendable before `settled`.
1. Seller signs fresh custody-protocol listing terms: exact card/sequence, allowed host settlement key, exact XMR gross, fee split/beneficiaries, protocol/network/order domain and validity rules. Buyer reviews and signs the immutable checkout quote, including the custodian, recipient identity, maturity and cancellation policy. V3 mock signatures do not authorize debiting real balances; use a new domain/version with explicit consent.
2. In one financial transaction, validate terms/availability, reserve funded **available** buyer balance, allocate an order ID and store the lock outbox intent. A local reservation protects buyer funds, not the NFT. If the seller has already transferred the card elsewhere, fail safely and release only after no live completion authority remains.
3. A new, separately reviewed Wikideck sale-lock transaction binds card/sequence, seller, buyer, order/market/chain IDs, terms digest, host public key and consensus-height deadlines. Ownership remains with the seller, but conflicting transfers and locks are rejected. Obtain the seller's exact authorization; the host must not be able to redirect the card to itself or another buyer.
4. After lock maturity and a durable reservation, the host signs a narrowly scoped funding/release attestation and relays the matching sale completion. Validators verify deterministic lock/signature/deadline rules, **not** Monero RPC or internal balances. They trust the host's assertion that customer funds were reserved under its deposit policy. A compromised host can lie about funding; seller assent and host accountability are the remaining protections.
5. On canonical completion at the selected Wikideck depth, commit once: consume buyer reservation and allocate seller, author and host amounts. The outbox/inbox and unique completion identity recover a crash after chain delivery but before journal commit. No Monero transaction occurs for this purchase. Display inclusion and maturity separately; the existing roughly 15-minute block cadence can make this slow.
6. Cancellation releases buyer funds only after canonical cancellation/expiry is mature and all previously signed completion paths are invalid under consensus. Never refund on a website timer, mempool absence, RPC timeout or current lack of delivery alone. If completion and cancellation race, canonical rules choose one; an uncertain fork remains reserved/reviewed until resolved.
NFT lock/completion/cancel rules are **not implemented or fully specified here**. Exact boundary heights, expiry, in-block ordering, seller authorization lifetime, host-key rotation/revocation, third-party submission of stored witnesses and fork behavior need a dedicated consensus specification and tests. Existing ordinary signed transfers cannot safely substitute because they can be submitted after a refund.
If the host disappears, a reviewed height-expiry path should eventually return NFT control without a host signature. It cannot recover custodial XMR; financial recovery still depends on operator backups/keys. A stalled chain delays safe cancellation. This is a recoverable saga with explicit trust, not an atomic commit across chains.
**Reorg after settlement:** pause affected withdrawals and resale, preserve the original postings, and enter review. If the same completion rematures, resolve without a second credit. If it is invalidated permanently, compensate with linked entries and prevent both a new delivery and buyer reimbursement. If proceeds have already left custody, use approved operator capital/loss procedures; never assume reversing a database entry recovers XMR or automatically confiscate unrelated balances. Confirmation/hold depths and funded exposure limits must reflect measured Wikideck chain security before launch.
## 7. Fees and small prices — proposed policy change
Retain exact native-XMR listing prices, no economic listing minimum, current independent downward rounding and fixed 1% author allocation. Gross equals seller credit plus author credit plus host commission. Internal purchase settlement has **zero Monero network fee**; one-atomic-unit sales are possible when rounded commissions are zero. Resource/rate limits still apply.
Propose: depositor pays their external sending fee; withdrawing beneficiary pays the quoted actual withdrawal fee; operator funds treasury sweeps/consolidation from disclosed operating capital. This replaces the earlier per-sale network-cost model **only if approved**. Do not run the existing per-sale payout-budget rejection unchanged for ledger purchases.
Author fees accrue as separately identified, fully backed liabilities associated with the fixed policy recipient; do not assume a Monero address is a Wikideck login or let an admin silently redirect it. A reviewed address-control enrollment or fixed-destination payout procedure is required. They may accumulate until economical to pay, but cannot become host revenue; timing, fee payer and small/dormant balance treatment need explicit terms. This accumulation is proposed, not already authorized.
No hidden withdrawal minimum or flat fee. Baseline: exact recipient amount plus a user-signed maximum fee; decline/defer before signing if it cannot be funded. A tiny balance remains owed even if a standalone withdrawal is currently uneconomic. Define fee-aware full-balance withdrawal, closure and unclaimed-funds handling before launch; do not promise every atomic balance can be withdrawn alone economically. Defer batching initially because it complicates fee allocation, privacy and partial outcomes.
## 8. Withdrawal protocol
`requested → reserved → approved → preparing → prepared → relay-unknown/submitted → confirming → complete`, with `review` for uncertainty. Cancellation is straightforward only before creation of an externally usable signed transaction.
- Fresh signed authorization binds custodian, both network identities, actor, destination, exact recipient amount, max fee, withdrawal ID/nonce, policy version and expiry. Verify Monero network/checksum; initially accept literal standard/subaddresses only, no DNS/OpenAlias or integrated-address ambiguity. Show full destination and total debit; use step-up authentication, new-destination cooling and independent approval above reviewed risk limits.
- Atomically reserve amount plus max fee. A single fenced treasury worker allocates an attempt before wallet I/O. Check pooled unlocked liquidity, not the depositor's original outputs. Do not promise immediate withdrawals when change is locked or cold treasury replenishment is required.
- Construct without relay, check actual fee/destination/amount/change against authorization, and durably encrypt/store signed transaction identity, metadata, selected-input identifiers and recovery material before broadcasting. `transfer` with `do_not_relay`/`get_tx_metadata` followed by `relay_tx` is an RPC capability, **not** a database transaction or automatic idempotency guarantee. Test the pinned wallet's construction/cache behavior, lost responses and input reservation explicitly.
- On relay timeout/crash, reconcile or retransmit the **same** prepared transaction. Do not construct another payment or release the reservation just because an RPC says failed/not found. A signed transaction may still be relayed by someone holding it; replacement/cancellation requires a reviewed proof that the old spend can no longer succeed, including reorg exposure. Uncertain attempts stay quarantined.
- After canonical withdrawal maturity, close liability once, account actual fee and release unused allowance. Preserve transaction keys/metadata securely for support; never expose secrets in logs. Outgoing reorgs reopen tracking, not a second withdrawal. No batch/automatic split in the first release; if construction yields multiple transactions, reject before relay or require an explicitly reviewed multi-transaction attempt model.
## 9. Custody operations, privacy and recovery
- Recommend a view-only deposit observer plus an isolated, policy-constrained spending service and offline-signing/dual-control cold treasury. Cold storage and hot liquidity caps limit routine exposure; old deposit addresses may continue receiving into a hot wallet, so sweeping/rotation does not create a cryptographic total-deposit cap. A compromised signer can spend its wallet regardless of application limits. Pin and review the actual signing technology; do not assume arbitrary HSM/threshold compatibility with Monero.
- Private fixed-origin authenticated RPC only; no public wallet RPC, browser credentials, arbitrary URL fetches or unrestricted proxy. Least privilege, method allowlists, independent signer policy, bounded bodies/timeouts, service authentication and encrypted transport where crossing hosts. Disable production capability by default and fail closed on network/profile mismatch.
- Track daemon/wallet lag, canonical tip disagreement, reconciliation differences, queued/uncertain withdrawals, locked liquidity, deposit/reservation concentration and cold/hot exposure. Maintain separate switches for new deposits, new orders, author payouts and withdrawals. During incidents continue monitoring existing liabilities and provide a support/recovery path; blanket freezes are not a substitute for reconciliation.
- Back up the financial journal/WAL, immutable customer-to-subaddress mapping and allocation high-water marks, wallet files/cache/seed under separate encrypted custody, policy versions, attestation keys, signed intents and prepared/outgoing transactions. Wallet seed alone cannot restore internal customer balances or all outgoing destination metadata. Restore into an isolated, non-spending environment; reconcile external transactions before enabling the single fenced signer. Drill full recovery and key compromise response.
- Custodian learns deposit-to-Wikideck-wallet, purchase and withdrawal linkage despite Monero's public-chain privacy. Keep balances, addresses and history private/actor-scoped; minimize access/retention and redact analytics/logs. Audit exports and legal disclosure need controlled procedures. Hash-chained journal exports help tamper detection but do not prove honest custody or prevent privileged tampering without independent copies/review.
- No automatic global wallet bans. Distinguish account-security restrictions, disputed cases and evidence-backed local service decisions; publish response, appeal and correction rules.
- Obtain qualified US custody/money-transmission, sanctions, consumer, privacy and tax advice before funds are accepted. Decide customer asset segregation, insolvency treatment, loss allocation, closure and support obligations with counsel. No claim of insurance, legal exemption or guaranteed reimbursement without actual reviewed arrangements and funding.
## 10. Integration and staged acceptance
Reuse [exact XMR amounts](../shared/xmr-amount.ts), [pricing splits](../shared/xmr-pricing.ts), [v3 mock domain](../shared/market-v3.ts) and receipt concepts in [market store](../server/market/store.ts). There is no connected live payment adapter. The selected implementation path is direct pinned Monero wallet/daemon observation for deposits, a pooled PostgreSQL liability ledger, and an isolated, policy-constrained treasury signer for withdrawals; each component requires production integration and review before funds are accepted.
1. **Approve scope and economics:** custodian identity, custody disclosure, account recovery, beneficiary enrollment, withdrawal/author fee policy, balance accumulation, loss/reserve obligations and numerical risk/confirmation/hold policies. These remain open; no fabricated thresholds or support SLA.
2. **Offline financial model:** property-test conservation, nonnegative available balances, concurrency, replay, output deduplication, tiny amounts, duplicate workers, crash at every journal/outbox boundary and repeat restoration. Keep mocks isolated; no mock balances become real opening liabilities.
3. **Separate NFT consensus specification:** lock/completion/cancel/expiry/host-attestation semantics, cross-market double sales, stale signatures, host disappearance and both fork races. Independent review, versioned network activation and migration approval; no silent changes to existing chain identity.
4. **Disposable Monero integration:** only with separate network/budget/access approval. Verify lossless RPC, output identity, wallet restore/lookahead, locked/double-output deposits, reorgs, construction-response loss, signer restrictions, relay ambiguity and withdrawal recovery. Independent security/accounting review and measured load/capacity tests.
5. **Operational release:** funded reserves and liquidity, counsel/terms, penetration test, audited restore/incident drills, customer statements/support and operator sign-off. Start with declared low exposure and manual withdrawal approvals; expand only after measured evidence. No live auction release.
Required failure outcomes: duplicate deposit credits are impossible; insufficient/unlocked-pending funds cannot buy; two concurrent buys/withdrawals cannot overspend; delivery and refund cannot both mature; completed-sale replay cannot mint ledger credit; a lost relay response never causes a second payment; restored journals cannot resend old withdrawals; operator compensation never silently drains another customer; deep reorgs create visible cases rather than imaginary rollback of Monero.
## Primary sources and remaining evidence
- [Monero subaddresses](https://docs.getmonero.org/public-address/subaddress/) and [wallet RPC `create_address`](https://docs.getmonero.org/rpc-library/wallet-rpc/#create_address): address allocation/indexing, not an internal financial ledger.
- [Wallet-owned outputs](https://docs.getmonero.org/rpc-library/wallet-rpc/#incoming_transfers), [transfers](https://docs.getmonero.org/rpc-library/wallet-rpc/#get_transfers), [balances](https://docs.getmonero.org/rpc-library/wallet-rpc/#get_balance): output identity, subaddress association, synchronization, locking and balance observations. Exact production-version fields and stability must be fixture-tested.
- [Constructing transactions](https://docs.getmonero.org/rpc-library/wallet-rpc/#transfer), [relay](https://docs.getmonero.org/rpc-library/wallet-rpc/#relay_tx), [offline signing](https://docs.getmonero.org/rpc-library/wallet-rpc/#sign_transfer): preparation/signing/relay separation; signed payloads must be checked, protected and recovered.
- [Transfer history](https://docs.getmonero.org/rpc-library/wallet-rpc/#get_transfer_by_txid) and [rescan](https://docs.getmonero.org/rpc-library/wallet-rpc/#rescan_blockchain): wallet restore can lose outgoing destinations, transaction keys and notes. Blockchain replay is not a backup for customer accounting.
Source review: 2026-10-20; documentation is capability evidence, not an audited implementation of this design. No wallet/RPC credentials or funds were accessed.
**Actual mTLS rehearsal result:** against the authenticated official v0.18.5.4 binary in Docker `--network none` on offline Stagenet, the approved ephemeral client certificate succeeded, a CA-trusted but non-allowlisted certificate and a client without a certificate were rejected, and a forbidden transfer method was rejected before Wallet RPC. This is an actual protocol handshake and allowlist test in one isolated container, not production network isolation or certificate lifecycle proof. Gateway/app wiring, deployment firewall policies, cert rotation, deposit observation/crediting and any payment capability remain unimplemented/disabled.
**Actual RPC integration blocker:** The v0.18.5.4 process rehearsal confirmed a login-protected Wallet RPC returns HTTP 401 with a Digest challenge; Basic auth also returns 401. The app does not implement legacy MD5 Digest. New groundwork replaces that idea with a local TLS 1.3 mTLS gateway and a client transport that emits no Authorization header. The gateway binds only to an explicitly configured private IP (never a wildcard/public interface), authenticates an allowlisted client certificate, permits only schema-bounded address/observation methods, and forwards to a fixed loopback Wallet RPC upstream. Wallet RPC would run without its own HTTP login only inside that protected boundary. This gateway is not deployed or wired to the application. Its isolated end-to-end certificate handshake has now passed against the official Wallet RPC; intended-host/network isolation, certificate provisioning/rotation, and production configuration remain unverified. Do not enable Wallet RPC outside the tested disposable boundary until those deployment controls pass review.
**Signed deposit-address enrollment slice (2026-10-22):** a server-side service now validates a short-lived customer-wallet signature over mainnet network/chain, custodian, beneficiary, wallet-generation fingerprint, account index and request ID, then uses the existing durable reserve-before-RPC allocator and deterministic-label recovery to return that customer's registered subaddress. A dedicated allocator database role is separated from custody-runtime, observer and credit roles. Schema v8 adds a database trigger preventing that role from inserting an already-registered/payable address; registration must follow a reserved row. PostgreSQL integration tests exercise replay, beneficiary uniqueness, wallet identity, role boundaries, no financial journals and attempted trigger bypass. This service is **not yet wired to an HTTP route or UI**, all wallet tests use fake RPC, and no deposits, credits or withdrawals are enabled. Do not display addresses to users until the complete credit/withdrawal/recovery flow has been validated.
-64
View File
@@ -1,64 +0,0 @@
# Signed sale → PostgreSQL accounting rehearsal
Status: **disposable, synthetic evidence only; no live settlement or consensus activation**. Evidence: 2026-10-20. Related: [sale-lock candidate](sale-lock-candidate.md), [financial reconciliation](financial-reconciliation.md), [production plan](production-plan.md).
## What is integrated
[The replay bridge](../server/market/sale-rehearsal.ts) validates trader-signed candidate terms against an actual sandbox purchase reservation. [The PostgreSQL custody implementation](../server/market/postgres-custody.ts) can consume this evidence and atomically resolve its reserved balance. This exercises the real restricted runtime role, financial writer lock, journals, balance projection, listing/order/outbox updates and business audit—not an in-memory imitation of SQL accounting.
`observeSaleRehearsal()` is callable only on an instance explicitly opened with `disposableSaleRehearsal: true`, with `WIKIDECK_PG_DISPOSABLE_TEST=1`, a configured database named `custody_test`, and a matching actual connected database name. There is **no HTTP route, production environment enable switch, host signer, Monero adapter or public checkout integration**. These guards prevent accidental use; a database name/environment flag does not independently prove infrastructure isolation. The supplied test Compose deployment is disposable/internal/tmpfs, and must never contain funds or valuable assets.
The evidence supplies one synthetic seller-owned NFT seed and up to 128 candidate blocks, each containing at most 64 sale transactions. Replay uses the existing candidate state machine, signatures and depth rules. JSON traversal has collection/depth/node limits and a 256 KiB evidence ceiling. Seed, policy, host identity, signed windows and exact economics are bound on the first successful observation. Changing that binding is rejected; a different block history under the same binding can be observed to test reorg handling.
This seed is **caller-supplied**, not discovered in the live node. Blocks have **no RandomX proof, parent hashes, fork choice, issuance verification, peer validation or canonical event provenance**. Signed terms authorize the simulated transitions; signatures do not prove the chain is canonical or that real Monero backs the reservation.
## Exact authorization and financial behavior
- Both seller and buyer sign exact order/custodian/card/sequence, trading identities, host authority, candidate policy/domain, gross XMR amount, fee policy, recipient and admission/expiry heights. Existing sandbox reservation signatures alone are not candidate sale authorization.
- The signed hosting rate must equal the stored listing rate, even where two rates round to identical commissions on a tiny sale. The allocation and host recipient must match the reserved order/listing. All amounts remain canonical atomic-unit strings and `bigint`; there is no float or USD conversion.
- Optional hosting recipient terms use a tagged signature extension. Omission retains the earlier candidate message bytes. New drafts preserve the order's snapshotted recipient; changing current host policy does not redirect revenue. The candidate only checks address shape; actual custody policy/business audits additionally check Monero network and checksum.
- The reservation commitment binds the order's exact buyer/seller, card/sequence, gross and split amounts, author and hosting recipient, custodian and rehearsal binding. Completion must contain that commitment and the bound host's valid signature. There is no private key or automatic signature generation in the accounting implementation.
- Before maturity, gross remains in the buyer's reserved account. Once authorization has been bound, ordinary buyer `cancel-reservation` is denied, including through another ordinary custody instance. Synthetic mature terminal/non-admission evidence is required instead.
- Mature completion debits reserved gross and credits the seller's available balance, fixed author liability and snapshotted hosting revenue in one balanced transaction. Zero commission legs are omitted, not rounded up; a one-atomic sale still credits one atomic unit to the seller.
- Mature cancellation/expiry or the safe never-admitted boundary debits the reservation and returns gross to the buyer. There is no seller/fee credit or Monero transfer on this branch.
- Deterministic journal IDs plus the shared database writer lock prevent duplicate terminal postings across pools, replay and restart. An identical outcome returns `none` rather than posting again. Failure while storing terminal evidence rolls the entire financial mutation back.
## Evidence, audit and review
Namespaced insert-only metadata records retain each order's binding, **first** signed observation, terminal observation, per-order terminal index and (when there is an explicit terminal candidate transaction) candidate-tx-to-order index. Runtime has INSERT/SELECT but no UPDATE/DELETE privilege on these metadata records. Repeated observations do not create an unbounded transcript archive. Business audits replay signed retained evidence, check the exact listing rate and binding/state commitment, and compare terminal outcome, candidate transaction ID and indexes with the stored order and financial lifecycle.
The existing sandbox `mock-sale-settlement` journal and `fixture-complete`/`fixture:<state-root>` outbox format are reused deliberately. They remain **fixture** evidence, not a new assertion of canonical delivery. No schema migration or production evidence format is implied. Existing imported SQLite fixture settlements remain supported without being relabeled as signed rehearsals.
A submitted history that conflicts with, removes or makes immature an already posted outcome triggers `sale-rehearsal-outcome-reorg`. Business changes roll back, and a redacted durable integrity incident commits while retaining the shared writer lock. All custody instances then reject new mutations; private reads and original signed receipts remain available. The original seller credit/refund stays recorded: no automatic compensation, reversal or second payout. Re-submitting the old mature history cannot clear the incident. Existing schema-owner incident review procedures are not a substitute for resolving chain risk; production resolution requires retained canonical evidence and approved loss policy.
## Local canonical-event inbox foundation
The same explicitly disposable PostgreSQL instance now has `observeCanonicalEvents()` and `observeLedgerCanonicalEvents(ledger)`. The ledger adapter requires an actual in-process `Ledger` object, checks its network/chain identity, and fetches one page at a time from its locally validated [canonical event API](../server/testnet/canonical-index.ts)—no caller/HTTP/peer page can enter through that adapter. The inbox is append-only and bounded. It checks stream identity, page limits, predecessor anchors, event hashes, sequence continuity, connect parent/tip and tip-first disconnect rules against a reconstructed canonical hash stack. It accepts exact retries and overlapping pages from concurrent consumers only after matching their persisted overlap; stale retries report the durable cursor/head, not the stale page head. The startup/periodic financial audit replays and verifies the stored inbox; a changed stream, gap or malformed/tampered event creates the normal durable integrity hold. Inbox records use namespaced `custody_meta` keys and the existing runtime role; there is no schema migration or mutable cursor.
An opt-in `CanonicalObserver` now schedules one bounded poll cycle on the server runtime, resumes from its durable cursor after restart, and stops/drains before PostgreSQL and the ledger close. Each cycle processes at most four pages of 64 events; lag is exposed on the private operations listener. Poll failures or sale-review events stop the loop fail-closed; it does not retry a failed observer automatically. The runtime opt-in requires `WIKIDECK_CUSTODY_CANONICAL_REHEARSAL=1`, PostgreSQL custody and `WIKIDECK_PG_DISPOSABLE_TEST=1`; the configured and actual database must also be `custody_test`, and `NODE_ENV=production` is explicitly rejected. Invalid/missing combinations fail closed, including direct construction of the polling controller. Shutdown stops scheduling immediately and drains the current page before custody/ledger close. This is **not enabled in the persistent sandbox or any regular deployment** and has no public HTTP control endpoint.
PostgreSQL tests include synthetic event pages for malformed/retry cases, local `Ledger` blocks configured with a **test-only fake PoW engine** for equal-work side-branch/reorg transitions, and one separately mined and independently revalidated block using the **native RandomX engine** before its canonical event is consumed. This proves the real PoW validation → local event API → PostgreSQL inbox path for a single block; it does not establish production multi-node reliability or sale-candidate transaction support. Hash-anchor consistency is not proof of honest observation; the stream ID and unkeyed hashes are stored beside the events, so a schema owner able to coherently rewrite the complete history can also recompute the hashes. The included corruption test detects a partial edit, not a fully rewritten valid history. Production must anchor custody checkpoints outside the database's mutable trust domain. The disposable inbox is capped at 4,096 total events, stores the append-only event history and fully rescans it during audits. That is intentionally a small-fixture design, not production storage/cursor architecture or a scale claim.
The synthetic PostgreSQL event-page seam now links an explicitly terminal candidate transaction ID to its posted order. A later **submitted disconnect event** containing that exact ID commits both the canonical event page and a durable per-order `sale-reorg-review` record plus global `posted-sale-terminal-disconnected` mutation hold in one transaction; the original journal is not reversed or paid again. This remains true if the transaction reappears later in the same replacement-branch page: review does not auto-clear on apparent re-inclusion. Generic incident resolution re-audits the retained review record and therefore cannot clear it. This exercises order-to-event linkage and atomic review behavior. The hold only detects disconnects actually delivered to this seam; it cannot detect an unseen intermediate fork.
The local-ledger adapter is **not** linked to these terminal candidate IDs: active v6 blocks cannot contain candidate sale transactions, and local free transfers are not accepted as sale completion evidence. The adapter's integration test demonstrates canonical event ingestion/reorg only, not sale rollback handling. The terminal-link test supplies a synthetic canonical page under disposable-only guards. Production still requires the candidate transaction format in a separately reviewed/activated network, an actual local canonical feed containing those IDs, and per-order integration with durable node history. No production sale-observation guarantee is claimed.
## Validation and remaining gates
TypeScript/Vite Docker build passed; **172 offline regressions and 31 PostgreSQL integration tests passed, zero failures/skips**. [Candidate tests](../tests/sale-candidate.test.ts) cover signature compatibility/recipient tampering and candidate transition rules. [PostgreSQL tests](../tests/postgres/custody.test.ts) add:
- explicit instance/database consent and exact signed reservation matching;
- seed-binding changes, malformed/cyclic/oversized collections, and denial of ordinary cancellation after binding;
- immature completion hold, concurrent exactly-once seller/author/host credit, replay and reconnect;
- mature cancellation and never-admitted-lock refund boundaries;
- identical-rounded-allocation but different fee-rate rejection;
- one-atomic settlement and signed custom-recipient revenue across current-policy changes;
- conflicting outcome → durable cross-instance/restart hold without a second credit;
- anchored canonical-event connect/disconnect paging, overlapping/stale consumer retries, reconnect, partial history mutation audit, forged disconnect-ancestor rejection and tamper-triggered hold; actual native-RandomX block validation and event ingestion plus test-only fake-PoW excluded branch/reorg fixture (no active-chain candidate sale link);
- opt-in HTTP runtime startup, initial observer checkpoint, 64-event bounded catch-up, clean shutdown, durable restart resume and invalid-flag rejection;
- synthetic exact candidate-terminal transaction disconnect/reappearance in one page → committed event history plus order-linked durable hold, generic incident resolution denied, one preserved seller credit and no second payout;
- injected terminal-evidence failure → complete rollback and safe retry; corrupted evidence → audit hold.
A first bounded-checkpoint implementation attempted metadata UPDATE and was rejected by the real runtime grants. It was corrected to retain insert-only first/terminal evidence; no privilege was widened. Test evidence is for this implementation boundary, not production approval.
**M3 remains open.** Next work is independently reviewed protocol/policy and explicit new-network activation design, then actual PoW/peer/index/undo integration and durable canonical observation tied to financially fenced host-signing intent. The order-link detector is only exercised with synthetic page events until an activated candidate network can produce candidate IDs through the real local ledger. Monero deposit confirmation/unlock observation, treasury/signer separation, real withdrawal controls, coordinated recovery, capacity and legal/operational release gates remain separate. The active v6 chain still rejects every candidate sale transaction. Persistent local custody deployments were not switched or restarted by this rehearsal.
-48
View File
@@ -1,48 +0,0 @@
# Custodial business-liability reconciliation
Status: implemented PostgreSQL **sandbox** integrity checks; not external proof of Monero backing or production settlement acceptance. Related: [production plan](production-plan.md), [financial storage](postgres-financial-storage.md). Updated 2026-10-20.
## Why totals are insufficient
A balanced journal and matching account projections can coexist with a corrupted order: its buyer, amount, status or pending task may disagree with the funds actually reserved. Aggregate assets equalling liabilities alone cannot detect a substituted recipient or orphan task.
[Business integrity checks](../server/market/custody-integrity.ts) now validate both directions:
- Strict persisted listing/order/withdrawal encodings, indexed identity/status columns and JSON record agreement.
- Order card, seller, buyer, sequence, price and historical hosting recipient against the original listing; exact independently rounded seller/author/host allocation and fixed author policy. Current operator fee configuration never rewrites history.
- Each awaiting-lock order has its exact credit-normal purchase reservation; cancelled/fixture-settled orders have zero reservation. The actual reservation and terminal journal lines must match the expected lifecycle, accounts and amounts, not just net to zero.
- Each withdrawal hold equals recipient amount plus maximum approved fee. Prepared/complete fixture records require an attempt ID, unique transaction identity and fee within cap. Cancelled/complete holds are zero; terminal postings and returned unused fee allowance match exactly.
- Blocked/cancelled/prepared/completed outbox state and payload correspond to the business record. Imported SQLite fixture terminal evidence is recognized explicitly; no real NFT/Monero settlement is inferred.
- Reverse checks reject orphan reservation accounts, pending work and lifecycle postings, duplicate listing orders, and reused prepared attempt/transaction identities.
Reads use the caller's coherent transaction. Record batches use UUID keyset pagination, maximum 128 per batch, with no growing process-wide customer cache. A 15-second business-scan budget is checked between batches/queries; the existing per-query timeout can extend the final boundary. This bounds application memory and failure behavior, **not a production capacity claim**. Very large histories may require indexed normalized schemas, incremental auditing and a dedicated database connection/worker budget before release.
The existing exact journal/projection/backing audit remains, and now invokes these checks at startup, explicit audit, SQLite import validation and deployment checks. Targeted pre/post checks run inside order/withdrawal mutation transactions. No database schema version or old financial record is rewritten by this increment.
## Runtime scheduling and failure behavior
The PostgreSQL backend schedules one nonoverlapping audit every 60 seconds. Mutations are held if the latest audit failed or the last success is over 120 seconds old. A transient availability failure can recover after a successful later audit; it does not automatically classify customer behavior as fraud.
A confirmed integrity mismatch latches the detecting process and stores a redacted `integrity_incident_v1` record in custody metadata. Subsequent writers check that marker under the existing cross-process advisory lock. Startup refuses it. Private activity and original signed receipt replay remain available; no new posting, refund, cancellation or withdrawal reservation is allowed while integrity is uncertain. This is deliberately stricter than an ordinary market-disabled flag, which still permits normal resolution.
For a targeted write-path mismatch, a savepoint rolls back business work while retaining the writer lock; the incident is committed before another cooperating writer can proceed. A background/read-only audit or startup failure records its incident separately. **Process crash or database unavailability can prevent that marker from committing.** A redacted error explicitly requests fencing all writers if marker persistence fails. A periodic audit is not an atomic fraud-prevention barrier for every unrelated write, nor protection from a privileged operator or fully compromised application.
Private loopback operations now expose only backend, mutation/incident hold, audit timestamps, freshness and a stable failure code. No customer ID, order ID, address, SQL statement, balance or connection secret is attached. [Operations checks](../server/operations-check.ts) emit `custody-financial-review` and `custody-audit-stale` warnings. No new public admin or financial audit endpoint was added.
## Controlled resolution — never reset journals
1. Stop/fence all custody writers and preserve matching database/node evidence and backups. Diagnose privately; a public-facing error intentionally does not disclose the affected customer.
2. Have the responsible operator/reviewer establish the correct state from immutable receipts/journals, trusted backup evidence and any external effects. This increment supplies **no automatic repair, compensation, destructive reset or payout retry**. Repair/restore authorization is separate from acknowledging an incident.
3. Using the schema-owner credential, run the existing database CLI action `resolve-integrity EVIDENCE_UUID`. The UUID refers to the externally maintained reviewed incident case; the tool does not certify the truth of that case or supply a second human approval.
4. [Resolution code](../server/market/custody-incident.ts) takes the financial writer lock, verifies schema-owner membership, tentatively removes the unresolved marker and runs the full accounting/business audit in the same transaction. Failure rolls everything back, preserving the hold. Success appends a resolution record with evidence UUID, timestamp and incident digest; it changes no journal/account/business rows.
5. Restart previously latched instances only after controlled resolution, then verify successful startup/audit and operations state. A detecting instance stays locally held even after a successful later audit. The restricted runtime role cannot acknowledge incidents or delete the marker.
This process is intentionally not a “clear error” button. Manual SQL balance edits, deleting a marker outside the reviewed procedure, restoring stale isolated financial state or inventing journal resets can create duplicate payouts or loss of liabilities. An external database owner retains administrative power; independent evidence retention remains necessary.
## Evidence and limitations
Tests cover business-record corruptions that leave all journal totals balanced; bad allocations/fee metadata; missing/mismatched outbox; orphan reserves/tasks; targeted mutation rollback; durable cross-instance/startup holds; private reads/original replay during a hold; restricted-role resolution denial; failed-resolution rollback; successful reviewed acknowledgement plus restart; traversal beyond 128 records; and import of historical fixture completions/cancellations. No actual fund transfer, incident on deployed user data or consensus change was performed.
Final validation: TypeScript/Vite Docker build passed; **168 offline regression tests and 16 real-PostgreSQL integration tests passed**, zero failures/skips. The first corruption-test run exposed an unguarded chained amount refinement on malformed stored decimals; the parser was corrected to emit a redacted integrity incident and all suites were rerun. Deployed sandbox services were not recreated or subjected to deliberate corruption; new code takes effect only after the selected runtime image is rebuilt/recreated.
SQLite remains a disposable compatibility model with its original journal audit; this richer runtime checking is implemented in the PostgreSQL backend, including imported SQLite histories. Source-freeze/import procedures are unchanged. Production live-deposit attribution, treasury asset reconciliation, normalized financial states, compensation, observer/signing services, independent review and measured load/SLOs remain open. A successful internal audit is **not** proof of external XMR reserves, a guarantee of solvency, or launch permission.
+464
View File
@@ -0,0 +1,464 @@
# WikiDeck: Edit War — balance report
Owner: sim-balance (claude/wikideck#4). Harness: `shared/bots/`, `scripts/sim/` (PR #14).
## Report v1: 2026-11-17 00:45 EST
**Engine:** `night/2026-11-16` @ 482de6c/4a4941c (engine #25 and #27, keywords and Portals; card data #28).
**Bots:** view-only (`viewFor`); see Method.
**Card pool:** `docs/game/card-sample.json` (236 cards), derived per §1 with percentiles from the sample.
**Decks:** the 4 §2.1 starter decks, 4 "realistic owned" decks (12 random cards from the sample), and archetypes.
**Runs:**
- full field: 3,000 matches per ruleset (report mix, 4 workers; r350 is memory-limited tonight)
- focused starters + owned round robin: 2,000 matches per ruleset
- greedy lever sweeps: 2,000–3,000 per variant
## v1.1 re-run on the real engine hooks (00:31)
> **Seat figures are pre-#38.** Every first-player and seat number in this report was measured on an engine before #38, which removed `opponent.queuedCount` from `PlayerView`. The bots never read the queue split (`stateFromView` uses the total hand, and an invariance test covers it), so the effect should be nil. A re-run on the merged head is still the clean number, and it is open for v1.2.
**Engine:** `night/engine/v1-1` @ 4a0dbd0, with `RULESET_V1_1` (DESIGN #32): `viral {base 1, cap 3}`, `encyclopedic {sides 1}`, `rising.powerDelta -1`, `cultureKeyword: home`, `costThresholds [26,39,51,63,78]`. It is the same focused run as above: the §2.1 starters plus 4 owned decks (cost thresholds and Culture keyword per v1.1), 2,000 matches per ruleset.
| | v1 | **v1.1 (#32, exact)** | v1.1 + item 6 |
|---|---|---|---|
| starter deck WR, overall (FG / Head / Pio / Star) | 65 / 40 / 57 / 54 | **52 / 52 / 52 / 53** ✅ | 50 / 56 / 50 / 52 |
| starter pairings, min–max | 23–77% | 39–61% (only FG–Head 61%, n = 51, is outside 45–55) | 42–58% |
| owned vs starters (FG / Head / Pio / Star) | 37 / 54 / 40 / 41 | 51 / 42 / 47 / 43 | 51 / 41 / 46 / 48 |
| first player (pre-#38) | 53.4% | **51.2% [48.8–53.6]** ✅ | 51.0% [48.6–53.5] |
| decided in the first third | 4.1% | 3.3% | 4.1% |
| greedy > maxpower, lookahead-lite > greedy | 62%, 60% | 63%, 65% | 51%, 70% |
Net keyword value per card under the exact v1.1 (counterfactual trigger value plus `powerDelta`):
| keyword | v1.1 net per card |
|---|---|
| translated | **+1.64** |
| nostalgic | **+1.69** |
| viral | +1.15 (base included) |
| encyclopedic | +0.77 |
| rising | 1.71 − 1 = +0.71 |
| local | +0.69 |
My earlier flat-+1 stand-in for encyclopedic overstated it: the real hook is worth +0.77, not +1.23.
**Updated recommendation:**
1. **Ship #32 (v1.1) as it is.** Every starter's overall WR is 52–53% and first player is 51.2%. The one out-of-band pairing (FG vs Headliners at 61%) is within this run's noise.
2. **Item 6 is an optional v1.2 candidate.** `nostalgic` and `translated` at `powerDelta -1` would bring translated and nostalgic (about +1.65) in line with the others (0.7–1.15). It fixes FG vs Headliners (50%), but at n ≈ 55 per pairing it isn't clearly better overall (42–58% vs 39–61%). Decide it on a larger run.
3. **Owned vs starters is 42–51%:** roughly the variety-not-power goal, slightly weak against Headliners and Stargazers.
Raw tables:
#### `v1.1`: 2000 matches, 10 draws, 0 engine errors
- First player (turn-1 initiative), symmetric games: **51.2% [48.8–53.6] (n=1641)**
- Decided early: 3.3% of decisive games locked in during the first third, 12.1% by half-time
- Skill: greedy>maxpower 63.3% (n=147), lookahead-lite>greedy 64.6% (n=99), greedy>random 83.5% (n=103)
| starters (row vs col) | field-guide | headliners | pioneers | stargazers | vs all decks |
|---|---|---|---|---|---|
| field-guide | – | 61% (n=51) | 49% (n=53) | 56% (n=55) | 51.8% |
| headliners | 39% (n=51) | – | 44% (n=54) | 50% (n=54) | 52.1% |
| pioneers | 51% (n=53) | 56% (n=54) | – | 48% (n=58) | 52.3% |
| stargazers | 44% (n=55) | 50% (n=54) | 52% (n=58) | – | 53.2% |
| owned (random 12 from card-sample) vs | field-guide | headliners | pioneers | stargazers | all |
|---|---|---|---|---|---|
| owned-0 | 39% | 32% | 41% | 46% | 40.3% |
| owned-1 | 50% | 43% | 42% | 38% | 45.1% |
| owned-2 | 55% | 37% | 62% | 44% | 49.7% |
| owned-3 | 62% | 55% | 43% | 45% | 55.0% |
| **all owned** | **51%** (n=233) | **42%** (n=196) | **47%** (n=198) | **43%** (n=198) | |
| keyword | power per card | games decided by it | cards played |
|---|---|---|---|
| rising | +1.71 | 13.3% | 1503 |
| nostalgic | +1.69 | 13.4% | 1791 |
| translated | +1.64 | 17.8% | 4976 |
| viral | +1.15 | 7.3% | 1852 |
| encyclopedic | +0.77 | 6.2% | 2349 |
| local | +0.69 | 6.4% | 4052 |
#### `v1.1+item6`: 2000 matches, 9 draws, 0 engine errors
- First player (turn-1 initiative), symmetric games: **51.0% [48.6–53.5] (n=1640)**
- Decided early: 4.1% of decisive games locked in during the first third, 12.6% by half-time
- Skill: greedy>maxpower 51.0% (n=147), lookahead-lite>greedy 70.0% (n=100), greedy>random 82.7% (n=104)
| starters (row vs col) | field-guide | headliners | pioneers | stargazers | vs all decks |
|---|---|---|---|---|---|
| field-guide | – | 50% (n=52) | 50% (n=52) | 53% (n=55) | 49.7% |
| headliners | 50% (n=52) | – | 58% (n=55) | 48% (n=54) | 56.1% |
| pioneers | 50% (n=52) | 42% (n=55) | – | 42% (n=57) | 49.7% |
| stargazers | 47% (n=55) | 52% (n=54) | 58% (n=57) | – | 51.9% |
| owned (random 12 from card-sample) vs | field-guide | headliners | pioneers | stargazers | all |
|---|---|---|---|---|---|
| owned-0 | 48% | 41% | 50% | 39% | 47.1% |
| owned-1 | 41% | 44% | 47% | 52% | 47.2% |
| owned-2 | 57% | 36% | 38% | 51% | 48.8% |
| owned-3 | 60% | 41% | 49% | 49% | 49.4% |
| **all owned** | **51%** (n=233) | **41%** (n=197) | **46%** (n=200) | **48%** (n=198) | |
| keyword | power per card | games decided by it | cards played |
|---|---|---|---|
| rising | +1.72 | 14.2% | 1546 |
| translated | +1.69 | 17.0% | 4787 |
| nostalgic | +1.68 | 13.2% | 1709 |
| viral | +1.15 | 8.8% | 1924 |
| encyclopedic | +0.79 | 6.7% | 2403 |
| local | +0.70 | 6.7% | 4127 |
### TL;DR for the council (report v1, 00:25; see the v1.1 re-run above for the updated recommendation)
1. **Seat and initiative are fine (pre-#38):** 51.5% [49.6–53.5] for the turn-1 initiative holder (n = 2,421 symmetric games), and seat 0 51.2%. Draws are 0.4%. The tie-break (total power) decides 4.7% of games. *This full-field run started before the bot-side queue-count fix (PR #14); the effect is at most a 0.02 nudge to the heuristic. The focused starters run, after the fix, gives a borderline 53.4% [51.0–55.8] under v1 and **51.0% [48.6–53.4]** under the recommended v1.1. Initiative only matters through reveal order, and v1.1 removes most of the order-sensitive power.*
2. **Keyword values are lopsided, confirming the critic's figures within 0.2:**
| keyword | power per card |
|---|---|
| rising | +1.76 |
| translated | +1.53 |
| nostalgic | +1.45 |
| local | +0.65 |
| **viral** | **+0.19** |
| **encyclopedic** | **+0.19** |
Values are counterfactual replays. viral and encyclopedic are dead: raising viral to amount 2 / cap 3 only reached +0.24, and encyclopedic amount 3 only +0.33. **Their conditions are the problem, not their numbers.**
3. **The starter decks are not 45–55% in v1:** pairings run 23–77%. Field Guide (rising + nostalgic) wins 65% overall and Headliners (local + viral) 40%. **With v1.1 items 1–6, every pairing is 45–55%.**
4. **Owned decks lose to the starters**, because they are about 51% viral and squashed into cost 2–4. That is the wrong way round for "NFTs give variety, not power".
5. **`costThresholds` squash fame.** The owned cost mix is 3/23/37/22/10/5. `[26,39,51,63,78]` gives 13/20/22/20/15/10, which hits the target and confirms the critic and designer-a.
6. **Pure extremes are dead under every lever:** heavy (cost 5–6 only) at 15%, swarm (cost ≤ 2) at 2%. Top-heavy (curve 1/1/2/2/3/3) is **57%**, so the §8 top-heavy retarget (≥ 40%) **passes**. Swarm and heavy aren't fixable without breaking curve decks: every lever that helps one hurts the other (sweep below). Treat them as non-decks.
7. **Matches are always 6 turns.** Only 6.5% of decisive games are decided in the first third, and 19.9% by half-time, so most games stay live to the end.
8. **Skill expression is healthy:**
- greedy beats maxpower ("always play the biggest card") 59.5%. §8 wants the naive line under 55% against a smart bot; it is at 40.5%.
- lookahead-lite beats greedy 63.7%.
- greedy beats random 77.5%.
### Proposed v1.1 rule changes (concrete)
| # | Change | Evidence | Status |
|---|---|---|---|
| 1 | `costThresholds: [26, 39, 51, 63, 78]` (designer-a's quantile rule) | owned cost mix 3/23/37/22/10/5 → 13/20/22/20/15/10 | **adopt** |
| 2 | `rising.powerDelta: -1` | rising +1.76 per card, the top keyword | **adopt** |
| 3 | viral: "+1, plus +1 per earlier reveal this turn, max +3" (critic) | viral +0.19; buffing amount/cap alone gives +0.24 | **adopt.** It needs the base +1. |
| 4 | encyclopedic: "+2 if *you* have no other cards here" (critic) | +0.19; amount 3 alone gives +0.33 | **adopt.** It needs the condition change. |
| 5 | Culture takes its home-stat keyword (critic) | owned decks drop from 51% viral to 18% | see the v1.1 results |
| 6 | `nostalgic.powerDelta -1`, `translated.powerDelta -1` | +1.45 / +1.53 per card, close to rising. Without them Field Guide beats Headliners 60% under 1–5 (approximated hooks). | **optional, v1.2**: see the v1.1 re-run above |
| 7 | No change for heavy or swarm | no lever fixes both | – |
| 8 | No change for seat or initiative | 48–52% target met | – |
### Starter round robin and owned vs starters (focused run: §2.1 starters plus 4 owned decks, 2,000 matches per ruleset)
| | v1 | v1.1 critic package (1–5) | **v1.1 critic + item 6** |
|---|---|---|---|
| starter pairings, min–max | **23–77%** | 40–60% | **45–55%** ✅ |
| starter deck WR (FG / Head / Pio / Star) | 65 / 40 / 57 / 54 | 50 / 48 / 54 / 54 | 51 / 55 / 52 / 52 |
| owned vs starters (FG / Head / Pio / Star) | 37 / 54 / 40 / 41 | 52 / 45 / 46 / 43 | 50 / 40 / 46 / 47 |
| first player (turn-1 initiative) | 53.4% [51.0–55.8] | 52.5% [50.1–54.9] | **51.0% [48.6–53.4]** ✅ |
| lookahead-lite > greedy | 60% | 70% | 66% |
Each starter pairing has about 50–58 symmetric games (±13 pp at 95%). Each owned-vs-starter cell has about 200 games (±7 pp).
**Net keyword value under v1.1** (counterfactual trigger value per card, plus `powerDelta`), from the 3,000-match critic-package full field:
| keyword | v1.1 net per card |
|---|---|
| rising | 1.74 − 1 = **+0.74** |
| viral | 0.16 + 1 = **+1.16** |
| encyclopedic | ≈ 0.23 + 1 = **+1.23** (approximated) |
| translated | +1.59, or **+0.59** with item 6 |
| nostalgic | +1.58, or **+0.58** with item 6 |
| local | **+0.66** |
So every keyword lands within 0.6–1.2. This matches the critic's numbers (viral +1.15, encyclopedic +0.9, rising +0.9) to within 0.35.
**Recommendation: ship items 1–5 plus item 6** (`nostalgic.powerDelta -1`, `translated.powerDelta -1`). Without item 6, Field Guide still beats Headliners 60% and Headliners sits at 40–41% against every starter. With it, every pairing is inside 45–55. Owned decks then win 40–50% against the starters: the variety-not-power goal, slightly on the weak side. If v1.2 wants owned decks a bit stronger, the next lever is `local.amount 2` (Headliners and owned decks are about 25% local).
Raw tables:
#### `v1` (DEFAULT_RULESET), focused: 2000 matches, 9 draws, 0 engine errors
- First player (turn-1 initiative), symmetric games: **53.4% [51.0–55.8] (n=1641)**
- Decided early: 4.1% of decisive games locked in during the first third, 15.5% by half-time
- Skill: greedy>maxpower 61.6% (n=146), lookahead-lite>greedy 60.0% (n=100), greedy>random 81.7% (n=104)
| starters (row vs col) | field-guide | headliners | pioneers | stargazers | vs all decks |
|---|---|---|---|---|---|
| field-guide | – | 77% (n=52) | 57% (n=53) | 69% (n=54) | 64.8% |
| headliners | 23% (n=52) | – | 36% (n=56) | 35% (n=54) | 39.6% |
| pioneers | 43% (n=53) | 64% (n=56) | – | 52% (n=58) | 56.9% |
| stargazers | 31% (n=54) | 65% (n=54) | 48% (n=58) | – | 54.3% |
| owned (random 12 from card-sample) vs | field-guide | headliners | pioneers | stargazers | all |
|---|---|---|---|---|---|
| owned-0 | 42% | 48% | 35% | 37% | 40.0% |
| owned-1 | 26% | 62% | 40% | 45% | 47.4% |
| owned-2 | 45% | 57% | 44% | 43% | 52.7% |
| owned-3 | 35% | 47% | 40% | 37% | 42.3% |
| **all owned** | **37%** (n=233) | **54%** (n=197) | **40%** (n=200) | **41%** (n=197) | |
| keyword | power per card | games decided by it | cards played |
|---|---|---|---|
| rising | +1.75 | 12.0% | 1822 |
| translated | +1.55 | 18.6% | 2263 |
| nostalgic | +1.54 | 10.3% | 2197 |
| local | +0.71 | 6.2% | 4300 |
| viral | +0.22 | 3.3% | 6034 |
| encyclopedic | +0.17 | 0.8% | 1042 |
#### `v1.1-critic`: 2000 matches, 4 draws, 0 engine errors
- First player (turn-1 initiative), symmetric games: **52.5% [50.1–54.9] (n=1646)**
- Decided early: 3.5% of decisive games locked in during the first third, 11.4% by half-time
- Skill: greedy>maxpower 59.6% (n=146), lookahead-lite>greedy 70.0% (n=100), greedy>random 80.8% (n=104)
| starters (row vs col) | field-guide | headliners | pioneers | stargazers | vs all decks |
|---|---|---|---|---|---|
| field-guide | – | 60% (n=52) | 51% (n=53) | 51% (n=55) | 50.1% |
| headliners | 40% (n=52) | – | 41% (n=56) | 41% (n=54) | 48.3% |
| pioneers | 49% (n=53) | 59% (n=56) | – | 55% (n=58) | 54.2% |
| stargazers | 49% (n=55) | 59% (n=54) | 45% (n=58) | – | 54.1% |
| owned (random 12 from card-sample) vs | field-guide | headliners | pioneers | stargazers | all |
|---|---|---|---|---|---|
| owned-0 | 46% | 43% | 46% | 49% | 43.8% |
| owned-1 | 50% | 43% | 40% | 34% | 44.1% |
| owned-2 | 52% | 47% | 56% | 51% | 52.7% |
| owned-3 | 63% | 49% | 43% | 42% | 52.4% |
| **all owned** | **52%** (n=233) | **45%** (n=198) | **46%** (n=198) | **43%** (n=199) | |
| keyword | power per card | games decided by it | cards played |
|---|---|---|---|
| rising | +1.71 | 12.8% | 1505 |
| nostalgic | +1.68 | 13.6% | 1789 |
| translated | +1.64 | 17.6% | 4491 |
| local | +0.70 | 6.3% | 4081 |
| encyclopedic | +0.21 | 1.7% | 2177 |
| viral | +0.13 | 0.9% | 2524 |
#### `v1.1-critic-nerf`: 2000 matches, 14 draws, 0 engine errors
- First player (turn-1 initiative), symmetric games: **51.0% [48.6–53.4] (n=1636)**
- Decided early: 4.0% of decisive games locked in during the first third, 12.7% by half-time
- Skill: greedy>maxpower 58.2% (n=146), lookahead-lite>greedy 66.0% (n=100), greedy>random 79.8% (n=104)
| starters (row vs col) | field-guide | headliners | pioneers | stargazers | vs all decks |
|---|---|---|---|---|---|
| field-guide | – | 49% (n=51) | 50% (n=52) | 55% (n=55) | 50.6% |
| headliners | 51% (n=51) | – | 50% (n=54) | 46% (n=54) | 55.3% |
| pioneers | 50% (n=52) | 50% (n=54) | – | 47% (n=58) | 51.8% |
| stargazers | 45% (n=55) | 54% (n=54) | 53% (n=58) | – | 51.9% |
| owned (random 12 from card-sample) vs | field-guide | headliners | pioneers | stargazers | all |
|---|---|---|---|---|---|
| owned-0 | 51% | 43% | 52% | 46% | 46.0% |
| owned-1 | 40% | 35% | 47% | 33% | 43.1% |
| owned-2 | 52% | 42% | 37% | 56% | 51.1% |
| owned-3 | 58% | 38% | 47% | 55% | 50.1% |
| **all owned** | **50%** (n=231) | **40%** (n=197) | **46%** (n=199) | **47%** (n=197) | |
| keyword | power per card | games decided by it | cards played |
|---|---|---|---|
| rising | +1.72 | 15.6% | 1534 |
| translated | +1.69 | 16.3% | 4315 |
| nostalgic | +1.66 | 13.3% | 1686 |
| local | +0.71 | 6.4% | 4113 |
| encyclopedic | +0.21 | 1.8% | 2221 |
| viral | +0.13 | 0.7% | 2571 |
#### Critic package, full field (3,000 matches)
#### `v1.1-critic`: 3000 matches, 14 draws, 0 engine errors
- First player (turn-1 initiative), symmetric games: **49.7% [47.7–51.7] (n=2418)**
- Decided early: 8.0% of decisive games locked in during the first third, 17.9% by half-time
- Skill: greedy>maxpower 54.6% (n=238), lookahead-lite>greedy 62.7% (n=161), greedy>random 84.0% (n=169)
| starters (row vs col) | field-guide | headliners | pioneers | stargazers | vs all decks |
|---|---|---|---|---|---|
| field-guide | – | 38% (n=8) | 50% (n=8) | 29% (n=7) | 60.6% |
| headliners | 62% (n=8) | – | 36% (n=11) | 56% (n=9) | 46.8% |
| pioneers | 50% (n=8) | 64% (n=11) | – | 50% (n=12) | 59.7% |
| stargazers | 71% (n=7) | 44% (n=9) | 50% (n=12) | – | 64.8% |
| owned (random 12 from card-sample) vs | field-guide | headliners | pioneers | stargazers | all |
|---|---|---|---|---|---|
| owned-0 | 33% | 64% | 36% | 50% | 55.3% |
| owned-1 | 50% | 50% | 33% | 43% | 54.9% |
| owned-2 | 55% | 58% | 27% | 42% | 52.7% |
| owned-3 | 11% | 42% | 9% | 50% | 52.8% |
| **all owned** | **38%** (n=37) | **54%** (n=41) | **26%** (n=39) | **46%** (n=37) | |
| archetype | WR vs other decks |
|---|---|
| curve | 58.6% [51.7–65.2] (n=203) |
| top-heavy | 52.2% [45.4–58.9] (n=205) |
| heavy | 23.4% [18.1–29.7] (n=205) |
| swarm | 0.9% [0.2–3.3] (n=220) |
| mono-Culture | 55.4% [48.9–61.6] (n=233) |
| mono-People | 47.5% [41.0–54.1] (n=221) |
| mono-Nature | 40.3% [34.0–46.9] (n=216) |
| keyword | power per card | games decided by it | cards played |
|---|---|---|---|
| rising | +1.74 | 21.1% | 3184 |
| translated | +1.59 | 15.8% | 3450 |
| nostalgic | +1.58 | 19.7% | 2871 |
| local | +0.66 | 7.5% | 4696 |
| encyclopedic | +0.23 | 2.0% | 4548 |
| viral | +0.16 | 1.5% | 4733 |
### v1 full-field detail
#### `v1` (DEFAULT_RULESET): 3000 matches, 13 draws, 0 engine errors
- First player (turn-1 initiative), symmetric games: **51.5% [49.6–53.5] (n=2421)**
- Decided early: 6.5% of decisive games locked in during the first third, 19.9% by half-time
- Skill: greedy>maxpower 59.5% (n=237), lookahead-lite>greedy 63.7% (n=160), greedy>random 77.5% (n=169)
| starters (row vs col) | field-guide | headliners | pioneers | stargazers | vs all decks |
|---|---|---|---|---|---|
| field-guide | – | 70% (n=10) | 57% (n=7) | 83% (n=6) | 67.4% |
| headliners | 30% (n=10) | – | 33% (n=12) | 56% (n=9) | 51.7% |
| pioneers | 43% (n=7) | 67% (n=12) | – | 64% (n=14) | 67.0% |
| stargazers | 17% (n=6) | 44% (n=9) | 36% (n=14) | – | 53.3% |
| owned (random 12 from card-sample) vs | field-guide | headliners | pioneers | stargazers | all |
|---|---|---|---|---|---|
| owned-0 | 29% | 40% | 15% | 58% | 51.0% |
| owned-1 | 33% | 33% | 67% | 56% | 51.6% |
| owned-2 | 27% | 62% | 62% | 25% | 59.7% |
| owned-3 | 43% | 50% | 56% | 70% | 57.7% |
| **all owned** | **31%** (n=42) | **48%** (n=48) | **44%** (n=36) | **51%** (n=43) | |
| archetype | WR vs other decks |
|---|---|
| curve | 50.0% [43.5–56.5] (n=222) |
| top-heavy | 56.8% [50.2–63.1] (n=222) |
| heavy | 15.3% [11.0–20.9] (n=203) |
| swarm | 2.0% [0.9–4.6] (n=250) |
| mono-Culture | 42.2% [35.7–48.9] (n=211) |
| mono-People | 51.7% [44.9–58.4] (n=207) |
| mono-Nature | 56.0% [49.6–62.3] (n=232) |
| keyword | power per card | games decided by it | cards played |
|---|---|---|---|
| rising | +1.76 | 15.6% | 4027 |
| translated | +1.53 | 17.5% | 1266 |
| nostalgic | +1.45 | 16.4% | 3610 |
| local | +0.65 | 6.1% | 6781 |
| viral | +0.19 | 2.3% | 8030 |
| encyclopedic | +0.19 | 1.4% | 1002 |
*Starter-vs-starter cells here have small n; the focused round robin above has the real numbers. Keyword table: counterfactual trigger value per card (excluding any powerDelta).*
### Lever sweeps (greedy mirrors, real pool)
Before keywords were implemented (engine core @ c938407), I swept these levers. Each row is 3,000 greedy-mirror games. Columns are win rate vs the other decks.
| variant | heavy | swarm | curve | first player |
|---|---|---|---|---|
| v1 | 11.9% | 0.9% | 64.5% | 50.5% |
| `energyCarryMax 2` | 17.8% | 0.9% | 59.3% | 51.0% |
| `energyByTurn [2..7]` | **42.4%** | 0.0% | 41.3% | 49.7% |
| `powerByCost [0,2,3,4,6,8,10]` | 8.1% | 13.4% | 65.6% | 49.3% |
| `powerByCost [0,2,4,5,7,8,10]` | 0.3% | **36.1%** | 62.1% | 49.7% |
| `laneCapacity 4` | 10.3% | 0.6% | 63.6% | 50.7% |
| `onTopicBonus [0,2,2,2,2,3,3]` | 10.2% | 6.8% | 62.2% | 49.7% |
**Reading:** energy 2→7 rescues heavy but kills swarm and curve, and flatter power rescues swarm but kills heavy. Neither helps the normal decks. Keep v1's curve.
### Caveats
- Bots aren't people. Greedy doesn't plan energy carry and queues one card at a time; lookahead-lite is shallow.
- Hidden cards in determinizations are sampled from the loaner pool, not from the opponent's real decklist.
- Some critic-package items need engine hooks that don't exist yet, so this run approximates them:
| item | modelled as | exact? |
|---|---|---|
| viral base +1 | `powerDelta +1` | yes |
| encyclopedic "your side only" | `powerDelta +1`, about the critic's measured +0.9 | no: an approximation until engine-b adds `encyclopedic {sides 1}` |
`powerDelta > 0` is a sim stand-in: the engine's derivation clamps `powerDelta` to [−3, 0].
- Owned decks are 4 random 12-card draws, not curated. They have no curve fill, so some are lopsided.
## Method
**Engine.** Every match runs on the real rules engine (`shared/game`, public `index.ts` API only), through
`shared/bots/game-adapter.ts`. Nothing in the sim re-implements rules. The engine commit is named in each
results section.
**Bots** (`shared/bots/index.ts`, each a pure `(state, player, rng) => action`):
- `random`: a uniformly random legal play or commit.
- `maxpower`: always queues the highest printed-power card it can afford, in a random legal lane. This is the
DESIGN §8 "always play the highest-power card" line.
- `greedy`: one-ply. It takes the action whose result scores best on a lane heuristic: a soft lead per Topic
plus total power. The heuristic sees the bot's own queued plays and the opponent's *revealed* cards only.
- `lookahead-lite` / `lookahead`: flat Monte Carlo over the top 3–4 greedy candidates, with 4–8 rollouts
each. Before each rollout, the opponent's queued plays are taken back and its hand and deck reshuffled
(determinization), so the bot never reads hidden information.
**Seats.** Plans are simultaneous: seat 0 queues and commits, then seat 1. Neither bot can see the other's
queue, so the order leaks nothing. "First player" means the seat with **initiative on turn 1**.
**Schedule.** Per ruleset, matches are drawn from a fixed mix of bot pairings with random seats:
| pairing | share | used for |
|---|---|---|
| greedy vs greedy | 55% | balance (decks, cards, keywords, first player) |
| lookahead-lite vs lookahead-lite | 12% | balance with a stronger player |
| random vs random | 5% | baseline |
| greedy vs lookahead-lite, maxpower vs lookahead-lite, maxpower vs greedy, random vs greedy | 28% | skill expression |
Deck, card and keyword statistics use only **bot-symmetric** games (the same bot on both seats). Deck pairs are
drawn uniformly, mirrors included; the per-deck win rate excludes mirrors. `--mix fast` (greedy only) is used for
quick lever sweeps.
**Decks.** These are built from a card pool by `defaultDecks()`:
- 6 seeded starter decks (`starterDeck`)
- `curve` (cost counts 2/3/3/2/1/1)
- `top-heavy` (1/1/2/2/3/3)
- `heavy` (cost 5–6 first: the §8 "all-famous" line)
- `swarm` (cost ≤ 2 first)
- `mono-<faction>` curve decks for factions with ≥ 6 cards
- `kw-<keyword>` curve decks for keywords on ≥ 3 cards
The pool is the engine's preview pool, or council-data's `card-sample.json` derived per DESIGN §1
(percentile → fame → cost, home stat, faction keyword). Loaner power always follows the ruleset's
`powerByCost`.
**Metrics.**
- Win rates with Wilson 95% intervals. **↑/↓** marks an interval that excludes 50%.
- First-player WR: initiative holder on turn 1, symmetric games.
- Match length in turns.
- "Decided early": the turn from which the eventual winner led on the heuristic until the end, as a fraction of
the match.
- Per-card WR: the win rate of the side that played the card.
- Per-stat correlations.
- **Keyword value:** a counterfactual. Each finished match is replayed with the same actions and the keyword
removed from one side. We report the side's lost total power per keyword card, and how often removing the
keyword made the result worse for that side ("games decided by it"). DESIGN §10.1 asks for
`keywordParams.<id>.powerDelta` when a keyword is worth more than about 1 power.
**Reproduce.**
```
SIM_POOL=docs/game/card-sample.json SIM_RULESETS=scripts/sim/variants/v1.json \
npx tsx scripts/sim/run.ts --engine game --matches 5000 --workers 10 --out sim-out
python3 scripts/sim/summary.py sim-out
```
**Limits.**
- Bots are not humans. Greedy undervalues saving energy and bluffing.
- Lookahead rollouts are short.
- Deck archetypes are built automatically, not tuned by hand.
- The 100-card sample is skewed: Culture 53, People 30, Nature 9, History 5, Science 3, Space 0.
+149
View File
@@ -0,0 +1,149 @@
# Card data: real stat distributions (council-data)
Status: **final for tonight**, 236 fully enriched cards, generated 2026-11-16 23:20 EST. Sampling stopped early on night-lead's request because Wikimedia was rate-limiting (429) our shared egress IP. 330 cards were picked; the first 236 finished enrichment.
**Method:** `scripts/night/card_sample.py` draws random ns0 articles in batches of 20 and keeps those that pass the `server/wiki.ts` filter: a thumbnail from upload/thumb.wikimedia.org and an intro extract of at least 40 characters. About 44% of random pages pass. Each card is enriched with the same API parameters as `server/enrichment.ts`:
- six completed months, Jun–Oct 2026; attention uses October
- monthly views summed from the daily REST pageviews
On top of that it adds Wikidata P31 and a 30-day drift (views 10-17..11-15 vs 09-17..10-16).
**Politeness:** the sampler runs serially at 1 request a second or slower, honours Retry-After, and caches every response to disk. `scripts/night/card_analyze.py` produces everything below, plus the `percentiles` (99 cut points each, for DESIGN §1.1) in `card-sample.json`.
## Files
- `card-sample.json`: `cards[]` with the `PageEnrichment` shape, plus `category` (legacy `category()`), `instanceOf` (P31), `faction` (the P31 rules below), `tiers` and `drift30`. Top level: `percentiles`, `tierBreakpoints`, `factionRules` and `note`.
- `starter-cards.json`: the loaner **pool**, 20 real frozen snapshots (a `MintStatsSnapshot` in `snapshot`). It also holds `starterDeckPageIds`: the 48 DESIGN §2.1 starter titles with their real pageIds and `cardId`s.
## Headline findings (236 cards)
1. **Raw scores are compressed.**
| score | median | p10–p90 | max |
|---|---|---|---|
| attention | 32 | 20–53 | 77 |
| depth | 63 | 54–73 | 87 |
| reach | 20 | 0–45 | 70 |
No honest card reaches 100. Use `percentiles` (§1.1) or the 1–10 tiers, never the raw 0–100 values.
2. **Correlations (Spearman):**
- attention and depth: 0.61, so these two double-count fame
- reach is nearly independent of both (0.17 with attention, 0.02 with depth)
3. **Reach has a hard floor:** 18% of cards (42) have 0 other languages, so reach is 0. Under the §1.1 counting, all of them get pct_reach of about 8.
4. **Raw values are long-tailed:**
| value | median | p90 | max |
|---|---|---|---|
| monthly views | 82 | 1,576 | 42k |
| pageBytes | 6.1 KB | 24 KB | |
| languageCount | 3 | 22 | |
5. **Trend is mostly down:**
- 65% of cards have a negative trendPercent, 34% positive; median −9.5%
- 16% swing by more than 50% either way
- null: 1%
6. **Live drift is small in score terms.** The 30-day median |pageview drift| is 22% (p90 60%). That moves attention by only **1.7 points** (p90 6.3), so at-mint and live values differ little unless someone inflates them.
7. **The legacy `category()` split is very skewed:**
| category | share |
|---|---|
| Culture | 56% |
| People | 26% |
| Nature | 8% |
| History | 8% |
| Science | 1% |
| Space | 0.4% |
8. **Candidate factions from P31:**
| faction | share |
|---|---|
| People | 29% |
| Places | 20% |
| Nature | 8% |
| Structures | 7% |
| Works | 5% |
| Events | 5% |
| Organisations | 4% |
| Ideas & Tech | 3% |
| Sport | 3% |
| unclassified | 14% |
Suggested 6 for v2: People, Places, Nature, Works & Culture (Works + Organisations + Sport), Structures, Events & Ideas, plus a neutral fallback.
## Full tables
Sample: **236 cards**; ~44% (149/340 logged during sampling) of random pages pass the illustrated filter. Pageviews available for 236.
| stat | n | min | p10 | p25 | median | p75 | p90 | max | mean | skew |
|---|---|---|---|---|---|---|---|---|---|---|
| attention | 236 | 13 | 20 | 25 | 32 | 41 | 53 | 77 | 35 | 0.78 |
| depth | 236 | 48 | 54 | 58 | 63 | 68 | 73 | 87 | 64 | 0.42 |
| reach | 236 | 0 | 0 | 10 | 20 | 33 | 45 | 70 | 23 | 0.36 |
| pageBytes | 236 | 772 | 1847 | 3084 | 6110 | 12805 | 24412 | 168332 | 11691 | 4.61 |
| languageCount | 236 | 0 | 0 | 1 | 3 | 9 | 22 | 124 | 8 | 4.14 |
| monthlyViews | 236 | 5 | 16 | 30 | 82 | 300 | 1576 | 42025 | 812 | 9.82 |
| dailyAverage | 236 | 0.2 | 0.5 | 1.0 | 2.6 | 9.7 | 50.8 | 1355.6 | 26.2 | 9.82 |
| trendPercent | 234 | -86.6 | -49.3 | -26.3 | -9.5 | 5.3 | 31.2 | 388.9 | -3.6 | 4.11 |
| drift30Percent | 235 | -94.7 | -58.2 | -33.8 | -12.9 | 1.0 | 27.7 | 2268.7 | -4.2 | 14.07 |
**Spearman rank correlations** (cards with pageviews):
| | attention | depth | reach | trendPercent | drift30Percent |
|---|---|---|---|---|---|
| attention | 1.00 | 0.61 | 0.17 | 0.35 | 0.33 |
| depth | 0.61 | 1.00 | 0.02 | 0.15 | 0.14 |
| reach | 0.17 | 0.02 | 1.00 | 0.00 | 0.09 |
| trendPercent | 0.35 | 0.15 | 0.00 | 1.00 | 0.31 |
| drift30Percent | 0.33 | 0.14 | 0.09 | 0.31 | 1.00 |
(n=234; attention~monthlyViews, depth~pageBytes, reach~languageCount are monotonic so their rank correlations are identical.)
**trendPercent sign:** positive 79 (34%), negative 153 (65%), zero 2; null (prior month 0 or no views) 2. |trend| > 50%: 38; > 100%: 7.
**30-day drift** (views 10-17..11-15 vs 09-17..10-16): median |drift| 22%, p90 |drift| 60%. Attention score change implied: median 1.7 points, p90 6.3 points.
**attention histogram (deciles 0-9,10-19..90-100):** 0 19 74 74 36 20 12 1 0 0
**depth histogram (deciles 0-9,10-19..90-100):** 0 0 0 0 2 72 117 38 7 0
**reach histogram (deciles 0-9,10-19..90-100):** 42 60 53 43 21 15 1 1 0 0
Reach = 0 (no other languages): 42; reach 100 (>=999 langs) impossible in practice, max langs 124. Attention null: 0; attention 0: 0.
**Sum of three stats:** min 73, p10 89, p25 102, median 116, p75 135, p90 156, max 222
**Legacy `category()` (server/wiki.ts):** Culture 133, People 62, Nature 19, History 18, Science 3, Space 1
**Top Wikidata P31 classes:** human 64, taxon 16, village 7, commune of France 6, river 5, human settlement 4, musical group 3, building 3, gene 3, village of Poland 2, civil parish 2, protest 2, legislative election 2, castle 2, events in a specific year or time period 2, township of Pennsylvania 2, film 2, company 2, island 2, rural municipality of Austria 1, municipality of Austria 1, municipality of Brazil 1, television film 1, nor'easter 1, rail company (Japan) 1, municipality 1, association football match 1, final 1, local government area of Victoria 1, plant disease 1, basketball team season 1, mosque 1, functional programming language 1, purely functional programming language 1, dependently typed programming language 1, programming language 1, free software 1, proof assistant 1, municipality of Croatia 1, municipality of Bangladesh 1
No Wikidata item: 0; no P31: 13
**Most frequent category words (cards containing):** stubs 81, births 55, people 50, from 50, century 46, living 33, geography 30, american 29, deaths 28, united 27, county 27, states 23, established 21, establishments 20, alumni 18, places 17, university 16, buildings 16, state 15, national 14, structures 14, male 13, players 12, district 11, villages 11, sportsmen 11, members 11, described 10, football 10, sports 10, city 10, film 10, british 9, companies 9, populated 9, sportspeople 9, biography 9, york 9, women 8, taxa 8, germany 8, politicians 8, television 7, writers 7, french 7, genera 7, based 7, communes 7, language 7, expatriate 7, named 7, olympics 7, completed 7, historic 7, register 7, faculty 6, pennsylvania 6, civil 6, history 6, california 6
## Rank-normalised tiers (1–10)
Tier = 1 + number of breakpoints the score is **>=**. Breakpoints are the sample deciles p10..p90 of the 0–100 score. Ties make some tiers thin (scores are integers).
| stat | p10 | p20 | p30 | p40 | p50 | p60 | p70 | p80 | p90 |
|---|---|---|---|---|---|---|---|---|---|
| attention | 20 | 24 | 27 | 30 | 32 | 35 | 39 | 44 | 53 |
| depth | 54 | 57 | 59 | 61 | 63 | 65 | 67 | 69 | 73 |
| reach | 0 | 10 | 10 | 16 | 20 | 26 | 30 | 36 | 45 |
Resulting tier counts — attention: None:0 1:19 2:27 3:24 4:23 5:23 6:17 7:28 8:25 9:22 10:28
; depth: 1:14 2:23 3:26 4:21 5:25 6:26 7:22 8:21 9:30 10:28
; reach: 1:0 2:42 3:0 4:30 5:30 6:32 7:21 8:27 9:27 10:27
## Candidate factions (Wikidata P31 rules)
| faction | n | share | median attention | median depth | median reach | example |
|---|---|---|---|---|---|---|
| People | 68 | 29% | 31 | 65 | 22 | Salahuddin of Aceh |
| Places | 48 | 20% | 28 | 61 | 32 | St. Georgen am Längsee |
| Other | 34 | 14% | 40 | 65 | 16 | Village (Pennsylvania) |
| Nature | 20 | 8% | 30 | 56 | 29 | Dichromorpha viridis |
| Structures | 17 | 7% | 26 | 57 | 10 | Pathrail Mosque |
| Works | 12 | 5% | 36 | 63 | 13 | The Best of Men |
| Events | 12 | 5% | 40 | 72 | 13 | April 2021 nor'easter |
| Organisations | 10 | 4% | 48 | 68 | 10 | Hiroshima Electric Railway |
| Ideas & Tech | 8 | 3% | 30 | 63 | 16 | Agda (programming language) |
| Sport | 7 | 3% | 27 | 70 | 16 | 1912 Argentine Primera División final |
Unclassified P31 labels: typeface 1, annexation 1, position 1, family 1, historic site 1, automobile manufacturer 1, historical society 1, stock character 1, pigeon breed 1, shopping center 1, Wikimedia list article 1, clinical sign 1, tram route 1, rubber-tyred tram 1, oil refinery 1, waterfall 1, orisha 1, water deity 1, Loa 1, arch 1, award 1, sex scandal 1, military base 1, artillery battery 1
+673
View File
@@ -0,0 +1,673 @@
# WikiDeck: Edit War — game design v1 (draft)
**Status:** v1 DRAFT, freeze target 23:30 EST 2026-11-16.
**Owners:** council-designer-a owns sections 0–9 (research, card derivation, rules). council-designer-b
owns sections 10–12 (keywords, peer-hosted modes, worked example). council-critic reviews.
Every number in **`code font`** is a rules-config key (see §9). Modes can override any of them.
A two-player lane game for 3–6 minute matches. Each player has a 12-card deck and there are 3
**Topics** (lanes) with 3 slots per side. There are 6 turns, both players plan at the same time, and
energy ramps from 1 to 6, with 1 unspent energy carried over. Reveals interleave one card at a time.
Win 2 of the 3 Topics. Each Topic is judged on one Wikipedia stat (**Attention**, **Depth** or
**Reach**), and a card is stronger in a Topic that matches its best stat. Fame (how high a card's
stats are overall) sets its **cost**, not its efficiency, so famous cards are sidegrades. They are
not upgrades.
---
## 0. Research summary (what we took, what we left)
| Game | Why it's fun | Taken | Left |
|---|---|---|---|
| Marvel Snap | 3-minute matches; simultaneous turns; 3 lanes, so the decision is *where*, not just *what* | lanes, about 6 turns, simultaneous planning, small deck | stakes betting (modes only); we deliberately diverge in lane size (3), energy carry-over, interleaved alternating reveals, stats visible from turn 1 with hidden Portals, and on-topic tie-breaks |
| Hearthstone | mana curve; readable cards; tempo | energy = turn number, curve-shaped costs | 30-card decks and 15-minute matches; hero powers |
| Magic: The Gathering | factions (colours) with distinct identities; deckbuilding depth | 6 factions with their own keyword flavour | land screw (resource variance); the stack; long text |
| Balatro | huge "moment" when a combo goes off; simple base rules plus modifiers | lane modifiers (Portals) as the run-to-run variety | single-player scoring |
| Slay the Spire | readable intents; every card is a choice | open information about lane state and power | roguelike runs (could be a mode) |
| Gwent | rows; best 2 of 3; passing and bluffing | best 2 of 3 Topics; hidden commitments | multi-round card advantage (too long) |
| Pokémon TCG | type advantage | on-topic bonus (card stat matches lane stat) | energy attachment; coin flips |
| Top Trumps | instantly understood: "my number beats yours" | lanes judged on one stat | picking the stat is solved play (always pick your best) |
| Dominion | deck building as play | — (too long for 3–6 min) | — |
**What is ours, not borrowed:**
- (a) each Topic is judged on one Wikipedia stat (the Top Trumps twist)
- (b) cost comes from an article's fame instead of being printed
- (c) a trend arrow driven by live pageviews
- (d) a total-power and consensus tie-break instead of stakes betting
- smaller choices: 3 slots per lane, 1 carried-over energy, interleaved reveals, and stats visible
from turn 1 with hidden Portals
The core loop is a lanes game in the style of Snap. The Top Trumps twist is that each lane asks for
one Wikipedia stat. That makes every stat matter and gives each turn its main decision: play the card
on-topic for the bonus, or put it where the fight is.
---
## 1. Card derivation (card data → game card)
The engine never reads raw 0–100 stats as power. Every game card is derived **deterministically** from a
`CardInput` that the match host freezes at match start:
```
CardInput = { cardId, pageId, title, category, rarity,
snapshot: MintStatsSnapshot, // at mint, immutable
live: { trendPercent: number | null, dailyAverage: number | null }, // frozen at match start
check: 'verified' | 'unverified' | 'unchecked' | 'loaner', // set by the host (§1.10)
pinned?: { cost, home, faction } } // loaners only (§2.1): replaces §1.1–1.5
```
### 1.1 Percentiles (rank-normalisation)
For each stat `s` in {attention, depth, reach}, `pct_s` = the percentile (0–100, integer) of the card's
snapshot score in the reference table `percentiles.<s>`. That table holds 99 ascending cut points from
council-data's `docs/game/card-sample.json`.
`pct_s` = the number of cut points strictly below the score, plus half the number equal to it, rounded
down. A `null` attention gives `pct_attention = null`.
### 1.2 Fame → Cost
`fame` = the integer mean (rounded half up) of the non-null percentiles.
`cost` = 1 + the number of thresholds in `costThresholds` (5 ascending values, default
`[26, 39, 51, 63, 78]` in v1.1) that are ≤ `fame`. So cost runs 1–6.
**Thresholds are data, not guesses (v1.1).** `fame` is a *mean* of up to 3 percentiles, so it clusters
around 50 even though each percentile is uniform. The v1.0 values `[15, 35, 55, 75, 90]` treated fame as
uniform, so 82% of the pool landed on cost 2–4 (3/23/37/22/10/5 %). `costThresholds` is therefore set to
the fame values at the **15/35/55/75/90 % points of the reference sample** (the same `card-sample.json`
whose `percentiles` table §1.1 uses). That's the integer set that brings the sample's cost spread closest
to the target 15/20/20/20/15/10 %. The v1.1 defaults come from the 236-card sample (fame 8–98) and
give 13/20/22/20/15/10 %. Whenever council-data refreshes the sample, the percentile table and
`costThresholds` are regenerated together and ship as one change. Pinned loaners (§2.1) are unaffected.
### 1.3 Power
`power` = `powerByCost[cost]`, default `[_, 1, 2, 4, 6, 8, 10]` (cost 1 → 1 … cost 6 → 10). The
critic's sim showed that heavy decks were too weak with `[…5,7,9]`.
Power depends **only on cost**. Two cards of the same cost have the same base power, whatever their
fame. Inflating stats (forged snapshots, template shopping) only moves a card up the curve. It never
makes a card more efficient.
### 1.4 Home stat
`home` = the stat with the highest `pct_s`. Ties are broken in this order: depth, reach, attention.
Depth and reach are the hardest to inflate. A `null` stat can never be home.
When a card is in a Topic whose stat equals its `home`, it gets **+`onTopicBonus[cost]`** power
(default `[0, 1, 1, 2, 2, 3, 3]`, i.e. ⌈cost/2⌉).
On-topic efficiency is then about 2 power per energy at every cost (2.0 / 1.5 / 2.0 / 1.75 / 2.0 / 2.0).
Off-topic, cheap cards are weaker (1.0) than expensive ones (1.5). Cheap cards want their Topic, and
big cards are flexible.
### 1.5 Faction
`faction` = the card's `category` (Space, Nature, People, Science, History, Culture), from
`server/wiki.ts`. Culture is about half the pool, so faction keywords are written so that a
mono-faction deck gains no consistency edge (§10: no v1 keyword scales with faction count).
### 1.6 Trend (live, small, capped)
`trend` = +1 if `live.trendPercent ≥ trendUp` (default 25), −1 if `≤ trendDown` (default **−200**,
which means there is **no down arrow in v1**: 69% of cards trend negative, so a ▼ would mostly land as
a quiet penalty on famous owned cards; modes can turn it back on), otherwise 0. A `null` value gives 0. Trend also needs `live.dailyAverage ≥ trendMinDaily` (default
**20**), because percentages on tiny articles are noise; otherwise trend is 0. The host computes it **once at match start**, and it is frozen for
the match. It shows as an arrow (▲), not a number. It adds to power in every Topic. *Why no ▼ by default:* 69% of the sample has a
negative `trendPercent`, and only busy (mostly owned, famous) cards pass `trendMinDaily`, so a ▼ would quietly penalise collectors.
Modes may turn it back on with e.g. `trendDown: -25`.
### 1.7 Rarity
The hash-derived `rarity` (`shared/protocol.ts:38`) is **cosmetic in v1** (frame colour only). Mining luck must not
become power or keyword choice.
### 1.8 Keyword
Each card has at most **one** keyword: cost-1 cards are vanilla, and the others get their faction's keyword (§10.1).
### 1.9 Card face (phone)
The card face shows **cost** (top-left), **power** (big, centre; the bonus shows as a "+N" badge on the home icon when the card is on-topic), a **home-stat icon**
(📣 attention / 📚 depth / 🌐 reach), an optional trend arrow, and one keyword word. That is two
numbers, plus the live lane power when the card is on the board.
### 1.10 Plausibility (anti-forgery, off-chain)
When `verifyStats` is true (the default for hosted matches), the match host checks each owned card's
snapshot before the match:
`pageBytes` against that revision's byte size, `languageCount` ≤ the live count + 5, and views for the
snapshot month within ±10 % of the pageviews API.
A card that fails is played with its live values. The **host replaces `snapshot`** with a snapshot
built from the live values (`deriveStats` on the live bytes, languages and views) **before** it builds
the `CardInput`. The match log marks the card `unverified`.
The engine does no I/O and only ever sees one version of each card.
- **Caching:** results are cached per `(pageId, revisionId, snapshotMonth)`. They are immutable, so a
cached pass or fail never expires. Live values for a failed card are cached for 24 h.
- **Card can't be verified** (the pageId or revision doesn't exist, or the title or category doesn't
match): the card is **rejected at deck validation**, and the player is asked to swap in a loaner.
- **API failure:** if Wikipedia can't be reached and nothing is cached, the card plays from its snapshot
with `check: 'unchecked'`. The engine then caps its cost at `uncheckedCostCap` (default **4**), and
power follows the capped cost. Matches are never blocked.
- The engine's only use of `check` is that cost cap. Loaner cards are `check: 'loaner'`.
---
## 2. Decks
- **Deck size:** exactly `deckSize` cards (default **12**).
- **Copies:** at most `maxCopiesPerPage` cards with the same `pageId` (default **2**). Owned and loaner
copies count **together**. Each copy keeps its own snapshot, so the two copies may differ in cost.
- **Deck validation** (engine): the size is right, the copy limit holds, every card's `check` is
valid, and there are no more loaners than `maxLoaners`. An invalid deck can't start a match.
- **Owned cards:** any card the player's wallet owns at match start. Ownership is read off-chain. The
match never moves, locks or burns a card.
- **Loaner cards:** off-chain preview cards with a fixed `CardInput`, shipped with the game data
(`docs/game/starter-cards.json`, picked by council-data: about 24 pageIds across all 6 categories,
with frozen, hand-checked snapshot stats, including the 4 cards in `shared/catalog.ts`).
Loaners follow the same curve (§2.1 pins their cost, home and faction), so they are no weaker or stronger than owned cards.
- **Starter decks:** `starterDecks` (default: 4 fixed 12-card loaner decks). Each one has two leading
factions and an average cost of 3.0–3.3, and is **curve-shaped**: at least 3 cards of cost 4 or more,
and at most 4 of cost 1. A new player picks one and can play at once.
- **Mixed decks:** an owned deck may fill any slots with loaners, up to `maxLoaners` (default 12, which
means no limit). Owning NFTs gives **variety**, not power: owned and loaner cards follow the same
curve.
### 2.1 Starter decks v1 *(owner: council-designer-b)*
These are the default `starterDecks`: four 12-card loaner decks.
- **Every deck has the same curve:** costs `1,1,2,2,3,3,3,4,4,5,5,6`. That's an average of 3.25, with 5 cards of cost 4 or more and 2 of cost 1.
- **Every deck has the same shape:** 6 cards from each of two factions, and 4 cards for each home stat. So every deck can play on-topic in every lane.
- **Loaner values are pinned.** Cost, home and faction are hand-set (not derived from `starter-cards.json`), so a loaner carries
`pinned: { cost, home, faction }`. For `check: 'loaner'` the engine takes these instead of §1.1–1.5.
Everything after them still applies: `powerByCost`, `onTopicBonus`, `vanillaBonus`, the §10.1 keyword choice and `keywordParams`.
A mode that changes those numbers changes loaners exactly as it changes owned cards.
- **Pinned cost isn't fame.** Cost was set by hand to fit the curve, not from the article's fame. Rarity is `Common` (frame only) and trend is 0.
- **Loaner ids:** `cardId` = `loaner:<kebab-title>`, and `pageId` = the article's real pageId (v1 pins the 4 `shared/catalog.ts` ones: Moon 19331, Periodic table 23053, Octopus 22780,
Albert Einstein 736; the rest are filled in from one batched API call in v1.1, `null` until then). The copy limit counts per `pageId`
together with owned copies (§2); a loaner with `pageId: null` counts per `cardId`.
- **Relation to `docs/game/starter-cards.json`** (council-data, real frozen snapshots of random articles): that file is the
**loaner pool** for the sim and for "fill a slot with a loaner" in the deck builder. It is **not** the default starter decks.
The decks below pin their values on purpose, for two reasons. Famous, recognisable articles would all derive to cost 5–6.
And the random sample has no Space cards (CARD_DATA.md finding 6).
- **v1.1 note (factions):** CARD_DATA.md finding 6 shows the legacy `category()` split as Culture 53%, People 30%, Nature 9%,
History 5%, Science 3%, Space 0%. In v1, owned decks were therefore about 50% viral and 30% local. Viral was the weakest keyword, so a typical owned deck
may be *weaker* than the starter decks. That's the wrong way round for "NFTs give variety, not power". v1 ships as is.
For v1.1, sim-balance runs a **realistic owned deck** (12 cards drawn from `card-sample.json` with its real category mix)
against each starter. **v1.1 fix:** viral gets a base of +1, and Culture cards take a keyword by home stat (§10.1), so owned decks
now have all six keywords in the mix. **BALANCE.md v1.1:** starters 52–53% overall, and owned vs starters 42–51%
(weakest vs Headliners and Stargazers; v1.2 candidates: `nostalgic`/`translated` `powerDelta -1`, `local.amount 2`). The P31-based factions council-data proposes (People, Places, Nature, Works & Culture,
Structures, Events & Ideas) are the v2 fix, and would need the host to fetch P31 (it isn't in `PageEnrichment`).
Keywords follow from §10.1: cost 1 → vanilla, otherwise the faction keyword (shown in brackets).
**A. Stargazers: Space (translated) + Science (encyclopedic)**
| Cost | Card | Faction | Home |
|---|---|---|---|
| 1 | Moon | Space | reach |
| 1 | Electron | Science | depth |
| 2 | Mars | Space | attention |
| 2 | Periodic table | Science | depth |
| 3 | Saturn | Space | reach |
| 3 | Photosynthesis | Science | attention |
| 3 | Black hole | Space | depth |
| 4 | Quantum mechanics | Science | reach |
| 4 | Milky Way | Space | attention |
| 5 | DNA | Science | attention |
| 5 | Sun | Space | reach |
| 6 | Theory of relativity | Science | depth |
**B. Field Guide: Nature (rising) + History (nostalgic)**
| Cost | Card | Faction | Home |
|---|---|---|---|
| 1 | Octopus | Nature | depth |
| 1 | Stonehenge | History | attention |
| 2 | Axolotl | Nature | attention |
| 2 | Rosetta Stone | History | reach |
| 3 | Coral reef | Nature | depth |
| 3 | Roman Empire | History | reach |
| 3 | Honey bee | Nature | attention |
| 4 | Ancient Egypt | History | depth |
| 4 | Amazon rainforest | Nature | reach |
| 5 | Blue whale | Nature | attention |
| 5 | Great Wall of China | History | reach |
| 6 | World War II | History | depth |
**C. Headliners: People (local) + Culture (by home stat: attention → viral, depth → encyclopedic, reach → translated)**
| Cost | Card | Faction | Home |
|---|---|---|---|
| 1 | Haiku | Culture | attention |
| 1 | Ada Lovelace | People | depth |
| 2 | Jazz | Culture | attention |
| 2 | Marie Curie | People | reach |
| 3 | Mona Lisa | Culture | reach |
| 3 | Frida Kahlo | People | attention |
| 3 | Chess | Culture | depth |
| 4 | Leonardo da Vinci | People | reach |
| 4 | The Beatles | Culture | attention |
| 5 | William Shakespeare | People | depth |
| 5 | Olympic Games | Culture | reach |
| 6 | Wolfgang Amadeus Mozart | People | depth |
**D. Pioneers: People (local) + Space (translated)**
| Cost | Card | Faction | Home |
|---|---|---|---|
| 1 | Sputnik 1 | Space | reach |
| 1 | Nikola Tesla | People | attention |
| 2 | Hubble Space Telescope | Space | depth |
| 2 | Isaac Newton | People | reach |
| 3 | Neil Armstrong | People | attention |
| 3 | Jupiter | Space | reach |
| 3 | Galileo Galilei | People | depth |
| 4 | Albert Einstein | People | attention |
| 4 | International Space Station | Space | depth |
| 5 | Apollo 11 | Space | attention |
| 5 | Charles Darwin | People | reach |
| 6 | Solar System | Space | depth |
- **Coverage:** all 6 factions appear, and all 4 `shared/catalog.ts` cards are included (Moon, Periodic table, Octopus, Albert Einstein).
- **Tutorial:** Field Guide vs Stargazers, seed 1, against the easy bot.
- **sim-balance:** please run the 4 decks round robin first. The target is every pairing at 45–55%. If a pairing misses, retune by
swapping home stats within a deck, never by changing the curve.
---
## 3. Board
- 3 **Topics** (lanes), numbered 1–3 from left to right (top to bottom in portrait).
- Each Topic has a **stat** (attention, depth or reach) and an optional **Portal** modifier (§10.3).
Topics have **no faction**. No v1 keyword counts factions: faction only picks the keyword.
- Each player has at most `laneCapacity` cards per Topic (default **3**). That gives 9 slots per side,
which caps cheap-card flooding and fits 3 cards across a 360 px phone.
- **Topic pool:** `topicPool` is a list of Topics, each `{ id, name, stat, portal | null }`. The default
pool has 9 Topics: 3 per stat, one plain and two with Portals. `pool_s` is the sub-list with stat
`s`, in file order.
- **Topic draw (exact):**
- If `distinctStats` is true (the default): for each stat in the fixed order
`[attention, depth, reach]`, pick `pool_s[floor(next() × len(pool_s))]`. That uses 3 `next()`
calls. Then Fisher–Yates the 3 picks into lanes 1–3 (i = 2, 1; j = floor(next() × (i+1))), which
uses 2 calls.
- If `distinctStats` is false: Fisher–Yates the whole pool (i from n−1 down to 1) and take the first
`topicCount` entries as lanes 1–3.
- **Stats visible, Portals hidden:** every Topic's **stat** is face-up from turn 1. Its **Portal**
modifier is face-down until the start of turn `portalReveal[i]` (default `[2, 3, 4]`). You always
know where your card is on-topic, but not what twist a lane will get.
---
## 4. Match setup (deterministic)
1. The input is `{ seed: uint32, rules, players: [p0, p1] }`, and each player's input is
`{ id, deck: CardInput[12] }`. Seat order is input order.
2. RNG: **mulberry32(seed)**. Every random choice draws `next()` in this fixed order:
1. shuffle p0's deck (Fisher–Yates, i from n−1 down to 1, j = floor(next() × (i+1)))
2. shuffle p1's deck the same way
3. draw and shuffle the Topics
4. the initiative coin: p0 has initiative on odd turns if next() < 0.5, otherwise p1
5. later random events (keywords only), in resolution order
3. Each player draws `openingHand` cards (default **3**). There are no mulligans in v1
(`mulligan: false`).
4. **Seed fairness (hosted PvP):** commit–reveal. Each party *i* (host, p0, p1) sends
`sha256(r_i)` for a random 32-byte `r_i`, then reveals `r_i` once all commits are in.
`seed` = the first 4 bytes (big-endian uint32) of `sha256(r_host ‖ r_p0 ‖ r_p1)`.
The host still relays the hidden plans, so hosted PvP trusts the host not to leak them.
Local and bot matches use any seed.
---
## 5. Turn structure
The match lasts `turns` turns (default **6**, hard cap). Each turn has these phases:
1. **Start**
- Reveal any Portal scheduled for turn *t* (resolve its "on reveal").
- Each player's energy = `energyByTurn[t-1]` + carry + `bonusEnergy`. Carry is
min(`energyCarryMax`, unspent energy from last turn), default max **1**. Saving one energy on
turn 2 makes a turn-3 four-drop possible: a real tempo choice.
- Each player draws 1 card if their deck isn't empty and their hand holds fewer than `handLimit`
(default **7**) cards. Otherwise they don't draw. This includes turn 1, so the turn-1 hand is
3 + 1 = 4 cards.
- Order within Start: Portal reveal, then energy, then draw. The Underdog check (step 2) comes after
all three.
2. **Underdog check** (mode option, `underdog: false` by default, because it can be sandbagged). When
it's on, from turn 2, a player who leads in 0 Topics while the opponent leads in ≥ 2 gets
**+1 energy** this turn.
3. **Plan** (simultaneous, hidden)
- Each player queues an ordered list of plays `(handIndex, topic)`.
- Total cost must be ≤ their energy, and each Topic needs room on that player's side.
- Plays can be undone freely until **Commit**. Passing is an empty commit.
- **Hidden means nothing leaks.** While you plan, the opponent's hand count and energy don't change
visibly. Only the bare fact "opponent is ready" (`committed`) is shown. No queue count, no spent energy.
- The turn timer is `turnSeconds` (default **25**). On timeout, whatever is queued is committed.
4. **Reveal (interleaved)**
- Plays reveal **one at a time, alternating**: the initiative player's 1st, the other player's
1st, the initiative player's 2nd, and so on. When one player runs out, the rest of the other's
reveal in order.
- Each card enters its Topic and its "on reveal" effect resolves at once.
- So the order in which you queue cards matters: lead with the card you want resolved first.
- Energy is reserved when a card is queued. A queued play that is no longer legal at reveal (the
lane is full, or a Portal rejects it) **fizzles**: the card stays in hand and its energy is lost.
5. **End**
- Recompute all Topic powers (§6).
- End-of-turn effects resolve, the initiative player's first.
- Initiative strictly **alternates** each turn (set by the coin in §4).
- Plans are locked before anything reveals, so initiative gives away no information. It only
decides the order of on-reveal effects. §10 includes keywords where that order matters.
A typical turn is: look at the lanes, tap a card, tap a Topic (×1–3), tap Commit. That is under 10
seconds, done with one thumb, with no dragging.
---
## 6. Power and Topic control
- A card's **lane power** = `power` + (`onTopicBonus[cost]` if its home stat is the Topic's stat) + `trend`
+ keyword and Portal modifiers. It is never below 0.
- A player's **Topic power** = the sum of their cards' lane power in that Topic.
- A player **leads** a Topic if their Topic power is strictly greater than the opponent's.
- **Consensus tie-break:** if the powers are equal and > 0, the player with more **on-topic** cards
there leads. If that is also equal, nobody leads. 0–0 has no leader.
---
## 7. Win conditions and tie-breaks
**Scoring** happens after the last turn's End phase (§5.5): every end-of-turn effect, including
the last turn's, and every "at scoring" Portal resolves **before** Topics are judged. Then:
1. The player who leads **more Topics** wins (2–1, 2–0, 1–0 and 3–0 all count).
2. If they lead the same number of Topics: the higher **total power across all Topics** wins.
3. If that is also equal: the match is a **draw**.
**Concede:** a player can concede at any time, and the opponent wins at once. A player who misses
`afkTurns` timeouts in a row (default **2**) with nothing queued concedes.
---
## 8. Degenerate lines and why they fail (for the critic)
| Line | Why it isn't dominant |
|---|---|
| All-famous (all max-stat) deck | It becomes an all-cost-5/6 deck with four dead early turns. Cheap cards are more efficient **per energy**, expensive cards **per card**, and only 9 cards are seen per match (3 + 6 draws). So a pure cost-5/6 deck is **weak by design**: **BALANCE.md v1: 15%**, and no lever (power curve, energy ramp) fixes it without breaking curve or swarm decks. There is no hard deck rule; the deck builder warns below 4 cards of cost ≤ 2, and every starter is curve-shaped (§2.1). **Target met:** a **top-heavy curve** (half the deck at cost 4 or more) wins **57%** (target ≥ 40%). `energyByTurn [2..7]` was rejected for v1.1: it lifts heavy decks but kills swarm (20%). |
| All-cheap flood (cost 1–2) | Weak by design: only 9 slots and 9 cards seen. **BALANCE.md v1: 2%** (critic's sim 7–11%). Every lever that revives it breaks curve decks (sweep in BALANCE.md). viral (base +1, v1.1) is its consolation, not its fix. |
| All one faction | No v1 keyword scales with faction count. `factionSynergyCap` is reserved for modes. Culture, the largest pool, splits over three keywords by home stat (§10.1), so it has no single keyword to stack. |
| Owning NFTs buys power (pay-to-win) | Power depends only on cost (§1.3), and cost follows a fixed curve. **BALANCE.md v1.1 re-run (real `RULESET_V1_1`):** each starter deck averages **52–53%** overall. A realistic owned deck from `card-sample.json` wins **42–51%** against the starters (n ≈ 55 per pairing, ±13 pp). So owning cards buys variety, not power. v1.2 levers if owned decks should be a little stronger: `local.amount 2`, and `nostalgic`/`translated` `powerDelta -1` (the two strongest keywords, about +1.65 net per card). |
| "Always play the highest-power card" | It ignores the on-topic bonus, lane capacity and the hidden Portals. **BALANCE.md v1:** the naive max-power line wins **40%** against greedy, and lookahead-lite beats greedy **60–70%**, so skill shows (target < 55%). Critic's sim: 18–21% against a smart bot. |
| Stall or pass | Passing leaves lanes to any 1-power card. Two passing players draw. |
| Mirror the AI | Hidden simultaneous commits: you only see the opponent's cards after you commit. |
| Seat or initiative | Planning is simultaneous and initiative strictly alternates (each seat has it for 3 of the 6 turns). **BALANCE.md v1.1 re-run (real `RULESET_V1_1`): first player 51.2% [48.8–53.6]** (target 48–52%; v1 was 53.4%). |
| Forged or shopped stats | They only raise cost (§1.3), the host check falls back to live stats (§1.10), and trend is capped at ±1. |
| Inflated live pageviews | Worth at most +1, frozen at match start, and only counts for articles with ≥ 20 views a day. |
| Swinginess | No effect may change a lane by more than 6 power or move cards between lanes in v1 (a keyword-design rule for §10). |
---
## 9. Rules config (all defaults)
The engine takes a `RulesConfig` object. Peer-hosted modes override it (§11). Defaults:
```json
{
"version": "1.1",
"deckSize": 12, "maxCopiesPerPage": 2, "maxLoaners": 12,
"openingHand": 3, "handLimit": 7, "mulligan": false,
"turns": 6, "turnSeconds": 25, "afkTurns": 2,
"energyByTurn": [1, 2, 3, 4, 5, 6], "energyCarryMax": 1, "bonusEnergy": 0, "underdog": false,
"topicCount": 3, "distinctStats": true, "portalReveal": [2, 3, 4], "laneCapacity": 3,
"topicPool": [ /* inline Topic objects {id, name, stat, portal}; default = the 9 in §10.3 */ ],
"keywordParams": { /* per-keyword numbers, keyed by keyword id (§10) */ },
"portalParams": { /* per-Portal numbers, keyed by Topic id (§10.3) */ },
"costThresholds": [26, 39, 51, 63, 78],
"powerByCost": [0, 1, 2, 4, 6, 8, 10],
"onTopicBonus": [0, 1, 1, 2, 2, 3, 3], "vanillaBonus": 1,
"keywordsEnabled": ["viral","rising","local","encyclopedic","nostalgic","translated"], "cultureKeyword": "home", "ownedCards": true,
"trendUp": 25, "trendDown": -200, "trendMinDaily": 20, "uncheckedCostCap": 4,
"factionSynergyCap": 3,
"verifyStats": true,
"percentiles": "card-sample-2026-11-16",
"starterDecks": "default"
}
```
**What modes may vary:** every key above, plus `topicPool` contents and the starter-deck lists.
**Fixed for all modes:** matches are off-chain and never move or burn NFTs; the RNG and its draw order
(§4); the shape of the derivation (§1: percentile → fame → cost → power); at most one keyword per card;
the phases of a turn (§5).
A mode must keep `turns × turnSeconds ≤ 240` so that matches stay within 3–6 minutes.
---
## 10. Keywords *(owner: council-designer-b)*
**The v1 keyword set is these six, one per faction.** The ids are the ones engine-b already uses on `night/engine/keywords`.
Topics carry only a **stat**, never a faction. Every keyword below that mentions a Topic keys off stats or board state.
### 10.1 Which keyword a card gets
First rule that matches:
1. `cost == 1` → **no keyword** (vanilla). The card gets +`vanillaBonus` power (default **1**), so a cost-1 card is 2.
2. `"edition"` is in `keywordsEnabled` (off by default) and the deck holds another card with the same `pageId` → **edition**.
3. If the faction is **Culture** and `cultureKeyword` is `"home"` (v1.1 default) → the keyword for its **home stat**:
attention → **viral**, depth → **encyclopedic**, reach → **translated**. (`"faction"` gives v1 behaviour: every Culture card is viral.)
4. Otherwise → the card's **faction keyword** from 10.2.
In steps 3–4, if the chosen keyword isn't in `keywordsEnabled`, the card is vanilla, *without* `vanillaBonus`.
*Why step 3:* Culture is about half of all owned cards. Without it, owned decks are half viral and see only 2 of the 6 keywords.
Rarity plays no part here (it's cosmetic, §1.7). Keywords don't lower power, and v1 has no per-keyword power deltas.
If sim shows that a keyword is worth more than about 1 power on average, sim-balance sets `keywordParams.<id>.powerDelta` (default 0, range −3 to 0).
### 10.2 Keyword list (v1)
| Faction | id (card word) | Trigger | Reminder text | Cap | Order-sensitive? |
|---|---|---|---|---|---|
| Culture | **viral** | On reveal | +1 power, plus +1 for each other card you revealed earlier this turn. | +3 | yes: your queue order |
| Nature | **rising** | End of turn | +1 power. | +2 total | no |
| People | **local** | Ongoing | +1 power while on-topic (the Topic's stat is its home stat). | +1 | no |
| Science | **encyclopedic** | On reveal | +2 power if you have no other cards here. | +2 | **yes: interleaving** |
| History | **nostalgic** | On reveal | +2 power if you are losing here. | +2 | **yes: interleaving** |
| Space | **translated** | On reveal | +1 power to your most recently revealed card in each *other* Topic. | +2 | yes |
Why this set: every keyword is one line and one trigger, and only adds power. The largest swing is +2 on one card,
so no lane moves by more than 3 from a keyword (viral at its cap). Nothing scales with faction count, so a mono-Culture deck gets no
consistency edge (`factionSynergyCap` is unused). Viral rewards wide turns, and Culture cards are spread over three keywords (§10.1 step 3).
Three keywords (encyclopedic, nostalgic, translated) react to the interleaved reveal (§5.4), so initiative and queue order matter.
Precise rules (for engine-b):
- **On reveal** resolves the moment the card enters its Topic, and sees every card revealed before it (both players,
including earlier reveals this turn). The bonuses it grants are permanent counters.
- **Ongoing** is a condition, recalculated whenever power is read.
- **End of turn** resolves in §5.5 order: the initiative player's cards first, then Topic 1→3, then reveal order.
- **viral:** gain = min(`base` + `amount` × N, `cap`), where N = the owner's cards revealed earlier in *this* turn's Reveal phase, in any Topic.
Cards that went back to hand don't count. v1.1: base 1, amount 1, cap 3 (v1 was base 0, cap 2).
- **rising:** stops after it has gained +2 in total.
- **local:** "on-topic" is exactly the §1.4/§6 condition. It's simply an extra +1 on top of `onTopicBonus`.
- **encyclopedic:** with `sides: 1` (v1.1 default), "no other cards here" means **your** side of this Topic is empty, apart from this card,
when it reveals; the opponent's cards don't matter. `sides: 2` is v1 (both sides empty).
- **nostalgic:** "losing here" means the opponent's Topic power here is strictly greater than yours, counted just *before* this card is added.
The consensus tie-break doesn't count: a tie is not losing.
- **translated:** "most recently revealed" means the highest global reveal sequence number among your cards in that Topic. Topics where you have no card are skipped.
- No v1 keyword uses the RNG. §4's "later random events" slot stays empty in v1.
**Already in code, disabled by default (`keywordsEnabled` excludes them; for modes only):**
- **edition:** +2 for each other copy of this `pageId` on your side.
- **obscure:** the opponent sees it face down until the end of the match.
- **wildcard:** its home stat becomes the Topic's stat on reveal.
These are engine-b's existing implementations. The faction-based versions of `local` and `wildcard`, and the token version of `viral`, are
**replaced** by the definitions above.
**`keywordParams` defaults** (keyed by keyword id; modes may change them within the §11 ranges):
```json
{ "viral": {"base": 1, "amount": 1, "cap": 3, "powerDelta": 0}, "rising": {"amount": 1, "cap": 2, "powerDelta": -1},
"local": {"amount": 1, "powerDelta": 0}, "encyclopedic": {"amount": 2, "sides": 1, "powerDelta": 0},
"nostalgic": {"amount": 2, "powerDelta": 0}, "translated": {"amount": 1, "powerDelta": 0},
"edition": {"amount": 2, "powerDelta": 0}, "obscure": {"powerDelta": 0}, "wildcard": {"powerDelta": 0} }
```
End-of-turn effects on the last turn resolve **before** scoring (§7).
**v1.2 candidates** (not in v1.1; decide on a larger run, per BALANCE.md's v1.1 re-run): the keyword values are still uneven:
translated +1.64 and nostalgic +1.69 per card vs local +0.69 (critic's target was ±0.3). The starter decks stay even only because each one
pairs a strong keyword with a weak one. The first levers are `nostalgic.powerDelta -1` and `translated.powerDelta -1`, plus `local.amount 2`
if owned decks stay under 45% against Headliners. Both are config only.
### 10.3 Portals (Topic modifiers) and the default Topic pool
Each Topic has `{ id, name, stat, portal | null }`. The default `topicPool` has 9 Topics, one plain and two with
Portals for each stat. A Portal applies from the moment its Topic is revealed (§3), except where it says otherwise.
| Topic | Stat | Portal rule |
|---|---|---|
| Current Events | attention | – |
| Main Page | attention | At scoring, each card here gets +1 power. |
| Trending | attention | Trend arrows (§1.6) count double here (±2). |
| Archive | depth | – |
| Featured Article | depth | At end of the match, the player with the single highest-power card here gets +2 Topic power here. If the highest card power here is tied (between the two players), nobody gets the bonus. |
| Stub | depth | Lane capacity here is 2 per player. |
| Translations | reach | – |
| Interwiki | reach | +1 Topic power here for a player who has at least one card in all 3 Topics. |
| Disambiguation | reach | Every card here counts as on-topic, whatever its home stat. |
As data: `portal = { kind: "scoringCardBonus", amount: 1 } | { kind: "trendMultiplier", factor: 2 } |
{ kind: "highestCardBonus", amount: 2 } | { kind: "laneCapacity", value: 2 } | { kind: "spreadBonus", amount: 1 } |
{ kind: "allOnTopic" }`. Modes may add Topics with these kinds, using new numbers, but not new kinds (engine code).
**`portalParams` defaults** (keyed by Topic id): `{ "main-page": {"amount": 1}, "trending": {"factor": 2},
"featured-article": {"amount": 2}, "stub": {"value": 2}, "interwiki": {"amount": 1} }`. Disambiguation has no numbers.
Topic ids are the names in kebab-case: `current-events, main-page, trending, archive, featured-article, stub,
translations, interwiki, disambiguation`. The UI shows each Portal's one-line rule **on the lane itself**, not behind a tap.
---
## 11. Peer-hosted modes *(owner: council-designer-b)*
A **mode** is data, published by a node operator and run by the match host:
```json
{
"id": "blitz", // [a-z0-9-]{3,32}, unique per host
"name": "Blitz", "description": "Four quick turns.", // ≤ 40 and ≤ 280 chars, plain text
"rules": { "turns": 4, "energyByTurn": [2, 3, 4, 5], "portalReveal": [1, 1, 2], "deckSize": 10 },
"topicPool": [ /* optional: Topic objects (10.3); default if omitted */ ],
"starterDecks": [ /* optional: lists of loaner pageIds */ ]
}
```
- `rules` is a **partial** `RulesConfig` (§9) merged over the defaults. Unknown keys are rejected.
- **Validation** (modes owns the code; these are the limits). If any check fails, the mode is refused:
| Key | Allowed |
|---|---|
| `turns` | 3–8, and `turns × turnSeconds ≤ 240` |
| `energyByTurn` | length = `turns`, each 0–10 |
| `bonusEnergy` | 0–3 |
| `portalReveal` | length = `topicCount`, each 1..`turns`, non-decreasing |
| `topicCount` | 1–5; `distinctStats` only if ≤ 3 |
| `laneCapacity` | 1–6 |
| `deckSize` | 6–20; `maxCopiesPerPage` 1–4; `maxLoaners` 0..`deckSize` |
| `openingHand` | 0–6; `handLimit` 1–10 |
| `turnSeconds` | 10–60; `afkTurns` 1–5 |
| `costThresholds` | 5 strictly ascending integers in 0–100 |
| `powerByCost` | 7 integers in 0–20, non-decreasing from index 1 |
| `onTopicBonus` (7 entries), `vanillaBonus` | 0–5 each |
| `trendUp` / `trendDown` | 0–200 / −200–0 |
| `factionSynergyCap` | 0–6 |
| `keywordsEnabled` | any subset of the 9 implemented ids (the 6 v1 defaults + edition, obscure, wildcard); a card whose keyword is disabled is vanilla, *without* `vanillaBonus` |
| `keywordParams`, `portalParams` | only the keys listed in §10 / §10.3; amounts and caps 0–6, `viral.base` 0–3, `encyclopedic.sides` 1–2, `powerDelta` −3–0 |
| `cultureKeyword` | `"home"` or `"faction"` |
| `verifyStats` | the host may only turn this off for modes that use only loaners (`maxLoaners == deckSize` and owned cards banned) |
| `topicPool` | 3–20 Topics, Portal kinds only from 10.3 |
- **Identity:** `modeHash` = SHA-256 of the canonical JSON (sorted keys, no whitespace) of the *merged* rules
plus the topicPool. A match record holds `{ modeHash, seed, both decks' CardInputs, both players' commit lists }`,
and that is enough to replay it exactly.
- **What modes can't change** is the "Fixed for all modes" list in §9. Modes also can't add keywords or Portal kinds, or
stake, move or burn NFTs.
Example modes (good defaults for operators to publish):
| Mode | Overrides | Feel |
|---|---|---|
| **Blitz** | `turns 4`, `energyByTurn [2,3,4,5]`, `portalReveal [1,1,2]`, `deckSize 10`, `turnSeconds 20` | about 2 minutes |
| **Deep Cuts** | `topicPool`: only the 3 depth Topics, `distinctStats false` | rewards long, obscure articles |
| **Loaner League** | `maxLoaners 12` and owned cards banned (`"ownedCards": false`, a new boolean key, default true) | fully level, for tournaments |
| **Big Board** | `topicCount 5`, `distinctStats false`, `portalReveal [1,2,3,4,5]`, `laneCapacity 3` | win 3 of 5; **tablet/desktop only** (5 × 3 slots won't fit a 360 px phone) |
| **No Keywords** | `keywordsEnabled []`, `onTopicBonus [0,3,3,3,3,3,3]` | Top Trumps–style tutorial mode |
---
## 12. Worked example match *(owner: council-designer-b)*
**Ruleset for this example: v1.0** (the golden test pins it): `cultureKeyword "faction"`, `viral {base 0, cap 2}`,
`encyclopedic {sides 2}`, `rising.powerDelta 0`; everything else as §9. *(The v1.1 numbers are in §12.1.)*
These are the §1–9 rules as of this PR:
- `powerByCost [0,1,2,4,6,8,10]`, `onTopicBonus [0,1,1,2,2,3,3]`, `vanillaBonus 1`
- `laneCapacity 3`, `energyCarryMax 1`, interleaved reveals, alternating initiative, `portalReveal [2,3,4]`
- `underdog false`, no trend arrows
The derived cards are given directly (the §1 output), so the test needs no percentile table.
Topics: **T1 Archive (depth, plain)**, **T2 Main Page (attention; Portal revealed turn 3; at scoring, each card here gets +1)**,
**T3 Translations (reach, plain; revealed turn 4)**. Ana (p0) has initiative on odd turns and Bo (p1) on even turns.
| Player | Card | Faction | Cost | Base | Home | Keyword |
|---|---|---|---|---|---|---|
| Ana | Octopus | Nature | 1 | 2 | depth | – (vanilla) |
| Ana | Moon | Space | 2 | 2 | reach | translated |
| Ana | Coral reef | Nature | 2 | 2 | depth | rising |
| Ana | Albert Einstein | People | 4 | 6 | attention | local |
| Ana | Ancient Rome | History | 5 | 8 | depth | nostalgic |
| Ana | Library of Alexandria | History | 4 | 6 | depth | nostalgic |
| Ana | Periodic table | Science | 3 | 4 | depth | encyclopedic |
| Bo | Haiku | Culture | 1 | 2 | attention | – (vanilla) |
| Bo | Mars | Space | 2 | 2 | reach | translated |
| Bo | Jazz | Culture | 2 | 2 | attention | viral |
| Bo | Pop music | Culture | 4 | 6 | attention | viral |
| Bo | Jupiter | Space | 5 | 8 | reach | translated |
| Bo | Fern | Nature | 3 | 4 | depth | rising |
| Bo | Mona Lisa | Culture | 3 | 4 | attention | viral |
Topic power is written as **Ana–Bo** after End of turn. Energy is "available / spent".
| Turn | Init | Energy Ana / Bo | Reveals, in interleaved order | T1 | T2 | T3 |
|---|---|---|---|---|---|---|
| 1 | Ana | 1/1, 1/1 | Ana Octopus → T1: 2 +1 on-topic = **3**. Bo Haiku → T2: 2+1 = **3** | 3–0 | 0–3 | 0–0 |
| 2 | Bo | 2/2, 2/0 | Bo passes (to carry 1). Ana Moon → T3: 2+1 = 3. translated: Octopus +1 → 4 | 4–0 | 0–3 | 3–0 |
| 3 | Ana | 3/2, **4**/4 | Main Page Portal revealed. Ana Coral reef → T1: 2+1 = 3. Bo Mars → T3: 2+1 = 3, translated: Haiku +1 → 4. Bo Jazz → T2: 2+1 = 3, viral (Mars earlier) +1 → 4. End: rising Coral reef → 4 | 8–0 | 0–8 | 3–3 (tie; on-topic 1–1, so no leader) |
| 4 | Bo | **5**/4, 4/4 | Bo Pop music → T3: 6 (off-topic), viral +0. Ana Einstein → T2: 6+2 on-topic, local +1 = **9**. End: rising Coral reef → 5 (cap reached) | 9–0 | 9–8 | 3–9 |
| 5 | Ana | **6**/5, 5/5 | Ana Ancient Rome → T3: 8 (off-topic). nostalgic: losing 3–9, so +2 → **10**. Bo Jupiter → T1: 8 (off-topic). translated: Jazz → 5 (T2), Pop music → 7 (T3) | 9–8 | 9–9: **Bo leads** (consensus: on-topic 1 vs 2) | 13–10 |
| 6 (last) | Bo | **7**/7, 6/6 | Bo Fern → T1: 4+2 = 6. Ana Library → T1: 6+2 = 8. nostalgic: losing 9–14, so +2 → **10**. Bo Mona Lisa → T2: 4+2 = 6, viral (Fern earlier) +1 → 7. Ana Periodic table → T2: 4 (off-topic), encyclopedic: no (cards here). End: rising Fern → 7. Scoring: Main Page +1 per card in T2 | **19–15** | **15–19** | **13–10** |
Final card values:
- **T1:**
- Ana: Octopus 4 + Coral reef 5 + Library 10 = 19.
- Bo: Jupiter 8 + Fern 7 = 15.
- **T2:** each card +1 from Main Page.
- Ana: Einstein 10 + Periodic table 5 = 15.
- Bo: Haiku 5 + Jazz 6 + Mona Lisa 8 = 19.
- **T3:**
- Ana: Moon 3 + Ancient Rome 10 = 13.
- Bo: Mars 3 + Pop music 7 = 10.
**Ana wins 2–1.** Three moments show the v1 mechanics:
- **Carry-over:** Bo passed on turn 2 to afford two plays on turn 3 (4 energy).
- **Consensus:** T2 at 9–9 after turn 5 went to Bo, who had two on-topic attention cards to Ana's one.
- **Interleaving decides the match:** on turn 6 Bo had initiative, so Fern revealed before Library. Ana was then losing T1 (9 vs 14) and nostalgic fired (+2).
If Ana had revealed first, she'd have been ahead 9–8, nostalgic would not have fired, and T1 would have been 17–15. Ana still wins that lane, but by 2 instead of 4.
**Golden test for engine-b:**
- **Inject:** the Topic order, the opening hands and the draw order directly, with each player's commit list per turn as in the table. The queue order within a turn is as listed.
- **Expected final Topic powers:** `T1 19–15, T2 15–19, T3 13–10`. Winner: p0, by 2 Topics to 1.
- **Also assert:**
- after turn 5, T2 is a 9–9 tie with Bo leading by consensus
- Ana's carried energy is 1 at the start of turns 4, 5 and 6
- Bo's carried energy is 1 at the start of turn 3
### 12.1 The same match under the v1.1 ruleset
Same cards, Topics, hands and commit lists; ruleset = §9 defaults (v1.1: `viral {base 1, cap 3}`, `encyclopedic {sides 1}`,
`rising.powerDelta -1`, `cultureKeyword "home"`). The example's Culture cards (Jazz, Pop music, Mona Lisa) are attention-home, so they stay viral.
Energy and carry are unchanged.
What changes:
- **rising −1:** Coral reef is 1 base and ends at 1+1+2 = **4**; Fern is 3 base and ends at 3+2+1 = **6**.
- **viral base 1:** Jazz +2 (Mars earlier), Pop music +1 (base only), Mona Lisa +2 (Fern earlier).
- **nostalgic still fires** for Library (Ana is losing T1 8–13 just before it). **encyclopedic still doesn't** (Einstein is already on Ana's side of T2).
| After turn | T1 | T2 | T3 |
|---|---|---|---|
| 1 | 3–0 | 0–3 | 0–0 |
| 2 | 4–0 | 0–3 | 3–0 |
| 3 | 7–0 | 0–9 | 3–3 |
| 4 | 8–0 | 9–9 | 3–10 |
| 5 | 8–8: **Ana leads** (consensus: on-topic 2 vs 0) | 9–10 | 13–11 |
| 6, before scoring | 18–14 | 13–18 | 13–11 |
| **final** (Main Page +1 per card in T2) | **18–14** | **15–21** | **13–11** |
**Ana still wins 2–1.** The moments in v1.1:
- **Carry-over:** unchanged.
- **Consensus:** moves to **T1 after turn 5** (8–8). Ana has two on-topic depth cards there (Octopus, Coral reef) and Bo has only the off-topic Jupiter.
- **Interleaving:** unchanged in kind. If Ana had revealed Library before Fern, T1 would have been 8–8 at that moment, a tie is not losing,
so nostalgic would not fire and T1 would end 16–14.
**v1.1 golden test:** expected `lanePower [[18,14],[15,21],[13,11]]`, winner p0. Also assert the T1 8–8 consensus lead for p0 after turn 5.
(Cross-checked by council-critic with the #27 engine, `tower-plus:scratchpad/critic/golden11.ts`, and by hand by designer-b.)
+89
View File
@@ -0,0 +1,89 @@
# WikiDeck Duel: engine API (v1, Night 2)
Owner: **duel-core** (claude/wikideck#55). Rules: `docs/game/DUEL_DESIGN.md` (duel-design). This file: how code talks to the engine.
- Types: `shared/duel/types.ts`. Ruleset: `shared/duel/ruleset.ts`. Function surface: `DuelEngineApi` in `shared/duel/index.ts`, implemented by `shared/duel/engine.ts` (engine-alpha PR).
- `shared/game/` (Edit War) is untouched. Change requests: comment on #55 with `[from <agent>]`.
## Principles
- **Pure and deterministic.** `(rules, decks, seed, actions)` → identical state and log. RNG: `shared/game/rng.ts` (mulberry32); its uint32 state lives in `DuelState.rng`.
- **Plain JSON.** `DuelState` round-trips through `JSON.stringify`/`parse`; `serialize`/`deserialize` are thin wrappers.
- **Clone-on-apply.** `applyAction` never mutates its input and throws on an illegal action.
- **Atomic actions.** `legalActions(state, seat)` is small, and `[]` for the seat that is not to act. The host checks an action by deep-equal against that list (`concede` and `timeout` excepted).
- **Off-chain.** Matches never move or burn cards. Cards arrive derived and frozen; the engine does no I/O.
## Cards (`DuelCard`)
Built by duel-cards (`derive()`), frozen by the host at match start. Shape agreed with duel-cards on #55.
| Field | Notes |
|---|---|
| `cardId` | unique in a deck (NFT tokenId; sample id in sims; `token:` for tokens) |
| `pageId`, `revisionId?`, `title`, `description?` | `pageId` matches Linked pairs; `revisionId` for recap references |
| `type`, `subtype?` | `Figure` · `Location` · `Event` · `Institution` · `Doctrine` |
| `portal` | `Arts, Earth, History, Science, Society, Neutral`; no deckbuilding restriction |
| `cost` | 1–6 (Locations 1–3) |
| `power`, `toughness` | Figures: body. Locations: 0 / Garrison (0 = can't block). Others: `null` or 0 |
| `keywords` | ≤ `maxKeywords` (2). Figures only |
| `territory?` | Location: +N max Citations while controlled (total from all sources ≤ `territoryCap`) |
| `effects` | `EffectSpec[]` (below), ≤ 4 |
| `rulesText`, `flavor` | display only |
| `connect?` | `{countries, centuries, links, p31}` frozen claims; the engine computes Connected |
| `rarity?`, `deriveVersion?`, `token?` | |
### Keywords (DUEL_DESIGN §4), as the engine applies them
- **Protected**: can't be the target of Events or Doctrines an opponent controls (abilities of other permanents and combat still apply).
- **Featured**: can be blocked only by Featured, Translated or Multilingual Figures.
- **Multilingual**: can block Featured; can't be blocked by Local Figures.
- **Translated**: can block Featured.
- **Legacy**: when destroyed, its controller draws a card.
- **Well-sourced**: prevent the first 1 damage dealt to it each turn.
- **Stub**: at the start of your turn, a +1/+1 counter, up to `stubMax` (2).
- **Local**: +1/+1 while you control a Location sharing a `connect.countries` value.
- **Trending** (Trending mode, set by the host via `applyLive`): no Pending review, +`trendingPower`/+0.
### Effects (`EffectSpec`)
`{ trigger, op, target?, amount?, power?, toughness?, duration?, token?, condition?, grant?, template? }`
- **Triggers:** `onPlay` (Event resolves; on a permanent same as `onEnter`), `onEnter`, `onAttack`, `onDestroyed`, `startOfTurn`, `onCombatDamageToPlayer` (on a Figure, or on a Doctrine for its attached Figure), `static`.
- **Ops:** `damage`, `damageEach`, `createToken`, `pump`, `fight`, `draw`, `attach`, `gainLife`, `drain`, `destroy`, `bounce`, `tap`.
- **Targets:** chosen: `figure`, `figureOrLocation`, `ownFigure`, `opponentFigure`, `anyTarget`; automatic: `each`, `self`, `attached`, `ownFigures`, `opponentFigures`, `opponent`, `controller`. Defaults: damage → `anyTarget`, pump → `self`, draw/gainLife/createToken → `controller`, drain → `opponent`.
- **Chosen targets:** each `onPlay`/`onEnter` effect with a chosen target consumes the next entry of `play.targets`, in effect order; `legalActions` enumerates the combinations. An Event or Doctrine with no legal target can't be played; a Figure/Location/Institution enters and its targeted effect fizzles (`targets` omitted).
- **fight:** the previous chosen target in the same card (else the source permanent) and this target deal damage equal to their power to each other. T6 = `[{op:'pump', target:'ownFigure', power:k, toughness:0}, {op:'fight', target:'opponentFigure'}]`.
- **Doctrine:** its `attach` effect's target is the Figure it attaches to (`ownFigure` for T11, `figure` for T12). Its `static` effects with `target: 'attached'` apply to that Figure; `condition.samePortal` on a Doctrine means "other Figures you control of the attached Figure's Portal". When the Figure leaves, the Doctrine is Deleted.
- **static pump** applies while the source is in play; conditions use **printed** power (no feedback loops). `condition.connected` = the affected Figure is Connected to the source (T9).
- **createToken:** `amount` tokens of `token` (a fresh `DuelCard` with `token: true`, uid `t:<n>`); `condition.maxTokens` = only if you control fewer tokens than that. Tokens leaving play cease to exist.
- Triggers resolve immediately: the active player's first, then in entry order.
## Rules (defaults: `DEFAULT_DUEL_RULESET`; details in DUEL_DESIGN §2)
- 40-card decks (`deckSize`), ≤ 4 per `pageId`, unique `cardId`s, no tokens. 20 Notability. Drawing from an empty library loses (`libraryEmpty: 'lose'`; `'reshuffle'` and `'fatigue'` exist as data).
- Opening hand 7. Up to `mulligans` (1): shuffle in, draw 7, then on `keep` put one card per mulligan on the bottom (the last in hand order). Seat 0 decides first, then seat 1.
- First player (from the seed) skips their first draw. Balance levers (data only): `firstPlayerDraws`, and `secondPlayerCitations` (extra Citations on the second player's first turn; default 1 from balance v1, #64).
- **Turn:** refresh (base max +1 to 10, plus Territory ≤ 2; refill; untap; Pending review ends; Stub and `startOfTurn` triggers) → draw → **main** → **attack** → **block** → damage → end (damage and "until end of turn" clear; discard down to `handSize` 7, **highest cost first**, automatically).
- Locations: `locationsPerTurn` (1), can't attack. Garrison Locations (toughness > 0) block as 0-power.
- Combat: attack the opponent only; each blocker blocks one attacker, at most one blocker per attacker; simultaneous damage; destroy triggers after all combat damage. No trample, first strike, stack or instants.
- **Connected** (engine, from `connect`, tiers in `connectedTiers`): Linked (either `links` contains the other's `pageId`, or either `cites` contains the other's `qid`), Compatriot (shared country), Contemporary (shared century, different types), Kin (shared P31, not Q5/Q16521). A Figure gets the single best bonus among other permanents its controller controls: `+linkedBonus` (2) if Linked, else `+connectedBonus` (1). Logged once (`connected`). Opposing Connected pairs are logged once as `rivalry`.
- **Timeouts:** `timeout` passes (mulligan: keep; main/attack: end the turn without attacking; block: confirm current blocks). `timeoutsToConcede` (3) consecutive timeouts by one seat lose (`reason: 'timeout'`).
- `turnCap` (default 40 total turns from balance v1, #64; `null` = none): after that many total turns, higher Notability wins, then higher total power in play, then the second player.
## Phases and actions
| Phase | Who acts | Listed actions |
|---|---|---|
| `mulligan` | seat 0 until ready, then seat 1 | `keep`, `mulligan` |
| `main` | active | `play {uid, targets?}`, `endPhase` |
| `attack` | active | `toggleAttacker {uid}` (untapped, not Pending review, not yet declared), `confirmAttack` |
| `block` | defender | `block {blocker, attacker}` (unassigned blocker, unblocked attacker, evasion allowing), `confirmBlocks` |
| any | either seat | `concede` (not listed) |
| any | host, for the seat to act | `timeout` (not listed) |
Declarations are **monotonic** (no un-declare), so every turn has a bounded number of actions; UIs stage choices locally and send them on confirm. If the defender has no legal block, damage resolves at `confirmAttack` with no block phase. `confirmAttack` with no attackers ends the turn.
## Views and log
- `viewFor(state, seat): PlayerView`: your hand; the opponent's hand and library **sizes** only; both graveyards; the battlefield with current power/toughness, keywords and Connected badge; combat; `toAct`; `version`; `result`. Never the RNG or library order.
- **The seed is secret until the match ends.** `seed` plus the deck lists reproduce every shuffle, so the host never sends `seed` or `rng` (or the raw `DuelState`) to clients before `gameOver`. Live log rendering picks template variants from a derived `storySeed = sha256(seed + ':story')`.
- `state.log` is omniscient (server, and the recap after the match). Clients get **`logFor(state, seat)`**: the opponent's `draw` events have no `card`. Every other event is public information.
- Every event has `seq` and `turn`. `CardRef` carries `uid, cardId, title, pageId, type` plus `power`/`toughness` right after the event.
- Kinds (DUEL_DESIGN §10 names): `start, mulligan, keep, turnStart, draw, deploy, cast, adopt, tokenCreated, connected, rivalry, effect, attack, block, effectDamage, combatDamage, playerDamage, lifeGain, destroyed, bounced, discard, fatigue, concede, timeout, gameOver`. `destroyed` = the recap's casualties. Prose templates live with duel-design / ui-pvp, not in the engine.
## Host binding
`duelEnginePort` (engine.ts) is structurally an `EnginePort<DuelRuleset, DuelCard, DuelState, DuelAction>` (`server/game/engine-port.ts`; `shared/` doesn't import `server/`, so host-pvp types it there). `concedeAction`, `timeoutAction`, `turnSeconds`, `turnOf`, `applyLive` included. `starterDeck` and `previewPool` throw: there are no starters (BRIEF decision 2); draft pools come from both players' collections.
## Stability
These types are the contract for duel-cards, host-pvp, ui-duel, ui-pvp and sim-balance. Additive changes (optional fields, new log kinds) can land with the engine; breaking ones get a `[duel-core] contract change` comment on #55 first.
+279
View File
@@ -0,0 +1,279 @@
# WikiDeck Duel: design v1
**Status:** v1.3, Night 2 (2026-11-17): v1 plus night-review's nits on PR #66, duel-cards' implementation choices from PR #70, and the balance v1 rules `secondPlayerCitations` 1 and `turnCap` 40 (#64). Owner: duel-design (issue #60).
**Base:** `docs/night2/BRIEF.md` (Eric's locked decisions). Where this file and BRIEF disagree, BRIEF wins. Reviews used: designer (rules), data §2–4 (derivation), critic S7 (tone).
**Consumers:** duel-core (`shared/duel/` engine and `types.ts`), duel-cards (`classify/derive/effects/text.ts`), sim-balance (bots, `DUEL_BALANCE.md`), ui-duel / ui-pvp (faces, recap), host-pvp (rulesets).
Every number in this file is a **ruleset key or a derivation table value**, not code. sim-balance tunes them in data-only PRs.
---
## 1. The game in one paragraph
Two players each bring **40 cards they own on-chain**. Each card is a Wikipedia article turned into a Magic-style card by fixed rules over real data. You start at **20 Notability**. Every turn your **Citations** (mana) maximum rises by one. You deploy Figures, attack with them, block with yours, cast Events, adopt Doctrines onto Figures. The first player to 0 Notability, or unable to draw, loses. The match is written up afterwards as an encyclopedic "Battle of X (2026)" page.
---
## 2. Rules
### 2.1 Decks and eligibility (BRIEF decisions 1–2)
| Key | Default | Rule |
|---|---|---|
| `deckSize` | **40** | Exactly this many cards. Every card is an NFT the player owns (server-verified by `ownership.ts`). No Basics, loaners, proxies or tokens in decks. |
| `maxCopiesPerPage` | **4** | Different mints of the same `pageId` may appear up to 4 times (each mint once: it is unique). |
| colour/Portal rules | none | Any mix of Portals. |
| Eligibility | owns ≥ `deckSize` | Below it, the UI shows "23 / 40 cards" and how to mine. No practice with borrowed cards. Bot matches need eligibility too. |
Testnet end-to-end mode files may lower `deckSize`. Production stays at 40.
### 2.2 Setup
- **Notability** (life): `startingLife` **20**. At 0 you lose.
- **Empty library:** drawing from an empty library loses (`libraryEmpty: 'lose'`).
- **Opening hand:** `openingHand` **7**. One mulligan (`mulligans: 1`): shuffle, draw 7, put 1 on the bottom.
- **First player** (seeded coin flip) skips their first draw.
- **Second player** gets +1 Citation maximum on their first turn only (`secondPlayerCitations` **1**). Balance v1: this moved the first-player win rate from 60.1% to 54.4% in 1,500 heuristic-mirror matches (engine 4623930, #64). Neither an extra opening card (washed out by the mulligan and the hand limit) nor `firstPlayerDraws` worked.
### 2.3 Turn structure: refresh → draw → main → combat → end
1. **Refresh.** Citation maximum +1 (to `maxCitations` **10**), plus Territory (§2.5). Citations refill to the maximum. Your permanents untap. "Pending review" ends for your Figures. Start-of-turn triggers (Stub, Institutions) resolve in the order the permanents entered.
2. **Draw** 1 card.
3. **Main.** Play cards in any order while you can pay their cost in Citations: Figures, Locations (one per turn: `locationsPerTurn` 1), Institutions, Doctrines (attach to a Figure), Events (resolve immediately).
4. **Combat** (§2.4).
5. **End.** Damage on permanents clears. "Until end of turn" effects end. Discard down to `handLimit` **7** (the player chooses; bots discard highest cost first).
**Zones.** Library and hand are hidden (a hand's size is public). The battlefield and **Deleted** (the graveyard) are **public**: a discarded card is revealed and named once it reaches Deleted.
There is **no second main phase, no stack, no priority and nothing at instant speed.** Events are sorcery-speed. Triggers resolve immediately, in a fixed order: the active player's first, in the order the cards entered.
### 2.4 Combat
- **Attack:** the active player chooses any untapped Figures without Pending review and taps them. They attack the opponent only, never permanents.
- **Block:** the defender assigns **at most one blocker per attacker**, and each blocker blocks one attacker. Untapped Figures and Garrison Locations may block. Evasion (Featured) restricts who may block: **a Garrison Location can't block a Featured attacker** (only Featured, Translated or Multilingual Figures can).
- **Damage:** simultaneous. A blocked pair deal their power to each other. An unblocked attacker deals its power to the defending player's Notability.
- A permanent with damage ≥ toughness is **destroyed** (goes to the Deleted pile, the graveyard). Destroy triggers (Legacy) fire after all combat damage.
- No trample, no first strike, no deathtouch, no lifelink in v1.
### 2.5 Card types (BRIEF; classifier in data §1, built by duel-cards)
| Type | MTG analogue | Rules |
|---|---|---|
| **Figure** | creature | Power/toughness. Enters with **Pending review** (summoning sickness): can't attack until your next turn. |
| **Location** | land-ish permanent | Cost `ceil(derivedCost/2)` (1–3). **Territory:** +1 Citation maximum while you control it; at most **+2 in total** from Territory (`territoryCap` 2). **Garrison 0/T:** can block like a 0-power Figure (T = 1 + floor(pct_depth / 25), so 1–4). Can't attack. Damage clears at end of turn as usual; a Location destroyed in a block goes to Deleted. One per turn. |
| **Event** | sorcery | Resolves at once, then goes to Deleted. |
| **Institution** | artifact | A permanent with a static or triggered ability. |
| **Doctrine** | Aura | **Adopt:** attach to target Figure (yours or the opponent's for negative Doctrines). If the Figure leaves play, the Doctrine goes to Deleted. |
Classification order (duel-cards owns it): P31 → P279 anchor classes → P31 label regex (`^human$`, fixing the `\bhuman\b` bug) → categories → description → **Doctrine**. The derived profile is **frozen** the first time a card is seen.
### 2.6 Clock and length
- `turnSeconds` **60** per turn plus `bankSeconds` **300** per player. The turn timer runs first; when it expires, the player's bank drains; when the bank is also empty, the turn passes (`timeout` action). The bank does not refill. Three timeouts in a row concede.
- **`turnCap` 40** (20 turns each, balance v1). At the cap the higher Notability wins, then the higher total power in play, then the second player. In sims it decides about 4% of games and removes every game past 20 turns each, without moving the median.
- **Sim targets** (agreed with sim-balance, #64): median 8–12 turns each; first-player win rate 48–54%; < 5% of games past 20 turns each. **Balance v1 result** (`secondPlayerCitations` 1 + `turnCap` 40; 3,000 heuristic-mirror matches, engine 4623930, duel-cards 067de83; run by ui-duel for sim-balance, #64): first player **54.7%** [53–57], turns each 6 / 8 / 12, 0% past 20, about 8 minutes median.
### 2.7 Determinism
All randomness (shuffles, coin flip, template variants) comes from the match seed via `shared/game/rng.ts`. The same seed and actions always replay to the same state, log and recap.
---
## 3. Derivation summary (duel-cards implements; data §2)
- **Percentiles** `pct_a`, `pct_d`, `pct_r` from the sample cut points (DESIGN.md §1.1 counting). **fame** = mean of the three, rounded.
- **Cost** 1–6 by `costThresholds` [26, 39, 51, 63, 78].
- **Figure body budget** P+T = [3, 4, 6, 8, 10, 12] for cost 1–6 (MTG vanilla curve). Subtract **1 per taxed keyword** (§4). At cost 1, a second taxed keyword is skipped, so a body never drops below 1/1. Then `power = clamp(round(budget × pct_a / (pct_a + pct_d)), 1, budget − 1)`, toughness = the rest. Famous cards are bigger and pricier, never more efficient.
- **Magnitude** for non-Figures: `k = ceil(cost / 2)` (1–3).
- **Portal** (faction): Arts, Earth, History, Science, Society, or Neutral, scored by regex hits (designer §3.2); ties go to the type default (Figure → Society, Location → Earth, Event → History, Institution → Arts, Doctrine → Science). No deckbuilding restriction.
- **Flavour text:** first sentence of on-chain `article.extract`; if absent (the sample has none), the Wikidata `description`; if that is empty too, none.
---
## 4. Keywords (10)
Eight card keywords, each triggered only by real data and applied **to Figures only**, at most **2 per card** in the priority order below. Plus two rules keywords. Thresholds are measured on the 236-card sample (86 Figures); sim-balance may move them.
| # | Keyword | Trigger (real data) | Rules text | Body tax | Rate among Figures |
|---|---|---|---|---|---|
| 1 | **Protected** | category `Living people` | Can't be the target of Events or Doctrines an opponent controls. | 1 | 38% |
| 2 | **Featured** (flying) | pct_attention ≥ 85 | Can't be blocked except by Featured, Translated or Multilingual Figures. | 1 | 15% |
| 3 | **Legacy** | a `<year> deaths` category (or P570 in the frozen profile) | When this is destroyed, draw a card. | 1 | 33% |
| 4 | **Multilingual** | pct_reach ≥ 90 | Can block Featured Figures. Can't be blocked by Local Figures. | 1 | ~5% |
| 5 | **Translated** (reach) | 75 ≤ pct_reach < 90 | Can block Featured Figures. | 0 | 19% |
| 6 | **Well-sourced** | pct_depth ≥ 85 | Prevent the first 1 damage that would be dealt to this each turn. | 1 | ~13% before cap |
| 7 | **Stub** | pageBytes < 3000 or a `…stubs` category | At the start of your turn, put a +1/+1 counter on this, to a maximum of 2. | 0 | 33% |
| 8 | **Local** | raw reach = 0 (no other language editions) | Gets +1/+1 while you control a Compatriot Location (same P17). | 0 | 7% before cap |
| 9 | **Connected** | the card pair's frozen claims and links (§6) | +1/+1 while you control another card Connected to it; +2/+2 if Linked. | – | target 15–30% of pairs |
| 10 | **Trending** (haste) | Trending mode only: frozen live ▲ (trend ≥ +25% and daily ≥ 20) | Can attack the turn it enters. Gets +1/+0. | – | ~2% of cards |
Rule words that are not keywords: **Pending review** (summoning sickness), **Territory**, **Garrison**, **Adopt**, **Deleted** (the graveyard).
Notes:
- Protected deliberately sits first: living people are the most targeted, and the rule that matters most for them is mechanical, not a tone rule. It doesn't stop combat.
- Multilingual and Translated are two bands of the same reach axis, so a card never has both.
- A card's face shows at most 2 keyword words; the reminder text is behind a tap.
---
## 5. Effect templates (12, MTG register)
Subtype regexes run over the frozen P31/P279 labels, then the description, then categories. First match wins, in the order listed. `k = ceil(cost/2)`.
| # | Type / subtype | Trigger regex (labels, description) | Rules text |
|---|---|---|---|
| T1 | Figure | (all Figures) | Vanilla body + keywords. No other text. |
| T2 | Location | (all Locations) | Territory. Garrison 0/T. |
| T3 | Event: conflict | `battle\|war\|siege\|annexation\|protest\|riot\|uprising\|massacre\|coup` | Deal k+1 damage to target Figure or Location. |
| T4 | Event: disaster | `storm\|nor.easter\|cyclone\|hurricane\|earthquake\|flood\|tornado\|wildfire\|eruption\|famine\|epidemic` | Deal k−1 damage (minimum 1) to each Figure and each Location. |
| T5 | Event: election | `election\|referendum\|straw poll` | Create k 1/1 Society Figure tokens named Elected Member. |
| T6 | Event: sport | `match\|final\|season\|tournament\|championship\|grand prix\|race` | Target Figure you control gets +k/+0 until end of turn, then fights target Figure you don't control. |
| T7 | Event: default (period, ceremony, scandal, other) | anything else | Draw k cards. |
| T8 | Institution: organisation | `company\|organi[sz]ation\|party\|agency\|studio\|military\|university\|diocese\|council\|band\|musical group\|association\|business\|school\|college\|institute\|manufacturer` | Cost ≥ 4: "At the start of your turn, if you control fewer than 3 tokens, create a 1/1 Figure token named Staff Member." Cost ≤ 3: "When this enters, create a 1/1 Figure token named Staff Member." |
| T9 | Institution: creative work | `film\|album\|song\|book\|novel\|series\|video game\|painting\|software\|typeface\|newspaper\|magazine` | When this enters, draw a card. Figures you control that are Connected to this get +1/+1. |
| T10 | Institution: team, award, vehicle, other | anything else | Figures you control with power 2 or less get +1/+0. |
| T11 | Doctrine: Adopt | (all non-Pathology Doctrines) | Attach to target Figure you control. It gets +k/+k. Rider by subtype, checked in the order pathology (→ T12) > language/software > mathematics, so "functional programming language" is not maths: mathematics → "and has Well-sourced"; language/software → "Whenever it deals combat damage to a player, draw a card"; ideology/religion → "Other Figures you control of its Portal get +1/+0"; otherwise none. |
| T12 | Doctrine: Pathology | `disease\|clinical sign\|pathogen\|syndrome\|disorder\|toxin\|poison` | Attach to target Figure. It gets −k/−k. |
Elected Member tokens are Society; Staff Member tokens have no Portal ("1/1 Figure token"). Tokens are not cards: they never appear in decks, are created only by T5/T8, and are removed when they leave play. Token names are fixed generic strings, never real people.
Rules-text style:
- Second person, present tense, MTG terse register: "Deal 3 damage to target Figure."
- Card names appear in rules text only as "this" (never the article title), so text stays the same length on a 360 px face.
- No adjectives, no puns, no exclamation marks.
---
## 6. Connected (data §4 tiers)
Computed by the host at match start from frozen card profiles. No network calls during a match; the edge list is written into the match record.
| Tier | Test | Bonus | Cut order |
|---|---|---|---|
| **Linked** | either article links to the other (cached outlinks), or one card's claims cite the other's Q-id | +2/+2 | keep |
| **Compatriot** | share a P17 (country) or P27 (citizenship) value | +1/+1 | keep |
| **Contemporary** | same century from P569/P570/P571/P580/P585, **only between different types** | +1/+1 | cut 4th (BRIEF) |
| **Kin** | same P31 class, excluding Q5 human and Q16521 taxon | +1/+1 | cut 4th (BRIEF) |
- A Figure gets the **single best** bonus among its Connected cards you control (no stacking): +2/+2 if any is Linked, else +1/+1.
- A Connected creative-work Institution (T9) gives its +1/+1 on top.
- **Target:** 15–30% of random card pairs connected (text proxies measured 21.5% for country OR century). If sims show more, drop the noisiest keys first (P17 = United States, then France); if fewer, add P131.
- The card shows why: "Connected — *Pathrail Mosque* (country: Bangladesh)".
- **Rivalry** (log only): when two opposing cards are Connected, the log may note it once (§8.3). No mechanical effect.
---
## 7. Modes (on the duel engine)
| Mode | Decks | Notes |
|---|---|---|
| **Classic** | constructed from your own 40+ owned cards | Ranked (Elo, keyed to the eom.dev account). Invite links and quick match. |
| **Bot** | your own 40 | Only for eligible players. Not ranked. |
| **Draft** | both players eligible | Pool drawn from both players' collections (e.g. 30 cards from each, shuffled into one pool). Snake-pick until each has `deckSize`. Drafted cards are used for that match only; nothing moves on-chain. Ownership is credited in the recap ("from the collection of bob"). |
| **Trending** | any | Live pageview trend from the daily cache, frozen at match start: ▲ (≥ +25%, daily ≥ 20) gives Trending (haste, +1/+0); ▼ (≤ −50%, daily ≥ 20) gives −1/−0. Cut 3rd. |
| **House rules** | peer-hosted | Data-only, versioned schema. Keys: `deckSize`, `maxCopiesPerPage`, `startingLife`, `openingHand`, `mulligans`, `maxCitations`, `territoryCap`, `handLimit`, `turnSeconds`, `bankSeconds`, `turnCap`, `secondPlayerCitations`, `connectedTiers`, `keywordThresholds`. Night 1 mode files are rejected cleanly with a message. |
---
## 8. Tone and story text
### 8.1 Tone rules (BRIEF decision 5, critic S7)
1. **Lean in.** Living people, tragedies, wars, disasters, crimes, diseases and dictators are ordinary cards with full mechanics. No `solemn` flags, no special cases, no softened verbs. "Casualties" is fine. A protester shot in 1970 is a 6/3 with Legacy like anything else.
2. **Deadpan.** The text takes itself completely seriously. It **never winks** and **never comments on the matchup** ("in a surprising twist", "unlikely", "ironically" are banned). The comedy lives in the nouns: "*Heart rot* was adopted by *Tom Ewell*."
3. **Encyclopedic texture.** Past tense, third person, passive where Wikipedia would use it, dates and turn numbers, and `[n]` citations linking each card's real article at its revision.
4. **No adjectives about cards or players** (no "brutal", "heroic", "humiliating", "bloodiest"). Mechanical verbs only: deployed, attacked, blocked, was destroyed, was adopted by, took N damage, was cited.
5. **Never invent facts about real people.** All generated text is a deterministic template filled **only** with real card data (title, description, dates, categories, revision id) and real match data (turn, players, numbers). No LLM prose. No made-up quotes, crimes, acts, motives or feelings. The template verbs describe **game events of the card**, and every narrative paragraph is framed as a WikiDeck engagement; the footer says so.
6. **Allowed real data in text:** title, Wikidata `description`, birth/death years parsed from the description or frozen claims, the first extract sentence (flavour), Portal, type. Nothing else about a person.
7. **Dull guard:** 3–4 synonymous variants per event, chosen by the match seed (§8.2).
| DO | DON'T |
|---|---|
| "Turn 6. *Zbyszek Godlewski* (6/3) attacked. *Pallas's cat* (5/5) blocked. *Zbyszek Godlewski* was destroyed.[3][4]" | "Godlewski got mauled by a cat lol" |
| "The *April 2021 nor'easter* dealt 1 damage to each Figure. *Dichromorpha viridis* was destroyed.[5][6]" | "Mother Nature wiped out the poor grasshopper!" |
| "*Heart rot* was adopted by *Tom Ewell*, which became a 2/2.[7][8]" | "Ewell caught a tree disease, how embarrassing" (adjective + invented claim) |
| "The **Battle of Pathrail Mosque (2026)** was a WikiDeck engagement fought on 17 November 2026 between the forces of alice and bob." | "the bloodiest battle in WikiDeck history" |
### 8.2 Match-log templates (`shared/duel/story/log.ts`)
- One template group per engine `LogEvent` kind, each with **3–4 variants**. Variant = `rng(seed, turn, eventIndex) mod n`, using the match seed, so `replay` regenerates the log exactly.
- First mention of a card in a match adds its description in parentheses: "*Tom Ewell* (American actor, 1909–1994)". Later mentions use the title only.
- Each first mention of a card assigns it the next reference number `[n]`; later mentions reuse it.
- `logFor(seat)` hides the opponent's hand: their draws read "bob drew a card." and mulligans are not named. Discards are named, because Deleted is public (§2.3).
| Event | Variants (`{card}` italic, `{player}` the seat name) |
|---|---|
| deploy (Figure/Location/Institution) | "{player} deployed {card}." · "{card} was deployed by {player}." · "{player} brought {card} into play." · "{card} entered play under {player}." |
| event cast | "{player} cited {card}." · "{card} was cited by {player}." · "{player} invoked {card}." |
| adopt | "{doctrine} was adopted by {figure}, which became a {p}/{t}." · "{figure} adopted {doctrine} and became a {p}/{t}." · "{player} attached {doctrine} to {figure} ({p}/{t})." |
| attack | "{card} ({p}/{t}) attacked." · "{player} sent {card} ({p}/{t}) into combat." · "{card} ({p}/{t}) advanced on {opponent}." |
| block | "{blocker} ({p}/{t}) blocked {attacker}." · "{attacker} was blocked by {blocker} ({p}/{t})." · "{blocker} ({p}/{t}) intercepted {attacker}." |
| player damage | "{opponent} lost {n} Notability ({life} remaining)." · "{card} dealt {n} damage to {opponent}, leaving {life} Notability." · "{opponent}'s Notability fell to {life}." |
| destroyed | "{card} was destroyed." · "{card} was moved to Deleted." · "{card} was removed from play." · "{card} did not survive the turn." |
| effect damage | "{source} dealt {n} damage to {target}." · "{target} took {n} damage from {source}." · "{source} inflicted {n} damage on {target}." |
| token created | "{source} produced {n} {token}." · "{n} {token} were created by {source}." · "{source} created {n} {token}." |
| draw (own) | "{player} drew {card}." · "{card} was drawn." · "{player} added {card} to their hand." |
| draw (hidden) | "{player} drew a card." · "{player} drew {n} cards." |
| Connected | "{a} and {b} were Connected ({reason})." · "{a} was Connected to {b} through {reason}." · "Records link {a} and {b} ({reason})." |
| discard | "{player} discarded {card}." · "{card} was discarded by {player}." · "{player} moved {card} from hand to Deleted." |
| rivalry (opposing Connected pair, once) | "{a} and {b} are both listed under {reason}." · "{a} and {b} share {reason}." · "The two sides were linked through {reason}." |
| turn start | "Turn {n}." (fixed) |
| game over | "{loser} was nominated for deletion. The result was **delete**." · "{loser} was reduced to 0 Notability. {winner} won." · "{winner} won on turn {n}." · (library) "{loser} could not draw a card and lost." · (concede) "{loser} withdrew." |
### 8.3 Battle recap (`shared/duel/story/recap.ts`)
A deterministic function `recap(matchRecord) → RecapDoc` (structured data; ui-pvp renders it). Inputs are the match record only: seed, players, decks' frozen card profiles, the event list, the date. No network, no clock.
**Title:** "{Prefix} {Name} ({year})"
- **Name:** the winner's highest-cost Location that entered play; else the loser's; else the highest-cost Event cast in the match; else the winner's highest-cost card deployed; ties broken by first played. Living people and tragedies are eligible like any card ("Battle of Zbyszek Godlewski (2026)" is valid).
- **Prefix:** "Skirmish at" (≤ 6 turns each), "Battle of" (7–12), "Siege of" (≥ 13). For a Figure name: "Battle of" becomes "{Name} campaign" (no prefix).
- **Year:** the match date's year (2026).
**Infobox:**
| Field | Value |
|---|---|
| Date | the match date, "17 November 2026" |
| Location | the Name card if it's a Location, else "WikiDeck host {hostName}" |
| Result | "Decisive {winner} victory" (margin ≥ 10 Notability) · "Pyrrhic {winner} victory" (winner ≤ 3) · "{winner} victory" · "{winner} victory by withdrawal" (concession/timeout) · "{winner} victory by attrition" (empty library) · "Victory by decision" (turn cap) |
| Belligerents | the two seat names (account display names) |
| Commanders | each side's highest-cost Figure deployed |
| Strength | cards deployed per side ("14 cards") |
| Casualties and losses | cards destroyed per side, count, then the titles |
**Sections:**
1. **Lead** (1 paragraph): "The {title} was a WikiDeck engagement fought on {date} between the forces of {a} and {b}. It lasted {n} turns and ended in {result-lowercase}.[1]" + one sentence on the first Figure deployed: "Contemporary accounts note the deployment of {card} in the {ordinal} turn.[n]"
2. **Background:** each side's Portal mix ("History was the largest Portal in the force of alice (eleven of twenty cards played)").
3. **Course of the battle:** the 3–5 largest Notability swings and every destroyed card with cost ≥ 4, in turn order, as log sentences (variants from §8.2, but seeded with `seed ⊕ 'recap'` so the recap doesn't repeat the log word for word).
4. **Aftermath:** final Notability, turns, rating change if ranked.
5. **See also:** Connected pairs and rivalries.
6. **References:** every card played by either side, in first-mention order: "{n}. ^ "{title}". Wikipedia. Revision {revisionId}. Minted as token {tokenId}." linking `https://en.wikipedia.org/w/index.php?title={title}&oldid={revisionId}`.
**Branding and footer:** WikiDeck masthead, never the Wikipedia/Wikimedia name or logo. Footer: "This page records a WikiDeck match. Card names refer to Wikipedia articles; the events described are game events." Shareable at `/recap/{matchId}`.
---
## 9. Worked examples (12 cards from `docs/game/card-sample.json`)
Computed with the rules above (data §2 budget, §4 keyword priority, §5 templates) by a script over the sample, and checked by hand. duel-cards' implementation (PR #70) agrees on all 12, with the two Portal corrections now applied (#9, #11). Flavour is the `description` because the sample has no extracts. Final numbers come from duel-cards' implementation; if they differ, the implementation and its golden test win and this table is updated.
| # | Card | Derivation | Card |
|---|---|---|---|
| 1 | **Marc Fesneau** (living person) | P31 human → Figure. "politician" → Society. pct 76/68/63 → fame 69 → cost 5, budget 10. Living people → Protected (−1) → 9 split 76:68 → 5/4. | **Marc Fesneau** · 5 · Figure — Society · **5/4** · *Protected.* "French politician (born 1971)." |
| 2 | **Tom Ewell** | human → Figure, Arts. 94/83/93 → fame 90 → cost 6, budget 12. Featured (−1), Legacy (−1); Multilingual dropped by the cap. 10 → 5/5. | **Tom Ewell** · 6 · Figure — Arts · **5/5** · *Featured. Legacy.* "American actor (1909–1994)." |
| 3 | **Zbyszek Godlewski** (killed at a 1970 protest) | human → Figure, History. 77/48/78 → fame 68 → cost 5. Legacy (1970 deaths, −1), Translated (pct_r 78, 0). 9 split 77:48 → 6/3. | **Zbyszek Godlewski** · 5 · Figure — History · **6/3** · *Legacy. Translated.* "Polish protester (1952–1970)." |
| 4 | **Pallas's cat** | taxon → Figure, Earth. 99/97/99 → fame 98 → cost 6. Featured (−1), Multilingual (−1); Well-sourced dropped. 10 → 5/5. | **Pallas's cat** · 6 · Figure — Earth · **5/5** · *Featured. Multilingual.* "Species of small wild cat." |
| 5 | **Dichromorpha viridis** | taxon → Figure, Earth. 58/3/53 → fame 38 → cost 2, budget 4. Stub (1,347 bytes, untaxed). Split clamps to 3/1. | **Dichromorpha viridis** · 2 · Figure — Earth · **3/1** · *Stub.* "Species of grasshopper." |
| 6 | **Monoid** (maths) | no P31; category "Algebraic structures" → Doctrine, Science. fame 96 → cost 6, k = 3. Maths rider. | **Monoid** · 6 · Doctrine — Science · Attach to target Figure you control. It gets +3/+3 and has Well-sourced. "Algebraic structure with an associative operation and an identity element." |
| 7 | **Heart rot** (disease) | P31 plant disease → Doctrine, Pathology (T12). Science. fame 68 → cost 5, k = 3. | **Heart rot** · 5 · Doctrine — Science · Attach to target Figure. It gets −3/−3. "Fungal disease of trees." |
| 8 | **April 2021 nor'easter** (disaster) | P31 nor'easter → Event, disaster (T4). Earth. fame 50 → cost 3, k = 2. | **April 2021 nor'easter** · 3 · Event — Earth · Deal 1 damage to each Figure and each Location. "Slow-moving nor'easter in April 2021." |
| 9 | **2025 Tehreek-e-Labbaik Pakistan protests** (conflict) | P31 protest → Event, conflict (T3). Society (protest/riot hits outnumber "war"). fame 64 → cost 5, k = 3. | **2025 Tehreek-e-Labbaik Pakistan protests** · 5 · Event — Society · Deal 4 damage to target Figure or Location. "Gaza war protests in Pakistan." |
| 10 | **1954 Gold Coast general election** | P31 legislative election → Event, election (T5). Society. fame 45 → cost 3, k = 2. | **1954 Gold Coast general election** · 3 · Event — Society · Create two 1/1 Society Figure tokens named Elected Member. *(no flavour: empty description)* |
| 11 | **Pathrail Mosque** | P31 mosque → Location, Society ("mosque" hits in P31, the description and two categories outnumber 15th-century + Sultanate). fame 49 → cost 3 → Location cost 2. pct_d 54 → Garrison 0/3. | **Pathrail Mosque** · 2 · Location — Society · Territory. Garrison 0/3. "Mosque in Faridpur, Bangladesh." |
| 12 | **Tatsunoko Production** | P31 animation studio → Institution, organisation (T8). Arts. fame 93 → cost 6. | **Tatsunoko Production** · 6 · Institution — Arts · At the start of your turn, if you control fewer than 3 tokens, create a 1/1 Figure token named Staff Member. "Japanese animation studio." |
Interactions these cards show:
- *Heart rot* on *Marc Fesneau* is illegal (Protected stops opponents' Doctrines). On *Tom Ewell* it makes a 2/2 Featured Legacy.
- *Monoid* on *Dichromorpha viridis* makes a 6/4 Well-sourced Stub that keeps growing to 8/6.
- *April 2021 nor'easter* destroys *Dichromorpha viridis* and both Elected Members, and leaves *Pathrail Mosque* at 0/3 with 1 damage.
- *Pathrail Mosque* and *2025 Tehreek-e-Labbaik Pakistan protests* are not Compatriots (Bangladesh vs Pakistan); *Pathrail Mosque* and *Zbyszek Godlewski* are not Contemporary (15th vs 20th century).
Sample log:
> Turn 5. alice deployed *Zbyszek Godlewski* (Polish protester, 1952–1970).[1]
> Turn 6. bob cited the *April 2021 nor'easter* (Slow-moving nor'easter in April 2021).[2] The *April 2021 nor'easter* dealt 1 damage to *Zbyszek Godlewski*.
> Turn 7. *Zbyszek Godlewski* (6/3) attacked. *Pallas's cat* (5/5) blocked *Zbyszek Godlewski*.[3] *Zbyszek Godlewski* was destroyed. alice drew a card.
---
## 10. Hand-offs
- **duel-core:** §2 rules and ruleset keys; `LogEvent` kinds needed by §8.2 (deploy, cast, adopt, attack, block, playerDamage, destroyed, effectDamage, tokenCreated, draw, connected, turnStart, gameOver with reason `life|library|concede|timeout|turnCap`). Each event carries card ids, P/T after the event, and Notability where relevant.
- **duel-cards:** §3 derivation, §4 thresholds and priority, §5 templates T1–T12, §6 tiers; the §9 table as golden tests.
- **sim-balance:** §2.6 targets; tune `keywordThresholds`, `connectedTiers`, T4's k−1, the Stub cap and the T8 token rate; report the first-player win rate and the cost-6 dominance check.
- **ui-pvp:** renders `RecapDoc` from §8.3.
## 11. Open questions for the sim (not blockers)
1. Disaster T4 at k−1 may be weak against 40-card boards; try k.
2. Stub at +2 counters on cheap bodies may be too strong (33% of Figures); try max 1.
3. **Locations (balance v1 finding):** Location-heavy decks win ~20% and Locations are the weakest cards. `territoryCap` 3, `locationsPerTurn` 2 and `garrisonStep` 15 move them ±3 points at most. Tested and **rejected for v1**: a T2 rider "When this enters, draw a card". It lifts the Location card (47 → 52%) but not Location-heavy decks (18 → 17%), pushes the first player back to 58.4%, and brings back library-out losses. Open for v1.1: a lever that helps Location-heavy decks without extra card flow, e.g. Territory that scales (+1 Citation per two Locations) or Garrison Locations that can block Featured.
+232
View File
@@ -0,0 +1,232 @@
# WikiDeck game engine API (v1)
**Owner:** engine-a (core and API) and engine-b (keywords, card derivation, tests). Issue: claude/wikideck#3.
**Rules:** `docs/game/DESIGN.md` v1 ("Edit War", as frozen in PR #17 @ cf2fceb). Where this file and DESIGN.md disagree, raise it on #3.
**Stability:** UI, simulation and modes build against this file. Any change to a name or shape below is
announced on #3 before it merges.
The engine is a pure TypeScript library in `shared/game/`:
- It does no I/O and has no clocks: no `Date.now()`, no `Math.random()`.
- It imports nothing from `server/` or `src/`.
- It runs entirely **off-chain**. A match never reads, moves, locks or burns an NFT.
- It is deterministic: the same `(ruleset, decks, seed, actions)` always gives the same state, byte for byte.
**Import only from `shared/game/index.ts`.**
```ts
import { createMatch, legalActions, applyAction, isOver, result, viewFor,
serialize, deserialize, replay, DEFAULT_RULESET, parseRuleset, validateDeck,
starterDeck, previewPool, type MatchState, type Action, type GameCard } from '../shared/game/index.ts';
```
## 1. Lifecycle
```ts
let state = createMatch(DEFAULT_RULESET, [deck0, deck1], seed); // turn 1, planning
while (!isOver(state)) {
// Each seat (in any order, any interleaving) queues plays, then commits.
const actions = legalActions(state, seat); // play / undo / commit
state = applyAction(state, chosen); // returns a NEW state
// When both seats have committed, the turn resolves inside applyAction.
}
const r = result(state); // { winner: 0 | 1 | null, reason, topicsLed, lanePower, totalPower, turns }
```
| Function | Description |
|---|---|
| `createMatch(ruleset, [deck0, deck1], seed: number \| string): MatchState` | Validates the ruleset (`parseRuleset`) and both decks (`validateDeck`), then performs DESIGN §4 setup and turn-1 start. A `seed` is a uint32. A string is hashed with FNV-1a (`seedFromString`). Throws `ZodError` for a bad ruleset and `IllegalActionError` for a bad deck. |
| `legalActions(state, seat): Action[]` | Lists every `play` (each card × each lane it can legally go into), every `undo`, and `commit`. Returns `[]` once the seat has committed or the match is over. It never lists `concede` (always legal while the match is running) or `timeout` (host only). |
| `applyAction(state, action): MatchState` | Pure: the input is never mutated. Throws `IllegalActionError` if the action is illegal. |
| `actionProblem(state, action): string \| null` | Explains why an action is illegal, without throwing. Use it for UI hints and for validating client input on a host. |
| `isOver(state)` / `result(state)` | `result` is `null` while the match is running. |
| `viewFor(state, seat): PlayerView` | The **hidden-information view**. Send only this to clients and AIs, never `MatchState`, because a `MatchState` contains both deck orders and the RNG state. |
| `serialize(state): string` / `deserialize(json): MatchState` | Lossless JSON. `MatchState` is plain data. |
| `replay(ruleset, decks, seed, actions): MatchState` | Rebuilds a match from its inputs. `state.actions` records every action applied, so a host can store `(ruleset, decks, seed, actions)` and verify a result later. |
| `validateDeck(ruleset, cards): string[]` | Returns the list of problems; empty means the deck is legal. |
| `cardPower(state, cardInPlay)`, `lanePower(state, lane)`, `laneLeader(state, lane)`, `topicsLed(state)` | Power queries (DESIGN §6). `laneLeader` and `topicsLed` apply the consensus tie-break. |
| `scoringPower(state, lane)` | Lane power plus revealed "at scoring" Portals (§7). `result().lanePower` uses this. |
| `laneCapacity(state, lane)` | Per-seat capacity of a lane. A Portal such as Stub may override it. |
| `isOnTopic(state, cardInPlay)` | §1.4/§6 on-topic test, including Disambiguation. |
| `STARTER_DECKS`, `starterDeckById(id, rules?)` | The 4 DESIGN §2.1 starter decks (`stargazers`, `field-guide`, `headliners`, `pioneers`), derived through `deriveCard` with the given rules (a `Ruleset` works). **Use these for new players.** |
| `starterDeck(seed)` | Older placeholder loaner deck (seeded, 2 per cost from `STARTER_POOL`). Kept for tests and tools; not a §2.1 starter deck. |
| `previewPool(rules?)` | The 20 frozen `docs/game/starter-cards.json` loaners (council-data), derived via §1 against the `card-sample-2026-11-16` percentile table. For loaner slots and draft modes. |
| `deriveCard(input, table, rules?)`, `deriveDeck(inputs, table, rules?)` | DESIGN §1 + §10.1: `CardInput` → `GameCard`. **Hosts only**: run on host-frozen, plausibility-checked inputs, never on client JSON. A `Ruleset` can be passed as `rules`. |
| `placeCard(state, seat, lane, card)`, `revealPortal(state, lane)` | Test helpers for building boards by hand. |
## 2. Actions
```ts
type Action =
| { type: 'play'; player: 0 | 1; cardId: string; lane: number } // queue a card from hand (hidden)
| { type: 'undo'; player: 0 | 1; cardId: string } // un-queue it (refunds energy)
| { type: 'commit'; player: 0 | 1 } // lock in this turn (empty = pass)
| { type: 'timeout'; player: 0 | 1 } // HOST ONLY: turn timer expired
| { type: 'concede'; player: 0 | 1 };
```
**Queuing a play**
- `play` reserves the card's cost from this turn's energy. It checks the energy, the lane's room (cards already in the lane plus queued plays must stay under `laneCapacity(state, lane)`), and, once the Portal is revealed, whether it accepts the card (`canPlay`).
- Your plays reveal in **your queue order**, interleaved with the opponent's (see below).
- `undo` and new plays are allowed until the seat sends `commit`.
**Resolving a turn**
- When both seats have committed, `applyAction` resolves the turn (DESIGN §5.4–5.5):
1. Carry is set: min(`energyCarryMax`, energy not reserved by queued plays). Energy spent on a play that later fizzles is still spent.
2. **Interleaved reveal:** the initiative seat's 1st play, then the other seat's 1st, then the initiative seat's 2nd, and so on. When one seat runs out, the other's remaining plays reveal in order. Each card gets the next global `seq` number, and its on-reveal effects (keyword, then Portal) run at once.
3. End-of-turn effects run: the initiative seat's cards first, then lanes left→right, then `seq` order.
4. On the last turn, scoring follows (§7). Otherwise the next turn starts:
- initiative **alternates**
- any Portal scheduled by `portalReveal` is revealed
- energy = `energyByTurn[t-1]` + carry + `bonusEnergy`
- each seat draws
- the underdog bonus applies (only if `underdog` is on)
- **A play that is illegal at reveal** (the lane filled up, or a Portal rejects the card) fizzles. The card stays in hand and its energy is lost. A `fizzle` log event records it.
**Timeouts.** `timeout` is how a host enforces `turnSeconds`. It commits whatever is queued. A timeout with an empty queue counts toward `afkTurns`. When that count is reached, the seat concedes and the result has `reason: 'afk'`. An ordinary `commit` resets the count.
**Seat ownership.** The engine does not authenticate anyone. The host must check that the seat in `action.player` is the caller's.
## 3. Cards
```ts
interface GameCard {
cardId: string; // unique within a deck: the NFT card hash, or `loaner:<pageId>:<n>`
pageId: number | null; // at most maxCopiesPerPage cards share a pageId; null (unpinned loaners) → counted per cardId
title: string;
faction: 'Space' | 'Nature' | 'People' | 'Science' | 'History' | 'Culture';
rarity: 'Common' | 'Rare' | 'Epic' | 'Legendary'; // cosmetic in v1
cost: number; // 0–6 (uncheckedCostCap already applied by derivation)
power: number; // 0–30, base power
home: 'attention' | 'depth' | 'reach';
trend: -1 | 0 | 1; // frozen at match start
keyword: string | null; // an id in KEYWORDS
source: 'owned' | 'loaner';
check?: 'verified' | 'unverified' | 'unchecked' | 'loaner'; // host plausibility result (§1.10), for logs
}
```
- **The engine takes already-derived cards and never reads raw stats.** The council asked for this, because snapshot stats are self-reported (#1, critic brief A.1).
- Derivation (DESIGN §1 and §10.1: percentile → fame → cost → power, home, trend, keyword and vanillaBonus) lives in `shared/game/derive.ts`, which engine-b owns. Hosts run it on host-frozen, plausibility-checked inputs before calling `createMatch`.
- `CardInput = { cardId, pageId | null, title, category, rarity, snapshot: { stats }, live: { trendPercent, dailyAverage }, check, pinned? }`. `pinned: { cost, home, faction }` replaces §1.1–1.5 **only** when `check === 'loaner'`. `check === 'unchecked'` caps cost at `uncheckedCostCap` (home and fame are kept).
- **Never build `GameCard`s from client JSON.** `validateDeck` only checks shapes and ranges; a client could send cost 1 / power 30. Constructed modes must re-derive on the host.
- Both seats can hold the same loaner `cardId`. The engine keys per seat, so UIs should key cards by `owner + cardId`.
- Modes may adjust `GameCard` fields such as `power` before `createMatch`. The engine does not re-derive them.
- **`check` and `pinned` are host decisions, not player input.** Build loaner inputs only from shipped data (`STARTER_DECKS`,
`previewPool()`, `LOANER_SNAPSHOTS`), and set `check` for owned cards from the host's own §1.10 check. Otherwise a client could
send `check: 'loaner', pinned: {cost: 1, …}` for any card.
- **`obscure` leaks in v1.** `viewFor` does not mask Obscure cards yet. Modes must not put `obscure` in `keywordsEnabled` until it does.
- A keyword that isn't in `ruleset.keywordsEnabled` never runs. Derivation is responsible for not giving that card `vanillaBonus`.
- Lane power = `power` + `bonus` + `trend` + `onTopicBonus[cost]` if on-topic + ongoing keyword and Portal effects, floored at 0.
## 4. Ruleset
`Ruleset` holds the DESIGN §9 keys, **flat** (nothing deeper than one level, apart from `topicPool` entries and the param tables).
- `parseRuleset(unknown)` is a **strict** zod parse: unknown keys are rejected and every number is bounded, so any ruleset that passes terminates within `turns` turns.
- Modes merge overrides onto `DEFAULT_RULESET` and then call `parseRuleset`.
Notes on the §9 keys:
- `topicPool` is inline `TopicDef[] = { id, name, stat, portal: PortalId | null }[]`. `DEFAULT_TOPIC_POOL` is the 9 Topics of §10.3. A Portal id is one of `PORTAL_IDS` (`main-page, trending, featured-article, stub, interwiki, disambiguation`).
- `keywordParams[keywordId]` holds keyword numbers; keys must be in `KEYWORD_IDS`. `portalParams[topicId]` holds Portal numbers, and falls back to `portalParams[portalId]`, so a mode can add a Topic that reuses a Portal kind with new numbers.
- `keywordsEnabled` ⊆ `KEYWORD_IDS` (the 6 v1 ids plus `edition`, `obscure` and `wildcard`).
- `mulligan` must be `false`. Mulligans are not implemented in v1.
- `percentiles`, `starterDecks`, `trendUp/Down`, `trendMinDaily`, `uncheckedCostCap`, `vanillaBonus`, `costThresholds`, `powerByCost`, `verifyStats` and `factionSynergyCap` are for derivation and the host. The core loop doesn't read them.
Validation also enforces:
- `turns × turnSeconds ≤ 240`
- `energyByTurn.length ≥ turns`
- `portalReveal.length = topicCount`
- `openingHand ≤ handLimit`
- `costThresholds` in ascending order
- with `distinctStats`, `topicCount == 3` and the pool has all 3 stats
- the ranges in DESIGN §11 are **stricter** and are enforced by modes (`shared/game/modes.ts`). The engine's bounds only guarantee safety and termination.
## 5. Determinism and the RNG
- The RNG is **mulberry32(seed: uint32)**, as in DESIGN §4. Its state is a single uint32 in `state.rng`.
- Draw order:
1. p0's deck is shuffled.
2. p1's deck is shuffled.
3. **The Topics are drawn.** With `distinctStats`: for each stat in the order `attention, depth, reach`, take `group[floor(next() × group.length)]`, where `group` is that stat's Topics in `topicPool` order. Then the picks are shuffled, and that is the lane order. Without `distinctStats`: the whole pool is shuffled and the first `topicCount` are taken.
4. The initiative coin is flipped: p0 has initiative on turn 1 (and every odd turn) if `next() < 0.5`; otherwise p1 does. After that, initiative strictly alternates.
5. Keyword and Portal hooks draw in resolution order.
- Shuffles are Fisher–Yates with `i` from n−1 down to 1 and `j = floor(next() × (i+1))`.
- `ongoing` power hooks get a throwaway RNG copy, so computing power never changes the match RNG.
## 6. State and views
The full `MatchState` (plain JSON) is for the **host only**:
```ts
interface MatchState {
schema: 'wikideck-match/1'; engineVersion: number; ruleset: Ruleset; seed: number; rng: number;
turn: number /* 1-based */; phase: 'planning' | 'over'; initiative: 0 | 1;
players: [PlayerState, PlayerState]; // deck, hand, energy, queue, committed, afk
lanes: { topic: TopicDef; portalRevealed: boolean; cards: [CardInPlay[], CardInPlay[]] }[];
revealSeq: number; log: LogEvent[]; actions: Action[]; result: MatchResult | null;
}
interface PlayerState { deck; hand; energy; queue: { cardId; lane }[]; committed; afk; carry }
interface CardInPlay { card: GameCard; owner: 0 | 1; lane: number; turn: number; seq: number; bonus: number }
```
`PlayerView`, returned by `viewFor(state, seat)`, is what a seat may see. In it, "you" is always index 0 and the opponent is index 1:
```ts
interface PlayerView {
you: 0 | 1; ruleset; turn; phase; initiative;
energy: number; energyLeft: number; hand: GameCard[]; queue: { cardId; lane }[]; committed; deckCount;
opponent: { handCount; deckCount; committed }; // §5.3: nothing about their queue (cards, count or energy) until reveal
lanes: { topic: TopicDef /* stat always; id/name/portal masked until portalRevealed */, portalRevealed, cards: [mine, theirs],
cardPower: [number[], number[]], power: [mine, theirs], leader: 'you' | 'opponent' | null }[];
result: MatchResult | null;
}
```
`state.log` is an append-only event list for animation and replays. Event types: `turnStart`, `portalRevealed`, `underdog`, `draw`, `reveal`, `fizzle`, `effect`, `concede` and `matchOver`. It contains both seats' draws, so a host must filter it per seat before sending it.
## 7. Results
```ts
interface MatchResult {
winner: 0 | 1 | null; // null = draw
reason: 'topics' | 'totalPower' | 'draw' | 'concede' | 'afk';
topicsLed: [number, number]; lanePower: [number, number][]; totalPower: [number, number]; turns: number;
}
```
Scoring runs after the last turn's End phase. Lane powers include revealed "at scoring" Portals, and each lane's leader uses the consensus tie-break (§6). Winner, per DESIGN §7:
1. The seat that leads more Topics.
2. If tied on Topics, the seat with more total power.
3. If that is also tied, a draw.
## 8. Keywords and Portals (extension contract)
`KEYWORDS` and `PORTALS` in `shared/game/keywords.ts` (engine-b) are registries of hook objects. v1 keywords (`V1_KEYWORDS`, one per faction via `FACTION_KEYWORD`): viral, rising, local, encyclopedic, nostalgic, translated; optional (`OPTIONAL_KEYWORDS`, off by default): edition, obscure, wildcard. Portals: the 6 kinds of §10.3. The header of that file is normative. Every hook gets `ctx = { state, rng, params, lane, log, power(card) }`.
**Keywords**
- `onReveal(ctx, self)` and `endOfTurn(ctx, self)` may change `bonus` on cards in `ctx.state`.
- `ongoing(ctx, self, target) → number` must be **pure**, and must not call `ctx.power`.
- Keyword hooks run only if the keyword is in `keywordsEnabled`.
**Portals** have the same hooks, plus:
- `onPortalReveal(ctx)`
- `canPlay(ctx, card, seat) → boolean`, checked when a play is queued and again at reveal
- `capacity(ctx) → number`
- `allOnTopic: true`
- `atScoring(ctx) → [delta0, delta1]`
Portal hooks act only once the Portal is revealed.
**Rules for all hooks**
- Hooks must not move or remove cards (DESIGN §10).
- Any randomness must come from `ctx.rng`. No v1 keyword uses it.
## 9. Testing
- `tests/game-core.test.ts` (engine-a) covers the core loop:
- the RNG reference value, ruleset bounds and setup
- hidden information and hidden Portals
- energy carry, interleaved reveal and alternating initiative
- on-topic power, the consensus tie-break, and Portal capacity, fizzle and at-scoring hooks
- disabled keywords, AFK and concede, and draws
- the random-play property: matches terminate, replay exactly, and serialise after every action
- `tests/game-keywords`, `game-derive`, `game-starter`, `game-property`, `game-golden` (engine-b): every keyword and Portal, derivation, starter decks, properties (termination, determinism, round-trip, no input mutation, legality, power ≥ 0, capacity, no hand leak) and the DESIGN §12 golden match (19–15 / 15–19 / 13–10, p0 wins).
+285
View File
@@ -0,0 +1,285 @@
# 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/game` by `server/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:
```json
{
"schema": "wikideck.mode/2",
"id": "trending",
"version": 1,
"name": "Trending",
"description": "Live Wikipedia pageview trends power cards up or down.",
"tags": ["live-data"],
"engine": "editwar",
"rules": { "trendUp": 25, "trendDown": -25 },
"cards": { "preset": "trending", "percentPerPoint": 25, "maxBonus": 3, "penalise": true },
"decks": { "kind": "starter" },
"limits": { "maxConcurrentMatches": 32, "turnSeconds": 90, "lobbyMinutes": 15 }
}
```
| Field | Meaning |
|---|---|
| `schema` | `wikideck.mode/2`. Night 1 documents (`wikideck.mode/1`) are rejected with a message saying what to change. |
| `engine` | Required: `editwar` (the Night 1 simultaneous-reveal game, `shared/game`) or `duel` (the Night 2 Magic-style duel, `shared/duel`). Duel modes only allow `constructed` and `draft` with `source: "collections"`: every card is one the players own. |
| `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, Topics, deck sizes, known keywords and portals only; see DESIGN.md §9 for the keys). |
| `cards` | A card-mapping **preset** from a fixed list. `standard` leaves cards as dealt. `live` freezes each card's live trend arrow (DESIGN §1.6, using the ruleset's `trendUp`/`trendDown`) at match start. `trending` does the same and also adds a bounded power bonus from the live pageview trend. The mode only picks a preset and tunes its bounded numbers. |
| `decks` | `constructed` (each player submits exactly `deckSize` NFT token ids they own; the host verifies ownership and confirmations on the chain, `minConfirmations` default 1, and builds every card from its block), `starter` (Edit War only: a seeded starter deck) or `draft` (snake draft; `source: "preview"` uses preview cards, Edit War only; `source: "collections"` pools both players' owned cards for that match only, and both must own at least `deckSize`). |
| `limits` | Concurrency and lobby expiry for this mode on this host. `rated: true` moves Elo (start 1200, K 24) when both seats are eom.dev accounts; `accountsOnly: true` refuses guest seats (owned-card modes always do). `turnSeconds` only applies to engines without their own turn timer; with tonight's engine, the ruleset's `turnSeconds` (plus 5 s network grace) is the timer. |
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.
### Seats, invites, quick match and polling (Night 2)
- **Seats:** `POST /modes/:id/lobbies`, `POST /lobbies/:id/join` and `POST /modes/:id/quick` take `{idToken, deck?, private?}` for an eom.dev account (the Dex ID token may also be sent as `Authorization: Bearer <jwt>`), or `{name, secret}` for a guest in Edit War modes. The reply is `{lobbyId, seat, token, invite, playerId}`; `token` is the seat bearer for every later call. Account player ids are `sha256("acct:" + iss + "\n" + sub)`.
- **Invites:** every lobby gets a 12-character `invite` code. `private: true` hides it from `/lobbies` and quick match. `GET /invites/:code` describes it and `POST /invites/:code/join` joins it (SPA link: `/play/invite/<code>`).
- **Quick match:** `POST /modes/:id/quick` joins the oldest open public lobby someone else opened (`matched: true`), or opens one (`matched: false`) to poll.
- **Polling:** every lobby view has a `version`. `GET /lobbies/:id?v=<version>` answers **204** while nothing changed. Poll; never hold requests open (the node caps concurrent `/api` requests).
- **Ladder:** `GET /modes/:id/ladder` (same as `/leaderboard`): entries carry `rating` (Elo, or null if unrated) plus W/L/D.
- **Duel cards:** `server/game/duel-binding.ts` `toDuelCard` is the one path from an owned NFT to a duel card, for matches and for `GET /api/game/collection` card faces. It uses the frozen card identity (`<dataDir>/card-identity.sqlite`, testnet-ops' pre-bake) when present. Otherwise it types the card from what its block carries (the extract's first sentence, then the mint-time category), with no fetch. So a card's *collection* type can change **once**, when its identity is first frozen. Matches never change: the record stores the derived cards. Run the identity pre-bake before opening a node to PvP.
- **Clock:** duel turns get `turnSeconds` (+5 s grace) plus a per-seat `bankSeconds` bank; seat views carry `clock: {turnStartedAt, turnMs, bankMs}`.
- **Records:** `GET /matches/:id` has the seed, rules, both decks (as the engine cards), every action, `engine`, `rated`, and for constructed modes `tokens` (the NFT ids each seat played), so the recap can replay the match.
## 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. |
| `WIKIDECK_GAME_TREND_INTERVAL_MS` | `20000` | Background trend warm-up pace for `trending` modes (minimum 15000). |
| `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):
```yaml
# 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": { "turns": 4, "energyByTurn": [3, 4, 5, 6] }`
- **On-topic:** `"rules": { "onTopicBonus": [0, 2, 2, 3, 3, 4, 4], "trendUp": 10, "trendDown": -10 }`
- **Slow play:** `"rules": { "turns": 6, "turnSeconds": 40 }` (the engine caps turns × turnSeconds at 240)
- **Big decks:** `"rules": { "deckSize": 16, "maxLoaners": 16 }` with `"decks": { "kind": "draft", "poolSize": 40 }`.
Starter decks are 12 cards, so a non-draft mode with another deck size is rejected at startup.
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.
### Restarts
Live lobbies, drafts and matches survive a node restart. The node saves them to
`$WIKIDECK_DATA_DIR/game/live.json` every 15 s and on SIGTERM/SIGINT, and restores them on start.
Player tokens keep working, and turn and draft timers restart from the moment the node is back.
A lobby is dropped instead of restored if its mode is no longer hosted with the same `version`
and rules, so a match never continues under different rules. A hard crash can lose up to 15 s
of moves.
## 4. Credit for hosts
Every mode shows **"Hosted by &lt;operator&gt;"** (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 (`turns` ≤ 12, turns × turnSeconds ≤ 240 s) 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 20 s by default (`WIKIDECK_GAME_TREND_INTERVAL_MS`, minimum 15 s), at most 256 queued, never per request |
### Mode validation
A mode is rejected at node startup, never handed to the engine half-checked, if:
- it fails the mode schema (section 1), or
- the merged ruleset fails the engine's strict `parseRuleset`, or
- it fails the host-side checks in `server/game/engine-binding.ts`: `distinctStats` requires
`topicCount` 3; every `portalReveal` turn ≤ `turns`; `energyByTurn` has an entry per turn;
`turns × turnSeconds ≤ 240`; `powerByCost` has 7 entries; no keyword whose hidden information
`viewFor` doesn't mask yet (`obscure`) is enabled; or
- its deck policy can't produce legal decks (starter decks illegal under its rules, or a draft
pool smaller than 2 × `deckSize`).
### Wikipedia load (`verifyStats`)
Our Wikipedia egress is shared and rate-limited, so tonight the host makes **no Wikipedia
requests in any request or match path**:
- Hosted decks are loaners (starter or drafted), so there are no owned-card stats to verify,
and `verifyStats` never triggers a fetch.
- When owned decks arrive, verification must use the DESIGN §1.10 immutable cache keyed by
`(pageId, revisionId, snapshotMonth)`, with `check: 'unchecked'` and `uncheckedCostCap` as the
normal path when the cache is cold, not a per-card fetch.
- `trending` reads only the background-warmed trend cache (see "Not yet").
### Cheating
- **The client is never trusted.** Each action must deep-equal one of the engine's
`legalActions` for 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 host picks a random seed when the lobby opens, so players can't
grind for a favourable shuffle. The engine hashes it to 32 bits: fine against players, but
not a secret worth relying on against a host.
- **Stalling:** when a seat runs out of turn time, the host applies the engine's `timeout`
action (auto-commit). After `afkTurns` idle timeouts the engine forfeits that seat. Timeouts
are in the action log, so they replay. 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 input.** The host builds every deck from shipped engine data (starter decks and the
loaner pool). It never accepts cards, `check` values or pinned stats from client JSON.
- **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
**Hosted PvP trusts the host.** The host holds both players' hidden plans (hands and queued plays)
and relays them; it decides the seed; and it would be the one to mark card stats as checked or
unchecked (DESIGN §1.10). Nothing tonight lets players verify a match *while* it's being played.
So a host is **trusted for the matches it hosts**, and only those. Play on hosts you trust, and
treat leaderboards on any other host as that host's claims.
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.
1. **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.
2. **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.
3. **Batched claims.** Once per epoch, a host submits one transaction committing a Merkle root of
its signed results. A new `hostClaim` transaction type would carry the root and a count. This is
the protocol change: a new transaction type, its validation and its reward rule.
4. **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.
5. **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
- `constructed` decks of **owned NFTs** are verified on the hosting node only, against its
own account store (Night 2). Playing them on a *peer* needs a wallet-signed deck claim,
because accounts are per node; that's a follow-up.
- `trending` never calls Wikipedia when a match starts. The node warms a cache-only trend
store in the background, one page every 20 s (configurable, never faster than 15 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: a few dozen pages per 6 hours per node.
- Spectating and rematches.
- **Separate game RPC budget.** `/api/game` sits behind the node's global `/api` admission
budget (`WIKIDECK_RPC_REQUESTS_PER_SECOND`, 10 writes/s node-wide), so a flood of game
traffic can delay chain RPC (and the reverse). At human speed this is fine. The fix is to give
game routes their own `RpcBudget`, which means mounting them ahead of the shared budget in
`server/testnet/http.ts`: a change to that shared file, so it's proposed in #6 rather than made
tonight.
+73
View File
@@ -0,0 +1,73 @@
# Ownership and collection API (Night 2, #57)
Server-side checks that a player owns the cards they play. Off-chain only: nothing here moves, burns or locks a card, and nothing changes consensus.
## The rules (ruleset data)
| Key | Default | Meaning |
|---|---|---|
| `deckSize` | 40 | A constructed deck has exactly this many cards. A testnet mode file may lower it. |
| `maxCopiesPerPage` | 4 | The MTG-style copy limit. Cards minted from the same Wikipedia `pageId` are separate cards, but at most this many go in one deck. |
| `minConfirmations` | 1 | The confirmations each card's mint block needs. Rated play uses `RATED_MIN_CONFIRMATIONS` = 3. |
## `server/game/ownership.ts` (used by the PvP host)
```ts
verifyAccount(deps, idToken: unknown): Promise<Account>
resolveDeck(deps, account, tokenIds: unknown, opts?: Partial<OwnershipRules>): Promise<ChainCard[]>
collection(deps, account, opts?: { minConfirmations?: number }): Promise<ChainCard[]>
```
- **`deps`** is `{ ledger, accounts, verifyIdToken }`. In production, `server/testnet/http.ts` builds it from the node's `Ledger`, the shared `AccountStore`, and `accountVerifier()` from `server/account/router.ts`. It passes the result to `gameRouter({ ownership })`.
- **`resolveDeck`** accepts token ids only, never card JSON. For each card it checks:
- the card is on the canonical chain (`ledger.nft()`);
- its current owner (after transfers) is one of the account's linked wallets;
- it has enough confirmations;
- the deck size and copy limit.
Each card is rebuilt from its own block (`article` and `statsSnapshot`). The cards come back in the order given.
- **Errors** are thrown as `DeckError { code, status, tokenIds, pageId? }`. `tokenIds` lists every offending card of that class.
| `code` | `status` |
|---|---|
| `auth` | 401 |
| `size` | 400 |
| `duplicate-token` | 400 |
| `unknown-token` (not on chain, or malformed) | 400 |
| `not-owned` (includes "no linked wallet") | 403 |
| `unconfirmed` | 400 |
| `copy-limit` | 400 |
`OwnershipUnavailable` (503) means Dex is unreachable or the chain tip kept moving during a read.
- **`collection`** pages `ledger.deck()` (24 per page) across every linked wallet at one canonical tip, restarting if the tip moves. There is no 128-block snapshot cap.
## `GET /api/game/collection`
`Authorization: Bearer <Dex ID token>` (the same token as `/api/account/me`). Optional: `?minConfirmations=N`.
```ts
{
tip, wallets: string[],
deckSize: 40, copyLimit: 4, maxCopiesPerPage: 4, minConfirmations: 1,
owned: number, // confirmed cards across all linked wallets
playable: number, // Σ min(copies, copyLimit) per pageId
needed: number, // max(0, deckSize - playable)
eligible: boolean, // playable >= deckSize
cards: ChainCard[] // tokenId, owner, confirmations, pageId, title, revisionId, url, extract, imageUrl?,
// height, blockHash, createdAt, powHash, article, statsSnapshot
}
```
| Case | Response |
|---|---|
| No linked wallets | 200 with `cards: []` and `needed: 40` |
| Missing or invalid token | 401 |
| Dex unreachable | 503 |
| Bad query | 400 |
The UI shows `playable / deckSize`, for example "23 / 40 cards", and how to mine.
## Not covered (known gaps)
- **Peer hosts.** Account stores are per node, and a Dex token sent to a peer could be replayed elsewhere (engineer review §2, G6). This API is for the self-hosted node only. The stretch fix is a wallet-signed deck claim.
- **Plausibility of minted stats** (G5): `pageId` → `title` and `revisionId` → `size` are not cross-checked yet.
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
+25 -25
View File
@@ -1,57 +1,57 @@
# Gated mainnet candidate
# Mainnet-first, gated candidate
This repository now has a **separate mainnet candidate profile**, not an audited or launched production network. Shipping code does not establish independent miners, economic security, an operational public network, or a safe real-money market. **Marketplace payments remain mocked on every profile.** There is opt-in mainnet code for operator-reviewed pending deposit credits and signed withdrawal reservations, but it does not expose customer deposits by default or construct/relay Monero transactions; it is not a live payment service.
The repository defaults to a **mainnet candidate**, not an audited or launched production network. Shipping code does not establish independent miners, economic security, or an operational public network. Market and payment features have been removed from the card-only product.
**Current production decision: NO-GO.** See the [2026-10-20 security review](security-review.md) and [operator evidence register and launch procedure](operator-launch.md). The read-only `launch:preflight` package script (or node entry-point `--launch-preflight`) reports local gates and unresolved blockers without starting a node or setting approvals. It deliberately exits nonzero while production readiness is blocked.
## What is implemented
| Property | Testnet default | Mainnet candidate |
| Property | Mainnet-first default | Explicit development fixture |
| --- | --- | --- |
| Selection | `WIKIDECK_NETWORK=testnet` (or unset) | `WIKIDECK_NETWORK=mainnet` |
| Network ID | `wikideck-randomx-testnet-6` | `wikideck-randomx-mainnet-1` |
| Protocol | Existing version 6 | Version 6 under a distinct chain identity |
| Genesis timestamp | Unchanged | 2027-01-01 00:00 UTC, **candidate only, not a promised launch** |
| Ledger/market subdirectory | testnet | mainnet |
| Browser wallet | Existing testnet store, unchanged | Separate mainnet store |
| Payment mode | Mock only | Mock only |
| Selection | `WIKIDECK_NETWORK=mainnet` (or unset) | `WIKIDECK_NETWORK=testnet` |
| Network ID | `wikideck-randomx-mainnet-1` | `wikideck-randomx-testnet-6` |
| Protocol | Version 6 | Existing fixed local testnet version 6 |
| Genesis timestamp | Fixed launch default: 2026-11-01 00:00 UTC (`1793491200`); ready to start now | Fixed at 2026-10-19 00:00 UTC |
| Ledger directory | mainnet | testnet |
| Browser wallet | IndexedDB name derived from exact chain ID | Separate chain identity |
| New backup | v2 header authenticates exact chain ID | Same v2 format; legacy v1 is accepted only on the original testnet |
Both profiles use real RandomX validation, cumulative-work branch selection, the 15-minute target, mint maturity, signed NFT transfers, atomic card trades, and SQLite persistence. The mainnet candidate has no premine, token migration, hidden checkpoint, or fake-PoW option. Changing the network identifier and candidate genesis derives distinct chain/genesis IDs, RandomX initial keys, signature domains, and consensus manifest checks. Existing testnet values and data remain unchanged.
**Testnet cards and backups do not migrate.** Browser storage is separate, backup network headers are authenticated and checked, peers reject mismatched manifests, and transactions are checked against the active chain. The selected profile is pinned at startup/browser build, never silently adopted from an RPC response.
**Cards and backups do not migrate across chain identities.** Browser storage and backup headers are bound to the exact chain ID; peers reject mismatched manifests, and transactions are checked against the active chain. The selected profile and genesis are pinned at startup/browser build, never silently adopted from an RPC response. The original fixed-testnet v1 backups remain supported only on that testnet.
## Inspect without launching
The node entry point accepts `--network-manifest`. With `WIKIDECK_NETWORK=mainnet` set in the process environment, this prints the candidate network/chain/genesis/timestamp and exits **before** opening databases, starting a RandomX engine, listening, or contacting peers. It does not require activation credentials or approval and does not launch anything.
Browser builds select `VITE_WIKIDECK_NETWORK=mainnet`; server/miner processes select `WIKIDECK_NETWORK=mainnet`. These must match. Docker's `WIKIDECK_NETWORK` **build argument** sets the browser profile; a runtime variable cannot alter an already compiled UI. A mismatched UI rejects the node network instead of signing for it. The mainnet Compose definition supplies both the build and runtime selections.
Browser builds select `VITE_WIKIDECK_NETWORK=mainnet`; server/miner processes select `WIKIDECK_NETWORK=mainnet`. These must match. `WIKIDECK_GENESIS_TIME` is also part of the chain identity. Docker's network/genesis **build arguments** pin the browser and immutable image manifest; a runtime variable cannot alter an already compiled UI. To choose another genesis, set it for the image build and runtime together, publish the resulting manifest, then use that immutable image and exact timestamp for every node and browser. A runtime-only genesis override fails closed. A mismatched UI rejects the node rather than signing for it.
## Explicit launch gates
[compose.mainnet.yaml](../compose.mainnet.yaml) is an opt-in Compose profile, uses a separate named volume, binds only loopback for an external HTTPS reverse proxy, and does **not** auto-restart a failed candidate. It has no default peers, approval, or public origin. It is not started by the default Compose definitions. **No mainnet nodes have been started by this change.**
[compose.yaml](../compose.yaml) and [compose.mainnet.yaml](../compose.mainnet.yaml) are mainnet-first definitions, use separate named volumes, bind only loopback for an external HTTPS reverse proxy, and do **not** auto-restart a failed candidate. They have no default peers, approval, or public origin. The default service therefore exits until the operator supplies real deployment values. The testnet Docker fixture is separate and explicit. **This code change does not establish or certify a public mainnet.**
Starting the candidate node or native miner requires all of:
1. `WIKIDECK_MAINNET_LAUNCH` equals the exact candidate chain ID printed by the manifest command.
2. `WIKIDECK_MAINNET_REVIEW_ACK=independent-review-complete` records the operator's review attestation. This is **not cryptographic proof of an audit**, and the manifest still honestly reports `audited: false`.
3. The candidate genesis timestamp has arrived. If review changes the timestamp or consensus manifest before launch, the chain ID also changes and the old approval is invalidated. Freeze and publish the final manifest only after review.
4. An HTTPS `PUBLIC_ORIGIN`, at least two distinct configured HTTPS peer origins, and no private-peer bypass. Configuration count cannot prove the peers are online, independent, or sufficiently distributed; verify that operationally. Existing peer DNS/origin controls still apply.
5. `WIKIDECK_PAYMENT_MODE=mock`. Live modes fail closed independently of launch approval.
2. `WIKIDECK_MAINNET_RISK_ACK=operator-accepts-unaudited-risk` records the operator's explicit acceptance that no external audit is planned and residual risks remain. This is not a safety certification; the manifest honestly reports `audited: false`.
3. The candidate genesis timestamp has arrived. If the operator changes the timestamp or consensus manifest before launch, the chain ID also changes and the old approval is invalidated. Freeze and publish the final manifest before launch.
4. An HTTPS `PUBLIC_ORIGIN` and at least two distinct configured peer origins. Public deployments require public HTTPS peers by default. An operator-controlled private candidate cluster may explicitly set `WIKIDECK_ALLOW_PRIVATE_PEERS=1` to permit private/HTTP peer RPC; this does not relax browser HTTPS, chain approval, risk acknowledgment, or genesis-time gates. Configuration count cannot prove the peers are online, independent, or sufficiently distributed; verify that operationally. Existing public peer DNS/origin controls still apply when the private opt-in is off, and HTTPS certificate verification is never disabled.
Unknown profile names fail closed. A direct import of the HTTP entry point is also guarded. Library-level manifest/consensus/storage inspection remains possible for tests and review; activation gates are accident prevention, not a security boundary against someone who edits the source.
For Kubernetes public peering, give every node a stable, unique public HTTPS endpoint. For an explicitly private candidate, separate single-replica Deployments, Services and exclusive PVCs may use distinct ClusterIP DNS origins with the private opt-in. Each validator lists the other two internal Services, never itself. The browser-facing node needs a TLS ingress/reverse proxy; internal-only validators may share that HTTPS browser origin without their own ingress. NetworkPolicy must restrict peer RPC to the selected validator pods on target TCP port 3001. Private HTTP RPC is unauthenticated and unencrypted unless protected by an independently configured mesh; do not use it across untrusted networks. Three validators in one cluster/storage failure domain are not independent operators or proof of production readiness.
See the [Kubernetes mainnet preparation checklist](../deploy/kubernetes/README.md) for the deployment contract and the values needed before manifests can be finalized.
Unknown profile names fail closed. A direct import of the HTTP entry point is also guarded. Library-level manifest/consensus/storage inspection remains possible for tests and review; activation gates are accident prevention and operator risk acceptance, not a security boundary against someone who edits the source.
## Required before an actual production launch
- **Independent review:** protocol/cryptography, signatures and wallet lifecycle, RandomX integration, difficulty/time/retarget attacks, state commitments, fork choice, network message validation and denial-of-service limits. Publish findings, fixes and a versioned final manifest.
- **Internal readiness review:** track code findings and regression evidence in-repository. No external audit is planned; the operator accepts the additional risk and must not describe the candidate as audited or certified.
- **Security model:** quantify hashpower, chain-rewrite cost and majority attacks. The inherited easy initial target and ten-block retarget are **not production-calibrated**. Choose reviewed launch difficulty/retarget behavior and test start-up/stall/recovery scenarios. Independent mining participation and sufficient hashpower are not provided by running multiple containers on one host.
- **Adversarial rehearsal:** sustained multi-host simulations, partitions/eclipses, competing branches, deep reorganizations, clock skew, bad peers, load/mempool saturation, corrupted state and restart recovery. Test the candidate rules with no valuable assets.
- **Operations:** independently administered public HTTPS nodes and miners across failure domains, pinned release artifacts and dependencies, firewall/reverse proxy/rate-limit policies, bounded storage and sync strategy, metrics, alerts, rotation and emergency-response procedures.
- **Recovery:** verified offline wallet recovery, consistent ledger/market snapshots, full replay/revalidation, documented incident and fork handling. No silent ledger reset or reuse of testnet data.
- **Launch governance:** select the actual genesis date, freeze the reviewed identity/configuration, publish binaries and configuration hashes, agree peer/miner readiness and upgrade policy, and explicitly authorize launch. No operator should attest review merely to bypass the gates.
- **Economics and legal review:** no monetary value or security is promised. NFT rights do not imply article/image copyright ownership. A real-money custodial market requires a separate risk, custody and payment review.
- **Recovery:** verified offline wallet recovery, consistent ledger snapshots, full replay/revalidation, documented incident and fork handling. No silent ledger reset or reuse of testnet data.
- **Launch governance:** select the actual genesis date, freeze the identity/configuration, publish binaries and configuration hashes, agree peer/miner readiness and upgrade policy, and explicitly record the operator's risk acceptance. Do not treat the flag as proof of safety or peer readiness.
- **User and legal review:** no monetary value or security is promised. NFT rights do not imply article/image copyright ownership. Publish experimental-use, privacy, support, and abuse-report terms appropriate to the release.
## Still not production-ready
This remains experimental software. Nodes retain the DAG and overlays in memory, rebuild state roots over the full NFT set, and revalidate proofs at startup. The HTTP UI trusts its connected node rather than independently validating the chain. There is no automatic peer discovery, established bootstrap infrastructure, formal finality, independent audit, built-in anti-shill mechanism or production abuse system. The marketplace is node-local, not consensus escrow. Mainnet selection does not remove any of these limitations.
See [marketplace sandbox and future live-custody boundary](marketplace.md) for the mock settlement model and the additional work required before any real XMR can be accepted or paid out.
This remains experimental software. Nodes retain the DAG and overlays in memory, rebuild state roots over the full NFT set, and revalidate proofs at startup. The HTTP UI trusts its connected node rather than independently validating the chain. There is no automatic peer discovery, established bootstrap infrastructure, formal finality, independent audit, or production abuse system. Mainnet selection does not remove any of these limitations. See the [card-only production plan](card-only-production-plan.md) for the current readiness gates.

Some files were not shown because too many files have changed in this diff Show More