@xgamesfun/solana 0.24.0 → 0.25.1

package/js/play/keys.js

@@ -13,18 +13,33 @@ import { concat, fromBase64, randomBytes, toBase64, toHex, utf8 } from '../chain
 import { sha256 } from '../chain/sha256.js';
 
 /** The PKCS #8 header of a raw 32-byte Ed25519 seed (RFC 8410). */
-const PKCS8_ED25519 = Uint8Array.from([0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20]);
+const PKCS8_ED25519 = Uint8Array.from([
+  0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20,
+]);
 
 const DERIVED = 'derived';
-const fromBase64Url = (text) => fromBase64(text.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(text.length / 4) * 4, '='));
+const fromBase64Url = text =>
+  fromBase64(
+    text
+      .replace(/-/g, '+')
+      .replace(/_/g, '/')
+      .padEnd(Math.ceil(text.length / 4) * 4, '='),
+  );
 
 /** An Ed25519 key from its 32-byte seed: { address, sign(message) }. */
 export async function keyFromSeed(seed, name = null) {
   const subtle = globalThis.crypto.subtle;
   const pkcs8 = concat(PKCS8_ED25519, seed);
-  const jwk = await subtle.exportKey('jwk', await subtle.importKey('pkcs8', pkcs8, { name: 'Ed25519' }, true, ['sign']));
+  const jwk = await subtle.exportKey(
+    'jwk',
+    await subtle.importKey('pkcs8', pkcs8, { name: 'Ed25519' }, true, ['sign']),
+  );
   const signer = await subtle.importKey('pkcs8', pkcs8, { name: 'Ed25519' }, false, ['sign']);
-  return { address: encodeBase58(fromBase64Url(jwk.x)), name, sign: async (message) => new Uint8Array(await subtle.sign('Ed25519', signer, message)) };
+  return {
+    address: encodeBase58(fromBase64Url(jwk.x)),
+    name,
+    sign: async message => new Uint8Array(await subtle.sign('Ed25519', signer, message)),
+  };
 }
 
 /** The text a wallet signs once a session for its settle keys. It moves nothing and says so. */
@@ -40,9 +55,9 @@ export function browserStore() {
   if (!ls || !globalThis.indexedDB) return null;
   let device = null;
   return {
-    get: (k) => ls.getItem(k),
+    get: k => ls.getItem(k),
     set: (k, v) => ls.setItem(k, v),
-    remove: (k) => ls.removeItem(k),
+    remove: k => ls.removeItem(k),
     keys: () => Array.from({ length: ls.length }, (_, i) => ls.key(i)).filter(Boolean),
     cryptoKey: () => (device ??= deviceKey().catch(() => null)),
   };
@@ -61,7 +76,10 @@ async function deviceKey() {
     r.onerror = () => reject(r.error);
   });
   if (found) return found;
-  const key = await globalThis.crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+  const key = await globalThis.crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, false, [
+    'encrypt',
+    'decrypt',
+  ]);
   await new Promise((resolve, reject) => {
     const tx = db.transaction('keys', 'readwrite');
     tx.objectStore('keys').put(key, 'device');
@@ -120,7 +138,13 @@ export function keyring({ wallet, project, store = null }) {
     const device = await store?.cryptoKey?.();
     if (!device || !text) return null;
     const bytes = fromBase64(text);
-    return new Uint8Array(await globalThis.crypto.subtle.decrypt({ name: 'AES-GCM', iv: bytes.subarray(0, 12) }, device, bytes.subarray(12)));
+    return new Uint8Array(
+      await globalThis.crypto.subtle.decrypt(
+        { name: 'AES-GCM', iv: bytes.subarray(0, 12) },
+        device,
+        bytes.subarray(12),
+      ),
+    );
   }
 
   return {
@@ -157,7 +181,9 @@ export function keyring({ wallet, project, store = null }) {
     stored() {
       if (!store) return [];
       const p = prefix();
-      return safe(() => store.keys(), []).filter((k) => k.startsWith(p)).map((k) => k.slice(p.length));
+      return safe(() => store.keys(), [])
+        .filter(k => k.startsWith(p))
+        .map(k => k.slice(p.length));
     },
 
     forget(name) {

package/js/results/index.js

@@ -1,5 +1,5 @@
 // `@xgamesfun/solana/results`: what a game uses with a results server, in a host server or in a player's game page.
-// Browser-safe: Web Crypto only. `server` is RESULTS_SERVER (the public one, on the games.fun play host), or another
+// Browser-safe: Web Crypto only. `server` is RESULTS_SERVER (the public one, on the xgames.fun play host), or another
 // one's URL. The server confirms who won (from signatures rooted on the chain) and signs grant vouchers; winners claim
 // them with js/play (`claimWins`, `claimGrant`). The program pays a wallet each round once, ever, whatever is signed.
 //
@@ -23,21 +23,37 @@ import { toHex } from '../chain/bytes.js';
 import { pda, voucherBytes } from '../client/index.js';
 import { canonicalJson, drawText, entryText, lockText, resultBytes, rosterHash } from './wire.js';
 
-export { canonicalJson, CERT_KINDS, CLUSTERS, drawText, entryText, giveawayHostText, hostCertText, lockText, NO_GRANT, RESULT_DOMAIN, resultBytes, revokeGiveawayText, revokeText, rosterHash } from './wire.js';
+export {
+  canonicalJson,
+  CERT_KINDS,
+  CLUSTERS,
+  drawText,
+  entryText,
+  giveawayHostText,
+  hostCertText,
+  lockText,
+  NO_GRANT,
+  RESULT_DOMAIN,
+  resultBytes,
+  revokeGiveawayText,
+  revokeText,
+  rosterHash,
+} from './wire.js';
 
-/** games.fun's results server, on its play host (devnet until the program's audit). */
+/** xgames.fun's results server, on its play host (devnet until the program's audit). */
 export const RESULTS_SERVER = 'https://play.xgames.fun/xsolana';
 
 const subtle = () => globalThis.crypto.subtle;
 /** A value as a query's value: encoded, so a `&`, `#` or `/` in it is part of the value. */
-const q = (value) => encodeURIComponent(String(value));
+const q = value => encodeURIComponent(String(value));
 /**
  * A value as one segment of a URL's path: encoded, so a `/` or `?` in it stays inside the segment. One that is empty,
  * `.` or `..` (which a URL reads as a step up the path, encoded or not) is refused.
  */
-const seg = (value) => {
+const seg = value => {
   const text = String(value);
-  if (text === '' || text === '.' || text === '..') throw new RangeError(`${JSON.stringify(text)} can't be a part of a path.`);
+  if (text === '' || text === '.' || text === '..')
+    throw new RangeError(`${JSON.stringify(text)} can't be a part of a path.`);
   return encodeURIComponent(text);
 };
 
@@ -58,7 +74,25 @@ export async function newKey() {
 export async function keyFromSecret(secret) {
   const seed = decodeBase58(secret);
   if (seed.length !== 32) throw new Error('A host key secret is 32 bytes in base58.');
-  const pkcs8 = new Uint8Array([0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20, ...seed]);
+  const pkcs8 = new Uint8Array([
+    0x30,
+    0x2e,
+    0x02,
+    0x01,
+    0x00,
+    0x30,
+    0x05,
+    0x06,
+    0x03,
+    0x2b,
+    0x65,
+    0x70,
+    0x04,
+    0x22,
+    0x04,
+    0x20,
+    ...seed,
+  ]);
   const privateKey = await subtle().importKey('pkcs8', pkcs8, { name: 'Ed25519' }, true, ['sign']);
   const jwk = await subtle().exportKey('jwk', privateKey);
   return keyOf(privateKey, base64url(jwk.x), jwk.d);
@@ -68,13 +102,13 @@ function keyOf(privateKey, publicBytes, d) {
   return {
     address: encodeBase58(publicBytes),
     secret: encodeBase58(base64url(d)),
-    sign: async (message) => new Uint8Array(await subtle().sign({ name: 'Ed25519' }, privateKey, message)),
+    sign: async message => new Uint8Array(await subtle().sign({ name: 'Ed25519' }, privateKey, message)),
   };
 }
 
 function base64url(text) {
   const bin = atob(text.replace(/-/g, '+').replace(/_/g, '/'));
-  return Uint8Array.from(bin, (c) => c.charCodeAt(0));
+  return Uint8Array.from(bin, c => c.charCodeAt(0));
 }
 
 /** One signer's signature of a result: { key, signature }. `signer` is a key from newKey, or anything with sign(). */
@@ -87,7 +121,17 @@ export async function signResult(signer, result, cluster = 'devnet') {
  * with the same result is safe: it is the same answer. Returns the server's answer, { result, vouchers }, or throws its
  * { code, why }.
  */
-export async function report({ server, cert, signer, game, round, endedAt, winners, cluster = 'devnet', fetchImpl = globalThis.fetch }) {
+export async function report({
+  server,
+  cert,
+  signer,
+  game,
+  round,
+  endedAt,
+  winners,
+  cluster = 'devnet',
+  fetchImpl = globalThis.fetch,
+}) {
   const result = { game, round, endedAt, winners };
   const all = [await signResult(signer, result, cluster)];
   const response = await fetchImpl(`${server.replace(/\/$/, '')}/v1/results`, {
@@ -104,14 +148,26 @@ export async function report({ server, cert, signer, game, round, endedAt, winne
  */
 async function answerOf(response) {
   const answer = await response.json().catch(() => null);
-  if (!response.ok) throw Object.assign(new Error(answer?.error?.why ?? `The results server answered ${response.status}${response.statusText ? ` ${response.statusText}` : ''}.`), { code: answer?.error?.code, status: response.status });
-  if (answer === null || typeof answer !== 'object') throw Object.assign(new Error(`The results server answered ${response.status} with no JSON.`), { status: response.status });
+  if (!response.ok)
+    throw Object.assign(
+      new Error(
+        answer?.error?.why ??
+          `The results server answered ${response.status}${response.statusText ? ` ${response.statusText}` : ''}.`,
+      ),
+      { code: answer?.error?.code, status: response.status },
+    );
+  if (answer === null || typeof answer !== 'object')
+    throw Object.assign(new Error(`The results server answered ${response.status} with no JSON.`), {
+      status: response.status,
+    });
   return answer;
 }
 
 /** A wallet's vouchers for a round it won: [{ grant, publicKey, signature, round, expires, … }]. */
 export async function fetchVouchers({ server, game, round, wallet, fetchImpl = globalThis.fetch }) {
-  const response = await fetchImpl(`${server.replace(/\/$/, '')}/v1/vouchers?game=${q(game)}&round=${q(round)}&wallet=${q(wallet)}`);
+  const response = await fetchImpl(
+    `${server.replace(/\/$/, '')}/v1/vouchers?game=${q(game)}&round=${q(round)}&wallet=${q(wallet)}`,
+  );
   return (await answerOf(response)).vouchers;
 }
 
@@ -126,19 +182,56 @@ export async function fetchVouchers({ server, game, round, wallet, fetchImpl = g
  * Returns { wallet, grant, incarnation, publicKey, signature, round, expires, personHash, amount } for js/play claimGrant,
  * plain JSON (`incarnation` and `amount` as decimal text), so a server can send it as it is.
  */
-export async function signVoucher({ signer, game, grant, incarnation, wallet, round, now, seconds = 7 * 86_400, personHash = null, amount = 0n }) {
-  if (!(Number(seconds) > 0)) throw new RangeError('A voucher lives some seconds from now (`seconds` above 0): one that has run out already pays nothing.');
+export async function signVoucher({
+  signer,
+  game,
+  grant,
+  incarnation,
+  wallet,
+  round,
+  now,
+  seconds = 7 * 86_400,
+  personHash = null,
+  amount = 0n,
+}) {
+  if (!(Number(seconds) > 0))
+    throw new RangeError(
+      'A voucher lives some seconds from now (`seconds` above 0): one that has run out already pays nothing.',
+    );
   if (Number(seconds) > 30 * 86_400) throw new Error('A voucher lives 30 days at most.');
   // The cluster's clock comes as a number or a bigint (an RPC's, a decoded Clock's); `expires` is a number either way.
   const expires = Math.floor(typeof now === 'bigint' ? Number(now) : now) + Number(seconds);
-  if (!Number.isSafeInteger(expires)) throw new RangeError('A voucher needs the cluster\'s clock (`now`, unix seconds).');
-  const message = voucherBytes({ grant: pda.grant(game, grant), incarnation, wallet, personHash, round, expires, amount: BigInt(amount) });
-  return { wallet, grant, incarnation: String(BigInt(incarnation)), publicKey: signer.address, signature: encodeBase58(await signer.sign(message)), round, expires, personHash: personHash ?? '0'.repeat(64), amount: String(BigInt(amount)) };
+  if (!Number.isSafeInteger(expires))
+    throw new RangeError("A voucher needs the cluster's clock (`now`, unix seconds).");
+  const message = voucherBytes({
+    grant: pda.grant(game, grant),
+    incarnation,
+    wallet,
+    personHash,
+    round,
+    expires,
+    amount: BigInt(amount),
+  });
+  return {
+    wallet,
+    grant,
+    incarnation: String(BigInt(incarnation)),
+    publicKey: signer.address,
+    signature: encodeBase58(await signer.sign(message)),
+    round,
+    expires,
+    personHash: personHash ?? '0'.repeat(64),
+    amount: String(BigInt(amount)),
+  };
 }
 
 /** Posts JSON to the server and answers its body, or throws its { code, why }. */
 async function post(server, path, body, fetchImpl) {
-  const response = await fetchImpl(`${server.replace(/\/$/, '')}${path}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+  const response = await fetchImpl(`${server.replace(/\/$/, '')}${path}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
   return answerOf(response);
 }
 
@@ -151,34 +244,134 @@ const fetchJson = async (server, path, fetchImpl) => answerOf(await fetchImpl(`$
  */
 export const draws = {
   open: async ({ server, signMessage, by, cert = null, rates = null, fetchImpl = globalThis.fetch, ...spec }) => {
-    const ratesHash = rates ? Array.from(new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonicalJson(rates)))), (b) => b.toString(16).padStart(2, '0')).join('') : 'default';
+    const ratesHash = rates
+      ? Array.from(
+          new Uint8Array(
+            await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonicalJson(rates))),
+          ),
+          b => b.toString(16).padStart(2, '0'),
+        ).join('')
+      : 'default';
     const text = drawText({ ...spec, rates: ratesHash });
-    return post(server, '/v1/draws', { text, signature: encodeBase58(await signMessage(new TextEncoder().encode(text))), by, ...(cert ? { cert } : {}), ...(rates ? { rates } : {}) }, fetchImpl);
+    return post(
+      server,
+      '/v1/draws',
+      {
+        text,
+        signature: encodeBase58(await signMessage(new TextEncoder().encode(text))),
+        by,
+        ...(cert ? { cert } : {}),
+        ...(rates ? { rates } : {}),
+      },
+      fetchImpl,
+    );
   },
   /** A player enters with their play-host token, or with their wallet's signature (`wallet`, `signMessage`). */
-  enter: async ({ server, game, draw, token = null, wallet = null, signMessage = null, cluster = 'devnet', fetchImpl = globalThis.fetch }) => {
+  enter: async ({
+    server,
+    game,
+    draw,
+    token = null,
+    wallet = null,
+    signMessage = null,
+    cluster = 'devnet',
+    fetchImpl = globalThis.fetch,
+  }) => {
     if (token) return post(server, `/v1/draws/${seg(game)}/${seg(draw)}/entries`, { token }, fetchImpl);
     const text = entryText({ cluster, game, draw });
-    return post(server, `/v1/draws/${seg(game)}/${seg(draw)}/entries`, { wallet, text, signature: encodeBase58(await signMessage(new TextEncoder().encode(text))) }, fetchImpl);
+    return post(
+      server,
+      `/v1/draws/${seg(game)}/${seg(draw)}/entries`,
+      { wallet, text, signature: encodeBase58(await signMessage(new TextEncoder().encode(text))) },
+      fetchImpl,
+    );
   },
   /** Locks the players the server holds now to `beacon`, a drand round still to come. Checks their hash itself. */
-  lock: async ({ server, game, draw, beacon, signMessage, by, cert = null, cluster = 'devnet', net = 'quicknet', fetchImpl = globalThis.fetch }) => {
+  lock: async ({
+    server,
+    game,
+    draw,
+    beacon,
+    signMessage,
+    by,
+    cert = null,
+    cluster = 'devnet',
+    net = 'quicknet',
+    fetchImpl = globalThis.fetch,
+  }) => {
     const { draw: view } = await fetchJson(server, `/v1/draws/${seg(game)}/${seg(draw)}`, fetchImpl);
-    const text = lockText({ cluster, game, draw, roster: await rosterHash(view.entries), players: view.entries.length, beacon, net });
-    return post(server, `/v1/draws/${seg(game)}/${seg(draw)}/lock`, { text, signature: encodeBase58(await signMessage(new TextEncoder().encode(text))), by, ...(cert ? { cert } : {}) }, fetchImpl);
+    const text = lockText({
+      cluster,
+      game,
+      draw,
+      roster: await rosterHash(view.entries),
+      players: view.entries.length,
+      beacon,
+      net,
+    });
+    return post(
+      server,
+      `/v1/draws/${seg(game)}/${seg(draw)}/lock`,
+      {
+        text,
+        signature: encodeBase58(await signMessage(new TextEncoder().encode(text))),
+        by,
+        ...(cert ? { cert } : {}),
+      },
+      fetchImpl,
+    );
   },
   /** The draw as anyone may check it; settled, with its result, once its beacon round is out. */
-  get: async ({ server, game, draw, fetchImpl = globalThis.fetch }) => (await fetchJson(server, `/v1/draws/${seg(game)}/${seg(draw)}`, fetchImpl)).draw,
+  get: async ({ server, game, draw, fetchImpl = globalThis.fetch }) =>
+    (await fetchJson(server, `/v1/draws/${seg(game)}/${seg(draw)}`, fetchImpl)).draw,
 };
 
 /** A giveaway, from its appointed host's page. */
 export const giveaways = {
   /** Opens one: `cert` the owner's appointment, `token` the host's play-host sign-in, `session` a key from newKey(). */
-  open: async ({ server, game, cert, token, giveaway, winners, endsBy, session, fetchImpl = globalThis.fetch }) => post(server, `/v1/giveaways/${seg(game)}`, { cert, token, giveaway, winners, endsBy, session: session.address }, fetchImpl),
+  open: async ({ server, game, cert, token, giveaway, winners, endsBy, session, fetchImpl = globalThis.fetch }) =>
+    post(
+      server,
+      `/v1/giveaways/${seg(game)}`,
+      { cert, token, giveaway, winners, endsBy, session: session.address },
+      fetchImpl,
+    ),
   /** Reports its result, signed by its session key. `grant`: the host's grant (each winner is paid from it). */
-  report: async ({ server, game, giveaway, session, endedAt, winners, grant, cluster = 'devnet', fetchImpl = globalThis.fetch }) => {
-    const signed = winners.map((w) => ({ wallet: w.wallet, place: w.place, grant }));
-    const signature = encodeBase58(await session.sign(resultBytes({ cluster, game, round: giveaway, endedAt, winners: signed })));
-    return post(server, `/v1/giveaways/${seg(game)}/${seg(giveaway)}/result`, { endedAt, winners: winners.map(({ wallet, place }) => ({ wallet, place })), signature }, fetchImpl);
+  report: async ({
+    server,
+    game,
+    giveaway,
+    session,
+    endedAt,
+    winners,
+    grant,
+    cluster = 'devnet',
+    fetchImpl = globalThis.fetch,
+  }) => {
+    const signed = winners.map(w => ({ wallet: w.wallet, place: w.place, grant }));
+    const signature = encodeBase58(
+      await session.sign(resultBytes({ cluster, game, round: giveaway, endedAt, winners: signed })),
+    );
+    return post(
+      server,
+      `/v1/giveaways/${seg(game)}/${seg(giveaway)}/result`,
+      { endedAt, winners: winners.map(({ wallet, place }) => ({ wallet, place })), signature },
+      fetchImpl,
+    );
   },
 };
+
+// What a game's server checks: a wallet's collectibles, a wallet's signed proof, promo codes (server.js).
+export {
+  codeAddresses,
+  codeKey,
+  codeVoucher,
+  collectiblesOf,
+  holds,
+  makeCodes,
+  normalizeCode,
+  proofRequest,
+  proofText,
+  readProof,
+  verifyProof,
+} from './server.js';

package/js/results/server.js

@@ -0,0 +1,230 @@
+// What a game's server checks before it pays or grants anything: which of the game's collectibles a wallet holds,
+// that a wallet's owner signed a proof (a sign-in, a link to a player), and promo codes with keys nobody can guess.
+// Browser-safe (Web Crypto and fetch only), so a Cloudflare Worker, a Node server or a page can use it alike; the
+// page's own answers are never trusted for what a server pays.
+//
+//   const mine = await collectiblesOf({ rpc: RPC_URL, spec, wallet })       // [{ asset, item, name, attributes, … }]
+//   if (await holds({ rpc: RPC_URL, spec, wallet, item: 'pass' })) …        // a perk for holders
+//
+//   const ask = proofRequest({ game, wallet, purpose: 'link to player 42' }) // the server keeps ask.nonce until ask.expires
+//   … the page has the wallet sign ask.text (signMessage) and sends back the signature …
+//   const proof = await verifyProof({ text: ask.text, signature, wallet, game, purpose: 'link to player 42' })
+//
+//   const codes = makeCodes(50)                                 // print these on flyers; keep them out of the repository
+//   spec.grants[i].keys = await codeAddresses(codes)            // only public keys go in the spec
+//   const voucher = await codeVoucher({ code, game, grant: 3, incarnation, wallet, now })  // the player typed `code`
+import { decodeBase58, encodeBase58, isAddress } from '../chain/base58.js';
+import { toHex, utf8 } from '../chain/bytes.js';
+import { MPL_CORE_PROGRAM, ownedAssetFilters, parseCoreAsset } from '../chain/core.js';
+import { rpcClient } from '../chain/rpc.js';
+import { sha256 } from '../chain/sha256.js';
+import { signVoucher } from './index.js';
+
+const subtle = () => globalThis.crypto.subtle;
+const rpcOf = rpc => (typeof rpc === 'string' ? rpcClient(rpc) : rpc);
+
+// ---------------------------------------------------------------- what a wallet holds
+
+/**
+ * The game's collectibles `wallet` holds now, read from the chain (Metaplex Core assets of the live spec's collection
+ * and of the collections it names): [{ asset, item (its key in the spec, or null), itemId, name, uri, attributes,
+ * frozen }]. `rpc`: an RPC link or a `rpcClient`. Token Metadata and compressed NFTs are not read here.
+ */
+export async function collectiblesOf({ rpc, spec, wallet }) {
+  if (!isAddress(wallet)) throw new Error('Name the wallet (its public address).');
+  const collections = [spec?.live?.collection, ...(spec?.collections ?? [])].filter(Boolean);
+  if (!collections.length)
+    throw new Error('The spec names no collection: put it live first (its live section names the collection).');
+  const keyOf = new Map((spec.items ?? []).filter(it => Number.isInteger(it.id)).map(it => [it.id, it.key]));
+  const client = rpcOf(rpc);
+  const found = (
+    await Promise.all(collections.map(c => client.programAccounts(MPL_CORE_PROGRAM, ownedAssetFilters(wallet, c))))
+  ).flat();
+  return found.map(({ pubkey, account }) => {
+    const a = parseCoreAsset(account.data);
+    const itemId = a.attributes?.item_id !== undefined ? Number(a.attributes.item_id) : null;
+    return { asset: pubkey, ...a, itemId, item: itemId === null ? null : (keyOf.get(itemId) ?? null) };
+  });
+}
+
+/**
+ * Whether `wallet` holds at least `atLeast` of the game's collectible `item` (its key in the spec), or of any of the
+ * game's collectibles when `item` is left out. With `attribute`, only those whose number under it is at least
+ * `minimum` count (a level, a rarity). → the count it holds when that is enough, else 0.
+ */
+export async function holds({ rpc, spec, wallet, item = null, atLeast = 1, attribute = null, minimum = 0 }) {
+  const mine = (await collectiblesOf({ rpc, spec, wallet })).filter(
+    c =>
+      (item === null || c.item === item) && (attribute === null || Number(c.attributes?.[attribute] ?? 0) >= minimum),
+  );
+  return mine.length >= atLeast ? mine.length : 0;
+}
+
+// ---------------------------------------------------------------- a wallet's signed proof
+
+const PROOF_TITLE = 'loot wallet proof';
+const PROOF_FIELDS = ['cluster', 'game', 'wallet', 'purpose', 'nonce', 'expires'];
+const oneLine = (name, value) => {
+  if (/[\r\n]/.test(String(value))) throw new RangeError(`A proof's ${name} is one line.`);
+  return String(value);
+};
+
+/** The exact text a wallet signs to prove it is its owner's: fixed lines, so nothing else can be passed off as it. */
+export const proofText = ({ cluster = 'devnet', game, wallet, purpose, nonce, expires }) =>
+  [
+    PROOF_TITLE,
+    ...PROOF_FIELDS.map(f => `${f}: ${oneLine(f, { cluster, game, wallet, purpose, nonce, expires }[f])}`),
+    '',
+    'Signing this moves nothing.',
+  ].join('\n');
+
+/**
+ * A proof to ask of `wallet`, made by the server: { text, nonce, expires }. The server keeps `nonce` until `expires`
+ * (unix seconds, `seconds` from now) and takes each nonce once, so a signed proof can't be replayed.
+ */
+export function proofRequest({
+  cluster = 'devnet',
+  game,
+  wallet,
+  purpose = 'sign in',
+  seconds = 300,
+  now = Math.floor(Date.now() / 1000),
+}) {
+  if (!isAddress(wallet)) throw new Error('Name the wallet (its public address).');
+  const nonce = toHex(globalThis.crypto.getRandomValues(new Uint8Array(16)));
+  const expires = Math.floor(now) + Math.floor(seconds);
+  return { text: proofText({ cluster, game, wallet, purpose, nonce, expires }), nonce, expires };
+}
+
+/** A proof text's fields, or null when it is not one. */
+export function readProof(text) {
+  const lines = String(text).split('\n');
+  if (
+    lines[0] !== PROOF_TITLE ||
+    lines.length !== PROOF_FIELDS.length + 3 ||
+    lines.at(-1) !== 'Signing this moves nothing.'
+  )
+    return null;
+  const out = {};
+  for (const [i, f] of PROOF_FIELDS.entries()) {
+    const prefix = `${f}: `;
+    if (!lines[i + 1].startsWith(prefix)) return null;
+    out[f] = lines[i + 1].slice(prefix.length);
+  }
+  out.expires = Number(out.expires);
+  return out;
+}
+
+/**
+ * Checks a wallet's signed proof: the text is a proof for this `game` (and `purpose`, when given), for `wallet`, not
+ * expired at `now`, and `signature` (base58, or 64 bytes) is that wallet's Ed25519 signature of it. → the proof's
+ * fields ({ wallet, nonce, expires, … }), or throws in words. Taking each nonce once is the caller's: check
+ * `fields.nonce` against the ones the server handed out and not yet used.
+ */
+export async function verifyProof({
+  text,
+  signature,
+  wallet,
+  game,
+  purpose = null,
+  cluster = 'devnet',
+  now = Math.floor(Date.now() / 1000),
+}) {
+  const fields = readProof(text);
+  if (!fields) throw new Error('That is not a wallet proof.');
+  if (fields.cluster !== cluster) throw new Error(`The proof is for ${fields.cluster}, not ${cluster}.`);
+  if (game !== undefined && fields.game !== String(game)) throw new Error('The proof is for another game.');
+  if (wallet !== undefined && fields.wallet !== wallet) throw new Error('The proof names another wallet.');
+  if (purpose !== null && fields.purpose !== purpose) throw new Error('The proof is for something else.');
+  if (!(fields.expires > now)) throw new Error('The proof has expired: ask for a new one.');
+  const sig = typeof signature === 'string' ? decodeBase58(signature) : Uint8Array.from(signature ?? []);
+  if (sig.length !== 64) throw new Error('A signature is 64 bytes.');
+  const key = await subtle().importKey('raw', decodeBase58(fields.wallet), { name: 'Ed25519' }, false, ['verify']);
+  if (!(await subtle().verify({ name: 'Ed25519' }, key, sig, utf8(text))))
+    throw new Error("The signature is not that wallet's.");
+  return fields;
+}
+
+// ---------------------------------------------------------------- promo codes
+
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const CODE_DOMAIN = 'loot-promo-code-v1';
+
+/**
+ * `n` fresh promo codes, each `bits` of randomness (80 by default, 16 characters of Crockford base32, in groups of 4).
+ * A code's key is in the spec for anyone to read, so a short code can be found by trying them all offline: fewer than
+ * 64 bits is refused.
+ */
+export function makeCodes(n, { bits = 80, group = 4 } = {}) {
+  if (!(bits >= 64))
+    throw new RangeError(
+      'A promo code needs at least 64 bits (80 by default): its key is public, so a short code can be guessed offline.',
+    );
+  const chars = Math.ceil(bits / 5);
+  return Array.from({ length: n }, () => {
+    const bytes = globalThis.crypto.getRandomValues(new Uint8Array(chars));
+    const text = Array.from(bytes, b => CROCKFORD[b & 31]).join('');
+    return group ? text.match(new RegExp(`.{1,${group}}`, 'g')).join('-') : text;
+  });
+}
+
+/** A code as typed, read the forgiving way (Crockford): case, spaces and dashes don't matter, O reads 0, I and L read 1. */
+export const normalizeCode = code =>
+  String(code).toUpperCase().replace(/[\s-]/g, '').replace(/O/g, '0').replace(/[IL]/g, '1');
+
+/** The key a code stands for: { address, sign } (Ed25519, its seed sha256 of the domain and the code). */
+export async function codeKey(code, { domain = CODE_DOMAIN } = {}) {
+  const normalized = normalizeCode(code);
+  if (!normalized || [...normalized].some(c => !CROCKFORD.includes(c))) throw new Error('That is not a code.');
+  const seed = sha256(utf8(`${domain}\n${normalized}`));
+  const pkcs8 = new Uint8Array([
+    0x30,
+    0x2e,
+    0x02,
+    0x01,
+    0x00,
+    0x30,
+    0x05,
+    0x06,
+    0x03,
+    0x2b,
+    0x65,
+    0x70,
+    0x04,
+    0x22,
+    0x04,
+    0x20,
+    ...seed,
+  ]);
+  const privateKey = await subtle().importKey('pkcs8', pkcs8, { name: 'Ed25519' }, true, ['sign']);
+  const jwk = await subtle().exportKey('jwk', privateKey);
+  const raw = Uint8Array.from(atob(jwk.x.replace(/-/g, '+').replace(/_/g, '/')), ch => ch.charCodeAt(0));
+  return {
+    address: encodeBase58(raw),
+    sign: async message => new Uint8Array(await subtle().sign({ name: 'Ed25519' }, privateKey, message)),
+  };
+}
+
+/** The public keys for a grant's `keys`, one per code, in order. */
+export const codeAddresses = async (codes, options) =>
+  Promise.all(codes.map(async c => (await codeKey(c, options)).address));
+
+/**
+ * A voucher a typed code signs for `wallet` (the page, or a server, makes it): the grant pays it once per code with
+ * `limits.perKey: 1`. Its round is the code's own, so one wallet can't use one code twice either. `incarnation` is the
+ * grant's, read from the chain; `now` the cluster's clock.
+ */
+export async function codeVoucher({
+  code,
+  game,
+  grant,
+  incarnation,
+  wallet,
+  now,
+  seconds = 86_400,
+  domain = CODE_DOMAIN,
+}) {
+  const key = await codeKey(code, { domain });
+  const round = toHex(sha256(utf8(`${domain}\nround\n${key.address}`))).slice(0, 32);
+  return signVoucher({ signer: key, game, grant, incarnation, wallet, round, now, seconds });
+}