@zkp2p/cash 0.2.0 → 0.3.0-rc.0

package/dist/tools.d.cts

@@ -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.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.2.0"};
+  version: "0.3.0-rc.0"};
 
 // 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,7 +132,9 @@ 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? }>`. Generic Zelle
+`Record<string, { fills, medianFillSeconds? }>`. Keys are exact
+`platform:currency` pairs or sorted sets such as `revolut:EUR+GBP+USD`; set
+medians measure time to the first fill in any offered currency. 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.
@@ -281,6 +285,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.                  |
@@ -295,6 +300,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

@@ -22,10 +22,11 @@ Key facts:
   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.
+  `platform:currency` or a sorted set such as `revolut:EUR+GBP+USD`. Set
+  medians measure time to the first fill in any offered 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.
 - 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zkp2p/cash",
-  "version": "0.2.0",
+  "version": "0.3.0-rc.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.9.0",
+    "@zkp2p/sdk": "0.10.0-rc.7",
     "zod": "^3.25.76"
   },
   "peerDependencies": {