@playmos/sdk 0.3.6 → 0.3.8

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
@@ -245,12 +245,66 @@ function createHttpClient(baseUrl, apiKey, retry) {
     }
     return false;
   }
+  async function probeSignerBelowFloor() {
+    try {
+      const res = await send(`${base}/health`, { method: "GET" });
+      if (!res.ok) return { below: false };
+      const body = await res.json();
+      const bal = body?.capabilities?.payments?.signerBalance;
+      if (!bal || bal.ok !== false) return { below: false };
+      const reason = bal.reason ?? "";
+      const fundedFloorMiss = reason === "low_usdc" || reason === "low_eth" || reason === "low_usdc_and_eth";
+      if (!fundedFloorMiss) return { below: false, reason: reason || void 0 };
+      return { below: true, reason };
+    } catch {
+      return { below: false };
+    }
+  }
   async function sendWithRetry(url, init) {
     let res = await send(url, init);
+    let signerBelowFloor = false;
+    let signerBelowReason;
+    let probed = false;
+    const maybeProbe = async () => {
+      if (probed || signerBelowFloor) return;
+      if (res.status !== 502 && res.status !== 503 && res.status !== 504) return;
+      const ct = (res.headers.get("content-type") || "").toLowerCase();
+      if (ct.includes("application/json")) return;
+      probed = true;
+      const probe = await probeSignerBelowFloor();
+      signerBelowFloor = probe.below;
+      signerBelowReason = probe.reason;
+    };
+    const maybePeekJsonSignerLow = async () => {
+      if (signerBelowFloor) return;
+      if (res.status !== 502 && res.status !== 503 && res.status !== 504) return;
+      const ct = (res.headers.get("content-type") || "").toLowerCase();
+      if (!ct.includes("application/json")) return;
+      try {
+        const peek = JSON.parse(await res.clone().text());
+        const code = peek?.error?.code;
+        const reason = peek?.error?.reason;
+        if (code === "signer_low_balance" || reason === "low_usdc" || reason === "low_eth" || reason === "low_usdc_and_eth") {
+          signerBelowFloor = true;
+          signerBelowReason = reason ?? code;
+        }
+      } catch {
+      }
+    };
+    const classifySignerBelow = async () => {
+      await maybeProbe();
+      await maybePeekJsonSignerLow();
+    };
+    await classifySignerBelow();
     for (let attempt = 0; attempt < cfg.maxRetries && isRetryable(res, init); attempt++) {
+      if (signerBelowFloor) break;
       await sleep(backoffMs(res, attempt, cfg));
       res = await send(url, init);
+      await classifySignerBelow();
     }
+    const flagged = res;
+    flagged.__playmosSignerBelowFloor = signerBelowFloor;
+    if (signerBelowReason) flagged.__playmosSignerBelowReason = signerBelowReason;
     return res;
   }
   async function handle(res, acceptStatuses) {
@@ -269,8 +323,22 @@ function createHttpClient(baseUrl, apiKey, retry) {
       json = text ? JSON.parse(text) : {};
     } catch {
       const gateway = res.status === 502 || res.status === 503 || res.status === 504;
-      const msg = gateway ? `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).` : `Non-JSON response (${res.status}) from ${res.url}`;
-      throw new ApiError(msg, { status: res.status, body: text.slice(0, 500), gateway });
+      const below = res.__playmosSignerBelowFloor === true;
+      let msg;
+      if (gateway && below) {
+        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 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}`;
+      }
+      throw new ApiError(msg, {
+        status: res.status,
+        body: text.slice(0, 500),
+        gateway,
+        signerBelowFloor: below || void 0
+      });
     }
     if (res.ok || acceptStatuses !== void 0 && acceptStatuses.includes(res.status)) {
       return json;
@@ -303,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";
@@ -320,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;
   }
 }
@@ -342,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
     });
@@ -415,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 });
@@ -429,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" };
@@ -712,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);
@@ -911,7 +1090,7 @@ var Playmos = class {
     this.mockWithdrawable = /* @__PURE__ */ new Map();
     this.rounds = {
       open: async (input) => {
-        this.assertSecretKey("playmos.rounds.open");
+        if (!this.config.mock) this.assertSecretKey("playmos.rounds.open");
         requireField(input?.gameId, "gameId");
         requireField(input?.roundId, "roundId");
         requireField(input?.entryAmount, "entryAmount");
@@ -965,7 +1144,7 @@ var Playmos = class {
         return body.round;
       },
       lock: async (input) => {
-        this.assertSecretKey("playmos.rounds.lock");
+        if (!this.config.mock) this.assertSecretKey("playmos.rounds.lock");
         requireField(input?.roundId, "roundId");
         if (this.config.mock) {
           const existing = this.mockRounds.get(input.roundId);
@@ -997,7 +1176,7 @@ var Playmos = class {
         return round;
       },
       settle: async (input) => {
-        this.assertSecretKey("playmos.rounds.settle");
+        if (!this.config.mock) this.assertSecretKey("playmos.rounds.settle");
         requireField(input?.roundId, "roundId");
         if (!input?.results) throw new ConfigError("results are required (ranking or winners)");
         if (this.config.mock) {
@@ -1058,20 +1237,64 @@ 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) => {
-        this.assertSecretKey("playmos.rounds.cancel");
+        if (!this.config.mock) this.assertSecretKey("playmos.rounds.cancel");
         requireField(input?.roundId, "roundId");
         if (this.config.mock) {
           const existing = this.mockRounds.get(input.roundId);
@@ -1106,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");
@@ -1268,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);
@@ -1285,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 });
@@ -1316,7 +1591,8 @@ var Playmos = class {
           amount: formatMicroToUsd(amountMicro),
           amountMicro: amountMicro.toString(),
           txHash,
-          status
+          status,
+          ...status === "pending" && callsId ? { callsId } : {}
         };
       }
     };
@@ -1563,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 }`
@@ -1629,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",
         {
@@ -1667,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);
@@ -1712,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",
@@ -1757,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);
@@ -1768,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;
@@ -1970,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"]
@@ -1998,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.6",
-  "description": "Playmos SDK \u2014 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.",
+  "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",