@playmos/sdk 0.3.13 → 0.3.15

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to `@playmos/sdk`. This project adheres to [Semantic Version
 
 ## Unreleased
 
+## [0.3.15] — 2026-09-11
+
+### Added
+- **`epochs.prepareSeries`** / `POST /v1/epochs/series/prepare` — after register, one call returns an unsigned `createSeries` tx (`broadcast: false`, default `feeBps` 100). The studio EOA signs. Playmos never broadcasts. (#742 / #739)
+
+### Fixed (service)
+- Studio-operated pool `POST /v1/epochs/:epochId/settle` returns 4xx naming `settleEpoch` / `executeSignedSettlement`, not a product 502/504. (#741 / #736)
+
+## [0.3.14] — 2026-09-11
+
+### Added
+- **`settle: "server"`** on `new Playmos({ ... })` — explicit sandbox no-wallet path. `pay()` / `enterRound()` server-settle even when MetaMask is installed. Live keys throw. Default without the ask is unchanged (wallet present → player signs).
+
 ## [0.3.13] — 2026-09-11
 
 ### Docs

package/README.md

@@ -16,14 +16,14 @@ Requires **Node 18 / 20 / 22 LTS** for local development and CI toolchains. Full
 
 ## Browser vs server entry
 
-- **Games (browser / Vite / Phaser):** `import { Playmos } from "@playmos/sdk"` — this entry is browser-safe and does **not** import Node `crypto` (issue #9).
+- **Games (browser / Vite / Phaser):** `import { Playmos } from "@playmos/sdk"` — this entry is browser-safe and does **not** import Node `crypto` (issue #9). The package depends on **viem**; the named import tree-shakes, but a default Vite single chunk can still exceed 500 kB gzip-warn.
 - **Your backend (webhook receivers):** `import { verifyWebhook } from "@playmos/sdk/server"` — HMAC verification uses Node crypto and must stay off the client bundle.
 
 The sandbox API also sends CORS headers so browser `pay()` / `enterRound()` work without a same-origin proxy (issue #10).
 
 ## Quickstart — the no-wallet sandbox
 
-The public sandbox key `pk_test_playmos_sandbox` runs against a real Playmos test service on Base Sepolia. **You don't need a wallet:** on a `pk_test` key with no `wallet` configured, the SDK routes to a server-settle path where Playmos signs and submits the on-chain transaction for you. You still get a real, confirmed `txHash` — just signed by the service. No wallet, no gas, no crypto.
+The public sandbox key `pk_test_playmos_sandbox` runs against a real Playmos test service on Base Sepolia. **You don't need a wallet:** set `settle: "server"` (the quickstart does). The SDK then server-settles even if MetaMask is installed. You still get a real, confirmed `txHash` — signed by the service. No wallet, no gas, no crypto. Omit `settle` only when you want the player to sign.
 
 The public key is wired to `game_sandbox_iap`. Skill entry (`game_sandbox_skill`) is an optional later path — not the first-hour default.
 
@@ -35,7 +35,7 @@ import { Playmos } from "@playmos/sdk";
 
 // Public sandbox key — client-safe, like Stripe's pk_test_.
 // No wallet needed: Playmos server-settles the test payment for you.
-const playmos = new Playmos({ apiKey: "pk_test_playmos_sandbox" });
+const playmos = new Playmos({ apiKey: "pk_test_playmos_sandbox", settle: "server" });
 
 const payment = await playmos.pay({
   gameId: "game_sandbox_iap", // required for the public sandbox key
@@ -51,6 +51,9 @@ while (result.status !== "confirmed" && tries !== 0) {
   result = await playmos.verify(payment.id);
   tries -= 1;
 }
+if (result.status !== "confirmed") {
+  throw new Error(`not confirmed yet: ${result.status}`);
+}
 
 console.log({ id: payment.id, status: result.status, tx: payment.txHash });
 // You won: pay_… + confirmed on Base Sepolia
@@ -78,24 +81,29 @@ if (result.status === "confirmed") {
 ### Optional later — skill-game entry (`enterRound()`)
 
 ```ts
+const idempotencyKey = "entry-player_abc"; // persist BEFORE enterRound
 const entry = await playmos.enterRound({
   gameId: "game_sandbox_skill",
   roundId: "5m-5944009",
   amount: "1.00",         // grows this round's pool
   playerId: "player_abc",
+  idempotencyKey,
 });
-// entry.status === "confirmed". Public sandbox skill is a shared Playmos pool — not your contest.
-// Your 1% contest is live only after you register your own pool (next section).
+// entry.status === "confirmed". Public sandbox skill is a shared Playmos pool —
+// not your contest and not your published take. Persist entry.identity
+// (sandbox#entry_…) when there is no wallet. Same $1.00/request cap as pay().
+// Your 1% is IAP pay() and your own registered pool (next section).
 ```
 
 ### Your own contest pool — `epochs.preparePool` (you sign)
 
-`@playmos/sdk` **0.3.13** ships `epochs.preparePool` with `bytecode` / `unsignedTx` on the typed response. It calls the live API. Playmos sets `broadcast: false` and does **not** send the transaction.
+`@playmos/sdk` **0.3.15** ships `epochs.preparePool` and `epochs.prepareSeries` with `unsignedTx` on the typed response. It calls the live API. Playmos sets `broadcast: false` and does **not** send the transaction.
 
 1. Fund your studio wallet on Base Sepolia (ETH + test USDC). Playmos has no faucet — use [Coinbase's faucet docs](https://docs.cdp.coinbase.com/faucets/introduction/welcome).
 2. Call `epochs.preparePool({ studioWallet })` or `POST /v1/epochs/pools/prepare`. Use `feeSink` from that response (`0xD84c190085aa59c48a9B478Ea333D50B8DF4aD42`).
 3. Sign `unsignedTx` in your wallet and send it.
-4. `epochs.registerPool` with `walletProof`, then open / enter **your** game — not the shared sandbox game.
+4. `epochs.registerPool` with `walletProof`.
+5. `epochs.prepareSeries` — one returned `unsignedTx`, you sign in the same EOA. Then `GET /v1/epochs/series` until `created=true`, then enter **your** game — not the shared sandbox game.
 
 Full steps: https://playmos-docs-public.vercel.app/docs#studio-pool-prepare
 

package/dist/{chunk-TZFGZNXV.js → chunk-ROWX6HVU.js}

@@ -345,6 +345,23 @@ var epochPrizePoolViewAbi = [
     outputs: [{ type: "uint256" }]
   }
 ];
+var epochPrizePoolCreateSeriesAbi = [
+  {
+    type: "function",
+    name: "createSeries",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "series", type: "bytes32" },
+      { name: "genesis", type: "uint256" },
+      { name: "epochDuration", type: "uint256" },
+      { name: "entry", type: "uint256" },
+      { name: "feeBps", type: "uint16" },
+      { name: "poolBps", type: "uint16" },
+      { name: "seedBps", type: "uint16" }
+    ],
+    outputs: []
+  }
+];
 var epochPrizePoolEnterAbi = [
   {
     type: "function",
@@ -442,4 +459,4 @@ function buildEpochExecuteSettlementCall(args) {
   };
 }
 
-export { AlreadyEnteredError, ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError, WalletTimeoutError, assertEnoughGas, buildEntryCalls, buildEpochExecuteSettlementCall, buildIapCalls, buildWithdrawCall, encodeApprove, epochPrizePoolEnterAbi, epochPrizePoolRefundAbi, epochPrizePoolViewAbi, identityToBytes32, prizePoolAbi, sendCalls, seriesToBytes32, toBytes32, waitForCalls };
+export { AlreadyEnteredError, ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError, WalletTimeoutError, assertEnoughGas, buildEntryCalls, buildEpochExecuteSettlementCall, buildIapCalls, buildWithdrawCall, encodeApprove, epochPrizePoolCreateSeriesAbi, epochPrizePoolEnterAbi, epochPrizePoolRefundAbi, epochPrizePoolViewAbi, identityToBytes32, prizePoolAbi, sendCalls, seriesToBytes32, toBytes32, waitForCalls };

package/dist/{errors-CYKgt2VU.d.cts → errors-WcDNfb4q.d.cts}

@@ -76,6 +76,13 @@ interface PlaymosConfig {
      * even mock results use the REAL status union (never a synthetic "mocked").
      */
     mock?: boolean;
+    /**
+     * Explicit sandbox no-wallet path. On a test key, `pay()` / `enterRound()`
+     * server-settle even if MetaMask (or another injected wallet) is installed.
+     * Live keys (`pk_live_` / `sk_live_`) throw — never server-settle real money.
+     * Omit to keep today's default: server-settle only when no wallet is present.
+     */
+    settle?: "server";
     /**
      * Automatic backoff/retry on HTTP 429 (throttling). Default ON (up to 2 retries,
      * honoring a `Retry-After` header). Retries are safe — reads are idempotent and

package/dist/{errors-CYKgt2VU.d.ts → errors-WcDNfb4q.d.ts}

@@ -76,6 +76,13 @@ interface PlaymosConfig {
      * even mock results use the REAL status union (never a synthetic "mocked").
      */
     mock?: boolean;
+    /**
+     * Explicit sandbox no-wallet path. On a test key, `pay()` / `enterRound()`
+     * server-settle even if MetaMask (or another injected wallet) is installed.
+     * Live keys (`pk_live_` / `sk_live_`) throw — never server-settle real money.
+     * Omit to keep today's default: server-settle only when no wallet is present.
+     */
+    settle?: "server";
     /**
      * Automatic backoff/retry on HTTP 429 (throttling). Default ON (up to 2 retries,
      * honoring a `Retry-After` header). Retries are safe — reads are idempotent and

package/dist/index.cjs

@@ -929,6 +929,23 @@ var epochPrizePoolViewAbi = [
     outputs: [{ type: "uint256" }]
   }
 ];
+var epochPrizePoolCreateSeriesAbi = [
+  {
+    type: "function",
+    name: "createSeries",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "series", type: "bytes32" },
+      { name: "genesis", type: "uint256" },
+      { name: "epochDuration", type: "uint256" },
+      { name: "entry", type: "uint256" },
+      { name: "feeBps", type: "uint16" },
+      { name: "poolBps", type: "uint16" },
+      { name: "seedBps", type: "uint16" }
+    ],
+    outputs: []
+  }
+];
 var epochPrizePoolEnterAbi = [
   {
     type: "function",
@@ -1136,6 +1153,9 @@ function encodeEpochPoolConstructorArgs(args) {
     args.refundTimeout
   ]);
 }
+var LOCKED_SERIES_FEE_BPS = 100;
+var DEFAULT_SERIES_POOL_BPS = 7900;
+var DEFAULT_SERIES_SEED_BPS = 2e3;
 function derivedEpochId(genesis, epochDuration, at) {
   if (epochDuration === 0n) {
     throw new ConfigError("epochDuration must be > 0");
@@ -1304,6 +1324,66 @@ function walletStatus(status) {
 function sameAddr(a, b) {
   return a.toLowerCase() === b.toLowerCase();
 }
+function parseSeriesBps(raw, field) {
+  if (raw === void 0) return void 0;
+  if (!Number.isInteger(raw) || raw < 0) {
+    throw new ConfigError(`${field} must be a non-negative integer`);
+  }
+  return raw;
+}
+function prepareSeriesLocal(input, chainId) {
+  const pool = requireAddr(input.epochPrizePool, "epochPrizePool");
+  const series = requireSeries(input.series);
+  const feeBps = parseSeriesBps(input.feeBps, "feeBps");
+  if (feeBps !== void 0 && feeBps !== LOCKED_SERIES_FEE_BPS) {
+    throw new ConfigError(
+      "feeBps must be 100 (the locked 1% Playmos take); refused before anything signable"
+    );
+  }
+  const poolBps = parseSeriesBps(input.poolBps, "poolBps") ?? DEFAULT_SERIES_POOL_BPS;
+  const seedBps = parseSeriesBps(input.seedBps, "seedBps") ?? DEFAULT_SERIES_SEED_BPS;
+  if (LOCKED_SERIES_FEE_BPS + poolBps + seedBps !== 1e4) {
+    throw new ConfigError("feeBps + poolBps + seedBps must sum to 10000 (fee is 100)");
+  }
+  const epochDuration = toBig(input.epochDuration, 0n);
+  const entry = toBig(input.entry, 0n);
+  if (epochDuration <= 0n) throw new ConfigError("epochDuration must be greater than 0");
+  if (entry <= 0n) throw new ConfigError("entry must be greater than 0");
+  const genesis = toBig(input.genesis, BigInt(Math.floor(Date.now() / 1e3)));
+  if (genesis <= 0n) throw new ConfigError("genesis must be greater than 0");
+  const data = viem.encodeFunctionData({
+    abi: epochPrizePoolCreateSeriesAbi,
+    functionName: "createSeries",
+    args: [
+      seriesToBytes32(series),
+      genesis,
+      epochDuration,
+      entry,
+      LOCKED_SERIES_FEE_BPS,
+      poolBps,
+      seedBps
+    ]
+  });
+  return {
+    series,
+    epochPrizePool: pool,
+    genesis: genesis.toString(),
+    epochDuration: epochDuration.toString(),
+    entry: entry.toString(),
+    feeBps: 100,
+    poolBps,
+    seedBps,
+    unsignedTx: {
+      chainId,
+      to: pool,
+      value: "0",
+      data
+    },
+    broadcast: false,
+    via: "mock",
+    mock: true
+  };
+}
 function prepareStudioPoolLocal(input, playmosFeeSink, token, playmosAddresses = []) {
   const studio = requireAddr(input.studioWallet, "studioWallet");
   const locked = PLAYMOS_FEE_SINK_DEFAULT;
@@ -1452,6 +1532,7 @@ async function readEpochTerminal(deps, pool, series, epochId) {
   }
 }
 function createEpochsApi(deps) {
+  const mockPreparedSeries = /* @__PURE__ */ new Map();
   return {
     async currentId(input) {
       const series = requireSeries(input?.series);
@@ -1529,6 +1610,9 @@ function createEpochsApi(deps) {
       const series = requireSeries(input?.series);
       const cfg = deps.config();
       if (cfg.mock) {
+        const pool = (input.epochPrizePool ?? cfg.contracts?.epochPrizePool ?? "").toLowerCase();
+        const prepared = mockPreparedSeries.get(`${pool}:${series}`);
+        if (prepared) return prepared;
         return {
           series,
           created: true,
@@ -1549,6 +1633,42 @@ function createEpochsApi(deps) {
       })}`;
       return deps.http().get(path);
     },
+    async prepareSeries(input) {
+      const feeBps = input?.feeBps;
+      if (feeBps !== void 0 && feeBps !== LOCKED_SERIES_FEE_BPS) {
+        throw new ConfigError(
+          "feeBps must be 100 (the locked 1% Playmos take); refused before anything signable"
+        );
+      }
+      const cfg = deps.config();
+      if (cfg.mock) {
+        const prepared = prepareSeriesLocal(input, CHAIN_ID["base-sepolia"]);
+        mockPreparedSeries.set(`${prepared.epochPrizePool}:${prepared.series}`, {
+          series: prepared.series,
+          created: true,
+          genesis: prepared.genesis,
+          epochDuration: prepared.epochDuration,
+          entry: prepared.entry,
+          feeBps: prepared.feeBps,
+          poolBps: prepared.poolBps,
+          seedBps: prepared.seedBps,
+          via: "mock",
+          epochPrizePool: prepared.epochPrizePool,
+          mock: true
+        });
+        return prepared;
+      }
+      return deps.http().post("/epochs/series/prepare", {
+        epochPrizePool: requireAddr(input?.epochPrizePool, "epochPrizePool"),
+        series: requireSeries(input?.series),
+        epochDuration: input.epochDuration,
+        entry: input.entry,
+        genesis: input.genesis,
+        feeBps: input.feeBps,
+        poolBps: input.poolBps,
+        seedBps: input.seedBps
+      });
+    },
     async preparePool(input) {
       const studioWallet = requireAddr(input?.studioWallet, "studioWallet");
       const cfg = deps.config();
@@ -2262,7 +2382,7 @@ var Playmos = class {
       },
       walletAddress: async () => getAccount(this.walletProvider()),
       readView: async (to, data) => {
-        if (await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
+        if (!await this.shouldServerSettle() && await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
           const provider = this.walletProvider();
           return await provider.request({
             method: "eth_call",
@@ -3363,8 +3483,14 @@ var Playmos = class {
         );
       }
     }
+    if (config.settle === "server" && !this.env.isTest) {
+      throw new ConfigError(
+        'settle: "server" is sandbox-only. Live keys must use a player wallet \u2014 never server-settle real money.',
+        { field: "settle" }
+      );
+    }
     this.http = createHttpClient(this.env.apiBaseUrl, config.apiKey, config.retry);
-    if (!config.mock) {
+    if (!config.mock && config.settle !== "server") {
       try {
         resolveProvider(config.wallet, this.walletTimeoutPolicy());
       } catch {
@@ -3434,6 +3560,23 @@ var Playmos = class {
       return 0n;
     }
   }
+  /**
+   * Sandbox server-settle when the developer asked (`settle: "server"`) or when
+   * a test key has no wallet. Never calls walletAvailable if the ask is set —
+   * that is the MetaMask-hijack delete (Moonhop leftover Slice 1).
+   */
+  async shouldServerSettle() {
+    if (this.config.settle === "server") {
+      if (!this.env.isTest) {
+        throw new ConfigError(
+          'settle: "server" is sandbox-only. Live keys must use a player wallet \u2014 never server-settle real money.',
+          { field: "settle" }
+        );
+      }
+      return true;
+    }
+    return this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy());
+  }
   /**
    * Wallet timeout policy (#462 / PR #463 residual).
    * - connectTimeoutMs → eth_requestAccounts only
@@ -3561,7 +3704,7 @@ var Playmos = class {
         heldIdem ? { key: heldIdem, terms } : void 0
       );
     }
-    if (this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
+    if (await this.shouldServerSettle()) {
       const res = await this.http.post(
         "/payments",
         {
@@ -3666,7 +3809,7 @@ var Playmos = class {
         heldIdem ? { key: heldIdem, terms } : void 0
       );
     }
-    const serverSettleNoWallet = this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy());
+    const serverSettleNoWallet = await this.shouldServerSettle();
     if (!serverSettleNoWallet) {
       const pinned = typeof input.identity === "string" ? input.identity.trim() : "";
       if (!pinned) {
@@ -3996,7 +4139,7 @@ var Playmos = class {
     });
     let raw;
     try {
-      if (await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
+      if (!await this.shouldServerSettle() && await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
         const provider = this.walletProvider();
         raw = await provider.request({
           method: "eth_call",
@@ -4215,8 +4358,11 @@ exports.C1_ENTER_SPLIT_MICRO = C1_ENTER_SPLIT_MICRO;
 exports.CHAIN_ID = CHAIN_ID;
 exports.ConfigError = ConfigError;
 exports.DEFAULT_API_BASE_URL = DEFAULT_API_BASE_URL;
+exports.DEFAULT_SERIES_POOL_BPS = DEFAULT_SERIES_POOL_BPS;
+exports.DEFAULT_SERIES_SEED_BPS = DEFAULT_SERIES_SEED_BPS;
 exports.InsufficientGasError = InsufficientGasError;
 exports.InvalidAmountError = InvalidAmountError;
+exports.LOCKED_SERIES_FEE_BPS = LOCKED_SERIES_FEE_BPS;
 exports.MICRO_PER_USDC = MICRO_PER_USDC;
 exports.MissingFieldError = MissingFieldError;
 exports.NothingToWithdrawError = NothingToWithdrawError;
@@ -4256,6 +4402,7 @@ exports.networkToCaip2 = networkToCaip2;
 exports.parsePaymentRequirement = parsePaymentRequirement;
 exports.parseUsdToMicro = parseUsdToMicro;
 exports.prefixedId = prefixedId;
+exports.prepareSeriesLocal = prepareSeriesLocal;
 exports.prepareStudioPoolLocal = prepareStudioPoolLocal;
 exports.previewEscrowFee = previewEscrowFee;
 exports.previewIapSplit = previewIapSplit;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { C as Call, P as PlaymosConfig, O as OnchainStatus, N as Network, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, c as RoundCancelInput, d as CancelRoundResult, e as RoundGetResult, A as ActiveSeriesRound, f as PayoutNoticesResult, g as PrizeBalance, h as WithdrawResult, i as AgentWallet, j as AgentFundResult, T as TransferResult, E as EscrowHoldInput, k as EscrowHoldResult, l as EscrowResolveResult, M as MarketplaceListInput, L as Listing, m as MarketplaceSaleResult, n as MarketplaceGetResult, o as PayInput, p as Payment, q as EnterRoundInput, r as TransferReconcile, s as WaitOptions, t as TransferInput, u as TransferConfirmOptions, V as VerifyResult, v as PayoutRule } from './errors-CYKgt2VU.cjs';
-export { w as ActiveForSeriesResult, x as AgentEconomyConfig, y as AlreadyEnteredError, z as ApiError, B as AuthError, D as ConfigError, F as ContractConfig, G as Eip1193Provider, H as GasConfig, I as GasMode, J as InsufficientGasError, K as InvalidAmountError, Q as ListingStatus, U as MarketplaceItem, X as MarketplaceSale, Y as MissingFieldError, Z as NothingToWithdrawError, _ as PaymentFailedError, $ as PaymentStatus, a0 as PayoutNotice, a1 as PayoutNoticeStatus, a2 as PlaymosError, a3 as PlaymosErrorCode, a4 as RetryOptions, a5 as RoundGetVia, a6 as RoundStatus, a7 as WalletConfig, a8 as WalletConnectionError, a9 as WalletConnector, aa as WalletTimeoutError, ab as WebhookEventType, ac as buildEpochExecuteSettlementCall } from './errors-CYKgt2VU.cjs';
+import { C as Call, P as PlaymosConfig, O as OnchainStatus, N as Network, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, c as RoundCancelInput, d as CancelRoundResult, e as RoundGetResult, A as ActiveSeriesRound, f as PayoutNoticesResult, g as PrizeBalance, h as WithdrawResult, i as AgentWallet, j as AgentFundResult, T as TransferResult, E as EscrowHoldInput, k as EscrowHoldResult, l as EscrowResolveResult, M as MarketplaceListInput, L as Listing, m as MarketplaceSaleResult, n as MarketplaceGetResult, o as PayInput, p as Payment, q as EnterRoundInput, r as TransferReconcile, s as WaitOptions, t as TransferInput, u as TransferConfirmOptions, V as VerifyResult, v as PayoutRule } from './errors-WcDNfb4q.cjs';
+export { w as ActiveForSeriesResult, x as AgentEconomyConfig, y as AlreadyEnteredError, z as ApiError, B as AuthError, D as ConfigError, F as ContractConfig, G as Eip1193Provider, H as GasConfig, I as GasMode, J as InsufficientGasError, K as InvalidAmountError, Q as ListingStatus, U as MarketplaceItem, X as MarketplaceSale, Y as MissingFieldError, Z as NothingToWithdrawError, _ as PaymentFailedError, $ as PaymentStatus, a0 as PayoutNotice, a1 as PayoutNoticeStatus, a2 as PlaymosError, a3 as PlaymosErrorCode, a4 as RetryOptions, a5 as RoundGetVia, a6 as RoundStatus, a7 as WalletConfig, a8 as WalletConnectionError, a9 as WalletConnector, aa as WalletTimeoutError, ab as WebhookEventType, ac as buildEpochExecuteSettlementCall } from './errors-WcDNfb4q.cjs';
 
 /**
  * Thin REST client for the Playmos service. Every SDK method that touches the
@@ -88,6 +88,8 @@ declare function buildEpochWithdrawCall(epochPrizePool: `0x${string}`): Call;
  * `epochs.enter` — pay into whatever window the clock says is current; no open
  * gate. `epochs.preparePool` / `registerPool` / `createPool` — studio wallet
  * deploys the existing EpochPrizePool constructor; Playmos is feeSink only.
+ * `epochs.prepareSeries` — unsigned createSeries tx; studio EOA signs; Playmos
+ * never broadcasts (sdk#739).
  * `epochs.settle` — secret key, operator wallet, broadcast + 202. Passes the
  * roster through; does not build a hub roster (R7b).
  * `epochs.claimableRefund` / `claimRefund` / `withdraw` — wallet-direct on
@@ -243,6 +245,44 @@ interface EpochEntry {
     via: EpochReadVia;
     mock?: true;
 }
+/** Locked 1% Playmos take on a studio series. Any other fee is refused before signable bytes. */
+declare const LOCKED_SERIES_FEE_BPS = 100;
+/** Default prize-bucket bps when the studio does not type a split (fee 100 + seed 2000 = 10000). */
+declare const DEFAULT_SERIES_POOL_BPS = 7900;
+/** Default next-window seed bps when the studio does not type a split. */
+declare const DEFAULT_SERIES_SEED_BPS = 2000;
+interface EpochPrepareSeriesInput {
+    epochPrizePool: `0x${string}`;
+    series: string;
+    epochDuration: number | string;
+    /** Integer micro-USDC. */
+    entry: number | string;
+    genesis?: number | string;
+    /** Must be 100 if set — the locked 1% Playmos take. */
+    feeBps?: number;
+    poolBps?: number;
+    seedBps?: number;
+}
+interface EpochPreparedSeries {
+    series: string;
+    epochPrizePool: `0x${string}`;
+    genesis: string;
+    epochDuration: string;
+    entry: string;
+    feeBps: 100;
+    poolBps: number;
+    seedBps: number;
+    unsignedTx: {
+        chainId: number;
+        to: `0x${string}`;
+        value: "0";
+        data: `0x${string}`;
+    };
+    /** Playmos never broadcasts. Studio EOA sends. */
+    broadcast: false;
+    via: EpochReadVia;
+    mock?: true;
+}
 interface EpochPreparePoolInput {
     studioWallet: `0x${string}`;
     /** Must equal the Playmos sink if set; any other address is refused before broadcast. */
@@ -531,6 +571,7 @@ interface EpochsApi {
     prize(input: EpochPrizeInput): Promise<EpochPrize>;
     get(input: EpochGetInput): Promise<EpochView>;
     getSeries(input: EpochGetSeriesInput): Promise<EpochSeriesView>;
+    prepareSeries(input: EpochPrepareSeriesInput): Promise<EpochPreparedSeries>;
     preparePool(input: EpochPreparePoolInput): Promise<EpochPreparedPool>;
     registerPool(input: EpochRegisterPoolInput): Promise<EpochStudioPool>;
     createPool(input: EpochCreatePoolInput): Promise<EpochStudioPool>;
@@ -603,6 +644,8 @@ interface EpochsDeps {
 declare function derivedEpochId(genesis: bigint, epochDuration: bigint, at: bigint): bigint;
 /** Settle payable is inherited seed + this epoch's pool (not outgoingSeed). */
 declare function epochPayableMicro(incomingSeed: bigint, pool: bigint): bigint;
+/** Same refuse-before-signable posture as preparePool's feeSink check. */
+declare function prepareSeriesLocal(input: EpochPrepareSeriesInput, chainId: number): EpochPreparedSeries;
 /** Client-side pin — same refusals as the service, so a bad sink never reaches broadcast. */
 declare function prepareStudioPoolLocal(input: EpochPreparePoolInput, playmosFeeSink: `0x${string}`, token: `0x${string}`, playmosAddresses?: `0x${string}`[]): EpochPreparedPool;
 /**
@@ -1323,6 +1366,12 @@ declare class Playmos {
      */
     private readonly mockByIdempotencyKey;
     constructor(config: PlaymosConfig);
+    /**
+     * Sandbox server-settle when the developer asked (`settle: "server"`) or when
+     * a test key has no wallet. Never calls walletAvailable if the ask is set —
+     * that is the MetaMask-hijack delete (Moonhop leftover Slice 1).
+     */
+    private shouldServerSettle;
     /**
      * Wallet timeout policy (#462 / PR #463 residual).
      * - connectTimeoutMs → eth_requestAccounts only
@@ -1587,4 +1636,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, C1_ENTER_SPLIT_MICRO, CHAIN_ID, CancelRoundResult, type CreatePaymentRequirementInput, DEFAULT_API_BASE_URL, EnterRoundInput, type EpochAttestation, type EpochClaimRefundInput, type EpochClaimRefundResult, type EpochClaimableRefund, type EpochClaimableRefundInput, type EpochCreatePoolInput, type EpochCurrentId, type EpochCurrentIdInput, type EpochEnterInput, type EpochEntry, type EpochEntryStatus, type EpochExecuteSettlementInput, type EpochExecuteSettlementResult, type EpochGetAttestationInput, type EpochGetInput, type EpochGetSeriesInput, type EpochPoolOwnership, type EpochPoolWalletProof, type EpochPreparePoolInput, type EpochPreparedPool, type EpochPrize, type EpochPrizeInput, type EpochReadVia, type EpochRegisterPoolInput, type EpochSeriesView, type EpochSettleInput, type EpochSettleResult, type EpochSettleStatus, type EpochSettleWinner, type EpochStudioPool, type EpochTerminal, type EpochView, type EpochWinnerIn, type EpochWithdrawInput, type EpochWithdrawResult, type EpochsApi, EscrowHoldInput, EscrowHoldResult, EscrowResolveResult, Listing, MICRO_PER_USDC, MarketplaceGetResult, MarketplaceListInput, MarketplaceSaleResult, Network, PLAYMOS_FEE_SINK_DEFAULT, PayInput, Payment, type PaymentRequirement, PayoutError, PayoutNoticesResult, PayoutRule, PayoutRule as PayoutRuleCompute, Playmos, PlaymosConfig, PrizeBalance, RETIRED_PLAYMOS_FEE_SINK, RoundCancelInput, RoundGetResult, RoundOpenInput, RoundSettleInput, RoundState, SettleRoundResult, type SettlementAsset, type SettlementTypedData, type SettlementTypedDataInput, 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, buildEpochClaimRefundCall, buildEpochEntryCalls, buildEpochWithdrawCall, clientRuntimeSignals, computeIapSplit, computePayout, computePoolSplit, createEpochsApi, createPaymentRequirement, createX402Challenge, decodePaymentHeader, derivedEpochId, encodeEpochPoolConstructorArgs, encodePaymentHeader, epochPayableMicro, epochPoolProofMessage, formatMicroToUsd, identityToBytes32, isClientRuntime, isWalletSignatureAuthorization, isX402PayloadAuthorization, networkToCaip2, parsePaymentRequirement, parseUsdToMicro, prefixedId, prepareStudioPoolLocal, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, resolveEnv, serializePaymentRequirement, seriesToBytes32, settlementTypedData, toX402PaymentRequired, ulid, validateX402ChallengeInput };
+export { ActiveSeriesRound, AgentFundResult, AgentWallet, type Authorization, C1_ENTER_SPLIT_MICRO, CHAIN_ID, CancelRoundResult, type CreatePaymentRequirementInput, DEFAULT_API_BASE_URL, DEFAULT_SERIES_POOL_BPS, DEFAULT_SERIES_SEED_BPS, EnterRoundInput, type EpochAttestation, type EpochClaimRefundInput, type EpochClaimRefundResult, type EpochClaimableRefund, type EpochClaimableRefundInput, type EpochCreatePoolInput, type EpochCurrentId, type EpochCurrentIdInput, type EpochEnterInput, type EpochEntry, type EpochEntryStatus, type EpochExecuteSettlementInput, type EpochExecuteSettlementResult, type EpochGetAttestationInput, type EpochGetInput, type EpochGetSeriesInput, type EpochPoolOwnership, type EpochPoolWalletProof, type EpochPreparePoolInput, type EpochPrepareSeriesInput, type EpochPreparedPool, type EpochPreparedSeries, type EpochPrize, type EpochPrizeInput, type EpochReadVia, type EpochRegisterPoolInput, type EpochSeriesView, type EpochSettleInput, type EpochSettleResult, type EpochSettleStatus, type EpochSettleWinner, type EpochStudioPool, type EpochTerminal, type EpochView, type EpochWinnerIn, type EpochWithdrawInput, type EpochWithdrawResult, type EpochsApi, EscrowHoldInput, EscrowHoldResult, EscrowResolveResult, LOCKED_SERIES_FEE_BPS, Listing, MICRO_PER_USDC, MarketplaceGetResult, MarketplaceListInput, MarketplaceSaleResult, Network, PLAYMOS_FEE_SINK_DEFAULT, PayInput, Payment, type PaymentRequirement, PayoutError, PayoutNoticesResult, PayoutRule, PayoutRule as PayoutRuleCompute, Playmos, PlaymosConfig, PrizeBalance, RETIRED_PLAYMOS_FEE_SINK, RoundCancelInput, RoundGetResult, RoundOpenInput, RoundSettleInput, RoundState, SettleRoundResult, type SettlementAsset, type SettlementTypedData, type SettlementTypedDataInput, 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, buildEpochClaimRefundCall, buildEpochEntryCalls, buildEpochWithdrawCall, clientRuntimeSignals, computeIapSplit, computePayout, computePoolSplit, createEpochsApi, createPaymentRequirement, createX402Challenge, decodePaymentHeader, derivedEpochId, encodeEpochPoolConstructorArgs, encodePaymentHeader, epochPayableMicro, epochPoolProofMessage, formatMicroToUsd, identityToBytes32, isClientRuntime, isWalletSignatureAuthorization, isX402PayloadAuthorization, networkToCaip2, parsePaymentRequirement, parseUsdToMicro, prefixedId, prepareSeriesLocal, prepareStudioPoolLocal, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, resolveEnv, serializePaymentRequirement, seriesToBytes32, settlementTypedData, toX402PaymentRequired, ulid, validateX402ChallengeInput };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as Call, P as PlaymosConfig, O as OnchainStatus, N as Network, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, c as RoundCancelInput, d as CancelRoundResult, e as RoundGetResult, A as ActiveSeriesRound, f as PayoutNoticesResult, g as PrizeBalance, h as WithdrawResult, i as AgentWallet, j as AgentFundResult, T as TransferResult, E as EscrowHoldInput, k as EscrowHoldResult, l as EscrowResolveResult, M as MarketplaceListInput, L as Listing, m as MarketplaceSaleResult, n as MarketplaceGetResult, o as PayInput, p as Payment, q as EnterRoundInput, r as TransferReconcile, s as WaitOptions, t as TransferInput, u as TransferConfirmOptions, V as VerifyResult, v as PayoutRule } from './errors-CYKgt2VU.js';
-export { w as ActiveForSeriesResult, x as AgentEconomyConfig, y as AlreadyEnteredError, z as ApiError, B as AuthError, D as ConfigError, F as ContractConfig, G as Eip1193Provider, H as GasConfig, I as GasMode, J as InsufficientGasError, K as InvalidAmountError, Q as ListingStatus, U as MarketplaceItem, X as MarketplaceSale, Y as MissingFieldError, Z as NothingToWithdrawError, _ as PaymentFailedError, $ as PaymentStatus, a0 as PayoutNotice, a1 as PayoutNoticeStatus, a2 as PlaymosError, a3 as PlaymosErrorCode, a4 as RetryOptions, a5 as RoundGetVia, a6 as RoundStatus, a7 as WalletConfig, a8 as WalletConnectionError, a9 as WalletConnector, aa as WalletTimeoutError, ab as WebhookEventType, ac as buildEpochExecuteSettlementCall } from './errors-CYKgt2VU.js';
+import { C as Call, P as PlaymosConfig, O as OnchainStatus, N as Network, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, c as RoundCancelInput, d as CancelRoundResult, e as RoundGetResult, A as ActiveSeriesRound, f as PayoutNoticesResult, g as PrizeBalance, h as WithdrawResult, i as AgentWallet, j as AgentFundResult, T as TransferResult, E as EscrowHoldInput, k as EscrowHoldResult, l as EscrowResolveResult, M as MarketplaceListInput, L as Listing, m as MarketplaceSaleResult, n as MarketplaceGetResult, o as PayInput, p as Payment, q as EnterRoundInput, r as TransferReconcile, s as WaitOptions, t as TransferInput, u as TransferConfirmOptions, V as VerifyResult, v as PayoutRule } from './errors-WcDNfb4q.js';
+export { w as ActiveForSeriesResult, x as AgentEconomyConfig, y as AlreadyEnteredError, z as ApiError, B as AuthError, D as ConfigError, F as ContractConfig, G as Eip1193Provider, H as GasConfig, I as GasMode, J as InsufficientGasError, K as InvalidAmountError, Q as ListingStatus, U as MarketplaceItem, X as MarketplaceSale, Y as MissingFieldError, Z as NothingToWithdrawError, _ as PaymentFailedError, $ as PaymentStatus, a0 as PayoutNotice, a1 as PayoutNoticeStatus, a2 as PlaymosError, a3 as PlaymosErrorCode, a4 as RetryOptions, a5 as RoundGetVia, a6 as RoundStatus, a7 as WalletConfig, a8 as WalletConnectionError, a9 as WalletConnector, aa as WalletTimeoutError, ab as WebhookEventType, ac as buildEpochExecuteSettlementCall } from './errors-WcDNfb4q.js';
 
 /**
  * Thin REST client for the Playmos service. Every SDK method that touches the
@@ -88,6 +88,8 @@ declare function buildEpochWithdrawCall(epochPrizePool: `0x${string}`): Call;
  * `epochs.enter` — pay into whatever window the clock says is current; no open
  * gate. `epochs.preparePool` / `registerPool` / `createPool` — studio wallet
  * deploys the existing EpochPrizePool constructor; Playmos is feeSink only.
+ * `epochs.prepareSeries` — unsigned createSeries tx; studio EOA signs; Playmos
+ * never broadcasts (sdk#739).
  * `epochs.settle` — secret key, operator wallet, broadcast + 202. Passes the
  * roster through; does not build a hub roster (R7b).
  * `epochs.claimableRefund` / `claimRefund` / `withdraw` — wallet-direct on
@@ -243,6 +245,44 @@ interface EpochEntry {
     via: EpochReadVia;
     mock?: true;
 }
+/** Locked 1% Playmos take on a studio series. Any other fee is refused before signable bytes. */
+declare const LOCKED_SERIES_FEE_BPS = 100;
+/** Default prize-bucket bps when the studio does not type a split (fee 100 + seed 2000 = 10000). */
+declare const DEFAULT_SERIES_POOL_BPS = 7900;
+/** Default next-window seed bps when the studio does not type a split. */
+declare const DEFAULT_SERIES_SEED_BPS = 2000;
+interface EpochPrepareSeriesInput {
+    epochPrizePool: `0x${string}`;
+    series: string;
+    epochDuration: number | string;
+    /** Integer micro-USDC. */
+    entry: number | string;
+    genesis?: number | string;
+    /** Must be 100 if set — the locked 1% Playmos take. */
+    feeBps?: number;
+    poolBps?: number;
+    seedBps?: number;
+}
+interface EpochPreparedSeries {
+    series: string;
+    epochPrizePool: `0x${string}`;
+    genesis: string;
+    epochDuration: string;
+    entry: string;
+    feeBps: 100;
+    poolBps: number;
+    seedBps: number;
+    unsignedTx: {
+        chainId: number;
+        to: `0x${string}`;
+        value: "0";
+        data: `0x${string}`;
+    };
+    /** Playmos never broadcasts. Studio EOA sends. */
+    broadcast: false;
+    via: EpochReadVia;
+    mock?: true;
+}
 interface EpochPreparePoolInput {
     studioWallet: `0x${string}`;
     /** Must equal the Playmos sink if set; any other address is refused before broadcast. */
@@ -531,6 +571,7 @@ interface EpochsApi {
     prize(input: EpochPrizeInput): Promise<EpochPrize>;
     get(input: EpochGetInput): Promise<EpochView>;
     getSeries(input: EpochGetSeriesInput): Promise<EpochSeriesView>;
+    prepareSeries(input: EpochPrepareSeriesInput): Promise<EpochPreparedSeries>;
     preparePool(input: EpochPreparePoolInput): Promise<EpochPreparedPool>;
     registerPool(input: EpochRegisterPoolInput): Promise<EpochStudioPool>;
     createPool(input: EpochCreatePoolInput): Promise<EpochStudioPool>;
@@ -603,6 +644,8 @@ interface EpochsDeps {
 declare function derivedEpochId(genesis: bigint, epochDuration: bigint, at: bigint): bigint;
 /** Settle payable is inherited seed + this epoch's pool (not outgoingSeed). */
 declare function epochPayableMicro(incomingSeed: bigint, pool: bigint): bigint;
+/** Same refuse-before-signable posture as preparePool's feeSink check. */
+declare function prepareSeriesLocal(input: EpochPrepareSeriesInput, chainId: number): EpochPreparedSeries;
 /** Client-side pin — same refusals as the service, so a bad sink never reaches broadcast. */
 declare function prepareStudioPoolLocal(input: EpochPreparePoolInput, playmosFeeSink: `0x${string}`, token: `0x${string}`, playmosAddresses?: `0x${string}`[]): EpochPreparedPool;
 /**
@@ -1323,6 +1366,12 @@ declare class Playmos {
      */
     private readonly mockByIdempotencyKey;
     constructor(config: PlaymosConfig);
+    /**
+     * Sandbox server-settle when the developer asked (`settle: "server"`) or when
+     * a test key has no wallet. Never calls walletAvailable if the ask is set —
+     * that is the MetaMask-hijack delete (Moonhop leftover Slice 1).
+     */
+    private shouldServerSettle;
     /**
      * Wallet timeout policy (#462 / PR #463 residual).
      * - connectTimeoutMs → eth_requestAccounts only
@@ -1587,4 +1636,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, C1_ENTER_SPLIT_MICRO, CHAIN_ID, CancelRoundResult, type CreatePaymentRequirementInput, DEFAULT_API_BASE_URL, EnterRoundInput, type EpochAttestation, type EpochClaimRefundInput, type EpochClaimRefundResult, type EpochClaimableRefund, type EpochClaimableRefundInput, type EpochCreatePoolInput, type EpochCurrentId, type EpochCurrentIdInput, type EpochEnterInput, type EpochEntry, type EpochEntryStatus, type EpochExecuteSettlementInput, type EpochExecuteSettlementResult, type EpochGetAttestationInput, type EpochGetInput, type EpochGetSeriesInput, type EpochPoolOwnership, type EpochPoolWalletProof, type EpochPreparePoolInput, type EpochPreparedPool, type EpochPrize, type EpochPrizeInput, type EpochReadVia, type EpochRegisterPoolInput, type EpochSeriesView, type EpochSettleInput, type EpochSettleResult, type EpochSettleStatus, type EpochSettleWinner, type EpochStudioPool, type EpochTerminal, type EpochView, type EpochWinnerIn, type EpochWithdrawInput, type EpochWithdrawResult, type EpochsApi, EscrowHoldInput, EscrowHoldResult, EscrowResolveResult, Listing, MICRO_PER_USDC, MarketplaceGetResult, MarketplaceListInput, MarketplaceSaleResult, Network, PLAYMOS_FEE_SINK_DEFAULT, PayInput, Payment, type PaymentRequirement, PayoutError, PayoutNoticesResult, PayoutRule, PayoutRule as PayoutRuleCompute, Playmos, PlaymosConfig, PrizeBalance, RETIRED_PLAYMOS_FEE_SINK, RoundCancelInput, RoundGetResult, RoundOpenInput, RoundSettleInput, RoundState, SettleRoundResult, type SettlementAsset, type SettlementTypedData, type SettlementTypedDataInput, 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, buildEpochClaimRefundCall, buildEpochEntryCalls, buildEpochWithdrawCall, clientRuntimeSignals, computeIapSplit, computePayout, computePoolSplit, createEpochsApi, createPaymentRequirement, createX402Challenge, decodePaymentHeader, derivedEpochId, encodeEpochPoolConstructorArgs, encodePaymentHeader, epochPayableMicro, epochPoolProofMessage, formatMicroToUsd, identityToBytes32, isClientRuntime, isWalletSignatureAuthorization, isX402PayloadAuthorization, networkToCaip2, parsePaymentRequirement, parseUsdToMicro, prefixedId, prepareStudioPoolLocal, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, resolveEnv, serializePaymentRequirement, seriesToBytes32, settlementTypedData, toX402PaymentRequired, ulid, validateX402ChallengeInput };
+export { ActiveSeriesRound, AgentFundResult, AgentWallet, type Authorization, C1_ENTER_SPLIT_MICRO, CHAIN_ID, CancelRoundResult, type CreatePaymentRequirementInput, DEFAULT_API_BASE_URL, DEFAULT_SERIES_POOL_BPS, DEFAULT_SERIES_SEED_BPS, EnterRoundInput, type EpochAttestation, type EpochClaimRefundInput, type EpochClaimRefundResult, type EpochClaimableRefund, type EpochClaimableRefundInput, type EpochCreatePoolInput, type EpochCurrentId, type EpochCurrentIdInput, type EpochEnterInput, type EpochEntry, type EpochEntryStatus, type EpochExecuteSettlementInput, type EpochExecuteSettlementResult, type EpochGetAttestationInput, type EpochGetInput, type EpochGetSeriesInput, type EpochPoolOwnership, type EpochPoolWalletProof, type EpochPreparePoolInput, type EpochPrepareSeriesInput, type EpochPreparedPool, type EpochPreparedSeries, type EpochPrize, type EpochPrizeInput, type EpochReadVia, type EpochRegisterPoolInput, type EpochSeriesView, type EpochSettleInput, type EpochSettleResult, type EpochSettleStatus, type EpochSettleWinner, type EpochStudioPool, type EpochTerminal, type EpochView, type EpochWinnerIn, type EpochWithdrawInput, type EpochWithdrawResult, type EpochsApi, EscrowHoldInput, EscrowHoldResult, EscrowResolveResult, LOCKED_SERIES_FEE_BPS, Listing, MICRO_PER_USDC, MarketplaceGetResult, MarketplaceListInput, MarketplaceSaleResult, Network, PLAYMOS_FEE_SINK_DEFAULT, PayInput, Payment, type PaymentRequirement, PayoutError, PayoutNoticesResult, PayoutRule, PayoutRule as PayoutRuleCompute, Playmos, PlaymosConfig, PrizeBalance, RETIRED_PLAYMOS_FEE_SINK, RoundCancelInput, RoundGetResult, RoundOpenInput, RoundSettleInput, RoundState, SettleRoundResult, type SettlementAsset, type SettlementTypedData, type SettlementTypedDataInput, 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, buildEpochClaimRefundCall, buildEpochEntryCalls, buildEpochWithdrawCall, clientRuntimeSignals, computeIapSplit, computePayout, computePoolSplit, createEpochsApi, createPaymentRequirement, createX402Challenge, decodePaymentHeader, derivedEpochId, encodeEpochPoolConstructorArgs, encodePaymentHeader, epochPayableMicro, epochPoolProofMessage, formatMicroToUsd, identityToBytes32, isClientRuntime, isWalletSignatureAuthorization, isX402PayloadAuthorization, networkToCaip2, parsePaymentRequirement, parseUsdToMicro, prefixedId, prepareSeriesLocal, prepareStudioPoolLocal, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, resolveEnv, serializePaymentRequirement, seriesToBytes32, settlementTypedData, toX402PaymentRequired, ulid, validateX402ChallengeInput };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { AuthError, InvalidAmountError, epochPrizePoolEnterAbi, seriesToBytes32, identityToBytes32, encodeApprove, epochPrizePoolRefundAbi, ConfigError, MissingFieldError, buildEpochExecuteSettlementCall, PaymentFailedError, epochPrizePoolViewAbi, ApiError, assertEnoughGas, sendCalls, waitForCalls, NothingToWithdrawError, buildWithdrawCall, WalletTimeoutError, buildIapCalls, buildEntryCalls, prizePoolAbi, WalletConnectionError, AlreadyEnteredError } from './chunk-TZFGZNXV.js';
-export { AlreadyEnteredError, ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError, WalletTimeoutError, buildEpochExecuteSettlementCall, identityToBytes32, seriesToBytes32 } from './chunk-TZFGZNXV.js';
+import { AuthError, InvalidAmountError, epochPrizePoolEnterAbi, seriesToBytes32, identityToBytes32, encodeApprove, epochPrizePoolRefundAbi, ConfigError, epochPrizePoolCreateSeriesAbi, MissingFieldError, buildEpochExecuteSettlementCall, PaymentFailedError, epochPrizePoolViewAbi, ApiError, assertEnoughGas, sendCalls, waitForCalls, NothingToWithdrawError, buildWithdrawCall, WalletTimeoutError, buildIapCalls, buildEntryCalls, prizePoolAbi, WalletConnectionError, AlreadyEnteredError } from './chunk-ROWX6HVU.js';
+export { AlreadyEnteredError, ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError, WalletTimeoutError, buildEpochExecuteSettlementCall, identityToBytes32, seriesToBytes32 } from './chunk-ROWX6HVU.js';
 import { encodeFunctionData, encodeAbiParameters, decodeFunctionResult } from 'viem';
 
 // src/config.ts
@@ -692,6 +692,9 @@ function encodeEpochPoolConstructorArgs(args) {
     args.refundTimeout
   ]);
 }
+var LOCKED_SERIES_FEE_BPS = 100;
+var DEFAULT_SERIES_POOL_BPS = 7900;
+var DEFAULT_SERIES_SEED_BPS = 2e3;
 function derivedEpochId(genesis, epochDuration, at) {
   if (epochDuration === 0n) {
     throw new ConfigError("epochDuration must be > 0");
@@ -860,6 +863,66 @@ function walletStatus(status) {
 function sameAddr(a, b) {
   return a.toLowerCase() === b.toLowerCase();
 }
+function parseSeriesBps(raw, field) {
+  if (raw === void 0) return void 0;
+  if (!Number.isInteger(raw) || raw < 0) {
+    throw new ConfigError(`${field} must be a non-negative integer`);
+  }
+  return raw;
+}
+function prepareSeriesLocal(input, chainId) {
+  const pool = requireAddr(input.epochPrizePool, "epochPrizePool");
+  const series = requireSeries(input.series);
+  const feeBps = parseSeriesBps(input.feeBps, "feeBps");
+  if (feeBps !== void 0 && feeBps !== LOCKED_SERIES_FEE_BPS) {
+    throw new ConfigError(
+      "feeBps must be 100 (the locked 1% Playmos take); refused before anything signable"
+    );
+  }
+  const poolBps = parseSeriesBps(input.poolBps, "poolBps") ?? DEFAULT_SERIES_POOL_BPS;
+  const seedBps = parseSeriesBps(input.seedBps, "seedBps") ?? DEFAULT_SERIES_SEED_BPS;
+  if (LOCKED_SERIES_FEE_BPS + poolBps + seedBps !== 1e4) {
+    throw new ConfigError("feeBps + poolBps + seedBps must sum to 10000 (fee is 100)");
+  }
+  const epochDuration = toBig(input.epochDuration, 0n);
+  const entry = toBig(input.entry, 0n);
+  if (epochDuration <= 0n) throw new ConfigError("epochDuration must be greater than 0");
+  if (entry <= 0n) throw new ConfigError("entry must be greater than 0");
+  const genesis = toBig(input.genesis, BigInt(Math.floor(Date.now() / 1e3)));
+  if (genesis <= 0n) throw new ConfigError("genesis must be greater than 0");
+  const data = encodeFunctionData({
+    abi: epochPrizePoolCreateSeriesAbi,
+    functionName: "createSeries",
+    args: [
+      seriesToBytes32(series),
+      genesis,
+      epochDuration,
+      entry,
+      LOCKED_SERIES_FEE_BPS,
+      poolBps,
+      seedBps
+    ]
+  });
+  return {
+    series,
+    epochPrizePool: pool,
+    genesis: genesis.toString(),
+    epochDuration: epochDuration.toString(),
+    entry: entry.toString(),
+    feeBps: 100,
+    poolBps,
+    seedBps,
+    unsignedTx: {
+      chainId,
+      to: pool,
+      value: "0",
+      data
+    },
+    broadcast: false,
+    via: "mock",
+    mock: true
+  };
+}
 function prepareStudioPoolLocal(input, playmosFeeSink, token, playmosAddresses = []) {
   const studio = requireAddr(input.studioWallet, "studioWallet");
   const locked = PLAYMOS_FEE_SINK_DEFAULT;
@@ -1008,6 +1071,7 @@ async function readEpochTerminal(deps, pool, series, epochId) {
   }
 }
 function createEpochsApi(deps) {
+  const mockPreparedSeries = /* @__PURE__ */ new Map();
   return {
     async currentId(input) {
       const series = requireSeries(input?.series);
@@ -1085,6 +1149,9 @@ function createEpochsApi(deps) {
       const series = requireSeries(input?.series);
       const cfg = deps.config();
       if (cfg.mock) {
+        const pool = (input.epochPrizePool ?? cfg.contracts?.epochPrizePool ?? "").toLowerCase();
+        const prepared = mockPreparedSeries.get(`${pool}:${series}`);
+        if (prepared) return prepared;
         return {
           series,
           created: true,
@@ -1105,6 +1172,42 @@ function createEpochsApi(deps) {
       })}`;
       return deps.http().get(path);
     },
+    async prepareSeries(input) {
+      const feeBps = input?.feeBps;
+      if (feeBps !== void 0 && feeBps !== LOCKED_SERIES_FEE_BPS) {
+        throw new ConfigError(
+          "feeBps must be 100 (the locked 1% Playmos take); refused before anything signable"
+        );
+      }
+      const cfg = deps.config();
+      if (cfg.mock) {
+        const prepared = prepareSeriesLocal(input, CHAIN_ID["base-sepolia"]);
+        mockPreparedSeries.set(`${prepared.epochPrizePool}:${prepared.series}`, {
+          series: prepared.series,
+          created: true,
+          genesis: prepared.genesis,
+          epochDuration: prepared.epochDuration,
+          entry: prepared.entry,
+          feeBps: prepared.feeBps,
+          poolBps: prepared.poolBps,
+          seedBps: prepared.seedBps,
+          via: "mock",
+          epochPrizePool: prepared.epochPrizePool,
+          mock: true
+        });
+        return prepared;
+      }
+      return deps.http().post("/epochs/series/prepare", {
+        epochPrizePool: requireAddr(input?.epochPrizePool, "epochPrizePool"),
+        series: requireSeries(input?.series),
+        epochDuration: input.epochDuration,
+        entry: input.entry,
+        genesis: input.genesis,
+        feeBps: input.feeBps,
+        poolBps: input.poolBps,
+        seedBps: input.seedBps
+      });
+    },
     async preparePool(input) {
       const studioWallet = requireAddr(input?.studioWallet, "studioWallet");
       const cfg = deps.config();
@@ -1818,7 +1921,7 @@ var Playmos = class {
       },
       walletAddress: async () => getAccount(this.walletProvider()),
       readView: async (to, data) => {
-        if (await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
+        if (!await this.shouldServerSettle() && await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
           const provider = this.walletProvider();
           return await provider.request({
             method: "eth_call",
@@ -2919,8 +3022,14 @@ var Playmos = class {
         );
       }
     }
+    if (config.settle === "server" && !this.env.isTest) {
+      throw new ConfigError(
+        'settle: "server" is sandbox-only. Live keys must use a player wallet \u2014 never server-settle real money.',
+        { field: "settle" }
+      );
+    }
     this.http = createHttpClient(this.env.apiBaseUrl, config.apiKey, config.retry);
-    if (!config.mock) {
+    if (!config.mock && config.settle !== "server") {
       try {
         resolveProvider(config.wallet, this.walletTimeoutPolicy());
       } catch {
@@ -2990,6 +3099,23 @@ var Playmos = class {
       return 0n;
     }
   }
+  /**
+   * Sandbox server-settle when the developer asked (`settle: "server"`) or when
+   * a test key has no wallet. Never calls walletAvailable if the ask is set —
+   * that is the MetaMask-hijack delete (Moonhop leftover Slice 1).
+   */
+  async shouldServerSettle() {
+    if (this.config.settle === "server") {
+      if (!this.env.isTest) {
+        throw new ConfigError(
+          'settle: "server" is sandbox-only. Live keys must use a player wallet \u2014 never server-settle real money.',
+          { field: "settle" }
+        );
+      }
+      return true;
+    }
+    return this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy());
+  }
   /**
    * Wallet timeout policy (#462 / PR #463 residual).
    * - connectTimeoutMs → eth_requestAccounts only
@@ -3117,7 +3243,7 @@ var Playmos = class {
         heldIdem ? { key: heldIdem, terms } : void 0
       );
     }
-    if (this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
+    if (await this.shouldServerSettle()) {
       const res = await this.http.post(
         "/payments",
         {
@@ -3222,7 +3348,7 @@ var Playmos = class {
         heldIdem ? { key: heldIdem, terms } : void 0
       );
     }
-    const serverSettleNoWallet = this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy());
+    const serverSettleNoWallet = await this.shouldServerSettle();
     if (!serverSettleNoWallet) {
       const pinned = typeof input.identity === "string" ? input.identity.trim() : "";
       if (!pinned) {
@@ -3552,7 +3678,7 @@ var Playmos = class {
     });
     let raw;
     try {
-      if (await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
+      if (!await this.shouldServerSettle() && await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
         const provider = this.walletProvider();
         raw = await provider.request({
           method: "eth_call",
@@ -3764,4 +3890,4 @@ function isX402PayloadAuthorization(auth) {
   return auth.kind === "x402-payload";
 }
 
-export { C1_ENTER_SPLIT_MICRO, CHAIN_ID, DEFAULT_API_BASE_URL, MICRO_PER_USDC, PLAYMOS_FEE_SINK_DEFAULT, PayoutError, Playmos, RETIRED_PLAYMOS_FEE_SINK, USDC_ADDRESS, USDC_DECIMALS, buildEpochClaimRefundCall, buildEpochEntryCalls, buildEpochWithdrawCall, clientRuntimeSignals, computeIapSplit, computePayout, computePoolSplit, createEpochsApi, createPaymentRequirement, createX402Challenge, decodePaymentHeader, derivedEpochId, encodeEpochPoolConstructorArgs, encodePaymentHeader, epochPayableMicro, epochPoolProofMessage, formatMicroToUsd, isClientRuntime, isWalletSignatureAuthorization, isX402PayloadAuthorization, networkToCaip2, parsePaymentRequirement, parseUsdToMicro, prefixedId, prepareStudioPoolLocal, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, resolveEnv, serializePaymentRequirement, settlementTypedData, toX402PaymentRequired, ulid, validateX402ChallengeInput };
+export { C1_ENTER_SPLIT_MICRO, CHAIN_ID, DEFAULT_API_BASE_URL, DEFAULT_SERIES_POOL_BPS, DEFAULT_SERIES_SEED_BPS, LOCKED_SERIES_FEE_BPS, MICRO_PER_USDC, PLAYMOS_FEE_SINK_DEFAULT, PayoutError, Playmos, RETIRED_PLAYMOS_FEE_SINK, USDC_ADDRESS, USDC_DECIMALS, buildEpochClaimRefundCall, buildEpochEntryCalls, buildEpochWithdrawCall, clientRuntimeSignals, computeIapSplit, computePayout, computePoolSplit, createEpochsApi, createPaymentRequirement, createX402Challenge, decodePaymentHeader, derivedEpochId, encodeEpochPoolConstructorArgs, encodePaymentHeader, epochPayableMicro, epochPoolProofMessage, formatMicroToUsd, isClientRuntime, isWalletSignatureAuthorization, isX402PayloadAuthorization, networkToCaip2, parsePaymentRequirement, parseUsdToMicro, prefixedId, prepareSeriesLocal, prepareStudioPoolLocal, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, resolveEnv, serializePaymentRequirement, settlementTypedData, toX402PaymentRequired, ulid, validateX402ChallengeInput };

package/dist/server.d.cts

@@ -1,5 +1,5 @@
-import { a2 as PlaymosError, W as WebhookEvent } from './errors-CYKgt2VU.cjs';
-export { ad as enterPathToBytes32 } from './errors-CYKgt2VU.cjs';
+import { a2 as PlaymosError, W as WebhookEvent } from './errors-WcDNfb4q.cjs';
+export { ad as enterPathToBytes32 } from './errors-WcDNfb4q.cjs';
 
 /**
  * Webhook signature verification (spec §6.2) — server-side only.

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-import { a2 as PlaymosError, W as WebhookEvent } from './errors-CYKgt2VU.js';
-export { ad as enterPathToBytes32 } from './errors-CYKgt2VU.js';
+import { a2 as PlaymosError, W as WebhookEvent } from './errors-WcDNfb4q.js';
+export { ad as enterPathToBytes32 } from './errors-WcDNfb4q.js';
 
 /**
  * Webhook signature verification (spec §6.2) — server-side only.

package/dist/server.js

@@ -1,5 +1,5 @@
-import { PlaymosError, ApiError, toBytes32 } from './chunk-TZFGZNXV.js';
-export { toBytes32 as enterPathToBytes32 } from './chunk-TZFGZNXV.js';
+import { PlaymosError, ApiError, toBytes32 } from './chunk-ROWX6HVU.js';
+export { toBytes32 as enterPathToBytes32 } from './chunk-ROWX6HVU.js';
 import { timingSafeEqual, createHmac } from 'crypto';
 import { encodeFunctionData, decodeFunctionResult } from 'viem';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playmos/sdk",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "description": "Playmos SDK — stablecoin payments for games on Base. IAP and skill contests are flat 1%. USD in, USDC on-chain, no crypto UX for players.",
   "license": "MIT",
   "private": false,