@playmos/sdk 0.1.5 → 0.2.0

package/dist/index.js

@@ -1,64 +1,6 @@
+import { InvalidAmountError, ConfigError, MissingFieldError, AuthError, WalletConnectionError, InsufficientGasError, PaymentFailedError, ApiError } from './chunk-B7SHFZYY.js';
+export { ApiError, AuthError, ConfigError, InsufficientGasError, InvalidAmountError, MissingFieldError, PaymentFailedError, PlaymosError, WalletConnectionError } from './chunk-B7SHFZYY.js';
 import { encodeFunctionData, numberToHex, keccak256, toBytes } from 'viem';
-import { timingSafeEqual, createHmac } from 'crypto';
-
-// src/errors.ts
-var PlaymosError = class extends Error {
-  constructor(code, message, detail) {
-    super(message);
-    this.name = new.target.name;
-    this.code = code;
-    this.detail = detail;
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-};
-var InvalidAmountError = class extends PlaymosError {
-  constructor(amount) {
-    super(
-      "invalid_amount",
-      `Invalid amount: ${JSON.stringify(amount)}. Provide a positive USD decimal string with at most 2 decimals, e.g. "4.99".`,
-      { amount }
-    );
-  }
-};
-var MissingFieldError = class extends PlaymosError {
-  constructor(field) {
-    super("missing_field", `Missing required field: "${field}".`, { field });
-  }
-};
-var InsufficientGasError = class extends PlaymosError {
-  constructor(detail) {
-    super(
-      "insufficient_gas",
-      `The player's wallet has too little ETH to pay gas. Ask them to add a little ETH, or switch to gas.mode: "sponsored".`,
-      detail
-    );
-  }
-};
-var WalletConnectionError = class extends PlaymosError {
-  constructor(message = "Could not connect the player's wallet.", detail) {
-    super("wallet_connection", message, detail);
-  }
-};
-var PaymentFailedError = class extends PlaymosError {
-  constructor(message = "The on-chain payment did not complete.", detail) {
-    super("payment_failed", message, detail);
-  }
-};
-var AuthError = class extends PlaymosError {
-  constructor(message = "Invalid or missing API key.", detail) {
-    super("auth", message, detail);
-  }
-};
-var ApiError = class extends PlaymosError {
-  constructor(message, detail) {
-    super("api_error", message, detail);
-  }
-};
-var ConfigError = class extends PlaymosError {
-  constructor(message, detail) {
-    super("config", message, detail);
-  }
-};
 
 // src/config.ts
 var CHAIN_ID = {
@@ -359,6 +301,17 @@ var playmosPayAbi = [
   }
 ];
 var prizePoolAbi = [
+  {
+    type: "function",
+    name: "openRound",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "roundId", type: "bytes32" },
+      { name: "series", type: "bytes32" },
+      { name: "entry", type: "uint256" }
+    ],
+    outputs: []
+  },
   {
     type: "function",
     name: "enter",
@@ -369,6 +322,40 @@ var prizePoolAbi = [
     ],
     outputs: []
   },
+  {
+    type: "function",
+    name: "lockRound",
+    stateMutability: "nonpayable",
+    inputs: [{ name: "roundId", type: "bytes32" }],
+    outputs: []
+  },
+  {
+    type: "function",
+    name: "settle",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "roundId", type: "bytes32" },
+      { name: "winners", type: "address[]" },
+      { name: "amounts", type: "uint256[]" }
+    ],
+    outputs: []
+  },
+  {
+    type: "function",
+    name: "getRound",
+    stateMutability: "view",
+    inputs: [{ name: "roundId", type: "bytes32" }],
+    outputs: [
+      { name: "state", type: "uint8" },
+      { name: "series", type: "bytes32" },
+      { name: "entry", type: "uint256" },
+      { name: "pot", type: "uint256" },
+      { name: "entrantCount", type: "uint256" },
+      { name: "payable_", type: "uint256" },
+      { name: "inheritedSeed", type: "uint256" },
+      { name: "lockedAt", type: "uint256" }
+    ]
+  },
   {
     type: "function",
     name: "hasEntered",
@@ -378,6 +365,13 @@ var prizePoolAbi = [
       { name: "identity", type: "bytes32" }
     ],
     outputs: [{ type: "bool" }]
+  },
+  {
+    type: "function",
+    name: "withdraw",
+    stateMutability: "nonpayable",
+    inputs: [],
+    outputs: [{ name: "amount", type: "uint256" }]
   }
 ];
 async function sendCalls(provider, from, chainId, calls, paymasterUrl) {
@@ -511,57 +505,51 @@ function mockEntryPayment(args) {
     mock: true
   };
 }
-var WebhookSignatureError = class extends PlaymosError {
-  constructor(message) {
-    super("api_error", `Webhook signature verification failed: ${message}`);
-  }
-};
-function parseHeader(header) {
-  const parts = Object.fromEntries(
-    header.split(",").map((kv) => {
-      const [k, v] = kv.split("=");
-      return [k?.trim(), v?.trim()];
-    })
-  );
-  const t = Number(parts["t"]);
-  const v1 = parts["v1"];
-  if (!Number.isFinite(t) || !v1) throw new WebhookSignatureError("malformed signature header");
-  return { t, v1 };
-}
-function computeSignature(secret, t, rawBody) {
-  return createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
-}
-function verifyWebhook(rawBody, signatureHeader, secret, opts = {}) {
-  if (!signatureHeader || Array.isArray(signatureHeader)) {
-    throw new WebhookSignatureError("missing signature header");
-  }
-  if (!secret) throw new WebhookSignatureError("missing signing secret");
-  const body = typeof rawBody === "string" ? rawBody : rawBody.toString("utf8");
-  const { t, v1 } = parseHeader(signatureHeader);
-  const tolerance = opts.toleranceSeconds ?? 300;
-  const nowSec = Math.floor(Date.now() / 1e3);
-  if (Math.abs(nowSec - t) > tolerance) {
-    throw new WebhookSignatureError(`timestamp outside tolerance (${tolerance}s)`);
-  }
-  const expected = computeSignature(secret, t, body);
-  const a = Buffer.from(expected, "hex");
-  const b = Buffer.from(v1, "hex");
-  if (a.length !== b.length || !timingSafeEqual(a, b)) {
-    throw new WebhookSignatureError("signature mismatch");
-  }
-  return JSON.parse(body);
-}
 
 // src/client.ts
+var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+function requireAddressField(value, field) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new MissingFieldError(field);
+  }
+  if (!ADDRESS_RE.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 }
+    );
+  }
+  return value.toLowerCase();
+}
+function partyRef(value, field) {
+  if (typeof value !== "string" || value.trim() === "") throw new MissingFieldError(field);
+  if (value.startsWith("0x")) return requireAddressField(value, field);
+  return value;
+}
 var IAP_FEE_BPS = 100;
 var POOL_BPS = 6e3;
 var SEED_BPS = 3e3;
 var RAKE_BPS = 1e3;
 var Playmos = class {
   constructor(config) {
+    /**
+     * 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);
+     */
     this.webhooks = {
-      /** Verify a webhook signature and return the parsed event (server-side). */
-      verify: (rawBody, signatureHeader, secret) => verifyWebhook(rawBody, signatureHeader, secret)
+      /**
+       * @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, _signatureHeader, _secret) => {
+        throw new ConfigError(
+          'playmos.webhooks.verify is server-only and no longer ships in the browser entry (issue #9). Use: import { verifyWebhook } from "@playmos/sdk/server"',
+          { entry: "@playmos/sdk/server" }
+        );
+      }
     };
     this.payouts = {
       /** Choose how the studio is paid: "usdc" (default) or "fiat" (Bridge). */
@@ -569,18 +557,236 @@ var Playmos = class {
       /** Create a Bridge KYC onboarding link (fiat payout). */
       createOnboardingLink: () => this.http.post("/payouts/onboarding_link", {})
     };
+    /**
+     * 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).
+     */
+    this.rounds = {
+      open: async (input) => {
+        requireField(input?.gameId, "gameId");
+        requireField(input?.roundId, "roundId");
+        requireField(input?.entryAmount, "entryAmount");
+        if (!input?.payout || typeof input.payout !== "object") {
+          throw new ConfigError("payout rule is required (winner-take-all | top-n | custom)");
+        }
+        validateAmount(input.entryAmount);
+        const { round } = await this.http.post("/rounds", {
+          gameId: input.gameId,
+          roundId: input.roundId,
+          entryAmount: input.entryAmount,
+          payout: input.payout,
+          closeAt: input.closeAt,
+          seriesKey: input.seriesKey,
+          roundKey: input.roundKey
+        });
+        return round;
+      },
+      lock: async (input) => {
+        requireField(input?.roundId, "roundId");
+        const { round } = await this.http.post(
+          `/rounds/${encodeURIComponent(input.roundId)}/lock`,
+          { gameId: input.gameId }
+        );
+        return round;
+      },
+      settle: async (input) => {
+        requireField(input?.roundId, "roundId");
+        if (!input?.results) throw new ConfigError("results are required (ranking or winners)");
+        const { settle } = await this.http.post(
+          `/rounds/${encodeURIComponent(input.roundId)}/settle`,
+          { gameId: input.gameId, results: input.results }
+        );
+        return settle;
+      },
+      get: async (input) => {
+        requireField(input?.roundId, "roundId");
+        const { round } = await this.http.get(
+          `/rounds/${encodeURIComponent(input.roundId)}`
+        );
+        return round;
+      }
+    };
+    /**
+     * `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.
+     */
     this.agents = {
-      /** Assign a wallet to any identity (incl. an AI NPC). Idempotent by agentId. */
-      createWallet: (input) => {
+      /** Assign (or return) the wallet for a game NPC id. Idempotent — safe to call wherever your NPCs spawn. */
+      createWallet: async (input) => {
+        requireField(input?.agentId, "agentId");
+        const { agent } = await this.http.post("/agents/wallets", { agentId: input.agentId });
+        return agent;
+      },
+      /** Resolve one NPC's wallet by your id. */
+      wallet: async (agentId) => {
+        requireField(agentId, "agentId");
+        const { agent } = await this.http.get(`/agents/wallets/${encodeURIComponent(agentId)}`);
+        return agent;
+      },
+      /** List the NPC wallets you've assigned in this studio. */
+      list: async () => {
+        const { agents } = await this.http.get("/agents/wallets");
+        return agents;
+      },
+      /** Sandbox faucet: fund an NPC with USDC from your treasury (per-NPC lifetime cap). */
+      fund: (input) => {
         requireField(input?.agentId, "agentId");
-        return this.http.post("/agents/wallets", { agentId: input.agentId });
+        validateAmount(input.amount);
+        return this.http.post(`/agents/wallets/${encodeURIComponent(input.agentId)}/fund`, { amount: input.amount });
       },
-      /** Agent↔agent USDC transfer; the configured taxBps is skimmed to Playmos. */
+      /** NPC→NPC (or →player) USDC transfer, by id. A thin alias of `playmos.transfer` (which is canonical). */
       pay: (input) => {
         requireField(input?.from, "from");
         requireField(input?.to, "to");
-        validateAmount(input?.amount);
-        return this.http.post("/agents/pay", input);
+        return this.transfer({ from: input.from, to: input.to, amount: input.amount, feeBps: input.feeBps, feeSink: input.feeSink });
+      }
+    };
+    /**
+     * `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.
+     */
+    this.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: async (input) => {
+        const amountMicro = validateAmount(input.amount);
+        const payer = input.payer === void 0 ? void 0 : requireAddressField(input.payer, "payer");
+        const payee = requireAddressField(input.payee, "payee");
+        const feeBps = input.feeBps ?? 0;
+        if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 1e4) {
+          throw new ConfigError(
+            `feeBps must be an integer in [0, 10000] (fee is taken at release only; refunds are 100%), got: ${JSON.stringify(input.feeBps)}`,
+            { feeBps: input.feeBps }
+          );
+        }
+        const feeSink = feeBps > 0 ? requireAddressField(input.feeSink, "feeSink") : input.feeSink === void 0 ? void 0 : requireAddressField(input.feeSink, "feeSink");
+        const resolver = input.resolver === void 0 ? void 0 : requireAddressField(input.resolver, "resolver");
+        const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
+        const feeMicro = amountMicro * BigInt(feeBps) / 10000n;
+        const { escrow } = await this.http.post(
+          "/escrows",
+          {
+            payer,
+            payee,
+            amount: input.amount,
+            feeBps,
+            feeSink,
+            resolver,
+            expiresIn: input.expiresIn,
+            deadline: input.deadline,
+            memo: input.memo,
+            idempotencyKey
+          },
+          { idempotencyKey }
+        );
+        return {
+          ...escrow,
+          payee: escrow.payee ?? payee,
+          amount: escrow.amount ?? formatMicroToUsd(amountMicro),
+          feeBps: escrow.feeBps ?? feeBps,
+          feeSink: escrow.feeSink ?? feeSink ?? null,
+          resolver: escrow.resolver ?? resolver ?? null,
+          feeAtRelease: escrow.feeAtRelease ?? formatMicroToUsd(feeMicro),
+          netAtRelease: escrow.netAtRelease ?? formatMicroToUsd(amountMicro - feeMicro),
+          idempotentReplay: Boolean(escrow.idempotentReplay)
+        };
+      },
+      /** Release a held deal to the payee (fee skimmed). `escrowId` is the `hold` result's `id`. */
+      release: async (input) => {
+        requireField(input?.escrowId, "escrowId");
+        const { escrow } = await this.http.post(`/escrows/${encodeURIComponent(input.escrowId)}/release`, {});
+        return escrow;
+      },
+      /** Refund a held deal to the payer (100%, untaxed). `escrowId` is the `hold` result's `id`. */
+      refund: async (input) => {
+        requireField(input?.escrowId, "escrowId");
+        const { escrow } = await this.http.post(`/escrows/${encodeURIComponent(input.escrowId)}/refund`, {});
+        return escrow;
+      },
+      /** Verify a deal's on-chain state (reconciles a `settling` hold wedged by a crash). */
+      get: async (escrowId) => {
+        requireField(escrowId, "escrowId");
+        const { escrow } = await this.http.get(`/escrows/${encodeURIComponent(escrowId)}`);
+        return escrow;
+      }
+    };
+    /**
+     * `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.
+     */
+    this.marketplace = {
+      /** List an off-chain item for sale. No money moves. Idempotent on `idempotencyKey`. */
+      list: async (input) => {
+        if (!input?.item || input.item.kind !== "offchain") {
+          throw new ConfigError('marketplace.list requires item = { kind: "offchain", sku: "<your-item-id>" } (on-chain items are Phase 3b)', { item: input?.item });
+        }
+        validateAmount(input.price);
+        const seller = requireAddressField(input.seller, "seller");
+        const feeBps = input.feeBps;
+        if (feeBps !== void 0 && (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 1e4)) {
+          throw new ConfigError(`feeBps must be an integer in [0, 10000], got: ${JSON.stringify(feeBps)}`, { feeBps });
+        }
+        const feeSink = input.feeSink === void 0 ? void 0 : requireAddressField(input.feeSink, "feeSink");
+        const { listing } = await this.http.post("/listings", {
+          seller,
+          item: input.item,
+          price: input.price,
+          feeBps,
+          feeSink,
+          deliveryWindow: input.deliveryWindow,
+          expiresIn: input.expiresIn,
+          gameId: input.gameId,
+          idempotencyKey: input.idempotencyKey
+        });
+        return listing;
+      },
+      /** Buy a listing: lock the buyer's USDC in escrow. Pass `deliver: true` to also pay the seller in one call. */
+      buy: async (input) => {
+        requireField(input?.listingId, "listingId");
+        const buyer = input.buyer === void 0 ? void 0 : requireAddressField(input.buyer, "buyer");
+        return this.http.post(`/listings/${encodeURIComponent(input.listingId)}/buy`, { buyer, deliver: input.deliver === true });
+      },
+      /** Confirm delivery → the seller is paid (release), fee skimmed. */
+      confirm: async (input) => {
+        requireField(input?.listingId, "listingId");
+        return this.http.post(`/listings/${encodeURIComponent(input.listingId)}/confirm`, {});
+      },
+      /** Refund the buyer 100% (seller couldn't deliver / dispute / timeout). */
+      refund: async (input) => {
+        requireField(input?.listingId, "listingId");
+        return this.http.post(`/listings/${encodeURIComponent(input.listingId)}/refund`, {});
+      },
+      /** Delist an unsold listing (pure DB, no tx). */
+      cancel: async (input) => {
+        requireField(input?.listingId, "listingId");
+        const { listing } = await this.http.post(`/listings/${encodeURIComponent(input.listingId)}/cancel`, {});
+        return listing;
+      },
+      /** Fetch a listing + its on-chain-verified sale status. */
+      get: async (listingId) => {
+        requireField(listingId, "listingId");
+        return this.http.get(`/listings/${encodeURIComponent(listingId)}`);
+      }
+    };
+    /**
+     * `transfers` — read-back / confirmation for a prior `transfer()` (issue #27).
+     * Poll when POST returned `status: "settling"`; reconciles against chain (incl. gasless agent path).
+     */
+    this.transfers = {
+      get: async (transferId) => {
+        requireField(transferId, "transferId");
+        const res = await this.http.get(`/transfers/${encodeURIComponent(transferId)}`);
+        return res.transfer;
       }
     };
     this.config = config;
@@ -657,9 +863,11 @@ var Playmos = class {
     const playmosPay = intent.clientParams?.contractAddress ?? this.config.contracts?.playmosPay;
     const studio = intent.clientParams?.studio ?? input.studio;
     if (!playmosPay) throw new ConfigError("No PlaymosPay contract address (service intent + config.contracts both empty).");
-    if (!studio) throw new ConfigError("No studio payout address for this payment.");
+    if (!studio) throw new ConfigError("No studio payout address for this payment (service must return clientParams.studio).");
+    if (!intent.clientParams?.studio && input.studio) ;
     const amountUnits = this.resolveUnits(intent, amountMicro);
-    const calls = buildIapCalls({ usdc, playmosPay, paymentId: intent.payment.id, studio, amountUnits });
+    const paymentId = intent.clientParams?.paymentId ?? intent.payment.id;
+    const calls = buildIapCalls({ usdc, playmosPay, paymentId, studio, amountUnits });
     const { id: callsId } = await sendCalls(provider, from, this.env.chainId, calls, this.sponsorUrl(intent));
     const { txHash } = await waitForCalls(provider, callsId);
     return this.settle(intent.payment.id, txHash);
@@ -711,8 +919,9 @@ var Playmos = class {
     const usdc = intent.clientParams?.usdc ?? this.config.contracts?.usdc ?? USDC_ADDRESS[this.env.network];
     const prizePool = intent.clientParams?.contractAddress ?? this.config.contracts?.prizePool;
     if (!prizePool) throw new ConfigError("No PrizePool contract address for this game (service intent + config.contracts both empty).");
-    const roundKey = input.roundKey ?? intent.clientParams?.roundKey ?? intent.clientParams?.roundId ?? `${input.gameId}:${input.roundId}`;
-    const identity = input.identity ?? intent.clientParams?.identity ?? `${from}#${idempotencyKey}`;
+    const roundKey = intent.clientParams?.roundKey ?? intent.clientParams?.roundId ?? input.roundKey ?? intent.payment.roundId ?? input.roundId;
+    if (!roundKey) throw new ConfigError("No roundKey/roundId for enterRound (service clientParams missing).");
+    const identity = intent.clientParams?.identity ?? input.identity ?? intent.payment.identity ?? `${from}#${idempotencyKey}`;
     const amountUnits = this.resolveUnits(intent, amountMicro);
     const calls = buildEntryCalls({ usdc, prizePool, roundKey, identity, amountUnits });
     const { id: callsId } = await sendCalls(provider, from, this.env.chainId, calls, this.sponsorUrl(intent));
@@ -721,6 +930,64 @@ var Playmos = class {
     payment.identity = identity;
     return payment;
   }
+  /**
+   * `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).
+   */
+  async transfer(input) {
+    const amountMicro = validateAmount(input.amount);
+    const from = input.from === void 0 ? void 0 : partyRef(input.from, "from");
+    const to = partyRef(input.to, "to");
+    const feeBps = input.feeBps ?? 0;
+    if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 1e4) {
+      throw new ConfigError(
+        `feeBps must be an integer in [0, 10000] (0 = untaxed reward/faucet; 500 = 5%; 10000 = 100%), got: ${JSON.stringify(input.feeBps)}`,
+        { feeBps: input.feeBps }
+      );
+    }
+    let feeSink;
+    if (feeBps > 0) {
+      feeSink = requireAddressField(input.feeSink, "feeSink");
+    } else if (input.feeSink !== void 0) {
+      feeSink = requireAddressField(input.feeSink, "feeSink");
+    }
+    const idempotencyKey = input.idempotencyKey ?? prefixedId("idem");
+    const res = await this.http.post(
+      "/transfers",
+      { from, to, amount: input.amount, memo: input.memo, feeBps, feeSink, idempotencyKey },
+      { idempotencyKey }
+    );
+    const t = res.transfer;
+    const feeMicro = amountMicro * BigInt(feeBps) / 10000n;
+    return {
+      id: t.id,
+      status: t.status,
+      txHash: t.txHash,
+      from: t.from,
+      // the service's resolved payer address (omitted when it's the redacted treasury signer)
+      to: t.to,
+      // the service's resolved payee address
+      amount: t.amount ?? formatMicroToUsd(amountMicro),
+      fee: t.fee ?? formatMicroToUsd(feeMicro),
+      net: t.net ?? formatMicroToUsd(amountMicro - feeMicro),
+      feeBps: t.feeBps ?? feeBps,
+      feeSink: t.feeSink ?? feeSink ?? null,
+      memo: t.memo ?? input.memo ?? null,
+      idempotentReplay: Boolean(t.idempotentReplay)
+    };
+  }
   /** Verify a payment by the service's on-chain read (spec §6.1). Idempotent. */
   async verify(paymentId) {
     requireField(paymentId, "paymentId");
@@ -812,6 +1079,30 @@ function previewIapSplit(amount) {
   const { feeMicro, netMicro } = computeIapSplit(micro, IAP_FEE_BPS);
   return { amount: formatMicroToUsd(micro), fee: formatMicroToUsd(feeMicro), net: formatMicroToUsd(netMicro) };
 }
+function previewTransferSplit(amount, feeBps) {
+  const micro = validateAmount(amount);
+  if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 1e4) {
+    throw new ConfigError(`feeBps must be an integer in [0, 10000], got: ${JSON.stringify(feeBps)}`, { feeBps });
+  }
+  const feeMicro = micro * BigInt(feeBps) / 10000n;
+  return { amount: formatMicroToUsd(micro), fee: formatMicroToUsd(feeMicro), net: formatMicroToUsd(micro - feeMicro), feeBps };
+}
+function previewEscrowFee(amount, feeBps) {
+  const micro = validateAmount(amount);
+  if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 1e4) {
+    throw new ConfigError(`feeBps must be an integer in [0, 10000], got: ${JSON.stringify(feeBps)}`, { feeBps });
+  }
+  const feeMicro = micro * BigInt(feeBps) / 10000n;
+  return { amount: formatMicroToUsd(micro), fee: formatMicroToUsd(feeMicro), net: formatMicroToUsd(micro - feeMicro), feeBps };
+}
+function previewMarketplaceSplit(price, feeBps) {
+  const micro = validateAmount(price);
+  if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 1e4) {
+    throw new ConfigError(`feeBps must be an integer in [0, 10000], got: ${JSON.stringify(feeBps)}`, { feeBps });
+  }
+  const feeMicro = micro * BigInt(feeBps) / 10000n;
+  return { price: formatMicroToUsd(micro), fee: formatMicroToUsd(feeMicro), net: formatMicroToUsd(micro - feeMicro), feeBps };
+}
 function previewPoolSplit(amount) {
   const micro = validateAmount(amount);
   const { poolMicro, seedMicro, rakeMicro } = computePoolSplit(micro, POOL_BPS, SEED_BPS, RAKE_BPS);
@@ -823,6 +1114,205 @@ function previewPoolSplit(amount) {
   };
 }
 
-export { ApiError, AuthError, CHAIN_ID, ConfigError, DEFAULT_API_BASE_URL, InsufficientGasError, InvalidAmountError, MICRO_PER_USDC, MissingFieldError, PaymentFailedError, Playmos, PlaymosError, USDC_ADDRESS, USDC_DECIMALS, WalletConnectionError, WebhookSignatureError, computeIapSplit, computePoolSplit, formatMicroToUsd, parseUsdToMicro, prefixedId, previewIapSplit, previewPoolSplit, ulid, verifyWebhook };
+// src/payout.ts
+var PayoutError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.code = "payout_invalid";
+    this.name = "PayoutError";
+  }
+};
+var ADDRESS_RE2 = /^0x[0-9a-fA-F]{40}$/;
+var BPS = 10000n;
+function requireAddress(w, i) {
+  if (!ADDRESS_RE2.test(w)) {
+    throw new PayoutError(`ranking[${i}] must be a 0x-prefixed 20-byte address, got: ${JSON.stringify(w)}`);
+  }
+  return w.toLowerCase();
+}
+function parseUsdToMicroLoose(amount) {
+  if (typeof amount !== "string" || !/^\d+(\.\d{1,6})?$/.test(amount.trim())) {
+    throw new PayoutError(`invalid USD amount: ${JSON.stringify(amount)}`);
+  }
+  const [wholeRaw, frac = ""] = amount.trim().split(".");
+  const whole = wholeRaw ?? "0";
+  const fracPadded = (frac + "000000").slice(0, 6);
+  const micro = BigInt(whole) * 1000000n + BigInt(fracPadded);
+  if (micro <= 0n) throw new PayoutError(`amount must be > 0, got: ${JSON.stringify(amount)}`);
+  return micro;
+}
+function computePayout(pool, ranking, rule) {
+  if (typeof pool !== "bigint" || pool <= 0n) {
+    throw new PayoutError(`pool must be a positive bigint (micro-USDC), got: ${String(pool)}`);
+  }
+  if (!Array.isArray(ranking) || ranking.length === 0) {
+    throw new PayoutError("ranking must be a non-empty array of wallets (best-first)");
+  }
+  const wallets = ranking.map((w, i) => requireAddress(w, i));
+  const seen = /* @__PURE__ */ new Set();
+  for (const w of wallets) {
+    if (seen.has(w)) throw new PayoutError(`duplicate wallet in ranking: ${w}`);
+    seen.add(w);
+  }
+  if (rule.kind === "winner-take-all") {
+    return [{ wallet: wallets[0], amount: pool }];
+  }
+  if (rule.kind === "top-n") {
+    const splits = rule.splitsBps;
+    if (!Array.isArray(splits) || splits.length === 0) {
+      throw new PayoutError("top-n splitsBps must be a non-empty array");
+    }
+    if (splits.length > wallets.length) {
+      throw new PayoutError(
+        `top-n needs ${splits.length} ranked wallets but ranking only has ${wallets.length}`
+      );
+    }
+    let sumBps = 0;
+    for (const b of splits) {
+      if (!Number.isInteger(b) || b <= 0 || b > 1e4) {
+        throw new PayoutError(`each splitsBps entry must be an integer in (0, 10000], got: ${b}`);
+      }
+      sumBps += b;
+    }
+    if (sumBps !== 1e4) {
+      throw new PayoutError(`splitsBps must sum to 10000, got ${sumBps}`);
+    }
+    const out = [];
+    let allocated = 0n;
+    for (let i = 0; i < splits.length; i++) {
+      const amt = pool * BigInt(splits[i]) / BPS;
+      out.push({ wallet: wallets[i], amount: amt });
+      allocated += amt;
+    }
+    const remainder = pool - allocated;
+    if (remainder < 0n) throw new PayoutError("internal: allocated more than pool");
+    out[0] = { wallet: out[0].wallet, amount: out[0].amount + remainder };
+    const filtered = out.filter((x) => x.amount > 0n);
+    if (filtered.length === 0) throw new PayoutError("payout produced no positive amounts");
+    const total = filtered.reduce((s, x) => s + x.amount, 0n);
+    if (total !== pool) throw new PayoutError(`internal: sum ${total} != pool ${pool}`);
+    return filtered;
+  }
+  if (rule.kind === "custom") {
+    const amounts = rule.amounts;
+    if (!Array.isArray(amounts) || amounts.length === 0) {
+      throw new PayoutError("custom amounts must be a non-empty array of USD strings");
+    }
+    if (amounts.length > wallets.length) {
+      throw new PayoutError(
+        `custom amounts has ${amounts.length} entries but ranking only has ${wallets.length}`
+      );
+    }
+    const out = [];
+    let total = 0n;
+    for (let i = 0; i < amounts.length; i++) {
+      const amt = parseUsdToMicroLoose(amounts[i]);
+      out.push({ wallet: wallets[i], amount: amt });
+      total += amt;
+    }
+    if (total !== pool) {
+      throw new PayoutError(
+        `custom amounts sum to ${total} micro-USDC but pool is ${pool} \u2014 must match exactly`
+      );
+    }
+    return out;
+  }
+  throw new PayoutError(`unknown payout rule kind: ${JSON.stringify(rule.kind)}`);
+}
+
+// src/settlement.ts
+var ADDRESS_RE3 = /^0x[0-9a-fA-F]{40}$/;
+var DEFAULT_TTL_MS = 15 * 60 * 1e3;
+function requireAddress2(value, field) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new MissingFieldError(field);
+  }
+  if (!ADDRESS_RE3.test(value)) {
+    throw new ConfigError(`${field} must be a 0x-prefixed 20-byte address, got: ${JSON.stringify(value)}`, {
+      field,
+      value
+    });
+  }
+  return value;
+}
+function requireNetwork(value) {
+  if (value === "base" || value === "base-sepolia") return value;
+  throw new ConfigError(`Unknown network: ${JSON.stringify(value)}. Expected one of ${Object.keys(CHAIN_ID).join(", ")}.`, {
+    field: "network",
+    value
+  });
+}
+function createPaymentRequirement(input) {
+  const now = (input.now ?? (() => /* @__PURE__ */ new Date()))();
+  const payTo = requireAddress2(input.payTo, "payTo");
+  const network = requireNetwork(input.network);
+  const asset = input.asset ?? "USDC";
+  if (asset !== "USDC") {
+    throw new ConfigError(`Unsupported asset: ${JSON.stringify(asset)}. Only "USDC" is supported.`, { asset });
+  }
+  parseUsdToMicro(input.amount);
+  const expiresAt = input.expiresAt ?? new Date(now.getTime() + (input.expiresInMs ?? DEFAULT_TTL_MS)).toISOString();
+  const req = {
+    id: input.id ?? prefixedId("preq"),
+    payTo,
+    amount: input.amount,
+    asset,
+    network,
+    expiresAt
+  };
+  if (input.terms !== void 0) req.terms = input.terms;
+  return req;
+}
+function serializePaymentRequirement(req) {
+  const body = {
+    id: req.id,
+    payTo: req.payTo,
+    amount: req.amount,
+    asset: req.asset,
+    network: req.network,
+    expiresAt: req.expiresAt
+  };
+  if (req.terms !== void 0) body.terms = req.terms;
+  return body;
+}
+function parsePaymentRequirement(input) {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new ConfigError("PaymentRequirement must be a JSON object.", { input });
+  }
+  const o = input;
+  const id = o.id;
+  if (typeof id !== "string" || id.trim() === "") throw new MissingFieldError("id");
+  if (o.asset !== "USDC") {
+    throw new ConfigError(`PaymentRequirement.asset must be "USDC", got: ${JSON.stringify(o.asset)}.`, {
+      asset: o.asset
+    });
+  }
+  const payTo = requireAddress2(o.payTo, "payTo");
+  const network = requireNetwork(o.network);
+  if (typeof o.amount !== "string") throw new InvalidAmountError(o.amount);
+  parseUsdToMicro(o.amount);
+  if (typeof o.expiresAt !== "string" || o.expiresAt.trim() === "") throw new MissingFieldError("expiresAt");
+  if (o.terms !== void 0 && typeof o.terms !== "string") {
+    throw new ConfigError("PaymentRequirement.terms must be a string when present.", { terms: o.terms });
+  }
+  const req = {
+    id,
+    payTo,
+    amount: o.amount,
+    asset: "USDC",
+    network,
+    expiresAt: o.expiresAt
+  };
+  if (o.terms !== void 0) req.terms = o.terms;
+  return req;
+}
+function isWalletSignatureAuthorization(auth) {
+  return auth.kind === "wallet-signature";
+}
+function isX402PayloadAuthorization(auth) {
+  return auth.kind === "x402-payload";
+}
+
+export { CHAIN_ID, DEFAULT_API_BASE_URL, MICRO_PER_USDC, PayoutError, Playmos, USDC_ADDRESS, USDC_DECIMALS, computeIapSplit, computePayout, computePoolSplit, createPaymentRequirement, formatMicroToUsd, isWalletSignatureAuthorization, isX402PayloadAuthorization, parsePaymentRequirement, parseUsdToMicro, prefixedId, previewEscrowFee, previewIapSplit, previewMarketplaceSplit, previewPoolSplit, previewTransferSplit, serializePaymentRequirement, ulid };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map