@zkp2p/cash 0.1.5 → 0.1.6

package/README.md

@@ -5,12 +5,25 @@ on Venmo, Revolut, Wise, Zelle, and more at the live Chainlink market rate,
 with zero spread and no centralized off-ramp provider.
 
 Peer Cash is an **offramp-only** SDK for the [ZKP2P](https://peer.xyz)
-protocol. The cashing-out user is the maker: their USDC becomes a
-protocol-held deposit, Peer handles the buyer side, and the SDK gives the
-integrator a small set of typed verbs plus readable order state. No hosted
-widget, no provider custody, no quote engine to maintain.
+protocol. The cashing-out user is the maker: their USDC becomes a deposit in
+the protocol contracts, a buyer pays them fiat and proves the payment, and the
+SDK gives the integrator a small set of typed verbs plus readable order state.
+No hosted widget, no provider custody, no quote engine to maintain.
 
-**[Live demo](https://react-cashout-demo.vercel.app)** · **[Product page](https://peer.xyz/cash)**
+**[npm](https://www.npmjs.com/package/@zkp2p/cash)** · **[Lifecycle and recovery](docs/lifecycle-and-recovery.md)** · **[Agent integration manual](AGENTS.md)**
+
+## Pick the right SDK
+
+Peer Cash and the general ZKP2P SDK serve different integration depths:
+
+| Package       | Use it when                                       | Boundary                                                                                                                                                                                  |
+| ------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@zkp2p/cash` | Cash-out is the product                           | Offramp only. The user is always the maker, the destination is Base USDC, pricing is the live Chainlink rate at fill with zero spread, and the SDK owns the resumable order lifecycle.    |
+| `@zkp2p/sdk`  | You are composing directly with the Peer protocol | General maker and taker operations, deposits, intents, proofs, quotes, vaults, rate managers, referrals, hooks, and API helpers. Your application owns the workflow and protocol choices. |
+
+Peer Cash is a narrow facade over `@zkp2p/sdk`, not a replacement for it. It
+cannot express custom spreads, buyer-side proof flows, vaults, disputes, or
+arbitrary protocol operations.
 
 ```ts
 import { createCashClient, usdc } from '@zkp2p/cash';

package/dist/index.cjs

@@ -1717,32 +1717,51 @@ function createCashClient(options) {
       (transaction) => transaction.chainId === BASE_CHAIN_ID
     );
     const batchIds = baseTransactions.filter((transaction) => transaction.isBatchTx === true).map((transaction) => transaction.hash);
+    const batchExecutionFailed = (cause) => errors.sourceExecutionFailed(cause, {
+      ...executed.requestId ? { requestId: executed.requestId } : {},
+      txHashes: executed.txHashes,
+      ...executed.transactions ? { transactions: executed.transactions } : {}
+    });
     let batchTransactionHashes = [];
     if (batchIds.length > 0) {
       let batchError;
       let batchesComplete = false;
+      let batchesSucceededWithoutReceipts = false;
       for (let attempt = 0; attempt < 20; attempt++) {
         try {
           const statuses = await Promise.all(
             batchIds.map((id) => sourceSigner.getCallsStatus({ id }))
           );
           if (statuses.some((status) => status.status === "failure")) {
-            throw new Error("Relay wallet call bundle failed");
+            throw batchExecutionFailed(new Error("Relay wallet call bundle failed"));
           }
           if (statuses.every((status) => status.status === "success")) {
-            batchTransactionHashes = statuses.flatMap(
-              (status) => (status.receipts ?? []).map((receipt) => receipt.transactionHash)
-            );
-            batchesComplete = true;
-            break;
+            const receiptGroups = statuses.map((status) => status.receipts ?? []);
+            if (receiptGroups.some((receipts) => receipts.length === 0)) {
+              batchError = new Error(
+                "Relay wallet call bundle did not include transaction receipts"
+              );
+              batchesSucceededWithoutReceipts = true;
+              break;
+            } else {
+              batchTransactionHashes = receiptGroups.flatMap(
+                (receipts) => receipts.map((receipt) => receipt.transactionHash)
+              );
+              batchesComplete = true;
+              break;
+            }
           }
         } catch (err) {
+          if (isCashError(err)) throw err;
           batchError = err;
         }
         await sleep(250);
       }
       if (!batchesComplete) {
-        throw batchError ?? new Error("Relay wallet call bundle did not complete");
+        if (batchesSucceededWithoutReceipts) throw batchError;
+        throw batchExecutionFailed(
+          batchError ?? new Error("Relay wallet call bundle did not complete")
+        );
       }
     }
     const hashes = [
@@ -1864,6 +1883,7 @@ function createCashClient(options) {
             executed
           );
         } catch (err) {
+          if (isCashError(err)) throw err;
           throw errors.sourceRouteCompletedCashoutFailed(
             routedSource,
             mapChainError("resolve same-chain Relay nonce", err)

package/dist/index.js

@@ -1344,32 +1344,51 @@ function createCashClient(options) {
       (transaction) => transaction.chainId === BASE_CHAIN_ID
     );
     const batchIds = baseTransactions.filter((transaction) => transaction.isBatchTx === true).map((transaction) => transaction.hash);
+    const batchExecutionFailed = (cause) => errors.sourceExecutionFailed(cause, {
+      ...executed.requestId ? { requestId: executed.requestId } : {},
+      txHashes: executed.txHashes,
+      ...executed.transactions ? { transactions: executed.transactions } : {}
+    });
     let batchTransactionHashes = [];
     if (batchIds.length > 0) {
       let batchError;
       let batchesComplete = false;
+      let batchesSucceededWithoutReceipts = false;
       for (let attempt = 0; attempt < 20; attempt++) {
         try {
           const statuses = await Promise.all(
             batchIds.map((id) => sourceSigner.getCallsStatus({ id }))
           );
           if (statuses.some((status) => status.status === "failure")) {
-            throw new Error("Relay wallet call bundle failed");
+            throw batchExecutionFailed(new Error("Relay wallet call bundle failed"));
           }
           if (statuses.every((status) => status.status === "success")) {
-            batchTransactionHashes = statuses.flatMap(
-              (status) => (status.receipts ?? []).map((receipt) => receipt.transactionHash)
-            );
-            batchesComplete = true;
-            break;
+            const receiptGroups = statuses.map((status) => status.receipts ?? []);
+            if (receiptGroups.some((receipts) => receipts.length === 0)) {
+              batchError = new Error(
+                "Relay wallet call bundle did not include transaction receipts"
+              );
+              batchesSucceededWithoutReceipts = true;
+              break;
+            } else {
+              batchTransactionHashes = receiptGroups.flatMap(
+                (receipts) => receipts.map((receipt) => receipt.transactionHash)
+              );
+              batchesComplete = true;
+              break;
+            }
           }
         } catch (err) {
+          if (isCashError(err)) throw err;
           batchError = err;
         }
         await sleep(250);
       }
       if (!batchesComplete) {
-        throw batchError ?? new Error("Relay wallet call bundle did not complete");
+        if (batchesSucceededWithoutReceipts) throw batchError;
+        throw batchExecutionFailed(
+          batchError ?? new Error("Relay wallet call bundle did not complete")
+        );
       }
     }
     const hashes = [
@@ -1491,6 +1510,7 @@ function createCashClient(options) {
             executed
           );
         } catch (err) {
+          if (isCashError(err)) throw err;
           throw errors.sourceRouteCompletedCashoutFailed(
             routedSource,
             mapChainError("resolve same-chain Relay nonce", err)

package/dist/tools.cjs

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

package/dist/tools.js

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

package/llms.txt

@@ -3,8 +3,8 @@
 > Offramp-only SDK for the ZKP2P protocol: route any Relay-supported EVM source
 > asset to Base USDC, then cash out to fiat (Venmo, Revolut, Wise, Zelle, ...)
 > at the live Chainlink oracle market rate with zero spread and no centralized
-> off-ramp provider. The user is the maker, Peer handles the buyer side, and the
-> SDK exposes readable order state.
+> off-ramp provider. The user is the maker, a buyer pays them fiat and proves
+> the payment, and the SDK exposes readable order state.
 > Base-USDC flows are serializable through prepare paths; source-routed cashout
 > uses Relay execution first. React apps, Node services, and agent hosts use the
 > same typed surface.
@@ -59,9 +59,8 @@ Key facts:
 
 ## Links
 
-- Live demo: https://react-cashout-demo.vercel.app
-- Product page: https://peer.xyz/cash
 - npm: https://www.npmjs.com/package/@zkp2p/cash
+- Source: https://github.com/zkp2p/peer-cash
 
 ## Docs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zkp2p/cash",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "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)",
@@ -12,7 +12,14 @@
   "publishConfig": {
     "access": "public"
   },
-  "homepage": "https://peer.xyz/cash",
+  "homepage": "https://github.com/zkp2p/peer-cash#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zkp2p/peer-cash.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zkp2p/peer-cash/issues"
+  },
   "keywords": [
     "zkp2p",
     "peer",
@@ -98,7 +105,7 @@
   "dependencies": {
     "@relayprotocol/relay-sdk": "^6.1.3",
     "@zkp2p/sdk": "^0.8.1",
-    "zod": "^3.24.1"
+    "zod": "^3.25.76"
   },
   "peerDependencies": {
     "react": ">=18",
@@ -110,19 +117,19 @@
     }
   },
   "devDependencies": {
-    "@eslint/js": "^9.17.0",
-    "@types/node": "^22.10.2",
-    "@types/react": "^19.0.2",
+    "@eslint/js": "^9.39.5",
+    "@types/node": "^22.20.1",
+    "@types/react": "^19.2.17",
     "@types/react-test-renderer": "19.1.0",
-    "eslint": "^9.17.0",
-    "eslint-config-prettier": "^9.1.0",
-    "prettier": "^3.4.2",
-    "react": "^19.0.0",
+    "eslint": "^9.39.5",
+    "eslint-config-prettier": "^9.1.2",
+    "prettier": "^3.9.5",
+    "react": "^19.2.7",
     "react-test-renderer": "19.2.7",
-    "tsup": "^8.3.5",
-    "typescript": "^5.7.2",
-    "typescript-eslint": "^8.18.1",
-    "viem": "^2.55.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.63.0",
+    "viem": "^2.55.1",
     "vitest": "^4.1.10"
   }
 }