@zkp2p/cash 0.1.8 → 0.2.0

package/dist/index.js

@@ -287,35 +287,41 @@ function toPricing(tuple) {
   };
 }
 function derivePayouts(paymentMethods, currencies, catalog) {
-  return paymentMethods.flatMap((method) => {
+  const payouts = [];
+  for (const method of paymentMethods) {
     const platformHash = method.paymentMethodHash ?? "";
     if (!platformHash) return [];
     let platform;
     try {
       platform = resolvePaymentMethodNameFromHash(platformHash, catalog);
     } catch {
-      platform = void 0;
+      return [];
     }
+    if (!platform) return [];
     const tuples = currencies.filter(
       (c) => (c.paymentMethodHash ?? "").toLowerCase() === platformHash.toLowerCase()
     );
     const base2 = {
-      ...platform !== void 0 ? { platform } : {},
+      platform,
       platformHash,
       payeeHash: method.payeeDetailsHash ?? "",
       active: method.active ?? true
     };
-    if (tuples.length === 0) return [{ ...base2, pricing: toPricing(void 0) }];
-    return tuples.map((tuple) => {
+    if (tuples.length === 0) {
+      payouts.push({ ...base2, pricing: toPricing(void 0) });
+      continue;
+    }
+    for (const tuple of tuples) {
       const currency = tuple.currencyCode != null ? getCurrencyCodeFromHash(tuple.currencyCode) : void 0;
-      return {
+      payouts.push({
         ...base2,
         ...currency !== void 0 ? { currency } : {},
         ...tuple.currencyCode != null ? { currencyHash: tuple.currencyCode } : {},
         pricing: toPricing(tuple)
-      };
-    });
-  });
+      });
+    }
+  }
+  return payouts;
 }
 
 // src/engine/buyerProfile.ts
@@ -387,26 +393,6 @@ 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 = {
@@ -425,20 +411,13 @@ var PAYEE_HINTS = {
 var IDENTITY_ATTESTATION_PLATFORMS = /* @__PURE__ */ new Set(["wise", "paypal"]);
 function buildCapabilities(environment) {
   const catalog = getPaymentMethodsCatalog(BASE_CHAIN_ID, environment);
-  const currenciesByPlatform = /* @__PURE__ */ new Map();
-  for (const [method, entry] of Object.entries(catalog)) {
-    const platform = basePlatformForMethod(method);
+  const platforms = Object.entries(catalog).map(([platform, entry]) => {
     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: [...currencies2].sort(),
+      currencies: [...new Set(currencies2)].sort(),
       payeeHint: PAYEE_HINTS[platform] ?? "Your payment handle for this platform",
       requiresIdentityAttestation: IDENTITY_ATTESTATION_PLATFORMS.has(platform)
     };
@@ -517,7 +496,7 @@ function computeFillStatsSample(deposits, nowSeconds, environment) {
       }
       const currency = normalizeCurrencyCode(intent.fiatCurrency);
       if (!method || !currency) continue;
-      const pair = `${basePlatformForMethod(method)}:${currency}`;
+      const pair = `${method}:${currency}`;
       fillCounts.set(pair, (fillCounts.get(pair) ?? 0) + 1);
       if (createdAt === void 0 || createdAt < windowStart || fulfilledAt < createdAt) continue;
       const previousPairFill = firstFillByPair.get(pair);
@@ -580,18 +559,18 @@ async function readFillStatsSample(client, environment) {
   }
   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);
+function fillEtaFromSample(sample, input) {
   const currency = input.currency.toUpperCase();
-  const seconds = input.platform ? sample.stats[`${basePlatformForMethod(input.platform)}:${currency}`]?.medianFillSeconds : sample.medianFillSecondsByCurrency.get(currency);
+  const seconds = input.platform ? sample.stats[`${input.platform}:${currency}`]?.medianFillSeconds : sample.medianFillSecondsByCurrency.get(currency);
   return {
     ...seconds !== void 0 ? { seconds } : {},
     label: etaLabel(seconds)
   };
 }
+async function readFillEta(client, input) {
+  const sample = await readFillStatsSample(client, input.environment);
+  return fillEtaFromSample(sample, input);
+}
 var RELAY_API_URL = MAINNET_RELAY_API;
 var NATIVE_TOKEN_ADDRESS = "0x0000000000000000000000000000000000000000";
 var BASE_USDC_ASSET = {
@@ -1127,13 +1106,18 @@ async function readEstimate(publicClient, input, context = {}) {
       }
     } : {}
   };
-  if (context.indexerClient && context.environment) {
+  if (context.includeEta !== false && context.environment) {
     try {
-      estimate.eta = await readFillEta(context.indexerClient, {
+      const etaInput = {
         environment: context.environment,
         currency,
         ...input.platform ? { platform: input.platform } : {}
-      });
+      };
+      if (context.etaReader) {
+        estimate.eta = await context.etaReader(etaInput);
+      } else if (context.indexerClient) {
+        estimate.eta = await readFillEta(context.indexerClient, etaInput);
+      }
     } catch {
     }
   }
@@ -1142,6 +1126,7 @@ async function readEstimate(publicClient, input, context = {}) {
 
 // src/client/createCashClient.ts
 var DEFAULT_RPC_URL = "https://mainnet.base.org";
+var FILL_STATS_CACHE_MS = 15 * 60 * 1e3;
 var CASH_ATTRIBUTION_CODE = "peer-cash";
 var DEFAULT_CURATOR_URLS = {
   preproduction: "https://api-preprod.zkp2p.xyz",
@@ -1240,6 +1225,25 @@ function createCashClient(options) {
     });
   }
   const readClient = buildSdkClient(createWalletClient({ chain: base, transport }));
+  let fillStatsCache = null;
+  let fillStatsRequest = null;
+  async function getFillStatsSample() {
+    if (fillStatsCache && fillStatsCache.expiresAt > Date.now()) {
+      return fillStatsCache.sample;
+    }
+    if (fillStatsRequest) return fillStatsRequest;
+    fillStatsRequest = readFillStatsSample(readClient, environment);
+    try {
+      const sample = await fillStatsRequest;
+      fillStatsCache = {
+        sample,
+        expiresAt: Date.now() + FILL_STATS_CACHE_MS
+      };
+      return sample;
+    } finally {
+      fillStatsRequest = null;
+    }
+  }
   const signingClients = /* @__PURE__ */ new WeakMap();
   async function signingClient(verb, opts) {
     const signer = opts?.signer;
@@ -1254,7 +1258,6 @@ 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
     );
@@ -1265,13 +1268,14 @@ function createCashClient(options) {
     if (!platform.currencies.includes(receive.currency)) {
       throw errors.unsupportedPlatformCurrency(receive.platform, receive.currency);
     }
-    const paymentMethods = paymentMethodsForPlatform(receive.platform, catalog);
     return {
-      payouts: paymentMethods.map((processorName) => ({
-        processorName,
-        currency: receive.currency,
-        payeeData: receive.payee
-      }))
+      payouts: [
+        {
+          processorName: receive.platform,
+          currency: receive.currency,
+          payeeData: receive.payee
+        }
+      ]
     };
   }
   function validateDepositInput(amount, input, payoutInput = validatePayout(input)) {
@@ -1288,6 +1292,9 @@ function createCashClient(options) {
       ...range ? { intentAmountRange: range } : {}
     };
   }
+  function isCashPayoutSet(payouts) {
+    return payouts.length === 1 && payouts.every((payout) => payout.pricing.marketRate && payout.pricing.spreadBps === 0);
+  }
   async function buildDepositParams(client, depositInput) {
     try {
       return await prepareCashDepositParams(client, depositInput);
@@ -1342,9 +1349,10 @@ function createCashClient(options) {
       deposit.currencies ?? [],
       getPaymentMethodsCatalog(BASE_CHAIN_ID, environment)
     );
+    if (!isCashPayoutSet(payouts)) throw errors.orderNotFound(compositeId);
     return deriveCashOrder(compositeId, deposit.intents ?? [], {
       ...depositOrderOptions(deposit),
-      ...payouts.length > 0 ? { payouts } : {}
+      payouts
     });
   }
   function escrowContext(depositId) {
@@ -1542,16 +1550,17 @@ function createCashClient(options) {
     async relayStatus(requestId) {
       return readRelayStatus(requestId, options.relay);
     },
-    async estimate(input) {
+    async estimate(input, estimateOptions) {
       return readEstimate(readClient.publicClient, input, {
-        indexerClient: readClient,
         environment,
+        ...estimateOptions?.includeEta !== void 0 ? { includeEta: estimateOptions.includeEta } : {},
+        etaReader: async (etaInput) => fillEtaFromSample(await getFillStatsSample(), etaInput),
         ...options.relay ? { relay: options.relay } : {}
       });
     },
     async fillStats() {
       try {
-        return await readFillStats(readClient, environment);
+        return (await getFillStatsSample()).stats;
       } catch (err) {
         throw errors.indexerUnavailable("fill stats", err);
       }
@@ -1790,7 +1799,7 @@ function createCashClient(options) {
           deposit.currencies ?? [],
           catalog
         );
-        if (payouts.length !== 1 || !payouts.every((payout) => payout.pricing.marketRate && payout.pricing.spreadBps === 0)) {
+        if (!isCashPayoutSet(payouts)) {
           return [];
         }
         return [
@@ -2059,7 +2068,7 @@ var cashPayoutPricingJsonSchema = z.object({
   marketRate: z.boolean()
 });
 var cashPayoutInfoJsonSchema = z.object({
-  platform: z.string().optional(),
+  platform: z.string(),
   platformHash: z.string(),
   currency: z.string().optional(),
   currencyHash: z.string().optional(),

package/dist/react.cjs

@@ -9,6 +9,7 @@ function useEstimate({
   currency,
   platform,
   source,
+  includeEta = true,
   refreshIntervalMs = 0
 }) {
   const [estimate, setEstimate] = react.useState(null);
@@ -34,7 +35,7 @@ function useEstimate({
       }
       return;
     }
-    const identity = { client, amount, currency, platform, source };
+    const identity = { client, amount, currency, platform, source, includeEta };
     if (isCurrent()) {
       loadingIdentityRef.current = identity;
       errorIdentityRef.current = null;
@@ -42,12 +43,15 @@ function useEstimate({
       setError(null);
     }
     try {
-      const result = await client.estimate({
-        amount,
-        currency,
-        ...platform ? { platform } : {},
-        ...source ? { source } : {}
-      });
+      const result = await client.estimate(
+        {
+          amount,
+          currency,
+          ...platform ? { platform } : {},
+          ...source ? { source } : {}
+        },
+        { includeEta }
+      );
       if (isCurrent()) {
         estimateIdentityRef.current = identity;
         setEstimate(result);
@@ -63,7 +67,7 @@ function useEstimate({
     } finally {
       if (isCurrent()) setIsLoading(false);
     }
-  }, [client, currency, amount, platform, source]);
+  }, [client, currency, amount, platform, source, includeEta]);
   react.useEffect(() => {
     latestRequestRef.current += 1;
     estimateIdentityRef.current = null;
@@ -72,7 +76,7 @@ function useEstimate({
     setEstimate(null);
     setIsLoading(false);
     setError(null);
-  }, [client, amount, currency, platform, source]);
+  }, [client, amount, currency, platform, source, includeEta]);
   react.useEffect(() => {
     mountedRef.current = true;
     void refresh();
@@ -85,7 +89,7 @@ function useEstimate({
       if (timerRef.current) clearInterval(timerRef.current);
     };
   }, [refresh, refreshIntervalMs]);
-  const matchesCurrentIdentity = (identity) => identity?.client === client && identity.amount === amount && identity.currency === currency && identity.platform === platform && identity.source === source;
+  const matchesCurrentIdentity = (identity) => identity?.client === client && identity.amount === amount && identity.currency === currency && identity.platform === platform && identity.source === source && identity.includeEta === includeEta;
   return {
     estimate: matchesCurrentIdentity(estimateIdentityRef.current) ? estimate : null,
     isLoading: matchesCurrentIdentity(loadingIdentityRef.current) ? isLoading : false,

package/dist/react.d.cts

@@ -1,5 +1,5 @@
 import { CurrencyType } from '@zkp2p/sdk';
-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 { 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-CTEXn9FF.cjs';
 import { WalletClient } from 'viem';
 import '@relayprotocol/relay-sdk';
 
@@ -12,6 +12,8 @@ interface UseEstimateOptions {
     platform?: string | null | undefined;
     /** Optional Relay source. Omit for the Base USDC default path. */
     source?: EstimateInput['source'] | null | undefined;
+    /** Disable to render the oracle rate before loading pair fill stats separately. */
+    includeEta?: boolean;
     /** Re-fetch interval (ms) so the displayed rate tracks the market. 0 = no auto-refresh. */
     refreshIntervalMs?: number;
 }
@@ -20,7 +22,7 @@ interface UseEstimateOptions {
  * estimate; the binding rate resolves at the Chainlink oracle when a buyer
  * fills - there is no committed quote to show.
  */
-declare function useEstimate({ client, amount, currency, platform, source, refreshIntervalMs, }: UseEstimateOptions): {
+declare function useEstimate({ client, amount, currency, platform, source, includeEta, refreshIntervalMs, }: UseEstimateOptions): {
     estimate: CashEstimate | null;
     isLoading: boolean;
     error: Error | null;

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import { CurrencyType } from '@zkp2p/sdk';
-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 { 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-CTEXn9FF.js';
 import { WalletClient } from 'viem';
 import '@relayprotocol/relay-sdk';
 
@@ -12,6 +12,8 @@ interface UseEstimateOptions {
     platform?: string | null | undefined;
     /** Optional Relay source. Omit for the Base USDC default path. */
     source?: EstimateInput['source'] | null | undefined;
+    /** Disable to render the oracle rate before loading pair fill stats separately. */
+    includeEta?: boolean;
     /** Re-fetch interval (ms) so the displayed rate tracks the market. 0 = no auto-refresh. */
     refreshIntervalMs?: number;
 }
@@ -20,7 +22,7 @@ interface UseEstimateOptions {
  * estimate; the binding rate resolves at the Chainlink oracle when a buyer
  * fills - there is no committed quote to show.
  */
-declare function useEstimate({ client, amount, currency, platform, source, refreshIntervalMs, }: UseEstimateOptions): {
+declare function useEstimate({ client, amount, currency, platform, source, includeEta, refreshIntervalMs, }: UseEstimateOptions): {
     estimate: CashEstimate | null;
     isLoading: boolean;
     error: Error | null;

package/dist/react.js

@@ -7,6 +7,7 @@ function useEstimate({
   currency,
   platform,
   source,
+  includeEta = true,
   refreshIntervalMs = 0
 }) {
   const [estimate, setEstimate] = useState(null);
@@ -32,7 +33,7 @@ function useEstimate({
       }
       return;
     }
-    const identity = { client, amount, currency, platform, source };
+    const identity = { client, amount, currency, platform, source, includeEta };
     if (isCurrent()) {
       loadingIdentityRef.current = identity;
       errorIdentityRef.current = null;
@@ -40,12 +41,15 @@ function useEstimate({
       setError(null);
     }
     try {
-      const result = await client.estimate({
-        amount,
-        currency,
-        ...platform ? { platform } : {},
-        ...source ? { source } : {}
-      });
+      const result = await client.estimate(
+        {
+          amount,
+          currency,
+          ...platform ? { platform } : {},
+          ...source ? { source } : {}
+        },
+        { includeEta }
+      );
       if (isCurrent()) {
         estimateIdentityRef.current = identity;
         setEstimate(result);
@@ -61,7 +65,7 @@ function useEstimate({
     } finally {
       if (isCurrent()) setIsLoading(false);
     }
-  }, [client, currency, amount, platform, source]);
+  }, [client, currency, amount, platform, source, includeEta]);
   useEffect(() => {
     latestRequestRef.current += 1;
     estimateIdentityRef.current = null;
@@ -70,7 +74,7 @@ function useEstimate({
     setEstimate(null);
     setIsLoading(false);
     setError(null);
-  }, [client, amount, currency, platform, source]);
+  }, [client, amount, currency, platform, source, includeEta]);
   useEffect(() => {
     mountedRef.current = true;
     void refresh();
@@ -83,7 +87,7 @@ function useEstimate({
       if (timerRef.current) clearInterval(timerRef.current);
     };
   }, [refresh, refreshIntervalMs]);
-  const matchesCurrentIdentity = (identity) => identity?.client === client && identity.amount === amount && identity.currency === currency && identity.platform === platform && identity.source === source;
+  const matchesCurrentIdentity = (identity) => identity?.client === client && identity.amount === amount && identity.currency === currency && identity.platform === platform && identity.source === source && identity.includeEta === includeEta;
   return {
     estimate: matchesCurrentIdentity(estimateIdentityRef.current) ? estimate : null,
     isLoading: matchesCurrentIdentity(loadingIdentityRef.current) ? isLoading : false,

package/dist/tools.cjs

@@ -2,7 +2,7 @@
 
 // package.json
 var package_default = {
-  version: "0.1.8"};
+  version: "0.2.0"};
 
 // src/tools/index.ts
 var bigintString = {

package/dist/tools.js

@@ -1,6 +1,6 @@
 // package.json
 var package_default = {
-  version: "0.1.8"};
+  version: "0.2.0"};
 
 // src/tools/index.ts
 var bigintString = {

package/docs/lifecycle-and-recovery.md

@@ -130,11 +130,16 @@ 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
+`Record<"platform:currency", { fills, medianFillSeconds? }>`. Generic Zelle
+fills are reported as `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.
+The client caches one raw environment snapshot for 15 minutes and de-duplicates
+concurrent reads; ETA resolution still uses only the requested normalized
+`platform:currency` key. A progressive UI can call
+`estimate(input, { includeEta: false })` to render rate/receive immediately,
+then read that pair from `fillStats()` without coupling the two loading states.
 
 - **Buyer arrival time is market-driven.** A deposit at market rate should
   fill fast, but the ETA is only a recent historical sample.
@@ -190,6 +195,11 @@ platform, currency, payee hash, and a pricing proof (`spreadBps: 0`,
 `kind: 'oracle_chainlink'`, `marketRate: true`): the zero-spread claim is a
 queryable fact, not marketing copy.
 
+Reconstruction is fail-closed: every payment method on the indexed deposit
+must resolve through the active SDK catalog, and the result must be exactly
+one zero-spread oracle payout. `orders()` excludes unsupported or mixed rows;
+`order()` returns `ORDER_NOT_FOUND` rather than partially reclassifying them.
+
 ## Who is this buyer?
 
 `buyer(address)` aggregates the matched buyer's full intent history into a

package/llms.txt

@@ -24,8 +24,13 @@ Key facts:
 - 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.
+  Its raw environment snapshot is cached for 15 minutes, while lookups remain
+  exact to the normalized platform:currency pair.
+- Progressive UIs can call estimate(input, { includeEta: false }) so the
+  oracle rate is not blocked by indexer history, then load the exact pair from
+  fillStats() separately.
+- capabilities() exposes one Zelle platform. A zelle cashout attaches only the
+  generic Zelle payment method to the on-chain deposit.
 - 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.
@@ -51,6 +56,8 @@ Key facts:
   payment id, released USDC, and fill latency after the proof.
 - Orders carry their payout legs (platform, currency, payee hash) plus a
   verifiable pricing proof (spreadBps: 0, oracle kind) from indexed data.
+- Order reads fail closed when any deposit method is absent from the active
+  catalog; mixed historical deposits are never partially reclassified.
 - buyer(address) aggregates a buyer's track record (fulfilled/pruned/success
   rate) from their full intent history.
 - Default path is same-chain Base USDC. Optional `source` on `cashout()` runs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zkp2p/cash",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "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)",
@@ -106,7 +106,7 @@
   },
   "dependencies": {
     "@relayprotocol/relay-sdk": "^6.1.3",
-    "@zkp2p/sdk": "^0.8.1",
+    "@zkp2p/sdk": "^0.9.0",
     "zod": "^3.25.76"
   },
   "peerDependencies": {