@playmos/sdk 0.3.1 → 0.3.3

package/dist/index.js

@@ -1,4 +1,4 @@
-import { InvalidAmountError, ConfigError, NothingToWithdrawError, PaymentFailedError, ApiError, MissingFieldError, WalletConnectionError, InsufficientGasError, AuthError } from './chunk-TMBBEGIF.js';
+import { InvalidAmountError, ConfigError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, ApiError, WalletConnectionError, InsufficientGasError, AuthError } from './chunk-TMBBEGIF.js';
 export { ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError } from './chunk-TMBBEGIF.js';
 import { encodeFunctionData, decodeFunctionResult, numberToHex, keccak256, toBytes } from 'viem';
 
@@ -205,15 +205,36 @@ function createHttpClient(baseUrl, apiKey, retry) {
       );
     }
   }
+  function hasIdempotencyKey(init) {
+    const h = init.headers;
+    if (!h) return false;
+    if (h instanceof Headers) {
+      return Boolean(h.get("idempotency-key") || h.get("Idempotency-Key"));
+    }
+    if (Array.isArray(h)) {
+      return h.some(([k]) => String(k).toLowerCase() === "idempotency-key");
+    }
+    const rec = h;
+    return Object.keys(rec).some((k) => k.toLowerCase() === "idempotency-key" && !!rec[k]);
+  }
+  function isRetryable(res, init) {
+    if (res.status === 429) return true;
+    if (res.status === 502 || res.status === 503 || res.status === 504) {
+      const method = (init.method ?? "GET").toUpperCase();
+      if (method === "GET" || method === "HEAD") return true;
+      return hasIdempotencyKey(init);
+    }
+    return false;
+  }
   async function sendWithRetry(url, init) {
     let res = await send(url, init);
-    for (let attempt = 0; res.status === 429 && attempt < cfg.maxRetries; attempt++) {
+    for (let attempt = 0; attempt < cfg.maxRetries && isRetryable(res, init); attempt++) {
       await sleep(backoffMs(res, attempt, cfg));
       res = await send(url, init);
     }
     return res;
   }
-  async function handle(res) {
+  async function handle(res, acceptStatuses) {
     let text;
     try {
       text = await res.text();
@@ -228,9 +249,13 @@ function createHttpClient(baseUrl, apiKey, retry) {
     try {
       json = text ? JSON.parse(text) : {};
     } catch {
-      throw new ApiError(`Non-JSON response (${res.status}) from ${res.url}`, { status: res.status, body: text });
+      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 });
+    }
+    if (res.ok || acceptStatuses !== void 0 && acceptStatuses.includes(res.status)) {
+      return json;
     }
-    if (res.ok) return json;
     const errBody = json;
     const message = errBody?.error?.message ?? `Request failed with ${res.status}`;
     if (res.status === 401 || res.status === 403 || errBody?.error?.code === "auth") {
@@ -246,7 +271,7 @@ function createHttpClient(baseUrl, apiKey, retry) {
       };
       if (opts?.idempotencyKey) headers["idempotency-key"] = opts.idempotencyKey;
       const res = await sendWithRetry(`${base}${path}`, { method: "POST", headers, body: JSON.stringify(body) });
-      return handle(res);
+      return handle(res, opts?.acceptStatuses);
     },
     async get(path) {
       const res = await sendWithRetry(`${base}${path}`, {
@@ -462,7 +487,23 @@ async function waitForCalls(provider, id, timeoutMs = 6e4) {
 function encodeApprove(spender, amountUnits) {
   return encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: [spender, amountUnits] });
 }
-async function assertEnoughGas(provider, from, minWei = 200000000000000n) {
+var GAS_FLOOR_WEI_DEFAULT = 200000000000000n;
+var GAS_FLOOR_WEI_BASE_SEPOLIA = 50000000000000n;
+var CHAIN_ID_BASE_SEPOLIA = 84532;
+function gasFloorWei(chainId) {
+  return chainId === CHAIN_ID_BASE_SEPOLIA ? GAS_FLOOR_WEI_BASE_SEPOLIA : GAS_FLOOR_WEI_DEFAULT;
+}
+async function assertEnoughGas(provider, from, minWei) {
+  let floor = minWei;
+  if (floor === void 0) {
+    let chainId = 0;
+    try {
+      const hex = await provider.request({ method: "eth_chainId", params: [] });
+      chainId = Number(BigInt(hex));
+    } catch {
+    }
+    floor = gasFloorWei(chainId);
+  }
   let balance;
   try {
     const hex = await provider.request({ method: "eth_getBalance", params: [from, "latest"] });
@@ -470,8 +511,11 @@ async function assertEnoughGas(provider, from, minWei = 200000000000000n) {
   } catch {
     return;
   }
-  if (balance < minWei) {
-    throw new InsufficientGasError({ balanceWei: balance.toString(), minWei: minWei.toString() });
+  if (balance < floor) {
+    throw new InsufficientGasError({
+      balanceWei: balance.toString(),
+      minWei: floor.toString()
+    });
   }
 }
 var toBytes32 = (s) => keccak256(toBytes(s));
@@ -533,6 +577,7 @@ function mockEntryPayment(args) {
     args.seedBps,
     args.rakeBps
   );
+  const roundKey = args.roundKey && args.roundKey.trim() !== "" ? args.roundKey : args.roundId;
   return {
     id: prefixedId("entry"),
     status: "confirmed",
@@ -549,7 +594,8 @@ function mockEntryPayment(args) {
     },
     gameId: args.gameId,
     roundId: args.roundId,
-    roundKey: args.roundId,
+    roundKey,
+    identity: args.identity,
     // Deterministic mock pool address so claim-flow unit tests can assert shape (#41).
     prizePoolAddress: "0x0000000000000000000000000000000000000001",
     playerId: args.playerId,
@@ -560,14 +606,160 @@ function mockEntryPayment(args) {
     mock: true
   };
 }
+function mockVerifyResult(payment) {
+  return { ...payment, mock: true };
+}
 
-// src/client.ts
+// src/x402.ts
 var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
-function requireAddressField(value, field) {
+function requireAddress(value, field) {
   if (typeof value !== "string" || value.trim() === "") {
     throw new MissingFieldError(field);
   }
   if (!ADDRESS_RE.test(value)) {
+    throw new ConfigError(`${field} must be a 0x-prefixed 20-byte address, got: ${JSON.stringify(value)}`, {
+      field,
+      value
+    });
+  }
+  return value.toLowerCase();
+}
+function networkToCaip2(network) {
+  if (network === "base") return "eip155:8453";
+  if (network === "base-sepolia") return "eip155:84532";
+  throw new ConfigError(`Unknown network for x402: ${JSON.stringify(network)}`, { network });
+}
+function toX402PaymentRequired(req, extras) {
+  const amountMicro = parseUsdToMicro(req.amount);
+  const out = {
+    scheme: "exact",
+    network: networkToCaip2(req.network),
+    maxAmountRequired: amountMicro.toString(),
+    // Service V1 emits the asset symbol; address is implied by network + config.
+    asset: "USDC",
+    payTo: req.payTo,
+    playmosRequirementId: req.id,
+    amount: req.amount,
+    playmosNetwork: req.network,
+    expiresAt: req.expiresAt,
+    terms: req.terms ?? null,
+    feeBps: extras?.feeBps ?? null,
+    feeSink: extras?.feeSink ?? null
+  };
+  return out;
+}
+function encodePaymentHeader(obj) {
+  const json = JSON.stringify(obj);
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(json, "utf8").toString("base64");
+  }
+  const bytes = new TextEncoder().encode(json);
+  let bin = "";
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+  return btoa(bin);
+}
+function decodePaymentHeader(header) {
+  if (typeof header !== "string" || header.trim() === "") {
+    throw new ConfigError("payment header must be a non-empty base64 JSON string");
+  }
+  try {
+    let json;
+    if (typeof Buffer !== "undefined") {
+      json = Buffer.from(header, "base64").toString("utf8");
+    } else {
+      const bin = atob(header);
+      const bytes = new Uint8Array(bin.length);
+      for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+      json = new TextDecoder().decode(bytes);
+    }
+    return JSON.parse(json);
+  } catch (err) {
+    throw new ConfigError("invalid base64 JSON payment header", {
+      cause: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+function createX402Challenge(requirement, extras) {
+  if (!requirement || typeof requirement !== "object") {
+    throw new ConfigError("createX402Challenge requires a PaymentRequirement");
+  }
+  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");
+  parseUsdToMicro(requirement.amount);
+  const feeBps = extras?.feeBps ?? 0;
+  if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 1e4) {
+    throw new ConfigError(
+      `feeBps must be an integer in [0, 10000], got: ${JSON.stringify(extras?.feeBps)}`,
+      { feeBps: extras?.feeBps }
+    );
+  }
+  const feeSink = extras?.feeSink ?? null;
+  if (feeBps > 0 && feeSink) requireAddress(feeSink, "feeSink");
+  const paymentRequired = toX402PaymentRequired(requirement, { feeBps, feeSink });
+  return {
+    status: 402,
+    headers: {
+      "PAYMENT-REQUIRED": encodePaymentHeader(paymentRequired),
+      "Content-Type": "application/json"
+    },
+    body: {
+      error: { code: "payment_required", message: "Payment Required" },
+      requirement,
+      paymentRequired,
+      feeBps,
+      feeSink
+    },
+    paymentRequired
+  };
+}
+function validateX402ChallengeInput(input) {
+  if (!input || typeof input !== "object") {
+    throw new ConfigError("x402 challenge input is required");
+  }
+  if ("url" in input && input.url !== void 0) {
+    throw new ConfigError(
+      "playmos.x402 does not accept { url } in V1 \u2014 use pay({ payTo, amount }) wrapping challenges+settle (ADR: resource URLs deferred V1.1+). See docs/design/PHASE-4-X402-ADR.md.",
+      { field: "url" }
+    );
+  }
+  const payTo = requireAddress(input.payTo, "payTo");
+  parseUsdToMicro(input.amount);
+  const intent = input.intent ?? "transfer";
+  if (intent !== "transfer" && intent !== "marketplace.buy") {
+    throw new ConfigError(
+      `x402 intent must be "transfer" or "marketplace.buy", got: ${JSON.stringify(input.intent)}`,
+      { intent: input.intent }
+    );
+  }
+  const feeBps = input.feeBps ?? 0;
+  if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 1e4) {
+    throw new ConfigError(
+      `feeBps must be an integer in [0, 10000], got: ${JSON.stringify(input.feeBps)}`,
+      { feeBps: input.feeBps }
+    );
+  }
+  const feeSink = input.feeSink === void 0 ? void 0 : requireAddress(input.feeSink, "feeSink");
+  return {
+    payTo,
+    amount: input.amount,
+    intent,
+    feeBps,
+    ...feeSink !== void 0 ? { feeSink } : {},
+    ...input.terms !== void 0 ? { terms: input.terms } : {},
+    ...input.expiresInMs !== void 0 ? { expiresInMs: input.expiresInMs } : {},
+    ...input.id !== void 0 ? { id: input.id } : {}
+  };
+}
+
+// src/client.ts
+var ADDRESS_RE2 = /^0x[0-9a-fA-F]{40}$/;
+function requireAddressField(value, field) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new MissingFieldError(field);
+  }
+  if (!ADDRESS_RE2.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 }
@@ -612,6 +804,122 @@ var Playmos = class {
       /** Create a Bridge KYC onboarding link (fiat payout). */
       createOnboardingLink: () => this.http.post("/payouts/onboarding_link", {})
     };
+    /**
+     * `x402` — Phase 4 HTTP 402 / x402-shaped adapter (#153).
+     *
+     * V1 surface (ADR):
+     *   - `challenge` → `POST /v1/x402/challenges` (returns 402; treated as success)
+     *   - `fulfill`   → `POST /v1/x402/settle`
+     *   - `pay`       → challenge then fulfill (senior DX ≤15 lines)
+     *
+     * **Not** resource URLs (`pay({ url })` is V1.1+). **Not** stock third-party
+     * x402 client interop (X3b deferred until #161). Requires `sk_test_` +
+     * Base Sepolia; flag `PLAYMOS_X402_ENABLED` on the service.
+     *
+     * ```ts
+     * const playmos = new Playmos({ apiKey: process.env.PLAYMOS_SK!, network: "base-sepolia" });
+     * const result = await playmos.x402.pay({
+     *   payTo: "0x…",
+     *   amount: "0.50",
+     *   feeBps: 0,
+     * });
+     * // result.txHash → BaseScan
+     * ```
+     */
+    this.x402 = {
+      /**
+       * Mint a server-authoritative PaymentRequirement (HTTP 402).
+       * Fee terms are stored server-side — settle rejects payload disagreement.
+       */
+      challenge: async (input) => {
+        this.assertX402Allowed();
+        const body = validateX402ChallengeInput(input);
+        if (body.intent === "marketplace.buy") {
+          throw new ConfigError(
+            'x402 challenge intent "marketplace.buy" is not supported yet (V1 service: "transfer" only; marketplace.buy follows).',
+            { intent: body.intent }
+          );
+        }
+        const res = await this.http.post("/x402/challenges", body, { acceptStatuses: [402] });
+        return {
+          requirement: res.requirement,
+          paymentRequired: res.paymentRequired,
+          feeBps: res.feeBps ?? body.feeBps,
+          feeSink: res.feeSink ?? body.feeSink ?? null
+        };
+      },
+      /**
+       * Settle a previously minted challenge with an `x402-payload` authorization.
+       * Defaults mode to `server-signer` when omitted (explicit on the wire — fail-closed
+       * materialize still requires mode; the route also defaults for this path).
+       */
+      fulfill: async (requirement, authorization) => {
+        this.assertX402Allowed();
+        if (!requirement || typeof requirement !== "object") {
+          throw new ConfigError("fulfill requires a PaymentRequirement from challenge()");
+        }
+        if (typeof requirement.id !== "string" || requirement.id.trim() === "") {
+          throw new MissingFieldError("requirement.id");
+        }
+        let payload;
+        if (authorization && typeof authorization === "object" && "kind" in authorization) {
+          const a = authorization;
+          if (a.kind !== "x402-payload") {
+            throw new ConfigError('authorization.kind must be "x402-payload"', { kind: a.kind });
+          }
+          payload = { ...a.payload ?? {} };
+        } else {
+          payload = { ...authorization ?? {} };
+        }
+        delete payload.feeBps;
+        delete payload.feeSink;
+        if (payload.mode === void 0 || typeof payload.mode === "string" && payload.mode.trim() === "") {
+          const hasNestedAuth = payload.authorization !== void 0 || payload.signature !== void 0 || payload.paymentPayload !== void 0;
+          if (hasNestedAuth) {
+            throw new ConfigError(
+              "fulfill: payload.mode is required when authorization/signature is present \u2014 stock-shaped payloads are not auto-mapped to server-signer (V1: no interop; set mode explicitly or see #161)",
+              { field: "mode" }
+            );
+          }
+          payload.mode = "server-signer";
+        }
+        if (payload.scheme === void 0) payload.scheme = "exact";
+        if (payload.requirementId === void 0) payload.requirementId = requirement.id;
+        const res = await this.http.post("/x402/settle", {
+          requirement,
+          authorization: { kind: "x402-payload", payload }
+        });
+        const s = res.settlement;
+        return {
+          requirementId: s.requirementId,
+          status: s.status,
+          txHash: s.txHash ?? null,
+          idempotentReplay: Boolean(s.idempotentReplay),
+          verifiedVia: s.verifiedVia,
+          feeBps: s.feeBps,
+          fee: s.fee,
+          net: s.net,
+          requirement: res.requirement,
+          success: s.success
+        };
+      },
+      /**
+       * Senior DX: mint challenge + settle in one call.
+       * Wraps challenges + settle only — **not** `pay({ url })` (ADR).
+       */
+      pay: async (input) => {
+        this.assertX402Allowed();
+        validateX402ChallengeInput(input);
+        const challenge = await this.x402.challenge(input);
+        const auth = {
+          mode: input.mode ?? "server-signer"
+        };
+        if (input.from !== void 0) auth.from = input.from;
+        if (input.authorization !== void 0) auth.authorization = input.authorization;
+        if (input.txHash !== void 0) auth.txHash = input.txHash;
+        return this.x402.fulfill(challenge.requirement, auth);
+      }
+    };
     /**
      * Skill/contest **round lifecycle** (issue #13) — closes the enterRound loop.
      *
@@ -621,6 +929,8 @@ var Playmos = class {
      *
      * Operator txs are signed by the Playmos service (OPERATOR_ROLE key).
      */
+    /** Offline mock store for rounds.open/lock/settle/get when `mock: true` (3-game dogfood). */
+    this.mockRounds = /* @__PURE__ */ new Map();
     this.rounds = {
       open: async (input) => {
         requireField(input?.gameId, "gameId");
@@ -630,6 +940,34 @@ var Playmos = class {
           throw new ConfigError("payout rule is required (winner-take-all | top-n | custom)");
         }
         validateAmount(input.entryAmount);
+        if (this.config.mock) {
+          const roundKey = input.roundKey ?? input.roundId;
+          const existing = this.mockRounds.get(input.roundId);
+          if (existing?.status === "open" || existing?.status === "locked") {
+            return existing;
+          }
+          if (existing?.status === "settled") {
+            throw new ApiError(`round ${input.roundId} already settled`, {
+              status: 409,
+              code: "conflict"
+            });
+          }
+          const round2 = {
+            roundId: input.roundId,
+            gameId: input.gameId,
+            roundKey,
+            status: "open",
+            entryAmount: input.entryAmount,
+            pool: null,
+            entrants: 0,
+            payout: input.payout,
+            closeAt: input.closeAt,
+            openTxHash: "0x000000000000000000000000000000000000000000000000000000000000mock",
+            prizePoolAddress: this.config.contracts?.prizePool ?? "0x0000000000000000000000000000000000000002"
+          };
+          this.mockRounds.set(input.roundId, round2);
+          return round2;
+        }
         const { round } = await this.http.post("/rounds", {
           gameId: input.gameId,
           roundId: input.roundId,
@@ -643,6 +981,29 @@ var Playmos = class {
       },
       lock: async (input) => {
         requireField(input?.roundId, "roundId");
+        if (this.config.mock) {
+          const existing = this.mockRounds.get(input.roundId);
+          if (!existing) {
+            throw new ApiError(`unknown round: ${input.roundId}`, { status: 404, code: "not_found" });
+          }
+          if (existing.status === "locked" || existing.status === "settled") return existing;
+          if (existing.status !== "open") {
+            throw new ApiError(`round ${input.roundId} is not open (status=${existing.status})`, {
+              status: 409,
+              code: "conflict"
+            });
+          }
+          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,
+            entrants: existing.entrants ?? 0,
+            lockTxHash: "0x000000000000000000000000000000000000000000000000000000000000loc1"
+          };
+          this.mockRounds.set(input.roundId, locked);
+          return locked;
+        }
         const { round } = await this.http.post(
           `/rounds/${encodeURIComponent(input.roundId)}/lock`,
           { gameId: input.gameId }
@@ -652,6 +1013,51 @@ var Playmos = class {
       settle: async (input) => {
         requireField(input?.roundId, "roundId");
         if (!input?.results) throw new ConfigError("results are required (ranking or winners)");
+        if (this.config.mock) {
+          const existing = this.mockRounds.get(input.roundId);
+          if (!existing) {
+            throw new ApiError(`unknown round: ${input.roundId}`, { status: 404, code: "not_found" });
+          }
+          if (existing.status === "settled" && existing.settleTxHash) {
+            return {
+              roundId: input.roundId,
+              txHash: existing.settleTxHash,
+              poolPaid: existing.pool ?? "0",
+              winners: "winners" in input.results ? input.results.winners : input.results.ranking.map((wallet) => ({
+                wallet,
+                amount: existing.pool ?? existing.entryAmount
+              })),
+              status: "settled"
+            };
+          }
+          if (existing.status !== "locked" && existing.status !== "open") {
+            throw new ApiError(`round ${input.roundId} cannot settle (status=${existing.status})`, {
+              status: 409,
+              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 settleTxHash = "0x000000000000000000000000000000000000000000000000000000000000set1";
+          const poolPaid = existing.pool ?? existing.entryAmount;
+          const settled = {
+            ...existing,
+            status: "settled",
+            settleTxHash,
+            pool: poolPaid
+          };
+          this.mockRounds.set(input.roundId, settled);
+          return {
+            roundId: input.roundId,
+            txHash: settleTxHash,
+            poolPaid,
+            winners,
+            status: "settled"
+          };
+        }
         const { settle } = await this.http.post(
           `/rounds/${encodeURIComponent(input.roundId)}/settle`,
           { gameId: input.gameId, results: input.results }
@@ -660,6 +1066,13 @@ var Playmos = class {
       },
       get: async (input) => {
         requireField(input?.roundId, "roundId");
+        if (this.config.mock) {
+          const existing = this.mockRounds.get(input.roundId);
+          if (!existing) {
+            throw new ApiError(`unknown round: ${input.roundId}`, { status: 404, code: "not_found" });
+          }
+          return existing;
+        }
         const { round } = await this.http.get(
           `/rounds/${encodeURIComponent(input.roundId)}`
         );
@@ -944,6 +1357,11 @@ var Playmos = class {
         return this.http.get(`/listings/${encodeURIComponent(listingId)}`);
       }
     };
+    /**
+     * Offline mock payments for this client instance — so `verify(id)` after
+     * `mock: true` pay/enterRound does not hit the live API (#204).
+     */
+    this.mockPayments = /* @__PURE__ */ new Map();
     /**
      * `transfers` — read-back / confirmation for a prior `transfer()` (issues #27, #47).
      * `get` reconciles once against chain truth; `wait` polls it to a terminal state
@@ -993,6 +1411,9 @@ var Playmos = class {
   }
   /** Connect the player's wallet and return their address. */
   async connect() {
+    if (this.config.mock) {
+      return "0x0000000000000000000000000000000000000001";
+    }
     return getAccount(resolveProvider(this.config.wallet));
   }
   /**
@@ -1009,18 +1430,30 @@ var Playmos = class {
       payEntry: async (req) => {
         const entry = await this.enterRound({
           gameId: cfg.gameId,
+          // Studio roundId for bookkeeping; pin roundKey separately for hasEntered.
           roundId: req.roundKey,
-          // the round the server verifies against
           roundKey: req.roundKey,
           identity: req.identity,
           amount: formatMicroToUsd(req.entryUnits),
           playerId: req.wallet
         });
-        const status = entry.status === "confirmed" ? "CONFIRMED" : entry.status === "failed" ? "FAILED" : "PENDING";
-        return { paymentId: entry.id, status, txHash: entry.txHash, onchain: true, identity: entry.identity };
+        const raw = String(entry.status ?? "pending").toLowerCase();
+        const status = raw === "confirmed" ? "confirmed" : raw === "failed" ? "failed" : "pending";
+        const onchain = !entry.mock;
+        return {
+          paymentId: entry.id,
+          status,
+          ...entry.txHash ? { txHash: entry.txHash } : {},
+          onchain,
+          identity: entry.identity ?? req.identity
+        };
       }
     };
   }
+  rememberMock(payment) {
+    if (payment.mock) this.mockPayments.set(payment.id, payment);
+    return payment;
+  }
   /** External-studio IAP (1%). Returns a real confirmed Payment with a txHash. */
   async pay(input) {
     const amountMicro = validateAmount(input.amount);
@@ -1029,14 +1462,16 @@ var Playmos = class {
     const metadata = validateMetadata(input.metadata);
     const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
     if (this.config.mock) {
-      return mockIapPayment({
-        amountMicro,
-        feeBps: IAP_FEE_BPS,
-        sku: input.sku,
-        playerId: input.playerId,
-        chain: this.env.network,
-        metadata
-      });
+      return this.rememberMock(
+        mockIapPayment({
+          amountMicro,
+          feeBps: IAP_FEE_BPS,
+          sku: input.sku,
+          playerId: input.playerId,
+          chain: this.env.network,
+          metadata
+        })
+      );
     }
     if (this.env.isTest && !await walletAvailable(this.config.wallet)) {
       const res = await this.http.post(
@@ -1079,17 +1514,22 @@ var Playmos = class {
     const metadata = validateMetadata(input.metadata);
     const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
     if (this.config.mock) {
-      return mockEntryPayment({
-        amountMicro,
-        poolBps: POOL_BPS,
-        seedBps: SEED_BPS,
-        rakeBps: RAKE_BPS,
-        gameId: input.gameId,
-        roundId: input.roundId,
-        playerId: input.playerId,
-        chain: this.env.network,
-        metadata
-      });
+      return this.rememberMock(
+        mockEntryPayment({
+          amountMicro,
+          poolBps: POOL_BPS,
+          seedBps: SEED_BPS,
+          rakeBps: RAKE_BPS,
+          gameId: input.gameId,
+          roundId: input.roundId,
+          playerId: input.playerId,
+          chain: this.env.network,
+          metadata,
+          // B2 pins — must survive mock path for hub hasEntered parity (#204).
+          roundKey: input.roundKey,
+          identity: input.identity
+        })
+      );
     }
     if (this.env.isTest && !await walletAvailable(this.config.wallet)) {
       const res = await this.http.post(
@@ -1101,7 +1541,7 @@ var Playmos = class {
       if (input.identity) payment2.identity = input.identity;
       const pool = res.clientParams?.contractAddress ?? this.config.contracts?.prizePool;
       if (pool) payment2.prizePoolAddress = pool.toLowerCase();
-      payment2.roundKey = res.clientParams?.roundKey ?? res.clientParams?.roundId ?? payment2.roundId ?? input.roundId;
+      payment2.roundKey = res.clientParams?.roundKey ?? input.roundKey ?? res.clientParams?.roundId ?? payment2.roundId ?? input.roundId;
       return payment2;
     }
     const intent = await this.http.post(
@@ -1196,9 +1636,41 @@ var Playmos = class {
   /** Verify a payment by the service's on-chain read (spec §6.1). Idempotent. */
   async verify(paymentId) {
     requireField(paymentId, "paymentId");
+    if (this.config.mock) {
+      const cached = this.mockPayments.get(paymentId);
+      if (!cached) {
+        throw new ApiError(`payment not found: ${paymentId}`, { status: 404, code: "not_found" });
+      }
+      const m = mockVerifyResult(cached);
+      return {
+        id: m.id,
+        status: m.status,
+        amount: m.amount,
+        fee: m.fee,
+        net: m.net,
+        txHash: m.txHash,
+        playerId: m.playerId ?? "",
+        sku: m.sku,
+        roundId: m.roundId,
+        chain: m.chain,
+        verifiedVia: "cache"
+      };
+    }
     return this.http.get(`/payments/${encodeURIComponent(paymentId)}`);
   }
   // ---- internals ---------------------------------------------------------
+  /**
+   * x402 V1 is Base Sepolia + test keys only (ADR D5). Fail closed before any
+   * network call so mainnet / live keys never silently hit the adapter.
+   */
+  assertX402Allowed() {
+    if (!this.env.isTest || this.env.network !== "base-sepolia") {
+      throw new ConfigError(
+        'playmos.x402 is Base Sepolia / test-key only in V1 (ADR D5). Use apiKey sk_test_\u2026 and network "base-sepolia".',
+        { network: this.env.network, isTest: this.env.isTest }
+      );
+    }
+  }
   /**
    * Map a server-settled payment (from the `settle: "server"` response) into the
    * SDK's `Payment` shape. The service already signed + confirmed on-chain, so we
@@ -1379,10 +1851,10 @@ var PayoutError = class extends Error {
     this.name = "PayoutError";
   }
 };
-var ADDRESS_RE2 = /^0x[0-9a-fA-F]{40}$/;
+var ADDRESS_RE3 = /^0x[0-9a-fA-F]{40}$/;
 var BPS = 10000n;
-function requireAddress(w, i) {
-  if (!ADDRESS_RE2.test(w)) {
+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();
@@ -1405,7 +1877,7 @@ function computePayout(pool, ranking, rule) {
   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 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}`);
@@ -1478,13 +1950,13 @@ function computePayout(pool, ranking, rule) {
 }
 
 // src/settlement.ts
-var ADDRESS_RE3 = /^0x[0-9a-fA-F]{40}$/;
+var ADDRESS_RE4 = /^0x[0-9a-fA-F]{40}$/;
 var DEFAULT_TTL_MS = 15 * 60 * 1e3;
-function requireAddress2(value, field) {
+function requireAddress3(value, field) {
   if (typeof value !== "string" || value.trim() === "") {
     throw new MissingFieldError(field);
   }
-  if (!ADDRESS_RE3.test(value)) {
+  if (!ADDRESS_RE4.test(value)) {
     throw new ConfigError(`${field} must be a 0x-prefixed 20-byte address, got: ${JSON.stringify(value)}`, {
       field,
       value
@@ -1501,7 +1973,7 @@ function requireNetwork(value) {
 }
 function createPaymentRequirement(input) {
   const now = (input.now ?? (() => /* @__PURE__ */ new Date()))();
-  const payTo = requireAddress2(input.payTo, "payTo");
+  const payTo = requireAddress3(input.payTo, "payTo");
   const network = requireNetwork(input.network);
   const asset = input.asset ?? "USDC";
   if (asset !== "USDC") {
@@ -1544,7 +2016,7 @@ function parsePaymentRequirement(input) {
       asset: o.asset
     });
   }
-  const payTo = requireAddress2(o.payTo, "payTo");
+  const payTo = requireAddress3(o.payTo, "payTo");
   const network = requireNetwork(o.network);
   if (typeof o.amount !== "string") throw new InvalidAmountError(o.amount);
   parseUsdToMicro(o.amount);
@@ -1570,6 +2042,6 @@ function isX402PayloadAuthorization(auth) {
   return auth.kind === "x402-payload";
 }
 
-export { CHAIN_ID, DEFAULT_API_BASE_URL, MICRO_PER_USDC, PayoutError, Playmos, USDC_ADDRESS, USDC_DECIMALS, computeIapSplit, computePayout, computePoolSplit, createPaymentRequirement, formatMicroToUsd, isWalletSignatureAuthorization, isX402PayloadAuthorization, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, serializePaymentRequirement, ulid };
+export { CHAIN_ID, DEFAULT_API_BASE_URL, MICRO_PER_USDC, PayoutError, Playmos, USDC_ADDRESS, USDC_DECIMALS, computeIapSplit, computePayout, computePoolSplit, createPaymentRequirement, createX402Challenge, decodePaymentHeader, encodePaymentHeader, formatMicroToUsd, isWalletSignatureAuthorization, isX402PayloadAuthorization, networkToCaip2, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, serializePaymentRequirement, toX402PaymentRequired, ulid, validateX402ChallengeInput };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map