Files
wikideck/docs/game/OWNERSHIP_API.md
T
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

3.5 KiB

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)

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.

{
  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.