@playmos/sdk 0.3.7 → 0.3.9

package/dist/index.js

@@ -1,5 +1,5 @@
-import { AuthError, InvalidAmountError, ConfigError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, ApiError, WalletConnectionError, InsufficientGasError } from './chunk-VYR6BBHF.js';
-export { ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError } from './chunk-VYR6BBHF.js';
+import { AuthError, InvalidAmountError, ConfigError, MissingFieldError, NothingToWithdrawError, WalletTimeoutError, PaymentFailedError, ApiError, WalletConnectionError, InsufficientGasError, AlreadyEnteredError } from './chunk-UZECDT6F.js';
+export { AlreadyEnteredError, ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError, WalletTimeoutError } from './chunk-UZECDT6F.js';
 import { encodeFunctionData, decodeFunctionResult, numberToHex, keccak256, toBytes } from 'viem';
 
 // src/config.ts
@@ -181,6 +181,112 @@ function validateMetadata(metadata) {
   return out;
 }
 
+// src/payout.ts
+var PayoutError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.code = "payout_invalid";
+    this.name = "PayoutError";
+  }
+};
+var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+var BPS = 10000n;
+function requireAddress(w, i) {
+  if (!ADDRESS_RE.test(w)) {
+    throw new PayoutError(`ranking[${i}] must be a 0x-prefixed 20-byte address, got: ${JSON.stringify(w)}`);
+  }
+  return w.toLowerCase();
+}
+function parseUsdToMicroLoose(amount) {
+  if (typeof amount !== "string" || !/^\d+(\.\d{1,6})?$/.test(amount.trim())) {
+    throw new PayoutError(`invalid USD amount: ${JSON.stringify(amount)}`);
+  }
+  const [wholeRaw, frac = ""] = amount.trim().split(".");
+  const whole = wholeRaw ?? "0";
+  const fracPadded = (frac + "000000").slice(0, 6);
+  const micro = BigInt(whole) * 1000000n + BigInt(fracPadded);
+  if (micro <= 0n) throw new PayoutError(`amount must be > 0, got: ${JSON.stringify(amount)}`);
+  return micro;
+}
+function computePayout(pool, ranking, rule) {
+  if (typeof pool !== "bigint" || pool <= 0n) {
+    throw new PayoutError(`pool must be a positive bigint (micro-USDC), got: ${String(pool)}`);
+  }
+  if (!Array.isArray(ranking) || ranking.length === 0) {
+    throw new PayoutError("ranking must be a non-empty array of wallets (best-first)");
+  }
+  const wallets = ranking.map((w, i) => requireAddress(w, i));
+  const seen = /* @__PURE__ */ new Set();
+  for (const w of wallets) {
+    if (seen.has(w)) throw new PayoutError(`duplicate wallet in ranking: ${w}`);
+    seen.add(w);
+  }
+  if (rule.kind === "winner-take-all") {
+    return [{ wallet: wallets[0], amount: pool }];
+  }
+  if (rule.kind === "top-n") {
+    const splits = rule.splitsBps;
+    if (!Array.isArray(splits) || splits.length === 0) {
+      throw new PayoutError("top-n splitsBps must be a non-empty array");
+    }
+    if (splits.length > wallets.length) {
+      throw new PayoutError(
+        `top-n needs ${splits.length} ranked wallets but ranking only has ${wallets.length}`
+      );
+    }
+    let sumBps = 0;
+    for (const b of splits) {
+      if (!Number.isInteger(b) || b <= 0 || b > 1e4) {
+        throw new PayoutError(`each splitsBps entry must be an integer in (0, 10000], got: ${b}`);
+      }
+      sumBps += b;
+    }
+    if (sumBps !== 1e4) {
+      throw new PayoutError(`splitsBps must sum to 10000, got ${sumBps}`);
+    }
+    const out = [];
+    let allocated = 0n;
+    for (let i = 0; i < splits.length; i++) {
+      const amt = pool * BigInt(splits[i]) / BPS;
+      out.push({ wallet: wallets[i], amount: amt });
+      allocated += amt;
+    }
+    const remainder = pool - allocated;
+    if (remainder < 0n) throw new PayoutError("internal: allocated more than pool");
+    out[0] = { wallet: out[0].wallet, amount: out[0].amount + remainder };
+    const filtered = out.filter((x) => x.amount > 0n);
+    if (filtered.length === 0) throw new PayoutError("payout produced no positive amounts");
+    const total = filtered.reduce((s, x) => s + x.amount, 0n);
+    if (total !== pool) throw new PayoutError(`internal: sum ${total} != pool ${pool}`);
+    return filtered;
+  }
+  if (rule.kind === "custom") {
+    const amounts = rule.amounts;
+    if (!Array.isArray(amounts) || amounts.length === 0) {
+      throw new PayoutError("custom amounts must be a non-empty array of USD strings");
+    }
+    if (amounts.length > wallets.length) {
+      throw new PayoutError(
+        `custom amounts has ${amounts.length} entries but ranking only has ${wallets.length}`
+      );
+    }
+    const out = [];
+    let total = 0n;
+    for (let i = 0; i < amounts.length; i++) {
+      const amt = parseUsdToMicroLoose(amounts[i]);
+      out.push({ wallet: wallets[i], amount: amt });
+      total += amt;
+    }
+    if (total !== pool) {
+      throw new PayoutError(
+        `custom amounts sum to ${total} micro-USDC but pool is ${pool} \u2014 must match exactly`
+      );
+    }
+    return out;
+  }
+  throw new PayoutError(`unknown payout rule kind: ${JSON.stringify(rule.kind)}`);
+}
+
 // src/http.ts
 function resolveRetry(retry) {
   const off = { maxRetries: 0, baseDelayMs: 500, maxDelayMs: 2e4 };
@@ -329,7 +435,7 @@ function createHttpClient(baseUrl, apiKey, retry) {
         const why = res.__playmosSignerBelowReason ?? "low_balance";
         msg = `Sandbox signer below funding floor (${why}) (${res.status} from ${res.url}) \u2014 top up Sepolia USDC (see GET /health capabilities.payments.signerBalance). Do not retry; retry cannot succeed until funded. Cross-ref: issue #205 recurrence \xB7 hub funding #15.`;
       } else if (gateway) {
-        msg = `Sandbox gateway timeout (${res.status}) from ${res.url} \u2014 the request likely exceeded the platform limit while settling on-chain. Retry with the same idempotency key (safe); prefer a dedicated Base Sepolia RPC on the service (BB-GATEB-002).`;
+        msg = `Sandbox gateway timeout (${res.status}) from ${res.url} \u2014 the request likely exceeded the platform edge limit while on-chain work ran. Retry with the same idempotency key after checking chain/service status (safe if settle already landed). Do not assume missing RPC \u2014 sandbox usually has one; prefer shorter async settle paths (BB-GATEB-002 / #422).`;
       } else {
         msg = `Non-JSON response (${res.status}) from ${res.url}`;
       }
@@ -371,7 +477,60 @@ function createHttpClient(baseUrl, apiKey, retry) {
 }
 
 // src/wallet.ts
-function resolveProvider(wallet) {
+var DEFAULT_WALLET_REQUEST_TIMEOUT_MS = 2e4;
+var MONEY_MOVING_METHODS = /* @__PURE__ */ new Set([
+  "wallet_sendCalls",
+  "eth_sendTransaction",
+  "eth_sendRawTransaction"
+]);
+var CONNECT_METHODS = /* @__PURE__ */ new Set(["eth_requestAccounts"]);
+var TIMED_FLAG = "__playmosTimedRequest";
+function resolvePolicy(opts) {
+  const requestTimeoutMs = typeof opts?.requestTimeoutMs === "number" && opts.requestTimeoutMs > 0 ? opts.requestTimeoutMs : DEFAULT_WALLET_REQUEST_TIMEOUT_MS;
+  const connectTimeoutMs = typeof opts?.connectTimeoutMs === "number" && opts.connectTimeoutMs > 0 ? opts.connectTimeoutMs : requestTimeoutMs;
+  const sendCallsTimeoutMs = typeof opts?.sendCallsTimeoutMs === "number" && opts.sendCallsTimeoutMs >= 0 ? opts.sendCallsTimeoutMs : 0;
+  return { requestTimeoutMs, connectTimeoutMs, sendCallsTimeoutMs };
+}
+function timeoutMsForMethod(method, opts) {
+  const p = resolvePolicy(opts);
+  if (MONEY_MOVING_METHODS.has(method)) return p.sendCallsTimeoutMs;
+  if (CONNECT_METHODS.has(method)) return p.connectTimeoutMs;
+  return p.requestTimeoutMs;
+}
+async function timedRequest(provider, args, timeoutMs = DEFAULT_WALLET_REQUEST_TIMEOUT_MS) {
+  if (timeoutMs <= 0) {
+    return provider.request(args);
+  }
+  let timer;
+  try {
+    return await Promise.race([
+      provider.request(args),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          reject(
+            new WalletTimeoutError(
+              `Wallet request "${args.method}" timed out after ${timeoutMs}ms.`,
+              { method: args.method, timeoutMs }
+            )
+          );
+        }, timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+}
+function withTimeoutProvider(provider, opts) {
+  const flagged = provider;
+  if (flagged[TIMED_FLAG]) return provider;
+  const policy = typeof opts === "number" ? { requestTimeoutMs: opts, connectTimeoutMs: opts } : opts ?? {};
+  const wrapped = {
+    request: (args) => timedRequest(provider, args, timeoutMsForMethod(args.method, policy))
+  };
+  Object.defineProperty(wrapped, TIMED_FLAG, { value: true, enumerable: false });
+  return wrapped;
+}
+function resolveRawProvider(wallet) {
   if (wallet?.provider) return wallet.provider;
   const injected = globalThis.ethereum;
   const connector = wallet?.connector ?? "base-account";
@@ -388,18 +547,23 @@ function resolveProvider(wallet) {
     "base-account connector needs a provider. In the Base App it is injected automatically; elsewhere, create one with @base-org/account and pass it as wallet.provider."
   );
 }
-async function walletAvailable(wallet) {
+function resolveProvider(wallet, opts) {
+  const raw = resolveRawProvider(wallet);
+  return withTimeoutProvider(raw, opts);
+}
+async function walletAvailable(wallet, opts) {
   if (wallet?.provider) return true;
   let provider;
   try {
-    provider = resolveProvider(wallet);
+    provider = resolveProvider(wallet, opts);
   } catch {
     return false;
   }
   try {
     await getAccount(provider);
     return true;
-  } catch {
+  } catch (e) {
+    if (e instanceof WalletTimeoutError) throw e;
     return false;
   }
 }
@@ -410,6 +574,7 @@ async function getAccount(provider) {
     if (!addr) throw new Error("no account");
     return addr;
   } catch (e) {
+    if (e instanceof WalletTimeoutError) throw e;
     throw new WalletConnectionError("Could not read the player's wallet account.", {
       cause: e?.message
     });
@@ -483,6 +648,7 @@ async function sendCalls(provider, from, chainId, calls, paymasterUrl) {
   try {
     result = await provider.request({ method: "wallet_sendCalls", params: [params] });
   } catch (e) {
+    if (e instanceof WalletTimeoutError) throw e;
     const msg = e?.message ?? String(e);
     if (/reject|denied|cancel|closed/i.test(msg)) {
       throw new WalletConnectionError("The player cancelled or closed the payment sheet.", { cause: msg });
@@ -497,14 +663,22 @@ async function waitForCalls(provider, id, timeoutMs = 6e4) {
   if (!id) return { status: "FAILED" };
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
-    const res = await provider.request({
-      method: "wallet_getCallsStatus",
-      params: [id]
-    });
-    const s = String(res?.status ?? "").toUpperCase();
-    const txHash = res?.receipts?.[0]?.transactionHash;
-    if (s === "200" || s === "CONFIRMED" || s === "SUCCESS") return { status: "CONFIRMED", txHash };
-    if (s === "400" || s === "500" || s === "FAILED" || s === "REVERTED") return { status: "FAILED", txHash };
+    try {
+      const res = await provider.request({
+        method: "wallet_getCallsStatus",
+        params: [id]
+      });
+      const s = String(res?.status ?? "").toUpperCase();
+      const txHash = res?.receipts?.[0]?.transactionHash;
+      if (s === "200" || s === "CONFIRMED" || s === "SUCCESS") return { status: "CONFIRMED", txHash };
+      if (s === "400" || s === "500" || s === "FAILED" || s === "REVERTED") return { status: "FAILED", txHash };
+    } catch (e) {
+      if (e instanceof WalletTimeoutError) {
+        await new Promise((r) => setTimeout(r, 900));
+        continue;
+      }
+      throw e;
+    }
     await new Promise((r) => setTimeout(r, 900));
   }
   return { status: "PENDING" };
@@ -636,12 +810,12 @@ function mockVerifyResult(payment) {
 }
 
 // src/x402.ts
-var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
-function requireAddress(value, field) {
+var ADDRESS_RE2 = /^0x[0-9a-fA-F]{40}$/;
+function requireAddress2(value, field) {
   if (typeof value !== "string" || value.trim() === "") {
     throw new MissingFieldError(field);
   }
-  if (!ADDRESS_RE.test(value)) {
+  if (!ADDRESS_RE2.test(value)) {
     throw new ConfigError(`${field} must be a 0x-prefixed 20-byte address, got: ${JSON.stringify(value)}`, {
       field,
       value
@@ -711,7 +885,7 @@ function createX402Challenge(requirement, extras) {
   if (typeof requirement.id !== "string" || !requirement.id.startsWith("preq_")) {
     throw new ConfigError('PaymentRequirement.id must be a "preq_\u2026" string', { id: requirement.id });
   }
-  requireAddress(requirement.payTo, "payTo");
+  requireAddress2(requirement.payTo, "payTo");
   parseUsdToMicro(requirement.amount);
   const feeBps = extras?.feeBps ?? 0;
   if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 1e4) {
@@ -721,7 +895,7 @@ function createX402Challenge(requirement, extras) {
     );
   }
   const feeSink = extras?.feeSink ?? null;
-  if (feeBps > 0 && feeSink) requireAddress(feeSink, "feeSink");
+  if (feeBps > 0 && feeSink) requireAddress2(feeSink, "feeSink");
   const paymentRequired = toX402PaymentRequired(requirement, { feeBps, feeSink });
   return {
     status: 402,
@@ -749,7 +923,7 @@ function validateX402ChallengeInput(input) {
       { field: "url" }
     );
   }
-  const payTo = requireAddress(input.payTo, "payTo");
+  const payTo = requireAddress2(input.payTo, "payTo");
   parseUsdToMicro(input.amount);
   const intent = input.intent ?? "transfer";
   if (intent !== "transfer" && intent !== "marketplace.buy") {
@@ -765,7 +939,7 @@ function validateX402ChallengeInput(input) {
       { feeBps: input.feeBps }
     );
   }
-  const feeSink = input.feeSink === void 0 ? void 0 : requireAddress(input.feeSink, "feeSink");
+  const feeSink = input.feeSink === void 0 ? void 0 : requireAddress2(input.feeSink, "feeSink");
   return {
     payTo,
     amount: input.amount,
@@ -779,12 +953,55 @@ function validateX402ChallengeInput(input) {
 }
 
 // src/client.ts
-var ADDRESS_RE2 = /^0x[0-9a-fA-F]{40}$/;
+var ADDRESS_RE3 = /^0x[0-9a-fA-F]{40}$/;
+function mapAlreadyEntered(e) {
+  const msg = e instanceof Error ? e.message : typeof e === "object" && e && "message" in e ? String(e.message) : String(e);
+  const detail = e instanceof PaymentFailedError || e instanceof ApiError ? e.detail : void 0;
+  const blob = `${msg} ${JSON.stringify(detail ?? {})}`;
+  if (/AlreadyEntered|already entered|already_entered/i.test(blob)) {
+    throw new AlreadyEnteredError({ cause: msg, ...detail ?? {} });
+  }
+  throw e;
+}
+var SETTLE_RECONCILE_TIMEOUT_MS = 2e4;
+var SETTLE_RECONCILE_INTERVAL_MS = 1e3;
+function isSoftRoundPollError(e, kind) {
+  if (e instanceof AuthError || e instanceof ConfigError) return false;
+  if (e instanceof ApiError) {
+    const status = typeof e.detail?.status === "number" ? e.detail.status : void 0;
+    const msg = e.message;
+    if (status === 409 && /already in progress|in progress — retry/i.test(msg)) {
+      return true;
+    }
+    if (kind === "settle") {
+      if (/cannot settle|not Locked on-chain|is already settled|nothing to settle/i.test(msg)) {
+        return false;
+      }
+    } else {
+      if (/cannot cancel|is already settled|is Settled on-chain|already settled — cannot cancel/i.test(
+        msg
+      )) {
+        return false;
+      }
+    }
+    if (status === 502 || status === 503 || status === 504 || status === 429 || e.detail?.gateway === true) {
+      return true;
+    }
+    if (status !== void 0 && status >= 400 && status < 500) return false;
+    if (status !== void 0 && status >= 500) return true;
+  }
+  return true;
+}
+function isSoftSettlePollError(e) {
+  return isSoftRoundPollError(e, "settle");
+}
+var CANCEL_RECONCILE_TIMEOUT_MS = SETTLE_RECONCILE_TIMEOUT_MS;
+var CANCEL_RECONCILE_INTERVAL_MS = SETTLE_RECONCILE_INTERVAL_MS;
 function requireAddressField(value, field) {
   if (typeof value !== "string" || value.trim() === "") {
     throw new MissingFieldError(field);
   }
-  if (!ADDRESS_RE2.test(value)) {
+  if (!ADDRESS_RE3.test(value)) {
     throw new ConfigError(
       `${field} must be a 0x-prefixed 20-byte wallet address (Phase 1a transfers settle server-held wallets), got: ${JSON.stringify(value)}`,
       { field, value }
@@ -972,11 +1189,22 @@ var Playmos = class {
      *   rounds.settle({ ranking }) → contract pays winners.
      *
      * Operator txs are signed by the Playmos service (OPERATOR_ROLE key).
+     *
+     * Offline `mock: true`: settle applies the stored payout rule and the 60/30/10
+     * pool leg across entries (#490). No series seed bank — mock pool is a floor,
+     * not a forecast of a live series with inherited seed.
      */
     /** Offline mock store for rounds.open/lock/settle/get when `mock: true` (3-game dogfood). */
     this.mockRounds = /* @__PURE__ */ new Map();
     /** Mock withdrawable credits after settle — key `${roundId}:${walletLower}` (#240 offline prize). */
     this.mockWithdrawable = /* @__PURE__ */ new Map();
+    /**
+     * Mock pot after per-entry rake (PrizePool escrowed sum) — keyed by roundId (#490).
+     * Payable pool at lock = pot × POOL_BPS / (POOL_BPS + SEED_BPS); inherited seed = 0 offline.
+     */
+    this.mockPotMicro = /* @__PURE__ */ new Map();
+    /** Persisted settle winners for re-settle replay (#490 C2) — never re-invent pool-to-everyone. */
+    this.mockSettleWinners = /* @__PURE__ */ new Map();
     this.rounds = {
       open: async (input) => {
         if (!this.config.mock) this.assertSecretKey("playmos.rounds.open");
@@ -1015,6 +1243,8 @@ var Playmos = class {
             prizePoolAddress: this.config.contracts?.prizePool ?? "0x0000000000000000000000000000000000000002"
           };
           this.mockRounds.set(input.roundId, round);
+          this.mockPotMicro.set(input.roundId, 0n);
+          this.mockSettleWinners.delete(input.roundId);
           return round;
         }
         const body = await this.http.post(
@@ -1047,11 +1277,12 @@ var Playmos = class {
               code: "conflict"
             });
           }
+          const payableMicro = this.mockPayablePoolMicro(existing);
+          const poolUsd = payableMicro > 0n ? formatMicroToUsd(payableMicro) : existing.pool ?? existing.entryAmount;
           const locked = {
             ...existing,
             status: "locked",
-            // Mock payable pool ≈ 60% of entry × max(1, entrants) for shape only — not money truth.
-            pool: existing.pool ?? existing.entryAmount,
+            pool: poolUsd,
             entrants: existing.entrants ?? 0,
             lockTxHash: MOCK_TX
           };
@@ -1074,14 +1305,15 @@ var Playmos = class {
             throw new ApiError(`unknown round: ${input.roundId}`, { status: 404, code: "not_found" });
           }
           if (existing.status === "settled" && existing.settleTxHash) {
+            const stored = this.mockSettleWinners.get(input.roundId);
             return {
               roundId: input.roundId,
               txHash: existing.settleTxHash,
               poolPaid: existing.pool ?? "0",
-              winners: "winners" in input.results ? input.results.winners : input.results.ranking.map((wallet) => ({
+              winners: stored ?? ("winners" in input.results ? input.results.winners : input.results.ranking.map((wallet) => ({
                 wallet,
-                amount: existing.pool ?? existing.entryAmount
-              })),
+                amount: "0"
+              }))),
               status: "settled"
             };
           }
@@ -1091,13 +1323,45 @@ var Playmos = class {
               code: "conflict"
             });
           }
-          const winners = "winners" in input.results ? input.results.winners : input.results.ranking.map((wallet, i) => ({
-            wallet,
-            // Winner-take-all mock shape when ranking only.
-            amount: i === 0 ? existing.pool ?? existing.entryAmount : "0"
-          }));
+          const payableMicro = existing.pool != null ? this.parseUsdToMicroLoose(existing.pool) : this.mockPayablePoolMicro(existing);
+          const poolPaid = payableMicro > 0n ? formatMicroToUsd(payableMicro) : existing.pool ?? existing.entryAmount;
+          let rows;
+          if ("winners" in input.results) {
+            rows = input.results.winners.map((w) => {
+              let micro;
+              try {
+                micro = this.parseUsdToMicroLoose(String(w.amount ?? "0"));
+              } catch (e) {
+                this.mockPayoutApiError(e);
+              }
+              return {
+                wallet: w.wallet,
+                amount: formatMicroToUsd(micro),
+                micro
+              };
+            });
+          } else {
+            if (payableMicro <= 0n) {
+              rows = [];
+            } else {
+              try {
+                const computed = computePayout(
+                  payableMicro,
+                  input.results.ranking,
+                  existing.payout
+                );
+                rows = computed.map((c) => ({
+                  wallet: c.wallet,
+                  amount: formatMicroToUsd(c.amount),
+                  micro: c.amount
+                }));
+              } catch (e) {
+                this.mockPayoutApiError(e);
+              }
+            }
+          }
+          const winners = rows.map(({ wallet, amount }) => ({ wallet, amount }));
           const settleTxHash = MOCK_TX;
-          const poolPaid = existing.pool ?? existing.entryAmount;
           const settled = {
             ...existing,
             status: "settled",
@@ -1105,18 +1369,11 @@ var Playmos = class {
             pool: poolPaid
           };
           this.mockRounds.set(input.roundId, settled);
-          for (const w of winners) {
-            const wAddr = String(w.wallet).toLowerCase();
-            let micro = 0n;
-            try {
-              micro = validateAmount(String(w.amount ?? "0"));
-            } catch {
-              micro = 0n;
-            }
-            if (micro > 0n) {
-              const k = `${input.roundId}:${wAddr}`;
-              this.mockWithdrawable.set(k, (this.mockWithdrawable.get(k) ?? 0n) + micro);
-            }
+          this.mockSettleWinners.set(input.roundId, winners);
+          for (const w of rows) {
+            if (w.micro <= 0n) continue;
+            const k = `${input.roundId}:${w.wallet.toLowerCase()}`;
+            this.mockWithdrawable.set(k, (this.mockWithdrawable.get(k) ?? 0n) + w.micro);
           }
           return {
             roundId: input.roundId,
@@ -1126,17 +1383,61 @@ var Playmos = class {
             status: "settled"
           };
         }
-        const { settle } = await this.http.post(
+        const timeoutMs = input.timeoutMs ?? SETTLE_RECONCILE_TIMEOUT_MS;
+        const intervalMs = input.intervalMs ?? SETTLE_RECONCILE_INTERVAL_MS;
+        const body = { gameId: input.gameId, results: input.results };
+        const idempotencyKey = `settle:${input.roundId}`;
+        const postSettle = () => this.http.post(
           `/rounds/${encodeURIComponent(input.roundId)}/settle`,
-          { gameId: input.gameId, results: input.results },
-          { acceptStatuses: [202] }
+          body,
+          { acceptStatuses: [200, 202], idempotencyKey }
         );
-        return settle;
+        let { settle } = await postSettle();
+        if (settle.status === "settled") return settle;
+        const firstWinners = settle.winners;
+        const firstPoolPaid = settle.poolPaid ?? null;
+        const withFirstExtras = (s) => ({
+          ...s,
+          winners: s.winners ?? firstWinners,
+          poolPaid: s.poolPaid ?? firstPoolPaid
+        });
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline && settle.status === "settling") {
+          const wait = Math.min(intervalMs, Math.max(0, deadline - Date.now()));
+          if (wait > 0) await new Promise((r) => setTimeout(r, wait));
+          if (Date.now() >= deadline) break;
+          try {
+            const again = await postSettle();
+            settle = withFirstExtras(again.settle);
+            if (settle.status === "settled") return settle;
+          } catch (e) {
+            if (!isSoftSettlePollError(e)) throw e;
+          }
+          try {
+            const round = await this.rounds.get({ roundId: input.roundId });
+            if (round.status === "settled") {
+              return {
+                roundId: input.roundId,
+                txHash: round.settleTxHash ?? settle.txHash ?? null,
+                poolPaid: round.pool ?? settle.poolPaid ?? firstPoolPaid,
+                winners: settle.winners ?? firstWinners,
+                status: "settled"
+              };
+            }
+          } catch (e) {
+            if (!isSoftSettlePollError(e)) throw e;
+          }
+        }
+        return withFirstExtras(settle);
       },
       /**
        * Cancel an open/locked round (operator sk_ only). Refunds entrants' escrowed ~90%
-       * and frees the series latch. May return `status: "cancelling"` (HTTP 202) until
-       * chain Cancelled(4) reconciles — poll `rounds.get` or re-call cancel (#346).
+       * and frees the series latch (#346 / #376).
+       *
+       * **Default is submit-only:** may return `status: "cancelling"` after broadcast —
+       * that is **not** success. Only `status: "cancelled"` means the chain is terminal.
+       * Pass `{ confirm: true }` to poll until cancelled or timeout (honest `cancelling`
+       * if still pending — never invents terminal success).
        */
       cancel: async (input) => {
         if (!this.config.mock) this.assertSecretKey("playmos.rounds.cancel");
@@ -1164,9 +1465,12 @@ var Playmos = class {
             ...existing,
             status: "cancelled",
             cancelTxHash: MOCK_TX,
-            pool: null
+            pool: null,
+            entrants: 0
           };
           this.mockRounds.set(input.roundId, cancelled);
+          this.mockPotMicro.set(input.roundId, 0n);
+          this.mockSettleWinners.delete(input.roundId);
           return {
             roundId: input.roundId,
             txHash: MOCK_TX,
@@ -1174,18 +1478,57 @@ var Playmos = class {
             round: cancelled
           };
         }
-        const body = await this.http.post(
-          `/rounds/${encodeURIComponent(input.roundId)}/cancel`,
-          { gameId: input.gameId },
-          { acceptStatuses: [202] }
-        );
-        const status = body.status === "cancelling" || body.round?.status === "cancelling" ? "cancelling" : "cancelled";
-        return {
-          roundId: input.roundId,
-          txHash: body.txHash ?? body.round?.cancelTxHash ?? null,
-          status,
-          round: body.round
+        const bodyPayload = { gameId: input.gameId };
+        const postCancel = () => this.http.post(`/rounds/${encodeURIComponent(input.roundId)}/cancel`, bodyPayload, {
+          acceptStatuses: [200, 202]
+        });
+        const toResult = (body, priorTx) => {
+          const explicitCancelled = body.status === "cancelled" || body.round?.status === "cancelled";
+          const explicitCancelling = body.status === "cancelling" || body.round?.status === "cancelling";
+          const status = explicitCancelled && !explicitCancelling ? "cancelled" : "cancelling";
+          const tx = body.txHash ?? body.round?.cancelTxHash ?? priorTx ?? null;
+          return {
+            roundId: input.roundId,
+            txHash: tx,
+            status,
+            round: body.round
+          };
         };
+        let result = toResult(await postCancel());
+        if (result.status === "cancelled") return result;
+        if (!input.confirm) return result;
+        const timeoutMs = Math.min(
+          Math.max(1, input.timeoutMs ?? CANCEL_RECONCILE_TIMEOUT_MS),
+          CANCEL_RECONCILE_TIMEOUT_MS
+        );
+        const intervalMs = Math.max(1, input.intervalMs ?? CANCEL_RECONCILE_INTERVAL_MS);
+        const deadline = Date.now() + timeoutMs;
+        const firstTx = result.txHash;
+        while (Date.now() < deadline && result.status === "cancelling") {
+          const wait = Math.min(intervalMs, Math.max(0, deadline - Date.now()));
+          if (wait > 0) await new Promise((r) => setTimeout(r, wait));
+          if (Date.now() >= deadline) break;
+          try {
+            result = toResult(await postCancel(), firstTx);
+            if (result.status === "cancelled") return result;
+          } catch (e) {
+            if (!isSoftRoundPollError(e, "cancel")) throw e;
+          }
+          try {
+            const round = await this.rounds.get({ roundId: input.roundId });
+            if (round.status === "cancelled") {
+              return {
+                roundId: input.roundId,
+                txHash: round.cancelTxHash ?? result.txHash ?? firstTx ?? null,
+                status: "cancelled",
+                round
+              };
+            }
+          } catch (e) {
+            if (!isSoftRoundPollError(e, "cancel")) throw e;
+          }
+        }
+        return { ...result, txHash: result.txHash ?? firstTx ?? null };
       },
       get: async (input) => {
         requireField(input?.roundId, "roundId");
@@ -1336,7 +1679,7 @@ var Playmos = class {
           }
           prizePool = round.prizePoolAddress;
         }
-        const provider = resolveProvider(this.config.wallet);
+        const provider = this.walletProvider();
         if (this.config.gas?.mode === "player") {
           const from0 = await getAccount(provider);
           await assertEnoughGas(provider, from0);
@@ -1353,18 +1696,31 @@ var Playmos = class {
         const paymasterUrl = this.config.gas?.mode === "sponsored" ? this.config.gas.paymasterUrl : void 0;
         let txHash;
         let status = "pending";
+        let callsId;
         try {
-          const { id: callsId } = await sendCalls(
+          const sent = await sendCalls(
             provider,
             from,
             this.env.chainId,
             [call],
             paymasterUrl
           );
+          callsId = sent.id;
           const waited = await waitForCalls(provider, callsId);
           txHash = waited.txHash;
           status = waited.status === "CONFIRMED" ? "confirmed" : waited.status === "FAILED" ? "failed" : "pending";
         } catch (e) {
+          if (e instanceof WalletTimeoutError && callsId) {
+            return {
+              prizePoolAddress: prizePool,
+              amount: formatMicroToUsd(amountMicro),
+              amountMicro: amountMicro.toString(),
+              txHash,
+              status: "pending",
+              callsId
+            };
+          }
+          if (e instanceof WalletTimeoutError) throw e;
           const msg = e?.message ?? String(e);
           if (/NothingToWithdraw|nothing to withdraw/i.test(msg)) {
             throw new NothingToWithdrawError({ prizePoolAddress: prizePool, wallet: from, cause: msg });
@@ -1384,7 +1740,8 @@ var Playmos = class {
           amount: formatMicroToUsd(amountMicro),
           amountMicro: amountMicro.toString(),
           txHash,
-          status
+          status,
+          ...status === "pending" && callsId ? { callsId } : {}
         };
       }
     };
@@ -1631,13 +1988,99 @@ var Playmos = class {
       }
     }
     this.http = createHttpClient(this.env.apiBaseUrl, config.apiKey, config.retry);
+    if (!config.mock) {
+      try {
+        resolveProvider(config.wallet, this.walletTimeoutPolicy());
+      } catch {
+      }
+    }
+  }
+  /**
+   * Resolve mock round by roundId **or** roundKey (kit `entryProvider` keys by roundKey, #490 C3).
+   */
+  findMockRound(idOrKey) {
+    const direct = this.mockRounds.get(idOrKey);
+    if (direct) return direct;
+    for (const r of this.mockRounds.values()) {
+      if (r.roundId === idOrKey || r.roundKey === idOrKey) return r;
+    }
+    return void 0;
+  }
+  /**
+   * 6dp USD → micro for mock winner amounts (#490 C1). Must not use 2dp `validateAmount`
+   * (would zero 0.135 from top-n 30% of $0.45).
+   */
+  parseUsdToMicroLoose(amount) {
+    if (typeof amount !== "string" || !/^\d+(\.\d{1,6})?$/.test(amount.trim())) {
+      throw new PayoutError(`invalid USD amount: ${JSON.stringify(amount)}`);
+    }
+    const [wholeRaw, frac = ""] = amount.trim().split(".");
+    const whole = wholeRaw ?? "0";
+    const fracPadded = (frac + "000000").slice(0, 6);
+    const micro = BigInt(whole) * 1000000n + BigInt(fracPadded);
+    if (micro < 0n) throw new PayoutError(`amount must be >= 0, got: ${JSON.stringify(amount)}`);
+    return micro;
+  }
+  /** Live-shaped 400 for mock payout validation (C5) — never leak raw PayoutError. */
+  mockPayoutApiError(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new ApiError(msg, { status: 400, code: "payout_invalid" });
+  }
+  /**
+   * Accumulate one mock entry into the pot (chain parity: rake off top, then lock split).
+   * No-op when no matching open/locked round — never 404 (C4).
+   */
+  mockAccumulateEntry(idOrKey, amountMicro) {
+    const round = this.findMockRound(idOrKey);
+    if (!round) return;
+    if (round.status !== "open" && round.status !== "locked") return;
+    const rake = amountMicro * BigInt(RAKE_BPS) / 10000n;
+    const escrowed = amountMicro - rake;
+    const pot = (this.mockPotMicro.get(round.roundId) ?? 0n) + escrowed;
+    this.mockPotMicro.set(round.roundId, pot);
+    const entrants = (round.entrants ?? 0) + 1;
+    const updated = { ...round, entrants };
+    this.mockRounds.set(round.roundId, updated);
+  }
+  /**
+   * Payable pool micro for mock lock/settle.
+   * With recorded entries: pot × POOL/(POOL+SEED) (seed bank = 0 offline).
+   * Zero entries: fall back to entryAmount micro (C4 — preserves existing suite).
+   */
+  mockPayablePoolMicro(round) {
+    const pot = this.mockPotMicro.get(round.roundId) ?? 0n;
+    if (pot > 0n) {
+      return pot * BigInt(POOL_BPS) / BigInt(POOL_BPS + SEED_BPS);
+    }
+    try {
+      return this.parseUsdToMicroLoose(round.entryAmount);
+    } catch {
+      return 0n;
+    }
+  }
+  /**
+   * Wallet timeout policy (#462 / PR #463 residual).
+   * - connectTimeoutMs → eth_requestAccounts only
+   * - machine RPCs → 20s default
+   * - wallet_sendCalls → unbounded (0) — never short-time a payment sheet
+   */
+  walletTimeoutPolicy() {
+    const connect = typeof this.config.connectTimeoutMs === "number" && this.config.connectTimeoutMs > 0 ? this.config.connectTimeoutMs : 2e4;
+    return {
+      connectTimeoutMs: connect,
+      requestTimeoutMs: 2e4,
+      sendCallsTimeoutMs: 0
+    };
+  }
+  walletProvider() {
+    return resolveProvider(this.config.wallet, this.walletTimeoutPolicy());
   }
   /** Connect the player's wallet and return their address. */
   async connect() {
     if (this.config.mock) {
       return "0x0000000000000000000000000000000000000001";
     }
-    return getAccount(resolveProvider(this.config.wallet));
+    return getAccount(this.walletProvider());
   }
   /**
    * A DROP-IN payment provider for game kits that expect `{ connect, payEntry }`
@@ -1697,7 +2140,7 @@ var Playmos = class {
         })
       );
     }
-    if (this.env.isTest && !await walletAvailable(this.config.wallet)) {
+    if (this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
       const res = await this.http.post(
         "/payments",
         {
@@ -1735,7 +2178,7 @@ var Playmos = class {
       },
       { idempotencyKey }
     );
-    const provider = resolveProvider(this.config.wallet);
+    const provider = this.walletProvider();
     if (this.config.gas?.mode === "player") {
       const from0 = await getAccount(provider);
       await assertEnoughGas(provider, from0);
@@ -1763,6 +2206,7 @@ var Playmos = class {
     const metadata = validateMetadata(input.metadata);
     const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
     if (this.config.mock) {
+      this.mockAccumulateEntry(input.roundId, amountMicro);
       return this.rememberMock(
         mockEntryPayment({
           amountMicro,
@@ -1780,7 +2224,17 @@ var Playmos = class {
         })
       );
     }
-    if (this.env.isTest && !await walletAvailable(this.config.wallet)) {
+    const serverSettleNoWallet = this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy());
+    if (!serverSettleNoWallet) {
+      const pinned = typeof input.identity === "string" ? input.identity.trim() : "";
+      if (!pinned) {
+        throw new ConfigError(
+          'enterRound: "identity" is required when using a player wallet. Pass the same identity your game server will use for hasEntered / entry confirm. One entry per identity \u2014 use a unique value per paid attempt (pay-per-play). Silent invent caused paid-but-not-admitted failures (#374 / #466). No-wallet sandbox smoke may omit identity (server-settle derives one).',
+          { field: "identity" }
+        );
+      }
+    }
+    if (serverSettleNoWallet) {
       const pinnedRoundKey = input.roundKey ?? input.roundId;
       const res = await this.http.post(
         "/payments",
@@ -1825,7 +2279,7 @@ var Playmos = class {
       },
       { idempotencyKey }
     );
-    const provider = resolveProvider(this.config.wallet);
+    const provider = this.walletProvider();
     if (this.config.gas?.mode === "player") {
       const from0 = await getAccount(provider);
       await assertEnoughGas(provider, from0);
@@ -1836,12 +2290,28 @@ var Playmos = class {
     if (!prizePool) throw new ConfigError("No PrizePool contract address for this game (service intent + config.contracts both empty).");
     const roundKey = intent.clientParams?.roundKey ?? intent.clientParams?.roundId ?? input.roundKey ?? intent.payment.roundId ?? input.roundId;
     if (!roundKey) throw new ConfigError("No roundKey/roundId for enterRound (service clientParams missing).");
-    const identity = intent.clientParams?.identity ?? input.identity ?? intent.payment.identity ?? `${from}#${idempotencyKey}`;
+    const identity = intent.clientParams?.identity ?? input.identity ?? intent.payment.identity;
+    if (!identity || !String(identity).trim()) {
+      throw new ConfigError(
+        "enterRound: missing on-chain identity after create-intent (pass input.identity).",
+        { field: "identity" }
+      );
+    }
     const amountUnits = this.resolveUnits(intent, amountMicro);
     const calls = buildEntryCalls({ usdc, prizePool, roundKey, identity, amountUnits });
-    const { id: callsId } = await sendCalls(provider, from, this.env.chainId, calls, this.sponsorUrl(intent));
+    let callsId;
+    try {
+      ({ id: callsId } = await sendCalls(provider, from, this.env.chainId, calls, this.sponsorUrl(intent)));
+    } catch (e) {
+      throw mapAlreadyEntered(e);
+    }
     const { txHash } = await waitForCalls(provider, callsId);
-    const payment = await this.settle(intent.payment.id, txHash);
+    let payment;
+    try {
+      payment = await this.settle(intent.payment.id, txHash);
+    } catch (e) {
+      throw mapAlreadyEntered(e);
+    }
     payment.identity = identity;
     payment.prizePoolAddress = prizePool.toLowerCase();
     payment.roundKey = roundKey;
@@ -2038,8 +2508,8 @@ var Playmos = class {
     });
     let raw;
     try {
-      if (await walletAvailable(this.config.wallet)) {
-        const provider = resolveProvider(this.config.wallet);
+      if (await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
+        const provider = this.walletProvider();
         raw = await provider.request({
           method: "eth_call",
           params: [{ to: prizePool, data }, "latest"]
@@ -2066,7 +2536,7 @@ var Playmos = class {
         raw = json.result;
       }
     } catch (e) {
-      if (e instanceof ApiError) throw e;
+      if (e instanceof ApiError || e instanceof WalletTimeoutError) throw e;
       throw new ApiError(`Could not read withdrawable balance: ${e.message}`, {
         prizePool,
         wallet
@@ -2157,112 +2627,6 @@ function previewPoolSplit(amount) {
   };
 }
 
-// src/payout.ts
-var PayoutError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.code = "payout_invalid";
-    this.name = "PayoutError";
-  }
-};
-var ADDRESS_RE3 = /^0x[0-9a-fA-F]{40}$/;
-var BPS = 10000n;
-function requireAddress2(w, i) {
-  if (!ADDRESS_RE3.test(w)) {
-    throw new PayoutError(`ranking[${i}] must be a 0x-prefixed 20-byte address, got: ${JSON.stringify(w)}`);
-  }
-  return w.toLowerCase();
-}
-function parseUsdToMicroLoose(amount) {
-  if (typeof amount !== "string" || !/^\d+(\.\d{1,6})?$/.test(amount.trim())) {
-    throw new PayoutError(`invalid USD amount: ${JSON.stringify(amount)}`);
-  }
-  const [wholeRaw, frac = ""] = amount.trim().split(".");
-  const whole = wholeRaw ?? "0";
-  const fracPadded = (frac + "000000").slice(0, 6);
-  const micro = BigInt(whole) * 1000000n + BigInt(fracPadded);
-  if (micro <= 0n) throw new PayoutError(`amount must be > 0, got: ${JSON.stringify(amount)}`);
-  return micro;
-}
-function computePayout(pool, ranking, rule) {
-  if (typeof pool !== "bigint" || pool <= 0n) {
-    throw new PayoutError(`pool must be a positive bigint (micro-USDC), got: ${String(pool)}`);
-  }
-  if (!Array.isArray(ranking) || ranking.length === 0) {
-    throw new PayoutError("ranking must be a non-empty array of wallets (best-first)");
-  }
-  const wallets = ranking.map((w, i) => requireAddress2(w, i));
-  const seen = /* @__PURE__ */ new Set();
-  for (const w of wallets) {
-    if (seen.has(w)) throw new PayoutError(`duplicate wallet in ranking: ${w}`);
-    seen.add(w);
-  }
-  if (rule.kind === "winner-take-all") {
-    return [{ wallet: wallets[0], amount: pool }];
-  }
-  if (rule.kind === "top-n") {
-    const splits = rule.splitsBps;
-    if (!Array.isArray(splits) || splits.length === 0) {
-      throw new PayoutError("top-n splitsBps must be a non-empty array");
-    }
-    if (splits.length > wallets.length) {
-      throw new PayoutError(
-        `top-n needs ${splits.length} ranked wallets but ranking only has ${wallets.length}`
-      );
-    }
-    let sumBps = 0;
-    for (const b of splits) {
-      if (!Number.isInteger(b) || b <= 0 || b > 1e4) {
-        throw new PayoutError(`each splitsBps entry must be an integer in (0, 10000], got: ${b}`);
-      }
-      sumBps += b;
-    }
-    if (sumBps !== 1e4) {
-      throw new PayoutError(`splitsBps must sum to 10000, got ${sumBps}`);
-    }
-    const out = [];
-    let allocated = 0n;
-    for (let i = 0; i < splits.length; i++) {
-      const amt = pool * BigInt(splits[i]) / BPS;
-      out.push({ wallet: wallets[i], amount: amt });
-      allocated += amt;
-    }
-    const remainder = pool - allocated;
-    if (remainder < 0n) throw new PayoutError("internal: allocated more than pool");
-    out[0] = { wallet: out[0].wallet, amount: out[0].amount + remainder };
-    const filtered = out.filter((x) => x.amount > 0n);
-    if (filtered.length === 0) throw new PayoutError("payout produced no positive amounts");
-    const total = filtered.reduce((s, x) => s + x.amount, 0n);
-    if (total !== pool) throw new PayoutError(`internal: sum ${total} != pool ${pool}`);
-    return filtered;
-  }
-  if (rule.kind === "custom") {
-    const amounts = rule.amounts;
-    if (!Array.isArray(amounts) || amounts.length === 0) {
-      throw new PayoutError("custom amounts must be a non-empty array of USD strings");
-    }
-    if (amounts.length > wallets.length) {
-      throw new PayoutError(
-        `custom amounts has ${amounts.length} entries but ranking only has ${wallets.length}`
-      );
-    }
-    const out = [];
-    let total = 0n;
-    for (let i = 0; i < amounts.length; i++) {
-      const amt = parseUsdToMicroLoose(amounts[i]);
-      out.push({ wallet: wallets[i], amount: amt });
-      total += amt;
-    }
-    if (total !== pool) {
-      throw new PayoutError(
-        `custom amounts sum to ${total} micro-USDC but pool is ${pool} \u2014 must match exactly`
-      );
-    }
-    return out;
-  }
-  throw new PayoutError(`unknown payout rule kind: ${JSON.stringify(rule.kind)}`);
-}
-
 // src/settlement.ts
 var ADDRESS_RE4 = /^0x[0-9a-fA-F]{40}$/;
 var DEFAULT_TTL_MS = 15 * 60 * 1e3;