@playmos/sdk 0.3.9 → 0.3.11

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { N as Network, P as PlaymosConfig, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, c as RoundCancelInput, C as CancelRoundResult, A as ActiveSeriesRound, d as PrizeBalance, e as WithdrawResult, f as AgentWallet, g as AgentFundResult, T as TransferResult, E as EscrowHoldInput, h as EscrowHoldResult, i as EscrowResolveResult, M as MarketplaceListInput, L as Listing, j as MarketplaceSaleResult, k as MarketplaceGetResult, l as PayInput, m as Payment, n as EnterRoundInput, o as TransferReconcile, p as WaitOptions, q as TransferInput, r as TransferConfirmOptions, V as VerifyResult, s as PayoutRule } from './errors-BMlWHsMb.js';
-export { t as ActiveForSeriesResult, u as AgentEconomyConfig, v as AlreadyEnteredError, w as ApiError, x as AuthError, y as ConfigError, z as ContractConfig, B as Eip1193Provider, G as GasConfig, D as GasMode, I as InsufficientGasError, F as InvalidAmountError, H as ListingStatus, J as MarketplaceItem, K as MarketplaceSale, O as MissingFieldError, Q as NothingToWithdrawError, U as PaymentFailedError, X as PaymentStatus, Y as PlaymosError, Z as PlaymosErrorCode, _ as RetryOptions, $ as RoundStatus, a0 as WalletConfig, a1 as WalletConnectionError, a2 as WalletConnector, a3 as WalletTimeoutError, a4 as WebhookEventType } from './errors-BMlWHsMb.js';
+import { N as Network, P as PlaymosConfig, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, c as RoundCancelInput, C as CancelRoundResult, d as RoundGetResult, A as ActiveSeriesRound, e as PrizeBalance, f as WithdrawResult, g as AgentWallet, h as AgentFundResult, T as TransferResult, E as EscrowHoldInput, i as EscrowHoldResult, j as EscrowResolveResult, M as MarketplaceListInput, L as Listing, k as MarketplaceSaleResult, l as MarketplaceGetResult, m as PayInput, n as Payment, o as EnterRoundInput, p as TransferReconcile, q as WaitOptions, r as TransferInput, s as TransferConfirmOptions, V as VerifyResult, t as PayoutRule } from './errors-Dpeesyop.js';
+export { u as ActiveForSeriesResult, v as AgentEconomyConfig, w as AlreadyEnteredError, x as ApiError, y as AuthError, z as ConfigError, B as ContractConfig, D as Eip1193Provider, G as GasConfig, F as GasMode, I as InsufficientGasError, H as InvalidAmountError, J as ListingStatus, K as MarketplaceItem, O as MarketplaceSale, Q as MissingFieldError, U as NothingToWithdrawError, X as PaymentFailedError, Y as PaymentStatus, Z as PlaymosError, _ as PlaymosErrorCode, $ as RetryOptions, a0 as RoundGetVia, a1 as RoundStatus, a2 as WalletConfig, a3 as WalletConnectionError, a4 as WalletConnector, a5 as WalletTimeoutError, a6 as WebhookEventType } from './errors-Dpeesyop.js';
 
 /**
  * Environment resolution + the canonical address book.
@@ -518,9 +518,22 @@ declare class Playmos {
          * if still pending — never invents terminal success).
          */
         cancel: (input: RoundCancelInput) => Promise<CancelRoundResult>;
+        /**
+         * Round state only (stable). Prefer {@link getWithMeta} when you need service
+         * read-path honesty (`via` / `chainReadFailed` — #497 / #501).
+         */
         get: (input: {
             roundId: string;
         }) => Promise<RoundState>;
+        /**
+         * Round state + transport meta from GET /v1/rounds/:id (#501).
+         * Does **not** attach `via` onto RoundState (Claude rejected option B — hub would
+         * silently pick it up and leak into settle/cancel paths that call get()).
+         * Under `mock: true`, meta fields are **omitted** (no eth_call; do not invent "cache").
+         */
+        getWithMeta: (input: {
+            roundId: string;
+        }) => Promise<RoundGetResult>;
         /**
          * Authoritative series latch (#351) — `null` means **proven free**.
          * `GET /v1/series/:seriesKey/active?gameId=…` — not a candidate probe.
@@ -550,6 +563,11 @@ declare class Playmos {
         withdraw: (input: {
             prizePoolAddress?: `0x${string}`;
             roundId?: string;
+            /**
+             * Winner wallet (0x…). **Required under mock** (#495 Claude) — live path uses the
+             * connected provider. Without this, mock paid the first non-zero credit to anyone.
+             */
+            wallet?: string;
             /** Pre-check claimable; default true. Set false only if you already called `prize()`. */
             checkBalance?: boolean;
         }) => Promise<WithdrawResult>;
@@ -637,8 +655,16 @@ declare class Playmos {
     /**
      * Offline mock payments for this client instance — so `verify(id)` after
      * `mock: true` pay/enterRound does not hit the live API (#204).
+     * Keyed by payment id for verify.
      */
     private readonly mockPayments;
+    /**
+     * sdk#513 / residual B1–B2 — held idempotencyKey offline (live contract rehearsal).
+     * Keyed like service: `${gameId}:${key}` (IAP without gameId uses empty gameId).
+     * Stores terms so same key + different money throws (live IdempotencyConflict), not silent replay.
+     * Auto-minted keys still unique per call (not stored for cross-call replay).
+     */
+    private readonly mockByIdempotencyKey;
     constructor(config: PlaymosConfig);
     /**
      * Wallet timeout policy (#462 / PR #463 residual).
@@ -677,7 +703,10 @@ declare class Playmos {
             identity?: string;
         }>;
     };
+    private mockIdemScopeKey;
     private rememberMock;
+    /** Live-shaped conflict when held mock key is reused with different money terms (sdk#513 residual B1). */
+    private mockIdemReplayOrThrow;
     /** External-studio IAP (1%). Returns a real confirmed Payment with a txHash. */
     pay(input: PayInput): Promise<Payment>;
     /** Playmos-owned skill-game entry (10%, 60/30/10 prize pool). Closes #343. */
@@ -741,12 +770,22 @@ declare class Playmos {
      *   the documented "confirmed" sandbox promise (TTFSC-T0 / cold-run).
      */
     private waitForServerSettle;
+    /**
+     * sdk#509 — recover a payment after a lost response by the idempotency key you held.
+     * Requires secret sk_test_ (same as list). Returns null if not found.
+     */
+    findPaymentByIdempotencyKey(idempotencyKey: string, opts?: {
+        gameId?: string;
+    }): Promise<Payment | null>;
     /**
      * 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
-     * pass its authoritative `status`/`txHash`/amounts straight through and, for an
-     * entry, derive the 60/30/10 USD `split` locally (exactly as the mock + the
-     * contract compute it) from the parsed amount.
+     * pass its authoritative `status`/`txHash`/amounts straight through.
+     *
+     * For entry, `Payment.split` is a **first-party 60/30/10 projection** from the
+     * request amount using SDK BPS constants (same integer math as mock) — not a
+     * chain read of pool constructor bps or post-lock payable pot (sdk#514 residual N1).
+     * Prefer `chainAmount` / on-chain `getRound` for money truth.
      */
     private mapServerPayment;
     /** Prefer the service's authoritative micro-USDC amount; fall back to the
@@ -820,8 +859,8 @@ declare function previewPoolSplit(amount: string): {
  */
 
 declare class PayoutError extends Error {
-    code: "payout_invalid";
-    constructor(message: string);
+    code: string;
+    constructor(message: string, code?: string);
 }
 /**
  * Apply the studio's payout rule to a payable pool and ranking (best-first).
@@ -890,4 +929,4 @@ declare function ulid(seedTime?: number): string;
 /** `${prefix}_${ulid()}` — e.g. `pay_01J…`, `entry_01J…`, `idem_01J…`. */
 declare function prefixedId(prefix: string): string;
 
-export { ActiveSeriesRound, AgentFundResult, AgentWallet, type Authorization, CHAIN_ID, CancelRoundResult, type CreatePaymentRequirementInput, DEFAULT_API_BASE_URL, EnterRoundInput, EscrowHoldInput, EscrowHoldResult, EscrowResolveResult, Listing, MICRO_PER_USDC, MarketplaceGetResult, MarketplaceListInput, MarketplaceSaleResult, Network, PayInput, Payment, type PaymentRequirement, PayoutError, PayoutRule, PayoutRule as PayoutRuleCompute, Playmos, PlaymosConfig, PrizeBalance, RoundCancelInput, RoundOpenInput, RoundSettleInput, RoundState, SettleRoundResult, type SettlementAsset, TransferConfirmOptions, TransferInput, TransferReconcile, TransferResult, USDC_ADDRESS, USDC_DECIMALS, VerifyResult, WaitOptions, type WalletSignatureAuthorization, WebhookEvent, WithdrawResult, type X402ChallengeInput, type X402ChallengeResult, type X402FulfillAuthorization, type X402PayInput, type X402PayloadAuthorization, type X402PayloadMode, type X402PaymentRequired, type X402SettleResult, clientRuntimeSignals, computeIapSplit, computePayout, computePoolSplit, createPaymentRequirement, createX402Challenge, decodePaymentHeader, encodePaymentHeader, formatMicroToUsd, isClientRuntime, isWalletSignatureAuthorization, isX402PayloadAuthorization, networkToCaip2, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, resolveEnv, serializePaymentRequirement, toX402PaymentRequired, ulid, validateX402ChallengeInput };
+export { ActiveSeriesRound, AgentFundResult, AgentWallet, type Authorization, CHAIN_ID, CancelRoundResult, type CreatePaymentRequirementInput, DEFAULT_API_BASE_URL, EnterRoundInput, EscrowHoldInput, EscrowHoldResult, EscrowResolveResult, Listing, MICRO_PER_USDC, MarketplaceGetResult, MarketplaceListInput, MarketplaceSaleResult, Network, PayInput, Payment, type PaymentRequirement, PayoutError, PayoutRule, PayoutRule as PayoutRuleCompute, Playmos, PlaymosConfig, PrizeBalance, RoundCancelInput, RoundGetResult, RoundOpenInput, RoundSettleInput, RoundState, SettleRoundResult, type SettlementAsset, TransferConfirmOptions, TransferInput, TransferReconcile, TransferResult, USDC_ADDRESS, USDC_DECIMALS, VerifyResult, WaitOptions, type WalletSignatureAuthorization, WebhookEvent, WithdrawResult, type X402ChallengeInput, type X402ChallengeResult, type X402FulfillAuthorization, type X402PayInput, type X402PayloadAuthorization, type X402PayloadMode, type X402PaymentRequired, type X402SettleResult, clientRuntimeSignals, computeIapSplit, computePayout, computePoolSplit, createPaymentRequirement, createX402Challenge, decodePaymentHeader, encodePaymentHeader, formatMicroToUsd, isClientRuntime, isWalletSignatureAuthorization, isX402PayloadAuthorization, networkToCaip2, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, resolveEnv, serializePaymentRequirement, toX402PaymentRequired, ulid, validateX402ChallengeInput };

package/dist/index.js

@@ -1,6 +1,6 @@
-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';
+import { AuthError, InvalidAmountError, ConfigError, MissingFieldError, NothingToWithdrawError, assertEnoughGas, buildWithdrawCall, sendCalls, waitForCalls, WalletTimeoutError, PaymentFailedError, ApiError, buildIapCalls, buildEntryCalls, prizePoolAbi, WalletConnectionError, AlreadyEnteredError } from './chunk-35WJANW4.js';
+export { AlreadyEnteredError, ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError, WalletTimeoutError } from './chunk-35WJANW4.js';
+import { encodeFunctionData, decodeFunctionResult } from 'viem';
 
 // src/config.ts
 var CHAIN_ID = {
@@ -183,10 +183,10 @@ function validateMetadata(metadata) {
 
 // src/payout.ts
 var PayoutError = class extends Error {
-  constructor(message) {
+  constructor(message, code = "payout_invalid") {
     super(message);
-    this.code = "payout_invalid";
     this.name = "PayoutError";
+    this.code = code;
   }
 };
 var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
@@ -231,7 +231,8 @@ function computePayout(pool, ranking, rule) {
     }
     if (splits.length > wallets.length) {
       throw new PayoutError(
-        `top-n needs ${splits.length} ranked wallets but ranking only has ${wallets.length}`
+        `ranking_too_short: a top-n rule cannot be settled from a ranking shorter than splitsBps.length (need ${splits.length}, got ${wallets.length}) \u2014 open with winner-take-all, or settle with explicit winners[{wallet,amount}]`,
+        "ranking_too_short"
       );
     }
     let sumBps = 0;
@@ -544,7 +545,7 @@ function resolveRawProvider(wallet) {
   }
   if (injected) return injected;
   throw new WalletConnectionError(
-    "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."
+    'base-account connector needs a provider \u2014 this is not a built-in Base Account/passkey flow in @playmos/sdk. In the Base App a provider is often injected; elsewhere install @base-org/account, construct a provider, and pass it as wallet.provider (or use connector: "injected" in a wallet browser).'
   );
 }
 function resolveProvider(wallet, opts) {
@@ -581,174 +582,6 @@ async function getAccount(provider) {
   }
 }
 
-// src/chain/abis.ts
-var erc20Abi = [
-  {
-    type: "function",
-    name: "approve",
-    stateMutability: "nonpayable",
-    inputs: [
-      { name: "spender", type: "address" },
-      { name: "amount", type: "uint256" }
-    ],
-    outputs: [{ type: "bool" }]
-  }
-];
-var playmosPayAbi = [
-  {
-    type: "function",
-    name: "pay",
-    stateMutability: "nonpayable",
-    inputs: [
-      { name: "paymentId", type: "bytes32" },
-      { name: "studio", type: "address" },
-      { name: "amount", type: "uint256" }
-    ],
-    outputs: []
-  }
-];
-var prizePoolAbi = [
-  {
-    type: "function",
-    name: "enter",
-    stateMutability: "nonpayable",
-    inputs: [
-      { name: "roundId", type: "bytes32" },
-      { name: "identity", type: "bytes32" }
-    ],
-    outputs: []
-  },
-  {
-    type: "function",
-    name: "withdrawable",
-    stateMutability: "view",
-    inputs: [{ name: "account", type: "address" }],
-    outputs: [{ type: "uint256" }]
-  },
-  {
-    type: "function",
-    name: "withdraw",
-    stateMutability: "nonpayable",
-    inputs: [],
-    outputs: [{ name: "amount", type: "uint256" }]
-  }
-];
-async function sendCalls(provider, from, chainId, calls, paymasterUrl) {
-  const params = {
-    version: "2.0.0",
-    from,
-    chainId: numberToHex(chainId),
-    atomicRequired: true,
-    calls
-  };
-  if (paymasterUrl) {
-    params.capabilities = { paymasterService: { url: paymasterUrl } };
-  }
-  let result;
-  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 });
-    }
-    throw new PaymentFailedError("wallet_sendCalls failed.", { cause: msg });
-  }
-  const id = typeof result === "string" ? result : result?.id ?? "";
-  if (!id) throw new PaymentFailedError("Wallet returned no calls id.");
-  return { id };
-}
-async function waitForCalls(provider, id, timeoutMs = 6e4) {
-  if (!id) return { status: "FAILED" };
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    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" };
-}
-function encodeApprove(spender, amountUnits) {
-  return encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: [spender, amountUnits] });
-}
-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"] });
-    balance = BigInt(hex);
-  } catch {
-    return;
-  }
-  if (balance < floor) {
-    throw new InsufficientGasError({
-      balanceWei: balance.toString(),
-      minWei: floor.toString()
-    });
-  }
-}
-var toBytes32 = (s) => keccak256(toBytes(s));
-function buildIapCalls(args) {
-  const payData = encodeFunctionData({
-    abi: playmosPayAbi,
-    functionName: "pay",
-    args: [toBytes32(args.paymentId), args.studio, args.amountUnits]
-  });
-  return [
-    { to: args.usdc, data: encodeApprove(args.playmosPay, args.amountUnits) },
-    { to: args.playmosPay, data: payData }
-  ];
-}
-function buildEntryCalls(args) {
-  const enterData = encodeFunctionData({
-    abi: prizePoolAbi,
-    functionName: "enter",
-    args: [toBytes32(args.roundKey), toBytes32(args.identity)]
-  });
-  return [
-    { to: args.usdc, data: encodeApprove(args.prizePool, args.amountUnits) },
-    { to: args.prizePool, data: enterData }
-  ];
-}
-function buildWithdrawCall(prizePool) {
-  const data = encodeFunctionData({
-    abi: prizePoolAbi,
-    functionName: "withdraw",
-    args: []
-  });
-  return { to: prizePool, data };
-}
-
 // src/mock.ts
 var MOCK_TX = `0x${"0".repeat(56)}deadbeef`;
 function mockIapPayment(args) {
@@ -1530,19 +1363,34 @@ var Playmos = class {
         }
         return { ...result, txHash: result.txHash ?? firstTx ?? null };
       },
+      /**
+       * Round state only (stable). Prefer {@link getWithMeta} when you need service
+       * read-path honesty (`via` / `chainReadFailed` — #497 / #501).
+       */
       get: async (input) => {
+        const meta = await this.rounds.getWithMeta(input);
+        return meta.round;
+      },
+      /**
+       * Round state + transport meta from GET /v1/rounds/:id (#501).
+       * Does **not** attach `via` onto RoundState (Claude rejected option B — hub would
+       * silently pick it up and leak into settle/cancel paths that call get()).
+       * Under `mock: true`, meta fields are **omitted** (no eth_call; do not invent "cache").
+       */
+      getWithMeta: 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;
+          return { round: existing };
         }
-        const { round } = await this.http.get(
-          `/rounds/${encodeURIComponent(input.roundId)}`
-        );
-        return round;
+        const body = await this.http.get(`/rounds/${encodeURIComponent(input.roundId)}`);
+        const out = { round: body.round };
+        if (body.via != null) out.via = body.via;
+        if (body.chainReadFailed === true) out.chainReadFailed = true;
+        return out;
       },
       /**
        * Authoritative series latch (#351) — `null` means **proven free**.
@@ -1647,19 +1495,26 @@ var Playmos = class {
        */
       withdraw: async (input) => {
         if (this.config.mock) {
-          let amountMicro2 = 0n;
           let prizePool2 = input.prizePoolAddress ?? "0x0000000000000000000000000000000000000001";
           if (input.roundId) {
             const existing = this.mockRounds.get(input.roundId);
             if (existing?.prizePoolAddress) prizePool2 = existing.prizePoolAddress;
-            for (const [k, v] of this.mockWithdrawable) {
-              if (k.startsWith(`${input.roundId}:`) && v > 0n) {
-                amountMicro2 = v;
-                this.mockWithdrawable.set(k, 0n);
-                break;
-              }
-            }
           }
+          if (!input.wallet || !ADDRESS_RE3.test(input.wallet)) {
+            throw new ConfigError(
+              "mock rounds.withdraw requires wallet (0x\u2026) \u2014 live uses the connected provider; without wallet mock would pay the first non-zero credit to the wrong player (#495)"
+            );
+          }
+          const wallet = input.wallet.toLowerCase();
+          if (!input.roundId) {
+            throw new ConfigError("mock rounds.withdraw requires roundId to locate claimable credits");
+          }
+          const key = `${input.roundId}:${wallet}`;
+          const amountMicro2 = this.mockWithdrawable.get(key) ?? 0n;
+          if (amountMicro2 === 0n) {
+            throw new NothingToWithdrawError({ prizePoolAddress: prizePool2, wallet });
+          }
+          this.mockWithdrawable.set(key, 0n);
           return {
             prizePoolAddress: prizePool2,
             amount: formatMicroToUsd(amountMicro2),
@@ -1931,8 +1786,16 @@ var Playmos = class {
     /**
      * Offline mock payments for this client instance — so `verify(id)` after
      * `mock: true` pay/enterRound does not hit the live API (#204).
+     * Keyed by payment id for verify.
      */
     this.mockPayments = /* @__PURE__ */ new Map();
+    /**
+     * sdk#513 / residual B1–B2 — held idempotencyKey offline (live contract rehearsal).
+     * Keyed like service: `${gameId}:${key}` (IAP without gameId uses empty gameId).
+     * Stores terms so same key + different money throws (live IdempotencyConflict), not silent replay.
+     * Auto-minted keys still unique per call (not stored for cross-call replay).
+     */
+    this.mockByIdempotencyKey = /* @__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
@@ -2117,18 +1980,62 @@ var Playmos = class {
       }
     };
   }
-  rememberMock(payment) {
-    if (payment.mock) this.mockPayments.set(payment.id, payment);
+  mockIdemScopeKey(gameId, heldKey) {
+    return `${gameId ?? ""}:${heldKey}`;
+  }
+  rememberMock(payment, held) {
+    if (payment.mock) {
+      this.mockPayments.set(payment.id, payment);
+      if (held) {
+        this.mockByIdempotencyKey.set(this.mockIdemScopeKey(held.terms.gameId, held.key), {
+          payment,
+          terms: held.terms
+        });
+      }
+    }
     return payment;
   }
+  /** Live-shaped conflict when held mock key is reused with different money terms (sdk#513 residual B1). */
+  mockIdemReplayOrThrow(heldKey, terms) {
+    const prior = this.mockByIdempotencyKey.get(this.mockIdemScopeKey(terms.gameId, heldKey));
+    if (!prior) return null;
+    const t = prior.terms;
+    const same = t.kind === terms.kind && t.amount === terms.amount && t.gameId === terms.gameId && t.playerId === terms.playerId && t.roundId === terms.roundId && t.identity === terms.identity && t.sku === terms.sku;
+    if (!same) {
+      throw new ApiError(
+        `idempotencyKey was already used for a payment with DIFFERENT terms (kind/amount/gameId/playerId/roundId/identity/sku); use a fresh key (mock:true mirrors live conflict \u2014 sdk#513).`,
+        {
+          code: "idempotency_conflict",
+          idempotencyKey: heldKey,
+          priorKind: t.kind,
+          priorAmount: t.amount
+        }
+      );
+    }
+    return prior.payment;
+  }
   /** External-studio IAP (1%). Returns a real confirmed Payment with a txHash. */
   async pay(input) {
     const amountMicro = validateAmount(input.amount);
     requireField(input.sku, "sku");
     requireField(input.playerId, "playerId");
     const metadata = validateMetadata(input.metadata);
-    const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
+    const heldIdem = typeof input.idempotencyKey === "string" && input.idempotencyKey.trim() ? input.idempotencyKey.trim() : void 0;
+    const idempotencyKey = heldIdem ?? prefixedId("idem");
     if (this.config.mock) {
+      const terms = {
+        kind: "iap",
+        amount: formatMicroToUsd(amountMicro),
+        gameId: input.gameId ?? "",
+        playerId: input.playerId,
+        roundId: "",
+        identity: "",
+        sku: input.sku.trim()
+      };
+      if (heldIdem) {
+        const replay = this.mockIdemReplayOrThrow(heldIdem, terms);
+        if (replay) return replay;
+      }
       return this.rememberMock(
         mockIapPayment({
           amountMicro,
@@ -2137,7 +2044,8 @@ var Playmos = class {
           playerId: input.playerId,
           chain: this.env.network,
           metadata
-        })
+        }),
+        heldIdem ? { key: heldIdem, terms } : void 0
       );
     }
     if (this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
@@ -2159,7 +2067,13 @@ var Playmos = class {
       );
       let payment = this.mapServerPayment(res.payment, "iap", amountMicro);
       if (payment.status === "pending" || payment.status === "created") {
-        payment = await this.waitForServerSettle(payment.id, "iap", amountMicro);
+        payment = await this.waitForServerSettle(
+          payment.id,
+          "iap",
+          amountMicro,
+          input.settleTimeoutMs ?? 6e4,
+          input.signal
+        );
       }
       return payment;
     }
@@ -2204,8 +2118,22 @@ var Playmos = class {
     requireField(input.roundId, "roundId");
     requireField(input.playerId, "playerId");
     const metadata = validateMetadata(input.metadata);
-    const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
+    const heldIdem = typeof input.idempotencyKey === "string" && input.idempotencyKey.trim() ? input.idempotencyKey.trim() : void 0;
+    const idempotencyKey = heldIdem ?? prefixedId("idem");
     if (this.config.mock) {
+      const terms = {
+        kind: "entry",
+        amount: formatMicroToUsd(amountMicro),
+        gameId: input.gameId,
+        playerId: input.playerId,
+        roundId: input.roundId,
+        identity: typeof input.identity === "string" ? input.identity.trim() : "",
+        sku: ""
+      };
+      if (heldIdem) {
+        const replay = this.mockIdemReplayOrThrow(heldIdem, terms);
+        if (replay) return replay;
+      }
       this.mockAccumulateEntry(input.roundId, amountMicro);
       return this.rememberMock(
         mockEntryPayment({
@@ -2221,7 +2149,8 @@ var Playmos = class {
           // B2 pins — must survive mock path for hub hasEntered parity (#204).
           roundKey: input.roundKey,
           identity: input.identity
-        })
+        }),
+        heldIdem ? { key: heldIdem, terms } : void 0
       );
     }
     const serverSettleNoWallet = this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy());
@@ -2254,7 +2183,13 @@ var Playmos = class {
       );
       let payment2 = this.mapServerPayment(res.payment, "entry", amountMicro);
       if (payment2.status === "pending" || payment2.status === "created") {
-        payment2 = await this.waitForServerSettle(payment2.id, "entry", amountMicro);
+        payment2 = await this.waitForServerSettle(
+          payment2.id,
+          "entry",
+          amountMicro,
+          input.settleTimeoutMs ?? 6e4,
+          input.signal
+        );
       }
       if (input.identity) payment2.identity = input.identity;
       const pool = res.clientParams?.contractAddress ?? this.config.contracts?.prizePool;
@@ -2437,10 +2372,16 @@ var Playmos = class {
    *   until chain verify catches PaymentSettled (RPC lag) — poll so pay() matches
    *   the documented "confirmed" sandbox promise (TTFSC-T0 / cold-run).
    */
-  async waitForServerSettle(paymentId, kind, amountMicro, timeoutMs = 6e4) {
+  async waitForServerSettle(paymentId, kind, amountMicro, timeoutMs = 6e4, signal) {
     const start = Date.now();
     let delayMs = 400;
     while (Date.now() - start < timeoutMs) {
+      if (signal?.aborted) {
+        throw new ApiError(
+          `Aborted waiting for server-settle of ${paymentId}. Re-check with playmos.verify("${paymentId}").`,
+          { paymentId, aborted: true, asyncSettle: true }
+        );
+      }
       const raw = await this.http.get(
         `/payments/${encodeURIComponent(paymentId)}`
       );
@@ -2455,12 +2396,46 @@ var Playmos = class {
       { paymentId, timeout: true, asyncSettle: true }
     );
   }
+  /**
+   * sdk#509 — recover a payment after a lost response by the idempotency key you held.
+   * Requires secret sk_test_ (same as list). Returns null if not found.
+   */
+  async findPaymentByIdempotencyKey(idempotencyKey, opts) {
+    requireField(idempotencyKey, "idempotencyKey");
+    if (this.config.mock) {
+      return null;
+    }
+    const q = new URLSearchParams({ idempotencyKey });
+    if (opts?.gameId) q.set("gameId", opts.gameId);
+    try {
+      const res = await this.http.get(
+        `/payments?${q.toString()}`
+      );
+      const row = res.data?.[0];
+      if (!row || typeof row.id !== "string") return null;
+      const kind = row.kind === "entry" ? "entry" : "iap";
+      const amountMicro = validateAmount(String(row.amount ?? "0.01"));
+      return this.mapServerPayment(
+        row,
+        kind,
+        amountMicro
+      );
+    } catch (e) {
+      if (e instanceof ApiError && (e.detail?.status === 404 || e.detail?.code === "not_found" || /not found/i.test(e.message))) {
+        return null;
+      }
+      throw e;
+    }
+  }
   /**
    * 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
-   * pass its authoritative `status`/`txHash`/amounts straight through and, for an
-   * entry, derive the 60/30/10 USD `split` locally (exactly as the mock + the
-   * contract compute it) from the parsed amount.
+   * pass its authoritative `status`/`txHash`/amounts straight through.
+   *
+   * For entry, `Payment.split` is a **first-party 60/30/10 projection** from the
+   * request amount using SDK BPS constants (same integer math as mock) — not a
+   * chain read of pool constructor bps or post-lock payable pot (sdk#514 residual N1).
+   * Prefer `chainAmount` / on-chain `getRound` for money truth.
    */
   mapServerPayment(p, kind, amountMicro) {
     const payment = {