@playmos/sdk 0.3.11 → 0.3.13

package/dist/index.js

@@ -1,6 +1,6 @@
-import { AuthError, InvalidAmountError, ConfigError, MissingFieldError, NothingToWithdrawError, assertEnoughGas, buildWithdrawCall, sendCalls, waitForCalls, WalletTimeoutError, PaymentFailedError, ApiError, buildIapCalls, buildEntryCalls, prizePoolAbi, WalletConnectionError, AlreadyEnteredError } from './chunk-35WJANW4.js';
-export { AlreadyEnteredError, ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError, WalletTimeoutError } from './chunk-35WJANW4.js';
-import { encodeFunctionData, decodeFunctionResult } 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-TZFGZNXV.js';
+export { AlreadyEnteredError, ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, NothingToWithdrawError, PaymentFailedError, PlaymosError, WalletConnectionError, WalletTimeoutError, buildEpochExecuteSettlementCall, identityToBytes32, seriesToBytes32 } from './chunk-TZFGZNXV.js';
+import { encodeFunctionData, encodeAbiParameters, decodeFunctionResult } from 'viem';
 
 // src/config.ts
 var CHAIN_ID = {
@@ -581,6 +581,37 @@ async function getAccount(provider) {
     });
   }
 }
+function buildEpochEntryCalls(args) {
+  const enterData = encodeFunctionData({
+    abi: epochPrizePoolEnterAbi,
+    functionName: "enter",
+    args: [seriesToBytes32(args.series), identityToBytes32(args.identity)]
+  });
+  return [
+    { to: args.usdc, data: encodeApprove(args.epochPrizePool, args.entryMicro) },
+    { to: args.epochPrizePool, data: enterData }
+  ];
+}
+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
 var MOCK_TX = `0x${"0".repeat(56)}deadbeef`;
@@ -642,13 +673,902 @@ function mockVerifyResult(payment) {
   return { ...payment, mock: true };
 }
 
-// src/x402.ts
+// src/epochs.ts
+var PLAYMOS_FEE_SINK_DEFAULT = "0xd84c190085aa59c48a9b478ea333d50b8df4ad42";
+var RETIRED_PLAYMOS_FEE_SINK = "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 locked = PLAYMOS_FEE_SINK_DEFAULT;
+  if (playmosFeeSink && !sameAddr(playmosFeeSink, locked)) {
+    throw new ConfigError("feeSink must equal the Playmos Sepolia treasury; refused before broadcast");
+  }
+  const sink = locked;
+  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 Sepolia treasury; 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
+    }),
+    broadcast: false,
+    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 = PLAYMOS_FEE_SINK_DEFAULT;
+      const token = (input.token ?? cfg.contracts?.usdc ?? "0x036cbd53842c5426634e7929541ec2318f3dcf7e").toLowerCase();
+      if (input.playmosFeeSink && !sameAddr(input.playmosFeeSink, sink)) {
+        throw new ConfigError("feeSink must equal the Playmos Sepolia treasury; refused before broadcast");
+      }
+      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
@@ -786,7 +1706,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;
@@ -834,7 +1754,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 }
@@ -873,6 +1793,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) => {
@@ -1038,6 +2008,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");
@@ -1203,6 +2175,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()}`;
@@ -1444,6 +2426,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
@@ -1500,7 +2569,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)"
             );
@@ -2111,7 +3180,7 @@ 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");
@@ -2603,13 +3672,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
@@ -2695,4 +3764,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, 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 };