@playmos/sdk 0.3.0 → 0.3.2

package/dist/index.cjs

@@ -2,6 +2,8 @@
 
 var viem = require('viem');
 
+// src/client.ts
+
 // src/errors.ts
 var PlaymosError = class extends Error {
   constructor(code, message, detail) {
@@ -60,6 +62,15 @@ var ConfigError = class extends PlaymosError {
     super("config", message, detail);
   }
 };
+var NothingToWithdrawError = class extends PlaymosError {
+  constructor(detail) {
+    super(
+      "nothing_to_withdraw",
+      "Nothing to withdraw \u2014 this wallet has no credited prize balance on this PrizePool (round not settled for them, or already claimed).",
+      detail
+    );
+  }
+};
 
 // src/config.ts
 var CHAIN_ID = {
@@ -264,15 +275,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();
@@ -287,9 +319,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") {
@@ -305,7 +341,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,6 +498,13 @@ var prizePoolAbi = [
     ],
     outputs: [{ type: "bool" }]
   },
+  {
+    type: "function",
+    name: "withdrawable",
+    stateMutability: "view",
+    inputs: [{ name: "account", type: "address" }],
+    outputs: [{ type: "uint256" }]
+  },
   {
     type: "function",
     name: "withdraw",
@@ -514,7 +557,23 @@ async function waitForCalls(provider, id, timeoutMs = 6e4) {
 function encodeApprove(spender, amountUnits) {
   return viem.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"] });
@@ -522,8 +581,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) => viem.keccak256(viem.toBytes(s));
@@ -549,6 +611,14 @@ function buildEntryCalls(args) {
     { to: args.prizePool, data: enterData }
   ];
 }
+function buildWithdrawCall(prizePool) {
+  const data = viem.encodeFunctionData({
+    abi: prizePoolAbi,
+    functionName: "withdraw",
+    args: []
+  });
+  return { to: prizePool, data };
+}
 
 // src/mock.ts
 var MOCK_TX = "0x000000000000000000000000000000000000000000000000000000000000mock";
@@ -577,6 +647,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",
@@ -593,6 +664,10 @@ function mockEntryPayment(args) {
     },
     gameId: args.gameId,
     roundId: args.roundId,
+    roundKey,
+    identity: args.identity,
+    // Deterministic mock pool address so claim-flow unit tests can assert shape (#41).
+    prizePoolAddress: "0x0000000000000000000000000000000000000001",
     playerId: args.playerId,
     txHash: MOCK_TX,
     chain: args.chain,
@@ -601,14 +676,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 }
@@ -653,6 +874,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.
      *
@@ -705,6 +1042,112 @@ var Playmos = class {
           `/rounds/${encodeURIComponent(input.roundId)}`
         );
         return round;
+      },
+      /**
+       * Read a wallet's **claimable** prize balance for a round (issue #41).
+       * Prefers the service chain read (`GET /v1/rounds/:id/prize?wallet=`); falls
+       * back to a direct eth_call when `prizePoolAddress` is supplied and no wallet
+       * connector is needed for the read path… actually uses service first, then
+       * on-chain via the player's provider if the service is unavailable.
+       */
+      prize: async (input) => {
+        requireField(input?.roundId, "roundId");
+        const wallet = requireAddressField(input?.wallet, "wallet");
+        try {
+          const res = await this.http.get(
+            `/rounds/${encodeURIComponent(input.roundId)}/prize?wallet=${encodeURIComponent(wallet)}`
+          );
+          return res.prize;
+        } catch (e) {
+          if (!input.prizePoolAddress && !(e instanceof ApiError)) throw e;
+          if (!input.prizePoolAddress) throw e;
+        }
+        const prizePoolAddress = requireAddressField(input.prizePoolAddress, "prizePoolAddress");
+        const claimableMicro = await this.readWithdrawable(prizePoolAddress, wallet);
+        return {
+          roundId: input.roundId,
+          prizePoolAddress,
+          wallet,
+          claimable: formatMicroToUsd(claimableMicro),
+          claimableMicro: claimableMicro.toString()
+        };
+      },
+      /**
+       * Winner **claim** — call PrizePool.withdraw() from the player's wallet (issue #41).
+       * Pull-payment: credits from settle live in `withdrawable[msg.sender]`. No approve needed.
+       * Pass either `prizePoolAddress` (from enterRound / rounds.get) or `roundId` (service resolves).
+       */
+      withdraw: async (input) => {
+        if (this.config.mock) {
+          return {
+            prizePoolAddress: input.prizePoolAddress ?? "0x0000000000000000000000000000000000000001",
+            amount: "0.00",
+            amountMicro: "0",
+            txHash: "0x000000000000000000000000000000000000000000000000000000000000mock",
+            status: "confirmed"
+          };
+        }
+        let prizePool = input.prizePoolAddress ? requireAddressField(input.prizePoolAddress, "prizePoolAddress") : void 0;
+        if (!prizePool) {
+          requireField(input?.roundId, "roundId");
+          const round = await this.rounds.get({ roundId: input.roundId });
+          if (!round.prizePoolAddress) {
+            throw new ConfigError(
+              "rounds.get did not return prizePoolAddress \u2014 pass prizePoolAddress from enterRound or configure contracts.prizePool"
+            );
+          }
+          prizePool = round.prizePoolAddress;
+        }
+        const provider = resolveProvider(this.config.wallet);
+        if (this.config.gas?.mode === "player") {
+          const from0 = await getAccount(provider);
+          await assertEnoughGas(provider, from0);
+        }
+        const from = await getAccount(provider);
+        let amountMicro = 0n;
+        if (input.checkBalance !== false) {
+          amountMicro = await this.readWithdrawable(prizePool, from);
+          if (amountMicro === 0n) {
+            throw new NothingToWithdrawError({ prizePoolAddress: prizePool, wallet: from });
+          }
+        }
+        const call = buildWithdrawCall(prizePool);
+        const paymasterUrl = this.config.gas?.mode === "sponsored" ? this.config.gas.paymasterUrl : void 0;
+        let txHash;
+        let status = "pending";
+        try {
+          const { id: callsId } = await sendCalls(
+            provider,
+            from,
+            this.env.chainId,
+            [call],
+            paymasterUrl
+          );
+          const waited = await waitForCalls(provider, callsId);
+          txHash = waited.txHash;
+          status = waited.status === "CONFIRMED" ? "confirmed" : waited.status === "FAILED" ? "failed" : "pending";
+        } catch (e) {
+          const msg = e?.message ?? String(e);
+          if (/NothingToWithdraw|nothing to withdraw/i.test(msg)) {
+            throw new NothingToWithdrawError({ prizePoolAddress: prizePool, wallet: from, cause: msg });
+          }
+          if (e instanceof NothingToWithdrawError || e instanceof PaymentFailedError) throw e;
+          throw new PaymentFailedError("PrizePool.withdraw() failed.", { cause: msg });
+        }
+        if (status === "failed") {
+          throw new PaymentFailedError("PrizePool.withdraw() did not confirm on-chain.", {
+            prizePoolAddress: prizePool,
+            txHash
+          });
+        }
+        if (amountMicro === 0n && input.checkBalance === false) ;
+        return {
+          prizePoolAddress: prizePool,
+          amount: formatMicroToUsd(amountMicro),
+          amountMicro: amountMicro.toString(),
+          txHash,
+          status
+        };
       }
     };
     /**
@@ -879,6 +1322,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
@@ -928,6 +1376,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));
   }
   /**
@@ -944,18 +1395,29 @@ 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 onchain = !entry.mock;
+        return {
+          paymentId: entry.id,
+          status,
+          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);
@@ -964,14 +1426,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(
@@ -1014,17 +1478,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(
@@ -1034,6 +1503,9 @@ var Playmos = class {
       );
       const payment2 = this.mapServerPayment(res.payment, "entry", amountMicro);
       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 ?? input.roundKey ?? res.clientParams?.roundId ?? payment2.roundId ?? input.roundId;
       return payment2;
     }
     const intent = await this.http.post(
@@ -1061,6 +1533,8 @@ var Playmos = class {
     const { txHash } = await waitForCalls(provider, callsId);
     const payment = await this.settle(intent.payment.id, txHash);
     payment.identity = identity;
+    payment.prizePoolAddress = prizePool.toLowerCase();
+    payment.roundKey = roundKey;
     return payment;
   }
   /**
@@ -1126,9 +1600,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
@@ -1170,6 +1676,58 @@ var Playmos = class {
     const fromServer = intent.clientParams?.amountUnits ?? intent.clientParams?.amountMicro;
     return fromServer ? BigInt(fromServer) : local;
   }
+  /**
+   * Read PrizePool.withdrawable[wallet] via eth_call (issue #41).
+   * Uses the wallet provider when present; otherwise a public Base Sepolia RPC in test.
+   */
+  async readWithdrawable(prizePool, wallet) {
+    const data = viem.encodeFunctionData({
+      abi: prizePoolAbi,
+      functionName: "withdrawable",
+      args: [wallet]
+    });
+    let raw;
+    try {
+      if (await walletAvailable(this.config.wallet)) {
+        const provider = resolveProvider(this.config.wallet);
+        raw = await provider.request({
+          method: "eth_call",
+          params: [{ to: prizePool, data }, "latest"]
+        });
+      } else {
+        const rpc = this.env.network === "base" ? "https://mainnet.base.org" : "https://sepolia.base.org";
+        const res = await fetch(rpc, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "eth_call",
+            params: [{ to: prizePool, data }, "latest"]
+          })
+        });
+        const json = await res.json();
+        if (!json.result) {
+          throw new ApiError(
+            `eth_call withdrawable failed: ${json.error?.message ?? "no result"}`,
+            { prizePool, wallet }
+          );
+        }
+        raw = json.result;
+      }
+    } catch (e) {
+      if (e instanceof ApiError) throw e;
+      throw new ApiError(`Could not read withdrawable balance: ${e.message}`, {
+        prizePool,
+        wallet
+      });
+    }
+    return viem.decodeFunctionResult({
+      abi: prizePoolAbi,
+      functionName: "withdrawable",
+      data: raw
+    });
+  }
   sponsorUrl(intent) {
     if (this.config.gas?.mode === "player") return void 0;
     return this.config.gas?.paymasterUrl ?? intent.clientParams?.paymasterUrl;
@@ -1257,10 +1815,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();
@@ -1283,7 +1841,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}`);
@@ -1356,13 +1914,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
@@ -1379,7 +1937,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") {
@@ -1422,7 +1980,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);
@@ -1457,6 +2015,7 @@ exports.InsufficientGasError = InsufficientGasError;
 exports.InvalidAmountError = InvalidAmountError;
 exports.MICRO_PER_USDC = MICRO_PER_USDC;
 exports.MissingFieldError = MissingFieldError;
+exports.NothingToWithdrawError = NothingToWithdrawError;
 exports.PaymentFailedError = PaymentFailedError;
 exports.PayoutError = PayoutError;
 exports.Playmos = Playmos;
@@ -1468,9 +2027,13 @@ exports.computeIapSplit = computeIapSplit;
 exports.computePayout = computePayout;
 exports.computePoolSplit = computePoolSplit;
 exports.createPaymentRequirement = createPaymentRequirement;
+exports.createX402Challenge = createX402Challenge;
+exports.decodePaymentHeader = decodePaymentHeader;
+exports.encodePaymentHeader = encodePaymentHeader;
 exports.formatMicroToUsd = formatMicroToUsd;
 exports.isWalletSignatureAuthorization = isWalletSignatureAuthorization;
 exports.isX402PayloadAuthorization = isX402PayloadAuthorization;
+exports.networkToCaip2 = networkToCaip2;
 exports.parsePaymentRequirement = parsePaymentRequirement;
 exports.parseUsdToMicro = parseUsdToMicro;
 exports.prefixedId = prefixedId;
@@ -1480,6 +2043,8 @@ exports.previewMarketplaceSplit = previewMarketplaceSplit;
 exports.previewPoolSplit = previewPoolSplit;
 exports.previewTransferSplit = previewTransferSplit;
 exports.serializePaymentRequirement = serializePaymentRequirement;
+exports.toX402PaymentRequired = toX402PaymentRequired;
 exports.ulid = ulid;
+exports.validateX402ChallengeInput = validateX402ChallengeInput;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map