@playmos/sdk 0.3.10 → 0.3.12

package/dist/index.js

@@ -1,6 +1,6 @@
-import { AuthError, InvalidAmountError, ConfigError, MissingFieldError, NothingToWithdrawError, WalletTimeoutError, PaymentFailedError, ApiError, WalletConnectionError, InsufficientGasError, AlreadyEnteredError } from './chunk-UZECDT6F.js';
-export { AlreadyEnteredError, ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError, WalletTimeoutError } from './chunk-UZECDT6F.js';
-import { encodeFunctionData, decodeFunctionResult, numberToHex, keccak256, toBytes } from 'viem';
+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-2CW4U5YB.js';
+export { AlreadyEnteredError, ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError, WalletTimeoutError, buildEpochExecuteSettlementCall, identityToBytes32, seriesToBytes32 } from './chunk-2CW4U5YB.js';
+import { encodeFunctionData, encodeAbiParameters, decodeFunctionResult } from 'viem';
 
 // src/config.ts
 var CHAIN_ID = {
@@ -183,10 +183,10 @@ function validateMetadata(metadata) {
 
 // src/payout.ts
 var PayoutError = class extends Error {
-  constructor(message) {
+  constructor(message, code = "payout_invalid") {
     super(message);
-    this.code = "payout_invalid";
     this.name = "PayoutError";
+    this.code = code;
   }
 };
 var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
@@ -231,7 +231,8 @@ function computePayout(pool, ranking, rule) {
     }
     if (splits.length > wallets.length) {
       throw new PayoutError(
-        `top-n needs ${splits.length} ranked wallets but ranking only has ${wallets.length}`
+        `ranking_too_short: a top-n rule cannot be settled from a ranking shorter than splitsBps.length (need ${splits.length}, got ${wallets.length}) \u2014 open with winner-take-all, or settle with explicit winners[{wallet,amount}]`,
+        "ranking_too_short"
       );
     }
     let sumBps = 0;
@@ -544,7 +545,7 @@ function resolveRawProvider(wallet) {
   }
   if (injected) return injected;
   throw new WalletConnectionError(
-    "base-account connector needs a provider. In the Base App it is injected automatically; elsewhere, create one with @base-org/account and pass it as wallet.provider."
+    'base-account connector needs a provider \u2014 this is not a built-in Base Account/passkey flow in @playmos/sdk. In the Base App a provider is often injected; elsewhere install @base-org/account, construct a provider, and pass it as wallet.provider (or use connector: "injected" in a wallet browser).'
   );
 }
 function resolveProvider(wallet, opts) {
@@ -580,173 +581,36 @@ async function getAccount(provider) {
     });
   }
 }
-
-// src/chain/abis.ts
-var erc20Abi = [
-  {
-    type: "function",
-    name: "approve",
-    stateMutability: "nonpayable",
-    inputs: [
-      { name: "spender", type: "address" },
-      { name: "amount", type: "uint256" }
-    ],
-    outputs: [{ type: "bool" }]
-  }
-];
-var playmosPayAbi = [
-  {
-    type: "function",
-    name: "pay",
-    stateMutability: "nonpayable",
-    inputs: [
-      { name: "paymentId", type: "bytes32" },
-      { name: "studio", type: "address" },
-      { name: "amount", type: "uint256" }
-    ],
-    outputs: []
-  }
-];
-var prizePoolAbi = [
-  {
-    type: "function",
-    name: "enter",
-    stateMutability: "nonpayable",
-    inputs: [
-      { name: "roundId", type: "bytes32" },
-      { name: "identity", type: "bytes32" }
-    ],
-    outputs: []
-  },
-  {
-    type: "function",
-    name: "withdrawable",
-    stateMutability: "view",
-    inputs: [{ name: "account", type: "address" }],
-    outputs: [{ type: "uint256" }]
-  },
-  {
-    type: "function",
-    name: "withdraw",
-    stateMutability: "nonpayable",
-    inputs: [],
-    outputs: [{ name: "amount", type: "uint256" }]
-  }
-];
-async function sendCalls(provider, from, chainId, calls, paymasterUrl) {
-  const params = {
-    version: "2.0.0",
-    from,
-    chainId: numberToHex(chainId),
-    atomicRequired: true,
-    calls
-  };
-  if (paymasterUrl) {
-    params.capabilities = { paymasterService: { url: paymasterUrl } };
-  }
-  let result;
-  try {
-    result = await provider.request({ method: "wallet_sendCalls", params: [params] });
-  } catch (e) {
-    if (e instanceof WalletTimeoutError) throw e;
-    const msg = e?.message ?? String(e);
-    if (/reject|denied|cancel|closed/i.test(msg)) {
-      throw new WalletConnectionError("The player cancelled or closed the payment sheet.", { cause: msg });
-    }
-    throw new PaymentFailedError("wallet_sendCalls failed.", { cause: msg });
-  }
-  const id = typeof result === "string" ? result : result?.id ?? "";
-  if (!id) throw new PaymentFailedError("Wallet returned no calls id.");
-  return { id };
-}
-async function waitForCalls(provider, id, timeoutMs = 6e4) {
-  if (!id) return { status: "FAILED" };
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    try {
-      const res = await provider.request({
-        method: "wallet_getCallsStatus",
-        params: [id]
-      });
-      const s = String(res?.status ?? "").toUpperCase();
-      const txHash = res?.receipts?.[0]?.transactionHash;
-      if (s === "200" || s === "CONFIRMED" || s === "SUCCESS") return { status: "CONFIRMED", txHash };
-      if (s === "400" || s === "500" || s === "FAILED" || s === "REVERTED") return { status: "FAILED", txHash };
-    } catch (e) {
-      if (e instanceof WalletTimeoutError) {
-        await new Promise((r) => setTimeout(r, 900));
-        continue;
-      }
-      throw e;
-    }
-    await new Promise((r) => setTimeout(r, 900));
-  }
-  return { status: "PENDING" };
-}
-function encodeApprove(spender, amountUnits) {
-  return encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: [spender, amountUnits] });
-}
-var GAS_FLOOR_WEI_DEFAULT = 200000000000000n;
-var GAS_FLOOR_WEI_BASE_SEPOLIA = 50000000000000n;
-var CHAIN_ID_BASE_SEPOLIA = 84532;
-function gasFloorWei(chainId) {
-  return chainId === CHAIN_ID_BASE_SEPOLIA ? GAS_FLOOR_WEI_BASE_SEPOLIA : GAS_FLOOR_WEI_DEFAULT;
-}
-async function assertEnoughGas(provider, from, minWei) {
-  let floor = minWei;
-  if (floor === void 0) {
-    let chainId = 0;
-    try {
-      const hex = await provider.request({ method: "eth_chainId", params: [] });
-      chainId = Number(BigInt(hex));
-    } catch {
-    }
-    floor = gasFloorWei(chainId);
-  }
-  let balance;
-  try {
-    const hex = await provider.request({ method: "eth_getBalance", params: [from, "latest"] });
-    balance = BigInt(hex);
-  } catch {
-    return;
-  }
-  if (balance < floor) {
-    throw new InsufficientGasError({
-      balanceWei: balance.toString(),
-      minWei: floor.toString()
-    });
-  }
-}
-var toBytes32 = (s) => keccak256(toBytes(s));
-function buildIapCalls(args) {
-  const payData = encodeFunctionData({
-    abi: playmosPayAbi,
-    functionName: "pay",
-    args: [toBytes32(args.paymentId), args.studio, args.amountUnits]
-  });
-  return [
-    { to: args.usdc, data: encodeApprove(args.playmosPay, args.amountUnits) },
-    { to: args.playmosPay, data: payData }
-  ];
-}
-function buildEntryCalls(args) {
+function buildEpochEntryCalls(args) {
   const enterData = encodeFunctionData({
-    abi: prizePoolAbi,
+    abi: epochPrizePoolEnterAbi,
     functionName: "enter",
-    args: [toBytes32(args.roundKey), toBytes32(args.identity)]
+    args: [seriesToBytes32(args.series), identityToBytes32(args.identity)]
   });
   return [
-    { to: args.usdc, data: encodeApprove(args.prizePool, args.amountUnits) },
-    { to: args.prizePool, data: enterData }
+    { to: args.usdc, data: encodeApprove(args.epochPrizePool, args.entryMicro) },
+    { to: args.epochPrizePool, data: enterData }
   ];
 }
-function buildWithdrawCall(prizePool) {
-  const data = encodeFunctionData({
-    abi: prizePoolAbi,
-    functionName: "withdraw",
-    args: []
-  });
-  return { to: prizePool, data };
+function buildEpochClaimRefundCall(args) {
+  return {
+    to: args.epochPrizePool,
+    data: encodeFunctionData({
+      abi: epochPrizePoolRefundAbi,
+      functionName: "claimRefund",
+      args: [seriesToBytes32(args.series), args.epochId, args.payer]
+    })
+  };
+}
+function buildEpochWithdrawCall(epochPrizePool) {
+  return {
+    to: epochPrizePool,
+    data: encodeFunctionData({
+      abi: epochPrizePoolRefundAbi,
+      functionName: "withdraw",
+      args: []
+    })
+  };
 }
 
 // src/mock.ts
@@ -809,13 +673,893 @@ function mockVerifyResult(payment) {
   return { ...payment, mock: true };
 }
 
-// src/x402.ts
+// src/epochs.ts
+var PLAYMOS_FEE_SINK_DEFAULT = "0x1b8031e20ed96131a849a52290b4d640f286998d";
+var EPOCH_POOL_CONSTRUCTOR_TYPES = [
+  { type: "address" },
+  { type: "address" },
+  { type: "address" },
+  { type: "address" },
+  { type: "uint256" }
+];
+function encodeEpochPoolConstructorArgs(args) {
+  return encodeAbiParameters(EPOCH_POOL_CONSTRUCTOR_TYPES, [
+    args.token,
+    args.admin,
+    args.operator,
+    args.feeSink,
+    args.refundTimeout
+  ]);
+}
+function derivedEpochId(genesis, epochDuration, at) {
+  if (epochDuration === 0n) {
+    throw new ConfigError("epochDuration must be > 0");
+  }
+  if (at < genesis) {
+    throw new ConfigError("epoch has not started (at < genesis)");
+  }
+  return (at - genesis) / epochDuration;
+}
+function epochPayableMicro(incomingSeed, pool) {
+  return incomingSeed + pool;
+}
+function mockPodiumPayable(winners) {
+  if (winners.length === 0) return void 0;
+  let total = 0n;
+  for (const w of winners) {
+    if (typeof w === "string") return void 0;
+    if (w.amountMicro != null && w.amountMicro !== "") {
+      try {
+        total += BigInt(w.amountMicro);
+      } catch {
+        return void 0;
+      }
+      continue;
+    }
+    if (w.amount) {
+      try {
+        total += parseUsdToMicro(w.amount);
+      } catch {
+        return void 0;
+      }
+      continue;
+    }
+    return void 0;
+  }
+  return {
+    payable: formatMicroToUsd(total),
+    payableMicro: total.toString()
+  };
+}
+function mockWinnerMicro(w) {
+  if (typeof w === "string") return void 0;
+  if (w.amountMicro != null && w.amountMicro !== "" && /^\d+$/.test(w.amountMicro)) {
+    return BigInt(w.amountMicro);
+  }
+  if (w.amount) {
+    try {
+      return parseUsdToMicro(w.amount);
+    } catch {
+      return void 0;
+    }
+  }
+  return void 0;
+}
+function mockWinnerAmount(w) {
+  const micro = mockWinnerMicro(w);
+  if (micro === void 0) return {};
+  return { amount: formatMicroToUsd(micro), amountMicro: micro.toString() };
+}
+var TERMINALS = ["none", "settled", "refunded", "rolled"];
+function terminalFromChain(raw) {
+  return TERMINALS[raw] ?? "none";
+}
+function requireSeries(series) {
+  if (typeof series !== "string" || series.trim() === "") {
+    throw new MissingFieldError("series");
+  }
+  return series.trim();
+}
+function requireIdentity(identity) {
+  if (typeof identity !== "string" || identity.trim() === "") {
+    throw new MissingFieldError("identity");
+  }
+  return identity.trim();
+}
+function assertPinParity(label, local, fromService) {
+  if (!fromService) {
+    throw new ConfigError(
+      `epochs.enter: the service did not return ${label}Bytes32 \u2014 cannot prove the on-chain id matches before paying.`,
+      { field: `${label}Bytes32` }
+    );
+  }
+  if (local.toLowerCase() !== fromService.toLowerCase()) {
+    throw new ConfigError(
+      `epochs.enter: ${label} derives differently in the SDK and the service (sdk=${local}, service=${fromService}). Refusing to enter \u2014 a paid entry under a mismatched id is never scored. See sdk#633.`,
+      { field: `${label}Bytes32` }
+    );
+  }
+}
+function epochPathId(epochId) {
+  if (epochId === void 0 || epochId === null || epochId === "") return "current";
+  const s = String(epochId).trim();
+  if (s === "current") return "current";
+  if (!/^\d+$/.test(s)) {
+    throw new ConfigError(`epochId must be a non-negative integer, got: ${JSON.stringify(epochId)}`);
+  }
+  return s;
+}
+function qs(params) {
+  const u = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v) u.set(k, v);
+  }
+  const s = u.toString();
+  return s ? `?${s}` : "";
+}
+function pictureFromMicros(args) {
+  const payableMicro = epochPayableMicro(args.incomingSeedMicro, args.poolMicro);
+  return {
+    series: args.series,
+    epochId: args.epochId,
+    pool: formatMicroToUsd(args.poolMicro),
+    incomingSeed: formatMicroToUsd(args.incomingSeedMicro),
+    outgoingSeed: formatMicroToUsd(args.outgoingSeedMicro),
+    payable: formatMicroToUsd(payableMicro),
+    poolMicro: args.poolMicro.toString(),
+    incomingSeedMicro: args.incomingSeedMicro.toString(),
+    outgoingSeedMicro: args.outgoingSeedMicro.toString(),
+    payableMicro: payableMicro.toString(),
+    via: args.via,
+    epochPrizePool: args.epochPrizePool,
+    ...args.mock ? { mock: true } : {}
+  };
+}
+function toBig(value, fallback) {
+  if (value === void 0) return fallback;
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0) return BigInt(Math.trunc(value));
+  if (typeof value === "string" && /^\d+$/.test(value.trim())) return BigInt(value.trim());
+  throw new ConfigError(`expected a non-negative integer, got: ${JSON.stringify(value)}`);
+}
 var ADDRESS_RE2 = /^0x[0-9a-fA-F]{40}$/;
+function requireAddr(raw, field) {
+  if (typeof raw !== "string" || !ADDRESS_RE2.test(raw.trim())) {
+    throw new MissingFieldError(field);
+  }
+  return raw.trim().toLowerCase();
+}
+function requireAddrKeepCase(raw, field) {
+  if (typeof raw !== "string" || !ADDRESS_RE2.test(raw.trim())) {
+    throw new MissingFieldError(field);
+  }
+  return raw.trim();
+}
+function requireEpochPool(input, cfg) {
+  const raw = input?.epochPrizePool ?? cfg.contracts?.epochPrizePool;
+  if (!raw) {
+    throw new ConfigError(
+      "epochs refund rail needs contracts.epochPrizePool (or pass epochPrizePool) \u2014 this is EpochPrizePool, not PrizePool",
+      { field: "epochPrizePool" }
+    );
+  }
+  return requireAddr(raw, "epochPrizePool");
+}
+function requirePastEpochId(epochId) {
+  const id = epochPathId(epochId);
+  if (id === "current") {
+    throw new ConfigError("epochs refund rail requires a past epochId \u2014 Current is still taking entries");
+  }
+  return id;
+}
+function walletStatus(status) {
+  if (status === "CONFIRMED") return "confirmed";
+  if (status === "FAILED") return "failed";
+  return "pending";
+}
+function sameAddr(a, b) {
+  return a.toLowerCase() === b.toLowerCase();
+}
+function prepareStudioPoolLocal(input, playmosFeeSink, token, playmosAddresses = []) {
+  const studio = requireAddr(input.studioWallet, "studioWallet");
+  const sink = playmosFeeSink.toLowerCase();
+  const forbidden = [sink, ...playmosAddresses.map((a) => a.toLowerCase())];
+  if (forbidden.some((a) => sameAddr(a, studio))) {
+    throw new ConfigError("studioWallet must not be a Playmos address (Playmos never holds studio keys)");
+  }
+  if (input.feeSink && !sameAddr(input.feeSink, sink)) {
+    throw new ConfigError("feeSink must equal the Playmos sink; refused before broadcast");
+  }
+  if (input.admin && !sameAddr(input.admin, studio)) {
+    throw new ConfigError("admin must be the studio wallet from block one");
+  }
+  if (input.operator && !sameAddr(input.operator, studio)) {
+    throw new ConfigError("operator must be the studio wallet from block one");
+  }
+  if (input.admin && forbidden.some((a) => sameAddr(a, input.admin))) {
+    throw new ConfigError("Playmos must not be ADMIN_ROLE");
+  }
+  if (input.operator && forbidden.some((a) => sameAddr(a, input.operator))) {
+    throw new ConfigError("Playmos must not be OPERATOR_ROLE");
+  }
+  const refundTimeout = toBig(input.refundTimeout, 604800n);
+  if (refundTimeout < 3600n || refundTimeout > 7776000n) {
+    throw new ConfigError("refundTimeout must be between 3600 (1h) and 7776000 (90d) seconds");
+  }
+  return {
+    token: token.toLowerCase(),
+    admin: studio,
+    operator: studio,
+    feeSink: sink,
+    refundTimeout: refundTimeout.toString(),
+    constructorArgs: encodeEpochPoolConstructorArgs({
+      token: token.toLowerCase(),
+      admin: studio,
+      operator: studio,
+      feeSink: sink,
+      refundTimeout
+    }),
+    constructor: "EpochPrizePool",
+    studioHoldsAdmin: true,
+    studioHoldsOperator: true,
+    playmosIsAdmin: false,
+    playmosIsOperator: false,
+    via: "mock",
+    mock: true
+  };
+}
+function epochPoolProofMessage(terms) {
+  return [
+    "Playmos EpochPrizePool registration",
+    `studio: ${terms.studioId}`,
+    `pool: ${terms.poolAddress.toLowerCase()}`,
+    `wallet: ${terms.studioWallet.toLowerCase()}`,
+    `chainId: ${terms.chainId}`
+  ].join("\n");
+}
+async function readWithdrawableMicro(deps, pool) {
+  const read = deps.readView;
+  const account = deps.walletAddress;
+  if (!read || !account) return null;
+  try {
+    const raw = await read(
+      pool,
+      encodeFunctionData({
+        abi: epochPrizePoolViewAbi,
+        functionName: "withdrawable",
+        args: [await account()]
+      })
+    );
+    return decodeFunctionResult({
+      abi: epochPrizePoolViewAbi,
+      functionName: "withdrawable",
+      data: raw
+    });
+  } catch {
+    return null;
+  }
+}
+function settlementTypedData(input) {
+  const pool = requireAddr(input.pool, "pool");
+  const series = requireSeries(input.series);
+  const epochId = requirePastEpochId(input.epochId);
+  if (!Array.isArray(input.winners) || !Array.isArray(input.amounts)) {
+    throw new MissingFieldError("winners");
+  }
+  if (input.winners.length !== input.amounts.length) {
+    throw new ConfigError("winners and amounts must be the same length");
+  }
+  return {
+    domain: {
+      name: "EpochPrizePool",
+      version: "1",
+      chainId: input.chainId,
+      verifyingContract: pool
+    },
+    types: {
+      Settlement: [
+        { name: "series", type: "bytes32" },
+        { name: "epochId", type: "uint256" },
+        { name: "winners", type: "address[]" },
+        { name: "amounts", type: "uint256[]" }
+      ]
+    },
+    primaryType: "Settlement",
+    message: {
+      series: seriesToBytes32(series),
+      epochId: BigInt(epochId),
+      winners: input.winners.map((w, i) => requireAddrKeepCase(w, `winners[${i}]`)),
+      amounts: input.amounts.map((a, i) => parseMicroString(a, `amounts[${i}]`))
+    }
+  };
+}
+function parseMicroString(raw, field) {
+  if (typeof raw !== "string" || !/^(0|[1-9]\d*)$/.test(raw)) {
+    throw new ConfigError(`${field} must be an integer micro-USDC string`, { field });
+  }
+  return BigInt(raw);
+}
+async function readEpochTerminal(deps, pool, series, epochId) {
+  const read = deps.readView;
+  if (!read) return null;
+  try {
+    const raw = await read(
+      pool,
+      encodeFunctionData({
+        abi: epochPrizePoolViewAbi,
+        functionName: "getEpoch",
+        args: [seriesToBytes32(series), BigInt(epochId)]
+      })
+    );
+    const decoded = decodeFunctionResult({
+      abi: epochPrizePoolViewAbi,
+      functionName: "getEpoch",
+      data: raw
+    });
+    const termRaw = decoded && typeof decoded === "object" && "terminal" in decoded ? Number(decoded.terminal) : Number(decoded[4]);
+    return terminalFromChain(termRaw);
+  } catch {
+    return null;
+  }
+}
+function createEpochsApi(deps) {
+  return {
+    async currentId(input) {
+      const series = requireSeries(input?.series);
+      const cfg = deps.config();
+      if (cfg.mock) {
+        const genesis = toBig(input.genesis, 0n);
+        const duration = toBig(input.epochDuration, 1n);
+        const at = toBig(input.at, BigInt(Math.floor(Date.now() / 1e3)));
+        const epochId = derivedEpochId(genesis, duration, at);
+        return {
+          series,
+          epochId: epochId.toString(),
+          via: "mock",
+          epochPrizePool: input.epochPrizePool ?? cfg.contracts?.epochPrizePool ?? null,
+          mock: true
+        };
+      }
+      const path = `/epochs/current${qs({
+        series,
+        epochPrizePool: input.epochPrizePool ?? cfg.contracts?.epochPrizePool
+      })}`;
+      return deps.http().get(path);
+    },
+    async prize(input) {
+      const series = requireSeries(input?.series);
+      const cfg = deps.config();
+      const epochId = epochPathId(input?.epochId);
+      if (cfg.mock) {
+        return pictureFromMicros({
+          series,
+          epochId: epochId === "current" ? "0" : epochId,
+          poolMicro: 0n,
+          incomingSeedMicro: 0n,
+          outgoingSeedMicro: 0n,
+          via: "mock",
+          epochPrizePool: input.epochPrizePool ?? cfg.contracts?.epochPrizePool ?? null,
+          mock: true
+        });
+      }
+      const path = `/epochs/${encodeURIComponent(epochId)}/prize${qs({
+        series,
+        epochPrizePool: input.epochPrizePool ?? cfg.contracts?.epochPrizePool
+      })}`;
+      const res = await deps.http().get(path);
+      return res.prize;
+    },
+    async get(input) {
+      const series = requireSeries(input?.series);
+      const cfg = deps.config();
+      const epochId = epochPathId(input?.epochId);
+      if (cfg.mock) {
+        const prize = pictureFromMicros({
+          series,
+          epochId: epochId === "current" ? "0" : epochId,
+          poolMicro: 0n,
+          incomingSeedMicro: 0n,
+          outgoingSeedMicro: 0n,
+          via: "mock",
+          epochPrizePool: input.epochPrizePool ?? cfg.contracts?.epochPrizePool ?? null,
+          mock: true
+        });
+        return {
+          ...prize,
+          entryCount: "0",
+          terminal: "none"
+        };
+      }
+      const path = `/epochs/${encodeURIComponent(epochId)}${qs({
+        series,
+        epochPrizePool: input.epochPrizePool ?? cfg.contracts?.epochPrizePool
+      })}`;
+      return deps.http().get(path);
+    },
+    async getSeries(input) {
+      const series = requireSeries(input?.series);
+      const cfg = deps.config();
+      if (cfg.mock) {
+        return {
+          series,
+          created: true,
+          genesis: "0",
+          epochDuration: "1",
+          entry: "0",
+          feeBps: 1e3,
+          poolBps: 6e3,
+          seedBps: 3e3,
+          via: "mock",
+          epochPrizePool: input.epochPrizePool ?? cfg.contracts?.epochPrizePool ?? null,
+          mock: true
+        };
+      }
+      const path = `/epochs/series${qs({
+        series,
+        epochPrizePool: input.epochPrizePool ?? cfg.contracts?.epochPrizePool
+      })}`;
+      return deps.http().get(path);
+    },
+    async preparePool(input) {
+      const studioWallet = requireAddr(input?.studioWallet, "studioWallet");
+      const cfg = deps.config();
+      const sink = (input.playmosFeeSink ?? PLAYMOS_FEE_SINK_DEFAULT).toLowerCase();
+      const token = (input.token ?? cfg.contracts?.usdc ?? "0x036cbd53842c5426634e7929541ec2318f3dcf7e").toLowerCase();
+      if (cfg.mock) {
+        return prepareStudioPoolLocal({ ...input, studioWallet }, sink, token);
+      }
+      return deps.http().post("/epochs/pools/prepare", {
+        studioWallet,
+        feeSink: input.feeSink,
+        admin: input.admin,
+        operator: input.operator,
+        refundTimeout: input.refundTimeout
+      });
+    },
+    async registerPool(input) {
+      const studioWallet = requireAddr(input?.studioWallet, "studioWallet");
+      const poolAddress = requireAddr(input?.poolAddress, "poolAddress");
+      const cfg = deps.config();
+      if (cfg.mock) {
+        const sink = (input.feeSink ?? PLAYMOS_FEE_SINK_DEFAULT).toLowerCase();
+        const token = (cfg.contracts?.usdc ?? "0x036cbd53842c5426634e7929541ec2318f3dcf7e").toLowerCase();
+        const prepared = prepareStudioPoolLocal({ studioWallet, feeSink: input.feeSink, admin: input.admin, operator: input.operator }, sink, token);
+        return {
+          poolAddress,
+          studioWallet: prepared.admin,
+          feeSink: prepared.feeSink,
+          admin: prepared.admin,
+          operator: prepared.operator,
+          studioHoldsAdmin: true,
+          studioHoldsOperator: true,
+          playmosIsAdmin: false,
+          playmosIsOperator: false,
+          ownership: input.walletProof ? "confirmed" : "pending",
+          owner: null,
+          via: "mock",
+          mock: true
+        };
+      }
+      return deps.http().post("/epochs/pools", {
+        studioWallet,
+        poolAddress,
+        feeSink: input.feeSink,
+        admin: input.admin,
+        operator: input.operator,
+        txHash: input.txHash,
+        walletProof: input.walletProof
+      });
+    },
+    async createPool(input) {
+      const prepared = await this.preparePool(input);
+      const cfg = deps.config();
+      if (cfg.mock) {
+        const poolAddress = input.poolAddress ? requireAddr(input.poolAddress, "poolAddress") : `0x${prepared.constructorArgs.slice(2, 42).padEnd(40, "0")}`;
+        return this.registerPool({
+          studioWallet: prepared.admin,
+          poolAddress,
+          feeSink: prepared.feeSink,
+          walletProof: input.walletProof
+        });
+      }
+      if (!input.poolAddress) {
+        throw new ConfigError(
+          "createPool on the live path needs poolAddress after the studio wallet submits the constructor \u2014 Playmos does not broadcast"
+        );
+      }
+      return this.registerPool({
+        studioWallet: prepared.admin,
+        poolAddress: input.poolAddress,
+        feeSink: prepared.feeSink,
+        txHash: input.txHash,
+        walletProof: input.walletProof
+      });
+    },
+    async settle(input) {
+      const series = requireSeries(input?.series);
+      if (!Array.isArray(input?.winners)) {
+        throw new MissingFieldError("winners");
+      }
+      const epochId = epochPathId(input?.epochId);
+      if (epochId === "current") {
+        throw new ConfigError("epochs.settle requires a past epochId \u2014 Current is still taking entries");
+      }
+      const cfg = deps.config();
+      if (!cfg.mock) {
+        if (deps.assertSecretKey) deps.assertSecretKey("playmos.epochs.settle");
+        else if (!String(cfg.apiKey ?? "").startsWith("sk_")) {
+          throw new AuthError(
+            "playmos.epochs.settle requires a secret (sk_) key \u2014 use sk_test_\u2026 / sk_live_\u2026 on the server. Publishable (pk_) keys cannot settle.",
+            { surface: "playmos.epochs.settle", isSecret: false }
+          );
+        }
+      }
+      if (cfg.mock) {
+        const empty = input.winners.length === 0;
+        const podiumPayable = mockPodiumPayable(input.winners);
+        return {
+          series,
+          epochId,
+          status: empty ? "rolled" : "settled",
+          txHash: "0x0000000000000000000000000000000000000000000000000000000000000001",
+          winners: input.winners.map((w) => {
+            const wallet = (typeof w === "string" ? w : w.wallet).toLowerCase();
+            return { wallet, ...mockWinnerAmount(w) };
+          }),
+          ...podiumPayable ?? {},
+          terminal: empty ? "rolled" : "settled",
+          via: "mock",
+          epochPrizePool: input.epochPrizePool ?? cfg.contracts?.epochPrizePool ?? null,
+          mock: true
+        };
+      }
+      const body = await deps.http().post(
+        `/epochs/${encodeURIComponent(epochId)}/settle`,
+        {
+          series,
+          winners: input.winners,
+          epochPrizePool: input.epochPrizePool ?? cfg.contracts?.epochPrizePool
+        },
+        { acceptStatuses: [200, 202] }
+      );
+      return body.settle;
+    },
+    async enter(input) {
+      const series = requireSeries(input?.series);
+      const identity = requireIdentity(input?.identity);
+      const cfg = deps.config();
+      const seriesBytes32 = seriesToBytes32(series);
+      const identityBytes32 = identityToBytes32(identity);
+      if (cfg.mock) {
+        const genesis = toBig(input.genesis, 0n);
+        const duration = toBig(input.epochDuration, 1n);
+        const at = toBig(input.at, BigInt(Math.floor(Date.now() / 1e3)));
+        return {
+          series,
+          identity,
+          epochId: derivedEpochId(genesis, duration, at).toString(),
+          epochIdSource: "mock",
+          seriesBytes32,
+          identityBytes32,
+          entry: formatMicroToUsd(C1_ENTER_SPLIT_MICRO.entry),
+          entryMicro: C1_ENTER_SPLIT_MICRO.entry.toString(),
+          status: "confirmed",
+          txHash: MOCK_TX,
+          identityEntryCount: "1",
+          epochPrizePool: input.epochPrizePool ?? cfg.contracts?.epochPrizePool ?? null,
+          usdc: cfg.contracts?.usdc ?? null,
+          via: "mock",
+          mock: true
+        };
+      }
+      const epochPrizePool = input.epochPrizePool ?? cfg.contracts?.epochPrizePool;
+      const plan = await deps.http().post("/epochs/enter", {
+        series,
+        identity,
+        ...epochPrizePool ? { epochPrizePool } : {}
+      });
+      assertPinParity("series", seriesBytes32, plan.clientParams?.seriesBytes32);
+      assertPinParity("identity", identityBytes32, plan.clientParams?.identityBytes32);
+      const send = deps.sendEntry;
+      if (!send) {
+        throw new ConfigError(
+          "epochs.enter needs a player wallet \u2014 pass `wallet` to the Playmos client. Entry money goes straight to the contract; Playmos never holds it. Building the calls yourself? Import `buildEpochEntryCalls`.",
+          { field: "wallet" }
+        );
+      }
+      const entryMicro = BigInt(plan.clientParams.entryMicro);
+      const calls = buildEpochEntryCalls({
+        usdc: plan.clientParams.usdc,
+        epochPrizePool: plan.clientParams.epochPrizePool,
+        series,
+        identity,
+        entryMicro
+      });
+      const sent = await send(calls, { paymasterUrl: plan.clientParams.paymasterUrl });
+      const base = {
+        series,
+        identity,
+        epochId: plan.entry.epochId,
+        epochIdSource: "chain-clock",
+        seriesBytes32,
+        identityBytes32,
+        entry: plan.entry.entry,
+        entryMicro: plan.entry.entryMicro,
+        status: sent.status === "FAILED" ? "failed" : "pending",
+        txHash: sent.txHash,
+        epochPrizePool: plan.clientParams.epochPrizePool,
+        usdc: plan.clientParams.usdc,
+        via: "service"
+      };
+      if (!sent.txHash) return base;
+      try {
+        const confirmed = await deps.http().post("/epochs/enter/confirm", {
+          series,
+          identity,
+          txHash: sent.txHash,
+          ...epochPrizePool ? { epochPrizePool } : {}
+        });
+        return {
+          ...base,
+          epochId: confirmed.entry.epochId,
+          epochIdSource: confirmed.entry.epochIdSource,
+          status: confirmed.entry.status,
+          identityEntryCount: confirmed.entry.identityEntryCount
+        };
+      } catch {
+        return base;
+      }
+    },
+    async claimableRefund(input) {
+      const series = requireSeries(input?.series);
+      const payer = requireAddr(input?.payer, "payer");
+      const epochId = requirePastEpochId(input?.epochId);
+      const cfg = deps.config();
+      const seriesBytes32 = seriesToBytes32(series);
+      const epochPrizePool = input.epochPrizePool ?? cfg.contracts?.epochPrizePool ?? null;
+      if (cfg.mock) {
+        return {
+          series,
+          epochId,
+          payer,
+          claimable: "0.00",
+          claimableMicro: "0",
+          seriesBytes32,
+          epochPrizePool,
+          via: "mock",
+          mock: true
+        };
+      }
+      const pool = requireEpochPool(input, cfg);
+      const data = encodeFunctionData({
+        abi: epochPrizePoolViewAbi,
+        functionName: "claimableRefund",
+        args: [seriesBytes32, BigInt(epochId), payer]
+      });
+      const read = deps.readView;
+      if (!read) {
+        throw new ConfigError(
+          "epochs.claimableRefund needs a wallet or RPC to read EpochPrizePool \u2014 pass `wallet` to the Playmos client",
+          { field: "wallet" }
+        );
+      }
+      const raw = await read(pool, data);
+      const amount = decodeFunctionResult({
+        abi: epochPrizePoolViewAbi,
+        functionName: "claimableRefund",
+        data: raw
+      });
+      return {
+        series,
+        epochId,
+        payer,
+        claimable: formatMicroToUsd(amount),
+        claimableMicro: amount.toString(),
+        seriesBytes32,
+        epochPrizePool: pool,
+        via: "chain"
+      };
+    },
+    async claimRefund(input) {
+      const series = requireSeries(input?.series);
+      const payer = requireAddr(input?.payer, "payer");
+      const epochId = requirePastEpochId(input?.epochId);
+      const cfg = deps.config();
+      const pool = requireEpochPool(input, cfg);
+      if (cfg.mock) {
+        return {
+          series,
+          epochId,
+          payer,
+          txHash: MOCK_TX,
+          status: "confirmed",
+          epochPrizePool: pool,
+          via: "mock",
+          mock: true
+        };
+      }
+      const send = deps.sendEntry;
+      if (!send) {
+        throw new ConfigError(
+          "epochs.claimRefund needs a player wallet \u2014 pass `wallet` to the Playmos client. The credit lands on `payer`; the connected wallet only signs.",
+          { field: "wallet" }
+        );
+      }
+      const call = buildEpochClaimRefundCall({
+        epochPrizePool: pool,
+        series,
+        epochId: BigInt(epochId),
+        payer
+      });
+      const sent = await send([call], {});
+      return {
+        series,
+        epochId,
+        payer,
+        txHash: sent.txHash,
+        status: walletStatus(sent.status),
+        epochPrizePool: pool,
+        via: "chain"
+      };
+    },
+    async withdraw(input = {}) {
+      const cfg = deps.config();
+      const pool = requireEpochPool(input, cfg);
+      if (cfg.mock) {
+        return {
+          epochPrizePool: pool,
+          txHash: MOCK_TX,
+          status: "confirmed",
+          via: "mock",
+          mock: true
+        };
+      }
+      const send = deps.sendEntry;
+      if (!send) {
+        throw new ConfigError(
+          "epochs.withdraw needs the payer wallet \u2014 pass `wallet` to the Playmos client. USDC is pulled to msg.sender on EpochPrizePool, not PrizePool.",
+          { field: "wallet" }
+        );
+      }
+      const creditedMicro = await readWithdrawableMicro(deps, pool);
+      const call = buildEpochWithdrawCall(pool);
+      const sent = await send([call], {});
+      return {
+        epochPrizePool: pool,
+        ...creditedMicro === null ? {} : {
+          amount: formatMicroToUsd(creditedMicro),
+          amountMicro: creditedMicro.toString()
+        },
+        txHash: sent.txHash,
+        status: walletStatus(sent.status),
+        via: "chain"
+      };
+    },
+    async getAttestation(input) {
+      const series = requireSeries(input?.series);
+      const epochId = requirePastEpochId(input?.epochId);
+      const cfg = deps.config();
+      if (cfg.mock) {
+        const pool = input.epochPrizePool ?? cfg.contracts?.epochPrizePool;
+        if (!pool) {
+          throw new ConfigError("epochs.getAttestation needs contracts.epochPrizePool (or pass epochPrizePool)", {
+            field: "epochPrizePool"
+          });
+        }
+        return {
+          series,
+          epochId,
+          winners: input.winners ?? [],
+          amountsMicro: input.amountsMicro ?? [],
+          signature: input.signature ?? `0x${"00".repeat(65)}`,
+          epochPrizePool: requireAddr(pool, "epochPrizePool"),
+          via: "mock",
+          mock: true
+        };
+      }
+      const path = `/epochs/${encodeURIComponent(epochId)}/attestation${qs({
+        series,
+        epochPrizePool: input.epochPrizePool ?? cfg.contracts?.epochPrizePool
+      })}`;
+      const res = await deps.http().get(path);
+      const inner = res.attestation ?? res;
+      if (!inner.series || !inner.winners || !inner.amountsMicro || !inner.signature || !inner.epochPrizePool) {
+        throw new ConfigError("attestation response missing posted fields \u2014 refusing to invent a podium");
+      }
+      return {
+        series: inner.series,
+        epochId: String(inner.epochId ?? epochId),
+        winners: inner.winners,
+        amountsMicro: inner.amountsMicro,
+        signature: inner.signature,
+        epochPrizePool: inner.epochPrizePool,
+        ...res.terminal !== void 0 ? { terminal: res.terminal } : {},
+        ...res.dueAt !== void 0 ? { dueAt: res.dueAt } : {},
+        via: res.via ?? "service"
+      };
+    },
+    async executeSettlement(input) {
+      const series = requireSeries(input?.series);
+      const epochId = requirePastEpochId(input?.epochId);
+      if (!Array.isArray(input?.winners)) throw new MissingFieldError("winners");
+      if (!Array.isArray(input?.amounts)) throw new MissingFieldError("amounts");
+      if (typeof input?.signature !== "string" || !/^0x[0-9a-fA-F]{130}$/.test(input.signature)) {
+        throw new MissingFieldError("signature");
+      }
+      const winners = input.winners.map((w, i) => requireAddrKeepCase(w, `winners[${i}]`));
+      const amountsMicro = input.amounts.map((a, i) => {
+        parseMicroString(a, `amounts[${i}]`);
+        return a;
+      });
+      const amounts = amountsMicro.map((a, i) => parseMicroString(a, `amounts[${i}]`));
+      const cfg = deps.config();
+      const pool = requireEpochPool(input, cfg);
+      if (cfg.mock) {
+        return {
+          series,
+          epochId,
+          winners,
+          amountsMicro,
+          signature: input.signature,
+          txHash: MOCK_TX,
+          status: "confirmed",
+          epochPrizePool: pool,
+          via: "mock",
+          mock: true
+        };
+      }
+      const send = deps.sendEntry;
+      if (!send) {
+        throw new ConfigError(
+          "epochs.executeSettlement needs a wallet \u2014 pass `wallet` to the Playmos client. The SDK relays the signed podium; it does not choose winners.",
+          { field: "wallet" }
+        );
+      }
+      const call = buildEpochExecuteSettlementCall({
+        epochPrizePool: pool,
+        series,
+        epochId: BigInt(epochId),
+        winners,
+        amounts,
+        signature: input.signature
+      });
+      let sent;
+      try {
+        sent = await send([call], {});
+      } catch (e) {
+        const msg = e?.message ?? String(e);
+        throw new PaymentFailedError("EpochPrizePool.executeSignedSettlement failed.", { cause: msg });
+      }
+      const terminal = await readEpochTerminal(deps, pool, series, epochId);
+      return {
+        series,
+        epochId,
+        winners,
+        amountsMicro,
+        signature: input.signature,
+        txHash: sent.txHash,
+        status: walletStatus(sent.status),
+        ...terminal === null ? {} : { terminal, settled: terminal === "settled" },
+        epochPrizePool: pool,
+        via: "chain"
+      };
+    }
+  };
+}
+var C1_ENTER_SPLIT_MICRO = {
+  entry: 1000000n,
+  fee: 100000n,
+  pool: 600000n,
+  outgoingSeed: 300000n,
+  incomingSeed: 0n
+};
+
+// src/x402.ts
+var ADDRESS_RE3 = /^0x[0-9a-fA-F]{40}$/;
 function requireAddress2(value, field) {
   if (typeof value !== "string" || value.trim() === "") {
     throw new MissingFieldError(field);
   }
-  if (!ADDRESS_RE2.test(value)) {
+  if (!ADDRESS_RE3.test(value)) {
     throw new ConfigError(`${field} must be a 0x-prefixed 20-byte address, got: ${JSON.stringify(value)}`, {
       field,
       value
@@ -953,7 +1697,7 @@ function validateX402ChallengeInput(input) {
 }
 
 // src/client.ts
-var ADDRESS_RE3 = /^0x[0-9a-fA-F]{40}$/;
+var ADDRESS_RE4 = /^0x[0-9a-fA-F]{40}$/;
 function mapAlreadyEntered(e) {
   const msg = e instanceof Error ? e.message : typeof e === "object" && e && "message" in e ? String(e.message) : String(e);
   const detail = e instanceof PaymentFailedError || e instanceof ApiError ? e.detail : void 0;
@@ -1001,7 +1745,7 @@ function requireAddressField(value, field) {
   if (typeof value !== "string" || value.trim() === "") {
     throw new MissingFieldError(field);
   }
-  if (!ADDRESS_RE3.test(value)) {
+  if (!ADDRESS_RE4.test(value)) {
     throw new ConfigError(
       `${field} must be a 0x-prefixed 20-byte wallet address (Phase 1a transfers settle server-held wallets), got: ${JSON.stringify(value)}`,
       { field, value }
@@ -1040,6 +1784,56 @@ var Playmos = class {
         );
       }
     };
+    /**
+     * Rolling epochs — `currentId` / `prize` / `get` / `getSeries` (sdk#629),
+     * `enter` (sdk#635 / S2), operator `settle` (sdk#639 / S3), the C3
+     * refund pull (sdk#634), and E1b `getAttestation` / `executeSettlement`
+     * (wallet-direct via the same `walletProvider()` funnel as `rounds.withdraw`).
+     * Reads/settle go through the service. Refund claim, withdraw, and signed
+     * execute are wallet-direct on EpochPrizePool — not PrizePool.
+     * Nothing here opens a round.
+     */
+    this.epochs = createEpochsApi({
+      http: () => this.http,
+      config: () => this.config,
+      assertSecretKey: (surface) => this.assertSecretKey(surface),
+      sendEntry: async (calls, opts) => {
+        const provider = this.walletProvider();
+        if (this.config.gas?.mode === "player") {
+          await assertEnoughGas(provider, await getAccount(provider));
+        }
+        const from = await getAccount(provider);
+        const paymasterUrl = this.config.gas?.mode === "player" ? void 0 : this.config.gas?.paymasterUrl ?? opts.paymasterUrl;
+        const { id } = await sendCalls(provider, from, this.env.chainId, calls, paymasterUrl);
+        return waitForCalls(provider, id);
+      },
+      walletAddress: async () => getAccount(this.walletProvider()),
+      readView: async (to, data) => {
+        if (await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
+          const provider = this.walletProvider();
+          return await provider.request({
+            method: "eth_call",
+            params: [{ to, data }, "latest"]
+          });
+        }
+        const rpc = this.env.network === "base" ? "https://mainnet.base.org" : "https://sepolia.base.org";
+        const res = await fetch(rpc, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "eth_call",
+            params: [{ to, data }, "latest"]
+          })
+        });
+        const json = await res.json();
+        if (!json.result) {
+          throw new ApiError(`eth_call failed: ${json.error?.message ?? "no result"}`, { to });
+        }
+        return json.result;
+      }
+    });
     this.payouts = {
       /** Choose how the studio is paid: "usdc" (default) or "fiat" (Bridge). Secret key only (#264). */
       setMode: async (mode) => {
@@ -1205,6 +1999,8 @@ var Playmos = class {
     this.mockPotMicro = /* @__PURE__ */ new Map();
     /** Persisted settle winners for re-settle replay (#490 C2) — never re-invent pool-to-everyone. */
     this.mockSettleWinners = /* @__PURE__ */ new Map();
+    /** L34 notices after mock settle — funded only with a push txHash. */
+    this.mockPayoutNotices = /* @__PURE__ */ new Map();
     this.rounds = {
       open: async (input) => {
         if (!this.config.mock) this.assertSecretKey("playmos.rounds.open");
@@ -1370,6 +2166,16 @@ var Playmos = class {
           };
           this.mockRounds.set(input.roundId, settled);
           this.mockSettleWinners.set(input.roundId, winners);
+          this.mockPayoutNotices.set(
+            input.roundId,
+            rows.filter((w) => w.micro > 0n).map((w) => ({
+              roundId: input.roundId,
+              wallet: w.wallet.toLowerCase(),
+              amountMicro: w.micro.toString(),
+              status: "claimable",
+              reason: "prizepool_pull_credit"
+            }))
+          );
           for (const w of rows) {
             if (w.micro <= 0n) continue;
             const k = `${input.roundId}:${w.wallet.toLowerCase()}`;
@@ -1611,6 +2417,93 @@ var Playmos = class {
         }
         return body.active;
       },
+      /**
+       * L34 / sdk#610 — notifications for a settled round.
+       * Each win is `funded` (push txHash) or `claimable` (withdraw fallback).
+       * Never returns `funded` without a transfer txHash.
+       */
+      payoutNotices: async (input) => {
+        requireField(input?.roundId, "roundId");
+        if (this.config.mock) {
+          const existing = this.mockRounds.get(input.roundId);
+          if (!existing) {
+            throw new ApiError(`unknown round: ${input.roundId}`, { status: 404, code: "not_found" });
+          }
+          let notices = this.mockPayoutNotices.get(input.roundId) ?? [];
+          if (input.wallet) {
+            if (!ADDRESS_RE4.test(input.wallet)) {
+              throw new ConfigError("wallet must be a 0x-prefixed 20-byte address");
+            }
+            const want = input.wallet.toLowerCase();
+            notices = notices.filter((n) => n.wallet === want);
+          }
+          for (const n of notices) {
+            if (n.status === "funded" && !n.txHash) {
+              throw new ApiError("cannot label funded without a transfer txHash", {
+                status: 500,
+                code: "payout_notice_invalid"
+              });
+            }
+          }
+          return { roundId: input.roundId, status: existing.status, notices };
+        }
+        const q = input.wallet ? `?wallet=${encodeURIComponent(input.wallet)}` : "";
+        return this.http.get(
+          `/rounds/${encodeURIComponent(input.roundId)}/payout-notices${q}`
+        );
+      },
+      /**
+       * Operator push-attempt after settle (L34). Mock: mark a winner funded only
+       * when a real-shaped txHash is supplied; otherwise that row stays claimable.
+       */
+      pushWinnings: async (input) => {
+        requireField(input?.roundId, "roundId");
+        if (!this.config.mock) this.assertSecretKey("playmos.rounds.pushWinnings");
+        if (this.config.mock) {
+          const existing = this.mockRounds.get(input.roundId);
+          if (!existing) {
+            throw new ApiError(`unknown round: ${input.roundId}`, { status: 404, code: "not_found" });
+          }
+          if (existing.status !== "settled") {
+            throw new ApiError(`round ${input.roundId} is not settled \u2014 push after the clock`, {
+              status: 409,
+              code: "conflict"
+            });
+          }
+          const prior = this.mockPayoutNotices.get(input.roundId) ?? [];
+          const byWallet = new Map(
+            (input.pushes ?? []).map((p) => [p.wallet.toLowerCase(), p])
+          );
+          const TX_RE = /^0x[0-9a-fA-F]{64}$/;
+          const ZERO = "0x" + "00".repeat(32);
+          const notices = prior.map((n) => {
+            const p = byWallet.get(n.wallet);
+            if (p && !p.failed && p.txHash && TX_RE.test(p.txHash) && p.txHash.toLowerCase() !== ZERO) {
+              return {
+                ...n,
+                status: "funded",
+                txHash: p.txHash.toLowerCase(),
+                reason: void 0
+              };
+            }
+            if (p && (p.failed || !p.txHash || !TX_RE.test(p.txHash) || p.txHash.toLowerCase() === ZERO)) {
+              return {
+                ...n,
+                status: "claimable",
+                txHash: void 0,
+                reason: p.failed ? "push_failed" : "push_missing_txHash"
+              };
+            }
+            return n;
+          });
+          this.mockPayoutNotices.set(input.roundId, notices);
+          return { roundId: input.roundId, status: existing.status, notices };
+        }
+        return this.http.post(
+          `/rounds/${encodeURIComponent(input.roundId)}/push-winnings`,
+          {}
+        );
+      },
       /**
        * Read a wallet's **claimable** prize balance for a round (issue #41).
        * Prefers the service chain read (`GET /v1/rounds/:id/prize?wallet=`); falls
@@ -1667,7 +2560,7 @@ var Playmos = class {
             const existing = this.mockRounds.get(input.roundId);
             if (existing?.prizePoolAddress) prizePool2 = existing.prizePoolAddress;
           }
-          if (!input.wallet || !ADDRESS_RE3.test(input.wallet)) {
+          if (!input.wallet || !ADDRESS_RE4.test(input.wallet)) {
             throw new ConfigError(
               "mock rounds.withdraw requires wallet (0x\u2026) \u2014 live uses the connected provider; without wallet mock would pay the first non-zero credit to the wrong player (#495)"
             );
@@ -1953,8 +2846,16 @@ var Playmos = class {
     /**
      * Offline mock payments for this client instance — so `verify(id)` after
      * `mock: true` pay/enterRound does not hit the live API (#204).
+     * Keyed by payment id for verify.
      */
     this.mockPayments = /* @__PURE__ */ new Map();
+    /**
+     * sdk#513 / residual B1–B2 — held idempotencyKey offline (live contract rehearsal).
+     * Keyed like service: `${gameId}:${key}` (IAP without gameId uses empty gameId).
+     * Stores terms so same key + different money throws (live IdempotencyConflict), not silent replay.
+     * Auto-minted keys still unique per call (not stored for cross-call replay).
+     */
+    this.mockByIdempotencyKey = /* @__PURE__ */ new Map();
     /**
      * `transfers` — read-back / confirmation for a prior `transfer()` (issues #27, #47).
      * `get` reconciles once against chain truth; `wait` polls it to a terminal state
@@ -2139,18 +3040,62 @@ var Playmos = class {
       }
     };
   }
-  rememberMock(payment) {
-    if (payment.mock) this.mockPayments.set(payment.id, payment);
+  mockIdemScopeKey(gameId, heldKey) {
+    return `${gameId ?? ""}:${heldKey}`;
+  }
+  rememberMock(payment, held) {
+    if (payment.mock) {
+      this.mockPayments.set(payment.id, payment);
+      if (held) {
+        this.mockByIdempotencyKey.set(this.mockIdemScopeKey(held.terms.gameId, held.key), {
+          payment,
+          terms: held.terms
+        });
+      }
+    }
     return payment;
   }
+  /** Live-shaped conflict when held mock key is reused with different money terms (sdk#513 residual B1). */
+  mockIdemReplayOrThrow(heldKey, terms) {
+    const prior = this.mockByIdempotencyKey.get(this.mockIdemScopeKey(terms.gameId, heldKey));
+    if (!prior) return null;
+    const t = prior.terms;
+    const same = t.kind === terms.kind && t.amount === terms.amount && t.gameId === terms.gameId && t.playerId === terms.playerId && t.roundId === terms.roundId && t.identity === terms.identity && t.sku === terms.sku;
+    if (!same) {
+      throw new ApiError(
+        `idempotencyKey was already used for a payment with DIFFERENT terms (kind/amount/gameId/playerId/roundId/identity/sku); use a fresh key (mock:true mirrors live conflict \u2014 sdk#513).`,
+        {
+          code: "idempotency_conflict",
+          idempotencyKey: heldKey,
+          priorKind: t.kind,
+          priorAmount: t.amount
+        }
+      );
+    }
+    return prior.payment;
+  }
   /** External-studio IAP (1%). Returns a real confirmed Payment with a txHash. */
   async pay(input) {
     const amountMicro = validateAmount(input.amount);
     requireField(input.sku, "sku");
     requireField(input.playerId, "playerId");
     const metadata = validateMetadata(input.metadata);
-    const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
+    const heldIdem = typeof input.idempotencyKey === "string" && input.idempotencyKey.trim() ? input.idempotencyKey.trim() : void 0;
+    const idempotencyKey = heldIdem ?? prefixedId("idem");
     if (this.config.mock) {
+      const terms = {
+        kind: "iap",
+        amount: formatMicroToUsd(amountMicro),
+        gameId: input.gameId ?? "",
+        playerId: input.playerId,
+        roundId: "",
+        identity: "",
+        sku: input.sku.trim()
+      };
+      if (heldIdem) {
+        const replay = this.mockIdemReplayOrThrow(heldIdem, terms);
+        if (replay) return replay;
+      }
       return this.rememberMock(
         mockIapPayment({
           amountMicro,
@@ -2159,7 +3104,8 @@ var Playmos = class {
           playerId: input.playerId,
           chain: this.env.network,
           metadata
-        })
+        }),
+        heldIdem ? { key: heldIdem, terms } : void 0
       );
     }
     if (this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy())) {
@@ -2181,7 +3127,13 @@ var Playmos = class {
       );
       let payment = this.mapServerPayment(res.payment, "iap", amountMicro);
       if (payment.status === "pending" || payment.status === "created") {
-        payment = await this.waitForServerSettle(payment.id, "iap", amountMicro);
+        payment = await this.waitForServerSettle(
+          payment.id,
+          "iap",
+          amountMicro,
+          input.settleTimeoutMs ?? 6e4,
+          input.signal
+        );
       }
       return payment;
     }
@@ -2219,15 +3171,29 @@ var Playmos = class {
     const { txHash } = await waitForCalls(provider, callsId);
     return this.settle(intent.payment.id, txHash);
   }
-  /** Playmos-owned skill-game entry (10%, 60/30/10 prize pool). Closes #343. */
+  /** Skill-game prize-pool entry. Live sandbox / Playmos Lab uses 60/30/10. Studio contest take is 1% (not a live separate pool yet). Closes #343. */
   async enterRound(input) {
     const amountMicro = validateAmount(input.amount);
     requireField(input.gameId, "gameId");
     requireField(input.roundId, "roundId");
     requireField(input.playerId, "playerId");
     const metadata = validateMetadata(input.metadata);
-    const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
+    const heldIdem = typeof input.idempotencyKey === "string" && input.idempotencyKey.trim() ? input.idempotencyKey.trim() : void 0;
+    const idempotencyKey = heldIdem ?? prefixedId("idem");
     if (this.config.mock) {
+      const terms = {
+        kind: "entry",
+        amount: formatMicroToUsd(amountMicro),
+        gameId: input.gameId,
+        playerId: input.playerId,
+        roundId: input.roundId,
+        identity: typeof input.identity === "string" ? input.identity.trim() : "",
+        sku: ""
+      };
+      if (heldIdem) {
+        const replay = this.mockIdemReplayOrThrow(heldIdem, terms);
+        if (replay) return replay;
+      }
       this.mockAccumulateEntry(input.roundId, amountMicro);
       return this.rememberMock(
         mockEntryPayment({
@@ -2243,7 +3209,8 @@ var Playmos = class {
           // B2 pins — must survive mock path for hub hasEntered parity (#204).
           roundKey: input.roundKey,
           identity: input.identity
-        })
+        }),
+        heldIdem ? { key: heldIdem, terms } : void 0
       );
     }
     const serverSettleNoWallet = this.env.isTest && !await walletAvailable(this.config.wallet, this.walletTimeoutPolicy());
@@ -2276,7 +3243,13 @@ var Playmos = class {
       );
       let payment2 = this.mapServerPayment(res.payment, "entry", amountMicro);
       if (payment2.status === "pending" || payment2.status === "created") {
-        payment2 = await this.waitForServerSettle(payment2.id, "entry", amountMicro);
+        payment2 = await this.waitForServerSettle(
+          payment2.id,
+          "entry",
+          amountMicro,
+          input.settleTimeoutMs ?? 6e4,
+          input.signal
+        );
       }
       if (input.identity) payment2.identity = input.identity;
       const pool = res.clientParams?.contractAddress ?? this.config.contracts?.prizePool;
@@ -2459,10 +3432,16 @@ var Playmos = class {
    *   until chain verify catches PaymentSettled (RPC lag) — poll so pay() matches
    *   the documented "confirmed" sandbox promise (TTFSC-T0 / cold-run).
    */
-  async waitForServerSettle(paymentId, kind, amountMicro, timeoutMs = 6e4) {
+  async waitForServerSettle(paymentId, kind, amountMicro, timeoutMs = 6e4, signal) {
     const start = Date.now();
     let delayMs = 400;
     while (Date.now() - start < timeoutMs) {
+      if (signal?.aborted) {
+        throw new ApiError(
+          `Aborted waiting for server-settle of ${paymentId}. Re-check with playmos.verify("${paymentId}").`,
+          { paymentId, aborted: true, asyncSettle: true }
+        );
+      }
       const raw = await this.http.get(
         `/payments/${encodeURIComponent(paymentId)}`
       );
@@ -2477,12 +3456,46 @@ var Playmos = class {
       { paymentId, timeout: true, asyncSettle: true }
     );
   }
+  /**
+   * sdk#509 — recover a payment after a lost response by the idempotency key you held.
+   * Requires secret sk_test_ (same as list). Returns null if not found.
+   */
+  async findPaymentByIdempotencyKey(idempotencyKey, opts) {
+    requireField(idempotencyKey, "idempotencyKey");
+    if (this.config.mock) {
+      return null;
+    }
+    const q = new URLSearchParams({ idempotencyKey });
+    if (opts?.gameId) q.set("gameId", opts.gameId);
+    try {
+      const res = await this.http.get(
+        `/payments?${q.toString()}`
+      );
+      const row = res.data?.[0];
+      if (!row || typeof row.id !== "string") return null;
+      const kind = row.kind === "entry" ? "entry" : "iap";
+      const amountMicro = validateAmount(String(row.amount ?? "0.01"));
+      return this.mapServerPayment(
+        row,
+        kind,
+        amountMicro
+      );
+    } catch (e) {
+      if (e instanceof ApiError && (e.detail?.status === 404 || e.detail?.code === "not_found" || /not found/i.test(e.message))) {
+        return null;
+      }
+      throw e;
+    }
+  }
   /**
    * Map a server-settled payment (from the `settle: "server"` response) into the
    * SDK's `Payment` shape. The service already signed + confirmed on-chain, so we
-   * pass its authoritative `status`/`txHash`/amounts straight through and, for an
-   * entry, derive the 60/30/10 USD `split` locally (exactly as the mock + the
-   * contract compute it) from the parsed amount.
+   * pass its authoritative `status`/`txHash`/amounts straight through.
+   *
+   * For entry, `Payment.split` is a **first-party 60/30/10 projection** from the
+   * request amount using SDK BPS constants (same integer math as mock) — not a
+   * chain read of pool constructor bps or post-lock payable pot (sdk#514 residual N1).
+   * Prefer `chainAmount` / on-chain `getRound` for money truth.
    */
   mapServerPayment(p, kind, amountMicro) {
     const payment = {
@@ -2650,13 +3663,13 @@ function previewPoolSplit(amount) {
 }
 
 // src/settlement.ts
-var ADDRESS_RE4 = /^0x[0-9a-fA-F]{40}$/;
+var ADDRESS_RE5 = /^0x[0-9a-fA-F]{40}$/;
 var DEFAULT_TTL_MS = 15 * 60 * 1e3;
 function requireAddress3(value, field) {
   if (typeof value !== "string" || value.trim() === "") {
     throw new MissingFieldError(field);
   }
-  if (!ADDRESS_RE4.test(value)) {
+  if (!ADDRESS_RE5.test(value)) {
     throw new ConfigError(`${field} must be a 0x-prefixed 20-byte address, got: ${JSON.stringify(value)}`, {
       field,
       value
@@ -2742,4 +3755,4 @@ function isX402PayloadAuthorization(auth) {
   return auth.kind === "x402-payload";
 }
 
-export { CHAIN_ID, DEFAULT_API_BASE_URL, MICRO_PER_USDC, PayoutError, Playmos, USDC_ADDRESS, USDC_DECIMALS, clientRuntimeSignals, computeIapSplit, computePayout, computePoolSplit, createPaymentRequirement, createX402Challenge, decodePaymentHeader, encodePaymentHeader, formatMicroToUsd, isClientRuntime, isWalletSignatureAuthorization, isX402PayloadAuthorization, networkToCaip2, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, resolveEnv, serializePaymentRequirement, toX402PaymentRequired, ulid, validateX402ChallengeInput };
+export { C1_ENTER_SPLIT_MICRO, CHAIN_ID, DEFAULT_API_BASE_URL, MICRO_PER_USDC, PLAYMOS_FEE_SINK_DEFAULT, PayoutError, Playmos, 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 };