@zkp2p/cash 0.1.4 → 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/{createCashClient-BbkfxILl.d.cts → createCashClient-jUA_GNdh.d.cts}

@@ -272,6 +272,8 @@ interface RelayExecutionResult {
 interface RelayTransaction {
     hash: string;
     chainId: number;
+    /** Relay batch-call identifiers are not transaction hashes. */
+    isBatchTx?: boolean | undefined;
 }
 interface RelayStatus {
     requestId: string;

package/dist/{createCashClient-BbkfxILl.d.ts → createCashClient-jUA_GNdh.d.ts}

@@ -272,6 +272,8 @@ interface RelayExecutionResult {
 interface RelayTransaction {
     hash: string;
     chainId: number;
+    /** Relay batch-call identifiers are not transaction hashes. */
+    isBatchTx?: boolean | undefined;
 }
 interface RelayStatus {
     requestId: string;

package/dist/index.cjs

@@ -980,10 +980,18 @@ function collectRelayTransactions(steps, sourceChainId) {
   for (const step of steps) {
     for (const item of step.items) {
       for (const tx of item.internalTxHashes ?? []) {
-        record({ hash: tx.txHash, chainId: tx.chainId });
+        record({
+          hash: tx.txHash,
+          chainId: tx.chainId,
+          ...tx.isBatchTx ? { isBatchTx: true } : {}
+        });
       }
       for (const tx of item.txHashes ?? []) {
-        record({ hash: tx.txHash, chainId: tx.chainId });
+        record({
+          hash: tx.txHash,
+          chainId: tx.chainId,
+          ...tx.isBatchTx ? { isBatchTx: true } : {}
+        });
       }
     }
   }
@@ -1703,6 +1711,97 @@ function createCashClient(options) {
     }
     throw errors.allowanceNotVisible(amount, lastReadError);
   }
+  async function waitForBaseSignerAfterRelay(client, cashoutSigner, sourceSigner, owner, sourceChainId, executed) {
+    if (sourceChainId !== BASE_CHAIN_ID) return;
+    const baseTransactions = (executed.transactions?.origin ?? []).filter(
+      (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 batchExecutionFailed(new Error("Relay wallet call bundle failed"));
+          }
+          if (statuses.every((status) => status.status === "success")) {
+            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) {
+        if (batchesSucceededWithoutReceipts) throw batchError;
+        throw batchExecutionFailed(
+          batchError ?? new Error("Relay wallet call bundle did not complete")
+        );
+      }
+    }
+    const hashes = [
+      ...baseTransactions.filter((transaction) => transaction.isBatchTx !== true).map((transaction) => transaction.hash),
+      ...batchTransactionHashes
+    ];
+    if (hashes.length === 0) return;
+    let transactions;
+    let lastLookupError;
+    for (let attempt = 0; attempt < 20; attempt++) {
+      try {
+        transactions = await Promise.all(
+          hashes.map((hash) => client.publicClient.getTransaction({ hash }))
+        );
+        break;
+      } catch (err) {
+        lastLookupError = err;
+        await sleep(250);
+      }
+    }
+    if (!transactions) throw lastLookupError;
+    const ownerNonces = transactions.filter((transaction) => transaction.from.toLowerCase() === owner.toLowerCase()).map((transaction) => transaction.nonce);
+    if (ownerNonces.length === 0) return;
+    const afterRelay = Math.max(...ownerNonces) + 1;
+    let lastNonceError;
+    for (let attempt = 0; attempt < 20; attempt++) {
+      try {
+        const pendingHex = await cashoutSigner.transport.request({
+          method: "eth_getTransactionCount",
+          params: [owner, "pending"]
+        });
+        if (Number(BigInt(pendingHex)) >= afterRelay) return;
+      } catch (err) {
+        lastNonceError = err;
+      }
+      await sleep(250);
+    }
+    if (lastNonceError) throw lastNonceError;
+    throw new Error(`Signer provider did not observe Relay nonce ${afterRelay - 1}`);
+  }
   return {
     capabilities,
     async sourceCapabilities() {
@@ -1774,6 +1873,22 @@ function createCashClient(options) {
           ...executed.transactions ? { transactions: executed.transactions } : {}
         };
         sourceResult = routedSource;
+        try {
+          await waitForBaseSignerAfterRelay(
+            client,
+            opts.signer,
+            sourceSigner,
+            owner,
+            input.source.chainId,
+            executed
+          );
+        } catch (err) {
+          if (isCashError(err)) throw err;
+          throw errors.sourceRouteCompletedCashoutFailed(
+            routedSource,
+            mapChainError("resolve same-chain Relay nonce", err)
+          );
+        }
         const attributedParams2 = { ...params2, txOverrides: attribution };
         const send2 = async () => {
           try {
@@ -2146,7 +2261,8 @@ var bigintString = zod.z.string().regex(/^-?\d+$/, "expected a decimal bigint st
 var nonNegativeBigintString = zod.z.string().regex(/^\d+$/, "expected a non-negative decimal bigint string");
 var relayTransactionJsonSchema = zod.z.object({
   hash: zod.z.string(),
-  chainId: zod.z.number()
+  chainId: zod.z.number(),
+  isBatchTx: zod.z.boolean().optional()
 });
 var relayTransactionsJsonSchema = zod.z.object({
   origin: zod.z.array(relayTransactionJsonSchema),