@playmos/sdk 0.3.10 → 0.3.12

package/dist/index.d.cts

@@ -1,5 +1,625 @@
-import { N as Network, P as PlaymosConfig, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, c as RoundCancelInput, C as CancelRoundResult, d as RoundGetResult, A as ActiveSeriesRound, e as PrizeBalance, f as WithdrawResult, g as AgentWallet, h as AgentFundResult, T as TransferResult, E as EscrowHoldInput, i as EscrowHoldResult, j as EscrowResolveResult, M as MarketplaceListInput, L as Listing, k as MarketplaceSaleResult, l as MarketplaceGetResult, m as PayInput, n as Payment, o as EnterRoundInput, p as TransferReconcile, q as WaitOptions, r as TransferInput, s as TransferConfirmOptions, V as VerifyResult, t as PayoutRule } from './errors-Chizbb96.cjs';
-export { u as ActiveForSeriesResult, v as AgentEconomyConfig, w as AlreadyEnteredError, x as ApiError, y as AuthError, z as ConfigError, B as ContractConfig, D as Eip1193Provider, G as GasConfig, F as GasMode, I as InsufficientGasError, H as InvalidAmountError, J as ListingStatus, K as MarketplaceItem, O as MarketplaceSale, Q as MissingFieldError, U as NothingToWithdrawError, X as PaymentFailedError, Y as PaymentStatus, Z as PlaymosError, _ as PlaymosErrorCode, $ as RetryOptions, a0 as RoundGetVia, a1 as RoundStatus, a2 as WalletConfig, a3 as WalletConnectionError, a4 as WalletConnector, a5 as WalletTimeoutError, a6 as WebhookEventType } from './errors-Chizbb96.cjs';
+import { C as Call, P as PlaymosConfig, O as OnchainStatus, N as Network, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, c as RoundCancelInput, d as CancelRoundResult, e as RoundGetResult, A as ActiveSeriesRound, f as PayoutNoticesResult, g as PrizeBalance, h as WithdrawResult, i as AgentWallet, j as AgentFundResult, T as TransferResult, E as EscrowHoldInput, k as EscrowHoldResult, l as EscrowResolveResult, M as MarketplaceListInput, L as Listing, m as MarketplaceSaleResult, n as MarketplaceGetResult, o as PayInput, p as Payment, q as EnterRoundInput, r as TransferReconcile, s as WaitOptions, t as TransferInput, u as TransferConfirmOptions, V as VerifyResult, v as PayoutRule } from './errors-CYKgt2VU.cjs';
+export { w as ActiveForSeriesResult, x as AgentEconomyConfig, y as AlreadyEnteredError, z as ApiError, B as AuthError, D as ConfigError, F as ContractConfig, G as Eip1193Provider, H as GasConfig, I as GasMode, J as InsufficientGasError, K as InvalidAmountError, Q as ListingStatus, U as MarketplaceItem, X as MarketplaceSale, Y as MissingFieldError, Z as NothingToWithdrawError, _ as PaymentFailedError, $ as PaymentStatus, a0 as PayoutNotice, a1 as PayoutNoticeStatus, a2 as PlaymosError, a3 as PlaymosErrorCode, a4 as RetryOptions, a5 as RoundGetVia, a6 as RoundStatus, a7 as WalletConfig, a8 as WalletConnectionError, a9 as WalletConnector, aa as WalletTimeoutError, ab as WebhookEventType, ac as buildEpochExecuteSettlementCall } from './errors-CYKgt2VU.cjs';
+
+/**
+ * Thin REST client for the Playmos service. Every SDK method that touches the
+ * backend (create intent, verify, payouts, agents) goes through here. `verify()`
+ * hits `GET /payments/:id`, which the service resolves by READING THE CHAIN — so
+ * the SDK never trusts a client claim or a mutable counter (#337 root fix).
+ *
+ * Automatic backoff/retry (#50 + BB-GATEB-002):
+ * - HTTP **429** (rate limit): always retried with exponential backoff + jitter
+ *   (honors `Retry-After` when present).
+ * - HTTP **502 / 503 / 504** (gateway / DO via_upstream HTML): GET always retried;
+ *   POST only when an `idempotency-key` is present so a retried write never
+ *   double-broadcasts. Opt out: `retry: false` or `retry: { maxRetries: 0 }`.
+ */
+
+/** Options for {@link HttpClient.post}. */
+interface HttpPostOptions {
+    idempotencyKey?: string;
+    /**
+     * HTTP statuses to treat as success in addition to 2xx.
+     * Used by x402 challenge mint, which correctly returns **402 Payment Required**.
+     */
+    acceptStatuses?: number[];
+}
+interface HttpClient {
+    post<T>(path: string, body: unknown, opts?: HttpPostOptions): Promise<T>;
+    get<T>(path: string): Promise<T>;
+}
+
+/**
+ * Series string → bytes32. Shared by SDK S1 reads and the service reader.
+ *
+ * Pass-through when already `0x`+64 hex; otherwise keccak of UTF-8
+ * (`keccak256(toHex(s))` == `ethers.id` / C1). Do not use `toBytes(s)` —
+ * viem hex-decodes address-shaped strings and drifts from the chain.
+ */
+declare function seriesToBytes32(series: string): `0x${string}`;
+/**
+ * Identity string → bytes32 (sdk#633). Deliberately the SAME function object as
+ * {@link seriesToBytes32}, not a copy: an identity that hashes differently from
+ * the chain records a paid entry against an id nobody scores. A second
+ * implementation could drift; an alias cannot.
+ */
+declare const identityToBytes32: typeof seriesToBytes32;
+
+/**
+ * Epoch entry calls (sdk#635 / S2).
+ *
+ * Deliberately NOT in `calls.ts`: that file's `toBytes32` is
+ * `keccak256(toBytes(s))`, which viem hex-decodes for hex-shaped input and
+ * therefore disagrees with the chain (sdk#633). It stays as-is because the
+ * legacy PrizePool's live paid entries were written with it. The epoch path
+ * uses the shared `seriesToBytes32` / `identityToBytes32` instead.
+ */
+
+interface EpochEntryCallsArgs {
+    usdc: `0x${string}`;
+    epochPrizePool: `0x${string}`;
+    /** Plain series string, or an already-derived 0x+64 bytes32. */
+    series: string;
+    /** Plain identity string, or an already-derived 0x+64 bytes32. */
+    identity: string;
+    /** The series' `entry` price in micro-USDC, read from the chain. */
+    entryMicro: bigint;
+}
+/** approve USDC → EpochPrizePool, then EpochPrizePool.enter(). One atomic batch. */
+declare function buildEpochEntryCalls(args: EpochEntryCallsArgs): Call[];
+interface EpochClaimRefundCallArgs {
+    epochPrizePool: `0x${string}`;
+    series: string;
+    epochId: bigint;
+    /** The address that paid — credit always lands here, never on the caller. */
+    payer: `0x${string}`;
+}
+/** EpochPrizePool.claimRefund(series, epochId, payer). Permissionless; credit → payer. */
+declare function buildEpochClaimRefundCall(args: EpochClaimRefundCallArgs): Call;
+/** EpochPrizePool.withdraw() — payer wallet pulls USDC. Not PrizePool.withdraw. */
+declare function buildEpochWithdrawCall(epochPrizePool: `0x${string}`): Call;
+
+/**
+ * Rolling-epoch reads (sdk#629 / S1), `enter` (sdk#635 / S2), D14 studio
+ * pool create (sdk#643), operator settle (sdk#639 / S3), and the C3 refund
+ * pull (sdk#634): `claimableRefund` / `claimRefund` / `withdraw`.
+ *
+ * `epochs.currentId` and `epochs.prize` — chain-backed via the service.
+ * `epochs.enter` — pay into whatever window the clock says is current; no open
+ * gate. `epochs.preparePool` / `registerPool` / `createPool` — studio wallet
+ * deploys the existing EpochPrizePool constructor; Playmos is feeSink only.
+ * `epochs.settle` — secret key, operator wallet, broadcast + 202. Passes the
+ * roster through; does not build a hub roster (R7b).
+ * `epochs.claimableRefund` / `claimRefund` / `withdraw` — wallet-direct on
+ * EpochPrizePool. No service hop. `withdraw` reports the credited balance it
+ * read before pulling, or no figure at all — never a placeholder zero beside a
+ * confirmed pull. Live `rounds.withdraw` stays on PrizePool.
+ * `epochs.getAttestation` / `executeSettlement` / `settlementTypedData` — E1b
+ * public board + permissionless relay of an operator-signed podium. The SDK
+ * never authors winners. `settled` is only reported from a chain read of
+ * `terminal`. Live `rounds.*` / `enterRound` are a different pool and stay unchanged.
+ */
+
+/** Playmos Base Sepolia feeSink (PlaymosPay / PrizePool). Service pins this. */
+declare const PLAYMOS_FEE_SINK_DEFAULT: "0x1b8031e20ed96131a849a52290b4d640f286998d";
+declare function encodeEpochPoolConstructorArgs(args: {
+    token: `0x${string}`;
+    admin: `0x${string}`;
+    operator: `0x${string}`;
+    feeSink: `0x${string}`;
+    refundTimeout: bigint;
+}): `0x${string}`;
+
+type EpochTerminal = "none" | "settled" | "refunded" | "rolled";
+type EpochReadVia = "service" | "mock" | "chain";
+interface EpochCurrentId {
+    series: string;
+    epochId: string;
+    via: EpochReadVia;
+    epochPrizePool?: `0x${string}` | null;
+    mock?: true;
+}
+interface EpochPrize {
+    series: string;
+    epochId: string;
+    /** This epoch's 60% bucket (USD). */
+    pool: string;
+    /** Inherited seed already sitting on this epoch (USD). */
+    incomingSeed: string;
+    /** This epoch's 30% — released only at settle (USD). */
+    outgoingSeed: string;
+    /** Settle payable = incomingSeed + pool (USD). */
+    payable: string;
+    poolMicro: string;
+    incomingSeedMicro: string;
+    outgoingSeedMicro: string;
+    payableMicro: string;
+    via: EpochReadVia;
+    epochPrizePool?: `0x${string}` | null;
+    mock?: true;
+}
+interface EpochView {
+    series: string;
+    epochId: string;
+    pool: string;
+    outgoingSeed: string;
+    incomingSeed: string;
+    payable: string;
+    poolMicro: string;
+    outgoingSeedMicro: string;
+    incomingSeedMicro: string;
+    payableMicro: string;
+    entryCount: string;
+    terminal: EpochTerminal;
+    via: EpochReadVia;
+    epochPrizePool?: `0x${string}` | null;
+    mock?: true;
+}
+interface EpochSeriesView {
+    series: string;
+    created: boolean;
+    genesis: string;
+    epochDuration: string;
+    entry: string;
+    feeBps: number;
+    poolBps: number;
+    seedBps: number;
+    via: EpochReadVia;
+    epochPrizePool?: `0x${string}` | null;
+    mock?: true;
+}
+interface EpochCurrentIdInput {
+    series: string;
+    epochPrizePool?: `0x${string}`;
+    /** Mock only — series genesis (unix seconds). */
+    genesis?: number | string;
+    /** Mock only — epoch duration (seconds). */
+    epochDuration?: number | string;
+    /** Mock only — clock to derive against (unix seconds). */
+    at?: number | string;
+}
+interface EpochPrizeInput {
+    series: string;
+    /** Omit to read the live epoch (`/epochs/current/prize`). */
+    epochId?: number | string;
+    epochPrizePool?: `0x${string}`;
+}
+interface EpochGetInput {
+    series: string;
+    epochId?: number | string;
+    epochPrizePool?: `0x${string}`;
+}
+interface EpochGetSeriesInput {
+    series: string;
+    epochPrizePool?: `0x${string}`;
+}
+/** Real status union — never a `"mocked"` status (P0 invariant #2). */
+type EpochEntryStatus = "created" | "pending" | "confirmed" | "failed";
+interface EpochEnterInput {
+    series: string;
+    /**
+     * The on-chain id this paid attempt is scored under. Required — never
+     * invented for you, because an invented identity means the player pays and
+     * their score is looked up somewhere else (#374 / #466).
+     */
+    identity: string;
+    epochPrizePool?: `0x${string}`;
+    /** Mock only — series genesis (unix seconds). */
+    genesis?: number | string;
+    /** Mock only — epoch duration (seconds). */
+    epochDuration?: number | string;
+    /** Mock only — clock to derive the window against (unix seconds). */
+    at?: number | string;
+}
+interface EpochEntry {
+    series: string;
+    identity: string;
+    /** The window this entry belongs to. */
+    epochId: string;
+    /**
+     * Where `epochId` came from. `chain-event` is the window the chain actually
+     * recorded (read back from the `Entered` log). `chain-clock` is the window
+     * that was current when the call was built — correct unless the tx mines on
+     * the far side of a boundary, which is why a confirmed entry always reports
+     * `chain-event`.
+     */
+    epochIdSource: "chain-event" | "chain-clock" | "mock";
+    seriesBytes32: `0x${string}`;
+    identityBytes32: `0x${string}`;
+    /** Entry price (USD) — the series' immutable `entry`, read from chain. */
+    entry: string;
+    entryMicro: string;
+    status: EpochEntryStatus;
+    txHash?: `0x${string}`;
+    /**
+     * How many paid entries this identity now has in this window (D9). A second
+     * entry reads `2` — re-entry is the product, not an error.
+     */
+    identityEntryCount?: string;
+    epochPrizePool?: `0x${string}` | null;
+    usdc?: `0x${string}` | null;
+    via: EpochReadVia;
+    mock?: true;
+}
+interface EpochPreparePoolInput {
+    studioWallet: `0x${string}`;
+    /** Must equal the Playmos sink if set; any other address is refused before broadcast. */
+    feeSink?: `0x${string}`;
+    admin?: `0x${string}`;
+    operator?: `0x${string}`;
+    refundTimeout?: number | string;
+    playmosFeeSink?: `0x${string}`;
+    token?: `0x${string}`;
+}
+interface EpochPreparedPool {
+    token: `0x${string}`;
+    admin: `0x${string}`;
+    operator: `0x${string}`;
+    feeSink: `0x${string}`;
+    refundTimeout: string;
+    constructorArgs: `0x${string}`;
+    constructor: "EpochPrizePool";
+    studioHoldsAdmin: true;
+    studioHoldsOperator: true;
+    playmosIsAdmin: false;
+    playmosIsOperator: false;
+    via: EpochReadVia;
+    mock?: true;
+}
+/**
+ * The studio wallet's EIP-191 signature over `EpochStudioPool.proof.message`.
+ * Without it the pool is verified on chain but ownership is left unrecorded —
+ * a wallet you do not hold the key to can never be registered as yours.
+ */
+interface EpochPoolWalletProof {
+    signature: `0x${string}`;
+}
+interface EpochRegisterPoolInput {
+    studioWallet: `0x${string}`;
+    poolAddress: `0x${string}`;
+    feeSink?: `0x${string}`;
+    admin?: `0x${string}`;
+    operator?: `0x${string}`;
+    txHash?: string;
+    walletProof?: EpochPoolWalletProof;
+}
+/** `pending` = chain-verified, owner NOT recorded (no wallet proof supplied). */
+type EpochPoolOwnership = "pending" | "confirmed";
+interface EpochStudioPool {
+    poolAddress: `0x${string}`;
+    studioId?: string | null;
+    studioWallet: `0x${string}`;
+    feeSink: `0x${string}`;
+    admin: `0x${string}`;
+    operator: `0x${string}`;
+    studioHoldsAdmin: true;
+    studioHoldsOperator: true;
+    playmosIsAdmin: false;
+    playmosIsOperator: false;
+    ownership?: EpochPoolOwnership;
+    owner?: string | null;
+    /** Present while `ownership` is `pending` — sign `message` and re-register. */
+    proof?: {
+        scheme: "eip191-personal-sign";
+        wallet: `0x${string}`;
+        message: string;
+    };
+    via: EpochReadVia;
+    mock?: true;
+}
+interface EpochCreatePoolInput extends EpochPreparePoolInput {
+    /** After the studio wallet submitted the constructor; omitted in mock. */
+    poolAddress?: `0x${string}`;
+    txHash?: string;
+    walletProof?: EpochPoolWalletProof;
+}
+type EpochWinnerIn = `0x${string}` | {
+    wallet: `0x${string}`;
+    amount?: string;
+    amountMicro?: string;
+};
+interface EpochSettleInput {
+    series: string;
+    epochId: number | string;
+    /** Empty array is a legal D11 roll. */
+    winners: EpochWinnerIn[];
+    epochPrizePool?: `0x${string}`;
+}
+type EpochSettleStatus = "settling" | "settled" | "rolled" | "refunded";
+interface EpochSettleWinner {
+    wallet: `0x${string}`;
+    /**
+     * USD decimal. Present only when the seat's share is known — a wallet-only
+     * roster carries no amounts, and absent ≠ `"0.00"` (sdk#660).
+     */
+    amount?: string;
+    /** Integer micro-USDC (6dp) for the same figure as {@link amount}. */
+    amountMicro?: string;
+    /** Present only after a chain read-back (never inferred from the podium). */
+    withdrawableMicro?: string;
+}
+interface EpochSettleResult {
+    series: string;
+    epochId: string;
+    status: EpochSettleStatus;
+    txHash: `0x${string}` | null;
+    winners: EpochSettleWinner[];
+    /**
+     * USDC the podium was paid. Present when the SDK knows it (mock: sum of
+     * winner amounts; live: the service figure). ABSENT when unknown — a
+     * wallet-only roster has no amounts to add. Never a placeholder `"0"` /
+     * `"0.00"` standing in for unknown (sdk#660 / same class as #659 withdraw).
+     */
+    payable?: string;
+    payableMicro?: string;
+    terminal?: EpochTerminal;
+    via: EpochReadVia;
+    epochPrizePool?: `0x${string}` | null;
+    mock?: true;
+}
+interface EpochClaimableRefundInput {
+    series: string;
+    epochId: number | string;
+    /** The wallet that paid — the address `claimRefund` will credit. */
+    payer: `0x${string}`;
+    epochPrizePool?: `0x${string}`;
+}
+interface EpochClaimableRefund {
+    series: string;
+    epochId: string;
+    payer: `0x${string}`;
+    claimable: string;
+    claimableMicro: string;
+    seriesBytes32: `0x${string}`;
+    epochPrizePool?: `0x${string}` | null;
+    via: EpochReadVia;
+    mock?: true;
+}
+interface EpochClaimRefundInput {
+    series: string;
+    epochId: number | string;
+    /** Credit always lands here, even if another wallet signs the tx. */
+    payer: `0x${string}`;
+    epochPrizePool?: `0x${string}`;
+}
+/**
+ * No money figure here on purpose. `claimRefund` returns the credited amount
+ * on chain, but a wallet batch hands back a receipt, not that return value —
+ * so the SDK does not know it. The figure stays readable on both sides of this
+ * call (`claimableRefund` before, `withdraw`'s `amountMicro` after), so there
+ * is nothing to guess and nothing to publish as a zero.
+ */
+interface EpochClaimRefundResult {
+    series: string;
+    epochId: string;
+    payer: `0x${string}`;
+    txHash?: `0x${string}`;
+    status: "confirmed" | "pending" | "failed";
+    epochPrizePool?: `0x${string}` | null;
+    via: EpochReadVia;
+    mock?: true;
+}
+interface EpochWithdrawInput {
+    epochPrizePool?: `0x${string}`;
+}
+interface EpochWithdrawResult {
+    epochPrizePool: `0x${string}`;
+    /**
+     * The USDC this pull moves, read from `withdrawable[wallet]` on chain
+     * immediately before the call — `withdraw()` transfers the whole credited
+     * balance, so this is the sum that leaves the pool.
+     *
+     * ABSENT means the SDK could not read that balance (no reader wired, or the
+     * read failed). Absent is not zero: the withdrawal is still broadcast and
+     * `txHash` still describes it. Never render a missing amount as `$0.00` —
+     * a player who pulled $0.90 must never be shown $0.00.
+     */
+    amount?: string;
+    amountMicro?: string;
+    txHash?: `0x${string}`;
+    status: "confirmed" | "pending" | "failed";
+    via: EpochReadVia;
+    mock?: true;
+}
+interface EpochGetAttestationInput {
+    series: string;
+    epochId: number | string;
+    epochPrizePool?: `0x${string}`;
+    /** Mock only — fixture the board would have served. */
+    winners?: `0x${string}`[];
+    /** Mock only — micro-USDC strings. */
+    amountsMicro?: string[];
+    /** Mock only. */
+    signature?: `0x${string}`;
+}
+interface EpochAttestation {
+    series: string;
+    epochId: string;
+    winners: `0x${string}`[];
+    amountsMicro: string[];
+    signature: `0x${string}`;
+    epochPrizePool: `0x${string}`;
+    terminal?: EpochTerminal;
+    dueAt?: string;
+    via: EpochReadVia;
+    mock?: true;
+}
+interface EpochExecuteSettlementInput {
+    series: string;
+    epochId: number | string;
+    winners: `0x${string}`[];
+    /** Integer micro-USDC strings — never USD. */
+    amounts: string[];
+    signature: `0x${string}`;
+    epochPrizePool?: `0x${string}`;
+}
+interface EpochExecuteSettlementResult {
+    series: string;
+    epochId: string;
+    winners: `0x${string}`[];
+    amountsMicro: string[];
+    signature: `0x${string}`;
+    txHash?: `0x${string}`;
+    status: "confirmed" | "pending" | "failed";
+    /**
+     * Only present after a successful chain read of `getEpoch.terminal`.
+     * Absent means the read failed — never inferred from broadcast.
+     */
+    settled?: boolean;
+    terminal?: EpochTerminal;
+    epochPrizePool?: `0x${string}` | null;
+    via: EpochReadVia;
+    mock?: true;
+}
+interface SettlementTypedDataInput {
+    pool: `0x${string}`;
+    chainId: number;
+    series: string;
+    epochId: number | string;
+    winners: `0x${string}`[];
+    amounts: string[];
+}
+interface SettlementTypedData {
+    domain: {
+        name: "EpochPrizePool";
+        version: "1";
+        chainId: number;
+        verifyingContract: `0x${string}`;
+    };
+    types: {
+        Settlement: [
+            {
+                name: "series";
+                type: "bytes32";
+            },
+            {
+                name: "epochId";
+                type: "uint256";
+            },
+            {
+                name: "winners";
+                type: "address[]";
+            },
+            {
+                name: "amounts";
+                type: "uint256[]";
+            }
+        ];
+    };
+    primaryType: "Settlement";
+    message: {
+        series: `0x${string}`;
+        epochId: bigint;
+        winners: `0x${string}`[];
+        amounts: bigint[];
+    };
+}
+interface EpochsApi {
+    currentId(input: EpochCurrentIdInput): Promise<EpochCurrentId>;
+    prize(input: EpochPrizeInput): Promise<EpochPrize>;
+    get(input: EpochGetInput): Promise<EpochView>;
+    getSeries(input: EpochGetSeriesInput): Promise<EpochSeriesView>;
+    preparePool(input: EpochPreparePoolInput): Promise<EpochPreparedPool>;
+    registerPool(input: EpochRegisterPoolInput): Promise<EpochStudioPool>;
+    createPool(input: EpochCreatePoolInput): Promise<EpochStudioPool>;
+    settle(input: EpochSettleInput): Promise<EpochSettleResult>;
+    /**
+     * Read EpochPrizePool.claimableRefund — micro-USDC still sitting in
+     * refundOwed for this payer on a Refunded window (sdk#634).
+     */
+    claimableRefund(input: EpochClaimableRefundInput): Promise<EpochClaimableRefund>;
+    /**
+     * Permissionless: move this payer's refund share into withdrawable[payer].
+     * The credit never lands on the caller.
+     */
+    claimRefund(input: EpochClaimRefundInput): Promise<EpochClaimRefundResult>;
+    /**
+     * Payer wallet pulls USDC from EpochPrizePool.withdrawable[msg.sender].
+     * Not live PrizePool `rounds.withdraw`.
+     */
+    withdraw(input?: EpochWithdrawInput): Promise<EpochWithdrawResult>;
+    /**
+     * Fetch a posted signed podium from the service board. Any authenticated
+     * key — the board is public. Amounts stay micro-USDC strings.
+     */
+    getAttestation(input: EpochGetAttestationInput): Promise<EpochAttestation>;
+    /**
+     * Wallet-direct executeSignedSettlement. Relays the fetched podium
+     * byte-exact. `settled` only from a chain read of `terminal`.
+     */
+    executeSettlement(input: EpochExecuteSettlementInput): Promise<EpochExecuteSettlementResult>;
+    /**
+     * Pay into whatever window is current right now. No open gate (sdk#635).
+     *
+     * Once the wallet batch mines this never rejects: an entry carrying a
+     * `txHash` comes back even if the confirm read fails, because that hash is
+     * the only handle on money that has already moved. Such an entry is
+     * `pending` / `chain-clock` — treat it as paid-but-not-read-back, not as a
+     * failure to retry.
+     */
+    enter(input: EpochEnterInput): Promise<EpochEntry>;
+}
+interface EpochsDeps {
+    http: () => HttpClient;
+    config: () => PlaymosConfig;
+    assertSecretKey?: (surface: string) => void;
+    /**
+     * Send the atomic approve+enter batch from the player's wallet. Supplied by
+     * the client so this module stays wallet-agnostic (and so the browser bundle
+     * keeps its own wallet funnel). Absent → `enter` refuses rather than
+     * pretending (P0 invariant #1).
+     */
+    sendEntry?: (calls: Call[], opts: {
+        paymasterUrl?: string;
+    }) => Promise<{
+        status: OnchainStatus;
+        txHash?: `0x${string}`;
+    }>;
+    /**
+     * Wallet-or-RPC `eth_call`. Used by the refund rail so a player can read
+     * `claimableRefund` without a service route (sdk#634; service is a parallel slice).
+     */
+    readView?: (to: `0x${string}`, data: `0x${string}`) => Promise<`0x${string}`>;
+    /**
+     * The connected wallet address — the account `withdraw()` pulls to. Needed
+     * to read `withdrawable[account]` before the pull, so the result can report
+     * the money that actually moves instead of a placeholder.
+     */
+    walletAddress?: () => Promise<`0x${string}`>;
+}
+/** Derived epochId — same formula as EpochPrizePool._epochIdAt. */
+declare function derivedEpochId(genesis: bigint, epochDuration: bigint, at: bigint): bigint;
+/** Settle payable is inherited seed + this epoch's pool (not outgoingSeed). */
+declare function epochPayableMicro(incomingSeed: bigint, pool: bigint): bigint;
+/** Client-side pin — same refusals as the service, so a bad sink never reaches broadcast. */
+declare function prepareStudioPoolLocal(input: EpochPreparePoolInput, playmosFeeSink: `0x${string}`, token: `0x${string}`, playmosAddresses?: `0x${string}`[]): EpochPreparedPool;
+/**
+ * The exact message the studio wallet signs to claim ownership of a pool.
+ * Byte-identical to the service's `epochPoolProofMessage` — one byte of drift
+ * and a legitimate studio is refused, so keep the two in lockstep.
+ */
+declare function epochPoolProofMessage(terms: {
+    studioId: string;
+    poolAddress: `0x${string}`;
+    studioWallet: `0x${string}`;
+    chainId: number;
+}): string;
+/**
+ * The one EIP-712 derivation E1c and every test must share.
+ * Domain: EpochPrizePool / 1 / chainId / pool.
+ * Type: Settlement(bytes32 series,uint256 epochId,address[] winners,uint256[] amounts).
+ * Amounts are micro-USDC integer strings — never USD. The SDK never signs this.
+ */
+declare function settlementTypedData(input: SettlementTypedDataInput): SettlementTypedData;
+declare function createEpochsApi(deps: EpochsDeps): EpochsApi;
+/** Test helper — known C1 1 USDC enter split (fee 10% then 60/30 of remainder). */
+declare const C1_ENTER_SPLIT_MICRO: {
+    readonly entry: 1000000n;
+    readonly fee: 100000n;
+    readonly pool: 600000n;
+    readonly outgoingSeed: 300000n;
+    readonly incomingSeed: 0n;
+};
 
 /**
  * Environment resolution + the canonical address book.
@@ -373,15 +993,6 @@ declare function validateX402ChallengeInput(input: X402ChallengeInput): {
     id?: string;
 };
 
-/**
- * The Playmos client — `new Playmos({ apiKey })` → `pay()`, `enterRound()`,
- * `verify()`, `webhooks`, `payouts`, `agents`.
- *
- * Real behavior, no `"mocked"` status anywhere. The chain calls use the proven
- * EIP-5792 approve+call batch; `verify()` resolves by the service's on-chain
- * read; ids are ULIDs; inputs are validated client-side; idempotency is honored.
- */
-
 declare class Playmos {
     readonly config: PlaymosConfig;
     readonly env: ResolvedEnv;
@@ -401,6 +1012,16 @@ declare class Playmos {
          */
         verify: (_rawBody: string | Buffer, _signatureHeader: string | string[] | undefined, _secret: string) => WebhookEvent;
     };
+    /**
+     * 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.
+     */
+    readonly epochs: EpochsApi;
     readonly payouts: {
         /** Choose how the studio is paid: "usdc" (default) or "fiat" (Bridge). Secret key only (#264). */
         setMode: (mode: "usdc" | "fiat") => Promise<{
@@ -479,6 +1100,8 @@ declare class Playmos {
     private readonly mockPotMicro;
     /** Persisted settle winners for re-settle replay (#490 C2) — never re-invent pool-to-everyone. */
     private readonly mockSettleWinners;
+    /** L34 notices after mock settle — funded only with a push txHash. */
+    private readonly mockPayoutNotices;
     /**
      * Resolve mock round by roundId **or** roundKey (kit `entryProvider` keys by roundKey, #490 C3).
      */
@@ -542,6 +1165,28 @@ declare class Playmos {
             seriesKey: string;
             gameId: string;
         }) => Promise<ActiveSeriesRound | null>;
+        /**
+         * 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: (input: {
+            roundId: string;
+            wallet?: string;
+        }) => Promise<PayoutNoticesResult>;
+        /**
+         * 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: (input: {
+            roundId: string;
+            /** Per-wallet push result. Missing / failed → claimable. */
+            pushes?: Array<{
+                wallet: string;
+                txHash?: string;
+                failed?: boolean;
+            }>;
+        }) => Promise<PayoutNoticesResult>;
         /**
          * Read a wallet's **claimable** prize balance for a round (issue #41).
          * Prefers the service chain read (`GET /v1/rounds/:id/prize?wallet=`); falls
@@ -655,8 +1300,16 @@ declare class Playmos {
     /**
      * 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.
      */
     private readonly mockPayments;
+    /**
+     * 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).
+     */
+    private readonly mockByIdempotencyKey;
     constructor(config: PlaymosConfig);
     /**
      * Wallet timeout policy (#462 / PR #463 residual).
@@ -695,10 +1348,13 @@ declare class Playmos {
             identity?: string;
         }>;
     };
+    private mockIdemScopeKey;
     private rememberMock;
+    /** Live-shaped conflict when held mock key is reused with different money terms (sdk#513 residual B1). */
+    private mockIdemReplayOrThrow;
     /** External-studio IAP (1%). Returns a real confirmed Payment with a txHash. */
     pay(input: PayInput): Promise<Payment>;
-    /** 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. */
     enterRound(input: EnterRoundInput): Promise<Payment>;
     /**
      * `transfers` — read-back / confirmation for a prior `transfer()` (issues #27, #47).
@@ -759,12 +1415,22 @@ declare class Playmos {
      *   the documented "confirmed" sandbox promise (TTFSC-T0 / cold-run).
      */
     private waitForServerSettle;
+    /**
+     * 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.
+     */
+    findPaymentByIdempotencyKey(idempotencyKey: string, opts?: {
+        gameId?: string;
+    }): Promise<Payment | null>;
     /**
      * 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.
      */
     private mapServerPayment;
     /** Prefer the service's authoritative micro-USDC amount; fall back to the
@@ -838,8 +1504,8 @@ declare function previewPoolSplit(amount: string): {
  */
 
 declare class PayoutError extends Error {
-    code: "payout_invalid";
-    constructor(message: string);
+    code: string;
+    constructor(message: string, code?: string);
 }
 /**
  * Apply the studio's payout rule to a payable pool and ranking (best-first).
@@ -884,9 +1550,10 @@ declare function computeIapSplit(amountMicro: bigint, feeBps: number): {
     netMicro: bigint;
 };
 /**
- * Skill-game prize-pool split (60/30/10 by default). Floor-matches the on-chain
- * `EconomyConfig`. Any 1–2 micro rounding remainder is assigned to the pool so
- * the three parts sum EXACTLY to the entry (invariant asserted below).
+ * First-party skill-game prize-pool split (60/30/10 by default). Floor-matches
+ * the on-chain first-party `EconomyConfig`. Not the studio contest take (1%
+ * Playmos / default 60/30/9 — not live). Any 1–2 micro rounding remainder is
+ * assigned to the pool so the three parts sum EXACTLY to the entry.
  */
 declare function computePoolSplit(amountMicro: bigint, poolBps: number, seedBps: number, rakeBps: number): {
     poolMicro: bigint;
@@ -908,4 +1575,4 @@ declare function ulid(seedTime?: number): string;
 /** `${prefix}_${ulid()}` — e.g. `pay_01J…`, `entry_01J…`, `idem_01J…`. */
 declare function prefixedId(prefix: string): string;
 
-export { ActiveSeriesRound, AgentFundResult, AgentWallet, type Authorization, CHAIN_ID, CancelRoundResult, type CreatePaymentRequirementInput, DEFAULT_API_BASE_URL, EnterRoundInput, EscrowHoldInput, EscrowHoldResult, EscrowResolveResult, Listing, MICRO_PER_USDC, MarketplaceGetResult, MarketplaceListInput, MarketplaceSaleResult, Network, PayInput, Payment, type PaymentRequirement, PayoutError, PayoutRule, PayoutRule as PayoutRuleCompute, Playmos, PlaymosConfig, PrizeBalance, RoundCancelInput, RoundGetResult, RoundOpenInput, RoundSettleInput, RoundState, SettleRoundResult, type SettlementAsset, TransferConfirmOptions, TransferInput, TransferReconcile, TransferResult, USDC_ADDRESS, USDC_DECIMALS, VerifyResult, WaitOptions, type WalletSignatureAuthorization, WebhookEvent, WithdrawResult, type X402ChallengeInput, type X402ChallengeResult, type X402FulfillAuthorization, type X402PayInput, type X402PayloadAuthorization, type X402PayloadMode, type X402PaymentRequired, type X402SettleResult, 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 { ActiveSeriesRound, AgentFundResult, AgentWallet, type Authorization, C1_ENTER_SPLIT_MICRO, CHAIN_ID, CancelRoundResult, type CreatePaymentRequirementInput, DEFAULT_API_BASE_URL, EnterRoundInput, type EpochAttestation, type EpochClaimRefundInput, type EpochClaimRefundResult, type EpochClaimableRefund, type EpochClaimableRefundInput, type EpochCreatePoolInput, type EpochCurrentId, type EpochCurrentIdInput, type EpochEnterInput, type EpochEntry, type EpochEntryStatus, type EpochExecuteSettlementInput, type EpochExecuteSettlementResult, type EpochGetAttestationInput, type EpochGetInput, type EpochGetSeriesInput, type EpochPoolOwnership, type EpochPoolWalletProof, type EpochPreparePoolInput, type EpochPreparedPool, type EpochPrize, type EpochPrizeInput, type EpochReadVia, type EpochRegisterPoolInput, type EpochSeriesView, type EpochSettleInput, type EpochSettleResult, type EpochSettleStatus, type EpochSettleWinner, type EpochStudioPool, type EpochTerminal, type EpochView, type EpochWinnerIn, type EpochWithdrawInput, type EpochWithdrawResult, type EpochsApi, EscrowHoldInput, EscrowHoldResult, EscrowResolveResult, Listing, MICRO_PER_USDC, MarketplaceGetResult, MarketplaceListInput, MarketplaceSaleResult, Network, PLAYMOS_FEE_SINK_DEFAULT, PayInput, Payment, type PaymentRequirement, PayoutError, PayoutNoticesResult, PayoutRule, PayoutRule as PayoutRuleCompute, Playmos, PlaymosConfig, PrizeBalance, RoundCancelInput, RoundGetResult, RoundOpenInput, RoundSettleInput, RoundState, SettleRoundResult, type SettlementAsset, type SettlementTypedData, type SettlementTypedDataInput, TransferConfirmOptions, TransferInput, TransferReconcile, TransferResult, USDC_ADDRESS, USDC_DECIMALS, VerifyResult, WaitOptions, type WalletSignatureAuthorization, WebhookEvent, WithdrawResult, type X402ChallengeInput, type X402ChallengeResult, type X402FulfillAuthorization, type X402PayInput, type X402PayloadAuthorization, type X402PayloadMode, type X402PaymentRequired, type X402SettleResult, buildEpochClaimRefundCall, buildEpochEntryCalls, buildEpochWithdrawCall, clientRuntimeSignals, computeIapSplit, computePayout, computePoolSplit, createEpochsApi, createPaymentRequirement, createX402Challenge, decodePaymentHeader, derivedEpochId, encodeEpochPoolConstructorArgs, encodePaymentHeader, epochPayableMicro, epochPoolProofMessage, formatMicroToUsd, identityToBytes32, isClientRuntime, isWalletSignatureAuthorization, isX402PayloadAuthorization, networkToCaip2, parsePaymentRequirement, parseUsdToMicro, prefixedId, prepareStudioPoolLocal, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, resolveEnv, serializePaymentRequirement, seriesToBytes32, settlementTypedData, toX402PaymentRequired, ulid, validateX402ChallengeInput };