@playmos/sdk 0.3.14 → 0.3.16

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to `@playmos/sdk`. This project adheres to [Semantic Version
 
 ## Unreleased
 
+## [0.3.16] — 2026-09-11
+
+### Added/Fixed
+- EOA / Chrome Coinbase extension: `sendCalls` falls back to sequential `eth_sendTransaction` when `wallet_sendCalls` is missing or fails (not a user cancel). Skip USDC approve when allowance already covers. (#746 / #745)
+
+## [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

package/README.md

@@ -16,7 +16,7 @@ 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).
@@ -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.14** 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.16** 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-U6BPSEKC.js}

@@ -1,4 +1,4 @@
-import { keccak256, toHex, numberToHex, encodeFunctionData, toBytes, getAddress } from 'viem';
+import { keccak256, toHex, numberToHex, encodeFunctionData, toBytes, getAddress, decodeFunctionData } from 'viem';
 
 // src/errors.ts
 var PlaymosError = class extends Error {
@@ -140,6 +140,35 @@ var prizePoolAbi = [
     outputs: [{ name: "amount", type: "uint256" }]
   }
 ];
+var erc20AllowanceAbi = [
+  {
+    type: "function",
+    name: "allowance",
+    stateMutability: "view",
+    inputs: [
+      { name: "owner", type: "address" },
+      { name: "spender", type: "address" }
+    ],
+    outputs: [{ type: "uint256" }]
+  }
+];
+var SEQUENTIAL_TX_ID_PREFIX = "eth:";
+var USER_CANCEL_RE = /reject|denied|cancel|closed/i;
+function sequentialTxId(txHash) {
+  return `${SEQUENTIAL_TX_ID_PREFIX}${txHash}`;
+}
+function sequentialTxHashFromId(id) {
+  if (!id.startsWith(SEQUENTIAL_TX_ID_PREFIX)) return void 0;
+  const hash = id.slice(SEQUENTIAL_TX_ID_PREFIX.length);
+  if (/^0x[0-9a-fA-F]{64}$/.test(hash)) return hash;
+  return void 0;
+}
+function errorMessage(e) {
+  return e?.message ?? String(e);
+}
+function isUserCancel(msg) {
+  return USER_CANCEL_RE.test(msg);
+}
 async function sendCalls(provider, from, chainId, calls, paymasterUrl) {
   const params = {
     version: "2.0.0",
@@ -151,23 +180,85 @@ async function sendCalls(provider, from, chainId, calls, paymasterUrl) {
   if (paymasterUrl) {
     params.capabilities = { paymasterService: { url: paymasterUrl } };
   }
-  let result;
   try {
-    result = await provider.request({ method: "wallet_sendCalls", params: [params] });
+    const result = await provider.request({ method: "wallet_sendCalls", params: [params] });
+    const id = typeof result === "string" ? result : result?.id ?? "";
+    if (!id) throw new PaymentFailedError("Wallet returned no calls id.");
+    return { id };
   } catch (e) {
+    if (e instanceof PaymentFailedError) throw e;
     if (e instanceof WalletTimeoutError) throw e;
-    const msg = e?.message ?? String(e);
-    if (/reject|denied|cancel|closed/i.test(msg)) {
+    const msg = errorMessage(e);
+    if (isUserCancel(msg)) {
       throw new WalletConnectionError("The player cancelled or closed the payment sheet.", { cause: msg });
     }
-    throw new PaymentFailedError("wallet_sendCalls failed.", { cause: msg });
+    return sendCallsSequentially(provider, from, calls);
   }
-  const id = typeof result === "string" ? result : result?.id ?? "";
-  if (!id) throw new PaymentFailedError("Wallet returned no calls id.");
-  return { id };
+}
+async function skipCoveredApprove(provider, from, calls) {
+  const first = calls[0];
+  if (!first) return calls;
+  let spender;
+  let amount;
+  try {
+    const decoded = decodeFunctionData({ abi: erc20Abi, data: first.data });
+    if (decoded.functionName !== "approve") return calls;
+    spender = decoded.args[0];
+    amount = decoded.args[1];
+  } catch {
+    return calls;
+  }
+  try {
+    const data = encodeFunctionData({
+      abi: erc20AllowanceAbi,
+      functionName: "allowance",
+      args: [from, spender]
+    });
+    const raw = await provider.request({
+      method: "eth_call",
+      params: [{ to: first.to, data }, "latest"]
+    });
+    const allowance = BigInt(typeof raw === "string" && raw !== "0x" ? raw : "0");
+    if (allowance >= amount) return calls.slice(1);
+  } catch {
+  }
+  return calls;
+}
+async function sendCallsSequentially(provider, from, calls) {
+  const toSend = await skipCoveredApprove(provider, from, calls);
+  if (toSend.length === 0) {
+    throw new PaymentFailedError("No wallet calls to send.");
+  }
+  let lastHash;
+  for (const call of toSend) {
+    let hash;
+    try {
+      hash = await provider.request({
+        method: "eth_sendTransaction",
+        params: [{ from, to: call.to, data: call.data }]
+      });
+    } catch (e) {
+      if (e instanceof WalletTimeoutError) throw e;
+      const msg = errorMessage(e);
+      if (isUserCancel(msg)) {
+        throw new WalletConnectionError("The player cancelled or closed the payment sheet.", { cause: msg });
+      }
+      throw new PaymentFailedError("eth_sendTransaction failed.", { cause: msg });
+    }
+    if (typeof hash !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(hash)) {
+      throw new PaymentFailedError("Wallet returned no transaction hash.");
+    }
+    lastHash = hash;
+  }
+  if (!lastHash) throw new PaymentFailedError("Wallet returned no transaction hash.");
+  return { id: sequentialTxId(lastHash) };
 }
 async function waitForCalls(provider, id, timeoutMs = 6e4) {
   if (!id) return { status: "FAILED" };
+  const sequentialHash = sequentialTxHashFromId(id);
+  if (sequentialHash) {
+    return waitForTransactionReceipt(provider, sequentialHash, timeoutMs);
+  }
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     try {
@@ -190,6 +281,30 @@ async function waitForCalls(provider, id, timeoutMs = 6e4) {
   }
   return { status: "PENDING" };
 }
+async function waitForTransactionReceipt(provider, txHash, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await provider.request({
+        method: "eth_getTransactionReceipt",
+        params: [txHash]
+      });
+      if (res && res.status !== void 0 && res.status !== null) {
+        const code = typeof res.status === "number" ? res.status : Number(res.status);
+        if (code === 1) return { status: "CONFIRMED", txHash };
+        if (code === 0) 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", txHash };
+}
 function encodeApprove(spender, amountUnits) {
   return encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: [spender, amountUnits] });
 }
@@ -345,6 +460,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 +574,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-WcDNfb4q.d.cts → errors-CdzI_iYO.d.cts}

@@ -735,9 +735,12 @@ interface SettleRoundResult {
 
 /**
  * EIP-5792 batch primitives — ported from the proven game-hub `payEntryOnchain`
- * path (`OnchainEntry.ts`). One `wallet_sendCalls` sends `approve` + the settling
- * call as ONE atomic confirmation; the paymaster sponsors gas when configured.
- * The player sees a single Apple-Pay-style sheet.
+ * path (`OnchainEntry.ts`). `wallet_sendCalls` still sends `approve` + the
+ * settling call as one atomic confirmation when the wallet can batch (paymaster
+ * sponsors gas when configured). If `wallet_sendCalls` is missing or fails on an
+ * EOA — not a user cancel — the same Call[] is sent as sequential
+ * `eth_sendTransaction`s. That fallback is not atomic and never attaches a
+ * paymaster. Covered USDC allowance skips the approve tx (one confirm).
  */
 
 interface Call {

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

@@ -735,9 +735,12 @@ interface SettleRoundResult {
 
 /**
  * EIP-5792 batch primitives — ported from the proven game-hub `payEntryOnchain`
- * path (`OnchainEntry.ts`). One `wallet_sendCalls` sends `approve` + the settling
- * call as ONE atomic confirmation; the paymaster sponsors gas when configured.
- * The player sees a single Apple-Pay-style sheet.
+ * path (`OnchainEntry.ts`). `wallet_sendCalls` still sends `approve` + the
+ * settling call as one atomic confirmation when the wallet can batch (paymaster
+ * sponsors gas when configured). If `wallet_sendCalls` is missing or fails on an
+ * EOA — not a user cancel — the same Call[] is sent as sequential
+ * `eth_sendTransaction`s. That fallback is not atomic and never attaches a
+ * paymaster. Covered USDC allowance skips the approve tx (one confirm).
  */
 
 interface Call {

package/dist/index.cjs

@@ -718,6 +718,37 @@ var prizePoolAbi = [
     outputs: [{ name: "amount", type: "uint256" }]
   }
 ];
+
+// src/chain/batch.ts
+var erc20AllowanceAbi = [
+  {
+    type: "function",
+    name: "allowance",
+    stateMutability: "view",
+    inputs: [
+      { name: "owner", type: "address" },
+      { name: "spender", type: "address" }
+    ],
+    outputs: [{ type: "uint256" }]
+  }
+];
+var SEQUENTIAL_TX_ID_PREFIX = "eth:";
+var USER_CANCEL_RE = /reject|denied|cancel|closed/i;
+function sequentialTxId(txHash) {
+  return `${SEQUENTIAL_TX_ID_PREFIX}${txHash}`;
+}
+function sequentialTxHashFromId(id) {
+  if (!id.startsWith(SEQUENTIAL_TX_ID_PREFIX)) return void 0;
+  const hash = id.slice(SEQUENTIAL_TX_ID_PREFIX.length);
+  if (/^0x[0-9a-fA-F]{64}$/.test(hash)) return hash;
+  return void 0;
+}
+function errorMessage(e) {
+  return e?.message ?? String(e);
+}
+function isUserCancel(msg) {
+  return USER_CANCEL_RE.test(msg);
+}
 async function sendCalls(provider, from, chainId, calls, paymasterUrl) {
   const params = {
     version: "2.0.0",
@@ -729,23 +760,85 @@ async function sendCalls(provider, from, chainId, calls, paymasterUrl) {
   if (paymasterUrl) {
     params.capabilities = { paymasterService: { url: paymasterUrl } };
   }
-  let result;
   try {
-    result = await provider.request({ method: "wallet_sendCalls", params: [params] });
+    const result = await provider.request({ method: "wallet_sendCalls", params: [params] });
+    const id = typeof result === "string" ? result : result?.id ?? "";
+    if (!id) throw new PaymentFailedError("Wallet returned no calls id.");
+    return { id };
   } catch (e) {
+    if (e instanceof PaymentFailedError) throw e;
     if (e instanceof WalletTimeoutError) throw e;
-    const msg = e?.message ?? String(e);
-    if (/reject|denied|cancel|closed/i.test(msg)) {
+    const msg = errorMessage(e);
+    if (isUserCancel(msg)) {
       throw new WalletConnectionError("The player cancelled or closed the payment sheet.", { cause: msg });
     }
-    throw new PaymentFailedError("wallet_sendCalls failed.", { cause: msg });
+    return sendCallsSequentially(provider, from, calls);
+  }
+}
+async function skipCoveredApprove(provider, from, calls) {
+  const first = calls[0];
+  if (!first) return calls;
+  let spender;
+  let amount;
+  try {
+    const decoded = viem.decodeFunctionData({ abi: erc20Abi, data: first.data });
+    if (decoded.functionName !== "approve") return calls;
+    spender = decoded.args[0];
+    amount = decoded.args[1];
+  } catch {
+    return calls;
+  }
+  try {
+    const data = viem.encodeFunctionData({
+      abi: erc20AllowanceAbi,
+      functionName: "allowance",
+      args: [from, spender]
+    });
+    const raw = await provider.request({
+      method: "eth_call",
+      params: [{ to: first.to, data }, "latest"]
+    });
+    const allowance = BigInt(typeof raw === "string" && raw !== "0x" ? raw : "0");
+    if (allowance >= amount) return calls.slice(1);
+  } catch {
+  }
+  return calls;
+}
+async function sendCallsSequentially(provider, from, calls) {
+  const toSend = await skipCoveredApprove(provider, from, calls);
+  if (toSend.length === 0) {
+    throw new PaymentFailedError("No wallet calls to send.");
+  }
+  let lastHash;
+  for (const call of toSend) {
+    let hash;
+    try {
+      hash = await provider.request({
+        method: "eth_sendTransaction",
+        params: [{ from, to: call.to, data: call.data }]
+      });
+    } catch (e) {
+      if (e instanceof WalletTimeoutError) throw e;
+      const msg = errorMessage(e);
+      if (isUserCancel(msg)) {
+        throw new WalletConnectionError("The player cancelled or closed the payment sheet.", { cause: msg });
+      }
+      throw new PaymentFailedError("eth_sendTransaction failed.", { cause: msg });
+    }
+    if (typeof hash !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(hash)) {
+      throw new PaymentFailedError("Wallet returned no transaction hash.");
+    }
+    lastHash = hash;
   }
-  const id = typeof result === "string" ? result : result?.id ?? "";
-  if (!id) throw new PaymentFailedError("Wallet returned no calls id.");
-  return { id };
+  if (!lastHash) throw new PaymentFailedError("Wallet returned no transaction hash.");
+  return { id: sequentialTxId(lastHash) };
 }
 async function waitForCalls(provider, id, timeoutMs = 6e4) {
   if (!id) return { status: "FAILED" };
+  const sequentialHash = sequentialTxHashFromId(id);
+  if (sequentialHash) {
+    return waitForTransactionReceipt(provider, sequentialHash, timeoutMs);
+  }
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     try {
@@ -768,6 +861,30 @@ async function waitForCalls(provider, id, timeoutMs = 6e4) {
   }
   return { status: "PENDING" };
 }
+async function waitForTransactionReceipt(provider, txHash, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await provider.request({
+        method: "eth_getTransactionReceipt",
+        params: [txHash]
+      });
+      if (res && res.status !== void 0 && res.status !== null) {
+        const code = typeof res.status === "number" ? res.status : Number(res.status);
+        if (code === 1) return { status: "CONFIRMED", txHash };
+        if (code === 0) 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", txHash };
+}
 function encodeApprove(spender, amountUnits) {
   return viem.encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: [spender, amountUnits] });
 }
@@ -929,6 +1046,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 +1270,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 +1441,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 +1649,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 +1727,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 +1750,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();
@@ -4238,8 +4475,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;
@@ -4279,6 +4519,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-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';
+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-CdzI_iYO.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-CdzI_iYO.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;
 /**
@@ -1593,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-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';
+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-CdzI_iYO.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-CdzI_iYO.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;
 /**
@@ -1593,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-U6BPSEKC.js';
+export { AlreadyEnteredError, ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError, WalletTimeoutError, buildEpochExecuteSettlementCall, identityToBytes32, seriesToBytes32 } from './chunk-U6BPSEKC.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();
@@ -3787,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-WcDNfb4q.cjs';
-export { ad as enterPathToBytes32 } from './errors-WcDNfb4q.cjs';
+import { a2 as PlaymosError, W as WebhookEvent } from './errors-CdzI_iYO.cjs';
+export { ad as enterPathToBytes32 } from './errors-CdzI_iYO.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-WcDNfb4q.js';
-export { ad as enterPathToBytes32 } from './errors-WcDNfb4q.js';
+import { a2 as PlaymosError, W as WebhookEvent } from './errors-CdzI_iYO.js';
+export { ad as enterPathToBytes32 } from './errors-CdzI_iYO.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-U6BPSEKC.js';
+export { toBytes32 as enterPathToBytes32 } from './chunk-U6BPSEKC.js';
 import { timingSafeEqual, createHmac } from 'crypto';
 import { encodeFunctionData, decodeFunctionResult } from 'viem';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playmos/sdk",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "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,