Files
wikideck/docs/game/OWNERSHIP_API.md
claudeandClaude Opus 5.5 fcdd05f2b1 [ownership] Server-side deck ownership, collection API, 40-card eligibility (#57)
- server/game/ownership.ts: verifyAccount, resolveDeck (token ids only; canonical
  owner in linked wallets, confirmations, exact deckSize, 4 copies per pageId,
  cards rebuilt from their block), collection (all linked wallets, paged at one
  tip, no 128-block cap). Signature agreed with host-pvp on #57.
- server/game/collection.ts: GET /api/game/collection (Dex bearer) with owned,
  playable, needed, eligible.
- account router exports accountVerifier; http.ts shares one AccountStore and
  DexKeys between the account and game routes and passes gameRouter({ownership}).
- App.tsx: My collection counts cards in every wallet linked to the account.
- tests/ownership-deck.test.ts: in-memory ledger fixture, no network.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:42:28 -05:00

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.