@zkp2p/cash 0.1.7 → 0.1.9

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-BhOytyHE.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.7"};
+  version: "0.1.9"};
 
 // 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.7"};
+  version: "0.1.9"};
 
 // 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

@@ -124,10 +124,22 @@ 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.
+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.

package/llms.txt

@@ -19,9 +19,18 @@ 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.
+  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 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.7",
+  "version": "0.1.9",
   "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"
   },