forked from WikiDeck/wikideck
Night 2 (2026-11-17), from the `claude/wikideck` fork's `night/2026-11-17` branch. It follows Night 1 (#22).
## What's in it
- **Duel engine** (fork #72, #80): 40-card decks of cards you own, Notability/Citations, keywords, effects T1–T12, Connected, a hidden-information-safe `viewFor`/`logFor`, and replay. Balance v1 tuning (#84) gives the first player about 51%.
- **Card profiles** (#70, #82): Figure, Location, Event, Institution or Doctrine, plus stats, keywords and rules text, all derived from real article data. Templates only.
- **Design and story** (#66, #69, #83): DUEL_DESIGN.md, plus the match log and the encyclopedic "Battle of X (2026)" recap.
- **PvP** (#74, #77, #81, #76, #85):
- The server checks ownership, and 40-card eligibility is enforced.
- Modes: Classic (ranked), Draft and Trending.
- Invites, quick match, Elo, a ladder and recap pages. Online matches render on the duel board.
- **Duel board UI** (#79): MTG-style card faces and combat declaration, built for 360 px first.
- **Polite Wikimedia client** (#73, #75): throttled, cached and identified requests, the mint-path fix, and a prefetch pool.
- **Android mining** (#78): native RandomX, as a sideload build. The emulator mined a testnet block.
- **Testnet ops** (#67, #68).
PR numbers refer to `claude/wikideck`.
## Status
- **Tests:** 423, of which 422 pass, 0 fail and 1 is skipped. The build is OK (`node:24-alpine`, `--network none`).
- **Testnet:** running this commit (036489c) on r350.
- **Untouched:** no changes to `server/testnet/consensus.ts`, `randomx.ts`, `native/` or the mainnet compose.
- **Review:** night-review reviewed fork #66–#79. #80–#85 came from the agents' unfinished branches and were not reviewed.
- **Known gaps:**
- The PvP end-to-end test hasn't been run (it needs two eom.dev accounts).
- Bot matches aren't reachable from Play.
- Card identity pre-bake hasn't been done.
- The RandomX verifier latch (`server/testnet/randomx.ts:140`) is still open.
This PR is for Eric to merge.
🤖 Generated with [Claude Code](https://claude.com/claude-code)Reviewed-on: WikiDeck/wikideck#23
Co-authored-by: Claude <claude@eom.dev>
74 lines
3.5 KiB
Markdown
74 lines
3.5 KiB
Markdown
# Ownership and collection API (Night 2, #57)
|
|
|
|
Server-side checks that a player owns the cards they play. Off-chain only: nothing here moves, burns or locks a card, and nothing changes consensus.
|
|
|
|
## The rules (ruleset data)
|
|
|
|
| Key | Default | Meaning |
|
|
|---|---|---|
|
|
| `deckSize` | 40 | A constructed deck has exactly this many cards. A testnet mode file may lower it. |
|
|
| `maxCopiesPerPage` | 4 | The MTG-style copy limit. Cards minted from the same Wikipedia `pageId` are separate cards, but at most this many go in one deck. |
|
|
| `minConfirmations` | 1 | The confirmations each card's mint block needs. Rated play uses `RATED_MIN_CONFIRMATIONS` = 3. |
|
|
|
|
## `server/game/ownership.ts` (used by the PvP host)
|
|
|
|
```ts
|
|
verifyAccount(deps, idToken: unknown): Promise<Account>
|
|
resolveDeck(deps, account, tokenIds: unknown, opts?: Partial<OwnershipRules>): Promise<ChainCard[]>
|
|
collection(deps, account, opts?: { minConfirmations?: number }): Promise<ChainCard[]>
|
|
```
|
|
|
|
- **`deps`** is `{ ledger, accounts, verifyIdToken }`. In production, `server/testnet/http.ts` builds it from the node's `Ledger`, the shared `AccountStore`, and `accountVerifier()` from `server/account/router.ts`. It passes the result to `gameRouter({ ownership })`.
|
|
- **`resolveDeck`** accepts token ids only, never card JSON. For each card it checks:
|
|
- the card is on the canonical chain (`ledger.nft()`);
|
|
- its current owner (after transfers) is one of the account's linked wallets;
|
|
- it has enough confirmations;
|
|
- the deck size and copy limit.
|
|
|
|
Each card is rebuilt from its own block (`article` and `statsSnapshot`). The cards come back in the order given.
|
|
- **Errors** are thrown as `DeckError { code, status, tokenIds, pageId? }`. `tokenIds` lists every offending card of that class.
|
|
|
|
| `code` | `status` |
|
|
|---|---|
|
|
| `auth` | 401 |
|
|
| `size` | 400 |
|
|
| `duplicate-token` | 400 |
|
|
| `unknown-token` (not on chain, or malformed) | 400 |
|
|
| `not-owned` (includes "no linked wallet") | 403 |
|
|
| `unconfirmed` | 400 |
|
|
| `copy-limit` | 400 |
|
|
|
|
`OwnershipUnavailable` (503) means Dex is unreachable or the chain tip kept moving during a read.
|
|
- **`collection`** pages `ledger.deck()` (24 per page) across every linked wallet at one canonical tip, restarting if the tip moves. There is no 128-block snapshot cap.
|
|
|
|
## `GET /api/game/collection`
|
|
|
|
`Authorization: Bearer <Dex ID token>` (the same token as `/api/account/me`). Optional: `?minConfirmations=N`.
|
|
|
|
```ts
|
|
{
|
|
tip, wallets: string[],
|
|
deckSize: 40, copyLimit: 4, maxCopiesPerPage: 4, minConfirmations: 1,
|
|
owned: number, // confirmed cards across all linked wallets
|
|
playable: number, // Σ min(copies, copyLimit) per pageId
|
|
needed: number, // max(0, deckSize - playable)
|
|
eligible: boolean, // playable >= deckSize
|
|
cards: ChainCard[] // tokenId, owner, confirmations, pageId, title, revisionId, url, extract, imageUrl?,
|
|
// height, blockHash, createdAt, powHash, article, statsSnapshot
|
|
}
|
|
```
|
|
|
|
| Case | Response |
|
|
|---|---|
|
|
| No linked wallets | 200 with `cards: []` and `needed: 40` |
|
|
| Missing or invalid token | 401 |
|
|
| Dex unreachable | 503 |
|
|
| Bad query | 400 |
|
|
|
|
The UI shows `playable / deckSize`, for example "23 / 40 cards", and how to mine.
|
|
|
|
## Not covered (known gaps)
|
|
|
|
- **Peer hosts.** Account stores are per node, and a Dex token sent to a peer could be replayed elsewhere (engineer review §2, G6). This API is for the self-hosted node only. The stretch fix is a wallet-signed deck claim.
|
|
- **Plausibility of minted stats** (G5): `pageId` → `title` and `revisionId` → `size` are not cross-checked yet.
|