@playmos/sdk 0.3.6 → 0.3.8

package/README.md

@@ -5,27 +5,13 @@
 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.
 
 
-## Local `file:` / monorepo install
-
-`@playmos/sdk` ships **built `dist/`**. `prepare` / `prepack` / `prepublishOnly` run
-`scripts/ensure-build.cjs`, which rebuilds `dist/` via local `tsup` or (on a cold
-`file:` install with no `sdk/node_modules`) `npx --yes tsup@8.3.0`:
-
-- `npm install` inside `sdk/`
-- `npm install` of a **`file:`** / git dependency (dogfood monorepos)
-- `npm publish` / pack
-
-So wiping `dist/` then `npm i file:…/sdk` still yields a current build (#211).
-CI also fails if committed `dist/` drifts from source.
-
-
 ## Install
 
 ```bash
 npm i @playmos/sdk
 ```
 
-Requires **Node 18 / 20 / 22 LTS** for the monorepo toolchains (Hardhat/service). See repo `docs/TOOLCHAIN.md` (issue #5).
+Requires **Node 18 / 20 / 22 LTS** for local development and CI toolchains. Full toolchain notes live in the private monorepo; third parties only need a current Node LTS and `npm i @playmos/sdk`.
 
 ## Browser vs server entry
 
@@ -148,7 +134,7 @@ Fields match the table above (`from` optional → defaults to the signer; `feeBp
 
 ### In-game economies — the Playmos Town golden path
 
-**In-game economies** = commerce between **players, NPCs, and agents** (AI or scripted). The money primitive is **`transfer()`** (entity-agnostic); NPC/agent wallets use **`agents.*`** (API names unchanged). This is the loop the [Playmos Town example](https://github.com/playmos-labs/playmos-sdk/blob/main/docs/examples/playmos-town-sdk.mjs) runs end to end: give each NPC a wallet, fund it, then move value with a per-call fee — P2P (5%), a monster bounty (0%), a shop sale (100%). Proven on **Base Sepolia** (transfer layer) — not a claim that a full MMO product is shipped.
+**In-game economies** = commerce between **players, NPCs, and agents** (AI or scripted). The money primitive is **`transfer()`** (entity-agnostic); NPC/agent wallets use **`agents.*`** (API names unchanged). This is the loop the **Playmos Town** pattern runs end to end (described in public docs — Path C / in-game economies): give each NPC a wallet, fund it, then move value with a per-call fee — P2P (5%), a monster bounty (0%), a shop sale (100%). Proven on **Base Sepolia** (transfer layer) — not a claim that a full MMO product is shipped.
 
 **Agents need a SECRET test key — `sk_test_`, not `pk_test_`.** Assigning NPC wallets and transferring *from* an NPC are privileged, server-side actions, so they require an `sk_test_` key kept on **your backend** — not the public `pk_test_playmos_sandbox`. `pk_test_` runs the no-wallet `pay()` / `enterRound()` demos above; `sk_test_` unlocks `agents.*` and NPC-funded `transfer`.
 
@@ -199,12 +185,32 @@ t.status; // "settled" (or "failed") — already terminal, no follow-up call
 
 The sandbox throttles (5 req/min per key), so back-to-back legs can `429`. **Retries are automatic** — the SDK backs off and retries a `429` up to twice by default, and every write carries an idempotency key so a retry never double-broadcasts (tune with `new Playmos({ apiKey, retry: { maxRetries } })`, or `retry: false` to opt out).
 
-The full 5-NPC walkthrough — create → fund → P2P / shop / bounty, each confirmed on-chain — is [`docs/examples/playmos-town-sdk.mjs`](https://github.com/playmos-labs/playmos-sdk/blob/main/docs/examples/playmos-town-sdk.mjs):
+The full 5-NPC walkthrough — create → fund → P2P / shop / bounty, each confirmed on-chain — is summarized in the public developer docs (in-game economies / agents). Example script names below are for monorepo operators only:
 
 ```bash
 PLAYMOS_SK_TEST=sk_test_… PLAYMOS_FEE_SINK=0x… node docs/examples/playmos-town-sdk.mjs
 ```
 
+## Local `file:` / monorepo install
+
+`@playmos/sdk` ships **built `dist/`**. Lifecycle hooks `prepare` / `prepack` / `prepublishOnly`
+run `scripts/ensure-build.cjs` (rebuild via local `tsup` or, on a cold `file:` install with no
+`sdk/node_modules`, `npx --yes tsup@8.3.0`) — **when lifecycle scripts are enabled**.
+
+**Repo hardening (sdk#431 / #434):** root + `sdk/` + `service/` + `contracts/` set
+`ignore-scripts=true` in `.npmrc`. That blocks dependency install scripts (supply-chain defense)
+and also suppresses those prepare/prepack/prepublishOnly hooks.
+
+| Action | What to do |
+|--------|------------|
+| Day-to-day install in this monorepo | `npm ci` / `npm i` as usual — scripts ignored by design |
+| Rebuild dist after source edits | **`npm run build`** in `sdk/` (user scripts still run) |
+| **Manual** `npm publish` from a laptop | **`cd sdk && npm run build && npm publish`** — do not rely on prepublishOnly |
+| CI publish | Already runs `npm run build` explicitly before pack/publish |
+
+So wiping `dist/` then `npm i file:…/sdk` may **not** auto-rebuild under `ignore-scripts`;
+run `npm run build` in `sdk/` first, or use CI. CI also fails if committed `dist/` drifts from source.
+
 ## Mock mode — offline, deterministic
 
 For CI and wiring checks, `mock: true` returns instant, deterministic results with **no network and no chain**. Results carry `mock: true` and use the real status union, so your handling code sees the exact production shape.
@@ -215,9 +221,23 @@ const payment = await playmos.pay({
   gameId: "game_sandbox_iap", sku: "gems_100", amount: "0.99", playerId: "player_abc",
 });
 // instant — payment.status === "confirmed", payment.mock === true
+
+// Operator lifecycle offline too — no sk_ required when mock:true (#435)
+await playmos.rounds.open({
+  gameId: "game_sandbox_skill",
+  roundId: "r1",
+  entryAmount: "0.25",
+  payout: { kind: "winner-take-all" },
+});
+await playmos.rounds.lock({ roundId: "r1" });
+await playmos.rounds.settle({
+  roundId: "r1",
+  results: { ranking: ["0x0000000000000000000000000000000000000001"] },
+});
 ```
 
 Mock mode is not test mode: mock is fabricated and offline; the sandbox is real and settles on Base Sepolia.
+**Live** `rounds.open` / `lock` / `settle` still need a provisioned secret key on the server.
 
 ## Production — real player wallets
 
@@ -257,4 +277,8 @@ The escrow/marketplace resolve endpoints (release/refund/confirm) return a deter
 
 ## Docs
 
-Full documentation — skill games, webhooks, gas, payouts, in-game economies, and the REST API — at [playmos.io](https://playmos.io).
+Full developer docs (install, IAP `pay()`, skill `enterRound()`, agents, webhooks, REST) — **public, no login**:
+
+**https://playmos-docs-public.vercel.app/docs**
+
+That is the third-party / stranger surface while we stress-test. Production **`playmos.io/docs`** comes after Founder promote (gate still holds for production only).

package/dist/{chunk-VYR6BBHF.js → chunk-UZECDT6F.js}

@@ -36,11 +36,25 @@ var WalletConnectionError = class extends PlaymosError {
     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);
@@ -66,4 +80,4 @@ var NothingToWithdrawError = class extends PlaymosError {
   }
 };
 
-export { ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError };
+export { AlreadyEnteredError, ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError, WalletTimeoutError };

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

@@ -28,6 +28,7 @@ interface WalletConfig {
     /**
      * 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.
      */
     provider?: Eip1193Provider;
 }
@@ -73,6 +74,13 @@ interface PlaymosConfig {
      *   retry: { maxRetries }  → tune attempts / backoff (0 also opts out)
      */
     retry?: boolean | RetryOptions;
+    /**
+     * Timeout for **connect / `eth_requestAccounts` only** (#462). Default 20_000.
+     * Does **not** bound the payment confirmation sheet (`wallet_sendCalls`) — a short
+     * guess there can take the player's USDC without recording the entry (PR #463 residual).
+     * Machine RPCs (status polls, balance, chainId) use a separate internal 20s bound.
+     */
+    connectTimeoutMs?: number;
 }
 /** Tuning for the automatic 429 retry (all optional; sane defaults). */
 interface RetryOptions {
@@ -152,9 +160,12 @@ interface EnterRoundInput {
      */
     roundKey?: string;
     /**
-     * Advanced: the EXACT on-chain identity for this paid attempt (e.g.
-     * "0xWallet#nonce"). Overrides the server-generated identity so the on-chain
-     * entry and your server's `hasEntered` check line up. One entry per identity.
+     * On-chain entrant id for this paid attempt (e.g. `"0xWallet#nonce"`).
+     * **Required on the client-signed (player wallet) path** so hub `hasEntered`
+     * matches (#374 / #466). **One entry per identity** — use a **unique value per
+     * paid attempt** (pay-per-play); reusing the same identity hits AlreadyEntered.
+     * Omit only on no-wallet sandbox server-settle smoke (service may derive).
+     * `entryProvider().payEntry` always supplies the kit identity.
      */
     identity?: string;
 }
@@ -532,11 +543,34 @@ interface ActiveForSeriesResult {
     via: "chain" | "cache";
     active: ActiveSeriesRound | null;
 }
-/** Result of `playmos.rounds.cancel` — may be async 202 cancelling (#346). */
+/**
+ * Input to `playmos.rounds.cancel` (#346 / #376).
+ *
+ * Default is **submit-only**: returns `status: "cancelling"` after broadcast without
+ * inventing success. Pass `confirm: true` to poll until `cancelled` or timeout
+ * (still returns honest `cancelling` on timeout — never pretends terminal).
+ */
+interface RoundCancelInput {
+    roundId: string;
+    gameId?: string;
+    /**
+     * When true, poll re-POST cancel + GET until `cancelled` or `timeoutMs`.
+     * Default **false** so hub fire-and-reconcile stays fast (hub #55).
+     */
+    confirm?: boolean;
+    /** Max poll ms when `confirm: true` (default 20_000, under hub 25s). */
+    timeoutMs?: number;
+    /** Poll interval ms when confirming (default 1000). */
+    intervalMs?: number;
+}
+/** Result of `playmos.rounds.cancel` — may be async 202 cancelling (#346 / #376). */
 interface CancelRoundResult {
     roundId: string;
     txHash: `0x${string}` | null;
-    /** `"cancelling"` = broadcast accepted; `"cancelled"` = chain Cancelled(4) finalized. */
+    /**
+     * `"cancelling"` = broadcast accepted, **not** terminal success (series latch may
+     * still be held). `"cancelled"` = chain Cancelled(4) finalized — only then forget latch.
+     */
     status: "cancelling" | "cancelled";
     round?: RoundState;
 }
@@ -561,6 +595,12 @@ interface WithdrawResult {
     amountMicro: string;
     txHash?: `0x${string}`;
     status: "confirmed" | "failed" | "pending";
+    /**
+     * EIP-5792 calls id when the claim was submitted but not yet confirmed (#462).
+     * Present on `status: "pending"` so the studio can reconcile later — never treat
+     * a slow mining claim as a hard failure.
+     */
+    callsId?: string;
 }
 interface RoundSettleInput {
     roundId: string;
@@ -573,6 +613,14 @@ interface RoundSettleInput {
             amount: string;
         }[];
     };
+    /**
+     * Max ms to poll after async `status: "settling"` before returning honest non-terminal.
+     * Default **20_000** — below hub SdkEscrow op timeout (25s) so the answer can reach
+     * the hub before the outer race kills the call (#422).
+     */
+    timeoutMs?: number;
+    /** Poll interval ms while reconciling (default 1000, same as `transfers.wait`). */
+    intervalMs?: number;
 }
 /**
  * Result of `playmos.rounds.settle`.
@@ -603,7 +651,7 @@ interface SettleRoundResult {
  * EARLIEST possible layer: input errors fire client-side before any network or
  * chain call, so a studio never pays gas to discover a typo.
  */
-type PlaymosErrorCode = "invalid_amount" | "missing_field" | "insufficient_gas" | "wallet_connection" | "payment_failed" | "auth" | "api_error" | "config" | "nothing_to_withdraw";
+type PlaymosErrorCode = "invalid_amount" | "missing_field" | "insufficient_gas" | "wallet_connection" | "wallet_timeout" | "payment_failed" | "already_entered" | "auth" | "api_error" | "config" | "nothing_to_withdraw";
 declare class PlaymosError extends Error {
     readonly code: PlaymosErrorCode;
     /** Optional machine context (e.g. the offending field, the http status). */
@@ -626,10 +674,27 @@ declare class InsufficientGasError extends PlaymosError {
 declare class WalletConnectionError extends PlaymosError {
     constructor(message?: string, detail?: Record<string, unknown>);
 }
+/**
+ * A wallet `provider.request` call exceeded the per-request deadline (#462).
+ * Distinct from {@link WalletConnectionError}: provider is present but the sheet
+ * hung / popup was blocked / request never returned. Must NOT be treated as
+ * "no wallet" (that would silently route to server-settle).
+ */
+declare class WalletTimeoutError extends PlaymosError {
+    constructor(message?: string, detail?: Record<string, unknown>);
+}
 /** The on-chain settlement reverted, was cancelled, or timed out. */
 declare class PaymentFailedError extends PlaymosError {
     constructor(message?: string, detail?: Record<string, unknown>);
 }
+/**
+ * PrizePool already has an entry for this `(roundId, identity)` (#462 pay-per-play).
+ * Studios using the same identity (e.g. bare wallet) for every attempt hit this on
+ * the second paid play — pass a per-attempt identity for pay-per-play.
+ */
+declare class AlreadyEnteredError extends PlaymosError {
+    constructor(detail?: Record<string, unknown>);
+}
 /** Bad, missing, or wrong-environment API key (e.g. a pk_test_ key on a live route). */
 declare class AuthError extends PlaymosError {
     constructor(message?: string, detail?: Record<string, unknown>);
@@ -650,4 +715,4 @@ declare class NothingToWithdrawError extends PlaymosError {
     constructor(detail?: Record<string, unknown>);
 }
 
-export { WalletConnectionError as $, type ActiveSeriesRound as A, InvalidAmountError as B, type CancelRoundResult as C, type ListingStatus as D, type EscrowHoldInput as E, type MarketplaceItem as F, type GasConfig as G, type MarketplaceSale as H, InsufficientGasError as I, MissingFieldError as J, NothingToWithdrawError as K, type Listing as L, type MarketplaceListInput as M, type Network as N, PaymentFailedError as O, type PlaymosConfig as P, type PaymentStatus as Q, type RoundOpenInput as R, type SettleRoundResult as S, type TransferResult as T, PlaymosError as U, type VerifyResult as V, type WebhookEvent as W, type PlaymosErrorCode as X, type RetryOptions as Y, type RoundStatus as Z, type WalletConfig as _, type RoundState as a, type WalletConnector as a0, type WebhookEventType as a1, type RoundSettleInput as b, type PrizeBalance as c, type WithdrawResult as d, type AgentWallet as e, type AgentFundResult as f, type EscrowHoldResult as g, type EscrowResolveResult as h, type MarketplaceSaleResult as i, type MarketplaceGetResult as j, type PayInput as k, type Payment as l, type EnterRoundInput as m, type TransferReconcile as n, type WaitOptions as o, type TransferInput as p, type TransferConfirmOptions as q, type PayoutRule as r, type ActiveForSeriesResult as s, type AgentEconomyConfig as t, ApiError as u, AuthError as v, ConfigError as w, type ContractConfig as x, type Eip1193Provider as y, type GasMode as z };
+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 };

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

@@ -28,6 +28,7 @@ interface WalletConfig {
     /**
      * 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.
      */
     provider?: Eip1193Provider;
 }
@@ -73,6 +74,13 @@ interface PlaymosConfig {
      *   retry: { maxRetries }  → tune attempts / backoff (0 also opts out)
      */
     retry?: boolean | RetryOptions;
+    /**
+     * Timeout for **connect / `eth_requestAccounts` only** (#462). Default 20_000.
+     * Does **not** bound the payment confirmation sheet (`wallet_sendCalls`) — a short
+     * guess there can take the player's USDC without recording the entry (PR #463 residual).
+     * Machine RPCs (status polls, balance, chainId) use a separate internal 20s bound.
+     */
+    connectTimeoutMs?: number;
 }
 /** Tuning for the automatic 429 retry (all optional; sane defaults). */
 interface RetryOptions {
@@ -152,9 +160,12 @@ interface EnterRoundInput {
      */
     roundKey?: string;
     /**
-     * Advanced: the EXACT on-chain identity for this paid attempt (e.g.
-     * "0xWallet#nonce"). Overrides the server-generated identity so the on-chain
-     * entry and your server's `hasEntered` check line up. One entry per identity.
+     * On-chain entrant id for this paid attempt (e.g. `"0xWallet#nonce"`).
+     * **Required on the client-signed (player wallet) path** so hub `hasEntered`
+     * matches (#374 / #466). **One entry per identity** — use a **unique value per
+     * paid attempt** (pay-per-play); reusing the same identity hits AlreadyEntered.
+     * Omit only on no-wallet sandbox server-settle smoke (service may derive).
+     * `entryProvider().payEntry` always supplies the kit identity.
      */
     identity?: string;
 }
@@ -532,11 +543,34 @@ interface ActiveForSeriesResult {
     via: "chain" | "cache";
     active: ActiveSeriesRound | null;
 }
-/** Result of `playmos.rounds.cancel` — may be async 202 cancelling (#346). */
+/**
+ * Input to `playmos.rounds.cancel` (#346 / #376).
+ *
+ * Default is **submit-only**: returns `status: "cancelling"` after broadcast without
+ * inventing success. Pass `confirm: true` to poll until `cancelled` or timeout
+ * (still returns honest `cancelling` on timeout — never pretends terminal).
+ */
+interface RoundCancelInput {
+    roundId: string;
+    gameId?: string;
+    /**
+     * When true, poll re-POST cancel + GET until `cancelled` or `timeoutMs`.
+     * Default **false** so hub fire-and-reconcile stays fast (hub #55).
+     */
+    confirm?: boolean;
+    /** Max poll ms when `confirm: true` (default 20_000, under hub 25s). */
+    timeoutMs?: number;
+    /** Poll interval ms when confirming (default 1000). */
+    intervalMs?: number;
+}
+/** Result of `playmos.rounds.cancel` — may be async 202 cancelling (#346 / #376). */
 interface CancelRoundResult {
     roundId: string;
     txHash: `0x${string}` | null;
-    /** `"cancelling"` = broadcast accepted; `"cancelled"` = chain Cancelled(4) finalized. */
+    /**
+     * `"cancelling"` = broadcast accepted, **not** terminal success (series latch may
+     * still be held). `"cancelled"` = chain Cancelled(4) finalized — only then forget latch.
+     */
     status: "cancelling" | "cancelled";
     round?: RoundState;
 }
@@ -561,6 +595,12 @@ interface WithdrawResult {
     amountMicro: string;
     txHash?: `0x${string}`;
     status: "confirmed" | "failed" | "pending";
+    /**
+     * EIP-5792 calls id when the claim was submitted but not yet confirmed (#462).
+     * Present on `status: "pending"` so the studio can reconcile later — never treat
+     * a slow mining claim as a hard failure.
+     */
+    callsId?: string;
 }
 interface RoundSettleInput {
     roundId: string;
@@ -573,6 +613,14 @@ interface RoundSettleInput {
             amount: string;
         }[];
     };
+    /**
+     * Max ms to poll after async `status: "settling"` before returning honest non-terminal.
+     * Default **20_000** — below hub SdkEscrow op timeout (25s) so the answer can reach
+     * the hub before the outer race kills the call (#422).
+     */
+    timeoutMs?: number;
+    /** Poll interval ms while reconciling (default 1000, same as `transfers.wait`). */
+    intervalMs?: number;
 }
 /**
  * Result of `playmos.rounds.settle`.
@@ -603,7 +651,7 @@ interface SettleRoundResult {
  * EARLIEST possible layer: input errors fire client-side before any network or
  * chain call, so a studio never pays gas to discover a typo.
  */
-type PlaymosErrorCode = "invalid_amount" | "missing_field" | "insufficient_gas" | "wallet_connection" | "payment_failed" | "auth" | "api_error" | "config" | "nothing_to_withdraw";
+type PlaymosErrorCode = "invalid_amount" | "missing_field" | "insufficient_gas" | "wallet_connection" | "wallet_timeout" | "payment_failed" | "already_entered" | "auth" | "api_error" | "config" | "nothing_to_withdraw";
 declare class PlaymosError extends Error {
     readonly code: PlaymosErrorCode;
     /** Optional machine context (e.g. the offending field, the http status). */
@@ -626,10 +674,27 @@ declare class InsufficientGasError extends PlaymosError {
 declare class WalletConnectionError extends PlaymosError {
     constructor(message?: string, detail?: Record<string, unknown>);
 }
+/**
+ * A wallet `provider.request` call exceeded the per-request deadline (#462).
+ * Distinct from {@link WalletConnectionError}: provider is present but the sheet
+ * hung / popup was blocked / request never returned. Must NOT be treated as
+ * "no wallet" (that would silently route to server-settle).
+ */
+declare class WalletTimeoutError extends PlaymosError {
+    constructor(message?: string, detail?: Record<string, unknown>);
+}
 /** The on-chain settlement reverted, was cancelled, or timed out. */
 declare class PaymentFailedError extends PlaymosError {
     constructor(message?: string, detail?: Record<string, unknown>);
 }
+/**
+ * PrizePool already has an entry for this `(roundId, identity)` (#462 pay-per-play).
+ * Studios using the same identity (e.g. bare wallet) for every attempt hit this on
+ * the second paid play — pass a per-attempt identity for pay-per-play.
+ */
+declare class AlreadyEnteredError extends PlaymosError {
+    constructor(detail?: Record<string, unknown>);
+}
 /** Bad, missing, or wrong-environment API key (e.g. a pk_test_ key on a live route). */
 declare class AuthError extends PlaymosError {
     constructor(message?: string, detail?: Record<string, unknown>);
@@ -650,4 +715,4 @@ declare class NothingToWithdrawError extends PlaymosError {
     constructor(detail?: Record<string, unknown>);
 }
 
-export { WalletConnectionError as $, type ActiveSeriesRound as A, InvalidAmountError as B, type CancelRoundResult as C, type ListingStatus as D, type EscrowHoldInput as E, type MarketplaceItem as F, type GasConfig as G, type MarketplaceSale as H, InsufficientGasError as I, MissingFieldError as J, NothingToWithdrawError as K, type Listing as L, type MarketplaceListInput as M, type Network as N, PaymentFailedError as O, type PlaymosConfig as P, type PaymentStatus as Q, type RoundOpenInput as R, type SettleRoundResult as S, type TransferResult as T, PlaymosError as U, type VerifyResult as V, type WebhookEvent as W, type PlaymosErrorCode as X, type RetryOptions as Y, type RoundStatus as Z, type WalletConfig as _, type RoundState as a, type WalletConnector as a0, type WebhookEventType as a1, type RoundSettleInput as b, type PrizeBalance as c, type WithdrawResult as d, type AgentWallet as e, type AgentFundResult as f, type EscrowHoldResult as g, type EscrowResolveResult as h, type MarketplaceSaleResult as i, type MarketplaceGetResult as j, type PayInput as k, type Payment as l, type EnterRoundInput as m, type TransferReconcile as n, type WaitOptions as o, type TransferInput as p, type TransferConfirmOptions as q, type PayoutRule as r, type ActiveForSeriesResult as s, type AgentEconomyConfig as t, ApiError as u, AuthError as v, ConfigError as w, type ContractConfig as x, type Eip1193Provider as y, type GasMode as z };
+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 };