@zkp2p/cash 0.4.0-rc.1 → 0.4.0-rc.3

package/AGENTS.md

@@ -27,8 +27,10 @@ can withdraw an unmatched deposit.
    Base-USDC `cash_cashout` tool. Never pass `source` into `prepare()`.
 
 Every transaction (including approves) carries ERC-8021 attribution:
-`peer-cash`, then any `referrer` codes from `createCashClient` options, then
-the Base builder code.
+`peer-cash`, then optional `peer-ref-XXXXXX` from the six-character
+`referralCode`, then any analytics-only `referrer` codes, then the Base builder
+code. The namespaced referral marker gives its Peer Privy wallet the direct
+deposit-level integration share instead of applying maker L1/L2.
 
 **Two platform caveats, both surfaced in `capabilities()`:**
 
@@ -85,6 +87,19 @@ const multiCurrency = await cash.cashout(
   { signer },
 );
 
+// Widest reach: several platforms on one order (each platform at most once);
+// the buyer picks the leg they can pay, every leg at the live oracle rate.
+const multiPlatform = await cash.cashout(
+  {
+    amount: usdc(500),
+    receive: [
+      { platform: 'venmo', currency: 'USD', payee: '@handle' },
+      { platform: 'revolut', currencies: ['EUR', 'GBP'], payee: { offchainId: 'revtag' } },
+    ],
+  },
+  { signer },
+);
+
 // 4. Persist depositId ↔ your user. That row is the entire integration state.
 
 // 5. Drive the lifecycle from nextActions - no heuristics.

package/README.md

@@ -65,12 +65,50 @@ const fastFill = await cash.cashout(
   { signer },
 );
 
+// One order can also offer several platforms (each at most once). The buyer
+// picks the leg they can pay; every leg fills at the live oracle market rate.
+const widestReach = await cash.cashout(
+  {
+    amount: usdc(1000),
+    receive: [
+      { platform: 'venmo', currency: 'USD', payee: '@you' },
+      { platform: 'revolut', currencies: ['EUR', 'GBP'], payee: { offchainId: 'revtag' } },
+    ],
+  },
+  { signer },
+);
+
 for await (const order of cash.watch(depositId)) {
   console.log(order.state, order.explain());
   if (order.state === 'delivered') break;
 }
 ```
 
+## Earn the integration share
+
+Use the same six-character referral code shown in your Peer mobile or web app.
+No API key, registration transaction, or separate receiving address is needed:
+the referral code already belongs to your Peer Privy wallet.
+
+```ts
+const cash = createCashClient({
+  environment: 'production',
+  referralCode: 'ABC123',
+});
+```
+
+The SDK normalizes the value and stamps `peer-ref-ABC123` into ERC-8021
+attribution on the deposit transaction. When that liquidity is filled, Curator
+pays the code owner 50 bps, capped by the configured Peer service fee. This is
+the deposit-level integration path: it replaces the maker L1/L2 referral split
+for that deposit instead of enrolling the cashing-out user as your referee.
+
+The mapping is permanent. If you later customize your displayed Peer referral
+code, open deposits carrying the old code still pay the same wallet. Include at
+most one `peer-ref-XXXXXX` marker; an unknown or conflicting marker receives no
+integration share. The existing `referrer` option remains available for
+analytics-only ERC-8021 codes such as `acme-app`.
+
 Source asset path:
 
 ```ts
@@ -122,8 +160,9 @@ must execute and confirm its Relay route before preparing the Base-USDC
 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.
+Peer Cash transaction, including approves, carries ERC-8021 attribution:
+`peer-cash` first, optional `peer-ref-XXXXXX` from `referralCode` next, and your
+analytics-only `referrer` code(s) after it.
 
 ```ts
 const prepared = await cash.prepare({

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

@@ -87,6 +87,18 @@ var errors = {
     retryable: false,
     remediation: `Pass one or more unique currencies listed for ${platform} by capabilities().`
   }),
+  invalidPayoutPlatforms: (reason) => new CashError({
+    code: "INVALID_PAYOUT_PLATFORMS",
+    message: `The payout platform set is invalid: ${reason}.`,
+    retryable: false,
+    remediation: `Pass one payout leg, or an array of legs using each platform from capabilities() at most once.`
+  }),
+  invalidReferralCode: () => new CashError({
+    code: "INVALID_REFERRAL_CODE",
+    message: `The Peer referral code must be exactly six letters or numbers.`,
+    retryable: false,
+    remediation: `Copy your six-character referral code from the Peer mobile or web app and pass it as referralCode.`
+  }),
   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.`,

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

@@ -461,11 +461,14 @@ declare function normalizeCashPayee(platform: string, payee: CashPayeeInput): Cu
 
 /**
  * ERC-8021 attribution code stamped on every transaction this package
- * produces (signed and prepare paths, including approves). Integrator codes
- * from `CashClientOptions.referrer` are appended after it; the SDK always
- * appends the Base builder code last.
+ * produces (signed and prepare paths, including approves). The optional
+ * namespaced `CashClientOptions.referralCode` marker and analytics-only
+ * `referrer` codes follow it; the SDK appends the Base builder code last.
  */
 declare const CASH_ATTRIBUTION_CODE = "peer-cash";
+declare const CASH_REFERRAL_ATTRIBUTION_PREFIX = "peer-ref-";
+/** Convert a Peer referral code into its financially meaningful ERC-8021 marker. */
+declare function toCashReferralAttributionCode(rawCode: string): string;
 interface CashClientOptions {
     /** `'production' | 'preproduction' | 'staging'` - selects contracts, curator, and indexer. */
     environment: RuntimeEnv;
@@ -482,8 +485,14 @@ interface CashClientOptions {
     /** Relay API configuration for source assets outside Base USDC. */
     relay?: RelayOptions;
     /**
-     * Your own ERC-8021 attribution code(s), appended after
-     * {@link CASH_ATTRIBUTION_CODE} on every transaction (e.g. `'acme-app'`).
+     * Your six-character referral code from the Peer mobile or web app. The SDK
+     * emits `peer-ref-XXXXXX`; when this deposit fills, Curator routes the
+     * integration share to the Privy wallet that owns the code.
+     */
+    referralCode?: string;
+    /**
+     * Analytics-only ERC-8021 attribution code(s), appended after the Peer Cash
+     * and optional integration-referral markers (e.g. `'acme-app'`).
      */
     referrer?: string | string[];
 }
@@ -506,6 +515,8 @@ interface CashMultiCurrencyLeg {
     payee: CashPayeeInput;
     currency?: never;
 }
+/** One payout leg of a cash-out - single-currency or multi-currency. */
+type CashReceiveLeg = CashLeg | CashMultiCurrencyLeg;
 interface CashoutInput {
     /**
      * Amount to cash out. Without `source`, this is Base USDC base units. With
@@ -520,8 +531,12 @@ 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. One method may offer multiple currencies. */
-    receive: CashLeg | CashMultiCurrencyLeg;
+    /**
+     * Where the fiat should arrive. One leg, or an array of legs to offer the
+     * buyer several payout platforms (each platform at most once). One method
+     * may offer multiple currencies; every leg fills at the live oracle rate.
+     */
+    receive: CashReceiveLeg | readonly [CashReceiveLeg, ...CashReceiveLeg[]];
     /** Per-order min/max override (USDC base units). */
     intentAmountRange?: {
         min: bigint;
@@ -693,4 +708,4 @@ interface CashClient {
 }
 declare function createCashClient(options: CashClientOptions): CashClient;
 
-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 };
+export { type WithdrawOptions as $, type CashPayeeInput as A, type CashPayout as B, type CashPayoutInfo as C, type CashPayoutPricing as D, type CashPlatformCapability as E, type CashPreparedStepKind as F, type CashReceiveLeg as G, type CashoutInput as H, type IntentStatus as I, type CashoutOptions as J, type CuratorPayeeDataInput as K, type EstimateInput as L, type EstimateOptions as M, MIN_CASHOUT_AMOUNT as N, type OrdersOptions as O, type PrepareResult as P, type PreparedCashoutReceipt as Q, type RelayExecutionResult as R, RECOMMENDED_MIN_CASHOUT_AMOUNT as S, type TopUpResult as T, type RelayOptions as U, type RelayQuoteInput as V, type WithdrawResult as W, type RelaySourceInput as X, type RelayTransaction as Y, type SignerOptions as Z, type WatchOptions as _, type IntentEntity as a, buildCapabilities as a0, createCashClient as a1, normalizeCashPayee as a2, toCashReferralAttributionCode as a3, 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, CASH_REFERRAL_ATTRIBUTION_PREFIX as p, type CashAsset as q, type CashChain as r, type CashClient as s, type CashClientOptions as t, type CashFillEta as u, type CashLeg as v, type CashMultiCurrencyLeg as w, type CashNextAction as x, type CashOrderState as y, type CashPairFillStats as z };

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

@@ -461,11 +461,14 @@ declare function normalizeCashPayee(platform: string, payee: CashPayeeInput): Cu
 
 /**
  * ERC-8021 attribution code stamped on every transaction this package
- * produces (signed and prepare paths, including approves). Integrator codes
- * from `CashClientOptions.referrer` are appended after it; the SDK always
- * appends the Base builder code last.
+ * produces (signed and prepare paths, including approves). The optional
+ * namespaced `CashClientOptions.referralCode` marker and analytics-only
+ * `referrer` codes follow it; the SDK appends the Base builder code last.
  */
 declare const CASH_ATTRIBUTION_CODE = "peer-cash";
+declare const CASH_REFERRAL_ATTRIBUTION_PREFIX = "peer-ref-";
+/** Convert a Peer referral code into its financially meaningful ERC-8021 marker. */
+declare function toCashReferralAttributionCode(rawCode: string): string;
 interface CashClientOptions {
     /** `'production' | 'preproduction' | 'staging'` - selects contracts, curator, and indexer. */
     environment: RuntimeEnv;
@@ -482,8 +485,14 @@ interface CashClientOptions {
     /** Relay API configuration for source assets outside Base USDC. */
     relay?: RelayOptions;
     /**
-     * Your own ERC-8021 attribution code(s), appended after
-     * {@link CASH_ATTRIBUTION_CODE} on every transaction (e.g. `'acme-app'`).
+     * Your six-character referral code from the Peer mobile or web app. The SDK
+     * emits `peer-ref-XXXXXX`; when this deposit fills, Curator routes the
+     * integration share to the Privy wallet that owns the code.
+     */
+    referralCode?: string;
+    /**
+     * Analytics-only ERC-8021 attribution code(s), appended after the Peer Cash
+     * and optional integration-referral markers (e.g. `'acme-app'`).
      */
     referrer?: string | string[];
 }
@@ -506,6 +515,8 @@ interface CashMultiCurrencyLeg {
     payee: CashPayeeInput;
     currency?: never;
 }
+/** One payout leg of a cash-out - single-currency or multi-currency. */
+type CashReceiveLeg = CashLeg | CashMultiCurrencyLeg;
 interface CashoutInput {
     /**
      * Amount to cash out. Without `source`, this is Base USDC base units. With
@@ -520,8 +531,12 @@ 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. One method may offer multiple currencies. */
-    receive: CashLeg | CashMultiCurrencyLeg;
+    /**
+     * Where the fiat should arrive. One leg, or an array of legs to offer the
+     * buyer several payout platforms (each platform at most once). One method
+     * may offer multiple currencies; every leg fills at the live oracle rate.
+     */
+    receive: CashReceiveLeg | readonly [CashReceiveLeg, ...CashReceiveLeg[]];
     /** Per-order min/max override (USDC base units). */
     intentAmountRange?: {
         min: bigint;
@@ -693,4 +708,4 @@ interface CashClient {
 }
 declare function createCashClient(options: CashClientOptions): CashClient;
 
-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 };
+export { type WithdrawOptions as $, type CashPayeeInput as A, type CashPayout as B, type CashPayoutInfo as C, type CashPayoutPricing as D, type CashPlatformCapability as E, type CashPreparedStepKind as F, type CashReceiveLeg as G, type CashoutInput as H, type IntentStatus as I, type CashoutOptions as J, type CuratorPayeeDataInput as K, type EstimateInput as L, type EstimateOptions as M, MIN_CASHOUT_AMOUNT as N, type OrdersOptions as O, type PrepareResult as P, type PreparedCashoutReceipt as Q, type RelayExecutionResult as R, RECOMMENDED_MIN_CASHOUT_AMOUNT as S, type TopUpResult as T, type RelayOptions as U, type RelayQuoteInput as V, type WithdrawResult as W, type RelaySourceInput as X, type RelayTransaction as Y, type SignerOptions as Z, type WatchOptions as _, type IntentEntity as a, buildCapabilities as a0, createCashClient as a1, normalizeCashPayee as a2, toCashReferralAttributionCode as a3, 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, CASH_REFERRAL_ATTRIBUTION_PREFIX as p, type CashAsset as q, type CashChain as r, type CashClient as s, type CashClientOptions as t, type CashFillEta as u, type CashLeg as v, type CashMultiCurrencyLeg as w, type CashNextAction as x, type CashOrderState as y, type CashPairFillStats as z };

package/dist/index.cjs

@@ -463,6 +463,9 @@ var PAYEE_HINTS = {
   n26: "MoneyBeam email or phone number"
 };
 var IDENTITY_ATTESTATION_PLATFORMS = /* @__PURE__ */ new Set(["wise", "paypal"]);
+function platformRequiresIdentityAttestation(platform) {
+  return IDENTITY_ATTESTATION_PLATFORMS.has(platform);
+}
 function buildCapabilities(environment) {
   const catalog = sdk.getPaymentMethodsCatalog(BASE_CHAIN_ID, environment);
   const platforms = Object.entries(catalog).map(([platform, entry]) => {
@@ -565,6 +568,18 @@ var errors = {
     retryable: false,
     remediation: `Pass one or more unique currencies listed for ${platform} by capabilities().`
   }),
+  invalidPayoutPlatforms: (reason) => new CashError({
+    code: "INVALID_PAYOUT_PLATFORMS",
+    message: `The payout platform set is invalid: ${reason}.`,
+    retryable: false,
+    remediation: `Pass one payout leg, or an array of legs using each platform from capabilities() at most once.`
+  }),
+  invalidReferralCode: () => new CashError({
+    code: "INVALID_REFERRAL_CODE",
+    message: `The Peer referral code must be exactly six letters or numbers.`,
+    retryable: false,
+    remediation: `Copy your six-character referral code from the Peer mobile or web app and pass it as referralCode.`
+  }),
   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.`,
@@ -1666,6 +1681,13 @@ function normalizeCashPayee(platform, payee) {
 var DEFAULT_RPC_URL = "https://mainnet.base.org";
 var FILL_STATS_CACHE_MS = 15 * 60 * 1e3;
 var CASH_ATTRIBUTION_CODE = "peer-cash";
+var CASH_REFERRAL_ATTRIBUTION_PREFIX = "peer-ref-";
+var PEER_REFERRAL_CODE_RE = /^[A-Z0-9]{6}$/;
+function toCashReferralAttributionCode(rawCode) {
+  const code = rawCode.trim().toUpperCase();
+  if (!PEER_REFERRAL_CODE_RE.test(code)) throw errors.invalidReferralCode();
+  return `${CASH_REFERRAL_ATTRIBUTION_PREFIX}${code}`;
+}
 var DEFAULT_CURATOR_URLS = {
   preproduction: "https://api-preprod.zkp2p.xyz",
   staging: "https://api-staging.zkp2p.xyz"
@@ -1743,6 +1765,7 @@ function createCashClient(options) {
   const transport = options.transport ?? viem.http(options.rpcUrl ?? DEFAULT_RPC_URL);
   const referrerCodes = [
     CASH_ATTRIBUTION_CODE,
+    ...options.referralCode === void 0 ? [] : [toCashReferralAttributionCode(options.referralCode)],
     ...options.referrer === void 0 ? [] : Array.isArray(options.referrer) ? options.referrer : [options.referrer]
   ];
   const attribution = { referrer: referrerCodes };
@@ -1791,41 +1814,51 @@ function createCashClient(options) {
     return client;
   }
   function validatePayout(input) {
-    const { receive } = input;
-    const platform = buildCapabilities(environment).platforms.find(
-      (capability) => capability.platform === receive.platform
-    );
-    if (!platform) throw errors.unsupportedPlatform(receive.platform);
-    if (receive.currency === void 0 === (receive.currencies === void 0)) {
-      throw errors.invalidPayoutCurrencies(
-        receive.platform,
-        "pass exactly one of currency or currencies"
-      );
-    }
-    const currencies = receive.currencies !== void 0 ? [...receive.currencies] : [receive.currency];
-    if (currencies.length === 0) {
-      throw errors.invalidPayoutCurrencies(receive.platform, "at least one currency is required");
-    }
-    if (new Set(currencies).size !== currencies.length) {
-      throw errors.invalidPayoutCurrencies(receive.platform, "currencies must be unique");
+    const legs = Array.isArray(input.receive) ? input.receive : [input.receive];
+    if (legs.length === 0) {
+      throw errors.invalidPayoutPlatforms("at least one payout leg is required");
     }
-    for (const currency of currencies) {
-      if (!isMarketRateSupported(currency)) {
-        throw errors.oracleUnsupportedCurrency(currency);
+    const capabilities2 = buildCapabilities(environment);
+    const seenPlatforms = /* @__PURE__ */ new Set();
+    const payouts = legs.map((leg) => {
+      const platform = capabilities2.platforms.find(
+        (capability) => capability.platform === leg.platform
+      );
+      if (!platform) throw errors.unsupportedPlatform(leg.platform);
+      if (seenPlatforms.has(leg.platform)) {
+        throw errors.invalidPayoutPlatforms(
+          `${leg.platform} appears more than once - each platform may carry one leg`
+        );
       }
-      if (!platform.currencies.includes(currency)) {
-        throw errors.unsupportedPlatformCurrency(receive.platform, currency);
+      seenPlatforms.add(leg.platform);
+      if (leg.currency === void 0 === (leg.currencies === void 0)) {
+        throw errors.invalidPayoutCurrencies(
+          leg.platform,
+          "pass exactly one of currency or currencies"
+        );
       }
-    }
-    return {
-      payouts: [
-        {
-          processorName: receive.platform,
-          ...currencies.length === 1 ? { currency: currencies[0] } : { currencies },
-          payeeData: normalizeCashPayee(receive.platform, receive.payee)
+      const currencies = leg.currencies !== void 0 ? [...leg.currencies] : [leg.currency];
+      if (currencies.length === 0) {
+        throw errors.invalidPayoutCurrencies(leg.platform, "at least one currency is required");
+      }
+      if (new Set(currencies).size !== currencies.length) {
+        throw errors.invalidPayoutCurrencies(leg.platform, "currencies must be unique");
+      }
+      for (const currency of currencies) {
+        if (!isMarketRateSupported(currency)) {
+          throw errors.oracleUnsupportedCurrency(currency);
         }
-      ]
-    };
+        if (!platform.currencies.includes(currency)) {
+          throw errors.unsupportedPlatformCurrency(leg.platform, currency);
+        }
+      }
+      return {
+        processorName: leg.platform,
+        ...currencies.length === 1 ? { currency: currencies[0] } : { currencies },
+        payeeData: normalizeCashPayee(leg.platform, leg.payee)
+      };
+    });
+    return { payouts };
   }
   function validateDepositInput(amount, input, payoutInput = validatePayout(input)) {
     if (amount < MIN_CASHOUT_AMOUNT) {
@@ -1842,12 +1875,7 @@ function createCashClient(options) {
     };
   }
   function isCashPayoutSet(payouts) {
-    const first = payouts[0];
-    return Boolean(
-      first && payouts.every(
-        (payout) => payout.platformHash.toLowerCase() === first.platformHash.toLowerCase() && payout.payeeHash.toLowerCase() === first.payeeHash.toLowerCase() && payout.pricing.marketRate && payout.pricing.spreadBps === 0
-      )
-    );
+    return payouts.length > 0 && payouts.every((payout) => payout.pricing.marketRate && payout.pricing.spreadBps === 0);
   }
   async function buildDepositParams(client, depositInput) {
     try {
@@ -1856,7 +1884,8 @@ function createCashClient(options) {
       if (isCashError(err)) throw err;
       const message = err instanceof Error ? err.message : String(err);
       if (/identityAttestation is required|identity attestation/i.test(message)) {
-        const platform = depositInput.payouts[0]?.processorName ?? "this platform";
+        const platforms = depositInput.payouts.map((payout) => payout.processorName);
+        const platform = platforms.find(platformRequiresIdentityAttestation) ?? platforms[0] ?? "this platform";
         throw errors.payeeVerificationRequired(platform, err);
       }
       throw errors.payeeRegistrationFailed(err);
@@ -2865,6 +2894,8 @@ var CASH_ERROR_CODES = defineCashErrorCodes([
   "AMOUNT_BELOW_MINIMUM",
   "INVALID_INTENT_AMOUNT_RANGE",
   "INVALID_PAYOUT_CURRENCIES",
+  "INVALID_PAYOUT_PLATFORMS",
+  "INVALID_REFERRAL_CODE",
   "ACTIVE_INTENT_BLOCKS_WITHDRAWAL",
   "NOTHING_TO_WITHDRAW",
   "INSUFFICIENT_AVAILABLE_FUNDS",
@@ -3352,6 +3383,7 @@ exports.BASE_USDC_ADDRESS = BASE_USDC_ADDRESS;
 exports.CASH_ATTRIBUTION_CODE = CASH_ATTRIBUTION_CODE;
 exports.CASH_ORDER_POLL_INTERVAL_MS = CASH_ORDER_POLL_INTERVAL_MS;
 exports.CASH_ORDER_STATUSES = CASH_ORDER_STATUSES;
+exports.CASH_REFERRAL_ATTRIBUTION_PREFIX = CASH_REFERRAL_ATTRIBUTION_PREFIX;
 exports.CASH_RETAIN_ON_EMPTY = CASH_RETAIN_ON_EMPTY;
 exports.CashError = CashError;
 exports.MARKET_SPREAD_BPS = MARKET_SPREAD_BPS;
@@ -3440,6 +3472,7 @@ exports.relayTransactionsJsonSchema = relayTransactionsJsonSchema;
 exports.resolveCashDepositId = resolveCashDepositId;
 exports.sourceCapabilitiesFromJson = sourceCapabilitiesFromJson;
 exports.sourceCapabilitiesToJson = sourceCapabilitiesToJson;
+exports.toCashReferralAttributionCode = toCashReferralAttributionCode;
 exports.topUpResultFromJson = topUpResultFromJson;
 exports.topUpResultJsonSchema = topUpResultJsonSchema;
 exports.topUpResultToJson = topUpResultToJson;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { I as IntentStatus, C as CashPayoutInfo, a as IntentEntity, b as CashBuyerProfile, c as CashDepositInput, d as CreateDepositParamsArg, e as CashOrder, f as CashFill, g as CashCapabilities, h as CashoutResult, i as CashEstimate, j as CashFillStats, P as PrepareResult, k as CashPreparedStep, R as RelayExecutionResult, l as RelayQuote, m as RelayStatus, n as CashSourceCapabilities, T as TopUpResult, W as WithdrawResult } from './createCashClient-DGMd8Swr.cjs';
-export { o as CASH_ATTRIBUTION_CODE, p as CashAsset, q as CashChain, r as CashClient, s as CashClientOptions, t as CashFillEta, u as CashLeg, v as CashMultiCurrencyLeg, w as CashNextAction, x as CashOrderState, y as CashPairFillStats, z as CashPayeeInput, A as CashPayout, B as CashPayoutPricing, D as CashPlatformCapability, E as CashPreparedStepKind, F as CashoutInput, G as CashoutOptions, H as CuratorPayeeDataInput, J as EstimateInput, K as EstimateOptions, M as MIN_CASHOUT_AMOUNT, O as OrdersOptions, L as PreparedCashoutReceipt, N as RECOMMENDED_MIN_CASHOUT_AMOUNT, Q as RelayOptions, S as RelayQuoteInput, U as RelaySourceInput, V as RelayTransaction, X as SignerOptions, Y as WatchOptions, Z as WithdrawOptions, _ as buildCapabilities, $ as createCashClient, a0 as normalizeCashPayee } from './createCashClient-DGMd8Swr.cjs';
+import { I as IntentStatus, C as CashPayoutInfo, a as IntentEntity, b as CashBuyerProfile, c as CashDepositInput, d as CreateDepositParamsArg, e as CashOrder, f as CashFill, g as CashCapabilities, h as CashoutResult, i as CashEstimate, j as CashFillStats, P as PrepareResult, k as CashPreparedStep, R as RelayExecutionResult, l as RelayQuote, m as RelayStatus, n as CashSourceCapabilities, T as TopUpResult, W as WithdrawResult } from './createCashClient-CYSM84-K.cjs';
+export { o as CASH_ATTRIBUTION_CODE, p as CASH_REFERRAL_ATTRIBUTION_PREFIX, q as CashAsset, r as CashChain, s as CashClient, t as CashClientOptions, u as CashFillEta, v as CashLeg, w as CashMultiCurrencyLeg, x as CashNextAction, y as CashOrderState, z as CashPairFillStats, A as CashPayeeInput, B as CashPayout, D as CashPayoutPricing, E as CashPlatformCapability, F as CashPreparedStepKind, G as CashReceiveLeg, H as CashoutInput, J as CashoutOptions, K as CuratorPayeeDataInput, L as EstimateInput, M as EstimateOptions, N as MIN_CASHOUT_AMOUNT, O as OrdersOptions, Q as PreparedCashoutReceipt, S as RECOMMENDED_MIN_CASHOUT_AMOUNT, U as RelayOptions, V as RelayQuoteInput, X as RelaySourceInput, Y as RelayTransaction, Z as SignerOptions, _ as WatchOptions, $ as WithdrawOptions, a0 as buildCapabilities, a1 as createCashClient, a2 as normalizeCashPayee, a3 as toCashReferralAttributionCode } from './createCashClient-CYSM84-K.cjs';
 import { PaymentMethodCatalog, CurrencyType, OracleAdapterOverrides, OnchainCurrency, Zkp2pClient, PreparedTransaction } from '@zkp2p/sdk';
 export { CurrencyType, PreparedTransaction, RuntimeEnv } from '@zkp2p/sdk';
 import { Log, Abi } from 'viem';
@@ -10,7 +10,7 @@ import '@relayprotocol/relay-sdk';
  * Typed errors - every failure carries a `code`, whether it is `retryable`,
  * and a `remediation` sentence so agents can self-drive recovery.
  */
-type CashErrorCode = 'ORACLE_UNSUPPORTED_CURRENCY' | 'ORACLE_READ_FAILED' | 'UNSUPPORTED_PLATFORM' | 'UNSUPPORTED_PLATFORM_CURRENCY' | 'AMOUNT_BELOW_MINIMUM' | 'INVALID_INTENT_AMOUNT_RANGE' | 'INVALID_PAYOUT_CURRENCIES' | 'ACTIVE_INTENT_BLOCKS_WITHDRAWAL' | 'NOTHING_TO_WITHDRAW' | 'INSUFFICIENT_AVAILABLE_FUNDS' | 'INSUFFICIENT_TOKEN_BALANCE' | 'ORDER_NOT_ACTIVE' | 'INVALID_DEPOSIT_ID' | 'ESCROW_PAUSED' | 'INDEXER_LAG' | 'INDEXER_UNAVAILABLE' | 'ORDER_NOT_FOUND' | 'PAYEE_REGISTRATION_FAILED' | 'PAYEE_VERIFICATION_REQUIRED' | 'SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE' | 'SOURCE_RECIPIENT_MISMATCH' | 'SOURCE_CAPABILITIES_FAILED' | 'SOURCE_QUOTE_FAILED' | 'SOURCE_NONCE_MANAGER_REQUIRED' | 'SOURCE_EXECUTION_FAILED' | 'SOURCE_STATUS_FAILED' | 'SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED' | 'SOURCE_CASHOUT_SUBMISSION_UNKNOWN' | 'SOURCE_CASHOUT_STATUS_UNKNOWN' | 'DEPOSIT_RESOLUTION_FAILED' | 'ALLOWANCE_NOT_VISIBLE' | 'SIGNER_REQUIRED' | 'SIGNER_CHAIN_MISMATCH' | 'SIGNER_CHAIN_UNAVAILABLE' | 'WATCH_TIMEOUT' | 'TRANSACTION_REJECTED' | 'TRANSACTION_FAILED' | 'TRANSACTION_SUBMISSION_UNKNOWN' | 'TRANSACTION_STATUS_UNKNOWN';
+type CashErrorCode = 'ORACLE_UNSUPPORTED_CURRENCY' | 'ORACLE_READ_FAILED' | 'UNSUPPORTED_PLATFORM' | 'UNSUPPORTED_PLATFORM_CURRENCY' | 'AMOUNT_BELOW_MINIMUM' | 'INVALID_INTENT_AMOUNT_RANGE' | 'INVALID_PAYOUT_CURRENCIES' | 'INVALID_PAYOUT_PLATFORMS' | 'INVALID_REFERRAL_CODE' | 'ACTIVE_INTENT_BLOCKS_WITHDRAWAL' | 'NOTHING_TO_WITHDRAW' | 'INSUFFICIENT_AVAILABLE_FUNDS' | 'INSUFFICIENT_TOKEN_BALANCE' | 'ORDER_NOT_ACTIVE' | 'INVALID_DEPOSIT_ID' | 'ESCROW_PAUSED' | 'INDEXER_LAG' | 'INDEXER_UNAVAILABLE' | 'ORDER_NOT_FOUND' | 'PAYEE_REGISTRATION_FAILED' | 'PAYEE_VERIFICATION_REQUIRED' | 'SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE' | 'SOURCE_RECIPIENT_MISMATCH' | 'SOURCE_CAPABILITIES_FAILED' | 'SOURCE_QUOTE_FAILED' | 'SOURCE_NONCE_MANAGER_REQUIRED' | 'SOURCE_EXECUTION_FAILED' | 'SOURCE_STATUS_FAILED' | 'SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED' | 'SOURCE_CASHOUT_SUBMISSION_UNKNOWN' | 'SOURCE_CASHOUT_STATUS_UNKNOWN' | 'DEPOSIT_RESOLUTION_FAILED' | 'ALLOWANCE_NOT_VISIBLE' | 'SIGNER_REQUIRED' | 'SIGNER_CHAIN_MISMATCH' | 'SIGNER_CHAIN_UNAVAILABLE' | 'WATCH_TIMEOUT' | 'TRANSACTION_REJECTED' | 'TRANSACTION_FAILED' | 'TRANSACTION_SUBMISSION_UNKNOWN' | 'TRANSACTION_STATUS_UNKNOWN';
 interface CashErrorShape {
     code: CashErrorCode;
     message: string;
@@ -78,6 +78,8 @@ declare const errors: {
     amountBelowMinimum: (amount: bigint, min: bigint) => CashError;
     invalidIntentAmountRange: (amount: bigint, min: bigint, max: bigint) => CashError;
     invalidPayoutCurrencies: (platform: string, reason: string) => CashError;
+    invalidPayoutPlatforms: (reason: string) => CashError;
+    invalidReferralCode: () => CashError;
     activeIntentBlocksWithdrawal: (depositId: string) => CashError;
     insufficientAvailableFunds: (depositId: string, requested: bigint, available: bigint) => CashError;
     insufficientTokenBalance: (requiredAmount?: bigint) => CashError;
@@ -223,9 +225,9 @@ interface MethodCurrencyLike {
 /**
  * Decode a deposit's payment methods + currency tuples into payout legs.
  * Pure - the environment arrives via the catalog. One leg per
- * (method, currency) pair; cash orders create exactly one in v1. If any
- * method is absent from the active catalog, reject the whole set instead of
- * partially reclassifying a mixed historical deposit.
+ * (method, currency) pair; a cash order carries one or several platforms. If
+ * any method is absent from the active catalog, reject the whole set instead
+ * of partially reclassifying a mixed historical deposit.
  */
 declare function derivePayouts(paymentMethods: ReadonlyArray<PaymentMethodLike>, currencies: ReadonlyArray<MethodCurrencyLike>, catalog: PaymentMethodCatalog): CashPayoutInfo[];
 
@@ -3184,7 +3186,7 @@ declare const cashErrorRecoveryJsonSchema: z.ZodDiscriminatedUnion<"kind", [z.Zo
     operation: string;
 }>]>;
 declare const cashErrorJsonSchema: z.ZodObject<{
-    code: z.ZodEnum<["ORACLE_UNSUPPORTED_CURRENCY", "ORACLE_READ_FAILED", "UNSUPPORTED_PLATFORM", "UNSUPPORTED_PLATFORM_CURRENCY", "AMOUNT_BELOW_MINIMUM", "INVALID_INTENT_AMOUNT_RANGE", "INVALID_PAYOUT_CURRENCIES", "ACTIVE_INTENT_BLOCKS_WITHDRAWAL", "NOTHING_TO_WITHDRAW", "INSUFFICIENT_AVAILABLE_FUNDS", "INSUFFICIENT_TOKEN_BALANCE", "ORDER_NOT_ACTIVE", "INVALID_DEPOSIT_ID", "ESCROW_PAUSED", "INDEXER_LAG", "INDEXER_UNAVAILABLE", "ORDER_NOT_FOUND", "PAYEE_REGISTRATION_FAILED", "PAYEE_VERIFICATION_REQUIRED", "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE", "SOURCE_RECIPIENT_MISMATCH", "SOURCE_CAPABILITIES_FAILED", "SOURCE_QUOTE_FAILED", "SOURCE_NONCE_MANAGER_REQUIRED", "SOURCE_EXECUTION_FAILED", "SOURCE_STATUS_FAILED", "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED", "SOURCE_CASHOUT_SUBMISSION_UNKNOWN", "SOURCE_CASHOUT_STATUS_UNKNOWN", "DEPOSIT_RESOLUTION_FAILED", "ALLOWANCE_NOT_VISIBLE", "SIGNER_REQUIRED", "SIGNER_CHAIN_MISMATCH", "SIGNER_CHAIN_UNAVAILABLE", "WATCH_TIMEOUT", "TRANSACTION_REJECTED", "TRANSACTION_FAILED", "TRANSACTION_SUBMISSION_UNKNOWN", "TRANSACTION_STATUS_UNKNOWN"]>;
+    code: z.ZodEnum<["ORACLE_UNSUPPORTED_CURRENCY", "ORACLE_READ_FAILED", "UNSUPPORTED_PLATFORM", "UNSUPPORTED_PLATFORM_CURRENCY", "AMOUNT_BELOW_MINIMUM", "INVALID_INTENT_AMOUNT_RANGE", "INVALID_PAYOUT_CURRENCIES", "INVALID_PAYOUT_PLATFORMS", "INVALID_REFERRAL_CODE", "ACTIVE_INTENT_BLOCKS_WITHDRAWAL", "NOTHING_TO_WITHDRAW", "INSUFFICIENT_AVAILABLE_FUNDS", "INSUFFICIENT_TOKEN_BALANCE", "ORDER_NOT_ACTIVE", "INVALID_DEPOSIT_ID", "ESCROW_PAUSED", "INDEXER_LAG", "INDEXER_UNAVAILABLE", "ORDER_NOT_FOUND", "PAYEE_REGISTRATION_FAILED", "PAYEE_VERIFICATION_REQUIRED", "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE", "SOURCE_RECIPIENT_MISMATCH", "SOURCE_CAPABILITIES_FAILED", "SOURCE_QUOTE_FAILED", "SOURCE_NONCE_MANAGER_REQUIRED", "SOURCE_EXECUTION_FAILED", "SOURCE_STATUS_FAILED", "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED", "SOURCE_CASHOUT_SUBMISSION_UNKNOWN", "SOURCE_CASHOUT_STATUS_UNKNOWN", "DEPOSIT_RESOLUTION_FAILED", "ALLOWANCE_NOT_VISIBLE", "SIGNER_REQUIRED", "SIGNER_CHAIN_MISMATCH", "SIGNER_CHAIN_UNAVAILABLE", "WATCH_TIMEOUT", "TRANSACTION_REJECTED", "TRANSACTION_FAILED", "TRANSACTION_SUBMISSION_UNKNOWN", "TRANSACTION_STATUS_UNKNOWN"]>;
     message: z.ZodString;
     retryable: z.ZodBoolean;
     remediation: z.ZodString;
@@ -3571,7 +3573,7 @@ declare const cashErrorJsonSchema: z.ZodObject<{
     }>]>>;
 }, "strict", z.ZodTypeAny, {
     message: string;
-    code: "ORACLE_UNSUPPORTED_CURRENCY" | "ORACLE_READ_FAILED" | "UNSUPPORTED_PLATFORM" | "UNSUPPORTED_PLATFORM_CURRENCY" | "AMOUNT_BELOW_MINIMUM" | "INVALID_INTENT_AMOUNT_RANGE" | "INVALID_PAYOUT_CURRENCIES" | "ACTIVE_INTENT_BLOCKS_WITHDRAWAL" | "NOTHING_TO_WITHDRAW" | "INSUFFICIENT_AVAILABLE_FUNDS" | "INSUFFICIENT_TOKEN_BALANCE" | "ORDER_NOT_ACTIVE" | "INVALID_DEPOSIT_ID" | "ESCROW_PAUSED" | "INDEXER_LAG" | "INDEXER_UNAVAILABLE" | "ORDER_NOT_FOUND" | "PAYEE_REGISTRATION_FAILED" | "PAYEE_VERIFICATION_REQUIRED" | "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE" | "SOURCE_RECIPIENT_MISMATCH" | "SOURCE_CAPABILITIES_FAILED" | "SOURCE_QUOTE_FAILED" | "SOURCE_NONCE_MANAGER_REQUIRED" | "SOURCE_EXECUTION_FAILED" | "SOURCE_STATUS_FAILED" | "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED" | "SOURCE_CASHOUT_SUBMISSION_UNKNOWN" | "SOURCE_CASHOUT_STATUS_UNKNOWN" | "DEPOSIT_RESOLUTION_FAILED" | "ALLOWANCE_NOT_VISIBLE" | "SIGNER_REQUIRED" | "SIGNER_CHAIN_MISMATCH" | "SIGNER_CHAIN_UNAVAILABLE" | "WATCH_TIMEOUT" | "TRANSACTION_REJECTED" | "TRANSACTION_FAILED" | "TRANSACTION_SUBMISSION_UNKNOWN" | "TRANSACTION_STATUS_UNKNOWN";
+    code: "ORACLE_UNSUPPORTED_CURRENCY" | "ORACLE_READ_FAILED" | "UNSUPPORTED_PLATFORM" | "UNSUPPORTED_PLATFORM_CURRENCY" | "AMOUNT_BELOW_MINIMUM" | "INVALID_INTENT_AMOUNT_RANGE" | "INVALID_PAYOUT_CURRENCIES" | "INVALID_PAYOUT_PLATFORMS" | "INVALID_REFERRAL_CODE" | "ACTIVE_INTENT_BLOCKS_WITHDRAWAL" | "NOTHING_TO_WITHDRAW" | "INSUFFICIENT_AVAILABLE_FUNDS" | "INSUFFICIENT_TOKEN_BALANCE" | "ORDER_NOT_ACTIVE" | "INVALID_DEPOSIT_ID" | "ESCROW_PAUSED" | "INDEXER_LAG" | "INDEXER_UNAVAILABLE" | "ORDER_NOT_FOUND" | "PAYEE_REGISTRATION_FAILED" | "PAYEE_VERIFICATION_REQUIRED" | "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE" | "SOURCE_RECIPIENT_MISMATCH" | "SOURCE_CAPABILITIES_FAILED" | "SOURCE_QUOTE_FAILED" | "SOURCE_NONCE_MANAGER_REQUIRED" | "SOURCE_EXECUTION_FAILED" | "SOURCE_STATUS_FAILED" | "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED" | "SOURCE_CASHOUT_SUBMISSION_UNKNOWN" | "SOURCE_CASHOUT_STATUS_UNKNOWN" | "DEPOSIT_RESOLUTION_FAILED" | "ALLOWANCE_NOT_VISIBLE" | "SIGNER_REQUIRED" | "SIGNER_CHAIN_MISMATCH" | "SIGNER_CHAIN_UNAVAILABLE" | "WATCH_TIMEOUT" | "TRANSACTION_REJECTED" | "TRANSACTION_FAILED" | "TRANSACTION_SUBMISSION_UNKNOWN" | "TRANSACTION_STATUS_UNKNOWN";
     retryable: boolean;
     remediation: string;
     recovery?: {
@@ -3653,7 +3655,7 @@ declare const cashErrorJsonSchema: z.ZodObject<{
     } | undefined;
 }, {
     message: string;
-    code: "ORACLE_UNSUPPORTED_CURRENCY" | "ORACLE_READ_FAILED" | "UNSUPPORTED_PLATFORM" | "UNSUPPORTED_PLATFORM_CURRENCY" | "AMOUNT_BELOW_MINIMUM" | "INVALID_INTENT_AMOUNT_RANGE" | "INVALID_PAYOUT_CURRENCIES" | "ACTIVE_INTENT_BLOCKS_WITHDRAWAL" | "NOTHING_TO_WITHDRAW" | "INSUFFICIENT_AVAILABLE_FUNDS" | "INSUFFICIENT_TOKEN_BALANCE" | "ORDER_NOT_ACTIVE" | "INVALID_DEPOSIT_ID" | "ESCROW_PAUSED" | "INDEXER_LAG" | "INDEXER_UNAVAILABLE" | "ORDER_NOT_FOUND" | "PAYEE_REGISTRATION_FAILED" | "PAYEE_VERIFICATION_REQUIRED" | "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE" | "SOURCE_RECIPIENT_MISMATCH" | "SOURCE_CAPABILITIES_FAILED" | "SOURCE_QUOTE_FAILED" | "SOURCE_NONCE_MANAGER_REQUIRED" | "SOURCE_EXECUTION_FAILED" | "SOURCE_STATUS_FAILED" | "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED" | "SOURCE_CASHOUT_SUBMISSION_UNKNOWN" | "SOURCE_CASHOUT_STATUS_UNKNOWN" | "DEPOSIT_RESOLUTION_FAILED" | "ALLOWANCE_NOT_VISIBLE" | "SIGNER_REQUIRED" | "SIGNER_CHAIN_MISMATCH" | "SIGNER_CHAIN_UNAVAILABLE" | "WATCH_TIMEOUT" | "TRANSACTION_REJECTED" | "TRANSACTION_FAILED" | "TRANSACTION_SUBMISSION_UNKNOWN" | "TRANSACTION_STATUS_UNKNOWN";
+    code: "ORACLE_UNSUPPORTED_CURRENCY" | "ORACLE_READ_FAILED" | "UNSUPPORTED_PLATFORM" | "UNSUPPORTED_PLATFORM_CURRENCY" | "AMOUNT_BELOW_MINIMUM" | "INVALID_INTENT_AMOUNT_RANGE" | "INVALID_PAYOUT_CURRENCIES" | "INVALID_PAYOUT_PLATFORMS" | "INVALID_REFERRAL_CODE" | "ACTIVE_INTENT_BLOCKS_WITHDRAWAL" | "NOTHING_TO_WITHDRAW" | "INSUFFICIENT_AVAILABLE_FUNDS" | "INSUFFICIENT_TOKEN_BALANCE" | "ORDER_NOT_ACTIVE" | "INVALID_DEPOSIT_ID" | "ESCROW_PAUSED" | "INDEXER_LAG" | "INDEXER_UNAVAILABLE" | "ORDER_NOT_FOUND" | "PAYEE_REGISTRATION_FAILED" | "PAYEE_VERIFICATION_REQUIRED" | "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE" | "SOURCE_RECIPIENT_MISMATCH" | "SOURCE_CAPABILITIES_FAILED" | "SOURCE_QUOTE_FAILED" | "SOURCE_NONCE_MANAGER_REQUIRED" | "SOURCE_EXECUTION_FAILED" | "SOURCE_STATUS_FAILED" | "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED" | "SOURCE_CASHOUT_SUBMISSION_UNKNOWN" | "SOURCE_CASHOUT_STATUS_UNKNOWN" | "DEPOSIT_RESOLUTION_FAILED" | "ALLOWANCE_NOT_VISIBLE" | "SIGNER_REQUIRED" | "SIGNER_CHAIN_MISMATCH" | "SIGNER_CHAIN_UNAVAILABLE" | "WATCH_TIMEOUT" | "TRANSACTION_REJECTED" | "TRANSACTION_FAILED" | "TRANSACTION_SUBMISSION_UNKNOWN" | "TRANSACTION_STATUS_UNKNOWN";
     retryable: boolean;
     remediation: string;
     recovery?: {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { I as IntentStatus, C as CashPayoutInfo, a as IntentEntity, b as CashBuyerProfile, c as CashDepositInput, d as CreateDepositParamsArg, e as CashOrder, f as CashFill, g as CashCapabilities, h as CashoutResult, i as CashEstimate, j as CashFillStats, P as PrepareResult, k as CashPreparedStep, R as RelayExecutionResult, l as RelayQuote, m as RelayStatus, n as CashSourceCapabilities, T as TopUpResult, W as WithdrawResult } from './createCashClient-DGMd8Swr.js';
-export { o as CASH_ATTRIBUTION_CODE, p as CashAsset, q as CashChain, r as CashClient, s as CashClientOptions, t as CashFillEta, u as CashLeg, v as CashMultiCurrencyLeg, w as CashNextAction, x as CashOrderState, y as CashPairFillStats, z as CashPayeeInput, A as CashPayout, B as CashPayoutPricing, D as CashPlatformCapability, E as CashPreparedStepKind, F as CashoutInput, G as CashoutOptions, H as CuratorPayeeDataInput, J as EstimateInput, K as EstimateOptions, M as MIN_CASHOUT_AMOUNT, O as OrdersOptions, L as PreparedCashoutReceipt, N as RECOMMENDED_MIN_CASHOUT_AMOUNT, Q as RelayOptions, S as RelayQuoteInput, U as RelaySourceInput, V as RelayTransaction, X as SignerOptions, Y as WatchOptions, Z as WithdrawOptions, _ as buildCapabilities, $ as createCashClient, a0 as normalizeCashPayee } from './createCashClient-DGMd8Swr.js';
+import { I as IntentStatus, C as CashPayoutInfo, a as IntentEntity, b as CashBuyerProfile, c as CashDepositInput, d as CreateDepositParamsArg, e as CashOrder, f as CashFill, g as CashCapabilities, h as CashoutResult, i as CashEstimate, j as CashFillStats, P as PrepareResult, k as CashPreparedStep, R as RelayExecutionResult, l as RelayQuote, m as RelayStatus, n as CashSourceCapabilities, T as TopUpResult, W as WithdrawResult } from './createCashClient-CYSM84-K.js';
+export { o as CASH_ATTRIBUTION_CODE, p as CASH_REFERRAL_ATTRIBUTION_PREFIX, q as CashAsset, r as CashChain, s as CashClient, t as CashClientOptions, u as CashFillEta, v as CashLeg, w as CashMultiCurrencyLeg, x as CashNextAction, y as CashOrderState, z as CashPairFillStats, A as CashPayeeInput, B as CashPayout, D as CashPayoutPricing, E as CashPlatformCapability, F as CashPreparedStepKind, G as CashReceiveLeg, H as CashoutInput, J as CashoutOptions, K as CuratorPayeeDataInput, L as EstimateInput, M as EstimateOptions, N as MIN_CASHOUT_AMOUNT, O as OrdersOptions, Q as PreparedCashoutReceipt, S as RECOMMENDED_MIN_CASHOUT_AMOUNT, U as RelayOptions, V as RelayQuoteInput, X as RelaySourceInput, Y as RelayTransaction, Z as SignerOptions, _ as WatchOptions, $ as WithdrawOptions, a0 as buildCapabilities, a1 as createCashClient, a2 as normalizeCashPayee, a3 as toCashReferralAttributionCode } from './createCashClient-CYSM84-K.js';
 import { PaymentMethodCatalog, CurrencyType, OracleAdapterOverrides, OnchainCurrency, Zkp2pClient, PreparedTransaction } from '@zkp2p/sdk';
 export { CurrencyType, PreparedTransaction, RuntimeEnv } from '@zkp2p/sdk';
 import { Log, Abi } from 'viem';
@@ -10,7 +10,7 @@ import '@relayprotocol/relay-sdk';
  * Typed errors - every failure carries a `code`, whether it is `retryable`,
  * and a `remediation` sentence so agents can self-drive recovery.
  */
-type CashErrorCode = 'ORACLE_UNSUPPORTED_CURRENCY' | 'ORACLE_READ_FAILED' | 'UNSUPPORTED_PLATFORM' | 'UNSUPPORTED_PLATFORM_CURRENCY' | 'AMOUNT_BELOW_MINIMUM' | 'INVALID_INTENT_AMOUNT_RANGE' | 'INVALID_PAYOUT_CURRENCIES' | 'ACTIVE_INTENT_BLOCKS_WITHDRAWAL' | 'NOTHING_TO_WITHDRAW' | 'INSUFFICIENT_AVAILABLE_FUNDS' | 'INSUFFICIENT_TOKEN_BALANCE' | 'ORDER_NOT_ACTIVE' | 'INVALID_DEPOSIT_ID' | 'ESCROW_PAUSED' | 'INDEXER_LAG' | 'INDEXER_UNAVAILABLE' | 'ORDER_NOT_FOUND' | 'PAYEE_REGISTRATION_FAILED' | 'PAYEE_VERIFICATION_REQUIRED' | 'SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE' | 'SOURCE_RECIPIENT_MISMATCH' | 'SOURCE_CAPABILITIES_FAILED' | 'SOURCE_QUOTE_FAILED' | 'SOURCE_NONCE_MANAGER_REQUIRED' | 'SOURCE_EXECUTION_FAILED' | 'SOURCE_STATUS_FAILED' | 'SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED' | 'SOURCE_CASHOUT_SUBMISSION_UNKNOWN' | 'SOURCE_CASHOUT_STATUS_UNKNOWN' | 'DEPOSIT_RESOLUTION_FAILED' | 'ALLOWANCE_NOT_VISIBLE' | 'SIGNER_REQUIRED' | 'SIGNER_CHAIN_MISMATCH' | 'SIGNER_CHAIN_UNAVAILABLE' | 'WATCH_TIMEOUT' | 'TRANSACTION_REJECTED' | 'TRANSACTION_FAILED' | 'TRANSACTION_SUBMISSION_UNKNOWN' | 'TRANSACTION_STATUS_UNKNOWN';
+type CashErrorCode = 'ORACLE_UNSUPPORTED_CURRENCY' | 'ORACLE_READ_FAILED' | 'UNSUPPORTED_PLATFORM' | 'UNSUPPORTED_PLATFORM_CURRENCY' | 'AMOUNT_BELOW_MINIMUM' | 'INVALID_INTENT_AMOUNT_RANGE' | 'INVALID_PAYOUT_CURRENCIES' | 'INVALID_PAYOUT_PLATFORMS' | 'INVALID_REFERRAL_CODE' | 'ACTIVE_INTENT_BLOCKS_WITHDRAWAL' | 'NOTHING_TO_WITHDRAW' | 'INSUFFICIENT_AVAILABLE_FUNDS' | 'INSUFFICIENT_TOKEN_BALANCE' | 'ORDER_NOT_ACTIVE' | 'INVALID_DEPOSIT_ID' | 'ESCROW_PAUSED' | 'INDEXER_LAG' | 'INDEXER_UNAVAILABLE' | 'ORDER_NOT_FOUND' | 'PAYEE_REGISTRATION_FAILED' | 'PAYEE_VERIFICATION_REQUIRED' | 'SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE' | 'SOURCE_RECIPIENT_MISMATCH' | 'SOURCE_CAPABILITIES_FAILED' | 'SOURCE_QUOTE_FAILED' | 'SOURCE_NONCE_MANAGER_REQUIRED' | 'SOURCE_EXECUTION_FAILED' | 'SOURCE_STATUS_FAILED' | 'SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED' | 'SOURCE_CASHOUT_SUBMISSION_UNKNOWN' | 'SOURCE_CASHOUT_STATUS_UNKNOWN' | 'DEPOSIT_RESOLUTION_FAILED' | 'ALLOWANCE_NOT_VISIBLE' | 'SIGNER_REQUIRED' | 'SIGNER_CHAIN_MISMATCH' | 'SIGNER_CHAIN_UNAVAILABLE' | 'WATCH_TIMEOUT' | 'TRANSACTION_REJECTED' | 'TRANSACTION_FAILED' | 'TRANSACTION_SUBMISSION_UNKNOWN' | 'TRANSACTION_STATUS_UNKNOWN';
 interface CashErrorShape {
     code: CashErrorCode;
     message: string;
@@ -78,6 +78,8 @@ declare const errors: {
     amountBelowMinimum: (amount: bigint, min: bigint) => CashError;
     invalidIntentAmountRange: (amount: bigint, min: bigint, max: bigint) => CashError;
     invalidPayoutCurrencies: (platform: string, reason: string) => CashError;
+    invalidPayoutPlatforms: (reason: string) => CashError;
+    invalidReferralCode: () => CashError;
     activeIntentBlocksWithdrawal: (depositId: string) => CashError;
     insufficientAvailableFunds: (depositId: string, requested: bigint, available: bigint) => CashError;
     insufficientTokenBalance: (requiredAmount?: bigint) => CashError;
@@ -223,9 +225,9 @@ interface MethodCurrencyLike {
 /**
  * Decode a deposit's payment methods + currency tuples into payout legs.
  * Pure - the environment arrives via the catalog. One leg per
- * (method, currency) pair; cash orders create exactly one in v1. If any
- * method is absent from the active catalog, reject the whole set instead of
- * partially reclassifying a mixed historical deposit.
+ * (method, currency) pair; a cash order carries one or several platforms. If
+ * any method is absent from the active catalog, reject the whole set instead
+ * of partially reclassifying a mixed historical deposit.
  */
 declare function derivePayouts(paymentMethods: ReadonlyArray<PaymentMethodLike>, currencies: ReadonlyArray<MethodCurrencyLike>, catalog: PaymentMethodCatalog): CashPayoutInfo[];
 
@@ -3184,7 +3186,7 @@ declare const cashErrorRecoveryJsonSchema: z.ZodDiscriminatedUnion<"kind", [z.Zo
     operation: string;
 }>]>;
 declare const cashErrorJsonSchema: z.ZodObject<{
-    code: z.ZodEnum<["ORACLE_UNSUPPORTED_CURRENCY", "ORACLE_READ_FAILED", "UNSUPPORTED_PLATFORM", "UNSUPPORTED_PLATFORM_CURRENCY", "AMOUNT_BELOW_MINIMUM", "INVALID_INTENT_AMOUNT_RANGE", "INVALID_PAYOUT_CURRENCIES", "ACTIVE_INTENT_BLOCKS_WITHDRAWAL", "NOTHING_TO_WITHDRAW", "INSUFFICIENT_AVAILABLE_FUNDS", "INSUFFICIENT_TOKEN_BALANCE", "ORDER_NOT_ACTIVE", "INVALID_DEPOSIT_ID", "ESCROW_PAUSED", "INDEXER_LAG", "INDEXER_UNAVAILABLE", "ORDER_NOT_FOUND", "PAYEE_REGISTRATION_FAILED", "PAYEE_VERIFICATION_REQUIRED", "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE", "SOURCE_RECIPIENT_MISMATCH", "SOURCE_CAPABILITIES_FAILED", "SOURCE_QUOTE_FAILED", "SOURCE_NONCE_MANAGER_REQUIRED", "SOURCE_EXECUTION_FAILED", "SOURCE_STATUS_FAILED", "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED", "SOURCE_CASHOUT_SUBMISSION_UNKNOWN", "SOURCE_CASHOUT_STATUS_UNKNOWN", "DEPOSIT_RESOLUTION_FAILED", "ALLOWANCE_NOT_VISIBLE", "SIGNER_REQUIRED", "SIGNER_CHAIN_MISMATCH", "SIGNER_CHAIN_UNAVAILABLE", "WATCH_TIMEOUT", "TRANSACTION_REJECTED", "TRANSACTION_FAILED", "TRANSACTION_SUBMISSION_UNKNOWN", "TRANSACTION_STATUS_UNKNOWN"]>;
+    code: z.ZodEnum<["ORACLE_UNSUPPORTED_CURRENCY", "ORACLE_READ_FAILED", "UNSUPPORTED_PLATFORM", "UNSUPPORTED_PLATFORM_CURRENCY", "AMOUNT_BELOW_MINIMUM", "INVALID_INTENT_AMOUNT_RANGE", "INVALID_PAYOUT_CURRENCIES", "INVALID_PAYOUT_PLATFORMS", "INVALID_REFERRAL_CODE", "ACTIVE_INTENT_BLOCKS_WITHDRAWAL", "NOTHING_TO_WITHDRAW", "INSUFFICIENT_AVAILABLE_FUNDS", "INSUFFICIENT_TOKEN_BALANCE", "ORDER_NOT_ACTIVE", "INVALID_DEPOSIT_ID", "ESCROW_PAUSED", "INDEXER_LAG", "INDEXER_UNAVAILABLE", "ORDER_NOT_FOUND", "PAYEE_REGISTRATION_FAILED", "PAYEE_VERIFICATION_REQUIRED", "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE", "SOURCE_RECIPIENT_MISMATCH", "SOURCE_CAPABILITIES_FAILED", "SOURCE_QUOTE_FAILED", "SOURCE_NONCE_MANAGER_REQUIRED", "SOURCE_EXECUTION_FAILED", "SOURCE_STATUS_FAILED", "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED", "SOURCE_CASHOUT_SUBMISSION_UNKNOWN", "SOURCE_CASHOUT_STATUS_UNKNOWN", "DEPOSIT_RESOLUTION_FAILED", "ALLOWANCE_NOT_VISIBLE", "SIGNER_REQUIRED", "SIGNER_CHAIN_MISMATCH", "SIGNER_CHAIN_UNAVAILABLE", "WATCH_TIMEOUT", "TRANSACTION_REJECTED", "TRANSACTION_FAILED", "TRANSACTION_SUBMISSION_UNKNOWN", "TRANSACTION_STATUS_UNKNOWN"]>;
     message: z.ZodString;
     retryable: z.ZodBoolean;
     remediation: z.ZodString;
@@ -3571,7 +3573,7 @@ declare const cashErrorJsonSchema: z.ZodObject<{
     }>]>>;
 }, "strict", z.ZodTypeAny, {
     message: string;
-    code: "ORACLE_UNSUPPORTED_CURRENCY" | "ORACLE_READ_FAILED" | "UNSUPPORTED_PLATFORM" | "UNSUPPORTED_PLATFORM_CURRENCY" | "AMOUNT_BELOW_MINIMUM" | "INVALID_INTENT_AMOUNT_RANGE" | "INVALID_PAYOUT_CURRENCIES" | "ACTIVE_INTENT_BLOCKS_WITHDRAWAL" | "NOTHING_TO_WITHDRAW" | "INSUFFICIENT_AVAILABLE_FUNDS" | "INSUFFICIENT_TOKEN_BALANCE" | "ORDER_NOT_ACTIVE" | "INVALID_DEPOSIT_ID" | "ESCROW_PAUSED" | "INDEXER_LAG" | "INDEXER_UNAVAILABLE" | "ORDER_NOT_FOUND" | "PAYEE_REGISTRATION_FAILED" | "PAYEE_VERIFICATION_REQUIRED" | "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE" | "SOURCE_RECIPIENT_MISMATCH" | "SOURCE_CAPABILITIES_FAILED" | "SOURCE_QUOTE_FAILED" | "SOURCE_NONCE_MANAGER_REQUIRED" | "SOURCE_EXECUTION_FAILED" | "SOURCE_STATUS_FAILED" | "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED" | "SOURCE_CASHOUT_SUBMISSION_UNKNOWN" | "SOURCE_CASHOUT_STATUS_UNKNOWN" | "DEPOSIT_RESOLUTION_FAILED" | "ALLOWANCE_NOT_VISIBLE" | "SIGNER_REQUIRED" | "SIGNER_CHAIN_MISMATCH" | "SIGNER_CHAIN_UNAVAILABLE" | "WATCH_TIMEOUT" | "TRANSACTION_REJECTED" | "TRANSACTION_FAILED" | "TRANSACTION_SUBMISSION_UNKNOWN" | "TRANSACTION_STATUS_UNKNOWN";
+    code: "ORACLE_UNSUPPORTED_CURRENCY" | "ORACLE_READ_FAILED" | "UNSUPPORTED_PLATFORM" | "UNSUPPORTED_PLATFORM_CURRENCY" | "AMOUNT_BELOW_MINIMUM" | "INVALID_INTENT_AMOUNT_RANGE" | "INVALID_PAYOUT_CURRENCIES" | "INVALID_PAYOUT_PLATFORMS" | "INVALID_REFERRAL_CODE" | "ACTIVE_INTENT_BLOCKS_WITHDRAWAL" | "NOTHING_TO_WITHDRAW" | "INSUFFICIENT_AVAILABLE_FUNDS" | "INSUFFICIENT_TOKEN_BALANCE" | "ORDER_NOT_ACTIVE" | "INVALID_DEPOSIT_ID" | "ESCROW_PAUSED" | "INDEXER_LAG" | "INDEXER_UNAVAILABLE" | "ORDER_NOT_FOUND" | "PAYEE_REGISTRATION_FAILED" | "PAYEE_VERIFICATION_REQUIRED" | "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE" | "SOURCE_RECIPIENT_MISMATCH" | "SOURCE_CAPABILITIES_FAILED" | "SOURCE_QUOTE_FAILED" | "SOURCE_NONCE_MANAGER_REQUIRED" | "SOURCE_EXECUTION_FAILED" | "SOURCE_STATUS_FAILED" | "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED" | "SOURCE_CASHOUT_SUBMISSION_UNKNOWN" | "SOURCE_CASHOUT_STATUS_UNKNOWN" | "DEPOSIT_RESOLUTION_FAILED" | "ALLOWANCE_NOT_VISIBLE" | "SIGNER_REQUIRED" | "SIGNER_CHAIN_MISMATCH" | "SIGNER_CHAIN_UNAVAILABLE" | "WATCH_TIMEOUT" | "TRANSACTION_REJECTED" | "TRANSACTION_FAILED" | "TRANSACTION_SUBMISSION_UNKNOWN" | "TRANSACTION_STATUS_UNKNOWN";
     retryable: boolean;
     remediation: string;
     recovery?: {
@@ -3653,7 +3655,7 @@ declare const cashErrorJsonSchema: z.ZodObject<{
     } | undefined;
 }, {
     message: string;
-    code: "ORACLE_UNSUPPORTED_CURRENCY" | "ORACLE_READ_FAILED" | "UNSUPPORTED_PLATFORM" | "UNSUPPORTED_PLATFORM_CURRENCY" | "AMOUNT_BELOW_MINIMUM" | "INVALID_INTENT_AMOUNT_RANGE" | "INVALID_PAYOUT_CURRENCIES" | "ACTIVE_INTENT_BLOCKS_WITHDRAWAL" | "NOTHING_TO_WITHDRAW" | "INSUFFICIENT_AVAILABLE_FUNDS" | "INSUFFICIENT_TOKEN_BALANCE" | "ORDER_NOT_ACTIVE" | "INVALID_DEPOSIT_ID" | "ESCROW_PAUSED" | "INDEXER_LAG" | "INDEXER_UNAVAILABLE" | "ORDER_NOT_FOUND" | "PAYEE_REGISTRATION_FAILED" | "PAYEE_VERIFICATION_REQUIRED" | "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE" | "SOURCE_RECIPIENT_MISMATCH" | "SOURCE_CAPABILITIES_FAILED" | "SOURCE_QUOTE_FAILED" | "SOURCE_NONCE_MANAGER_REQUIRED" | "SOURCE_EXECUTION_FAILED" | "SOURCE_STATUS_FAILED" | "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED" | "SOURCE_CASHOUT_SUBMISSION_UNKNOWN" | "SOURCE_CASHOUT_STATUS_UNKNOWN" | "DEPOSIT_RESOLUTION_FAILED" | "ALLOWANCE_NOT_VISIBLE" | "SIGNER_REQUIRED" | "SIGNER_CHAIN_MISMATCH" | "SIGNER_CHAIN_UNAVAILABLE" | "WATCH_TIMEOUT" | "TRANSACTION_REJECTED" | "TRANSACTION_FAILED" | "TRANSACTION_SUBMISSION_UNKNOWN" | "TRANSACTION_STATUS_UNKNOWN";
+    code: "ORACLE_UNSUPPORTED_CURRENCY" | "ORACLE_READ_FAILED" | "UNSUPPORTED_PLATFORM" | "UNSUPPORTED_PLATFORM_CURRENCY" | "AMOUNT_BELOW_MINIMUM" | "INVALID_INTENT_AMOUNT_RANGE" | "INVALID_PAYOUT_CURRENCIES" | "INVALID_PAYOUT_PLATFORMS" | "INVALID_REFERRAL_CODE" | "ACTIVE_INTENT_BLOCKS_WITHDRAWAL" | "NOTHING_TO_WITHDRAW" | "INSUFFICIENT_AVAILABLE_FUNDS" | "INSUFFICIENT_TOKEN_BALANCE" | "ORDER_NOT_ACTIVE" | "INVALID_DEPOSIT_ID" | "ESCROW_PAUSED" | "INDEXER_LAG" | "INDEXER_UNAVAILABLE" | "ORDER_NOT_FOUND" | "PAYEE_REGISTRATION_FAILED" | "PAYEE_VERIFICATION_REQUIRED" | "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE" | "SOURCE_RECIPIENT_MISMATCH" | "SOURCE_CAPABILITIES_FAILED" | "SOURCE_QUOTE_FAILED" | "SOURCE_NONCE_MANAGER_REQUIRED" | "SOURCE_EXECUTION_FAILED" | "SOURCE_STATUS_FAILED" | "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED" | "SOURCE_CASHOUT_SUBMISSION_UNKNOWN" | "SOURCE_CASHOUT_STATUS_UNKNOWN" | "DEPOSIT_RESOLUTION_FAILED" | "ALLOWANCE_NOT_VISIBLE" | "SIGNER_REQUIRED" | "SIGNER_CHAIN_MISMATCH" | "SIGNER_CHAIN_UNAVAILABLE" | "WATCH_TIMEOUT" | "TRANSACTION_REJECTED" | "TRANSACTION_FAILED" | "TRANSACTION_SUBMISSION_UNKNOWN" | "TRANSACTION_STATUS_UNKNOWN";
     retryable: boolean;
     remediation: string;
     recovery?: {