@playmos/sdk 0.3.7 → 0.3.8

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { N as Network, P as PlaymosConfig, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, C as CancelRoundResult, A as ActiveSeriesRound, c as PrizeBalance, d as WithdrawResult, e as AgentWallet, f as AgentFundResult, T as TransferResult, E as EscrowHoldInput, g as EscrowHoldResult, h as EscrowResolveResult, M as MarketplaceListInput, L as Listing, i as MarketplaceSaleResult, j as MarketplaceGetResult, k as PayInput, l as Payment, m as EnterRoundInput, n as TransferReconcile, o as WaitOptions, p as TransferInput, q as TransferConfirmOptions, V as VerifyResult, r as PayoutRule } from './errors-CdVzHuhY.js';
-export { s as ActiveForSeriesResult, t as AgentEconomyConfig, u as ApiError, v as AuthError, w as ConfigError, x as ContractConfig, y as Eip1193Provider, G as GasConfig, z as GasMode, I as InsufficientGasError, B as InvalidAmountError, D as ListingStatus, F as MarketplaceItem, H as MarketplaceSale, J as MissingFieldError, K as NothingToWithdrawError, O as PaymentFailedError, Q as PaymentStatus, U as PlaymosError, X as PlaymosErrorCode, Y as RetryOptions, Z as RoundStatus, _ as WalletConfig, $ as WalletConnectionError, a0 as WalletConnector, a1 as WebhookEventType } from './errors-CdVzHuhY.js';
+import { N as Network, P as PlaymosConfig, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, c as RoundCancelInput, C as CancelRoundResult, A as ActiveSeriesRound, d as PrizeBalance, e as WithdrawResult, f as AgentWallet, g as AgentFundResult, T as TransferResult, E as EscrowHoldInput, h as EscrowHoldResult, i as EscrowResolveResult, M as MarketplaceListInput, L as Listing, j as MarketplaceSaleResult, k as MarketplaceGetResult, l as PayInput, m as Payment, n as EnterRoundInput, o as TransferReconcile, p as WaitOptions, q as TransferInput, r as TransferConfirmOptions, V as VerifyResult, s as PayoutRule } from './errors-BMlWHsMb.js';
+export { t as ActiveForSeriesResult, u as AgentEconomyConfig, v as AlreadyEnteredError, w as ApiError, x as AuthError, y as ConfigError, z as ContractConfig, B as Eip1193Provider, G as GasConfig, D as GasMode, I as InsufficientGasError, F as InvalidAmountError, H as ListingStatus, J as MarketplaceItem, K as MarketplaceSale, O as MissingFieldError, Q as NothingToWithdrawError, U as PaymentFailedError, X as PaymentStatus, Y as PlaymosError, Z as PlaymosErrorCode, _ as RetryOptions, $ as RoundStatus, a0 as WalletConfig, a1 as WalletConnectionError, a2 as WalletConnector, a3 as WalletTimeoutError, a4 as WebhookEventType } from './errors-BMlWHsMb.js';
 
 /**
  * Environment resolution + the canonical address book.
@@ -477,13 +477,14 @@ declare class Playmos {
         settle: (input: RoundSettleInput) => Promise<SettleRoundResult>;
         /**
          * 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: (input: {
-            roundId: string;
-            gameId?: string;
-        }) => Promise<CancelRoundResult>;
+        cancel: (input: RoundCancelInput) => Promise<CancelRoundResult>;
         get: (input: {
             roundId: string;
         }) => Promise<RoundState>;
@@ -606,6 +607,14 @@ declare class Playmos {
      */
     private readonly mockPayments;
     constructor(config: PlaymosConfig);
+    /**
+     * 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
+     */
+    private walletTimeoutPolicy;
+    private walletProvider;
     /** Connect the player's wallet and return their address. */
     connect(): Promise<`0x${string}`>;
     /**
@@ -848,4 +857,4 @@ declare function ulid(seedTime?: number): string;
 /** `${prefix}_${ulid()}` — e.g. `pay_01J…`, `entry_01J…`, `idem_01J…`. */
 declare function prefixedId(prefix: string): string;
 
-export { ActiveSeriesRound, AgentFundResult, AgentWallet, type Authorization, CHAIN_ID, CancelRoundResult, type CreatePaymentRequirementInput, DEFAULT_API_BASE_URL, EnterRoundInput, EscrowHoldInput, EscrowHoldResult, EscrowResolveResult, Listing, MICRO_PER_USDC, MarketplaceGetResult, MarketplaceListInput, MarketplaceSaleResult, Network, PayInput, Payment, type PaymentRequirement, PayoutError, PayoutRule, PayoutRule as PayoutRuleCompute, Playmos, PlaymosConfig, PrizeBalance, RoundOpenInput, RoundSettleInput, RoundState, SettleRoundResult, type SettlementAsset, TransferConfirmOptions, TransferInput, TransferReconcile, TransferResult, USDC_ADDRESS, USDC_DECIMALS, VerifyResult, WaitOptions, type WalletSignatureAuthorization, WebhookEvent, WithdrawResult, type X402ChallengeInput, type X402ChallengeResult, type X402FulfillAuthorization, type X402PayInput, type X402PayloadAuthorization, type X402PayloadMode, type X402PaymentRequired, type X402SettleResult, clientRuntimeSignals, computeIapSplit, computePayout, computePoolSplit, createPaymentRequirement, createX402Challenge, decodePaymentHeader, encodePaymentHeader, formatMicroToUsd, isClientRuntime, isWalletSignatureAuthorization, isX402PayloadAuthorization, networkToCaip2, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, resolveEnv, serializePaymentRequirement, toX402PaymentRequired, ulid, validateX402ChallengeInput };
+export { ActiveSeriesRound, AgentFundResult, AgentWallet, type Authorization, CHAIN_ID, CancelRoundResult, type CreatePaymentRequirementInput, DEFAULT_API_BASE_URL, EnterRoundInput, EscrowHoldInput, EscrowHoldResult, EscrowResolveResult, Listing, MICRO_PER_USDC, MarketplaceGetResult, MarketplaceListInput, MarketplaceSaleResult, Network, PayInput, Payment, type PaymentRequirement, PayoutError, PayoutRule, PayoutRule as PayoutRuleCompute, Playmos, PlaymosConfig, PrizeBalance, RoundCancelInput, RoundOpenInput, RoundSettleInput, RoundState, SettleRoundResult, type SettlementAsset, TransferConfirmOptions, TransferInput, TransferReconcile, TransferResult, USDC_ADDRESS, USDC_DECIMALS, VerifyResult, WaitOptions, type WalletSignatureAuthorization, WebhookEvent, WithdrawResult, type X402ChallengeInput, type X402ChallengeResult, type X402FulfillAuthorization, type X402PayInput, type X402PayloadAuthorization, type X402PayloadMode, type X402PaymentRequired, type X402SettleResult, clientRuntimeSignals, computeIapSplit, computePayout, computePoolSplit, createPaymentRequirement, createX402Challenge, decodePaymentHeader, encodePaymentHeader, formatMicroToUsd, isClientRuntime, isWalletSignatureAuthorization, isX402PayloadAuthorization, networkToCaip2, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, resolveEnv, serializePaymentRequirement, toX402PaymentRequired, ulid, validateX402ChallengeInput };

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
@@ -329,7 +329,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 +371,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 +441,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 +468,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 +542,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 +557,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" };
@@ -780,6 +848,49 @@ function validateX402ChallengeInput(input) {
 
 // src/client.ts
 var ADDRESS_RE2 = /^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);
@@ -1126,17 +1237,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");
@@ -1174,18 +1329,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 +1530,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 +1547,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 +1591,8 @@ var Playmos = class {
           amount: formatMicroToUsd(amountMicro),
           amountMicro: amountMicro.toString(),
           txHash,
-          status
+          status,
+          ...status === "pending" && callsId ? { callsId } : {}
         };
       }
     };
@@ -1631,13 +1839,36 @@ var Playmos = class {
       }
     }
     this.http = createHttpClient(this.env.apiBaseUrl, config.apiKey, config.retry);
+    if (!config.mock) {
+      try {
+        resolveProvider(config.wallet, this.walletTimeoutPolicy());
+      } catch {
+      }
+    }
+  }
+  /**
+   * 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 +1928,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 +1966,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);
@@ -1780,7 +2011,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 +2066,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 +2077,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 +2295,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 +2323,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

package/dist/server.d.cts

@@ -1,4 +1,4 @@
-import { U as PlaymosError, W as WebhookEvent } from './errors-CdVzHuhY.cjs';
+import { Y as PlaymosError, W as WebhookEvent } from './errors-BMlWHsMb.cjs';
 
 /**
  * Webhook signature verification (spec §6.2) — server-side only.

package/dist/server.d.ts

@@ -1,4 +1,4 @@
-import { U as PlaymosError, W as WebhookEvent } from './errors-CdVzHuhY.js';
+import { Y as PlaymosError, W as WebhookEvent } from './errors-BMlWHsMb.js';
 
 /**
  * Webhook signature verification (spec §6.2) — server-side only.

package/dist/server.js

@@ -1,4 +1,4 @@
-import { PlaymosError } from './chunk-VYR6BBHF.js';
+import { PlaymosError } from './chunk-UZECDT6F.js';
 import { timingSafeEqual, createHmac } from 'crypto';
 
 var WebhookSignatureError = class extends PlaymosError {

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@playmos/sdk",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "Playmos SDK — stablecoin payments for games on Base. One SDK for IAP (1%), skill-game prize-pool entries (10%, 60/30/10), and agent economies. USD in, USDC on-chain, no crypto UX for players.",
   "license": "UNLICENSED",
   "private": false,
+  "homepage": "https://playmos-docs-public.vercel.app/docs",
+  "bugs": {
+    "url": "https://playmos-docs-public.vercel.app/docs"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/playmos-labs/playmos-sdk.git",