@playmos/sdk 0.1.5 → 0.2.0

package/dist/index.d.ts

@@ -1,178 +1,5 @@
-/**
- * Public types — pruned to WIRED capability only (fixes #344/I and #335/E).
- *
- * The old vendored surface advertised four wallet connectors that silently
- * returned {connected:false} and config fields the code never read. Here the
- * types expose exactly what V1 does: two connectors, the fields `pay()` /
- * `enterRound()` actually use, and no more.
- */
-type Network = "base" | "base-sepolia";
-/** Only the connectors that are actually implemented. */
-type WalletConnector = "base-account" | "injected";
-type GasMode = "sponsored" | "player";
-type PaymentStatus = "created" | "pending" | "confirmed" | "failed";
-/** Minimal EIP-1193 provider shape (what the wallet must expose). */
-interface Eip1193Provider {
-    request(args: {
-        method: string;
-        params?: unknown[] | object;
-    }): Promise<unknown>;
-}
-interface GasConfig {
-    mode?: GasMode;
-    /** CDP paymaster URL — required only for `mode: "sponsored"`. */
-    paymasterUrl?: string;
-}
-interface WalletConfig {
-    connector?: WalletConnector;
-    /**
-     * Pre-built EIP-1193 provider. If omitted, `injected` uses globalThis.ethereum
-     * and `base-account` expects a provider supplied by the Base Account SDK host.
-     */
-    provider?: Eip1193Provider;
-}
-/** Per-game contract addresses. On testnet these come from the service intent,
- *  but a studio may pin them explicitly (matches the dogfood adapter). */
-interface ContractConfig {
-    usdc?: `0x${string}`;
-    playmosPay?: `0x${string}`;
-    prizePool?: `0x${string}`;
-}
-interface AgentEconomyConfig {
-    enabled?: boolean;
-    /** Tax skimmed to Playmos on each agent↔agent transfer. 100 = 1% (default). */
-    taxBps?: number;
-}
-interface PlaymosConfig {
-    /** pk_test_* (sandbox / Base Sepolia) or pk_live_* (production / Base mainnet).
-     *  The key prefix selects the environment. */
-    apiKey: string;
-    /** Override the network derived from the key. Explicit value wins. */
-    network?: Network;
-    wallet?: WalletConfig;
-    gas?: GasConfig;
-    agentEconomy?: AgentEconomyConfig;
-    contracts?: ContractConfig;
-    /** Escape hatch; defaults to the right env's base URL. */
-    apiBaseUrl?: string;
-    /**
-     * Explicit, clearly-labeled offline unit-test helper — instant, deterministic,
-     * NO network, NO chain. Never the default, never conflated with sandbox. Note:
-     * even mock results use the REAL status union (never a synthetic "mocked").
-     */
-    mock?: boolean;
-}
-interface PayInput {
-    /** USD decimal string ("4.99"). Rejected: ≤ 0, non-numeric, > 2 dp. */
-    amount: string;
-    /** Your product id, echoed on the receipt + webhook. */
-    sku: string;
-    /** Your opaque user id. */
-    playerId: string;
-    /**
-     * The game this IAP belongs to. Optional: when your API key maps to exactly
-     * one game the service resolves it for you (the quickstart). Supply it
-     * explicitly when your key spans multiple games.
-     */
-    gameId?: string;
-    /** The studio wallet that receives the 99%. Falls back to the service default. */
-    studio?: `0x${string}`;
-    /** Supply your own to make retries safe; omit and the SDK generates a ULID. */
-    idempotencyKey?: string;
-    metadata?: Record<string, string>;
-}
-interface EnterRoundInput {
-    /** The game — selects its prize-pool contract. */
-    gameId: string;
-    /** The round being entered. */
-    roundId: string;
-    /** USD entry — grows this round's pool. */
-    amount: string;
-    playerId: string;
-    idempotencyKey?: string;
-    metadata?: Record<string, string>;
-    /**
-     * Advanced (games that manage their own on-chain rounds, e.g. the Playmos
-     * game-hub kit): the EXACT on-chain round key to enter — overrides the default
-     * `${gameId}:${roundId}` derivation. Set it to the value your game's server
-     * verifies `hasEntered` against (e.g. "bjtest:T1").
-     */
-    roundKey?: string;
-    /**
-     * Advanced: the EXACT on-chain identity for this paid attempt (e.g.
-     * "0xWallet#nonce"). Overrides the server-generated identity so the on-chain
-     * entry and your server's `hasEntered` check line up. One entry per identity.
-     */
-    identity?: string;
-}
-interface Payment {
-    /** `pay_…` (IAP) or `entry_…` (prize-pool) — ULID, server-issued, unique. */
-    id: string;
-    status: PaymentStatus;
-    /** "iap" (1% external) or "entry" (60/30/10 prize-pool). */
-    kind: "iap" | "entry";
-    amount: string;
-    fee: string;
-    net: string;
-    /** Present for prize-pool entries: the 60/30/10 breakdown in USD. */
-    split?: {
-        pool: string;
-        seed: string;
-        rake: string;
-    };
-    sku?: string;
-    roundId?: string;
-    gameId?: string;
-    playerId: string;
-    txHash?: `0x${string}`;
-    chain: Network;
-    createdAt: string;
-    metadata?: Record<string, string>;
-    /**
-     * The on-chain identity used for a prize-pool entry (echo of
-     * `EnterRoundInput.identity` or the SDK-derived value) — reconcile against your
-     * server's `hasEntered`.
-     */
-    identity?: string;
-    /** True only when produced by the labeled `mock: true` helper. */
-    mock?: boolean;
-}
-/** What `verify()` resolves to (server reads the chain). */
-interface VerifyResult {
-    id: string;
-    status: PaymentStatus;
-    amount: string;
-    fee: string;
-    net: string;
-    txHash?: `0x${string}`;
-    playerId: string;
-    sku?: string;
-    roundId?: string;
-    chain: Network;
-    /** How the service derived this status: an on-chain read, the honest cache, or
-     *  degraded (chain reads not configured). Lets the SDK stop polling when the
-     *  service can never confirm on-chain. */
-    verifiedVia?: "chain" | "cache" | "degraded";
-    chainReads?: "enabled" | "degraded";
-}
-type WebhookEventType = "payment.confirmed" | "payment.failed" | "payout.settled" | "refund.processed";
-interface WebhookEvent {
-    id: string;
-    type: WebhookEventType;
-    createdAt: string;
-    data: {
-        id: string;
-        status: PaymentStatus;
-        amount: string;
-        fee: string;
-        net: string;
-        playerId: string;
-        sku?: string;
-        txHash?: `0x${string}`;
-        chain: Network;
-        metadata?: Record<string, string>;
-    };
-}
+import { N as Network, P as PlaymosConfig, W as WebhookEvent, R as RoundOpenInput, a as RoundState, b as RoundSettleInput, S as SettleRoundResult, A as AgentWallet, c as AgentFundResult, T as TransferResult, E as EscrowHoldInput, d as EscrowHoldResult, e as EscrowResolveResult, M as MarketplaceListInput, L as Listing, f as MarketplaceSaleResult, g as MarketplaceGetResult, h as PayInput, i as Payment, j as EnterRoundInput, k as TransferInput, V as VerifyResult } from './errors-CjL85YKR.js';
+export { l as AgentEconomyConfig, m as ApiError, n as AuthError, C as ConfigError, o as ContractConfig, p as Eip1193Provider, G as GasConfig, q as GasMode, I as InsufficientGasError, r as InvalidAmountError, s as ListingStatus, t as MarketplaceItem, u as MarketplaceSale, v as MissingFieldError, w as PaymentFailedError, x as PaymentStatus, y as PayoutRule, z as PlaymosError, B as PlaymosErrorCode, D as RoundStatus, F as WalletConfig, H as WalletConnectionError, J as WalletConnector, K as WebhookEventType } from './errors-CjL85YKR.js';
 
 /**
  * Environment resolution + the canonical address book.
@@ -209,9 +36,20 @@ declare class Playmos {
     readonly config: PlaymosConfig;
     readonly env: ResolvedEnv;
     private readonly http;
+    /**
+     * Webhook helpers. Signature verification is **server-only** (Node `crypto`) and
+     * lives on `@playmos/sdk/server` so browser bundlers never see `node:crypto` (#9).
+     *
+     *   import { verifyWebhook } from "@playmos/sdk/server";
+     *   const event = verifyWebhook(rawBody, req.headers["x-playmos-signature"], secret);
+     */
     readonly webhooks: {
-        /** Verify a webhook signature and return the parsed event (server-side). */
-        verify: (rawBody: string | Buffer, signatureHeader: string | string[] | undefined, secret: string) => WebhookEvent;
+        /**
+         * @deprecated Use `import { verifyWebhook } from "@playmos/sdk/server"` instead.
+         * Throws if called — kept as a discoverable pointer so call sites fail loudly
+         * with a fix instruction rather than a silent missing method.
+         */
+        verify: (_rawBody: string | Buffer, _signatureHeader: string | string[] | undefined, _secret: string) => WebhookEvent;
     };
     readonly payouts: {
         /** Choose how the studio is paid: "usdc" (default) or "fiat" (Bridge). */
@@ -223,25 +61,104 @@ declare class Playmos {
             url: string;
         }>;
     };
+    /**
+     * Skill/contest **round lifecycle** (issue #13) — closes the enterRound loop.
+     *
+     * Scores never leave the studio. Flow:
+     *   rounds.open → players enterRound → studio scores → rounds.lock →
+     *   rounds.settle({ ranking }) → contract pays winners.
+     *
+     * Operator txs are signed by the Playmos service (OPERATOR_ROLE key).
+     */
+    readonly rounds: {
+        open: (input: RoundOpenInput) => Promise<RoundState>;
+        lock: (input: {
+            roundId: string;
+            gameId?: string;
+        }) => Promise<RoundState>;
+        settle: (input: RoundSettleInput) => Promise<SettleRoundResult>;
+        get: (input: {
+            roundId: string;
+        }) => Promise<RoundState>;
+    };
+    /**
+     * `agents` — assign wallets to the NPCs YOUR game already owns, so they can transact USDC in your economy.
+     * The game creates the NPCs; the SDK only creates the WALLET for a game-supplied id. Engine-agnostic
+     * (Unity/Unreal/Godot/web all call the same REST). Requires a secret test key (`sk_test_`) on the sandbox.
+     */
     readonly agents: {
-        /** Assign a wallet to any identity (incl. an AI NPC). Idempotent by agentId. */
+        /** Assign (or return) the wallet for a game NPC id. Idempotent — safe to call wherever your NPCs spawn. */
         createWallet: (input: {
             agentId: string;
-        }) => Promise<{
+        }) => Promise<AgentWallet>;
+        /** Resolve one NPC's wallet by your id. */
+        wallet: (agentId: string) => Promise<AgentWallet>;
+        /** List the NPC wallets you've assigned in this studio. */
+        list: () => Promise<AgentWallet[]>;
+        /** Sandbox faucet: fund an NPC with USDC from your treasury (per-NPC lifetime cap). */
+        fund: (input: {
             agentId: string;
-            address: `0x${string}`;
-            chain: string;
-        }>;
-        /** Agent↔agent USDC transfer; the configured taxBps is skimmed to Playmos. */
+            amount: string;
+        }) => Promise<AgentFundResult>;
+        /** NPC→NPC (or →player) USDC transfer, by id. A thin alias of `playmos.transfer` (which is canonical). */
         pay: (input: {
             from: string;
             to: string;
             amount: string;
-        }) => Promise<{
-            id: string;
-            taxUSD: string;
-            status: string;
-        }>;
+            feeBps?: number;
+            feeSink?: `0x${string}`;
+        }) => Promise<TransferResult>;
+    };
+    /**
+     * `escrow` — the fair-exchange primitive (Phase 2): lock the payer's USDC on-chain the instant a deal
+     * opens (`hold`), then move it exactly once — `release` (→ payee, fee skimmed) XOR `refund` (→ payer,
+     * 100%). The contract holds the funds trustlessly; YOUR game decides the rule (who resolves, and when).
+     * A `deadline` auto-refund guarantees funds never get stuck. Pass the `hold` result's `id` to the rest.
+     */
+    readonly escrow: {
+        /** Open a deal: lock `amount` of the payer's USDC into the on-chain escrow. Retries are idempotent.
+         *  `async` so client-side validation surfaces as a rejected promise, not a synchronous throw. */
+        hold: (input: EscrowHoldInput) => Promise<EscrowHoldResult>;
+        /** Release a held deal to the payee (fee skimmed). `escrowId` is the `hold` result's `id`. */
+        release: (input: {
+            escrowId: string;
+        }) => Promise<EscrowResolveResult>;
+        /** Refund a held deal to the payer (100%, untaxed). `escrowId` is the `hold` result's `id`. */
+        refund: (input: {
+            escrowId: string;
+        }) => Promise<EscrowResolveResult>;
+        /** Verify a deal's on-chain state (reconciles a `settling` hold wedged by a crash). */
+        get: (escrowId: string) => Promise<EscrowResolveResult>;
+    };
+    /**
+     * `marketplace` — list an item, and the seller is paid ONLY when it's bought (Phase 3a, off-chain items).
+     * Built on `escrow`: `buy` locks the buyer's USDC on-chain, `confirm` (after your game server delivers the
+     * item) pays the seller, and a no-delivery/timeout `refund`s the buyer. `deliver: true` on `buy` collapses
+     * lock+pay into one call when your server delivers synchronously. On-chain items are Phase 3b.
+     */
+    readonly marketplace: {
+        /** List an off-chain item for sale. No money moves. Idempotent on `idempotencyKey`. */
+        list: (input: MarketplaceListInput) => Promise<Listing>;
+        /** Buy a listing: lock the buyer's USDC in escrow. Pass `deliver: true` to also pay the seller in one call. */
+        buy: (input: {
+            listingId: string;
+            buyer?: `0x${string}`;
+            deliver?: boolean;
+        }) => Promise<MarketplaceSaleResult>;
+        /** Confirm delivery → the seller is paid (release), fee skimmed. */
+        confirm: (input: {
+            listingId: string;
+        }) => Promise<MarketplaceSaleResult>;
+        /** Refund the buyer 100% (seller couldn't deliver / dispute / timeout). */
+        refund: (input: {
+            listingId: string;
+        }) => Promise<MarketplaceSaleResult>;
+        /** Delist an unsold listing (pure DB, no tx). */
+        cancel: (input: {
+            listingId: string;
+        }) => Promise<Listing>;
+        /** Fetch a listing + its on-chain-verified sale status. */
+        get: (listingId: string) => Promise<MarketplaceGetResult>;
     };
     constructor(config: PlaymosConfig);
     /** Connect the player's wallet and return their address. */
@@ -276,6 +193,37 @@ declare class Playmos {
     pay(input: PayInput): Promise<Payment>;
     /** Playmos-owned skill-game entry (10%, 60/30/10 prize pool). Closes #343. */
     enterRound(input: EnterRoundInput): Promise<Payment>;
+    /**
+     * `transfers` — read-back / confirmation for a prior `transfer()` (issue #27).
+     * Poll when POST returned `status: "settling"`; reconciles against chain (incl. gasless agent path).
+     */
+    readonly transfers: {
+        get: (transferId: string) => Promise<{
+            id: string;
+            status: string;
+            txHash: string | null;
+            to: string;
+            amount: string;
+            verifiedVia: "chain" | "cache" | "degraded";
+        }>;
+    };
+    /**
+     * `transfer` — the value-movement base primitive (Phase 1a): move USDC from one wallet to another,
+     * with a per-call fee. The GAME LOGIC is the authority — you already decided the move is valid — so
+     * this is a direct, unconditional push (use `escrow`/`marketplace` when a trust boundary needs fair
+     * exchange). The service settles it through the protocol-agnostic settlement core (idempotent,
+     * reserve-before-broadcast) and the on-chain PlaymosTransfer / PlaymosTransferAuth contracts.
+     *
+     * Fee is per-call: `feeBps` 0–10000 (+ `feeSink`). `feeBps: 0` is an untaxed reward/faucet transfer.
+     * Retries are safe: pass the same `idempotencyKey` and a re-call NEVER broadcasts a second tx —
+     * it returns the cached result (`idempotentReplay: true`).
+     *
+     * Confirmation: treat `status === "settled" && txHash` as final. If `settling`, call
+     * `playmos.transfers.get(id)` until settled/failed. BaseScan: `https://sepolia.basescan.org/tx/<txHash>`.
+     *
+     * NPC `from` requires `sk_test_` and settles gaslessly (NPC signs; service relays).
+     */
+    transfer(input: TransferInput): Promise<TransferResult>;
     /** Verify a payment by the service's on-chain read (spec §6.1). Idempotent. */
     verify(paymentId: string): Promise<VerifyResult>;
     /**
@@ -302,6 +250,37 @@ declare function previewIapSplit(amount: string): {
     fee: string;
     net: string;
 };
+/**
+ * Local preview of a `transfer` fee split without any network — handy for UIs and quotes. Mirrors the
+ * on-chain floor math: `fee = floor(amount * feeBps / 10000)`, `net = amount − fee` (dust → payee).
+ */
+declare function previewTransferSplit(amount: string, feeBps: number): {
+    amount: string;
+    fee: string;
+    net: string;
+    feeBps: number;
+};
+/**
+ * Local preview of what an escrow `release` would pay out, without any network. Mirrors the on-chain
+ * floor math: `fee = floor(amount * feeBps / 10000)`, `net = amount − fee` (dust → payee). A `refund`
+ * returns the full `amount` with no fee, so it needs no preview.
+ */
+declare function previewEscrowFee(amount: string, feeBps: number): {
+    amount: string;
+    fee: string;
+    net: string;
+    feeBps: number;
+};
+/**
+ * Local preview of a marketplace sale's payout, without any network. Mirrors the on-chain floor math
+ * (`fee = floor(price * feeBps / 10000)`, `net = price − fee`, dust → seller). A no-sale/refund pays 0.
+ */
+declare function previewMarketplaceSplit(price: string, feeBps: number): {
+    price: string;
+    fee: string;
+    net: string;
+    feeBps: number;
+};
 /** Local preview of the 60/30/10 entry split without any network. */
 declare function previewPoolSplit(amount: string): {
     amount: string;
@@ -311,74 +290,38 @@ declare function previewPoolSplit(amount: string): {
 };
 
 /**
- * Typed, actionable errors — the Stripe bar (spec §11).
- *
- * Every error carries a stable machine-readable `code` and is thrown at the
- * EARLIEST possible layer: input errors fire client-side before any network or
- * chain call, so a studio never pays gas to discover a typo.
- */
-type PlaymosErrorCode = "invalid_amount" | "missing_field" | "insufficient_gas" | "wallet_connection" | "payment_failed" | "auth" | "api_error" | "config";
-declare class PlaymosError extends Error {
-    readonly code: PlaymosErrorCode;
-    /** Optional machine context (e.g. the offending field, the http status). */
-    readonly detail?: Record<string, unknown>;
-    constructor(code: PlaymosErrorCode, message: string, detail?: Record<string, unknown>);
-}
-/** amount ≤ 0, non-numeric, empty, or more than 2 decimal places. */
-declare class InvalidAmountError extends PlaymosError {
-    constructor(amount: unknown);
-}
-/** A required field (sku, playerId, gameId, roundId, agentId…) was empty. */
-declare class MissingFieldError extends PlaymosError {
-    constructor(field: string);
-}
-/** gas mode "player" and the player's ETH is too low to cover gas (pre-check, §7). */
-declare class InsufficientGasError extends PlaymosError {
-    constructor(detail?: Record<string, unknown>);
-}
-/** The player closed or failed the wallet sheet, or no provider is available. */
-declare class WalletConnectionError extends PlaymosError {
-    constructor(message?: string, detail?: Record<string, unknown>);
-}
-/** The on-chain settlement reverted, was cancelled, or timed out. */
-declare class PaymentFailedError extends PlaymosError {
-    constructor(message?: string, detail?: Record<string, unknown>);
-}
-/** Bad, missing, or wrong-environment API key (e.g. a pk_test_ key on a live route). */
-declare class AuthError extends PlaymosError {
-    constructor(message?: string, detail?: Record<string, unknown>);
-}
-/** The Playmos service returned a non-2xx we don't have a more specific error for. */
-declare class ApiError extends PlaymosError {
-    constructor(message: string, detail?: Record<string, unknown>);
-}
-/** SDK misconfiguration (e.g. a missing contract address for on-chain mode). */
-declare class ConfigError extends PlaymosError {
-    constructor(message: string, detail?: Record<string, unknown>);
-}
-
-/**
- * Webhook signature verification (spec §6.2) — server-side only.
+ * payout.ts — pure payout math for skill/contest settlement (issue #13).
  *
- * Signature scheme (mirrors the Playmos service byte-for-byte):
- *   header `X-Playmos-Signature: t=<unixSeconds>,v1=<hex>`
- *   where <hex> = HMAC_SHA256(secret, `${t}.${rawBody}`)
+ * Scores NEVER enter this module. The studio ranks wallets (best-first) from its
+ * own leaderboard; we only turn that ranking + a payout rule into integer USDC
+ * base-unit amounts that sum EXACTLY to the payable pool.
  *
- * Verify BEFORE trusting an event. Uses node:crypto (constant-time compare) and
- * rejects stale timestamps to blunt replay. Throws on any mismatch.
+ * No network, no chain — fully unit-testable.
  */
-
-declare class WebhookSignatureError extends PlaymosError {
+type PayoutRule = {
+    kind: "winner-take-all";
+} | {
+    kind: "top-n";
+    splitsBps: number[];
+} | {
+    kind: "custom";
+    amounts: string[];
+};
+declare class PayoutError extends Error {
+    code: "payout_invalid";
     constructor(message: string);
 }
 /**
- * Verify a webhook and return the parsed event. `rawBody` MUST be the exact raw
- * request bytes (use express.raw / fastify rawBody) — a re-serialized JSON body
- * will not match the signature.
+ * Apply the studio's payout rule to a payable pool and ranking (best-first).
+ *
+ * - Integer math only (bigint micro-USDC).
+ * - Sum of amounts == pool exactly; any remainder from floor division goes to rank 1.
+ * - Rejects empty ranking, bad splits, more winners than ranking, zero pool.
  */
-declare function verifyWebhook(rawBody: string | Buffer, signatureHeader: string | string[] | undefined, secret: string, opts?: {
-    toleranceSeconds?: number;
-}): WebhookEvent;
+declare function computePayout(pool: bigint, ranking: `0x${string}`[], rule: PayoutRule): {
+    wallet: `0x${string}`;
+    amount: bigint;
+}[];
 
 /**
  * Money math — exact, integer-only, in USDC micro-units (6 decimals).
@@ -435,4 +378,132 @@ declare function ulid(seedTime?: number): string;
 /** `${prefix}_${ulid()}` — e.g. `pay_01J…`, `entry_01J…`, `idem_01J…`. */
 declare function prefixedId(prefix: string): string;
 
-export { type AgentEconomyConfig, ApiError, AuthError, CHAIN_ID, ConfigError, type ContractConfig, DEFAULT_API_BASE_URL, type Eip1193Provider, type EnterRoundInput, type GasConfig, type GasMode, InsufficientGasError, InvalidAmountError, MICRO_PER_USDC, MissingFieldError, type Network, type PayInput, type Payment, PaymentFailedError, type PaymentStatus, Playmos, type PlaymosConfig, PlaymosError, type PlaymosErrorCode, USDC_ADDRESS, USDC_DECIMALS, type VerifyResult, type WalletConfig, WalletConnectionError, type WalletConnector, type WebhookEvent, type WebhookEventType, WebhookSignatureError, computeIapSplit, computePoolSplit, formatMicroToUsd, parseUsdToMicro, prefixedId, previewIapSplit, previewPoolSplit, ulid, verifyWebhook };
+/**
+ * settlement.ts — the x402-ready settlement CORE contract (Phase 0).
+ *
+ * Two shared shapes every value-movement primitive (`transfer`, `escrow`,
+ * `marketplace`) AND the future x402 adapter build on. The whole point of
+ * naming them now is that x402 later becomes a thin HTTP-402 adapter with zero
+ * rework — see `docs/design/transfer-escrow-marketplace-spec.md` §"Architecture:
+ * x402-ready by design".
+ *
+ *   PaymentRequirement — WHAT must be paid. A plain, JSON-safe object. A direct
+ *     SDK call creates one and satisfies it immediately; an x402 "402 Payment
+ *     Required" challenge is literally this object serialized onto the wire. So
+ *     it is designed to round-trip to/from an HTTP 402 body with zero loss —
+ *     `parsePaymentRequirement(serializePaymentRequirement(req))` is `req`.
+ *
+ *   Authorization — HOW a settlement is authorized. A discriminated union so the
+ *     settlement core never bakes in "direct SDK signature": today a
+ *     `wallet-signature` (implemented), tomorrow an `x402-payload` (declared,
+ *     not settled yet). This union is the seam that keeps x402 out of the core.
+ *
+ * Nothing here touches the network or the chain — these are the shared data
+ * shapes the SDK produces and the service's protocol-agnostic settlement core
+ * consumes.
+ */
+
+/** The only settlement asset in V1. Named so an x402 challenge carries it verbatim. */
+type SettlementAsset = "USDC";
+/**
+ * The shared payment contract — WHAT must be paid, independent of HOW it was
+ * requested (direct SDK call today, x402 challenge tomorrow).
+ *
+ * Every field is a JSON primitive so the object is byte-stable across an HTTP
+ * 402 body: mint it once, and both the direct path and the x402 path settle the
+ * exact same requirement, idempotent on `id`.
+ */
+interface PaymentRequirement {
+    /** The anchor id (`preq_<ulid>`). Settlement idempotency key + x402 challenge id. */
+    id: string;
+    /** The recipient wallet (the payee). Checksummed or lowercase 0x-address. */
+    payTo: `0x${string}`;
+    /** USD decimal string ("5.00") — same money convention as `pay()`/`enterRound()`. */
+    amount: string;
+    /** Only USDC in V1. */
+    asset: SettlementAsset;
+    /** Which chain settles this requirement. */
+    network: Network;
+    /** Optional free-form terms/memo, echoed on the receipt and in the 402 body. */
+    terms?: string;
+    /** ISO-8601 expiry. A challenge/authorization presented after this is rejected. */
+    expiresAt: string;
+}
+interface CreatePaymentRequirementInput {
+    /** Recipient wallet. */
+    payTo: `0x${string}`;
+    /** USD decimal string ("5.00"). */
+    amount: string;
+    /** Settlement chain. */
+    network: Network;
+    /** Defaults to "USDC". */
+    asset?: SettlementAsset;
+    /** Optional terms/memo. */
+    terms?: string;
+    /** Absolute ISO expiry. Overrides `expiresInMs`. Defaults to now + 15 min. */
+    expiresAt?: string;
+    /** Relative TTL from now, in ms. Ignored if `expiresAt` is set. */
+    expiresInMs?: number;
+    /** Supply for a deterministic id (e.g. to reuse an upstream id); else a `preq_<ulid>` is minted. */
+    id?: string;
+    /** Injectable clock for deterministic tests. */
+    now?: () => Date;
+}
+/**
+ * Build a validated {@link PaymentRequirement}. This is the single producer the
+ * direct primitives (`transfer`/`escrow`/`marketplace`) and — later — the x402
+ * adapter both call, so every requirement on the wire is shaped identically.
+ * Pure: no network, no chain, no id collisions (monotonic ULID).
+ */
+declare function createPaymentRequirement(input: CreatePaymentRequirementInput): PaymentRequirement;
+/**
+ * Serialize a requirement to a plain, JSON-safe object — the exact body an x402
+ * "402 Payment Required" response carries. Undefined optionals are omitted so
+ * the shape is stable across `JSON.stringify` → `JSON.parse` → re-parse.
+ */
+declare function serializePaymentRequirement(req: PaymentRequirement): Record<string, unknown>;
+/**
+ * Parse + validate an untrusted object (an HTTP 402 body, a queue message, a
+ * direct call) back into a {@link PaymentRequirement}. This is the exact decoder
+ * the x402 adapter reuses — it must reject anything malformed with a typed error.
+ */
+declare function parsePaymentRequirement(input: unknown): PaymentRequirement;
+/**
+ * A settlement authorized by a wallet — the ONLY variant implemented in Phase 0.
+ * Covers both signer models the primitives support:
+ *   - server-held NPC/agent wallets (the service signs) and
+ *   - player Base Accounts (the client signs) —
+ * carrying either the settlement `txHash` the client already broadcast, or a
+ * `signature` + `payload` (e.g. EIP-3009 / EIP-5792 batch params) the service
+ * submits. Phase 0 only READS `txHash`; the signed-submit path lands in Phase 1.
+ */
+interface WalletSignatureAuthorization {
+    kind: "wallet-signature";
+    /** The wallet that authorized the move (payer / signer). */
+    from: `0x${string}`;
+    /** A settlement tx the client already broadcast (client-signed path). */
+    txHash?: `0x${string}`;
+    /** An off-chain signature the service submits on the payer's behalf. */
+    signature?: `0x${string}`;
+    /** Opaque protocol-specific authorization data (EIP-5792 calls, EIP-3009, …). */
+    payload?: Record<string, unknown>;
+}
+/**
+ * A settlement authorized by an x402 payment payload (the `X-PAYMENT` header).
+ * DECLARED for the Phase 4 HTTP-402 adapter so the core's type surface is final
+ * now — but NOT settled in Phase 0: `settle()` throws a clear "not implemented
+ * yet" for this variant. This is the seam that keeps x402 out of the core.
+ */
+interface X402PayloadAuthorization {
+    kind: "x402-payload";
+    /** The raw, opaque x402 payment payload decoded from the request. */
+    payload: Record<string, unknown>;
+}
+/** How a settlement is authorized — protocol-agnostic by construction. */
+type Authorization = WalletSignatureAuthorization | X402PayloadAuthorization;
+/** Narrow to the implemented wallet-signature variant. */
+declare function isWalletSignatureAuthorization(auth: Authorization): auth is WalletSignatureAuthorization;
+/** Narrow to the declared-but-unimplemented x402 variant. */
+declare function isX402PayloadAuthorization(auth: Authorization): auth is X402PayloadAuthorization;
+
+export { AgentFundResult, AgentWallet, type Authorization, CHAIN_ID, type CreatePaymentRequirementInput, DEFAULT_API_BASE_URL, EnterRoundInput, EscrowHoldInput, EscrowHoldResult, EscrowResolveResult, Listing, MICRO_PER_USDC, MarketplaceGetResult, MarketplaceListInput, MarketplaceSaleResult, Network, PayInput, Payment, type PaymentRequirement, PayoutError, type PayoutRule as PayoutRuleCompute, Playmos, PlaymosConfig, RoundOpenInput, RoundSettleInput, RoundState, SettleRoundResult, type SettlementAsset, TransferInput, TransferResult, USDC_ADDRESS, USDC_DECIMALS, VerifyResult, type WalletSignatureAuthorization, WebhookEvent, type X402PayloadAuthorization, computeIapSplit, computePayout, computePoolSplit, createPaymentRequirement, formatMicroToUsd, isWalletSignatureAuthorization, isX402PayloadAuthorization, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, serializePaymentRequirement, ulid };