Compare commits

..
Author SHA1 Message Date
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 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 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 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 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 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 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: #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: #21
2026-11-01 22:07:51 +00:00
eric 1edf2e6200 Merge pull request 'More cards' (#20) from v2 into main
Reviewed-on: #20
2026-10-19 22:57:02 +00:00
369 changed files with 39333 additions and 17504 deletions
+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
+54
View File
@@ -0,0 +1,54 @@
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:!*~'
}
}
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,5 @@
package dev.eom.wikideck;
import com.getcapacitor.BridgeActivity;
public class MainActivity extends BridgeActivity {}
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);
}
}
+12
View File
@@ -0,0 +1,12 @@
#!/bin/sh
# Build the WikiDeck debug APK against the private Night-1 testnet.
# Needs ANDROID_HOME 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}"
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-16 && 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-16}
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
+28
View File
@@ -0,0 +1,28 @@
# 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.
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_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_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_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.
+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).
+272
View File
@@ -0,0 +1,272 @@
# 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/1",
"id": "trending",
"version": 1,
"name": "Trending",
"description": "Live Wikipedia pageview trends power cards up or down.",
"tags": ["live-data"],
"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 |
|---|---|
| `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` | `starter` (everyone gets a seeded starter deck), `draft` (snake draft from a host-seeded pool of preview cards) or `constructed` (bring your own; see "Not yet" below). |
| `limits` | Concurrency and lobby expiry for this mode on this host. `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.
## 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**: the policy exists, but tonight the host deals
starter decks for it. Playing with your own cards needs a wallet-signed ownership proof
for the lobby (and then the engine's `cardFromStats`). That's a follow-up once accounts and
wallet linking (#7) settle.
- `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.
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.
-35
View File
@@ -1,35 +0,0 @@
# Optional market hosting and host fee wallet
These are **server runtime** environment variables, forwarded by the single-node, three-node, gated mainnet and persistent custody Compose files. They do not enable real payments.
| Variable | Default | Effect |
| --- | --- | --- |
| `WIKIDECK_MARKET_ENABLED` | `1` | `0` removes public listings and rejects new listings, bids, purchases, custody reservations and fictitious funding. Node validation, mining, peer sync and free transfers/trades continue unchanged. |
| `WIKIDECK_MARKET_TRADING_ENABLED` | `1` | `0` pauses new trading/funding but keeps public listings browsable. Useful for maintenance/read-only operation. |
| `WIKIDECK_MARKET_HOST_FEE_ADDRESS` | Fixed project author XMR address | Public Monero recipient for the **hosting commission**, independently of the fixed additional author commission. |
| `WIKIDECK_MARKET_FEE_BPS` | `250` | Existing hosting commission rate, in basis points; range 0–5000. |
| `WIKIDECK_CUSTODY_MODE` | `off` in the application | Existing custody-service control: `off` or testnet-only `sandbox`. The dedicated custody Compose stack deliberately enables `sandbox` and provisions PostgreSQL. |
Booleans accept exactly `0`/`1`; malformed or empty flags fail startup. The fee address must be a checksum-valid **mainnet Monero standard address or subaddress** under the current XMR policy; integrated addresses, URLs, other networks and blank values are rejected. It is not a private key, buyer deposit address, or proof of ownership. No RPC/wallet access is needed to validate it.
Default wallet:
44xHcCdFhW4b951yBHpkTPdLSJ85qTCnFQ8N7m96TtqqRL3dbhzbEH4fe2SJ3a6ESHcNyzCYH5nYJ9ActR1JtkeA7QYGbQv
Set the variables in the shell/Compose environment or a local Compose environment file, then recreate the intended app container. They are not browser build variables. Merely restarting a container does not replace its environment. Existing Compose defaults preserve current hosting behavior. In the three-node configuration shared values apply to all nodes; per-service environment overrides allow different hosts/fees. Do not point independent markets at a shared financial schema.
## Existing obligations remain available
Disabling market hosting is **not a funds freeze or deletion**. Signed private activity, existing-order mock payment/delivery/refund, listing retirement/cancellation, custody cancellation and withdrawal-hold requests remain available under their existing checks. Reconciliation continues and data is retained. PostgreSQL remains required if that node already has PostgreSQL-backed liabilities; the switch is not a shortcut to abandoning custody responsibilities. Existing valid command receipts remain replayable without creating another mutation.
A peer that never wants custody can leave `WIKIDECK_CUSTODY_MODE=off` and use the ordinary single/three-node stack with `WIKIDECK_MARKET_ENABLED=0`; it does not need the dedicated PostgreSQL stack. Do not turn custody off merely to hide pre-existing liabilities; first resolve them under a reviewed shutdown procedure. The marketplace UI retains an activity/resolution surface and displays the disabled/paused policy rather than hiding recovery controls.
## Fee recipient and signature compatibility
New native-XMR listings and custody listings snapshot the configured host fee address. Buyer checkout/reservation must authorize that same recipient. Both UIs show it during review and include it in signed terms. Recipient tampering invalidates the signature, and an unsigned/omitted recipient is accepted **only as the historical default author address**, never as authorization for an arbitrary configured wallet.
Existing signature bytes remain valid: omission retains the original message; explicitly supplied recipients add a domain-tagged fee tuple. Old USD/native-XMR records are not rewritten. Changing the environment changes **new listings**, not existing listings/orders or accumulated revenue. New checkout against an old listing follows its original recipient. For a new recipient, cancel/relist with fresh seller authorization. Hosting rate and the fixed 1% author policy remain separate; defaulting both recipients to the same wallet does not merge the rates.
The custody SQLite fixture records newly settled simulated host revenue under its snapshotted recipient. PostgreSQL production settlement/host withdrawals are still unimplemented: configuring an address does not create automatic transfers. Historical unallocated host revenue remains historical; it is not silently reassigned. The offline sale-lock candidate now preserves the hosting recipient in a tagged signed-terms extension. A [disposable PostgreSQL accounting rehearsal](custody-sale-rehearsal.md) verifies that the signed snapshot receives simulated revenue even after current host policy changes; this is not active-chain delivery or a live host withdrawal service.
Validation: current TypeScript/Vite build, 172 offline regressions and 31 PostgreSQL integration tests passed. Tests cover strict flag/address validation, paused/disabled behavior, continuing existing-order delivery, preserved balances/cancellations, signed-recipient tampering and recipient snapshots across config changes, including the isolated accounting rehearsal. Real XMR remains disabled.
-133
View File
@@ -1,133 +0,0 @@
# Market payments, buyer protections and seller protections
**Read this before buying or delivering a card.** Trust should come from knowing what a market does, who controls it and where its protections stop—not from a promise that every trade is safe.
## Current status: no real payments
**The running Wikideck market is a testnet sandbox. It does not process real cryptocurrency payments.** New listing prices are native XMR amounts; payment confirmations, fees, seller payouts and refunds are simulated. Historical USD orders retain their original terms and are labeled as legacy. Checkout provides **no payable Monero address**. Do not send cryptocurrency to a host, author-fee address or address someone provides in a message to pay a sandbox order.
**Card delivery is real on the selected blockchain.** When a seller signs delivery, they authorize an actual NFT transfer, even though the buyer only clicked a simulated-payment button. A `paid` or `mock-paid` label here is **not evidence of real money received**. Do not deliver valuable assets in exchange for mock payment.
There is no live payment integration or supported setting that enables live checkout today.
## Who controls what?
| Item | Controller and trust boundary |
| --- | --- |
| Your NFT signing key | Your local wallet. New/migrated local storage is password-encrypted; an unlocked tab can sign. Never give the host your password, backup or private key. |
| A listed card | The seller keeps control until a signed transfer is mined. **Listing is not escrow** and does not lock the card on-chain. |
| Confirmed card ownership | The selected network's canonical blockchain, subject to reorganizations. The browser trusts the connected node's reported chain; it is not an independent validating wallet. |
| Listings, auction bids, reservations and orders | The particular hosting peer's local marketplace database. They are not replicated as blockchain consensus records or shared with every other market. |
| Payment money today | No money is collected, held or sent by this release. Amounts are accounting simulations. |
| Money in the proposed live design | The selected direction is a pooled Monero treasury and internal liability ledger controlled by the market operator. **That would be custodial**, not trustless escrow or a non-custodial exchange. It is not active. |
Your NFT wallet address is not an XMR payment address. Sharing the RandomX algorithm with Monero does not merge the two networks, payments or security budgets.
## What happens in today's checkout?
### 1. Seller lists a card
The seller reviews and signs the card, ownership sequence, price, sale format, auction deadline where applicable and hosting-fee rate. Listing/checkout signatures also bind the hardcoded author-fee policy and recipient. The node checks that the seller owns a sufficiently mature card at the current sequence and that no conflicting card transaction is pending. Only one active listing for that card is allowed **on that market host**, not globally across all hosts.
The seller may cancel an available fixed-price listing. An auction cannot be cancelled after its first bid. The seller still controls the card and can transfer it elsewhere; subsequent checks can invalidate the listing. These checks reduce stale sales but cannot prevent a seller from breaking an off-chain promise.
### 2. Buyer reserves the sale or wins an auction
Fixed-price checkout reserves the local listing for **30 minutes from reservation**. An unpaid reservation expires and can reopen if the card is still eligible. A seller cannot cancel the reserved listing through the normal cancellation action.
Sandbox auctions last one minute to 30 days. Bids are signed but **unfunded**; each new v3 bid must meet the opening price and exceed an existing highest bid by at least one atomic unit. Historical USD auctions are read-only and retain their original bid terms. The seller's own address cannot bid, but alternate-wallet shill bidding is not prevented. There are no funded bid deposits, identity checks or automatic nonpayment penalties. Live auctions remain a separate release gate.
The auction winner must check out and complete mock payment within **30 minutes after auction close**, not 30 minutes after clicking checkout. Without bids the auction expires at closing. An unpaid winner causes expiry; there is no automatic runner-up sale. The seller can relist later.
### 3. Buyer simulates payment
For a new version-3 order, the buyer sees the exact signed XMR gross, host fee, author fee, seller net and payment deadline. No USD conversion or exchange rate is applied. Legacy version-2 USD orders retain their previously signed USD price and snapshotted mock-XMR quote; they are not reinterpreted as XMR. Quote amounts, fee allocations and delivery-confirmation requirements remain stored with each order.
Only the order's buyer can sign **Simulate XMR payment**, and eligibility is checked again. This action changes an accounting status; it does not verify a Monero transaction. Other users cannot mark the order paid through the normal participant-authorized API, but the buyer's signature alone never proves real payment.
### 4. Seller reviews and signs delivery
The seller must return to review the exact card, recipient and net proceeds. The market accepts only a valid seller transfer matching that order's card, seller, buyer and ownership sequence. The node validates the transfer under the chain rules. Submission means **pending**, not delivered.
Seller delivery is due **48 hours after mock payment**. The node recognizes the exact agreed transfer if submitted through the marketplace, the normal transfer endpoint or peer gossip. Merely seeing the buyer hold some card is not the settlement criterion. Direct delivery without recorded mock payment is held for review rather than automatically paying the seller.
The market never signs NFT delivery on the seller's behalf. Locking a wallet stops new session signing; it does **not** revoke an already issued signature or undo a mined transfer.
### 5. Canonical delivery unlocks simulated payouts
The market waits for the exact sale transfer to appear in the canonical chain at the order's required depth—**10 confirmations by default**, configurable for new orders. It then records the seller net and author-fee leg as `mock-paid`, with the hosting allocation retained in simulated host accounting. These are not XMR transaction receipts.
No finite depth guarantees proof-of-work finality. If a reorganization removes or reduces the depth of an already settled transfer, the order enters **review** and is not paid a second time automatically. This prevents blind duplicate accounting; it does not recover money or reverse a transfer. An order's `review` state is not automatically cleared just because the chain later changes back.
## Fees: who receives them and how much?
| Allocation | Rate | Recipient / treatment |
| --- | --- | --- |
| Hosting fee | Operator-configurable, default **2.5%** | Hosting peer's market operator. Retained from gross proceeds in the intended merchant-wallet design. Currently simulated. |
| Project author fee | Hardcoded **1%** in the distributed implementation | Fixed author XMR address below. Separate allocation/payout, currently simulated. |
| Seller net | Gross minus both fees | Seller. Currently simulated; no XMR payout is sent. |
Both fees are calculated independently from gross XMR, not compounded. They are deducted from seller proceeds, not secretly added to the buyer's listed price. At default rates a **0.100000000000 XMR** simulated sale allocates:
- Host: **0.002500000000 XMR**.
- Author: **0.001000000000 XMR**.
- Seller: **0.096500000000 XMR**.
The author recipient is:
44xHcCdFhW4b951yBHpkTPdLSJ85qTCnFQ8N7m96TtqqRL3dbhzbEH4fe2SJ3a6ESHcNyzCYH5nYJ9ActR1JtkeA7QYGbQv
**This is a payout recipient, not a checkout address.** Setting hosting fees to zero does not disable the author allocation. Checksum verification does not prove recipient ownership. The author fee is source-level policy, not a guarantee that every independently modified host runs the same release; verify the host and its disclosed terms.
New v3 XMR prices and fees use integer 12-decimal atomic units. Buyer gross is the exact signed listed amount; there is no USD conversion or gross-up. Each fee rounds down separately; seller net is exactly gross minus both fees. A fee below one atomic unit rounds to zero. Historical v2 orders retain their original USD cents, mock-XMR quote and accounting, including legacy orders predating the author fee. Eligible old open listings are read-only until the seller retires and relists with fresh v3 authorization.
Fees apply to completed marketplace sales—not listing creation, auction bids, free NFT transfers or card-for-card trades. Failed/expired/refunded orders do not produce successful payout accounting. There is **no finalized live processor/network-fee or refund-cost policy**; one must be disclosed before real payments are enabled. The test numbers are not a promise about future all-in costs.
## What if something goes wrong?
| Situation | Current behavior | What is not guaranteed |
| --- | --- | --- |
| Buyer does not pay | Reservation or winner payment window expires; eligible fixed listings reopen; auctions expire. | Funded bid enforcement, penalties or a guaranteed replacement buyer. |
| Seller transfers the card elsewhere | Ownership/sequence/pending checks can invalidate the listing or put a paid order into `refund-required`. | An on-chain card lock, automatic replacement or compensation. |
| Seller does not deliver | After the delivery deadline, an order without an exact pending/canonical delivery may become `refund-required`. | A real cash refund or an operator response deadline. |
| Exact sale transfer is still pending | The deadline alone does not authorize a refund while that transfer remains pending. | A maximum mining time; network congestion/stalls can prolong the wait. |
| Buyer requests a mock refund | Only the buyer can act, and only in `refund-required`, with no pending card transaction and no exact canonical delivery. The journal records `refunded` and cancels the listing. | A real cryptocurrency refund, cancellation of existing signatures, or future delivery prevention. |
| Delivery is reorged after settlement | Hold for review; no automatic second payout. | Finality, rollback of payouts or loss insurance. |
| Host becomes unavailable | Local orders and reconciliation wait until the host recovers. The chain may keep operating elsewhere. | Order portability, replication to another market or a project-run recovery service. |
| Request times out | Outcome may be unknown; inspect refreshed activity before signing a new action. Replays of the same signed nonce return its stored result where applicable. | That timeout means failure, or that a new nonce cannot create a new action. |
| Wrong address or compromised key | Valid signatures can transfer cards; verify recipients and protect backups. | Chargebacks, key resets or reversal of confirmed ownership. |
**A refund check cannot revoke a signed NFT transfer.** A delayed transaction can arrive later, including after a reorganization or a proposed refund. No automatic real-money refund mechanism solves that risk here. This is one reason live settlement remains disabled.
There is currently **no built-in arbitration service, buyer insurance, chargeback system, guaranteed reimbursement, operator override/payment-recovery endpoint, or dispute-resolution SLA**. A `review` label means investigation is needed—not that a resolver or repayment fund exists. Do not infer those protections from words such as “market,” “confirmation” or “settlement.”
## Future live custody is not active
The intended direction is direct wallet/daemon observation into a pooled liability ledger; it does not depend on a third-party invoice processor. An opt-in mainnet operator workflow can stage observed outputs as pending and release them to a customer's available ledger balance after signed review. A separate opt-in API accepts signed withdrawal requests and reserves funds, but does not create or relay Monero transactions. Neither flow has a customer UI, and the address-enrollment API does not itself credit funds. No customer-facing deposit address should be issued until withdrawals, outgoing reconciliation, backup recovery, and custody policy are complete. No confirmation threshold, funded reserve, loss allocation, refund policy or dispute process has been approved. This document describes current behavior and does not promise buyer protection.
## Privacy, evidence and host accountability
Public listings reveal seller/highest-bidder wallet addresses, card IDs, prices and auction state. Participant activity requires a wallet signature through the application, but **the hosting operator and anyone with its database/backups can read orders, counterparties and amounts**. The host can also observe network requests. An eventual XMR payment would not make this application-level activity anonymous. Never send seed phrases, private keys, passwords or complete wallet backups to a market/support operator.
The market uses signed actions, short request expiry, stored nonce receipts, serialized mutations and SQLite transactions to reduce unauthorized actions, accidental replay and inconsistent updates. These controls do not make the operator's database tamper-proof. Card ownership/transfer records are on-chain; order terms, payment simulation and payout markers are not blockchain-enforced. The browser still relies on its connected host to report them honestly.
Before any future live market can earn trust, its operator must publish:
- Operator identity/contact and which domain, network/chain and software release it runs; any local modifications and responsibility for the merchant wallet.
- Clear live-versus-test status, supported currency, exact quote/expiry and fee policy, payment-confirmation requirements and disclosure of custodial control.
- Seller delivery terms, payment/payout holds, network/processor costs, cancellation/late/partial/overpayment treatment, refund eligibility/costs and who bears reorg or processor losses.
- A workable dispute/reconciliation process with evidence requirements and actual response targets, including ambiguous payouts and partial success. Do not invent a support address or SLA before it exists.
- Privacy/retention policy, operational monitoring, consistent off-host backup/restore evidence, incident communication and independent security-review evidence.
Those are **requirements for a future offering**, not assurances already fulfilled by this project or every peer. The project author fee does not make the author the guarantor, custodian or arbitrator of independently hosted markets.
## A practical checklist for users
1. Check the host's domain, chain and **mock/live status**. Today's release is mock-only: do not pay real XMR.
2. Review the exact card ID, counterparty, native-XMR price (or clearly labeled historical USD price), both fees, net proceeds and deadlines before signing.
3. Keep the order/listing ID, host origin, agreed terms, status and NFT transfer identity for your records. A screenshot or status label is not independently verified proof of payment; never include secret keys/passwords in evidence.
4. Use **Your activity** on the same market host to inspect progress. Confirmations refer to canonical inclusion, not a money guarantee. Refresh after a timeout; contact the actual host through a verified channel if one is published.
5. Sellers: never equate a simulated or buyer-supplied receipt with real payment. Buyers: do not assume an off-chain reservation locks the card or guarantees a refund.
6. Protect and test your [wallet backups](wallet-security.md). If you cannot accept the host/custody/reorg risks, do not transact with valuable assets.
For operational details see [market rules](marketplace.md), [security findings](security-review.md) and [backup/recovery boundaries](operations-recovery.md). These disclosures describe the current implementation; future live features require an updated policy and explicit review before use.
-94
View File
@@ -1,94 +0,0 @@
# Peer-hosted markets
**Before buying or delivering:** read [Market payments, buyer protections and seller protections](market-transparency.md) for the complete flow, host/author fees, custody model, refund limits, privacy and dispute responsibilities. Today's payments are simulated; NFT delivery is real. The market is not trustless escrow and does not provide guaranteed reimbursement or arbitration.
Every Wikideck peer can host its own market for cards on the shared NFT blockchain. A host can serve collectors broadly or build a community around a particular collection, theme or subject. Card ownership and confirmed transfers follow the shared chain; each host keeps its own listings, bids and order journal. Buyers and sellers must use the same host to complete a sale.
The current market provides fixed-price sales and timed auctions. Running a collection-focused community is possible today, but built-in collection-specific admission, moderation and curation controls are not implemented. Peer-hosted custom trading card games are also planned, not available yet. Operators can adapt the source and presentation subject to licensing; the project still needs a published software license before open-source reuse rights can be claimed. See [project direction and licensing](../README.md#peer-ownership-and-customization).
## Cryptocurrency payments and the two sale fees
New marketplace terms use **native XMR prices** represented exactly in atomic units (12 decimal places). There is no USD conversion, exchange-rate field or live payment route. Historical version-2 USD orders remain in their original currency and signatures; USD listings are read-only until the seller closes them and signs a fresh XMR listing. Mining and payments are separate: RandomX secures Wikideck's own blockchain, while any future XMR settlement would use Monero.
Each sale allocates a configurable hosting fee to the peer's market operator (default **2.5%**) plus a hardcoded **1% author fee** to the project author's fixed XMR address. Both are deducted from the seller's gross proceeds, not compounded or secretly added to the buyer price. At the default rates the seller keeps 96.5% before any future disclosed processor/network-fee policy. The host retains the hosting allocation; the author allocation is a separate payout. **All allocations and payouts are currently simulated.**
## Current testnet sandbox
Open **Marketplace** in the interface. New prices and checkout amounts are **XMR-native**; fees, refunds, and automatic seller payouts are simulated. Historical USD orders are explicitly labeled. There is no payable address, payment processor connection, or movement of real Monero in this release. No exchange rate is applied. **Signing delivery transfers the actual card on the selected chain**, even though payment is mocked.
## Try a sale
1. Mine enough blocks to own a mature NFT. Open Marketplace → **Sell a card**.
2. Choose a card, a fixed price or timed auction, and review the seller fee before signing.
3. In a different browser profile/wallet on the **same marketplace node**, buy the fixed-price listing, or bid and wait for the auction to close.
4. Open **Your activity** as the buyer, review the order, and choose **Simulate XMR payment**.
5. Return as the seller, review the buyer/card/proceeds, and **Sign and confirm** delivery. This creates an ordinary signed NFT transfer; mine it into the canonical chain.
6. After the order's required confirmation depth, reconciliation records automatic **mock-paid** seller and additional-fee payouts. The configured market fee is retained in the simulated accounting. No operator payout click is needed.
Wallet backup/recovery remains local; never send private keys or backup passwords to the node. A Wikideck NFT wallet is not a Monero wallet.
## Sale rules
- **Fixed price:** stays listed until sold, cancelled, or invalidated by changing ownership/sequence. Checkout exclusively reserves it for 30 minutes; an unpaid reservation expires and the listing reopens if still valid.
- **Auction:** one minute to 30 days in the sandbox. Bids must meet the start price and exceed the highest bid by at least one atomic unit. Bids are signed but **unfunded**. Sellers cannot bid on their own auction or cancel after its first bid. This does not prevent alternate-wallet shill bidding or nonpayment. Live auctions remain a separate unreleased gate.
- No bids are accepted at or after the deadline. If there are bids, the listing remains available only for winner checkout until **30 minutes after auction close**, not 30 minutes after checkout. With no bids it expires at closing. An unpaid winner causes expiry; there is no automatic runner-up sale. The seller may relist.
- Seller delivery is due **48 hours after mock payment**. Failed delivery can enter **refund-required**. The buyer can simulate a full refund only if the sale transfer is neither pending nor canonical. Pending/late/ambiguous delivery requires review, not an automatic refund that might also release the card.
- Listings are **not consensus escrow**: they do not lock cards on-chain. A seller can transfer or trade elsewhere; availability is rechecked when listing, reserving, paying, and reconciling delivery. Payment and NFT delivery are **not an atomic cross-chain exchange**.
- Fee basis points are fixed when the seller lists and explicitly reviewed at checkout. The XMR quote, fee, net, and delivery-confirmation requirement are pinned to the order. Changing configuration does not reprice an existing order.
- Settlement matches the **exact canonical transfer identity**, not merely the buyer's current holdings. Unconfirmed submission never counts as delivery. A buyer may transfer onward after delivery without confusing its identity.
- If a reorganization affects an already settled order, it enters **review** permanently and does not auto-pay again. The operator must investigate; this sandbox has no administrative recovery/payment override endpoint.
New sale prices use canonical atomic-unit strings and integer arithmetic; JSON/signature payloads never use floating-point XMR. Each fee rounds down independently; seller net is gross minus both allocations. No economic listing minimum is imposed. Historical USD records retain original cents and are never converted or repriced.
## Configuration
| Variable | Default | Meaning |
| --- | --- | --- |
| `WIKIDECK_PAYMENT_MODE` | `mock` | Only accepted value. Other values fail startup, including on the mainnet candidate. |
| `WIKIDECK_MARKET_FEE_BPS` | `250` | Seller fee: 250 basis points = 2.5%; integer 0–5000. |
| `WIKIDECK_MARKET_CONFIRMATIONS` | `10` | Canonical delivery confirmations before simulated payout; integer 2–1000. No finite depth guarantees PoW finality. |
The single-node and three-node testnet Compose configurations pass these hosting-fee and delivery-confirmation settings. Choose one market host and use its origin consistently. Node marketplaces have different identities and journals: **listing, bid, checkout, and order state are not gossiped**. NFT transfers/blocks are. Buyers and sellers must use the same market host.
New listings, bids, and checkout store native XMR atomic-unit amounts (12 decimal places); they are not derived from fiat. Historical v2 records retain USD cents and their originally snapshotted mock XMR amounts. The application bound on newly entered atomic gross is documented in the [amount domain specification](xmr-domain.md); it is not a wallet-balance or exposure approval.
## Hardcoded 1% project author fee
Every new marketplace sale (fixed price or winning auction) includes a **hardcoded 1% project author fee**, on top of the configurable fee for the hosting peer's operator. Both fees are calculated independently on gross sale proceeds, not compounded. At the default 2.5% hosting fee the combined deduction is **3.5%**. Setting the hosting fee to zero does **not** disable the author fee.
The fixed public XMR payout recipient is:
44xHcCdFhW4b951yBHpkTPdLSJ85qTCnFQ8N7m96TtqqRL3dbhzbEH4fe2SJ3a6ESHcNyzCYH5nYJ9ActR1JtkeA7QYGbQv
This is a payout destination, **not a buyer checkout address**. Do not send real XMR to it to pay for a sandbox order. No real transfer is submitted; the journal only records a simulated fee allocation and payout after canonical NFT delivery. Both seller and additional-fee payouts enter review if a settled delivery is reorganized. Refunded or expired sales do not pay either recipient. The fee applies to marketplace sales, not free NFT transfers, card-for-card trades, bids or listing creation, which have no XMR sale proceeds.
The additional fee is rounded down to an atomic unit separately from the hosting fee. Seller net is exactly gross minus **both** fees. For example, a 0.1 XMR sale with 2.5% hosting allocates 0.0025 XMR hosting fee, 0.001 XMR additional fee, and 0.0965 XMR seller net. Rounding below one atomic unit produces zero rather than increasing the charge above 1%.
The recipient and percentage are snapshotted into each new order and disclosed in the UI. They are bound to v3 listing/checkout signatures and are neither environment-configurable nor request-overridable. **Existing reserved/paid/completed v2 orders are not retroactively repriced.** Open USD listings remain read-only until eligible sellers close them and relist with fresh v3 XMR authorization; historical bids are not converted. The v2 domain remains for compatibility with historical orders and receipts; new USD listings, bids, and checkout are rejected.
## API and storage
- `GET /api/market?offset=0` returns up to 24 public listings, pagination, server clock, fee policy, and market identity.
- `POST /api/market/command` accepts strict, signed commands. New XMR terms use `market-command-v3`; historical `market-command-v2` is retained only to service existing orders and eligible seller cancellation. Actions include `list`, `bid`, `buy`, `cancel`, `retire-legacy-listing`, `mock-pay`, `deliver`, `refund`, and `activity` under their allowed version.
- Every command binds the network, chain ID, **market instance ID**, actor/public key, UUID nonce, short expiry, action, and all versioned terms. New prices sign the currency and canonical atomic XMR gross. Private activity requires a wallet signature and includes only orders involving that actor. Signed requests expire within five minutes; keep clocks synchronized.
- Nonce receipts are persisted and replay returns the same result. A different command cannot reuse that nonce. Refresh activity to obtain the latest order state rather than interpreting an old receipt as current state.
- Public listings reveal seller/highest bidder wallet addresses and card holdings. Orders reveal counterparties/amounts only to their participants, but the **market operator and its database backups can see all orders**. This is not private Monero trading.
- The marketplace journal is stored alongside the ledger in the selected network subdirectory, uses SQLite/WAL and full synchronous commits, and binds its metadata to the active chain. Mutations are serialized. There is one active local listing per card, at most 100 active listings per seller, and 10,000 total listings/orders per journal. Reaching a journal cap fails closed; operator archival work is required, not deleting active records.
- HTTP rate limits and bounded mutation queues apply. Read/reconciliation work still scans the bounded journal and chain; this is not a high-volume production market.
## Recovery and operations
Back up the ledger, marketplace SQLite databases and their WAL state consistently, plus the independent wallet backups. Prefer a clean node shutdown before copying the data directory; do not copy a live SQLite file without SQLite's backup facilities. Do not delete the journal to clear a stuck order: this loses reservations, invoice identities and idempotency history.
The service writes delivery intent before submitting to the ledger. A crash between these steps is reconciled by deterministic transfer ID; the seller can resubmit the same delivery if still valid. Background reconciliation runs every 15 seconds, and marketplace commands reconcile before mutation. A closed server does not send payouts or advance its local journal until restarted; deadline enforcement still uses absolute timestamps.
Canonical and pending sale delivery is recognized by the agreed seller/buyer/card/sequence even if submitted through the normal transfer endpoint or peer gossip rather than the marketplace command. Direct delivery without a recorded mock payment enters review instead of paying the seller. A refund check cannot cancel a previously signed transfer that arrives later or after a reorganization; this is a [production settlement blocker](security-review.md), not a solved atomic-exchange guarantee.
For **review**, preserve backups and inspect canonical blocks, pending transfers, signed order terms and transfer ID. Do not clear a payout marker, auto-refund, or blindly resubmit a payout. This release intentionally has no real-fund recovery controls.
## Future live XMR custody
The selected direction is a pooled custodial ledger, not per-sale processor invoices. Real deposits would be assigned to durable Monero subaddresses and reconciled against wallet-owned outputs; purchases would transfer liabilities internally. Withdrawals would require a separate, policy-constrained treasury signer and durable reconciliation. A mainnet-only address-enrollment API now exists behind `WIKIDECK_MONERO_DEPOSIT_ENROLLMENT=1`, but it is off by default and has no customer UI; its response explicitly says the address is not credited. There is still no customer credit worker, withdrawal signer, or paid-sale settlement path. **Do not enable the enrollment API or publish its addresses until customers can be credited, withdraw, and recover funds end-to-end.**
The selected direction is a pooled custodial ledger, not per-sale processor invoices. Deposits are associated with durable Monero subaddresses and an operator-reviewed observation can now be staged as a pending liability, then separately released to a customer's available balance. A separate mainnet-only API can accept signed withdrawal requests, reserve the exact amount plus maximum fee from that balance, and let the customer cancel before signer handoff. Both mainnet paths require dedicated PostgreSQL roles and explicit startup/operator configuration. **They are not a complete payment system:** the current withdrawal endpoint only reserves liabilities; there is no transaction construction, signer, relay, outgoing-chain confirmation or recovery process, and no customer UI. Deposits and withdrawals remain off by default. Do not publish addresses or solicit funds until the XMR send and recovery lifecycle is proven.
Do not send real XMR to this sandbox. Live activation requires an end-to-end reviewed implementation, funded-liability and custody policies, production wallet/daemon isolation, withdrawal/reorg recovery, backups and operations evidence. No payment-mode setting is an activation path.
+40
View File
@@ -0,0 +1,40 @@
# WikiDeck Android app (Night 1)
A Capacitor 7 shell (`dev.eom.wikideck`) around the React UI. It talks to a WikiDeck node over native HTTP.
![Android emulator screenshots](android/screens.jpg)
## Build a debug APK
You need JDK 21 (a full JDK with `javac`), the Android SDK (platform 35 and build-tools 35) and `ANDROID_HOME`.
```
android/build-debug.sh # testnet build: VITE_WIKIDECK_NETWORK=testnet, genesis 1792411200, node http://192.168.1.32:3101
adb install -r android/app/build/outputs/apk/debug/app-debug.apk
```
- **Settings:** override any of them with env vars, for example `VITE_NODE_URL=http://192.168.1.32:3102 android/build-debug.sh`.
- **Network:** without `VITE_WIKIDECK_NETWORK=testnet`, the bundle is a **mainnet** build.
- **Signing:** debug signing only. Nothing is published.
## How it works (`src/native.ts`, imported first in `main.tsx`; does nothing on the web)
- **Node URL:** relative `fetch('/api/…')` and `fetch('/auth/…')` calls go to `VITE_NODE_URL`. The default is the Night-1 testnet node. A runtime override is available through `setNodeUrl()`, stored in localStorage.
- **Native HTTP (`CapacitorHttp`):** fetches go through Android's HTTP stack. There's no CORS, and no WebView `Origin` header, so the node's POST origin check passes without any server change.
- Verified: a POST from the app returns 400 (validation), while the same POST with `Origin: https://localhost` returns 403.
- The interceptor merges headers (`content-length: 0, 384`). `native.ts` drops that header so `StateClient`'s size check works, and byte limits are still enforced while streaming.
- **Mining:** RandomX is desktop-only. `isNativeApp()` hides the mining panel, and `html.native-app` lets CSS target the app.
- **SSO:** "Log in with eom.dev" opens Dex in a Custom Tab (`setNativeBrowser(Browser)`). Dex redirects to `dev.eom.wikideck:/oauth/callback` (intent filter, `singleTask`), and `completeLogin()` has the node exchange the code.
- **Android behaviour:**
- The **back button** closes an open dialog first, then goes back in history, then minimizes the app.
- The **keyboard** uses `adjustResize`.
- **Edge-to-edge** margins are on, with a dark window behind the system bars.
## Emulator (inspiron-3670, user space)
The SDK, AVD and JDK are under `~/worker/jobs/night/mobile-android/{sdk,avd,jdk}`, and `env.sh` sets the paths.
```
emulator -avd wikideck -no-window -no-audio -gpu swiftshader_indirect # headless, KVM
adb exec-out screencap -p > shot.png
```
To inspect the WebView, forward DevTools with `adb forward tcp:9222 localabstract:webview_devtools_remote_$(adb shell pidof dev.eom.wikideck)`.
## Known gaps
- **Real SSO login:** needs an eom.dev account and wasn't done tonight. The deep-link round trip was verified up to Dex's `invalid_grant` for a dummy code.
- **Touch targets in the Play UI:** the dashed "Play here" lane zone doesn't respond to taps; only the lane plate does (reported on #5).
- **Mining copy on the home hero:** "Explore mining" still shows in the app.
+53
View File
@@ -0,0 +1,53 @@
# Night 1: module boundaries
Owner: `night-lead`. This file is the rule when two PRs touch the same path. If you need to edit a path you don't own, comment on the owner's issue (`[from <you>]`) or keep your change to the "shared hook" listed below.
## Who owns what
| Path | Owner | Issue |
|---|---|---|
| `docs/game/DESIGN.md` | council (designer-a, designer-b, critic) | #1 |
| `docs/game/CARD_DATA.md`, `docs/game/card-sample.json` | council-data | #2 |
| `shared/game/` (types, RNG, state machine, rules, keywords, `Ruleset`, `starterDeck`) | engine-a (core, API), engine-b (keywords, effects) | #3 |
| `docs/game/ENGINE_API.md` | engine-a | #3 |
| `shared/game/modes.ts` | modes | #6 |
| `server/game*` (e.g. `server/game/`, `server/game-*.ts`) | modes | #6 |
| `docs/game/HOSTING.md` | modes | #6 |
| `src/game/` (screens, lobby, deck builder, match, tutorial) | ui-a | #5 |
| `src/game/ai/` (browser bots, easy and normal) | ui-b | #5 |
| beta-fix files outside `src/game/` (landing page, `Card.tsx`, etc.) | ui-b, one PR per upstream issue | #5 |
| `shared/bots/`, `scripts/sim/` (bots and the simulation runner) | sim-balance | #4 |
| `docs/game/BALANCE.md` | sim-balance | #4 |
| `compose.testnet.yaml` overrides, `deploy/night/` (testnet config, per-node mode files) | sim-testnet | #4 |
| `server/account*` (e.g. `server/account/`), `src/auth/` | sso | #7 |
| `android/`, `capacitor.config.ts` | mobile-android | #8 |
| `ios/`, `docs/night/IOS.md` | mobile-ios, macos-fetch | #9 |
| `docs/night/` (except `IOS.md`), this file, `REPORT.md` | night-lead | #10 |
## Tests
`scripts/run-tests.mjs` only picks up **top-level** `tests/*.test.ts`. Name your files with your team as a prefix so they never collide:
`tests/game-*.test.ts` (engine), `tests/modes-*.test.ts`, `tests/ui-*.test.ts`, `tests/bots-*.test.ts`, `tests/account-*.test.ts`.
## Shared hooks (the only places two teams touch the same file)
1. **`server/testnet/http.ts`**: modes and sso each export an Express `Router` from their own files and add **exactly one** `app.use(...)` mount line just **above** the `/api` 404 handler (`app.use(['/api','/p2p'],(_req,res)=>{res.status(404)...`). Nothing else in this file. If SSO needs a CSP change (`connect-src` for `https://dex.eom.dev`), keep it to the `helmet` directive and say so in the PR.
2. **`src/App.tsx`**: ui-a owns it. Others get one import and one element each (sso: a login button or provider; mobile: hide the mining controls behind a `isNativeApp()` check from `src/game/` or `src/auth/`, never by deleting code).
3. **`package.json` and `package-lock.json`**: additive changes only (new dependencies or scripts). Don't reformat or bump existing versions. Lockfile conflicts are resolved by night-lead regenerating the lockfile.
4. **`shared/enrichment.ts`**: read-only for everyone tonight. Map card data into game stats inside `shared/game/`.
## Off limits (consensus and protocol; PRs touching these are rejected)
`server/chain.ts`, `shared/protocol.ts`, `shared/trade-offer.ts`, `shared/chain-identity.ts`, `shared/network.ts`, `server/testnet/consensus.ts`, `server/testnet/ledger.ts`, `server/testnet/canonical-index.ts`, `server/testnet/randomx.ts`, `server/testnet/miner.ts`, `server/testnet/peers.ts`, `native/`.
If you think you need a change there, write it up in your issue instead.
## Dependency direction
`shared/game/` imports nothing from `server/` or `src/` and does no I/O. `shared/game/modes.ts`, `shared/bots/`, `server/game*`, `src/game/` import from `shared/game/` through the API in `ENGINE_API.md`, not from its internals.
## Merging
- Branch `night/<team>/<topic>`, PR into `night/2026-11-16`, squash-merged by night-lead after night-review approves and `npm test` and `npm run build` pass.
- Small PRs merge faster. Rebase on the integration branch before asking for review if it moved under you.
- After 01:10 (code freeze), only fixes merge.

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