@playmos/sdk 0.3.10 → 0.3.11

package/CHANGELOG.md

@@ -0,0 +1,189 @@
+# Changelog
+
+All notable changes to `@playmos/sdk`. This project adheres to [Semantic Versioning](https://semver.org/).
+
+## Unreleased
+
+## [0.3.11] — 2026-08-09
+
+### Added
+- **`hasEntered` on `@playmos/sdk/server`** (sdk#510 / PR #541): server-side PrizePool admit read — required `rpcUrl`, plain-string pins, throws on RPC fail/timeout (never `false` on outage). Default `timeoutMs` 8s + optional `AbortSignal`.
+- Service **`GET /v1/rounds/:id/entered`** (sk_ only): store tenancy + pure-chain query params for server-settle studios.
+
+### Notes
+- Third parties need this tag on npm for Option A; Option B needs service deploy of main after #541.
+- Related carries: timeout REVERT-RED (#542), residual money-path #538 C1–C4 (service).
+
+
+### Fixed (service; next tag)
+- **#530** — `rounds.open` refuses IAP catalog ids / playmosPay games (no PrizePool calldata at PlaymosPay).
+- **#533** — self-serve global settle cap releases on settle failure (no permanent shared-ceiling burn).
+- **#532** — mutation-proof coverage for #528 R2 open gate, #529 burn payout, #509 idempotency lookup.
+- **#528 / #529 / #508 / #509** — shipped on main via PR #531 (open-mined fence, IAP payout, settle wait, idem recovery).
+
+### Docs
+- **#511** — `rounds.cancel` is real (docs no longer claim “no wrapper in V1”).
+- **#516** — CHANGELOG in npm tarball; 0.3.8 identity breaking called out below.
+
+## [0.3.10] — 2026-08-06
+
+### Added
+- **`rounds.getWithMeta`** (#501): returns `{ round, via?, chainReadFailed? }` for service read-path honesty after #499. `rounds.get` still returns `RoundState` only (no transport meta on the record — hub-safe). Mock omits `via`.
+
+### Fixed
+- **Mock `rounds.withdraw`** (#495): requires `wallet`; debits only that wallet’s credit; zero balance → `NothingToWithdrawError` (was paying first non-zero credit to any caller).
+
+### Ops / service
+- **Mainnet refuse non-dedicated RPC + Ankr free-path honesty** (#505 / #502 residual).
+- **`/health` RPC redaction host-only** + **`chain.rpcKind`** allowlist classification (#502 partial on this tag). Warn on public RPC for Sepolia; hard-fail public RPC on mainnet chainId (further #505 refuse-unknown if merged before tag).
+
+## [0.3.9] — 2026-08-06
+
+### Fixed
+- **Mock `rounds.settle` payout economics** (#490 / #493): offline settle applies the stored payout rule (`computePayout`) and accumulates the PrizePool pot (rake off top, then `POOL/(POOL+SEED)` at lock) instead of winner-takes-all on `entryAmount`. Credits `rounds.prize` from integer micro (not 2dp re-parse). Re-settle replays stored winners (claimable unchanged). Ranking validation matches live (400 `payout_invalid`). **Behaviour change:** mock settle now rejects non-address / short rankings that previously returned fake numbers.
+
+### Docs
+- Mock pool is a **floor** (no series seed bank offline) — not a live-series forecast (#490 C6).
+- Public operator note: `pk_` on `/v1/rounds*` → clean **403** (not an opaque 504) (#496 / #500).
+- Public docs auto-deploy pipeline unblocked (#498).
+
+## [0.3.8] — 2026-08-05
+
+### Breaking
+- **`identity` required on the player-wallet (client-signed) path** (#466 / #374). `enterRound` with a wallet no longer invents `wallet#idempotencyKey`. Missing `identity` → typed `ConfigError`. Pass the same identity your server will use for `hasEntered` / hub `/entry/confirm`. No-wallet server-settle smoke may still omit it (service derives). Studios on `^0.3.x` that auto-bump must pin identity before upgrading past 0.3.7.
+
+### Packaging
+- **homepage / bugs** point at public docs (`https://playmos-docs-public.vercel.app/docs`) so npm sidebar links resolve for outsiders (#481 / #488).
+
+## [0.3.7] — 2026-08-04
+
+### Fixed
+- **Mock operator lifecycle with public key** (#435 / #456): `rounds.open` / `lock` / `settle` / `cancel` work offline when `mock: true` with a `pk_` key. Live operator path still requires a provisioned `sk_`.
+
+### Docs
+- **Issa residual honesty** (#435 / #457): skill entry ids are `entry_…` (not `pay_…`); Base Stack uses `basestack` / `game_sandbox_skill` (not `game_sandbox_base_stack`); shared sandbox pool callout.
+
+## [0.3.6] — 2026-07-25
+
+**Packaging only. No API change, no runtime change, no behaviour change** — code under `sdk/src`
+is byte-identical to `0.3.5`. Upgrading gains you nothing functionally, and nothing breaks.
+
+This release exists to prove the release path itself. It is the **first `@playmos/sdk` version
+published by CI from a version tag** rather than by a person running `npm publish` by hand.
+
+### Packaging
+- **`repository`** — required by npm Trusted Publishing (OIDC), and it fails at publish time
+  rather than at setup time when absent.
+- **`publishConfig: { access: "public", provenance: true }`** — a scoped package defaults to
+  **restricted**; a silently-private publish of a package studios must install is a failure that
+  looks like success. Making it explicit means `--access` can never be omitted.
+
+### Release path (context, not a code change)
+`.github/workflows/publish-npm.yml` now publishes on a `v*` tag, behind two guards that run
+**before** any credential is touched: the tag version must equal `sdk/package.json`, and the
+tagged commit must be an ancestor of `origin/main`. The workflow then **reads the version back
+off the registry** — the publish command's own exit code is not treated as evidence.
+
+Why it was built: three npm tokens expired silently, each taking publishing down with it, and an
+expired token returns **E404, not 401**, so the 2026-07-18 outage was misdiagnosed as a missing
+package. `publish-pypi.yml` and `publish-nuget.yml` already existed; npm — the actual product —
+had no publish workflow at all.
+
+### Supersedes
+- The **"npm publish is Boz-run"** note in `0.3.5` below is **no longer accurate.** Publishing is
+  automated from a version tag whose commit is on `main` and passed CI. *The machine may release;
+  it may not release unreviewed, untagged, or off-main work.*
+
+### Known, recorded, not fixed here
+- **The SDK's test suite cannot run standalone** — three suites import across into `service/src`,
+  so a clean checkout of `sdk/` alone cannot resolve them. This means **the published package has
+  never been validated in isolation from the monorepo**, which is the only way a studio ever
+  installs it. Carried to the Frozen Plan.
+
+## [0.3.5] — 2026-07-18
+
+**Authoritative series latch** (issue **#351**). Unblocks hub PR #57 probe-subsystem deletion.
+
+### Added
+- **`rounds.activeForSeries({ seriesKey, gameId })`** → `ActiveSeriesRound | null`.
+  `null` is a **proof of free** (service `GET /v1/series/:seriesKey/active`), not a failed probe.
+- Types: `ActiveSeriesRound`, `ActiveForSeriesResult`; optional `seriesKey` on `RoundState`.
+
+### Fixed
+- **Mock `rounds.open` persists `seriesKey`** (was discarded). Without this, mock
+  `activeForSeries` would always return free — the money-strand class.
+
+### Service (same release train)
+- `GET /v1/series/:seriesKey/active?gameId=` — chain `activeRound` + studio-scoped hash reverse.
+- `activeRound` on PrizePool ABI; `readActiveRound` / `readPrizeRoundByHash`.
+- `serializeRound` emits `seriesKey`; `/health` capabilities include `series.active`.
+- `listRoundsForStudio` on store for tenancy-safe reverse lookup.
+
+### Note
+- **npm publish is Boz-run.** Hub pins `^0.3.4` until dual-path ships, then bumps to `^0.3.5`.
+- Hub probe/memory **deletion is a separate PR** after live verify.
+- **Hub dual-path capability detection:** read `ApiError.detail.status` / `detail.code` (not
+  top-level `.status`/`.code`). Prefer `/health` `capabilities.rounds.capabilities` includes
+  `"series.active"` over inferring from 404 shape.
+
+## [0.3.3] — 2026-07-15
+
+3-game dogfood convergence (Path B / kit). **Testnet only.**
+
+### Fixed
+- **`exports["./package.json"]`** — resolvable from npm (tools that import package metadata no longer fail on 0.3.2). **#215**
+- **`entryProvider().payEntry` status** — always **lowercase** (`confirmed` | `failed` | `pending`), matching `Payment.status` (was `CONFIRMED` / kit-style). **#217**
+- **`entryProvider` + offline `verify`** — payEntry path keeps the mock store (`rememberMock`) so `verify(payEntry.paymentId)` is offline like `enterRound` (**#219** completes **#207** for the kit path). Same `Playmos` instance required (store is per client).
+
+### Added
+- **Mock `rounds.open` / `lock` / `settle` / `get`** when `mock: true` — offline Path B operator lifecycle for unit tests and dogfood without sandbox. **#216**
+
+### Note
+- Kits that compare `status === "CONFIRMED"` should use case-insensitive checks.
+- No #161 interop claim language.
+
+## [0.3.2] — 2026-07-15
+
+Path B mock / dogfood seam (issues **#204** / **#207**). **Testnet only.**
+
+### Fixed
+- **`mock: true` `connect()`** works offline (no Base App / base-account provider required).
+- **`enterRound` mock honors `roundKey` + `identity` pins**.
+- **`verify(id)` offline for mock payments**.
+- **`entryProvider` mock receipts set `onchain: false`**.
+
+### Docs / publish
+- CI: `sdk/dist` must match a fresh `npm run build` (#211).
+
+## [0.3.1] — 2026-07-11
+
+Winner claim ergonomics (issue #41). **Proven on Base Sepolia** (issue #62 — `service/scripts/prove-withdraw-claim.ts`).
+
+### Added
+- **`enterRound` returns `prizePoolAddress` + `roundKey`** on the entry payment — keep them for later claim.
+- **`rounds.prize({ roundId, wallet })`** — read claimable pull-payment balance (+ PrizePool address).
+- **`rounds.withdraw({ prizePoolAddress | roundId })`** — player-signed `PrizePool.withdraw()`; pre-check claimable; typed **`NothingToWithdrawError`**.
+- Service: **`GET /v1/rounds/:id/prize?wallet=`**, `RoundState.prizePoolAddress` on open/lock/get.
+- Docs: claim flow marked **proven** after live settle→prize→withdraw→balance proof.
+
+## [0.3.0] — 2026-07-11
+
+Agent-economy DX hardening from the Playmos Town live stress-test (Base Sepolia).
+
+### Added
+- **`transfers.wait(id, opts?)`** and **`transfer(input, { confirm: true })`** — first-class settlement confirmation, so you no longer hand-roll a poll loop. `wait` resolves on a terminal state (`settled`/`failed` — a `failed` transfer *resolves*, inspect `status`; it does not throw) and throws a typed `ApiError` (`detail.timeout`) past `timeoutMs` (default 30s) / `maxAttempts` (40). (#47)
+- **Automatic `429` retry** — the client retries throttled requests with exponential backoff + jitter, honoring `Retry-After` (default ≤ 2 retries). Opt out with `new Playmos({ apiKey, retry: false })`; tune with `retry: { maxRetries, baseDelayMs, maxDelayMs }`. Safe: reads are idempotent and writes carry an idempotency key. (#50)
+- **`agents.fund` now returns `funding.id`** and auto-sends an `idempotencyKey` (body + header) like `transfer`, so a retry re-hits the same requirement (`preq_<key>`) — no double-fund. The id is pollable for recovery after a 502/timeout. (#48, #54)
+
+### Changed
+- **`fee` / `net` strings now carry full micro precision** — a sub-cent fee shows its real value (e.g. `"0.005"`, never `"0.00"`), and **`fee + net === amount`** holds exactly. (#45)
+- **`feeSink` is now optional on the sandbox** for `transfer` and `escrow.hold` (previously the client hard-rejected an omitted sink when `feeBps > 0`). The sandbox service supplies a default sink (advertised on `/health`), so agent scripts move value without wiring a treasury; on **live** an omitted sink still 400s at the service (server authority). A supplied sink is always shape-validated client-side. Now consistent with `marketplace.list`. (#49, #58)
+
+### Fixed
+- **`RoundState.pool` / `RoundState.entrants` are now `string | null` / `number | null`** — matching the wire, which returns `null` until a round is reconciled against chain (the types previously claimed non-null). (#42)
+
+### Docs
+- README now includes the **Playmos Town agent golden path** (`createWallet` → `fund` → `transfer` → confirm) and the `sk_test_` vs `pk_test_` distinction. (#38)
+
+## [0.2.0]
+- Value-movement primitives: `transfer`, `escrow`, `marketplace`, agent wallets (`agents.*`), and contest-settle round lifecycle (`rounds.*`).

package/README.md

@@ -4,6 +4,7 @@
 
 Stablecoin payments for games on Base. One SDK for in-app purchases (1%), skill-game prize-pool entries (10%, 60/30/10), and **in-game economies** (player · NPC · agent commerce via `transfer()`). USD in, USDC on-chain — no crypto UX for your players.
 
+**Changelog:** see [`CHANGELOG.md`](./CHANGELOG.md) (shipped in the npm tarball from the next publish). **Breaking in 0.3.8:** player-wallet `enterRound` requires `identity` — no silent invent.
 
 ## Install
 
@@ -246,6 +247,8 @@ Outside the sandbox (a `pk_live` key), or whenever you want the player to sign t
 ```ts
 const playmos = new Playmos({
   apiKey: "pk_live_…",
+  // base-account (default) is NOT a built-in Base Account package — pass wallet.provider
+  // from @base-org/account when not in Base App / no injected ethereum (sdk#512)
   wallet: { connector: "base-account" }, // or "injected" in a wallet browser
 });
 ```

package/dist/chunk-35WJANW4.js

@@ -0,0 +1,255 @@
+import { numberToHex, keccak256, toBytes, encodeFunctionData } from 'viem';
+
+// src/errors.ts
+var PlaymosError = class extends Error {
+  constructor(code, message, detail) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.detail = detail;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var InvalidAmountError = class extends PlaymosError {
+  constructor(amount) {
+    super(
+      "invalid_amount",
+      `Invalid amount: ${JSON.stringify(amount)}. Provide a positive USD decimal string with at most 2 decimals, e.g. "4.99".`,
+      { amount }
+    );
+  }
+};
+var MissingFieldError = class extends PlaymosError {
+  constructor(field) {
+    super("missing_field", `Missing required field: "${field}".`, { field });
+  }
+};
+var InsufficientGasError = class extends PlaymosError {
+  constructor(detail) {
+    super(
+      "insufficient_gas",
+      `The player's wallet has too little ETH to pay gas. Ask them to add a little ETH, or switch to gas.mode: "sponsored".`,
+      detail
+    );
+  }
+};
+var WalletConnectionError = class extends PlaymosError {
+  constructor(message = "Could not connect the player's wallet.", detail) {
+    super("wallet_connection", message, detail);
+  }
+};
+var WalletTimeoutError = class extends PlaymosError {
+  constructor(message = "The wallet did not respond in time. Ask the player to approve the prompt, or retry.", detail) {
+    super("wallet_timeout", message, detail);
+  }
+};
+var PaymentFailedError = class extends PlaymosError {
+  constructor(message = "The on-chain payment did not complete.", detail) {
+    super("payment_failed", message, detail);
+  }
+};
+var AlreadyEnteredError = class extends PlaymosError {
+  constructor(detail) {
+    super(
+      "already_entered",
+      "This identity already entered this round on-chain. For pay-per-play, pass a unique identity per attempt (not just the wallet address).",
+      detail
+    );
+  }
+};
+var AuthError = class extends PlaymosError {
+  constructor(message = "Invalid or missing API key.", detail) {
+    super("auth", message, detail);
+  }
+};
+var ApiError = class extends PlaymosError {
+  constructor(message, detail) {
+    super("api_error", message, detail);
+  }
+};
+var ConfigError = class extends PlaymosError {
+  constructor(message, detail) {
+    super("config", message, detail);
+  }
+};
+var NothingToWithdrawError = class extends PlaymosError {
+  constructor(detail) {
+    super(
+      "nothing_to_withdraw",
+      "Nothing to withdraw \u2014 this wallet has no credited prize balance on this PrizePool (round not settled for them, or already claimed).",
+      detail
+    );
+  }
+};
+
+// src/chain/abis.ts
+var erc20Abi = [
+  {
+    type: "function",
+    name: "approve",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "spender", type: "address" },
+      { name: "amount", type: "uint256" }
+    ],
+    outputs: [{ type: "bool" }]
+  }
+];
+var playmosPayAbi = [
+  {
+    type: "function",
+    name: "pay",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "paymentId", type: "bytes32" },
+      { name: "studio", type: "address" },
+      { name: "amount", type: "uint256" }
+    ],
+    outputs: []
+  }
+];
+var prizePoolAbi = [
+  {
+    type: "function",
+    name: "enter",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "roundId", type: "bytes32" },
+      { name: "identity", type: "bytes32" }
+    ],
+    outputs: []
+  },
+  {
+    type: "function",
+    name: "withdrawable",
+    stateMutability: "view",
+    inputs: [{ name: "account", type: "address" }],
+    outputs: [{ type: "uint256" }]
+  },
+  {
+    type: "function",
+    name: "withdraw",
+    stateMutability: "nonpayable",
+    inputs: [],
+    outputs: [{ name: "amount", type: "uint256" }]
+  }
+];
+async function sendCalls(provider, from, chainId, calls, paymasterUrl) {
+  const params = {
+    version: "2.0.0",
+    from,
+    chainId: numberToHex(chainId),
+    atomicRequired: true,
+    calls
+  };
+  if (paymasterUrl) {
+    params.capabilities = { paymasterService: { url: paymasterUrl } };
+  }
+  let result;
+  try {
+    result = await provider.request({ method: "wallet_sendCalls", params: [params] });
+  } catch (e) {
+    if (e instanceof WalletTimeoutError) throw e;
+    const msg = e?.message ?? String(e);
+    if (/reject|denied|cancel|closed/i.test(msg)) {
+      throw new WalletConnectionError("The player cancelled or closed the payment sheet.", { cause: msg });
+    }
+    throw new PaymentFailedError("wallet_sendCalls failed.", { cause: msg });
+  }
+  const id = typeof result === "string" ? result : result?.id ?? "";
+  if (!id) throw new PaymentFailedError("Wallet returned no calls id.");
+  return { id };
+}
+async function waitForCalls(provider, id, timeoutMs = 6e4) {
+  if (!id) return { status: "FAILED" };
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await provider.request({
+        method: "wallet_getCallsStatus",
+        params: [id]
+      });
+      const s = String(res?.status ?? "").toUpperCase();
+      const txHash = res?.receipts?.[0]?.transactionHash;
+      if (s === "200" || s === "CONFIRMED" || s === "SUCCESS") return { status: "CONFIRMED", txHash };
+      if (s === "400" || s === "500" || s === "FAILED" || s === "REVERTED") return { status: "FAILED", txHash };
+    } catch (e) {
+      if (e instanceof WalletTimeoutError) {
+        await new Promise((r) => setTimeout(r, 900));
+        continue;
+      }
+      throw e;
+    }
+    await new Promise((r) => setTimeout(r, 900));
+  }
+  return { status: "PENDING" };
+}
+function encodeApprove(spender, amountUnits) {
+  return encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: [spender, amountUnits] });
+}
+var GAS_FLOOR_WEI_DEFAULT = 200000000000000n;
+var GAS_FLOOR_WEI_BASE_SEPOLIA = 50000000000000n;
+var CHAIN_ID_BASE_SEPOLIA = 84532;
+function gasFloorWei(chainId) {
+  return chainId === CHAIN_ID_BASE_SEPOLIA ? GAS_FLOOR_WEI_BASE_SEPOLIA : GAS_FLOOR_WEI_DEFAULT;
+}
+async function assertEnoughGas(provider, from, minWei) {
+  let floor = minWei;
+  if (floor === void 0) {
+    let chainId = 0;
+    try {
+      const hex = await provider.request({ method: "eth_chainId", params: [] });
+      chainId = Number(BigInt(hex));
+    } catch {
+    }
+    floor = gasFloorWei(chainId);
+  }
+  let balance;
+  try {
+    const hex = await provider.request({ method: "eth_getBalance", params: [from, "latest"] });
+    balance = BigInt(hex);
+  } catch {
+    return;
+  }
+  if (balance < floor) {
+    throw new InsufficientGasError({
+      balanceWei: balance.toString(),
+      minWei: floor.toString()
+    });
+  }
+}
+
+// src/chain/calls.ts
+var toBytes32 = (s) => keccak256(toBytes(s));
+function buildIapCalls(args) {
+  const payData = encodeFunctionData({
+    abi: playmosPayAbi,
+    functionName: "pay",
+    args: [toBytes32(args.paymentId), args.studio, args.amountUnits]
+  });
+  return [
+    { to: args.usdc, data: encodeApprove(args.playmosPay, args.amountUnits) },
+    { to: args.playmosPay, data: payData }
+  ];
+}
+function buildEntryCalls(args) {
+  const enterData = encodeFunctionData({
+    abi: prizePoolAbi,
+    functionName: "enter",
+    args: [toBytes32(args.roundKey), toBytes32(args.identity)]
+  });
+  return [
+    { to: args.usdc, data: encodeApprove(args.prizePool, args.amountUnits) },
+    { to: args.prizePool, data: enterData }
+  ];
+}
+function buildWithdrawCall(prizePool) {
+  const data = encodeFunctionData({
+    abi: prizePoolAbi,
+    functionName: "withdraw",
+    args: []
+  });
+  return { to: prizePool, data };
+}
+
+export { AlreadyEnteredError, ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError, WalletTimeoutError, assertEnoughGas, buildEntryCalls, buildIapCalls, buildWithdrawCall, prizePoolAbi, sendCalls, toBytes32, waitForCalls };

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

@@ -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 {

package/dist/{errors-Chizbb96.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 {