@zkp2p/cash 0.1.6 → 0.1.8

package/dist/index.js

@@ -1,5 +1,5 @@
-import { MARKET_SPREAD_BPS, ORACLE_MIN_CONVERSION_RATE_SENTINEL, CASH_RETAIN_ON_EMPTY, BASE_USDC_ADDRESS, USDC_DECIMALS, BASE_CHAIN_ID, errors, isCashError, CASH_ORDER_STATUSES, mapChainError, CashError } from './chunk-P3KYZ2FX.js';
-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 } from './chunk-P3KYZ2FX.js';
+import { MARKET_SPREAD_BPS, ORACLE_MIN_CONVERSION_RATE_SENTINEL, CASH_RETAIN_ON_EMPTY, BASE_USDC_ADDRESS, USDC_DECIMALS, BASE_CHAIN_ID, errors, isCashError, CASH_ORDER_STATUSES, mapChainError, CashError } from './chunk-TR6JVYYF.js';
+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 } from './chunk-TR6JVYYF.js';
 import { parseAbi, parseEventLogs, isAddress, http, createWalletClient, encodeFunctionData } from 'viem';
 import { base } from 'viem/chains';
 import { getSpreadOracleConfig, currencyInfo, getPaymentMethodsCatalog, getGatingServiceAddress, resolvePaymentMethodHashFromCatalog, resolvePaymentMethodNameFromHash, getCurrencyCodeFromHash, createCompositeDepositId, appendAttributionToCalldata, Zkp2pClient, CHAINLINK_ORACLE_FEEDS } from '@zkp2p/sdk';
@@ -387,6 +387,26 @@ function parseCompositeDepositId(compositeId) {
   const onchainDepositId = BigInt(rawDepositId);
   return { escrowAddress: canonicalEscrowAddress, onchainDepositId };
 }
+
+// src/client/platformGroups.ts
+var PLATFORM_METHOD_GROUPS = {
+  zelle: ["zelle", "zelle-chase", "zelle-bofa", "zelle-citi"]
+};
+var METHOD_TO_BASE_PLATFORM = new Map(
+  Object.entries(PLATFORM_METHOD_GROUPS).flatMap(
+    ([platform, methods]) => methods.map((method) => [method, platform])
+  )
+);
+function basePlatformForMethod(method) {
+  return METHOD_TO_BASE_PLATFORM.get(method) ?? method;
+}
+function paymentMethodsForPlatform(platform, catalog) {
+  const configured = PLATFORM_METHOD_GROUPS[platform];
+  const methods = configured ?? [platform];
+  return methods.filter((method) => catalog[method] !== void 0);
+}
+
+// src/client/capabilities.ts
 var MIN_CASHOUT_AMOUNT = 10000n;
 var RECOMMENDED_MIN_CASHOUT_AMOUNT = 1000000n;
 var PAYEE_HINTS = {
@@ -405,13 +425,20 @@ var PAYEE_HINTS = {
 var IDENTITY_ATTESTATION_PLATFORMS = /* @__PURE__ */ new Set(["wise", "paypal"]);
 function buildCapabilities(environment) {
   const catalog = getPaymentMethodsCatalog(BASE_CHAIN_ID, environment);
-  const platforms = Object.entries(catalog).map(([platform, entry]) => {
+  const currenciesByPlatform = /* @__PURE__ */ new Map();
+  for (const [method, entry] of Object.entries(catalog)) {
+    const platform = basePlatformForMethod(method);
     const currencies2 = (entry.currencies ?? []).map((hash) => getCurrencyCodeFromHash(hash)).filter(
       (code) => code != null && isMarketRateSupported(code)
     );
+    const aggregate = currenciesByPlatform.get(platform) ?? /* @__PURE__ */ new Set();
+    for (const currency of currencies2) aggregate.add(currency);
+    currenciesByPlatform.set(platform, aggregate);
+  }
+  const platforms = [...currenciesByPlatform.entries()].map(([platform, currencies2]) => {
     return {
       platform,
-      currencies: [...new Set(currencies2)],
+      currencies: [...currencies2].sort(),
       payeeHint: PAYEE_HINTS[platform] ?? "Your payment handle for this platform",
       requiresIdentityAttestation: IDENTITY_ATTESTATION_PLATFORMS.has(platform)
     };
@@ -430,11 +457,8 @@ function buildCapabilities(environment) {
     pricing: { kind: "oracle-market-rate", spreadBps: 0 }
   };
 }
-var ETA_WINDOW_DAYS = 30;
-var ETA_WINDOW_SECONDS = ETA_WINDOW_DAYS * 24 * 60 * 60;
-var ETA_PAGE_LIMIT = 250;
-var ETA_MAX_DEPOSIT_SCAN = 2e3;
-var FULFILLED = /* @__PURE__ */ new Set(["FULFILLED", "MANUALLY_RELEASED"]);
+var FILL_STATS_WINDOW_SECONDS = 30 * 24 * 60 * 60;
+var FILL_STATS_PAGE_LIMIT = 250;
 function toUnixSeconds2(value) {
   if (value === null || value === void 0 || value === "") return void 0;
   if (value instanceof Date) {
@@ -445,12 +469,22 @@ function toUnixSeconds2(value) {
     const parsed = Date.parse(value);
     if (Number.isFinite(parsed)) return Math.floor(parsed / 1e3);
   }
-  const n = Number(value);
-  return Number.isFinite(n) && n > 0 ? n : void 0;
+  const numeric = Number(value);
+  return Number.isFinite(numeric) && numeric > 0 ? numeric : void 0;
+}
+function normalizeCurrencyCode(value) {
+  const raw = value?.trim();
+  if (!raw) return void 0;
+  if (!raw.toLowerCase().startsWith("0x")) return raw.toUpperCase();
+  try {
+    return getCurrencyCodeFromHash(raw)?.toUpperCase();
+  } catch {
+    return void 0;
+  }
 }
 function median(values) {
   if (values.length === 0) return void 0;
-  const sorted = [...values].sort((a, b) => a - b);
+  const sorted = [...values].sort((left, right) => left - right);
   const mid = Math.floor(sorted.length / 2);
   return sorted.length % 2 === 1 ? sorted[mid] : Math.round((sorted[mid - 1] + sorted[mid]) / 2);
 }
@@ -462,47 +496,97 @@ function etaLabel(seconds) {
   const hours = Math.max(1, Math.round(minutes / 60));
   return `Usually starts in about ${hours} hr`;
 }
-function matchesPayout(deposit, environment, platform, currency) {
-  const payouts = derivePayouts(
-    deposit.paymentMethods ?? [],
-    deposit.currencies ?? [],
-    getPaymentMethodsCatalog(BASE_CHAIN_ID, environment)
-  );
-  return payouts.some(
-    (payout) => payout.pricing.marketRate && payout.pricing.spreadBps === 0 && (platform === void 0 || payout.platform === platform) && (currency === void 0 || payout.currency === currency)
-  );
+function computeFillStatsSample(deposits, nowSeconds, environment) {
+  const catalog = getPaymentMethodsCatalog(BASE_CHAIN_ID, environment);
+  const windowStart = nowSeconds - FILL_STATS_WINDOW_SECONDS;
+  const fillCounts = /* @__PURE__ */ new Map();
+  const latenciesByPair = /* @__PURE__ */ new Map();
+  const latenciesByCurrency = /* @__PURE__ */ new Map();
+  for (const deposit of deposits) {
+    const createdAt = toUnixSeconds2(deposit.createdAt ?? deposit.timestamp);
+    const firstFillByPair = /* @__PURE__ */ new Map();
+    const firstFillByCurrency = /* @__PURE__ */ new Map();
+    for (const intent of deposit.intents ?? []) {
+      const fulfilledAt = toUnixSeconds2(intent.fulfillTimestamp);
+      if (fulfilledAt === void 0 || fulfilledAt < windowStart) continue;
+      let method;
+      try {
+        method = intent.paymentMethodHash ? resolvePaymentMethodNameFromHash(intent.paymentMethodHash, catalog) : void 0;
+      } catch {
+        method = void 0;
+      }
+      const currency = normalizeCurrencyCode(intent.fiatCurrency);
+      if (!method || !currency) continue;
+      const pair = `${basePlatformForMethod(method)}:${currency}`;
+      fillCounts.set(pair, (fillCounts.get(pair) ?? 0) + 1);
+      if (createdAt === void 0 || createdAt < windowStart || fulfilledAt < createdAt) continue;
+      const previousPairFill = firstFillByPair.get(pair);
+      if (previousPairFill === void 0 || fulfilledAt < previousPairFill) {
+        firstFillByPair.set(pair, fulfilledAt);
+      }
+      const previousCurrencyFill = firstFillByCurrency.get(currency);
+      if (previousCurrencyFill === void 0 || fulfilledAt < previousCurrencyFill) {
+        firstFillByCurrency.set(currency, fulfilledAt);
+      }
+    }
+    if (createdAt === void 0) continue;
+    for (const [pair, firstFill] of firstFillByPair) {
+      const latencies = latenciesByPair.get(pair) ?? [];
+      latencies.push(firstFill - createdAt);
+      latenciesByPair.set(pair, latencies);
+    }
+    for (const [currency, firstFill] of firstFillByCurrency) {
+      const latencies = latenciesByCurrency.get(currency) ?? [];
+      latencies.push(firstFill - createdAt);
+      latenciesByCurrency.set(currency, latencies);
+    }
+  }
+  const stats = {};
+  for (const [pair, fills] of fillCounts) {
+    const medianFillSeconds = median(latenciesByPair.get(pair) ?? []);
+    stats[pair] = {
+      fills,
+      ...medianFillSeconds !== void 0 ? { medianFillSeconds } : {}
+    };
+  }
+  const medianFillSecondsByCurrency = /* @__PURE__ */ new Map();
+  for (const [currency, latencies] of latenciesByCurrency) {
+    const value = median(latencies);
+    if (value !== void 0) medianFillSecondsByCurrency.set(currency, value);
+  }
+  return { stats, medianFillSecondsByCurrency };
 }
-async function readFillEta(client, input) {
+async function readFillStatsSample(client, environment) {
   const now = Math.floor(Date.now() / 1e3);
-  const windowStart = now - ETA_WINDOW_SECONDS;
+  const windowStart = now - FILL_STATS_WINDOW_SECONDS;
   const deposits = [];
-  for (let offset = 0; offset < ETA_MAX_DEPOSIT_SCAN; offset += ETA_PAGE_LIMIT) {
+  for (let offset = 0; ; offset += FILL_STATS_PAGE_LIMIT) {
     const page = await client.indexer.getDepositsWithRelations(
       { chainId: BASE_CHAIN_ID },
-      { limit: ETA_PAGE_LIMIT, offset, orderBy: "timestamp", orderDirection: "desc" },
+      {
+        limit: FILL_STATS_PAGE_LIMIT,
+        offset,
+        orderBy: "updatedAt",
+        orderDirection: "desc"
+      },
       { includeIntents: true, intentStatuses: ["FULFILLED", "MANUALLY_RELEASED"] }
     );
     deposits.push(...page);
-    if (page.length < ETA_PAGE_LIMIT) break;
-    const oldestCreatedAt = Math.min(
-      ...page.map((deposit) => toUnixSeconds2(deposit.createdAt ?? deposit.timestamp) ?? Infinity)
+    if (page.length < FILL_STATS_PAGE_LIMIT) break;
+    const oldestUpdatedAt = Math.min(
+      ...page.map((deposit) => toUnixSeconds2(deposit.updatedAt) ?? Infinity)
     );
-    if (oldestCreatedAt < windowStart) break;
+    if (oldestUpdatedAt < windowStart) break;
   }
-  const firstFillLatencies = [];
-  for (const deposit of deposits) {
-    const createdAt = toUnixSeconds2(deposit.createdAt ?? deposit.timestamp);
-    if (createdAt === void 0 || createdAt < windowStart) continue;
-    if (!matchesPayout(deposit, input.environment, input.platform, input.currency)) continue;
-    const fulfilled = (deposit.intents ?? []).filter((intent) => intent.status != null && FULFILLED.has(intent.status)).map((intent) => ({
-      fulfilledAt: toUnixSeconds2(intent.fulfillTimestamp)
-    })).filter(
-      (intent) => intent.fulfilledAt !== void 0 && intent.fulfilledAt >= createdAt
-    ).sort((a, b) => a.fulfilledAt - b.fulfilledAt);
-    if (fulfilled.length === 0) continue;
-    firstFillLatencies.push(fulfilled[0].fulfilledAt - createdAt);
-  }
-  const seconds = median(firstFillLatencies);
+  return computeFillStatsSample(deposits, now, environment);
+}
+async function readFillStats(client, environment) {
+  return (await readFillStatsSample(client, environment)).stats;
+}
+async function readFillEta(client, input) {
+  const sample = await readFillStatsSample(client, input.environment);
+  const currency = input.currency.toUpperCase();
+  const seconds = input.platform ? sample.stats[`${basePlatformForMethod(input.platform)}:${currency}`]?.medianFillSeconds : sample.medianFillSecondsByCurrency.get(currency);
   return {
     ...seconds !== void 0 ? { seconds } : {},
     label: etaLabel(seconds)
@@ -675,6 +759,14 @@ async function assertRelayExecutionIdentity(quote, wallet, expectedRecipient) {
     throw new Error("Relay quote recipient does not match the expected Base recipient");
   }
 }
+function assertRelayNonceManagement(quote, wallet) {
+  const account = wallet.account;
+  if (!account || account.type !== "local" || account.nonceManager !== void 0) return;
+  const transactionCount = quote.steps.flatMap(
+    (step) => step.items.filter((item) => asString(asRecord(item.data).to) !== void 0)
+  ).length;
+  if (transactionCount > 1) throw errors.sourceNonceManagerRequired(transactionCount);
+}
 function isRelaySecretKey(key) {
   const normalized = key.toLowerCase();
   return normalized === "headers" || normalized === "apikey";
@@ -876,6 +968,7 @@ async function executeRelayQuote(quote, wallet, options = {}) {
     observedRequestId = quoteRequestId(rawQuote);
     assertCanonicalRelayDestination(rawQuote);
     await assertRelayExecutionIdentity(rawQuote, wallet, options.recipient);
+    assertRelayNonceManagement(rawQuote, wallet);
     const client = relayClient(options.relay);
     const sourceChainId = quoteSourceChainId(rawQuote);
     if (sourceChainId !== void 0 && !(client.chains ?? []).some((chain) => chain.id === sourceChainId)) {
@@ -1161,6 +1254,7 @@ function createCashClient(options) {
   }
   function validatePayout(input) {
     const { receive } = input;
+    const catalog = getPaymentMethodsCatalog(BASE_CHAIN_ID, environment);
     const platform = buildCapabilities(environment).platforms.find(
       (capability) => capability.platform === receive.platform
     );
@@ -1171,14 +1265,13 @@ function createCashClient(options) {
     if (!platform.currencies.includes(receive.currency)) {
       throw errors.unsupportedPlatformCurrency(receive.platform, receive.currency);
     }
+    const paymentMethods = paymentMethodsForPlatform(receive.platform, catalog);
     return {
-      payouts: [
-        {
-          processorName: receive.platform,
-          currency: receive.currency,
-          payeeData: receive.payee
-        }
-      ]
+      payouts: paymentMethods.map((processorName) => ({
+        processorName,
+        currency: receive.currency,
+        payeeData: receive.payee
+      }))
     };
   }
   function validateDepositInput(amount, input, payoutInput = validatePayout(input)) {
@@ -1456,6 +1549,13 @@ function createCashClient(options) {
         ...options.relay ? { relay: options.relay } : {}
       });
     },
+    async fillStats() {
+      try {
+        return await readFillStats(readClient, environment);
+      } catch (err) {
+        throw errors.indexerUnavailable("fill stats", err);
+      }
+    },
     async cashout(input, opts) {
       const client = await signingClient("cashout", opts);
       const owner = opts.signer.account.address;
@@ -2055,6 +2155,11 @@ var cashEstimateJsonSchema = z.object({
     label: z.string()
   }).optional()
 });
+var cashPairFillStatsJsonSchema = z.object({
+  fills: z.number().int().nonnegative(),
+  medianFillSeconds: z.number().int().nonnegative().optional()
+}).strict();
+var cashFillStatsJsonSchema = z.record(z.string(), cashPairFillStatsJsonSchema);
 var preparedTransactionJsonSchema = z.object({
   to: z.string(),
   data: z.string(),
@@ -2186,6 +2291,7 @@ var CASH_ERROR_CODES = defineCashErrorCodes([
   "SOURCE_RECIPIENT_MISMATCH",
   "SOURCE_CAPABILITIES_FAILED",
   "SOURCE_QUOTE_FAILED",
+  "SOURCE_NONCE_MANAGER_REQUIRED",
   "SOURCE_EXECUTION_FAILED",
   "SOURCE_STATUS_FAILED",
   "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED",
@@ -2358,6 +2464,21 @@ function estimateFromJson(json) {
     } : void 0
   });
 }
+function fillStatsToJson(stats) {
+  return cashFillStatsJsonSchema.parse(stats);
+}
+function fillStatsFromJson(json) {
+  const parsed = cashFillStatsJsonSchema.parse(json);
+  return Object.fromEntries(
+    Object.entries(parsed).map(([pair, stats]) => [
+      pair,
+      {
+        fills: stats.fills,
+        ...stats.medianFillSeconds !== void 0 ? { medianFillSeconds: stats.medianFillSeconds } : {}
+      }
+    ])
+  );
+}
 function cashAssetFromJson(asset) {
   return {
     chainId: asset.chainId,
@@ -2635,4 +2756,4 @@ function cashErrorFromJson(json) {
   });
 }
 
-export { CASH_ATTRIBUTION_CODE, MIN_CASHOUT_AMOUNT, RATE_PRECISION, RECOMMENDED_MIN_CASHOUT_AMOUNT, bigintString, buildCapabilities, buildIntentAmountRange, buildMarketRateCurrencyOverride, buyerProfileFromJson, buyerProfileToJson, capabilitiesFromJson, capabilitiesToJson, cashAssetJsonSchema, cashBuyerProfileJsonSchema, cashCapabilitiesJsonSchema, cashChainJsonSchema, cashErrorFromJson, cashErrorJsonSchema, cashErrorRecoveryJsonSchema, cashErrorToJson, cashEstimateJsonSchema, cashFillJsonSchema, cashNextActionSchema, cashOrderJsonSchema, cashOrderStateSchema, cashPayoutInfoJsonSchema, cashPayoutPricingJsonSchema, cashPreparedStepJsonSchema, cashSourceCapabilitiesJsonSchema, cashoutResultFromJson, cashoutResultJsonSchema, cashoutResultToJson, centsToNumber, createCashClient, deriveBuyerProfile, deriveCashOrder, derivePayouts, estimateFromJson, estimateToJson, explainOrder, fiatFromUsdc, fiatToNumber, fillFromJson, fillToJson, formatUsdc, intentStatusSchema, isFillLive, isMarketRateSupported, nonNegativeBigintString, orderFromJson, orderToJson, parseCompositeDepositId, prepareCashDepositParams, prepareResultFromJson, prepareResultJsonSchema, prepareResultToJson, preparedStepFromJson, preparedStepToJson, preparedTransactionJsonSchema, preparedTxFromJson, preparedTxToJson, rateToNumber, relayExecutionResultFromJson, relayExecutionResultJsonSchema, relayExecutionResultToJson, relayQuoteFromJson, relayQuoteJsonSchema, relayQuoteToJson, relayStatusFromJson, relayStatusJsonSchema, relayStatusToJson, relayTransactionJsonSchema, relayTransactionsJsonSchema, resolveCashDepositId, sourceCapabilitiesFromJson, sourceCapabilitiesToJson, topUpResultFromJson, topUpResultJsonSchema, topUpResultToJson, usdc, withExplain, withdrawResultFromJson, withdrawResultJsonSchema, withdrawResultToJson };
+export { CASH_ATTRIBUTION_CODE, MIN_CASHOUT_AMOUNT, RATE_PRECISION, RECOMMENDED_MIN_CASHOUT_AMOUNT, bigintString, buildCapabilities, buildIntentAmountRange, buildMarketRateCurrencyOverride, buyerProfileFromJson, buyerProfileToJson, capabilitiesFromJson, capabilitiesToJson, cashAssetJsonSchema, cashBuyerProfileJsonSchema, cashCapabilitiesJsonSchema, cashChainJsonSchema, cashErrorFromJson, cashErrorJsonSchema, cashErrorRecoveryJsonSchema, cashErrorToJson, cashEstimateJsonSchema, cashFillJsonSchema, cashFillStatsJsonSchema, cashNextActionSchema, cashOrderJsonSchema, cashOrderStateSchema, cashPairFillStatsJsonSchema, cashPayoutInfoJsonSchema, cashPayoutPricingJsonSchema, cashPreparedStepJsonSchema, cashSourceCapabilitiesJsonSchema, cashoutResultFromJson, cashoutResultJsonSchema, cashoutResultToJson, centsToNumber, createCashClient, deriveBuyerProfile, deriveCashOrder, derivePayouts, estimateFromJson, estimateToJson, explainOrder, fiatFromUsdc, fiatToNumber, fillFromJson, fillStatsFromJson, fillStatsToJson, fillToJson, formatUsdc, intentStatusSchema, isFillLive, isMarketRateSupported, nonNegativeBigintString, orderFromJson, orderToJson, parseCompositeDepositId, prepareCashDepositParams, prepareResultFromJson, prepareResultJsonSchema, prepareResultToJson, preparedStepFromJson, preparedStepToJson, preparedTransactionJsonSchema, preparedTxFromJson, preparedTxToJson, rateToNumber, relayExecutionResultFromJson, relayExecutionResultJsonSchema, relayExecutionResultToJson, relayQuoteFromJson, relayQuoteJsonSchema, relayQuoteToJson, relayStatusFromJson, relayStatusJsonSchema, relayStatusToJson, relayTransactionJsonSchema, relayTransactionsJsonSchema, resolveCashDepositId, sourceCapabilitiesFromJson, sourceCapabilitiesToJson, topUpResultFromJson, topUpResultJsonSchema, topUpResultToJson, usdc, withExplain, withdrawResultFromJson, withdrawResultJsonSchema, withdrawResultToJson };

package/dist/react.d.cts

@@ -1,5 +1,5 @@
 import { CurrencyType } from '@zkp2p/sdk';
-import { q as CashClient, E as EstimateInput, i as CashEstimate, B as CashoutOptions, h as CashoutResult, A as CashoutInput, T as TopUpResult, W as WithdrawResult, e as CashOrder } from './createCashClient-jUA_GNdh.cjs';
+import { r as CashClient, G as EstimateInput, i as CashEstimate, E as CashoutOptions, h as CashoutResult, D as CashoutInput, T as TopUpResult, W as WithdrawResult, e as CashOrder } from './createCashClient-BIzOLHjF.cjs';
 import { WalletClient } from 'viem';
 import '@relayprotocol/relay-sdk';
 

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import { CurrencyType } from '@zkp2p/sdk';
-import { q as CashClient, E as EstimateInput, i as CashEstimate, B as CashoutOptions, h as CashoutResult, A as CashoutInput, T as TopUpResult, W as WithdrawResult, e as CashOrder } from './createCashClient-jUA_GNdh.js';
+import { r as CashClient, G as EstimateInput, i as CashEstimate, E as CashoutOptions, h as CashoutResult, D as CashoutInput, T as TopUpResult, W as WithdrawResult, e as CashOrder } from './createCashClient-BIzOLHjF.js';
 import { WalletClient } from 'viem';
 import '@relayprotocol/relay-sdk';
 

package/dist/react.js

@@ -1,4 +1,4 @@
-import { isCashError, CASH_ORDER_POLL_INTERVAL_MS } from './chunk-P3KYZ2FX.js';
+import { isCashError, CASH_ORDER_POLL_INTERVAL_MS } from './chunk-TR6JVYYF.js';
 import { useState, useRef, useCallback, useEffect, useMemo } from 'react';
 
 function useEstimate({

package/dist/tools.cjs

@@ -2,7 +2,7 @@
 
 // package.json
 var package_default = {
-  version: "0.1.6"};
+  version: "0.1.8"};
 
 // src/tools/index.ts
 var bigintString = {
@@ -112,6 +112,15 @@ var builtInCashTools = [
       additionalProperties: false
     }
   },
+  {
+    name: "cash_fill_stats",
+    description: "Read raw 30-day demand and first-fill speed evidence for every observed platform:currency pair. Consumers should apply their own threshold and fail open to cash_capabilities when stats are unavailable or filtering would empty the catalog.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    }
+  },
   {
     name: "cash_cashout",
     description: "Start a Base-USDC cash-out using the custody-separated prepare path. Returns UNSIGNED transactions plus same-index steps [approve, createDeposit]; signing and ordered submission stay host-side. For another source asset, complete cash_source_quote and cash_source_status first, then pass the guaranteed Base USDC output amount here.",

package/dist/tools.d.cts

@@ -135,6 +135,14 @@ declare const builtInCashTools: readonly [{
         readonly required: readonly ["amount", "currency"];
         readonly additionalProperties: false;
     };
+}, {
+    readonly name: "cash_fill_stats";
+    readonly description: "Read raw 30-day demand and first-fill speed evidence for every observed platform:currency pair. Consumers should apply their own threshold and fail open to cash_capabilities when stats are unavailable or filtering would empty the catalog.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly additionalProperties: false;
+    };
 }, {
     readonly name: "cash_cashout";
     readonly description: "Start a Base-USDC cash-out using the custody-separated prepare path. Returns UNSIGNED transactions plus same-index steps [approve, createDeposit]; signing and ordered submission stay host-side. For another source asset, complete cash_source_quote and cash_source_status first, then pass the guaranteed Base USDC output amount here.";

package/dist/tools.d.ts

@@ -135,6 +135,14 @@ declare const builtInCashTools: readonly [{
         readonly required: readonly ["amount", "currency"];
         readonly additionalProperties: false;
     };
+}, {
+    readonly name: "cash_fill_stats";
+    readonly description: "Read raw 30-day demand and first-fill speed evidence for every observed platform:currency pair. Consumers should apply their own threshold and fail open to cash_capabilities when stats are unavailable or filtering would empty the catalog.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly additionalProperties: false;
+    };
 }, {
     readonly name: "cash_cashout";
     readonly description: "Start a Base-USDC cash-out using the custody-separated prepare path. Returns UNSIGNED transactions plus same-index steps [approve, createDeposit]; signing and ordered submission stay host-side. For another source asset, complete cash_source_quote and cash_source_status first, then pass the guaranteed Base USDC output amount here.";

package/dist/tools.js

@@ -1,6 +1,6 @@
 // package.json
 var package_default = {
-  version: "0.1.6"};
+  version: "0.1.8"};
 
 // src/tools/index.ts
 var bigintString = {
@@ -110,6 +110,15 @@ var builtInCashTools = [
       additionalProperties: false
     }
   },
+  {
+    name: "cash_fill_stats",
+    description: "Read raw 30-day demand and first-fill speed evidence for every observed platform:currency pair. Consumers should apply their own threshold and fail open to cash_capabilities when stats are unavailable or filtering would empty the catalog.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    }
+  },
   {
     name: "cash_cashout",
     description: "Start a Base-USDC cash-out using the custody-separated prepare path. Returns UNSIGNED transactions plus same-index steps [approve, createDeposit]; signing and ordered submission stay host-side. For another source asset, complete cash_source_quote and cash_source_status first, then pass the guaranteed Base USDC output amount here.",

package/docs/lifecycle-and-recovery.md

@@ -36,6 +36,16 @@ For any other EVM source asset, Peer Cash uses `@relayprotocol/relay-sdk`:
    `executeSourceQuote()` remains available for apps that want a separate
    bridge step.
 
+Routes that need more than one source-chain transaction (an ERC-20 `approve`,
+then the route transaction) are submitted back-to-back by the Relay SDK. On a
+plain local account the route transaction reuses the approval's nonce and
+reverts mid-route, so `executeSourceQuote()` and `cashout({ source })` refuse
+multi-transaction routes up front with `SOURCE_NONCE_MANAGER_REQUIRED` unless
+the source signer carries a viem nonce manager:
+`privateKeyToAccount(pk, { nonceManager })`. The check fires before anything
+is submitted. Browser (`json-rpc`) wallets are unaffected - the node
+allocates their nonces.
+
 Cash-out interfaces should use `tradeType: 'EXACT_INPUT'` (also the default),
 so `amount` always means source-token base units. A `RelayQuote.outputAmount`
 is the guaranteed minimum Base USDC output. The same value becomes
@@ -62,10 +72,16 @@ destination constant.
 
 Do not retry a source route merely because the Base cashout did not finish:
 
+- `SOURCE_NONCE_MANAGER_REQUIRED` is preflight: nothing was submitted.
+  Recreate the source signer with viem's nonce manager and execute a fresh
+  quote.
 - `SOURCE_EXECUTION_FAILED` means Relay execution did not report success. Check
   its `inspect-relay-route` recovery evidence, submitted wallet transactions,
   and `relayStatus(requestId)` before taking another action; a blind retry can
-  route twice.
+  route twice. A failed route whose only landed transaction is the approval
+  can sit in `relayStatus` `waiting` indefinitely - it never becomes terminal,
+  so decide from the persisted recovery payload and the origin transactions,
+  not from Relay reaching a final status.
 - `SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED` means Relay completed, but the Base
   cashout was not created. Its recovery payload has
   `kind: 'retry-base-usdc-cashout'`, the guaranteed Base USDC `amount`, Relay
@@ -108,10 +124,17 @@ passes through `delivering` until the last one completes. `filledAmount`,
 ## The ETA principle
 
 `estimate().eta` is historical, not a promise. It uses rolling 30-day indexer
-data from deposit/order creation to the first fulfilled fill. It deliberately
-does **not** measure buyer signal to fulfillment; that would miss the
-buyer-arrival wait that users actually care about. The public shape is small:
-`{ seconds, label }`.
+data from deposit/order creation to the first fulfilled fill through the
+intent's actual platform and currency pair. It deliberately does **not**
+measure buyer signal to fulfillment; that would miss the buyer-arrival wait
+that users actually care about. The public shape is small: `{ seconds, label }`.
+
+`fillStats()` exposes the sampler's raw evidence for catalog filtering as
+`Record<"platform:currency", { fills, medianFillSeconds? }>`. Bank-scoped Zelle
+methods aggregate to `zelle:USD`. Consumers own thresholding; the recommended
+gate is `fills >= 10 && medianFillSeconds <= 48h`, with a fail-open fallback to
+the full capability catalog when the read fails or filtering would empty it.
+Medians are per-deposit first-fill latencies, never means or censored cohorts.
 
 - **Buyer arrival time is market-driven.** A deposit at market rate should
   fill fast, but the ETA is only a recent historical sample.
@@ -132,7 +155,9 @@ UI built on this SDK is a bug in that UI.
 - **Partial withdrawal** - `withdraw(depositId, { amount })` pulls part of
   the _unlocked_ balance back out. A live buyer intent does not block it
   (their locked portion is untouched); asking for more than the unlocked
-  balance fails with `INSUFFICIENT_AVAILABLE_FUNDS`.
+  balance fails with `INSUFFICIENT_AVAILABLE_FUNDS`. Accounting note: a
+  partial withdrawal increments `returnedAmount`; `totalAmount` records
+  everything the order has ever held and does not shrink.
 - There is no retain-on-empty or rate knob to manage - a cash order cleans
   itself up when fully filled, and the market rate is not configurable.
 
@@ -252,6 +277,7 @@ explicit override.
 | `SOURCE_RECIPIENT_MISMATCH`             | no        | Relay output recipient differs from the cashout depositor. Use the depositor address.                                                        |
 | `SOURCE_CAPABILITIES_FAILED`            | yes       | Relay source discovery failed. Retry or use Base USDC.                                                                                       |
 | `SOURCE_QUOTE_FAILED`                   | yes       | Relay returned no valid canonical Base-USDC route. Refresh capabilities and quote again.                                                     |
+| `SOURCE_NONCE_MANAGER_REQUIRED`         | no        | Preflight; nothing was submitted. Recreate the source signer with viem's `nonceManager` and execute a fresh quote.                           |
 | `SOURCE_EXECUTION_FAILED`               | no        | Route execution did not report success. Inspect source transactions and Relay status before retrying.                                        |
 | `SOURCE_STATUS_FAILED`                  | yes       | Relay status is temporarily unavailable. Retry the status read without resubmitting.                                                         |
 | `SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED` | no        | Relay completed but no Base cashout was created. Use the recovery amount for a Base-USDC-only retry; never repeat Relay.                     |

package/llms.txt

@@ -19,9 +19,13 @@ Key facts:
   source.amount is Relay's guaranteed minimum Base USDC output and the exact
   order deposit amount, not the route's actual output.
 - There is NO locked fiat quote. estimate() reads the oracle; the binding rate
-  resolves at fill time. ETA is `{ seconds, label }` from rolling 30-day,
-  zero-spread market-rate deposits in the same payout corridor, not a
-  guarantee.
+  resolves at fill time. ETA is `{ seconds, label }` from the same rolling
+  30-day, intent-attributed pair sampler as fillStats(), not a guarantee.
+- fillStats() returns raw `{ fills, medianFillSeconds? }` evidence keyed by
+  `platform:currency`. Recommended consumer gate: fills >= 10 and median <=
+  48h; fail open to capabilities() if unavailable or filtering empties it.
+- capabilities() exposes one Zelle platform. A zelle cashout internally attaches
+  the generic method plus Chase, Bank of America, and Citi buyer routes.
 - Resume any order from its depositId alone (composite escrow_onchainId).
 - One unwind verb: withdraw(depositId) - prunes expired intents automatically;
   pass amount for a partial withdrawal of the unlocked balance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zkp2p/cash",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Peer Cash - offramp-only SDK for routing crypto to Base USDC, then cashing out to fiat at the live oracle market rate.",
   "license": "MIT",
   "author": "Peer (https://peer.xyz)",
@@ -92,13 +92,15 @@
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
-    "lint": "eslint src test examples",
+    "lint": "eslint src test examples scripts",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "test": "vitest run",
     "test:watch": "vitest",
     "audit": "bun audit --production",
     "pack:check": "bun scripts/check-packed-package.ts",
+    "verify:production-crosschain-relay": "bun scripts/verify-production-crosschain-relay.ts",
+    "verify:production-maker": "bun scripts/verify-production-maker.ts",
     "prepack": "bun run build",
     "ci": "bun run typecheck && bun run lint && bun run format:check && bun run test && bun run audit && bun run build && bun run pack:check"
   },