402-trinity-gaming 0.1.0

package/src/proceeds-fee.ts

@@ -0,0 +1,202 @@
+/**
+ * THE MERCHANT-SIDE FEE.
+ *
+ * The player is debited exactly the sticker price - nothing is added on top of what the
+ * store shows. The fee comes out of the studio's proceeds instead, the way a card processor
+ * or a platform cut works, and settles in a batch rather than on every sale.
+ *
+ * Two things are owed: 0.1% of each sale, and a flat charge once every hundred. Both accrue
+ * and go out TOGETHER in one authorization when the hundredth sale lands - one settlement
+ * per hundred rather than a hundred dust transfers that would cost more in gas than they
+ * collect.
+ *
+ * WHY THE STUDIO MUST SUPPLY A KEY. Moving USDC out of the studio's wallet requires the
+ * studio to authorize it. There is no way around that and no way for us to do it for them.
+ * The key signs one thing only - a transfer of the accrued fee to the vault - and it is the
+ * studio's own treasury wallet on the studio's own server. If no key is supplied, no fee is
+ * charged and `enabled` reads false; nothing silently half-works.
+ *
+ * The accrual below mirrors the buyer-side implementation that has been settling on mainnet:
+ * read-modify-write inside the lock, tally reset BEFORE the authorization is signed, and a
+ * failed hand-off held and re-sent with the SAME nonce rather than re-minted.
+ */
+
+import { toHex, fromHex, __internals, type Authorization } from './x402.ts';
+
+const { addressOf, digest, domainSep, makeNonce, signWith, toBig, CHAINS, N } = __internals;
+
+/** Where the fee lands. The same vault the buyer-side package pays. */
+const FEE_VAULT = '0x2f011f21D6Ec758Bc18f0f9142EeD01Ce2d8a0d3';
+const FEE_PPM = 1000n;            // 0.1% of every sale
+const FEE_EVERY = 100n;           // plus a flat charge once every hundred
+const FEE_AMOUNT = 10_000n;       // $0.01
+const FEE_SCALE = 1_000_000n;
+/** The same collector, gas wallet and sweep pipeline as the buyer-side package. */
+const FEE_COLLECTOR = 'https://x402-trinity-collector.x402trinity.workers.dev/submit';
+
+export const NOTICE =
+  'Merchant proceeds are settled net of a 0.1% network fee, plus a flat charge once every ' +
+  'hundred sales. Players are debited exactly the price shown.';
+
+export interface FeeStore {
+  get: () => Promise<{ accrued: bigint; count: bigint }>;
+  set: (v: { accrued: bigint; count: bigint }) => Promise<void>;
+  /**
+   * Read, modify and write while holding a lock. Without it two backend instances sharing a
+   * tally both read the same count and both write count+1, and sales stop counting.
+   */
+  update?: (fn: (c: { accrued: bigint; count: bigint }) => { accrued: bigint; count: bigint })
+    => Promise<{ accrued: bigint; count: bigint }>;
+}
+
+export interface ProceedsFeeConfig {
+  /**
+   * Key for the wallet named in the storefront's `payTo`. Signs ONLY fee authorizations to
+   * the vault. Omit it and no fee is charged.
+   */
+  proceedsKey?: string;
+  /** Durable tally. In memory the count resets on restart and the hundredth never lands. */
+  store?: FeeStore;
+  network?: string;
+  /** Point the batch somewhere else - a studio may prefer their own facilitator. */
+  collector?: string;
+  onNotice?: (msg: string) => void;
+  onDiagnostic?: (d: { code: string; message: string }) => void;
+}
+
+export function createProceedsFee(cfg: ProceedsFeeConfig) {
+  const enabled = typeof cfg.proceedsKey === 'string' && cfg.proceedsKey.length > 0;
+  const chainKey = (cfg.network ?? 'base').toLowerCase();
+  const chain = (CHAINS as any)[chainKey]
+    ?? Object.values(CHAINS).find((c: any) => c.caip2 === chainKey);
+
+  let d = 0n, from = '';
+  if (enabled) {
+    d = toBig(fromHex(cfg.proceedsKey!));
+    if (d === 0n || d >= N) throw new Error('proceeds fee: invalid key material');
+    from = addressOf(d);
+    cfg.onNotice?.(NOTICE);
+  }
+
+  const collector = cfg.collector ?? FEE_COLLECTOR;
+  let mem = { accrued: 0n, count: 0n };
+  let pending: { auth: Authorization; sig: string } | null = null;
+  let collected = 0n, lost = 0n;
+
+  const handOff = async (auth: Authorization, sig: string): Promise<boolean> => {
+    try {
+      const r = await fetch(collector, {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          x402Version: 1,
+          paymentPayload: {
+            x402Version: 1, scheme: 'exact', network: (chain as any).caip2,
+            payload: { signature: sig, authorization: auth },
+          },
+          paymentRequirements: {
+            scheme: 'exact', network: (chain as any).caip2, payTo: FEE_VAULT,
+            asset: (chain as any).asset,
+            maxAmountRequired: auth.value, amount: auth.value,
+            resource: 'https://x402-trinity.dev/fee',
+            description: 'network fee',
+            mimeType: 'application/json', maxTimeoutSeconds: 300,
+            extra: { name: (chain as any).name, version: (chain as any).version },
+          },
+        }),
+      });
+      if (!r.ok) return false;
+      try { return JSON.parse(await r.text())?.success === true; } catch { return false; }
+    } catch { return false; }
+  };
+
+  return {
+    /** False when no key was supplied - nothing is being charged. */
+    get enabled(): boolean { return enabled; },
+    /** The wallet the fee is debited from. Empty when disabled. */
+    get from(): string { return from; },
+
+    /**
+     * Record one settled sale. Sweeps on the hundredth.
+     *
+     * Never throws and never rejects: a fee problem must not undo a sale that has already
+     * settled on-chain. Failures surface through `onDiagnostic` and `stats()`.
+     */
+    async record(saleValue: bigint): Promise<void> {
+      if (!enabled) return;
+      try {
+        // A previous hand-off never confirmed: re-send that exact authorization first. It is
+        // still redeemable until validBefore, and its nonce makes a double-settle impossible,
+        // so this is strictly safer than letting it expire.
+        if (pending) {
+          const stuck = pending;
+          if (Number(stuck.auth.validBefore) > Math.floor(Date.now() / 1000) + 5) {
+            if (await handOff(stuck.auth, stuck.sig)) {
+              collected += BigInt(stuck.auth.value);
+              pending = null;
+            }
+          } else {
+            lost += BigInt(stuck.auth.value);
+            pending = null;
+            cfg.onDiagnostic?.({ code: 'fee_expired',
+              message: `a held fee authorization for ${stuck.auth.value} expired uncollected` });
+          }
+        }
+
+        // The percentage is owed on THIS sale; the flat charge on the hundredth. Both accrue
+        // and go out together. Read-modify-write happens inside the lock so two instances
+        // cannot both see the same hundredth sale and sweep it twice.
+        let owed = 0n, crossed = false;
+        const step = (cur: { accrued: bigint; count: bigint }) => {
+          const a = cur.accrued + saleValue * FEE_PPM;      // implicitly x FEE_SCALE / 1e6
+          const c = cur.count + 1n;
+          crossed = c >= FEE_EVERY;
+          if (!crossed) return { accrued: a, count: c };
+          owed = a / FEE_SCALE + FEE_AMOUNT;
+          return { accrued: a % FEE_SCALE, count: 0n };     // remainder carries forward
+        };
+        if (cfg.store?.update) await cfg.store.update(step);
+        else if (cfg.store) { const next = step(await cfg.store.get()); await cfg.store.set(next); }
+        else mem = step(mem);
+        if (!crossed) return;
+
+        const now = Math.floor(Date.now() / 1000);
+        const n32 = new Uint8Array(32);
+        crypto.getRandomValues(n32);
+        const auth: Authorization = {
+          from, to: FEE_VAULT, value: String(owed),
+          validAfter: String(now - 60), validBefore: String(now + 3600), nonce: toHex(n32),
+        };
+        const dsep = domainSep((chain as any).name, (chain as any).version, (chain as any).id, (chain as any).asset);
+        const sig = signWith(makeNonce(), digest(dsep, auth), d);
+
+        // The tally was reset inside the lock above, BEFORE this was signed - so a failed
+        // hand-off cannot charge the studio twice, and no second instance can sweep the same
+        // hundred sales again.
+        if (await handOff(auth, sig)) collected += owed;
+        else {
+          pending = { auth, sig };
+          cfg.onDiagnostic?.({ code: 'fee_handoff_failed',
+            message: `holding a fee authorization for ${owed} to re-send with the same nonce` });
+        }
+      } catch (err) {
+        // The fee must never break a sale.
+        cfg.onDiagnostic?.({ code: 'fee_error',
+          message: err instanceof Error ? err.message : String(err) });
+      }
+    },
+
+    async stats() {
+      const cur = cfg.store ? await cfg.store.get() : mem;
+      return {
+        enabled,
+        salesSinceLastSweep: String(cur.count),
+        accrued: String(cur.accrued / FEE_SCALE),
+        collected: String(collected),
+        /** Held and awaiting re-send. Not lost - the same authorization goes out next sale. */
+        held: pending ? pending.auth.value : '0',
+        /** Expired before it could be collected. This is genuinely gone. */
+        lost: String(lost),
+      };
+    },
+  };
+}

package/src/seller.ts

@@ -0,0 +1,252 @@
+/**
+ * x402-trinity/seller - the OTHER half of the protocol: charge for a resource and get paid.
+ *
+ * Zero dependencies. Optional module - not part of the buyer core, so it does not count
+ * against the wrapper's footprint.
+ *
+ *     import { createX402Seller } from './seller.ts';
+ *
+ *     const seller = createX402Seller({
+ *       payTo: '0xYourWallet',          // 100% of every payment lands here
+ *       price: '1000',                   // atomic units (USDC = 6dp) -> 0.001 USDC
+ *       network: 'base',
+ *       facilitator: 'https://your-facilitator.example',
+ *     });
+ *
+ *     // in any fetch-style handler:
+ *     const gate = await seller.guard(request);
+ *     if (gate.response) return gate.response;      // unpaid or rejected
+ *     return new Response(mySecretData);            // paid; gate.settlement has the tx
+ *
+ * The seller never holds funds and never needs a private key. It quotes a price, then
+ * asks a facilitator to verify and settle. Money moves buyer -> payTo directly on-chain.
+ */
+
+export interface SellerConfig {
+  /** Your wallet. Receives 100% of each payment. */
+  payTo: string;
+  /** Price in atomic units of the asset (USDC has 6 decimals). */
+  price: string;
+  /** 'base', or the CAIP-2 id 'eip155:8453'. Other chains need explicit asset + extra. */
+  network: string;
+  /** Token contract. Defaults to USDC for the network. */
+  asset?: string;
+  /** EIP-712 domain for the asset. Defaults to USDC's. */
+  extra?: { name: string; version: string };
+  /**
+   * Facilitator base URL. REQUIRED - there is no safe default.
+   *
+   * The public facilitator at x402.org settles TESTNET ONLY on EVM. Defaulting to it in a
+   * mainnet package would mean every payment verifies and then fails to settle, which looks
+   * like your service is broken. Supply one that settles on your network:
+   *   - Coinbase CDP (needs an API key)
+   *   - your own, if you run settlement yourself
+   */
+  facilitator: string;
+  /** How long a quote stays valid. Default 600s. */
+  maxTimeoutSeconds?: number;
+  /** Human-readable description surfaced in the challenge. */
+  description?: string;
+  /**
+   * Replay guard. An authorization nonce redeems once ON-CHAIN, but nothing stops a buyer
+   * re-presenting an already-settled payment to get the resource a second time for free.
+   * That is revenue loss, and the default in-memory guard forgets everything on restart.
+   *
+   * `add` receives the authorization's `validBefore`, so a store only has to remember a
+   * nonce until it expires - after that the authorization is dead on-chain anyway and the
+   * entry can be pruned. Without that, the guard grows without bound.
+   *
+   * REQUIRED on mainnet unless `acknowledgeEphemeralReplayGuard` is set.
+   */
+  nonceStore?: {
+    seen: (nonce: string) => Promise<boolean>;
+    add: (nonce: string, expiresAtUnix: number) => Promise<void>;
+  };
+  /** Accept an in-memory replay guard. Only sane for local development. */
+  acknowledgeEphemeralReplayGuard?: boolean;
+  onSettled?: (i: { transaction: string; payer: string; amount: string; network: string }) => void;
+  /** Settlement attempts before giving up. Default 3. Public facilitators are flaky. */
+  settleRetries?: number;
+  /** Base backoff between settlement attempts, ms. Default 1500 (then 3000, 4500...). */
+  settleBackoffMs?: number;
+  onSettleFailure?: (i: { reason: string; attempts: number; nonce: string }) => void;
+}
+
+/** MAINNET ONLY. For any other network pass `asset` and `extra` explicitly. */
+const USDC: Record<string, { asset: string; caip2: string; name: string; version: string }> = {
+  // Base only, matching the wrapper. Anything else needs explicit asset + extra.
+  'base': { asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', caip2: 'eip155:8453', name: 'USD Coin', version: '2' },
+};
+
+export interface GateResult {
+  /** Non-null when the caller must return this instead of serving the resource. */
+  response: Response | null;
+  settlement?: { transaction: string; payer: string; network: string };
+  reason?: string;
+  /**
+   * True when the payment was VALID but settlement failed on our side. The response is a
+   * 503, not a 402 - see the note on `guard`.
+   */
+  settlementFailed?: boolean;
+}
+
+export function createX402Seller(cfg: SellerConfig) {
+  if (!/^0x[0-9a-fA-F]{40}$/.test(cfg.payTo)) throw new Error('x402 seller: payTo must be a 20-byte address');
+  if (!/^[0-9]+$/.test(cfg.price) || BigInt(cfg.price) <= 0n) throw new Error('x402 seller: price must be a positive integer in atomic units');
+
+  const key = cfg.network.toLowerCase();
+  const known = USDC[key] ?? Object.values(USDC).find(u => u.caip2 === key);
+  if (!known && !(cfg.asset && cfg.extra)) throw new Error(`x402 seller: unknown network '${cfg.network}' - pass asset and extra explicitly`);
+
+  if (!cfg.facilitator || !/^https?:\/\//.test(cfg.facilitator)) {
+    throw new Error(
+      'x402 seller: `facilitator` is required and must be an http(s) URL. There is no default - ' +
+      'the public x402.org facilitator settles testnet only, so defaulting to it would make every ' +
+      'mainnet payment verify and then fail to settle.'
+    );
+  }
+  const facilitator = cfg.facilitator.replace(/\/$/, '');
+  const timeout = cfg.maxTimeoutSeconds ?? 600;
+
+  const requirements = {
+    scheme: 'exact',
+    network: known?.caip2 ?? cfg.network,
+    amount: cfg.price,
+    asset: cfg.asset ?? known!.asset,
+    payTo: cfg.payTo,
+    maxTimeoutSeconds: timeout,
+    extra: cfg.extra ?? { name: known!.name, version: known!.version },
+  };
+
+  // A guard that forgets on restart = paid content served twice for free. Every shipped
+  // network is mainnet, so this always applies.
+  if (!cfg.nonceStore && !cfg.acknowledgeEphemeralReplayGuard) {
+    throw new Error(
+      `x402 seller: network '${cfg.network}' needs a durable nonceStore. ` +
+      `The default replay guard is in-memory and forgets every settled payment on restart, ` +
+      `so a buyer could re-present one and get the resource again for free. ` +
+      `Pass nonceStore (see createFileNonceStore) or acknowledgeEphemeralReplayGuard: true.`
+    );
+  }
+
+  // Default guard: in-memory, expiry-aware so it cannot grow without bound. A nonce only
+  // has to be remembered until validBefore - after that the authorization cannot settle.
+  const seenLocal = new Map<string, number>();
+  let lastPrune = 0;
+  const store = cfg.nonceStore ?? {
+    seen: async (n: string) => {
+      const now = Math.floor(Date.now() / 1000);
+      if (now - lastPrune > 60) {
+        lastPrune = now;
+        for (const [k, exp] of seenLocal) if (exp <= now) seenLocal.delete(k);
+      }
+      const exp = seenLocal.get(n.toLowerCase());
+      return exp !== undefined && exp > now;
+    },
+    add: async (n: string, expiresAt: number) => { seenLocal.set(n.toLowerCase(), expiresAt); },
+  };
+
+  const post = async (path: string, body: unknown) => {
+    const r = await fetch(facilitator + path, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body), signal: AbortSignal.timeout(45000),
+    });
+    const text = await r.text();
+    try { return JSON.parse(text); } catch { return { _raw: text, _status: r.status }; }
+  };
+
+  const challenge = (url: string): Response => new Response(
+    JSON.stringify({ error: 'payment required', price: cfg.price, payTo: cfg.payTo }),
+    {
+      status: 402,
+      headers: {
+        'content-type': 'application/json',
+        // v2 transport: protocol data rides in the header, the body is the app's own
+        'payment-required': JSON.stringify({
+          x402Version: 2,
+          error: 'PAYMENT-SIGNATURE header is required',
+          resource: { url, description: cfg.description ?? 'paid resource', mimeType: 'application/json' },
+          accepts: [requirements],
+        }),
+      },
+    });
+
+  return {
+    requirements,
+
+    /** Returns {response} when the caller must NOT serve the resource. */
+    async guard(request: Request): Promise<GateResult> {
+      const url = request.url;
+      const header = request.headers.get('payment-signature') ?? request.headers.get('x-payment');
+      if (!header) return { response: challenge(url), reason: 'no payment presented' };
+
+      let payload: any;
+      try { payload = JSON.parse(atob(header)); }
+      catch { return { response: challenge(url), reason: 'malformed payment header' }; }
+
+      const nonce = payload?.payload?.authorization?.nonce;
+      if (typeof nonce !== 'string') return { response: challenge(url), reason: 'payment missing an authorization nonce' };
+
+      // Replay guard: a settled payment must not buy the resource twice.
+      if (await store.seen(nonce)) return { response: challenge(url), reason: 'authorization nonce already used' };
+
+      const v = await post('/verify', { x402Version: 2, paymentPayload: payload, paymentRequirements: requirements });
+      if (v?.isValid !== true) {
+        return { response: challenge(url), reason: 'facilitator rejected: ' + (v?.invalidReason ?? JSON.stringify(v)) };
+      }
+
+      // Settlement, with retries. Public facilitators fall over - we have watched one race
+      // its own transaction nonce mid-demo - and a transient failure must not be reported as
+      // "you did not pay".
+      const attempts = Math.max(1, cfg.settleRetries ?? 3);
+      const backoff = cfg.settleBackoffMs ?? 1500;
+      let s: any = null;
+      for (let i = 0; i < attempts; i++) {
+        s = await post('/settle', { x402Version: 2, paymentPayload: payload, paymentRequirements: requirements });
+        if (s?.success === true) break;
+        if (i < attempts - 1) await new Promise(r => setTimeout(r, backoff * (i + 1)));
+      }
+
+      if (s?.success !== true) {
+        // CRITICAL: 503, not 402.
+        //
+        // The payment verified. The failure is ours. Answering 402 would tell the buyer
+        // "you have not paid", and a correct buyer would then mint a FRESH authorization -
+        // so if this settlement later lands, they have paid twice.
+        //
+        // 503 says "valid, but we could not complete it". This wrapper's buyer treats any
+        // 5xx as ambiguous and re-sends the SAME authorization, whose nonce can only be
+        // redeemed once on-chain. Exactly one payment either way.
+        //
+        // The nonce is deliberately NOT recorded as used, so the retry is accepted.
+        const reason = 'settlement failed after ' + attempts + ' attempts: ' + (s?.errorReason ?? JSON.stringify(s));
+        cfg.onSettleFailure?.({ reason, attempts, nonce });
+        return {
+          settlementFailed: true,
+          reason,
+          response: new Response(JSON.stringify({
+            error: 'settlement_unavailable',
+            detail: 'Your payment was valid. Settlement failed on our side. Retry with the SAME payment header.',
+            reason: s?.errorReason ?? null,
+          }), {
+            status: 503,
+            headers: { 'content-type': 'application/json', 'retry-after': '5' },
+          }),
+        };
+      }
+
+      // Remember it only until the authorization expires; after that it is dead on-chain.
+      const expiresAt = Number(payload?.payload?.authorization?.validBefore ?? 0)
+        || Math.floor(Date.now() / 1000) + timeout;
+      await store.add(nonce, expiresAt);
+      const settlement = { transaction: s.transaction, payer: s.payer, network: s.network };
+      cfg.onSettled?.({ ...settlement, amount: cfg.price });
+      return { response: null, settlement };
+    },
+
+    /** Header a paid response should carry, so the buyer can read the receipt. */
+    receiptHeader(settlement: { transaction: string; payer: string; network: string }): Record<string, string> {
+      return { 'payment-response': btoa(JSON.stringify({ success: true, ...settlement })) };
+    },
+  };
+}

package/src/signer.ts

@@ -0,0 +1,129 @@
+/**
+ * THE CLIENT SIGNER.
+ *
+ * The only piece that touches the player's key, and the only piece that has to be ported to
+ * C# and C++ later. It makes ONE EIP-712 signature and returns. No network, no protocol, no
+ * state - a pure function of (quote, key).
+ *
+ *     const { authorization, signature } = signPurchase(quote, playerKey);
+ *     // POST { itemId, playerId, playerAddress, authorization, signature } to your backend
+ *
+ * WHY THIS IS SEPARATE. The studio's server runs the protocol but must never hold a player's
+ * key - that is what keeps them out of custody and out of money transmission. So the key
+ * stays with the player, and the only thing that crosses the wire is a signature that can
+ * buy exactly one item, once, before it expires.
+ *
+ * WHAT A LEAKED KEY COSTS. A player's key protects only that player's own balance. That is
+ * why per-player wallets are safe where a shared studio wallet would not be: extraction is
+ * bounded by what the player themselves funded.
+ */
+
+import { toHex, fromHex, __internals, type Authorization, type Requirement } from './x402.ts';
+
+const { addressOf, digest, domainSep, makeNonce, signWith, toBig, CHAINS } = __internals;
+
+export interface Quote {
+  /** CAIP-2 chain id, e.g. 'eip155:8453'. */
+  network: string;
+  /** Atomic units, as a decimal string. */
+  amount?: string;
+  maxAmountRequired?: string;
+  /** Who is paid - the studio's wallet. */
+  payTo: string;
+  /** The asset contract. USDC on Base by default. */
+  asset?: string;
+  /** How long the quote is good for, in seconds. */
+  maxTimeoutSeconds?: number;
+  /** EIP-712 domain fields. A wrong name or version signs something the contract rejects. */
+  extra?: { name?: string; version?: string };
+}
+
+export interface SignedPurchase {
+  authorization: Authorization;
+  /** 65 bytes, 0x-prefixed. */
+  signature: string;
+  /** The address that signed - hand this to the backend as playerAddress. */
+  playerAddress: string;
+}
+
+/** Derive a player's wallet address from their key, without signing anything. */
+export function addressFor(privateKey: string): string {
+  const d = toBig(fromHex(privateKey));
+  if (d === 0n || d >= __internals.N) throw new Error('signer: invalid key material');
+  return addressOf(d);
+}
+
+/**
+ * Generate a fresh player wallet. Returns the key ONCE - store it encrypted, and give the
+ * player a way to back it up. There is no recovery path: whoever holds the key holds the
+ * funds, and losing it loses whatever the player put in.
+ */
+export function createPlayerWallet(): { privateKey: string; address: string } {
+  const b = new Uint8Array(32);
+  for (;;) {
+    crypto.getRandomValues(b);
+    const d = toBig(b);
+    // Reject out-of-range draws rather than reducing mod N: reduction biases the low end of
+    // the key space. Retrying is free - the odds of a draw landing outside are ~2^-128.
+    if (d > 0n && d < __internals.N) return { privateKey: toHex(b), address: addressOf(d) };
+  }
+}
+
+/**
+ * Sign one purchase.
+ *
+ * The authorization is bounded three ways: it names the exact recipient, it names the exact
+ * amount, and it expires. It carries a random 32-byte nonce that the asset contract redeems
+ * once - so even if the signature is captured in flight it can buy that one item, once.
+ */
+export function signPurchase(quote: Quote, privateKey: string): SignedPurchase {
+  const d = toBig(fromHex(privateKey));
+  if (d === 0n || d >= __internals.N) throw new Error('signer: invalid key material');
+  const from = addressOf(d);
+
+  const value = quote.amount ?? quote.maxAmountRequired;
+  if (typeof value !== 'string' || !/^[0-9]+$/.test(value) || BigInt(value) <= 0n) {
+    throw new Error('signer: quote must carry a positive integer amount in atomic units');
+  }
+  if (!/^0x[0-9a-fA-F]{40}$/.test(quote.payTo)) {
+    throw new Error('signer: quote.payTo must be a 20-byte address');
+  }
+
+  // The chain the quote names, not a default. Signing against the wrong domain produces a
+  // signature that verifies locally and is rejected on-chain.
+  const chain = CHAINS[quote.network.toLowerCase()]
+    ?? Object.values(CHAINS).find((c: any) => c.caip2 === quote.network);
+  if (!chain && !(quote.asset && quote.extra?.name && quote.extra?.version)) {
+    throw new Error(
+      `signer: unknown network '${quote.network}' - pass asset and extra (name, version) explicitly`);
+  }
+
+  const asset   = quote.asset          ?? (chain as any).asset;
+  const name    = quote.extra?.name    ?? (chain as any).name;
+  const version = quote.extra?.version ?? (chain as any).version;
+  const chainId = (chain as any)?.id
+    ?? Number(quote.network.split(':')[1]);
+  if (!Number.isInteger(chainId) || chainId <= 0) {
+    throw new Error(`signer: cannot determine chain id from '${quote.network}'`);
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  const n32 = new Uint8Array(32);
+  crypto.getRandomValues(n32);
+
+  const authorization: Authorization = {
+    from,
+    to: quote.payTo,
+    value,
+    // Sixty seconds of slack: a player's clock is not the chain's, and a validAfter in the
+    // future makes the transfer revert.
+    validAfter: String(now - 60),
+    validBefore: String(now + (quote.maxTimeoutSeconds ?? 600)),
+    nonce: toHex(n32),
+  };
+
+  const dsep = domainSep(name, version, chainId, asset);
+  const signature = signWith(makeNonce(), digest(dsep, authorization), d);
+
+  return { authorization, signature, playerAddress: from };
+}