@playmos/sdk 0.3.8 → 0.3.10

package/dist/{errors-BMlWHsMb.d.cts → errors-Chizbb96.d.cts}

@@ -493,6 +493,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 +728,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/{errors-BMlWHsMb.d.ts → errors-Chizbb96.d.ts}

@@ -493,6 +493,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 +728,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

@@ -265,6 +265,112 @@ function validateMetadata(metadata) {
   return out;
 }
 
+// src/payout.ts
+var PayoutError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.code = "payout_invalid";
+    this.name = "PayoutError";
+  }
+};
+var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+var BPS = 10000n;
+function requireAddress(w, i) {
+  if (!ADDRESS_RE.test(w)) {
+    throw new PayoutError(`ranking[${i}] must be a 0x-prefixed 20-byte address, got: ${JSON.stringify(w)}`);
+  }
+  return w.toLowerCase();
+}
+function parseUsdToMicroLoose(amount) {
+  if (typeof amount !== "string" || !/^\d+(\.\d{1,6})?$/.test(amount.trim())) {
+    throw new PayoutError(`invalid USD amount: ${JSON.stringify(amount)}`);
+  }
+  const [wholeRaw, frac = ""] = amount.trim().split(".");
+  const whole = wholeRaw ?? "0";
+  const fracPadded = (frac + "000000").slice(0, 6);
+  const micro = BigInt(whole) * 1000000n + BigInt(fracPadded);
+  if (micro <= 0n) throw new PayoutError(`amount must be > 0, got: ${JSON.stringify(amount)}`);
+  return micro;
+}
+function computePayout(pool, ranking, rule) {
+  if (typeof pool !== "bigint" || pool <= 0n) {
+    throw new PayoutError(`pool must be a positive bigint (micro-USDC), got: ${String(pool)}`);
+  }
+  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 seen = /* @__PURE__ */ new Set();
+  for (const w of wallets) {
+    if (seen.has(w)) throw new PayoutError(`duplicate wallet in ranking: ${w}`);
+    seen.add(w);
+  }
+  if (rule.kind === "winner-take-all") {
+    return [{ wallet: wallets[0], amount: pool }];
+  }
+  if (rule.kind === "top-n") {
+    const splits = rule.splitsBps;
+    if (!Array.isArray(splits) || splits.length === 0) {
+      throw new PayoutError("top-n splitsBps must be a non-empty array");
+    }
+    if (splits.length > wallets.length) {
+      throw new PayoutError(
+        `top-n needs ${splits.length} ranked wallets but ranking only has ${wallets.length}`
+      );
+    }
+    let sumBps = 0;
+    for (const b of splits) {
+      if (!Number.isInteger(b) || b <= 0 || b > 1e4) {
+        throw new PayoutError(`each splitsBps entry must be an integer in (0, 10000], got: ${b}`);
+      }
+      sumBps += b;
+    }
+    if (sumBps !== 1e4) {
+      throw new PayoutError(`splitsBps must sum to 10000, got ${sumBps}`);
+    }
+    const out = [];
+    let allocated = 0n;
+    for (let i = 0; i < splits.length; i++) {
+      const amt = pool * BigInt(splits[i]) / BPS;
+      out.push({ wallet: wallets[i], amount: amt });
+      allocated += amt;
+    }
+    const remainder = pool - allocated;
+    if (remainder < 0n) throw new PayoutError("internal: allocated more than pool");
+    out[0] = { wallet: out[0].wallet, amount: out[0].amount + remainder };
+    const filtered = out.filter((x) => x.amount > 0n);
+    if (filtered.length === 0) throw new PayoutError("payout produced no positive amounts");
+    const total = filtered.reduce((s, x) => s + x.amount, 0n);
+    if (total !== pool) throw new PayoutError(`internal: sum ${total} != pool ${pool}`);
+    return filtered;
+  }
+  if (rule.kind === "custom") {
+    const amounts = rule.amounts;
+    if (!Array.isArray(amounts) || amounts.length === 0) {
+      throw new PayoutError("custom amounts must be a non-empty array of USD strings");
+    }
+    if (amounts.length > wallets.length) {
+      throw new PayoutError(
+        `custom amounts has ${amounts.length} entries but ranking only has ${wallets.length}`
+      );
+    }
+    const out = [];
+    let total = 0n;
+    for (let i = 0; i < amounts.length; i++) {
+      const amt = parseUsdToMicroLoose(amounts[i]);
+      out.push({ wallet: wallets[i], amount: amt });
+      total += amt;
+    }
+    if (total !== pool) {
+      throw new PayoutError(
+        `custom amounts sum to ${total} micro-USDC but pool is ${pool} \u2014 must match exactly`
+      );
+    }
+    return out;
+  }
+  throw new PayoutError(`unknown payout rule kind: ${JSON.stringify(rule.kind)}`);
+}
+
 // src/http.ts
 function resolveRetry(retry) {
   const off = { maxRetries: 0, baseDelayMs: 500, maxDelayMs: 2e4 };
@@ -788,12 +894,12 @@ function mockVerifyResult(payment) {
 }
 
 // src/x402.ts
-var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
-function requireAddress(value, field) {
+var ADDRESS_RE2 = /^0x[0-9a-fA-F]{40}$/;
+function requireAddress2(value, field) {
   if (typeof value !== "string" || value.trim() === "") {
     throw new MissingFieldError(field);
   }
-  if (!ADDRESS_RE.test(value)) {
+  if (!ADDRESS_RE2.test(value)) {
     throw new ConfigError(`${field} must be a 0x-prefixed 20-byte address, got: ${JSON.stringify(value)}`, {
       field,
       value
@@ -863,7 +969,7 @@ function createX402Challenge(requirement, extras) {
   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");
+  requireAddress2(requirement.payTo, "payTo");
   parseUsdToMicro(requirement.amount);
   const feeBps = extras?.feeBps ?? 0;
   if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 1e4) {
@@ -873,7 +979,7 @@ function createX402Challenge(requirement, extras) {
     );
   }
   const feeSink = extras?.feeSink ?? null;
-  if (feeBps > 0 && feeSink) requireAddress(feeSink, "feeSink");
+  if (feeBps > 0 && feeSink) requireAddress2(feeSink, "feeSink");
   const paymentRequired = toX402PaymentRequired(requirement, { feeBps, feeSink });
   return {
     status: 402,
@@ -901,7 +1007,7 @@ function validateX402ChallengeInput(input) {
       { field: "url" }
     );
   }
-  const payTo = requireAddress(input.payTo, "payTo");
+  const payTo = requireAddress2(input.payTo, "payTo");
   parseUsdToMicro(input.amount);
   const intent = input.intent ?? "transfer";
   if (intent !== "transfer" && intent !== "marketplace.buy") {
@@ -917,7 +1023,7 @@ function validateX402ChallengeInput(input) {
       { feeBps: input.feeBps }
     );
   }
-  const feeSink = input.feeSink === void 0 ? void 0 : requireAddress(input.feeSink, "feeSink");
+  const feeSink = input.feeSink === void 0 ? void 0 : requireAddress2(input.feeSink, "feeSink");
   return {
     payTo,
     amount: input.amount,
@@ -931,7 +1037,7 @@ function validateX402ChallengeInput(input) {
 }
 
 // src/client.ts
-var ADDRESS_RE2 = /^0x[0-9a-fA-F]{40}$/;
+var ADDRESS_RE3 = /^0x[0-9a-fA-F]{40}$/;
 function mapAlreadyEntered(e) {
   const msg = e instanceof Error ? e.message : typeof e === "object" && e && "message" in e ? String(e.message) : String(e);
   const detail = e instanceof PaymentFailedError || e instanceof ApiError ? e.detail : void 0;
@@ -979,7 +1085,7 @@ function requireAddressField(value, field) {
   if (typeof value !== "string" || value.trim() === "") {
     throw new MissingFieldError(field);
   }
-  if (!ADDRESS_RE2.test(value)) {
+  if (!ADDRESS_RE3.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 }
@@ -1167,11 +1273,22 @@ var Playmos = class {
      *   rounds.settle({ ranking }) → contract pays winners.
      *
      * Operator txs are signed by the Playmos service (OPERATOR_ROLE key).
+     *
+     * Offline `mock: true`: settle applies the stored payout rule and the 60/30/10
+     * pool leg across entries (#490). No series seed bank — mock pool is a floor,
+     * not a forecast of a live series with inherited seed.
      */
     /** Offline mock store for rounds.open/lock/settle/get when `mock: true` (3-game dogfood). */
     this.mockRounds = /* @__PURE__ */ new Map();
     /** Mock withdrawable credits after settle — key `${roundId}:${walletLower}` (#240 offline prize). */
     this.mockWithdrawable = /* @__PURE__ */ new Map();
+    /**
+     * Mock pot after per-entry rake (PrizePool escrowed sum) — keyed by roundId (#490).
+     * Payable pool at lock = pot × POOL_BPS / (POOL_BPS + SEED_BPS); inherited seed = 0 offline.
+     */
+    this.mockPotMicro = /* @__PURE__ */ new Map();
+    /** Persisted settle winners for re-settle replay (#490 C2) — never re-invent pool-to-everyone. */
+    this.mockSettleWinners = /* @__PURE__ */ new Map();
     this.rounds = {
       open: async (input) => {
         if (!this.config.mock) this.assertSecretKey("playmos.rounds.open");
@@ -1210,6 +1327,8 @@ var Playmos = class {
             prizePoolAddress: this.config.contracts?.prizePool ?? "0x0000000000000000000000000000000000000002"
           };
           this.mockRounds.set(input.roundId, round);
+          this.mockPotMicro.set(input.roundId, 0n);
+          this.mockSettleWinners.delete(input.roundId);
           return round;
         }
         const body = await this.http.post(
@@ -1242,11 +1361,12 @@ var Playmos = class {
               code: "conflict"
             });
           }
+          const payableMicro = this.mockPayablePoolMicro(existing);
+          const poolUsd = payableMicro > 0n ? formatMicroToUsd(payableMicro) : existing.pool ?? existing.entryAmount;
           const locked = {
             ...existing,
             status: "locked",
-            // Mock payable pool ≈ 60% of entry × max(1, entrants) for shape only — not money truth.
-            pool: existing.pool ?? existing.entryAmount,
+            pool: poolUsd,
             entrants: existing.entrants ?? 0,
             lockTxHash: MOCK_TX
           };
@@ -1269,14 +1389,15 @@ var Playmos = class {
             throw new ApiError(`unknown round: ${input.roundId}`, { status: 404, code: "not_found" });
           }
           if (existing.status === "settled" && existing.settleTxHash) {
+            const stored = this.mockSettleWinners.get(input.roundId);
             return {
               roundId: input.roundId,
               txHash: existing.settleTxHash,
               poolPaid: existing.pool ?? "0",
-              winners: "winners" in input.results ? input.results.winners : input.results.ranking.map((wallet) => ({
+              winners: stored ?? ("winners" in input.results ? input.results.winners : input.results.ranking.map((wallet) => ({
                 wallet,
-                amount: existing.pool ?? existing.entryAmount
-              })),
+                amount: "0"
+              }))),
               status: "settled"
             };
           }
@@ -1286,13 +1407,45 @@ var Playmos = class {
               code: "conflict"
             });
           }
-          const winners = "winners" in input.results ? input.results.winners : input.results.ranking.map((wallet, i) => ({
-            wallet,
-            // Winner-take-all mock shape when ranking only.
-            amount: i === 0 ? existing.pool ?? existing.entryAmount : "0"
-          }));
+          const payableMicro = existing.pool != null ? this.parseUsdToMicroLoose(existing.pool) : this.mockPayablePoolMicro(existing);
+          const poolPaid = payableMicro > 0n ? formatMicroToUsd(payableMicro) : existing.pool ?? existing.entryAmount;
+          let rows;
+          if ("winners" in input.results) {
+            rows = input.results.winners.map((w) => {
+              let micro;
+              try {
+                micro = this.parseUsdToMicroLoose(String(w.amount ?? "0"));
+              } catch (e) {
+                this.mockPayoutApiError(e);
+              }
+              return {
+                wallet: w.wallet,
+                amount: formatMicroToUsd(micro),
+                micro
+              };
+            });
+          } else {
+            if (payableMicro <= 0n) {
+              rows = [];
+            } else {
+              try {
+                const computed = computePayout(
+                  payableMicro,
+                  input.results.ranking,
+                  existing.payout
+                );
+                rows = computed.map((c) => ({
+                  wallet: c.wallet,
+                  amount: formatMicroToUsd(c.amount),
+                  micro: c.amount
+                }));
+              } catch (e) {
+                this.mockPayoutApiError(e);
+              }
+            }
+          }
+          const winners = rows.map(({ wallet, amount }) => ({ wallet, amount }));
           const settleTxHash = MOCK_TX;
-          const poolPaid = existing.pool ?? existing.entryAmount;
           const settled = {
             ...existing,
             status: "settled",
@@ -1300,18 +1453,11 @@ var Playmos = class {
             pool: poolPaid
           };
           this.mockRounds.set(input.roundId, settled);
-          for (const w of winners) {
-            const wAddr = String(w.wallet).toLowerCase();
-            let micro = 0n;
-            try {
-              micro = validateAmount(String(w.amount ?? "0"));
-            } catch {
-              micro = 0n;
-            }
-            if (micro > 0n) {
-              const k = `${input.roundId}:${wAddr}`;
-              this.mockWithdrawable.set(k, (this.mockWithdrawable.get(k) ?? 0n) + micro);
-            }
+          this.mockSettleWinners.set(input.roundId, winners);
+          for (const w of rows) {
+            if (w.micro <= 0n) continue;
+            const k = `${input.roundId}:${w.wallet.toLowerCase()}`;
+            this.mockWithdrawable.set(k, (this.mockWithdrawable.get(k) ?? 0n) + w.micro);
           }
           return {
             roundId: input.roundId,
@@ -1403,9 +1549,12 @@ var Playmos = class {
             ...existing,
             status: "cancelled",
             cancelTxHash: MOCK_TX,
-            pool: null
+            pool: null,
+            entrants: 0
           };
           this.mockRounds.set(input.roundId, cancelled);
+          this.mockPotMicro.set(input.roundId, 0n);
+          this.mockSettleWinners.delete(input.roundId);
           return {
             roundId: input.roundId,
             txHash: MOCK_TX,
@@ -1465,19 +1614,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**.
@@ -1582,19 +1746,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),
@@ -1930,6 +2101,69 @@ var Playmos = class {
       }
     }
   }
+  /**
+   * Resolve mock round by roundId **or** roundKey (kit `entryProvider` keys by roundKey, #490 C3).
+   */
+  findMockRound(idOrKey) {
+    const direct = this.mockRounds.get(idOrKey);
+    if (direct) return direct;
+    for (const r of this.mockRounds.values()) {
+      if (r.roundId === idOrKey || r.roundKey === idOrKey) return r;
+    }
+    return void 0;
+  }
+  /**
+   * 6dp USD → micro for mock winner amounts (#490 C1). Must not use 2dp `validateAmount`
+   * (would zero 0.135 from top-n 30% of $0.45).
+   */
+  parseUsdToMicroLoose(amount) {
+    if (typeof amount !== "string" || !/^\d+(\.\d{1,6})?$/.test(amount.trim())) {
+      throw new PayoutError(`invalid USD amount: ${JSON.stringify(amount)}`);
+    }
+    const [wholeRaw, frac = ""] = amount.trim().split(".");
+    const whole = wholeRaw ?? "0";
+    const fracPadded = (frac + "000000").slice(0, 6);
+    const micro = BigInt(whole) * 1000000n + BigInt(fracPadded);
+    if (micro < 0n) throw new PayoutError(`amount must be >= 0, got: ${JSON.stringify(amount)}`);
+    return micro;
+  }
+  /** Live-shaped 400 for mock payout validation (C5) — never leak raw PayoutError. */
+  mockPayoutApiError(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new ApiError(msg, { status: 400, code: "payout_invalid" });
+  }
+  /**
+   * Accumulate one mock entry into the pot (chain parity: rake off top, then lock split).
+   * No-op when no matching open/locked round — never 404 (C4).
+   */
+  mockAccumulateEntry(idOrKey, amountMicro) {
+    const round = this.findMockRound(idOrKey);
+    if (!round) return;
+    if (round.status !== "open" && round.status !== "locked") return;
+    const rake = amountMicro * BigInt(RAKE_BPS) / 10000n;
+    const escrowed = amountMicro - rake;
+    const pot = (this.mockPotMicro.get(round.roundId) ?? 0n) + escrowed;
+    this.mockPotMicro.set(round.roundId, pot);
+    const entrants = (round.entrants ?? 0) + 1;
+    const updated = { ...round, entrants };
+    this.mockRounds.set(round.roundId, updated);
+  }
+  /**
+   * Payable pool micro for mock lock/settle.
+   * With recorded entries: pot × POOL/(POOL+SEED) (seed bank = 0 offline).
+   * Zero entries: fall back to entryAmount micro (C4 — preserves existing suite).
+   */
+  mockPayablePoolMicro(round) {
+    const pot = this.mockPotMicro.get(round.roundId) ?? 0n;
+    if (pot > 0n) {
+      return pot * BigInt(POOL_BPS) / BigInt(POOL_BPS + SEED_BPS);
+    }
+    try {
+      return this.parseUsdToMicroLoose(round.entryAmount);
+    } catch {
+      return 0n;
+    }
+  }
   /**
    * Wallet timeout policy (#462 / PR #463 residual).
    * - connectTimeoutMs → eth_requestAccounts only
@@ -2078,6 +2312,7 @@ var Playmos = class {
     const metadata = validateMetadata(input.metadata);
     const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
     if (this.config.mock) {
+      this.mockAccumulateEntry(input.roundId, amountMicro);
       return this.rememberMock(
         mockEntryPayment({
           amountMicro,
@@ -2498,112 +2733,6 @@ function previewPoolSplit(amount) {
   };
 }
 
-// src/payout.ts
-var PayoutError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.code = "payout_invalid";
-    this.name = "PayoutError";
-  }
-};
-var ADDRESS_RE3 = /^0x[0-9a-fA-F]{40}$/;
-var BPS = 10000n;
-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();
-}
-function parseUsdToMicroLoose(amount) {
-  if (typeof amount !== "string" || !/^\d+(\.\d{1,6})?$/.test(amount.trim())) {
-    throw new PayoutError(`invalid USD amount: ${JSON.stringify(amount)}`);
-  }
-  const [wholeRaw, frac = ""] = amount.trim().split(".");
-  const whole = wholeRaw ?? "0";
-  const fracPadded = (frac + "000000").slice(0, 6);
-  const micro = BigInt(whole) * 1000000n + BigInt(fracPadded);
-  if (micro <= 0n) throw new PayoutError(`amount must be > 0, got: ${JSON.stringify(amount)}`);
-  return micro;
-}
-function computePayout(pool, ranking, rule) {
-  if (typeof pool !== "bigint" || pool <= 0n) {
-    throw new PayoutError(`pool must be a positive bigint (micro-USDC), got: ${String(pool)}`);
-  }
-  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) => 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}`);
-    seen.add(w);
-  }
-  if (rule.kind === "winner-take-all") {
-    return [{ wallet: wallets[0], amount: pool }];
-  }
-  if (rule.kind === "top-n") {
-    const splits = rule.splitsBps;
-    if (!Array.isArray(splits) || splits.length === 0) {
-      throw new PayoutError("top-n splitsBps must be a non-empty array");
-    }
-    if (splits.length > wallets.length) {
-      throw new PayoutError(
-        `top-n needs ${splits.length} ranked wallets but ranking only has ${wallets.length}`
-      );
-    }
-    let sumBps = 0;
-    for (const b of splits) {
-      if (!Number.isInteger(b) || b <= 0 || b > 1e4) {
-        throw new PayoutError(`each splitsBps entry must be an integer in (0, 10000], got: ${b}`);
-      }
-      sumBps += b;
-    }
-    if (sumBps !== 1e4) {
-      throw new PayoutError(`splitsBps must sum to 10000, got ${sumBps}`);
-    }
-    const out = [];
-    let allocated = 0n;
-    for (let i = 0; i < splits.length; i++) {
-      const amt = pool * BigInt(splits[i]) / BPS;
-      out.push({ wallet: wallets[i], amount: amt });
-      allocated += amt;
-    }
-    const remainder = pool - allocated;
-    if (remainder < 0n) throw new PayoutError("internal: allocated more than pool");
-    out[0] = { wallet: out[0].wallet, amount: out[0].amount + remainder };
-    const filtered = out.filter((x) => x.amount > 0n);
-    if (filtered.length === 0) throw new PayoutError("payout produced no positive amounts");
-    const total = filtered.reduce((s, x) => s + x.amount, 0n);
-    if (total !== pool) throw new PayoutError(`internal: sum ${total} != pool ${pool}`);
-    return filtered;
-  }
-  if (rule.kind === "custom") {
-    const amounts = rule.amounts;
-    if (!Array.isArray(amounts) || amounts.length === 0) {
-      throw new PayoutError("custom amounts must be a non-empty array of USD strings");
-    }
-    if (amounts.length > wallets.length) {
-      throw new PayoutError(
-        `custom amounts has ${amounts.length} entries but ranking only has ${wallets.length}`
-      );
-    }
-    const out = [];
-    let total = 0n;
-    for (let i = 0; i < amounts.length; i++) {
-      const amt = parseUsdToMicroLoose(amounts[i]);
-      out.push({ wallet: wallets[i], amount: amt });
-      total += amt;
-    }
-    if (total !== pool) {
-      throw new PayoutError(
-        `custom amounts sum to ${total} micro-USDC but pool is ${pool} \u2014 must match exactly`
-      );
-    }
-    return out;
-  }
-  throw new PayoutError(`unknown payout rule kind: ${JSON.stringify(rule.kind)}`);
-}
-
 // src/settlement.ts
 var ADDRESS_RE4 = /^0x[0-9a-fA-F]{40}$/;
 var DEFAULT_TTL_MS = 15 * 60 * 1e3;