@playmos/sdk 0.3.14 → 0.3.15

package/CHANGELOG.md

@@ -4,6 +4,14 @@ 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

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.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/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();
@@ -4238,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;
@@ -4279,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

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

@@ -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-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();
@@ -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.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.14",
+  "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,