@playmos/sdk 0.3.9 → 0.3.11

package/dist/{errors-BMlWHsMb.d.ts → errors-Dpeesyop.d.ts}

@@ -24,11 +24,19 @@ interface GasConfig {
     paymasterUrl?: string;
 }
 interface WalletConfig {
+    /**
+     * Which connector name to use when {@link WalletConfig.provider} is omitted.
+     * - `"injected"` — requires `globalThis.ethereum` (wallet browser / extension).
+     * - `"base-account"` (default) — **not** a built-in Base Account package inside
+     *   `@playmos/sdk`. Resolution: use injected ethereum if present; otherwise you
+     *   must install `@base-org/account` yourself, construct a provider, and pass
+     *   it as `wallet.provider` (sdk#512). No hard dependency on `@base-org/account`.
+     */
     connector?: WalletConnector;
     /**
-     * Pre-built EIP-1193 provider. If omitted, `injected` uses globalThis.ethereum
-     * and `base-account` expects a provider supplied by the Base Account SDK host.
-     * A raw provider is still **timeout-wrapped** on resolve (#462) — not a no-op passthrough.
+     * Pre-built EIP-1193 provider (host-owned). Always preferred when set.
+     * For Base Account / passkey hosts: construct with `@base-org/account` (or the
+     * Base App injection) and pass it here. Still **timeout-wrapped** on resolve (#462).
      */
     provider?: Eip1193Provider;
 }
@@ -129,6 +137,10 @@ interface PayInput {
     sku: string;
     /** Your opaque user id. */
     playerId: string;
+    /** sdk#508 — max wait for server-settle poll (ms). Default 60_000. */
+    settleTimeoutMs?: number;
+    /** sdk#508 — abort server-settle polling. */
+    signal?: AbortSignal;
     /**
      * The game this IAP belongs to. Optional: when your API key maps to exactly
      * one game the service resolves it for you (the quickstart). Supply it
@@ -150,6 +162,13 @@ interface EnterRoundInput {
     amount: string;
     playerId: string;
     idempotencyKey?: string;
+    /**
+     * sdk#508 — max wait for server-settle poll (ms). Default 60_000.
+     * Only applies to no-wallet sandbox server-settle path.
+     */
+    settleTimeoutMs?: number;
+    /** sdk#508 — abort server-settle polling. */
+    signal?: AbortSignal;
     metadata?: Record<string, string>;
     /**
      * Exact on-chain round key for Path B / entryProvider (#201 / #204 / #210).
@@ -387,10 +406,31 @@ interface Payment {
     status: PaymentStatus;
     /** "iap" (1% external) or "entry" (60/30/10 prize-pool). */
     kind: "iap" | "entry";
+    /**
+     * Requested amount (USD string). For prize-pool **server-settle**, this may
+     * differ from what moved on chain — see {@link Payment.chainAmount} (sdk#507).
+     */
     amount: string;
     fee: string;
     net: string;
-    /** Present for prize-pool entries: the 60/30/10 breakdown in USD. */
+    /**
+     * On-chain entry amount (USD) when the service observed it (server-settle entry).
+     * PrizePool charges the **round open price**, not necessarily {@link Payment.amount}.
+     * Reconcile economics against this field (or a chain `getRound` read), not `amount` alone.
+     */
+    chainAmount?: string;
+    /** On-chain entry amount in micro-USDC (6 dp integer string), when known. */
+    chainAmountMicro?: string;
+    /**
+     * First-party **60/30/10 projection** (pool/seed/rake USD strings) for prize-pool
+     * entries — bookkeeping preview, **not** a chain-derived settlement observation
+     * (sdk#514). Numbers come from SDK constants (`POOL_BPS`/`SEED_BPS`/`RAKE_BPS`),
+     * not from reading the deployed pool’s constructor bps. On-chain, entry only
+     * takes the fee off the top; pool/seed split at **lock**; payable pot also
+     * includes inherited seedBank — so `split.pool` is **not** “what this round pays.”
+     * Reconcile money with {@link Payment.chainAmount} / pool `getRound`.
+     * Field name kept for compatibility (no rename in V1).
+     */
     split?: {
         pool: string;
         seed: string;
@@ -427,9 +467,17 @@ interface Payment {
 interface VerifyResult {
     id: string;
     status: PaymentStatus;
+    /** Requested amount (USD). May differ from {@link VerifyResult.chainAmount} on server-settle entry. */
     amount: string;
     fee: string;
     net: string;
+    /**
+     * On-chain settled entry amount (USD) when known — distinct from {@link VerifyResult.amount}
+     * (sdk#507 / Vault Pop DX-05b). Prefer this for pot/split economics on shared rounds.
+     */
+    chainAmount?: string;
+    /** On-chain settled entry amount in micro-USDC, when known. */
+    chainAmountMicro?: string;
     txHash?: `0x${string}`;
     playerId: string;
     sku?: string;
@@ -440,6 +488,8 @@ interface VerifyResult {
      *  service can never confirm on-chain. */
     verifiedVia?: "chain" | "cache" | "degraded";
     chainReads?: "enabled" | "degraded";
+    /** Echo of on-chain identity when the service returns it (server-settle). */
+    identity?: string;
 }
 type WebhookEventType = "payment.confirmed" | "payment.failed" | "payout.settled" | "refund.processed";
 interface WebhookEvent {
@@ -493,6 +543,19 @@ interface RoundOpenInput {
      */
     roundKey?: string;
 }
+/**
+ * Service GET /v1/rounds/:id read-path honesty (#497 / #501).
+ * Transport meta — not chain lifecycle. Prefer `rounds.getWithMeta` over stuffing onto RoundState.
+ */
+type RoundGetVia = "chain" | "cache" | "stale" | "unknown";
+/** Full GET round response including transport meta (#501 — Claude pick C / getWithMeta). */
+interface RoundGetResult {
+    round: RoundState;
+    /** Present on live service responses after #499. Omitted under `mock: true`. */
+    via?: RoundGetVia;
+    /** Present only when eth_call itself threw (#497 C1). */
+    chainReadFailed?: boolean;
+}
 interface RoundState {
     roundId: string;
     gameId: string;
@@ -715,4 +778,4 @@ declare class NothingToWithdrawError extends PlaymosError {
     constructor(detail?: Record<string, unknown>);
 }
 
-export { type RoundStatus as $, type ActiveSeriesRound as A, type Eip1193Provider as B, type CancelRoundResult as C, type GasMode as D, type EscrowHoldInput as E, InvalidAmountError as F, type GasConfig as G, type ListingStatus as H, InsufficientGasError as I, type MarketplaceItem as J, type MarketplaceSale as K, type Listing as L, type MarketplaceListInput as M, type Network as N, MissingFieldError as O, type PlaymosConfig as P, NothingToWithdrawError as Q, type RoundOpenInput as R, type SettleRoundResult as S, type TransferResult as T, PaymentFailedError as U, type VerifyResult as V, type WebhookEvent as W, type PaymentStatus as X, PlaymosError as Y, type PlaymosErrorCode as Z, type RetryOptions as _, type RoundState as a, type WalletConfig as a0, WalletConnectionError as a1, type WalletConnector as a2, WalletTimeoutError as a3, type WebhookEventType as a4, type RoundSettleInput as b, type RoundCancelInput as c, type PrizeBalance as d, type WithdrawResult as e, type AgentWallet as f, type AgentFundResult as g, type EscrowHoldResult as h, type EscrowResolveResult as i, type MarketplaceSaleResult as j, type MarketplaceGetResult as k, type PayInput as l, type Payment as m, type EnterRoundInput as n, type TransferReconcile as o, type WaitOptions as p, type TransferInput as q, type TransferConfirmOptions as r, type PayoutRule as s, type ActiveForSeriesResult as t, type AgentEconomyConfig as u, AlreadyEnteredError as v, ApiError as w, AuthError as x, ConfigError as y, type ContractConfig as z };
+export { type RetryOptions as $, type ActiveSeriesRound as A, type ContractConfig as B, type CancelRoundResult as C, type Eip1193Provider as D, type EscrowHoldInput as E, type GasMode as F, type GasConfig as G, InvalidAmountError as H, InsufficientGasError as I, type ListingStatus as J, type MarketplaceItem as K, type Listing as L, type MarketplaceListInput as M, type Network as N, type MarketplaceSale as O, type PlaymosConfig as P, MissingFieldError as Q, type RoundOpenInput as R, type SettleRoundResult as S, type TransferResult as T, NothingToWithdrawError as U, type VerifyResult as V, type WebhookEvent as W, PaymentFailedError as X, type PaymentStatus as Y, PlaymosError as Z, type PlaymosErrorCode as _, type RoundState as a, type RoundGetVia as a0, type RoundStatus as a1, type WalletConfig as a2, WalletConnectionError as a3, type WalletConnector as a4, WalletTimeoutError as a5, type WebhookEventType as a6, type RoundSettleInput as b, type RoundCancelInput as c, type RoundGetResult as d, type PrizeBalance as e, type WithdrawResult as f, type AgentWallet as g, type AgentFundResult as h, type EscrowHoldResult as i, type EscrowResolveResult as j, type MarketplaceSaleResult as k, type MarketplaceGetResult as l, type PayInput as m, type Payment as n, type EnterRoundInput as o, type TransferReconcile as p, type WaitOptions as q, type TransferInput as r, type TransferConfirmOptions as s, type PayoutRule as t, type ActiveForSeriesResult as u, type AgentEconomyConfig as v, AlreadyEnteredError as w, ApiError as x, AuthError as y, ConfigError as z };

package/dist/index.cjs

@@ -267,10 +267,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}$/;
@@ -315,7 +315,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;
@@ -628,7 +629,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) {
@@ -1614,19 +1615,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**.
@@ -1731,19 +1747,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),
@@ -2015,8 +2038,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
@@ -2201,18 +2232,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,
@@ -2221,7 +2296,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())) {
@@ -2243,7 +2319,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;
     }
@@ -2288,8 +2370,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({
@@ -2305,7 +2401,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());
@@ -2338,7 +2435,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;
@@ -2521,10 +2624,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)}`
       );
@@ -2539,12 +2648,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 = {

package/dist/index.d.cts

@@ -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.cjs';
-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.cjs';
+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.cjs';
+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.cjs';
 
 /**
  * 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 };