@zkp2p/cash 0.2.0 → 0.3.0-rc.0

package/AGENTS.md

@@ -16,7 +16,9 @@ can withdraw an unmatched deposit.
    human approval step) → use `prepare()` / `prepareTopUp()` /
    `prepareWithdraw()`. Each returns unsigned `txs[]`
    (`{ to, data, value, chainId }`) plus same-index `steps[]` labels; inspect
-   the plan, submit the transactions in order, and wait for each receipt.
+   the plan, submit the transactions in order, and wait for each receipt. After
+   `createDeposit` confirms, pass its receipt to `finalizePreparedCashout()` and
+   persist the returned `depositId`.
 3. **You are a tool-use host** (MCP server, CLI) → import the manifest from
    `@zkp2p/cash/tools` and map the tool names to the verbs above. Base-USDC
    mutating tools return unsigned transactions. `cash_source_quote` is a quote,
@@ -57,14 +59,28 @@ const est = await cash.estimate({ amount: usdc(500), currency: 'EUR' });
 // Progressive UI: do not let indexer-backed history hold up the oracle rate.
 const rateOnly = await cash.estimate({ amount: usdc(500), currency: 'EUR' }, { includeEta: false });
 
-// Optional: raw demand + speed evidence per offered platform:currency pair.
+// Optional: raw demand + speed evidence per offered pair or sorted currency set.
 const stats = await cash.fillStats();
+console.log(stats['revolut:EUR+GBP+USD']);
 
 // 3. Execute.
 const { depositId } = await cash.cashout(
   {
     amount: usdc(500),
-    receive: { platform: 'revolut', currency: 'EUR', payee: { offchainId: 'revtag' } },
+    receive: { platform: 'revolut', currency: 'EUR', payee: 'revtag' },
+  },
+  { signer },
+);
+
+// Faster matching: one Revolut method, three live-oracle currency options.
+const multiCurrency = await cash.cashout(
+  {
+    amount: usdc(500),
+    receive: {
+      platform: 'revolut',
+      currencies: ['EUR', 'GBP', 'USD'],
+      payee: { offchainId: 'revtag' },
+    },
   },
   { signer },
 );
@@ -173,6 +189,7 @@ Every `CashError` carries `code`, `retryable`, `remediation`. Behavior:
 | `UNSUPPORTED_PLATFORM_CURRENCY`         | no        | Use a currency listed for that platform                                                    |
 | `AMOUNT_BELOW_MINIMUM`                  | no        | Raise amount (hard floor $0.01, recommended at least 1 USDC)                               |
 | `INVALID_INTENT_AMOUNT_RANGE`           | no        | Use a positive min, max at least min, and max no greater than amount                       |
+| `INVALID_PAYOUT_CURRENCIES`             | no        | Pass one or more unique currencies listed for the platform                                 |
 | `PAYEE_VERIFICATION_REQUIRED`           | no        | Register a new Wise/PayPal payee through Peer; an existing registered handle can be reused |
 | `PAYEE_REGISTRATION_FAILED`             | yes       | Validate against `payeeHint`, then retry                                                   |
 | `SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE`   | no        | Execute Relay with a signer first, then prepare a Base-USDC cashout                        |
@@ -187,6 +204,7 @@ Every `CashError` carries `code`, `retryable`, `remediation`. Behavior:
 | `SOURCE_CASHOUT_STATUS_UNKNOWN`         | no        | Inspect `recovery.depositTxHash`; do not resubmit while its receipt is unknown             |
 | `INSUFFICIENT_TOKEN_BALANCE`            | no        | Fund the required token amount, then retry                                                 |
 | `ALLOWANCE_NOT_VISIBLE`                 | yes       | Approval mined but a stale RPC hid it; retry after it becomes visible                      |
+| `TRANSACTION_REJECTED`                  | yes       | Retry when ready and approve the wallet request                                            |
 | `TRANSACTION_FAILED`                    | no        | Inspect the failed/reverted call before another action                                     |
 | `TRANSACTION_SUBMISSION_UNKNOWN`        | no        | Inspect Base wallet/protocol state and the recovery action before any resubmission         |
 | `TRANSACTION_STATUS_UNKNOWN`            | no        | Inspect `recovery.transactionHash` before resubmitting                                     |

package/README.md

@@ -39,16 +39,32 @@ const rateOnly = await cash.estimate(
   { amount: usdc(1000), currency: 'USD' },
   { includeEta: false },
 );
-const pairStats = (await cash.fillStats())['venmo:USD'];
+const fillStats = await cash.fillStats();
+const pairStats = fillStats['venmo:USD'];
+const multiCurrencyStats = fillStats['revolut:EUR+GBP+USD'];
 
 const { depositId } = await cash.cashout(
   {
     amount: usdc(1000),
-    receive: { platform: 'venmo', currency: 'USD', payee: { offchainId: '@you' } },
+    receive: { platform: 'venmo', currency: 'USD', payee: '@you' },
   },
   { signer }, // any viem WalletClient on Base
 );
 
+// One method can offer several currencies. The buyer chooses the fill
+// currency, and each option resolves at its own live oracle rate.
+const fastFill = await cash.cashout(
+  {
+    amount: usdc(1000),
+    receive: {
+      platform: 'revolut',
+      currencies: ['EUR', 'GBP', 'USD'],
+      payee: { offchainId: 'revtag' },
+    },
+  },
+  { signer },
+);
+
 for await (const order of cash.watch(depositId)) {
   console.log(order.state, order.explain());
   if (order.state === 'delivered') break;
@@ -83,11 +99,12 @@ console.log(source?.transactions?.origin, source?.transactions?.destination);
 | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
 | `capabilities()`                                               | Sync discovery: Base USDC destination/default source, platforms × currencies × payee hints × amount bounds                      |
 | `capabilities({ includeRelaySources: true })`                  | Async discovery: adds live Relay SDK EVM source chains/tokens                                                                   |
-| `fillStats()`                                                  | Cached 30-day fill counts and median first-fill time per exact `platform:currency` pair                                         |
+| `fillStats()`                                                  | Cached 30-day fill counts and median first-fill time per exact `platform:currency` pair or sorted multi-currency set            |
 | `quoteSource(input)` / `executeSourceQuote(quote, { signer })` | Relay SDK EVM source routing into Base USDC before cashout                                                                      |
 | `relayStatus(requestId)`                                       | Relay request status from the Relay SDK request path                                                                            |
 | `estimate({ amount, currency }, { includeEta? })`              | Base USDC oracle estimate; optionally skip the historical ETA for progressive rendering                                         |
 | `cashout(input, { signer })`                                   | Registers your payee, creates the protocol-held order, returns the `depositId`                                                  |
+| `prepare(input)` / `finalizePreparedCashout(receipt)`          | Prepare external signing, then resolve the confirmed createDeposit receipt into a resumable result                              |
 | `order(depositId)` / `orders(owner)`                           | Resume any order from its id alone; list all orders for a wallet                                                                |
 | `watch(depositId)`                                             | Async iterator: yields on every state change until terminal, abort, or timeout                                                  |
 | `withdraw(depositId, { signer, amount? })`                     | The ONE unwind verb - partial with an `amount` (live intents don't block it), full close without (prunes expired intents first) |
@@ -102,9 +119,36 @@ transaction does before signing. `prepare()` is Base-USDC-only and rejects a
 `source` with `SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE`. A signer-backed app can
 use `cashout({ source }, { signer, sourceSigner })`; a custody-separated host
 must execute and confirm its Relay route before preparing the Base-USDC
-cashout. Every Peer Cash transaction, including approves, carries ERC-8021
+cashout. After externally executing a prepared `createDeposit`, pass its
+confirmed receipt to `finalizePreparedCashout()` to recover the same
+`CashoutResult` shape as `cashout()` without importing protocol ABIs. Every
+Peer Cash transaction, including approves, carries ERC-8021
 attribution: `peer-cash` first, your own `referrer` code(s) after it.
 
+```ts
+const prepared = await cash.prepare({
+  amount: 5_000_000n,
+  receive: {
+    platform: 'venmo',
+    currency: 'USD',
+    payee: { offchainId: '@maker' },
+  },
+});
+
+let createDepositReceipt;
+for (const [index, transaction] of prepared.txs.entries()) {
+  const receipt = await externalRuntime.sendAndWait(transaction);
+  if (prepared.steps[index]?.kind === 'createDeposit') {
+    createDepositReceipt = receipt;
+  }
+}
+if (!createDepositReceipt) throw new Error('createDeposit receipt missing');
+
+const result = cash.finalizePreparedCashout(createDepositReceipt);
+await persistDepositId(result.depositId);
+const liveOrder = await cash.order(result.depositId);
+```
+
 `capabilities()` presents Zelle as one platform. A cashout with
 `receive.platform: 'zelle'` attaches only the generic Zelle payment method to
 the deposit. Bank-specific capture routing is outside this maker-side SDK and
@@ -193,7 +237,9 @@ awaiting-buyer ──────────► matched ───────
   by the same rolling 30-day, intent-attributed pair sampler as `fillStats()`,
   measured from deposit creation to the first fulfilled fill through the pair.
   The raw snapshot is cached for 15 minutes per client and each ETA is still
-  resolved from its exact normalized `platform:currency` key. Use
+  resolved from its exact normalized `platform:currency` key. Multi-currency
+  deposits also produce sorted keys such as `revolut:EUR+GBP+USD`, measured to
+  the first fill in any offered currency. Use
   `{ includeEta: false }` when rate and receive amount should render first.
 - **Availability thresholds belong to the consumer.** `fillStats()` returns raw
   evidence. A recommended gate is `fills >= 10 && medianFillSeconds <= 48h`.

package/dist/{chunk-TR6JVYYF.js → chunk-5VBP3IWK.js}

@@ -81,6 +81,12 @@ var errors = {
     retryable: false,
     remediation: `Use a positive minimum no greater than the maximum, and a maximum no greater than the cash-out amount.`
   }),
+  invalidPayoutCurrencies: (platform, reason) => new CashError({
+    code: "INVALID_PAYOUT_CURRENCIES",
+    message: `The ${platform} payout currency set is invalid: ${reason}.`,
+    retryable: false,
+    remediation: `Pass one or more unique currencies listed for ${platform} by capabilities().`
+  }),
   activeIntentBlocksWithdrawal: (depositId) => new CashError({
     code: "ACTIVE_INTENT_BLOCKS_WITHDRAWAL",
     message: `Order ${depositId} has a live buyer intent; escrow blocks withdrawal while a buyer may still deliver.`,
@@ -284,7 +290,12 @@ var errors = {
     code: "DEPOSIT_RESOLUTION_FAILED",
     message: `Deposit transaction ${txHash} succeeded but no DepositReceived event was found in the receipt.`,
     retryable: false,
-    remediation: `Inspect the transaction on Basescan; recover the depositId from the DepositReceived log manually, then resume with order(depositId).`
+    remediation: `Inspect the transaction on Basescan; recover the depositId from the DepositReceived log manually, then resume with order(depositId).`,
+    recovery: {
+      kind: "inspect-base-transaction",
+      transactionHash: txHash,
+      operation: "cashout"
+    }
   }),
   signerRequired: (verb) => new CashError({
     code: "SIGNER_REQUIRED",
@@ -322,6 +333,15 @@ var errors = {
     },
     { cause }
   ),
+  transactionRejected: (verb, cause) => new CashError(
+    {
+      code: "TRANSACTION_REJECTED",
+      message: `The ${verb} wallet request was cancelled.`,
+      retryable: true,
+      remediation: `Retry the original Peer Cash action and approve the wallet request when you are ready.`
+    },
+    { cause }
+  ),
   transactionSubmissionUnknown: (operation, cause, recovery) => new CashError(
     {
       code: "TRANSACTION_SUBMISSION_UNKNOWN",
@@ -365,6 +385,7 @@ var errors = {
 };
 function mapChainError(verb, err, context = {}) {
   if (isCashError(err)) return err;
+  if (isUserRejectedError(err)) return errors.transactionRejected(verb, err);
   const message = err instanceof Error ? err.message : String(err);
   if (/\bpaused\b/i.test(message)) return errors.escrowPaused();
   if (/exceeds balance|insufficient token balance/i.test(message)) {
@@ -375,5 +396,41 @@ function mapChainError(verb, err, context = {}) {
   }
   return errors.chainCallFailed(verb, err);
 }
+function hasUserRejectionText(value) {
+  const normalized = value.toLowerCase().replace(/[^a-z0-9]+/g, "");
+  return normalized.includes("userrejected") || normalized.includes("userdenied") || normalized.includes("requestrejected") || normalized.includes("rejectedrequest") || /(^|[^a-z0-9])action[_ -]?rejected(?:error)?($|[^a-z0-9])/i.test(value) || normalized === "actionrejected" || normalized === "actionrejectederror";
+}
+function isUserRejectedError(value) {
+  const seen = /* @__PURE__ */ new Set();
+  const text = [];
+  let current = value;
+  while (current !== null && !seen.has(current)) {
+    seen.add(current);
+    if (current === -32003 || current === "-32003") return false;
+    if (current === 4001 || current === "4001" || current === 5e3 || current === "5000") {
+      return true;
+    }
+    if (typeof current === "string") {
+      text.push(current);
+      break;
+    }
+    if (typeof current !== "object" && typeof current !== "function") break;
+    const detail = current;
+    if (detail.code === -32003 || detail.code === "-32003" || detail.name === "TransactionRejectedRpcError") {
+      return false;
+    }
+    if (detail.code === 4001 || detail.code === "4001" || detail.code === 5e3 || detail.code === "5000" || detail.code === "ACTION_REJECTED" || detail.name === "UserRejectedRequestError") {
+      return true;
+    }
+    text.push(
+      ...[detail.name, detail.message, detail.code].filter(
+        (part) => typeof part === "string"
+      )
+    );
+    if (detail.cause === void 0) break;
+    current = detail.cause;
+  }
+  return text.some(hasUserRejectionText);
+}
 
-export { BASE_CHAIN_ID, BASE_USDC_ADDRESS, CASH_ORDER_POLL_INTERVAL_MS, CASH_ORDER_STATUSES, CASH_RETAIN_ON_EMPTY, CashError, MARKET_SPREAD_BPS, ORACLE_MIN_CONVERSION_RATE_SENTINEL, USDC_DECIMALS, errors, isCashError, mapChainError };
+export { BASE_CHAIN_ID, BASE_USDC_ADDRESS, CASH_ORDER_POLL_INTERVAL_MS, CASH_ORDER_STATUSES, CASH_RETAIN_ON_EMPTY, CashError, MARKET_SPREAD_BPS, ORACLE_MIN_CONVERSION_RATE_SENTINEL, USDC_DECIMALS, errors, isCashError, isUserRejectedError, mapChainError };

package/dist/{createCashClient-CTEXn9FF.d.cts → createCashClient-DGMd8Swr.d.cts}

@@ -1,4 +1,4 @@
-import { Address, WalletClient, Hash, Transport } from 'viem';
+import { Address, WalletClient, Hash, Log, Transport } from 'viem';
 import { IndexerIntentStatus, Zkp2pClient, IndexerIntent, CurrencyType, PreparedTransaction, RuntimeEnv } from '@zkp2p/sdk';
 import { Execute, RelayClient, RelayChain, ProgressData } from '@relayprotocol/relay-sdk';
 
@@ -172,15 +172,20 @@ interface CashBuyerProfile {
     firstSeenAt?: number;
     lastSeenAt?: number;
 }
-/** A single payout leg of a cash-out (one platform + currency + payee). */
-interface CashPayout {
+interface CashPayoutBase {
     /** Payment platform / processor name, e.g. `'venmo'`, `'revolut'`, `'wise'`. */
     processorName: string;
-    /** Fiat currency the user wants to receive. */
-    currency: CurrencyType;
     /** The user's payee handle for that platform (e.g. a Venmo username, Wisetag). */
     payeeData: CuratorPayeeDataInput;
 }
+/** One payment method offering either one currency or a non-empty currency set. */
+type CashPayout = CashPayoutBase & ({
+    currency: CurrencyType;
+    currencies?: never;
+} | {
+    currency?: never;
+    currencies: readonly [CurrencyType, ...CurrencyType[]];
+});
 /**
  * Input to create a market-rate (0% spread) cash-out deposit.
  *
@@ -193,7 +198,7 @@ interface CashDepositInput {
     token?: Address;
     /** Total amount to cash out, in USDC base units (6 decimals). */
     amount: bigint;
-    /** One or more payout legs (platform + currency + payee). */
+    /** One or more payout legs (platform + currency choice + payee). */
     payouts: CashPayout[];
     /** Per-order min/max in USDC base units. Defaults derive from {@link buildIntentAmountRange}. */
     intentAmountRange?: {
@@ -358,12 +363,15 @@ interface CashCapabilities {
 declare function buildCapabilities(environment: RuntimeEnv): CashCapabilities;
 
 interface CashPairFillStats {
-    /** Fulfilled intents through this pair inside the rolling 30-day window. */
+    /** Fulfilled intents through this pair or currency set inside the rolling 30-day window. */
     fills: number;
-    /** Median deposit-to-first-fill seconds, sampled once per deposit for this pair. */
+    /** Median deposit-to-first-fill seconds, sampled once per deposit for this pair or set. */
     medianFillSeconds?: number;
 }
-/** Raw demand and speed evidence keyed by `basePlatform:currencyCode`. */
+/**
+ * Raw demand and speed evidence keyed by `basePlatform:currencyCode` or a
+ * sorted multi-currency set such as `revolut:EUR+GBP+USD`.
+ */
 type CashFillStats = Record<string, CashPairFillStats>;
 interface CashFillEta {
     /** Simple headline ETA from recent deposits. Undefined when no recent sample exists. */
@@ -435,8 +443,12 @@ interface CashEstimate {
     eta?: CashFillEta;
 }
 
+type CashPayeeInput = string | CuratorPayeeDataInput;
+/** Convert user-entered handles into the curator form for a payment platform. */
+declare function normalizeCashPayee(platform: string, payee: CashPayeeInput): CuratorPayeeDataInput;
+
 /**
- * `createCashClient` - the eight-verb facade over a read-only `Zkp2pClient`.
+ * `createCashClient` - the cash lifecycle facade over a read-only `Zkp2pClient`.
  *
  * The facade keeps the outward surface tiny (capabilities / estimate / cashout
  * / order / orders / watch / withdraw / topUp) while reusing the published
@@ -481,8 +493,18 @@ interface CashLeg {
     platform: string;
     /** Fiat currency to receive. */
     currency: CurrencyType;
-    /** Payee details, e.g. `{ offchainId: '@andrew' }`. */
-    payee: CuratorPayeeDataInput;
+    /** Raw handle or prepared curator data (needed for identity attestations). */
+    payee: CashPayeeInput;
+    currencies?: never;
+}
+interface CashMultiCurrencyLeg {
+    /** Platform id from `capabilities()`, e.g. `'revolut'`. */
+    platform: string;
+    /** Fiat currencies a buyer may use to fill this cash-out. */
+    currencies: readonly [CurrencyType, ...CurrencyType[]];
+    /** Raw handle or prepared curator data shared by every offered currency. */
+    payee: CashPayeeInput;
+    currency?: never;
 }
 interface CashoutInput {
     /**
@@ -498,8 +520,8 @@ interface CashoutInput {
         /** Relay amount mode. Omit for the recommended exact source-input flow. */
         tradeType?: 'EXACT_INPUT' | 'EXACT_OUTPUT' | 'EXPECTED_OUTPUT';
     };
-    /** Where the fiat should arrive. Multi-payout is a deliberate v1 cut. */
-    receive: CashLeg;
+    /** Where the fiat should arrive. One method may offer multiple currencies. */
+    receive: CashLeg | CashMultiCurrencyLeg;
     /** Per-order min/max override (USDC base units). */
     intentAmountRange?: {
         min: bigint;
@@ -572,6 +594,12 @@ interface PrepareResult {
         hashedOnchainIds: string[];
     };
 }
+/** Confirmed createDeposit receipt from an externally executed prepare() plan. */
+interface PreparedCashoutReceipt {
+    transactionHash: Hash;
+    status: 'success' | 'reverted';
+    logs: readonly Log[];
+}
 interface WithdrawResult {
     depositId: string;
     /** Present when expired intents had to be pruned before withdrawal. */
@@ -597,10 +625,11 @@ interface CashClient {
         includeRelaySources: true;
     }): Promise<CashCapabilities>;
     /**
-     * 0c - Raw 30-day demand and first-fill speed evidence keyed by
-     * `platform:currency`. A recommended consumer gate is `fills >= 10 &&
-     * medianFillSeconds <= 48h`; fail open to the full capability catalog when
-     * stats are unavailable or the gate would remove every pair.
+     * 0c - Raw 30-day demand and first-fill speed evidence keyed by an exact
+     * `platform:currency` pair or sorted multi-currency set. A recommended
+     * consumer gate is `fills >= 10 && medianFillSeconds <= 48h`; fail open to
+     * the full capability catalog when stats are unavailable or the gate would
+     * remove every pair.
      */
     fillStats(): Promise<CashFillStats>;
     /** Relay-only source discovery helper. */
@@ -624,6 +653,8 @@ interface CashClient {
     cashout(input: CashoutInput, opts: CashoutOptions): Promise<CashoutResult>;
     /** 2b - Unsigned path: `txs[]` for agent wallets, AA, server keys, policy layers. */
     prepare(input: CashoutInput): Promise<PrepareResult>;
+    /** Resolve an externally executed createDeposit receipt into resumable cash-out state. */
+    finalizePreparedCashout(receipt: PreparedCashoutReceipt): CashoutResult;
     /** 3 - Observe: resumable from `depositId` alone; no session state anywhere. */
     order(depositId: string): Promise<CashOrder>;
     /**
@@ -662,4 +693,4 @@ interface CashClient {
 }
 declare function createCashClient(options: CashClientOptions): CashClient;
 
-export { type CashPlatformCapability as A, type CashPreparedStepKind as B, type CashPayoutInfo as C, type CashoutInput as D, type CashoutOptions as E, type CuratorPayeeDataInput as F, type EstimateInput as G, type EstimateOptions as H, type IntentStatus as I, RECOMMENDED_MIN_CASHOUT_AMOUNT as J, type RelayOptions as K, type RelayQuoteInput as L, MIN_CASHOUT_AMOUNT as M, type RelaySourceInput as N, type OrdersOptions as O, type PrepareResult as P, type RelayTransaction as Q, type RelayExecutionResult as R, type SignerOptions as S, type TopUpResult as T, type WatchOptions as U, type WithdrawOptions as V, type WithdrawResult as W, buildCapabilities as X, createCashClient as Y, type IntentEntity as a, type CashBuyerProfile as b, type CashDepositInput as c, type CreateDepositParamsArg as d, type CashOrder as e, type CashFill as f, type CashCapabilities as g, type CashoutResult as h, type CashEstimate as i, type CashFillStats as j, type CashPreparedStep as k, type RelayQuote as l, type RelayStatus as m, type CashSourceCapabilities as n, CASH_ATTRIBUTION_CODE as o, type CashAsset as p, type CashChain as q, type CashClient as r, type CashClientOptions as s, type CashFillEta as t, type CashLeg as u, type CashNextAction as v, type CashOrderState as w, type CashPairFillStats as x, type CashPayout as y, type CashPayoutPricing as z };
+export { createCashClient as $, type CashPayout as A, type CashPayoutPricing as B, type CashPayoutInfo as C, type CashPlatformCapability as D, type CashPreparedStepKind as E, type CashoutInput as F, type CashoutOptions as G, type CuratorPayeeDataInput as H, type IntentStatus as I, type EstimateInput as J, type EstimateOptions as K, type PreparedCashoutReceipt as L, MIN_CASHOUT_AMOUNT as M, RECOMMENDED_MIN_CASHOUT_AMOUNT as N, type OrdersOptions as O, type PrepareResult as P, type RelayOptions as Q, type RelayExecutionResult as R, type RelayQuoteInput as S, type TopUpResult as T, type RelaySourceInput as U, type RelayTransaction as V, type WithdrawResult as W, type SignerOptions as X, type WatchOptions as Y, type WithdrawOptions as Z, buildCapabilities as _, type IntentEntity as a, normalizeCashPayee as a0, type CashBuyerProfile as b, type CashDepositInput as c, type CreateDepositParamsArg as d, type CashOrder as e, type CashFill as f, type CashCapabilities as g, type CashoutResult as h, type CashEstimate as i, type CashFillStats as j, type CashPreparedStep as k, type RelayQuote as l, type RelayStatus as m, type CashSourceCapabilities as n, CASH_ATTRIBUTION_CODE as o, type CashAsset as p, type CashChain as q, type CashClient as r, type CashClientOptions as s, type CashFillEta as t, type CashLeg as u, type CashMultiCurrencyLeg as v, type CashNextAction as w, type CashOrderState as x, type CashPairFillStats as y, type CashPayeeInput as z };

package/dist/{createCashClient-CTEXn9FF.d.ts → createCashClient-DGMd8Swr.d.ts}

@@ -1,4 +1,4 @@
-import { Address, WalletClient, Hash, Transport } from 'viem';
+import { Address, WalletClient, Hash, Log, Transport } from 'viem';
 import { IndexerIntentStatus, Zkp2pClient, IndexerIntent, CurrencyType, PreparedTransaction, RuntimeEnv } from '@zkp2p/sdk';
 import { Execute, RelayClient, RelayChain, ProgressData } from '@relayprotocol/relay-sdk';
 
@@ -172,15 +172,20 @@ interface CashBuyerProfile {
     firstSeenAt?: number;
     lastSeenAt?: number;
 }
-/** A single payout leg of a cash-out (one platform + currency + payee). */
-interface CashPayout {
+interface CashPayoutBase {
     /** Payment platform / processor name, e.g. `'venmo'`, `'revolut'`, `'wise'`. */
     processorName: string;
-    /** Fiat currency the user wants to receive. */
-    currency: CurrencyType;
     /** The user's payee handle for that platform (e.g. a Venmo username, Wisetag). */
     payeeData: CuratorPayeeDataInput;
 }
+/** One payment method offering either one currency or a non-empty currency set. */
+type CashPayout = CashPayoutBase & ({
+    currency: CurrencyType;
+    currencies?: never;
+} | {
+    currency?: never;
+    currencies: readonly [CurrencyType, ...CurrencyType[]];
+});
 /**
  * Input to create a market-rate (0% spread) cash-out deposit.
  *
@@ -193,7 +198,7 @@ interface CashDepositInput {
     token?: Address;
     /** Total amount to cash out, in USDC base units (6 decimals). */
     amount: bigint;
-    /** One or more payout legs (platform + currency + payee). */
+    /** One or more payout legs (platform + currency choice + payee). */
     payouts: CashPayout[];
     /** Per-order min/max in USDC base units. Defaults derive from {@link buildIntentAmountRange}. */
     intentAmountRange?: {
@@ -358,12 +363,15 @@ interface CashCapabilities {
 declare function buildCapabilities(environment: RuntimeEnv): CashCapabilities;
 
 interface CashPairFillStats {
-    /** Fulfilled intents through this pair inside the rolling 30-day window. */
+    /** Fulfilled intents through this pair or currency set inside the rolling 30-day window. */
     fills: number;
-    /** Median deposit-to-first-fill seconds, sampled once per deposit for this pair. */
+    /** Median deposit-to-first-fill seconds, sampled once per deposit for this pair or set. */
     medianFillSeconds?: number;
 }
-/** Raw demand and speed evidence keyed by `basePlatform:currencyCode`. */
+/**
+ * Raw demand and speed evidence keyed by `basePlatform:currencyCode` or a
+ * sorted multi-currency set such as `revolut:EUR+GBP+USD`.
+ */
 type CashFillStats = Record<string, CashPairFillStats>;
 interface CashFillEta {
     /** Simple headline ETA from recent deposits. Undefined when no recent sample exists. */
@@ -435,8 +443,12 @@ interface CashEstimate {
     eta?: CashFillEta;
 }
 
+type CashPayeeInput = string | CuratorPayeeDataInput;
+/** Convert user-entered handles into the curator form for a payment platform. */
+declare function normalizeCashPayee(platform: string, payee: CashPayeeInput): CuratorPayeeDataInput;
+
 /**
- * `createCashClient` - the eight-verb facade over a read-only `Zkp2pClient`.
+ * `createCashClient` - the cash lifecycle facade over a read-only `Zkp2pClient`.
  *
  * The facade keeps the outward surface tiny (capabilities / estimate / cashout
  * / order / orders / watch / withdraw / topUp) while reusing the published
@@ -481,8 +493,18 @@ interface CashLeg {
     platform: string;
     /** Fiat currency to receive. */
     currency: CurrencyType;
-    /** Payee details, e.g. `{ offchainId: '@andrew' }`. */
-    payee: CuratorPayeeDataInput;
+    /** Raw handle or prepared curator data (needed for identity attestations). */
+    payee: CashPayeeInput;
+    currencies?: never;
+}
+interface CashMultiCurrencyLeg {
+    /** Platform id from `capabilities()`, e.g. `'revolut'`. */
+    platform: string;
+    /** Fiat currencies a buyer may use to fill this cash-out. */
+    currencies: readonly [CurrencyType, ...CurrencyType[]];
+    /** Raw handle or prepared curator data shared by every offered currency. */
+    payee: CashPayeeInput;
+    currency?: never;
 }
 interface CashoutInput {
     /**
@@ -498,8 +520,8 @@ interface CashoutInput {
         /** Relay amount mode. Omit for the recommended exact source-input flow. */
         tradeType?: 'EXACT_INPUT' | 'EXACT_OUTPUT' | 'EXPECTED_OUTPUT';
     };
-    /** Where the fiat should arrive. Multi-payout is a deliberate v1 cut. */
-    receive: CashLeg;
+    /** Where the fiat should arrive. One method may offer multiple currencies. */
+    receive: CashLeg | CashMultiCurrencyLeg;
     /** Per-order min/max override (USDC base units). */
     intentAmountRange?: {
         min: bigint;
@@ -572,6 +594,12 @@ interface PrepareResult {
         hashedOnchainIds: string[];
     };
 }
+/** Confirmed createDeposit receipt from an externally executed prepare() plan. */
+interface PreparedCashoutReceipt {
+    transactionHash: Hash;
+    status: 'success' | 'reverted';
+    logs: readonly Log[];
+}
 interface WithdrawResult {
     depositId: string;
     /** Present when expired intents had to be pruned before withdrawal. */
@@ -597,10 +625,11 @@ interface CashClient {
         includeRelaySources: true;
     }): Promise<CashCapabilities>;
     /**
-     * 0c - Raw 30-day demand and first-fill speed evidence keyed by
-     * `platform:currency`. A recommended consumer gate is `fills >= 10 &&
-     * medianFillSeconds <= 48h`; fail open to the full capability catalog when
-     * stats are unavailable or the gate would remove every pair.
+     * 0c - Raw 30-day demand and first-fill speed evidence keyed by an exact
+     * `platform:currency` pair or sorted multi-currency set. A recommended
+     * consumer gate is `fills >= 10 && medianFillSeconds <= 48h`; fail open to
+     * the full capability catalog when stats are unavailable or the gate would
+     * remove every pair.
      */
     fillStats(): Promise<CashFillStats>;
     /** Relay-only source discovery helper. */
@@ -624,6 +653,8 @@ interface CashClient {
     cashout(input: CashoutInput, opts: CashoutOptions): Promise<CashoutResult>;
     /** 2b - Unsigned path: `txs[]` for agent wallets, AA, server keys, policy layers. */
     prepare(input: CashoutInput): Promise<PrepareResult>;
+    /** Resolve an externally executed createDeposit receipt into resumable cash-out state. */
+    finalizePreparedCashout(receipt: PreparedCashoutReceipt): CashoutResult;
     /** 3 - Observe: resumable from `depositId` alone; no session state anywhere. */
     order(depositId: string): Promise<CashOrder>;
     /**
@@ -662,4 +693,4 @@ interface CashClient {
 }
 declare function createCashClient(options: CashClientOptions): CashClient;
 
-export { type CashPlatformCapability as A, type CashPreparedStepKind as B, type CashPayoutInfo as C, type CashoutInput as D, type CashoutOptions as E, type CuratorPayeeDataInput as F, type EstimateInput as G, type EstimateOptions as H, type IntentStatus as I, RECOMMENDED_MIN_CASHOUT_AMOUNT as J, type RelayOptions as K, type RelayQuoteInput as L, MIN_CASHOUT_AMOUNT as M, type RelaySourceInput as N, type OrdersOptions as O, type PrepareResult as P, type RelayTransaction as Q, type RelayExecutionResult as R, type SignerOptions as S, type TopUpResult as T, type WatchOptions as U, type WithdrawOptions as V, type WithdrawResult as W, buildCapabilities as X, createCashClient as Y, type IntentEntity as a, type CashBuyerProfile as b, type CashDepositInput as c, type CreateDepositParamsArg as d, type CashOrder as e, type CashFill as f, type CashCapabilities as g, type CashoutResult as h, type CashEstimate as i, type CashFillStats as j, type CashPreparedStep as k, type RelayQuote as l, type RelayStatus as m, type CashSourceCapabilities as n, CASH_ATTRIBUTION_CODE as o, type CashAsset as p, type CashChain as q, type CashClient as r, type CashClientOptions as s, type CashFillEta as t, type CashLeg as u, type CashNextAction as v, type CashOrderState as w, type CashPairFillStats as x, type CashPayout as y, type CashPayoutPricing as z };
+export { createCashClient as $, type CashPayout as A, type CashPayoutPricing as B, type CashPayoutInfo as C, type CashPlatformCapability as D, type CashPreparedStepKind as E, type CashoutInput as F, type CashoutOptions as G, type CuratorPayeeDataInput as H, type IntentStatus as I, type EstimateInput as J, type EstimateOptions as K, type PreparedCashoutReceipt as L, MIN_CASHOUT_AMOUNT as M, RECOMMENDED_MIN_CASHOUT_AMOUNT as N, type OrdersOptions as O, type PrepareResult as P, type RelayOptions as Q, type RelayExecutionResult as R, type RelayQuoteInput as S, type TopUpResult as T, type RelaySourceInput as U, type RelayTransaction as V, type WithdrawResult as W, type SignerOptions as X, type WatchOptions as Y, type WithdrawOptions as Z, buildCapabilities as _, type IntentEntity as a, normalizeCashPayee as a0, type CashBuyerProfile as b, type CashDepositInput as c, type CreateDepositParamsArg as d, type CashOrder as e, type CashFill as f, type CashCapabilities as g, type CashoutResult as h, type CashEstimate as i, type CashFillStats as j, type CashPreparedStep as k, type RelayQuote as l, type RelayStatus as m, type CashSourceCapabilities as n, CASH_ATTRIBUTION_CODE as o, type CashAsset as p, type CashChain as q, type CashClient as r, type CashClientOptions as s, type CashFillEta as t, type CashLeg as u, type CashMultiCurrencyLeg as v, type CashNextAction as w, type CashOrderState as x, type CashPairFillStats as y, type CashPayeeInput as z };