@zkp2p/cash 0.1.9 → 0.2.1

package/dist/tools.d.ts

@@ -166,20 +166,39 @@ declare const builtInCashTools: readonly [{
                         readonly type: "string";
                         readonly description: "Fiat currency code, e.g. \"USD\"";
                     };
+                    readonly currencies: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly uniqueItems: true;
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly description: "Fiat currency choices for one payment method, e.g. [\"EUR\", \"GBP\"]";
+                    };
                     readonly payee: {
-                        readonly type: "object";
-                        readonly description: "Payee handle for the platform";
-                        readonly properties: {
-                            readonly offchainId: {
-                                readonly type: "string";
-                                readonly description: "The handle, e.g. \"@andrew\" for Venmo - see payeeHint in cash_capabilities";
+                        readonly description: "Raw payee handle or structured curator payee data";
+                        readonly oneOf: readonly [{
+                            readonly type: "string";
+                            readonly description: "User-entered handle, e.g. \"@andrew\" for Venmo; Peer Cash normalizes it for the selected platform";
+                        }, {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly offchainId: {
+                                    readonly type: "string";
+                                    readonly description: "Already-normalized handle for the platform";
+                                };
                             };
-                        };
-                        readonly required: readonly ["offchainId"];
-                        readonly additionalProperties: true;
+                            readonly required: readonly ["offchainId"];
+                            readonly additionalProperties: true;
+                        }];
                     };
                 };
-                readonly required: readonly ["platform", "currency", "payee"];
+                readonly required: readonly ["platform", "payee"];
+                readonly oneOf: readonly [{
+                    readonly required: readonly ["currency"];
+                }, {
+                    readonly required: readonly ["currencies"];
+                }];
                 readonly additionalProperties: false;
             };
         };

package/dist/tools.js

@@ -1,6 +1,6 @@
 // package.json
 var package_default = {
-  version: "0.1.9"};
+  version: "0.2.1"};
 
 // src/tools/index.ts
 var bigintString = {
@@ -135,20 +135,36 @@ var builtInCashTools = [
               description: 'Platform id from cash_capabilities, e.g. "venmo"'
             },
             currency: { type: "string", description: 'Fiat currency code, e.g. "USD"' },
+            currencies: {
+              type: "array",
+              minItems: 1,
+              uniqueItems: true,
+              items: { type: "string" },
+              description: 'Fiat currency choices for one payment method, e.g. ["EUR", "GBP"]'
+            },
             payee: {
-              type: "object",
-              description: "Payee handle for the platform",
-              properties: {
-                offchainId: {
+              description: "Raw payee handle or structured curator payee data",
+              oneOf: [
+                {
                   type: "string",
-                  description: 'The handle, e.g. "@andrew" for Venmo - see payeeHint in cash_capabilities'
+                  description: 'User-entered handle, e.g. "@andrew" for Venmo; Peer Cash normalizes it for the selected platform'
+                },
+                {
+                  type: "object",
+                  properties: {
+                    offchainId: {
+                      type: "string",
+                      description: "Already-normalized handle for the platform"
+                    }
+                  },
+                  required: ["offchainId"],
+                  additionalProperties: true
                 }
-              },
-              required: ["offchainId"],
-              additionalProperties: true
+              ]
             }
           },
-          required: ["platform", "currency", "payee"],
+          required: ["platform", "payee"],
+          oneOf: [{ required: ["currency"] }, { required: ["currencies"] }],
           additionalProperties: false
         }
       },

package/docs/lifecycle-and-recovery.md

@@ -61,7 +61,9 @@ The unsigned `prepare()` path is Base-USDC-only and rejects `source` with
 `SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE`. The tool manifest follows the same
 boundary: `cash_source_quote` and `cash_source_status` quote and observe Relay,
 but the host or a signer-backed client must execute the route before
-`cash_cashout` prepares the Base-USDC order.
+`cash_cashout` prepares the Base-USDC order. Once the prepared `createDeposit`
+transaction confirms, call `finalizePreparedCashout(receipt)` to decode it with
+the environment-correct escrow ABI and obtain the resumable `CashoutResult`.
 
 There is no static chain/token allowlist in Peer Cash. Relay decides source
 support through its metadata and quote execution, filtered to the viem/EVM
@@ -130,8 +132,8 @@ 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.
@@ -195,6 +197,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
@@ -276,6 +283,7 @@ explicit override.
 | `UNSUPPORTED_PLATFORM_CURRENCY`         | no        | The platform does not support that currency. Use its `capabilities()` currencies.                                                            |
 | `AMOUNT_BELOW_MINIMUM`                  | no        | Amount is below the $0.01 hard floor. The recommended minimum is 1 USDC.                                                                     |
 | `INVALID_INTENT_AMOUNT_RANGE`           | no        | Min/max is non-positive, inverted, or exceeds the deposit. Correct the range.                                                                |
+| `INVALID_PAYOUT_CURRENCIES`             | no        | The currency set is empty or contains duplicates. Pass a non-empty unique set from `capabilities()`.                                         |
 | `PAYEE_VERIFICATION_REQUIRED`           | no        | A new Wise/PayPal payee needs an attestation. Register it through Peer first; an existing registration can be reused.                        |
 | `PAYEE_REGISTRATION_FAILED`             | yes       | Curator rejected the handle or was unavailable. Check `payeeHint` and retry.                                                                 |
 | `SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE`   | no        | `prepare()` accepts Base USDC only. Use signed source execution, or complete Relay first and then prepare the Base cashout.                  |
@@ -290,6 +298,7 @@ explicit override.
 | `SOURCE_CASHOUT_STATUS_UNKNOWN`         | no        | Relay completed and the Base tx was submitted, but its receipt is unknown. Inspect `depositTxHash`; do not resubmit while status is unknown. |
 | `INSUFFICIENT_TOKEN_BALANCE`            | no        | Wallet lacks the required token amount. Fund it, then retry.                                                                                 |
 | `ALLOWANCE_NOT_VISIBLE`                 | yes       | Approval mined but a stale RPC replica hid it. Retry the same call after the allowance becomes visible.                                      |
+| `TRANSACTION_REJECTED`                  | yes       | The wallet request was cancelled before broadcast. Retry when ready.                                                                         |
 | `TRANSACTION_FAILED`                    | no        | The on-chain call failed or reverted. Inspect the cause and transaction before another action.                                               |
 | `TRANSACTION_SUBMISSION_UNKNOWN`        | no        | A Base mutation returned no hash but may have broadcast. Inspect wallet/protocol state and its recovery action before any retry.             |
 | `TRANSACTION_STATUS_UNKNOWN`            | no        | A transaction was submitted but its receipt is unknown. Inspect `recovery.transactionHash` before resubmitting.                              |

package/llms.txt

@@ -29,8 +29,8 @@ Key facts:
 - 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.
+- 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.
@@ -56,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.9",
+  "version": "0.2.1",
   "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": {