@playmos/sdk 0.3.9 → 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

@@ -1614,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**.
@@ -1731,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),

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-Chizbb96.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-Chizbb96.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>;
@@ -890,4 +908,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.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-Chizbb96.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-Chizbb96.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>;
@@ -890,4 +908,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

@@ -1530,19 +1530,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 +1662,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),

package/dist/server.d.cts

@@ -1,4 +1,4 @@
-import { Y as PlaymosError, W as WebhookEvent } from './errors-BMlWHsMb.cjs';
+import { Z as PlaymosError, W as WebhookEvent } from './errors-Chizbb96.cjs';
 
 /**
  * Webhook signature verification (spec §6.2) — server-side only.

package/dist/server.d.ts

@@ -1,4 +1,4 @@
-import { Y as PlaymosError, W as WebhookEvent } from './errors-BMlWHsMb.js';
+import { Z as PlaymosError, W as WebhookEvent } from './errors-Chizbb96.js';
 
 /**
  * Webhook signature verification (spec §6.2) — server-side only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playmos/sdk",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "description": "Playmos SDK — stablecoin payments for games on Base. One SDK for IAP (1%), skill-game prize-pool entries (10%, 60/30/10), and agent economies. USD in, USDC on-chain, no crypto UX for players.",
   "license": "UNLICENSED",
   "private": false,