@zkp2p/cash 0.1.5 → 0.1.7

package/AGENTS.md

@@ -110,10 +110,19 @@ console.log(routed.source?.transactions?.origin, routed.source?.transactions?.de
   `sourceSigner`. Use `EXACT_INPUT` in high-level cash-out flows so `amount`
   remains source-token base units. `source.amount` is Relay's guaranteed
   minimum output and the exact Base USDC deposit amount.
+- **Use a nonce-managed source signer for routed cashouts.** Relay routes
+  with more than one source-chain transaction (approve, then route) are
+  refused preflight with `SOURCE_NONCE_MANAGER_REQUIRED` on plain local
+  accounts - create the source signer with
+  `privateKeyToAccount(pk, { nonceManager })`. Browser (`json-rpc`) wallets
+  are unaffected.
 - **Persist source evidence.** A routed result carries `requestId`, flat
   `txHashes`, and chain-aware `transactions.origin` / `.destination` arrays.
 - **Never repeat a completed or uncertain route.** On `SOURCE_EXECUTION_FAILED`,
-  inspect its Relay request and transaction recovery evidence. On
+  inspect its Relay request and transaction recovery evidence. A failed
+  approval-only route can sit in `relayStatus` `waiting` indefinitely - decide
+  from the recovery payload and origin transactions, never by waiting for a
+  terminal Relay status. On
   `SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED`, retry without `source` using
   `BigInt(err.recovery.amount)`. On `SOURCE_CASHOUT_SUBMISSION_UNKNOWN`, inspect
   Base wallet activity and `orders(err.recovery.depositor)`. On
@@ -128,7 +137,8 @@ console.log(routed.source?.transactions?.origin, routed.source?.transactions?.de
   deposit. The tx receipt you hold is the truth. Retry; `watch()` absorbs
   this automatically.
 - **Unwind with `withdraw()` only.** It is state-aware (prunes expired
-  intents first). Do not call escrow functions directly.
+  intents first). Do not call escrow functions directly. Partial withdrawals
+  increment `returnedAmount`; `totalAmount` is historical and never shrinks.
 - **Read fills as receipts.** `fiatOwed` is the buyer's obligation at the
   locked rate; after the proof, `fiatPaid`/`paymentId`/`releasedAmount` are
   the verified outcome. Reconcile against those, not your own math.
@@ -161,6 +171,7 @@ Every `CashError` carries `code`, `retryable`, `remediation`. Behavior:
 | `SOURCE_RECIPIENT_MISMATCH`             | no        | Route Base USDC to the cashout depositor                                                   |
 | `SOURCE_CAPABILITIES_FAILED`            | yes       | Retry discovery or fall back to Base USDC                                                  |
 | `SOURCE_QUOTE_FAILED`                   | yes       | Refresh capabilities and request a new canonical Base-USDC quote                           |
+| `SOURCE_NONCE_MANAGER_REQUIRED`         | no        | Preflight; recreate the source signer with viem's `nonceManager`, then quote again         |
 | `SOURCE_EXECUTION_FAILED`               | no        | Inspect source transactions and Relay status before any retry                              |
 | `SOURCE_STATUS_FAILED`                  | yes       | Retry only the status read                                                                 |
 | `SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED` | no        | Do not route again; retry Base-only with `recovery.amount`                                 |

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';
@@ -94,6 +107,13 @@ The destination is always canonical Base USDC
 discovered and quoted by `@relayprotocol/relay-sdk`, not a static token
 allowlist.
 
+Routes that submit more than one source-chain transaction (approve, then
+route) require a nonce-managed source signer -
+`privateKeyToAccount(pk, { nonceManager })` from viem. Without one the SDK
+refuses the route preflight with `SOURCE_NONCE_MANAGER_REQUIRED` instead of
+letting the route transaction reuse the approval's nonce and revert
+mid-route. Browser wallets are unaffected.
+
 `capabilities()` tells you which platforms need a verified identity for a new
 payee registration (`requiresIdentityAttestation` - Wise and PayPal today).
 An already-registered Wise or PayPal handle can be reused with bare payee data.
@@ -107,6 +127,10 @@ they are available. A source-routed result includes both a flat
 `source.txHashes` list and chain-aware `source.transactions.origin` /
 `.destination` entries.
 
+- `SOURCE_EXECUTION_FAILED` where only the approval landed: the Relay request
+  can stay in `relayStatus` `waiting` indefinitely. Decide from the error's
+  recovery payload and origin transactions, never by waiting for a terminal
+  Relay status.
 - `SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED`: Relay completed, but the Base
   cashout was not created. Do not route again. Retry a Base-USDC-only
   `cashout()` with `BigInt(error.recovery.amount)`.

package/dist/{chunk-P3KYZ2FX.js → chunk-TR6JVYYF.js}

@@ -189,6 +189,12 @@ var errors = {
     },
     { cause }
   ),
+  sourceNonceManagerRequired: (transactionCount) => new CashError({
+    code: "SOURCE_NONCE_MANAGER_REQUIRED",
+    message: `This Relay route submits ${transactionCount} source-chain transactions, but the local signer has no nonce manager; the route transaction would reuse the approval nonce and revert.`,
+    retryable: false,
+    remediation: `Create the source signer with viem's nonce manager - privateKeyToAccount(pk, { nonceManager }) - then request a fresh quote and retry. No transaction was submitted.`
+  }),
   sourceExecutionFailed: (cause, evidence) => new CashError(
     {
       code: "SOURCE_EXECUTION_FAILED",

package/dist/index.cjs

@@ -623,6 +623,12 @@ var errors = {
     },
     { cause }
   ),
+  sourceNonceManagerRequired: (transactionCount) => new CashError({
+    code: "SOURCE_NONCE_MANAGER_REQUIRED",
+    message: `This Relay route submits ${transactionCount} source-chain transactions, but the local signer has no nonce manager; the route transaction would reuse the approval nonce and revert.`,
+    retryable: false,
+    remediation: `Create the source signer with viem's nonce manager - privateKeyToAccount(pk, { nonceManager }) - then request a fresh quote and retry. No transaction was submitted.`
+  }),
   sourceExecutionFailed: (cause, evidence) => new CashError(
     {
       code: "SOURCE_EXECUTION_FAILED",
@@ -1048,6 +1054,14 @@ async function assertRelayExecutionIdentity(quote, wallet, expectedRecipient) {
     throw new Error("Relay quote recipient does not match the expected Base recipient");
   }
 }
+function assertRelayNonceManagement(quote, wallet) {
+  const account = wallet.account;
+  if (!account || account.type !== "local" || account.nonceManager !== void 0) return;
+  const transactionCount = quote.steps.flatMap(
+    (step) => step.items.filter((item) => asString(asRecord(item.data).to) !== void 0)
+  ).length;
+  if (transactionCount > 1) throw errors.sourceNonceManagerRequired(transactionCount);
+}
 function isRelaySecretKey(key) {
   const normalized = key.toLowerCase();
   return normalized === "headers" || normalized === "apikey";
@@ -1249,6 +1263,7 @@ async function executeRelayQuote(quote, wallet, options = {}) {
     observedRequestId = quoteRequestId(rawQuote);
     assertCanonicalRelayDestination(rawQuote);
     await assertRelayExecutionIdentity(rawQuote, wallet, options.recipient);
+    assertRelayNonceManagement(rawQuote, wallet);
     const client = relayClient(options.relay);
     const sourceChainId = quoteSourceChainId(rawQuote);
     if (sourceChainId !== void 0 && !(client.chains ?? []).some((chain) => chain.id === sourceChainId)) {
@@ -1717,32 +1732,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 +1898,7 @@ function createCashClient(options) {
             executed
           );
         } catch (err) {
+          if (isCashError(err)) throw err;
           throw errors.sourceRouteCompletedCashoutFailed(
             routedSource,
             mapChainError("resolve same-chain Relay nonce", err)
@@ -2539,6 +2574,7 @@ var CASH_ERROR_CODES = defineCashErrorCodes([
   "SOURCE_RECIPIENT_MISMATCH",
   "SOURCE_CAPABILITIES_FAILED",
   "SOURCE_QUOTE_FAILED",
+  "SOURCE_NONCE_MANAGER_REQUIRED",
   "SOURCE_EXECUTION_FAILED",
   "SOURCE_STATUS_FAILED",
   "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED",

package/dist/index.d.cts

@@ -10,7 +10,7 @@ import '@relayprotocol/relay-sdk';
  * Typed errors - every failure carries a `code`, whether it is `retryable`,
  * and a `remediation` sentence so agents can self-drive recovery.
  */
-type CashErrorCode = 'ORACLE_UNSUPPORTED_CURRENCY' | 'ORACLE_READ_FAILED' | 'UNSUPPORTED_PLATFORM' | 'UNSUPPORTED_PLATFORM_CURRENCY' | 'AMOUNT_BELOW_MINIMUM' | 'INVALID_INTENT_AMOUNT_RANGE' | 'ACTIVE_INTENT_BLOCKS_WITHDRAWAL' | 'NOTHING_TO_WITHDRAW' | 'INSUFFICIENT_AVAILABLE_FUNDS' | 'INSUFFICIENT_TOKEN_BALANCE' | 'ORDER_NOT_ACTIVE' | 'INVALID_DEPOSIT_ID' | 'ESCROW_PAUSED' | 'INDEXER_LAG' | 'INDEXER_UNAVAILABLE' | 'ORDER_NOT_FOUND' | 'PAYEE_REGISTRATION_FAILED' | 'PAYEE_VERIFICATION_REQUIRED' | 'SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE' | 'SOURCE_RECIPIENT_MISMATCH' | 'SOURCE_CAPABILITIES_FAILED' | 'SOURCE_QUOTE_FAILED' | 'SOURCE_EXECUTION_FAILED' | 'SOURCE_STATUS_FAILED' | 'SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED' | 'SOURCE_CASHOUT_SUBMISSION_UNKNOWN' | 'SOURCE_CASHOUT_STATUS_UNKNOWN' | 'DEPOSIT_RESOLUTION_FAILED' | 'ALLOWANCE_NOT_VISIBLE' | 'SIGNER_REQUIRED' | 'SIGNER_CHAIN_MISMATCH' | 'SIGNER_CHAIN_UNAVAILABLE' | 'WATCH_TIMEOUT' | 'TRANSACTION_FAILED' | 'TRANSACTION_SUBMISSION_UNKNOWN' | 'TRANSACTION_STATUS_UNKNOWN';
+type CashErrorCode = 'ORACLE_UNSUPPORTED_CURRENCY' | 'ORACLE_READ_FAILED' | 'UNSUPPORTED_PLATFORM' | 'UNSUPPORTED_PLATFORM_CURRENCY' | 'AMOUNT_BELOW_MINIMUM' | 'INVALID_INTENT_AMOUNT_RANGE' | 'ACTIVE_INTENT_BLOCKS_WITHDRAWAL' | 'NOTHING_TO_WITHDRAW' | 'INSUFFICIENT_AVAILABLE_FUNDS' | 'INSUFFICIENT_TOKEN_BALANCE' | 'ORDER_NOT_ACTIVE' | 'INVALID_DEPOSIT_ID' | 'ESCROW_PAUSED' | 'INDEXER_LAG' | 'INDEXER_UNAVAILABLE' | 'ORDER_NOT_FOUND' | 'PAYEE_REGISTRATION_FAILED' | 'PAYEE_VERIFICATION_REQUIRED' | 'SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE' | 'SOURCE_RECIPIENT_MISMATCH' | 'SOURCE_CAPABILITIES_FAILED' | 'SOURCE_QUOTE_FAILED' | 'SOURCE_NONCE_MANAGER_REQUIRED' | 'SOURCE_EXECUTION_FAILED' | 'SOURCE_STATUS_FAILED' | 'SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED' | 'SOURCE_CASHOUT_SUBMISSION_UNKNOWN' | 'SOURCE_CASHOUT_STATUS_UNKNOWN' | 'DEPOSIT_RESOLUTION_FAILED' | 'ALLOWANCE_NOT_VISIBLE' | 'SIGNER_REQUIRED' | 'SIGNER_CHAIN_MISMATCH' | 'SIGNER_CHAIN_UNAVAILABLE' | 'WATCH_TIMEOUT' | 'TRANSACTION_FAILED' | 'TRANSACTION_SUBMISSION_UNKNOWN' | 'TRANSACTION_STATUS_UNKNOWN';
 interface CashErrorShape {
     code: CashErrorCode;
     message: string;
@@ -92,6 +92,7 @@ declare const errors: {
     sourceRecipientMismatch: (recipient: string, owner: string) => CashError;
     sourceCapabilitiesFailed: (cause?: unknown) => CashError;
     sourceQuoteFailed: (cause?: unknown) => CashError;
+    sourceNonceManagerRequired: (transactionCount: number) => CashError;
     sourceExecutionFailed: (cause?: unknown, evidence?: {
         requestId?: string;
         txHashes: string[];
@@ -3153,7 +3154,7 @@ declare const cashErrorRecoveryJsonSchema: z.ZodDiscriminatedUnion<"kind", [z.Zo
     operation: string;
 }>]>;
 declare const cashErrorJsonSchema: z.ZodObject<{
-    code: z.ZodEnum<["ORACLE_UNSUPPORTED_CURRENCY", "ORACLE_READ_FAILED", "UNSUPPORTED_PLATFORM", "UNSUPPORTED_PLATFORM_CURRENCY", "AMOUNT_BELOW_MINIMUM", "INVALID_INTENT_AMOUNT_RANGE", "ACTIVE_INTENT_BLOCKS_WITHDRAWAL", "NOTHING_TO_WITHDRAW", "INSUFFICIENT_AVAILABLE_FUNDS", "INSUFFICIENT_TOKEN_BALANCE", "ORDER_NOT_ACTIVE", "INVALID_DEPOSIT_ID", "ESCROW_PAUSED", "INDEXER_LAG", "INDEXER_UNAVAILABLE", "ORDER_NOT_FOUND", "PAYEE_REGISTRATION_FAILED", "PAYEE_VERIFICATION_REQUIRED", "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE", "SOURCE_RECIPIENT_MISMATCH", "SOURCE_CAPABILITIES_FAILED", "SOURCE_QUOTE_FAILED", "SOURCE_EXECUTION_FAILED", "SOURCE_STATUS_FAILED", "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED", "SOURCE_CASHOUT_SUBMISSION_UNKNOWN", "SOURCE_CASHOUT_STATUS_UNKNOWN", "DEPOSIT_RESOLUTION_FAILED", "ALLOWANCE_NOT_VISIBLE", "SIGNER_REQUIRED", "SIGNER_CHAIN_MISMATCH", "SIGNER_CHAIN_UNAVAILABLE", "WATCH_TIMEOUT", "TRANSACTION_FAILED", "TRANSACTION_SUBMISSION_UNKNOWN", "TRANSACTION_STATUS_UNKNOWN"]>;
+    code: z.ZodEnum<["ORACLE_UNSUPPORTED_CURRENCY", "ORACLE_READ_FAILED", "UNSUPPORTED_PLATFORM", "UNSUPPORTED_PLATFORM_CURRENCY", "AMOUNT_BELOW_MINIMUM", "INVALID_INTENT_AMOUNT_RANGE", "ACTIVE_INTENT_BLOCKS_WITHDRAWAL", "NOTHING_TO_WITHDRAW", "INSUFFICIENT_AVAILABLE_FUNDS", "INSUFFICIENT_TOKEN_BALANCE", "ORDER_NOT_ACTIVE", "INVALID_DEPOSIT_ID", "ESCROW_PAUSED", "INDEXER_LAG", "INDEXER_UNAVAILABLE", "ORDER_NOT_FOUND", "PAYEE_REGISTRATION_FAILED", "PAYEE_VERIFICATION_REQUIRED", "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE", "SOURCE_RECIPIENT_MISMATCH", "SOURCE_CAPABILITIES_FAILED", "SOURCE_QUOTE_FAILED", "SOURCE_NONCE_MANAGER_REQUIRED", "SOURCE_EXECUTION_FAILED", "SOURCE_STATUS_FAILED", "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED", "SOURCE_CASHOUT_SUBMISSION_UNKNOWN", "SOURCE_CASHOUT_STATUS_UNKNOWN", "DEPOSIT_RESOLUTION_FAILED", "ALLOWANCE_NOT_VISIBLE", "SIGNER_REQUIRED", "SIGNER_CHAIN_MISMATCH", "SIGNER_CHAIN_UNAVAILABLE", "WATCH_TIMEOUT", "TRANSACTION_FAILED", "TRANSACTION_SUBMISSION_UNKNOWN", "TRANSACTION_STATUS_UNKNOWN"]>;
     message: z.ZodString;
     retryable: z.ZodBoolean;
     remediation: z.ZodString;
@@ -3540,7 +3541,7 @@ declare const cashErrorJsonSchema: z.ZodObject<{
     }>]>>;
 }, "strict", z.ZodTypeAny, {
     message: string;
-    code: "ORACLE_UNSUPPORTED_CURRENCY" | "ORACLE_READ_FAILED" | "UNSUPPORTED_PLATFORM" | "UNSUPPORTED_PLATFORM_CURRENCY" | "AMOUNT_BELOW_MINIMUM" | "INVALID_INTENT_AMOUNT_RANGE" | "ACTIVE_INTENT_BLOCKS_WITHDRAWAL" | "NOTHING_TO_WITHDRAW" | "INSUFFICIENT_AVAILABLE_FUNDS" | "INSUFFICIENT_TOKEN_BALANCE" | "ORDER_NOT_ACTIVE" | "INVALID_DEPOSIT_ID" | "ESCROW_PAUSED" | "INDEXER_LAG" | "INDEXER_UNAVAILABLE" | "ORDER_NOT_FOUND" | "PAYEE_REGISTRATION_FAILED" | "PAYEE_VERIFICATION_REQUIRED" | "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE" | "SOURCE_RECIPIENT_MISMATCH" | "SOURCE_CAPABILITIES_FAILED" | "SOURCE_QUOTE_FAILED" | "SOURCE_EXECUTION_FAILED" | "SOURCE_STATUS_FAILED" | "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED" | "SOURCE_CASHOUT_SUBMISSION_UNKNOWN" | "SOURCE_CASHOUT_STATUS_UNKNOWN" | "DEPOSIT_RESOLUTION_FAILED" | "ALLOWANCE_NOT_VISIBLE" | "SIGNER_REQUIRED" | "SIGNER_CHAIN_MISMATCH" | "SIGNER_CHAIN_UNAVAILABLE" | "WATCH_TIMEOUT" | "TRANSACTION_FAILED" | "TRANSACTION_SUBMISSION_UNKNOWN" | "TRANSACTION_STATUS_UNKNOWN";
+    code: "ORACLE_UNSUPPORTED_CURRENCY" | "ORACLE_READ_FAILED" | "UNSUPPORTED_PLATFORM" | "UNSUPPORTED_PLATFORM_CURRENCY" | "AMOUNT_BELOW_MINIMUM" | "INVALID_INTENT_AMOUNT_RANGE" | "ACTIVE_INTENT_BLOCKS_WITHDRAWAL" | "NOTHING_TO_WITHDRAW" | "INSUFFICIENT_AVAILABLE_FUNDS" | "INSUFFICIENT_TOKEN_BALANCE" | "ORDER_NOT_ACTIVE" | "INVALID_DEPOSIT_ID" | "ESCROW_PAUSED" | "INDEXER_LAG" | "INDEXER_UNAVAILABLE" | "ORDER_NOT_FOUND" | "PAYEE_REGISTRATION_FAILED" | "PAYEE_VERIFICATION_REQUIRED" | "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE" | "SOURCE_RECIPIENT_MISMATCH" | "SOURCE_CAPABILITIES_FAILED" | "SOURCE_QUOTE_FAILED" | "SOURCE_NONCE_MANAGER_REQUIRED" | "SOURCE_EXECUTION_FAILED" | "SOURCE_STATUS_FAILED" | "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED" | "SOURCE_CASHOUT_SUBMISSION_UNKNOWN" | "SOURCE_CASHOUT_STATUS_UNKNOWN" | "DEPOSIT_RESOLUTION_FAILED" | "ALLOWANCE_NOT_VISIBLE" | "SIGNER_REQUIRED" | "SIGNER_CHAIN_MISMATCH" | "SIGNER_CHAIN_UNAVAILABLE" | "WATCH_TIMEOUT" | "TRANSACTION_FAILED" | "TRANSACTION_SUBMISSION_UNKNOWN" | "TRANSACTION_STATUS_UNKNOWN";
     retryable: boolean;
     remediation: string;
     recovery?: {
@@ -3622,7 +3623,7 @@ declare const cashErrorJsonSchema: z.ZodObject<{
     } | undefined;
 }, {
     message: string;
-    code: "ORACLE_UNSUPPORTED_CURRENCY" | "ORACLE_READ_FAILED" | "UNSUPPORTED_PLATFORM" | "UNSUPPORTED_PLATFORM_CURRENCY" | "AMOUNT_BELOW_MINIMUM" | "INVALID_INTENT_AMOUNT_RANGE" | "ACTIVE_INTENT_BLOCKS_WITHDRAWAL" | "NOTHING_TO_WITHDRAW" | "INSUFFICIENT_AVAILABLE_FUNDS" | "INSUFFICIENT_TOKEN_BALANCE" | "ORDER_NOT_ACTIVE" | "INVALID_DEPOSIT_ID" | "ESCROW_PAUSED" | "INDEXER_LAG" | "INDEXER_UNAVAILABLE" | "ORDER_NOT_FOUND" | "PAYEE_REGISTRATION_FAILED" | "PAYEE_VERIFICATION_REQUIRED" | "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE" | "SOURCE_RECIPIENT_MISMATCH" | "SOURCE_CAPABILITIES_FAILED" | "SOURCE_QUOTE_FAILED" | "SOURCE_EXECUTION_FAILED" | "SOURCE_STATUS_FAILED" | "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED" | "SOURCE_CASHOUT_SUBMISSION_UNKNOWN" | "SOURCE_CASHOUT_STATUS_UNKNOWN" | "DEPOSIT_RESOLUTION_FAILED" | "ALLOWANCE_NOT_VISIBLE" | "SIGNER_REQUIRED" | "SIGNER_CHAIN_MISMATCH" | "SIGNER_CHAIN_UNAVAILABLE" | "WATCH_TIMEOUT" | "TRANSACTION_FAILED" | "TRANSACTION_SUBMISSION_UNKNOWN" | "TRANSACTION_STATUS_UNKNOWN";
+    code: "ORACLE_UNSUPPORTED_CURRENCY" | "ORACLE_READ_FAILED" | "UNSUPPORTED_PLATFORM" | "UNSUPPORTED_PLATFORM_CURRENCY" | "AMOUNT_BELOW_MINIMUM" | "INVALID_INTENT_AMOUNT_RANGE" | "ACTIVE_INTENT_BLOCKS_WITHDRAWAL" | "NOTHING_TO_WITHDRAW" | "INSUFFICIENT_AVAILABLE_FUNDS" | "INSUFFICIENT_TOKEN_BALANCE" | "ORDER_NOT_ACTIVE" | "INVALID_DEPOSIT_ID" | "ESCROW_PAUSED" | "INDEXER_LAG" | "INDEXER_UNAVAILABLE" | "ORDER_NOT_FOUND" | "PAYEE_REGISTRATION_FAILED" | "PAYEE_VERIFICATION_REQUIRED" | "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE" | "SOURCE_RECIPIENT_MISMATCH" | "SOURCE_CAPABILITIES_FAILED" | "SOURCE_QUOTE_FAILED" | "SOURCE_NONCE_MANAGER_REQUIRED" | "SOURCE_EXECUTION_FAILED" | "SOURCE_STATUS_FAILED" | "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED" | "SOURCE_CASHOUT_SUBMISSION_UNKNOWN" | "SOURCE_CASHOUT_STATUS_UNKNOWN" | "DEPOSIT_RESOLUTION_FAILED" | "ALLOWANCE_NOT_VISIBLE" | "SIGNER_REQUIRED" | "SIGNER_CHAIN_MISMATCH" | "SIGNER_CHAIN_UNAVAILABLE" | "WATCH_TIMEOUT" | "TRANSACTION_FAILED" | "TRANSACTION_SUBMISSION_UNKNOWN" | "TRANSACTION_STATUS_UNKNOWN";
     retryable: boolean;
     remediation: string;
     recovery?: {

package/dist/index.d.ts

@@ -10,7 +10,7 @@ import '@relayprotocol/relay-sdk';
  * Typed errors - every failure carries a `code`, whether it is `retryable`,
  * and a `remediation` sentence so agents can self-drive recovery.
  */
-type CashErrorCode = 'ORACLE_UNSUPPORTED_CURRENCY' | 'ORACLE_READ_FAILED' | 'UNSUPPORTED_PLATFORM' | 'UNSUPPORTED_PLATFORM_CURRENCY' | 'AMOUNT_BELOW_MINIMUM' | 'INVALID_INTENT_AMOUNT_RANGE' | 'ACTIVE_INTENT_BLOCKS_WITHDRAWAL' | 'NOTHING_TO_WITHDRAW' | 'INSUFFICIENT_AVAILABLE_FUNDS' | 'INSUFFICIENT_TOKEN_BALANCE' | 'ORDER_NOT_ACTIVE' | 'INVALID_DEPOSIT_ID' | 'ESCROW_PAUSED' | 'INDEXER_LAG' | 'INDEXER_UNAVAILABLE' | 'ORDER_NOT_FOUND' | 'PAYEE_REGISTRATION_FAILED' | 'PAYEE_VERIFICATION_REQUIRED' | 'SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE' | 'SOURCE_RECIPIENT_MISMATCH' | 'SOURCE_CAPABILITIES_FAILED' | 'SOURCE_QUOTE_FAILED' | 'SOURCE_EXECUTION_FAILED' | 'SOURCE_STATUS_FAILED' | 'SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED' | 'SOURCE_CASHOUT_SUBMISSION_UNKNOWN' | 'SOURCE_CASHOUT_STATUS_UNKNOWN' | 'DEPOSIT_RESOLUTION_FAILED' | 'ALLOWANCE_NOT_VISIBLE' | 'SIGNER_REQUIRED' | 'SIGNER_CHAIN_MISMATCH' | 'SIGNER_CHAIN_UNAVAILABLE' | 'WATCH_TIMEOUT' | 'TRANSACTION_FAILED' | 'TRANSACTION_SUBMISSION_UNKNOWN' | 'TRANSACTION_STATUS_UNKNOWN';
+type CashErrorCode = 'ORACLE_UNSUPPORTED_CURRENCY' | 'ORACLE_READ_FAILED' | 'UNSUPPORTED_PLATFORM' | 'UNSUPPORTED_PLATFORM_CURRENCY' | 'AMOUNT_BELOW_MINIMUM' | 'INVALID_INTENT_AMOUNT_RANGE' | 'ACTIVE_INTENT_BLOCKS_WITHDRAWAL' | 'NOTHING_TO_WITHDRAW' | 'INSUFFICIENT_AVAILABLE_FUNDS' | 'INSUFFICIENT_TOKEN_BALANCE' | 'ORDER_NOT_ACTIVE' | 'INVALID_DEPOSIT_ID' | 'ESCROW_PAUSED' | 'INDEXER_LAG' | 'INDEXER_UNAVAILABLE' | 'ORDER_NOT_FOUND' | 'PAYEE_REGISTRATION_FAILED' | 'PAYEE_VERIFICATION_REQUIRED' | 'SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE' | 'SOURCE_RECIPIENT_MISMATCH' | 'SOURCE_CAPABILITIES_FAILED' | 'SOURCE_QUOTE_FAILED' | 'SOURCE_NONCE_MANAGER_REQUIRED' | 'SOURCE_EXECUTION_FAILED' | 'SOURCE_STATUS_FAILED' | 'SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED' | 'SOURCE_CASHOUT_SUBMISSION_UNKNOWN' | 'SOURCE_CASHOUT_STATUS_UNKNOWN' | 'DEPOSIT_RESOLUTION_FAILED' | 'ALLOWANCE_NOT_VISIBLE' | 'SIGNER_REQUIRED' | 'SIGNER_CHAIN_MISMATCH' | 'SIGNER_CHAIN_UNAVAILABLE' | 'WATCH_TIMEOUT' | 'TRANSACTION_FAILED' | 'TRANSACTION_SUBMISSION_UNKNOWN' | 'TRANSACTION_STATUS_UNKNOWN';
 interface CashErrorShape {
     code: CashErrorCode;
     message: string;
@@ -92,6 +92,7 @@ declare const errors: {
     sourceRecipientMismatch: (recipient: string, owner: string) => CashError;
     sourceCapabilitiesFailed: (cause?: unknown) => CashError;
     sourceQuoteFailed: (cause?: unknown) => CashError;
+    sourceNonceManagerRequired: (transactionCount: number) => CashError;
     sourceExecutionFailed: (cause?: unknown, evidence?: {
         requestId?: string;
         txHashes: string[];
@@ -3153,7 +3154,7 @@ declare const cashErrorRecoveryJsonSchema: z.ZodDiscriminatedUnion<"kind", [z.Zo
     operation: string;
 }>]>;
 declare const cashErrorJsonSchema: z.ZodObject<{
-    code: z.ZodEnum<["ORACLE_UNSUPPORTED_CURRENCY", "ORACLE_READ_FAILED", "UNSUPPORTED_PLATFORM", "UNSUPPORTED_PLATFORM_CURRENCY", "AMOUNT_BELOW_MINIMUM", "INVALID_INTENT_AMOUNT_RANGE", "ACTIVE_INTENT_BLOCKS_WITHDRAWAL", "NOTHING_TO_WITHDRAW", "INSUFFICIENT_AVAILABLE_FUNDS", "INSUFFICIENT_TOKEN_BALANCE", "ORDER_NOT_ACTIVE", "INVALID_DEPOSIT_ID", "ESCROW_PAUSED", "INDEXER_LAG", "INDEXER_UNAVAILABLE", "ORDER_NOT_FOUND", "PAYEE_REGISTRATION_FAILED", "PAYEE_VERIFICATION_REQUIRED", "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE", "SOURCE_RECIPIENT_MISMATCH", "SOURCE_CAPABILITIES_FAILED", "SOURCE_QUOTE_FAILED", "SOURCE_EXECUTION_FAILED", "SOURCE_STATUS_FAILED", "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED", "SOURCE_CASHOUT_SUBMISSION_UNKNOWN", "SOURCE_CASHOUT_STATUS_UNKNOWN", "DEPOSIT_RESOLUTION_FAILED", "ALLOWANCE_NOT_VISIBLE", "SIGNER_REQUIRED", "SIGNER_CHAIN_MISMATCH", "SIGNER_CHAIN_UNAVAILABLE", "WATCH_TIMEOUT", "TRANSACTION_FAILED", "TRANSACTION_SUBMISSION_UNKNOWN", "TRANSACTION_STATUS_UNKNOWN"]>;
+    code: z.ZodEnum<["ORACLE_UNSUPPORTED_CURRENCY", "ORACLE_READ_FAILED", "UNSUPPORTED_PLATFORM", "UNSUPPORTED_PLATFORM_CURRENCY", "AMOUNT_BELOW_MINIMUM", "INVALID_INTENT_AMOUNT_RANGE", "ACTIVE_INTENT_BLOCKS_WITHDRAWAL", "NOTHING_TO_WITHDRAW", "INSUFFICIENT_AVAILABLE_FUNDS", "INSUFFICIENT_TOKEN_BALANCE", "ORDER_NOT_ACTIVE", "INVALID_DEPOSIT_ID", "ESCROW_PAUSED", "INDEXER_LAG", "INDEXER_UNAVAILABLE", "ORDER_NOT_FOUND", "PAYEE_REGISTRATION_FAILED", "PAYEE_VERIFICATION_REQUIRED", "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE", "SOURCE_RECIPIENT_MISMATCH", "SOURCE_CAPABILITIES_FAILED", "SOURCE_QUOTE_FAILED", "SOURCE_NONCE_MANAGER_REQUIRED", "SOURCE_EXECUTION_FAILED", "SOURCE_STATUS_FAILED", "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED", "SOURCE_CASHOUT_SUBMISSION_UNKNOWN", "SOURCE_CASHOUT_STATUS_UNKNOWN", "DEPOSIT_RESOLUTION_FAILED", "ALLOWANCE_NOT_VISIBLE", "SIGNER_REQUIRED", "SIGNER_CHAIN_MISMATCH", "SIGNER_CHAIN_UNAVAILABLE", "WATCH_TIMEOUT", "TRANSACTION_FAILED", "TRANSACTION_SUBMISSION_UNKNOWN", "TRANSACTION_STATUS_UNKNOWN"]>;
     message: z.ZodString;
     retryable: z.ZodBoolean;
     remediation: z.ZodString;
@@ -3540,7 +3541,7 @@ declare const cashErrorJsonSchema: z.ZodObject<{
     }>]>>;
 }, "strict", z.ZodTypeAny, {
     message: string;
-    code: "ORACLE_UNSUPPORTED_CURRENCY" | "ORACLE_READ_FAILED" | "UNSUPPORTED_PLATFORM" | "UNSUPPORTED_PLATFORM_CURRENCY" | "AMOUNT_BELOW_MINIMUM" | "INVALID_INTENT_AMOUNT_RANGE" | "ACTIVE_INTENT_BLOCKS_WITHDRAWAL" | "NOTHING_TO_WITHDRAW" | "INSUFFICIENT_AVAILABLE_FUNDS" | "INSUFFICIENT_TOKEN_BALANCE" | "ORDER_NOT_ACTIVE" | "INVALID_DEPOSIT_ID" | "ESCROW_PAUSED" | "INDEXER_LAG" | "INDEXER_UNAVAILABLE" | "ORDER_NOT_FOUND" | "PAYEE_REGISTRATION_FAILED" | "PAYEE_VERIFICATION_REQUIRED" | "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE" | "SOURCE_RECIPIENT_MISMATCH" | "SOURCE_CAPABILITIES_FAILED" | "SOURCE_QUOTE_FAILED" | "SOURCE_EXECUTION_FAILED" | "SOURCE_STATUS_FAILED" | "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED" | "SOURCE_CASHOUT_SUBMISSION_UNKNOWN" | "SOURCE_CASHOUT_STATUS_UNKNOWN" | "DEPOSIT_RESOLUTION_FAILED" | "ALLOWANCE_NOT_VISIBLE" | "SIGNER_REQUIRED" | "SIGNER_CHAIN_MISMATCH" | "SIGNER_CHAIN_UNAVAILABLE" | "WATCH_TIMEOUT" | "TRANSACTION_FAILED" | "TRANSACTION_SUBMISSION_UNKNOWN" | "TRANSACTION_STATUS_UNKNOWN";
+    code: "ORACLE_UNSUPPORTED_CURRENCY" | "ORACLE_READ_FAILED" | "UNSUPPORTED_PLATFORM" | "UNSUPPORTED_PLATFORM_CURRENCY" | "AMOUNT_BELOW_MINIMUM" | "INVALID_INTENT_AMOUNT_RANGE" | "ACTIVE_INTENT_BLOCKS_WITHDRAWAL" | "NOTHING_TO_WITHDRAW" | "INSUFFICIENT_AVAILABLE_FUNDS" | "INSUFFICIENT_TOKEN_BALANCE" | "ORDER_NOT_ACTIVE" | "INVALID_DEPOSIT_ID" | "ESCROW_PAUSED" | "INDEXER_LAG" | "INDEXER_UNAVAILABLE" | "ORDER_NOT_FOUND" | "PAYEE_REGISTRATION_FAILED" | "PAYEE_VERIFICATION_REQUIRED" | "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE" | "SOURCE_RECIPIENT_MISMATCH" | "SOURCE_CAPABILITIES_FAILED" | "SOURCE_QUOTE_FAILED" | "SOURCE_NONCE_MANAGER_REQUIRED" | "SOURCE_EXECUTION_FAILED" | "SOURCE_STATUS_FAILED" | "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED" | "SOURCE_CASHOUT_SUBMISSION_UNKNOWN" | "SOURCE_CASHOUT_STATUS_UNKNOWN" | "DEPOSIT_RESOLUTION_FAILED" | "ALLOWANCE_NOT_VISIBLE" | "SIGNER_REQUIRED" | "SIGNER_CHAIN_MISMATCH" | "SIGNER_CHAIN_UNAVAILABLE" | "WATCH_TIMEOUT" | "TRANSACTION_FAILED" | "TRANSACTION_SUBMISSION_UNKNOWN" | "TRANSACTION_STATUS_UNKNOWN";
     retryable: boolean;
     remediation: string;
     recovery?: {
@@ -3622,7 +3623,7 @@ declare const cashErrorJsonSchema: z.ZodObject<{
     } | undefined;
 }, {
     message: string;
-    code: "ORACLE_UNSUPPORTED_CURRENCY" | "ORACLE_READ_FAILED" | "UNSUPPORTED_PLATFORM" | "UNSUPPORTED_PLATFORM_CURRENCY" | "AMOUNT_BELOW_MINIMUM" | "INVALID_INTENT_AMOUNT_RANGE" | "ACTIVE_INTENT_BLOCKS_WITHDRAWAL" | "NOTHING_TO_WITHDRAW" | "INSUFFICIENT_AVAILABLE_FUNDS" | "INSUFFICIENT_TOKEN_BALANCE" | "ORDER_NOT_ACTIVE" | "INVALID_DEPOSIT_ID" | "ESCROW_PAUSED" | "INDEXER_LAG" | "INDEXER_UNAVAILABLE" | "ORDER_NOT_FOUND" | "PAYEE_REGISTRATION_FAILED" | "PAYEE_VERIFICATION_REQUIRED" | "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE" | "SOURCE_RECIPIENT_MISMATCH" | "SOURCE_CAPABILITIES_FAILED" | "SOURCE_QUOTE_FAILED" | "SOURCE_EXECUTION_FAILED" | "SOURCE_STATUS_FAILED" | "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED" | "SOURCE_CASHOUT_SUBMISSION_UNKNOWN" | "SOURCE_CASHOUT_STATUS_UNKNOWN" | "DEPOSIT_RESOLUTION_FAILED" | "ALLOWANCE_NOT_VISIBLE" | "SIGNER_REQUIRED" | "SIGNER_CHAIN_MISMATCH" | "SIGNER_CHAIN_UNAVAILABLE" | "WATCH_TIMEOUT" | "TRANSACTION_FAILED" | "TRANSACTION_SUBMISSION_UNKNOWN" | "TRANSACTION_STATUS_UNKNOWN";
+    code: "ORACLE_UNSUPPORTED_CURRENCY" | "ORACLE_READ_FAILED" | "UNSUPPORTED_PLATFORM" | "UNSUPPORTED_PLATFORM_CURRENCY" | "AMOUNT_BELOW_MINIMUM" | "INVALID_INTENT_AMOUNT_RANGE" | "ACTIVE_INTENT_BLOCKS_WITHDRAWAL" | "NOTHING_TO_WITHDRAW" | "INSUFFICIENT_AVAILABLE_FUNDS" | "INSUFFICIENT_TOKEN_BALANCE" | "ORDER_NOT_ACTIVE" | "INVALID_DEPOSIT_ID" | "ESCROW_PAUSED" | "INDEXER_LAG" | "INDEXER_UNAVAILABLE" | "ORDER_NOT_FOUND" | "PAYEE_REGISTRATION_FAILED" | "PAYEE_VERIFICATION_REQUIRED" | "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE" | "SOURCE_RECIPIENT_MISMATCH" | "SOURCE_CAPABILITIES_FAILED" | "SOURCE_QUOTE_FAILED" | "SOURCE_NONCE_MANAGER_REQUIRED" | "SOURCE_EXECUTION_FAILED" | "SOURCE_STATUS_FAILED" | "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED" | "SOURCE_CASHOUT_SUBMISSION_UNKNOWN" | "SOURCE_CASHOUT_STATUS_UNKNOWN" | "DEPOSIT_RESOLUTION_FAILED" | "ALLOWANCE_NOT_VISIBLE" | "SIGNER_REQUIRED" | "SIGNER_CHAIN_MISMATCH" | "SIGNER_CHAIN_UNAVAILABLE" | "WATCH_TIMEOUT" | "TRANSACTION_FAILED" | "TRANSACTION_SUBMISSION_UNKNOWN" | "TRANSACTION_STATUS_UNKNOWN";
     retryable: boolean;
     remediation: string;
     recovery?: {

package/dist/index.js

@@ -1,5 +1,5 @@
-import { MARKET_SPREAD_BPS, ORACLE_MIN_CONVERSION_RATE_SENTINEL, CASH_RETAIN_ON_EMPTY, BASE_USDC_ADDRESS, USDC_DECIMALS, BASE_CHAIN_ID, errors, isCashError, CASH_ORDER_STATUSES, mapChainError, CashError } from './chunk-P3KYZ2FX.js';
-export { BASE_CHAIN_ID, BASE_USDC_ADDRESS, CASH_ORDER_POLL_INTERVAL_MS, CASH_ORDER_STATUSES, CASH_RETAIN_ON_EMPTY, CashError, MARKET_SPREAD_BPS, ORACLE_MIN_CONVERSION_RATE_SENTINEL, USDC_DECIMALS, errors, isCashError } from './chunk-P3KYZ2FX.js';
+import { MARKET_SPREAD_BPS, ORACLE_MIN_CONVERSION_RATE_SENTINEL, CASH_RETAIN_ON_EMPTY, BASE_USDC_ADDRESS, USDC_DECIMALS, BASE_CHAIN_ID, errors, isCashError, CASH_ORDER_STATUSES, mapChainError, CashError } from './chunk-TR6JVYYF.js';
+export { BASE_CHAIN_ID, BASE_USDC_ADDRESS, CASH_ORDER_POLL_INTERVAL_MS, CASH_ORDER_STATUSES, CASH_RETAIN_ON_EMPTY, CashError, MARKET_SPREAD_BPS, ORACLE_MIN_CONVERSION_RATE_SENTINEL, USDC_DECIMALS, errors, isCashError } from './chunk-TR6JVYYF.js';
 import { parseAbi, parseEventLogs, isAddress, http, createWalletClient, encodeFunctionData } from 'viem';
 import { base } from 'viem/chains';
 import { getSpreadOracleConfig, currencyInfo, getPaymentMethodsCatalog, getGatingServiceAddress, resolvePaymentMethodHashFromCatalog, resolvePaymentMethodNameFromHash, getCurrencyCodeFromHash, createCompositeDepositId, appendAttributionToCalldata, Zkp2pClient, CHAINLINK_ORACLE_FEEDS } from '@zkp2p/sdk';
@@ -675,6 +675,14 @@ async function assertRelayExecutionIdentity(quote, wallet, expectedRecipient) {
     throw new Error("Relay quote recipient does not match the expected Base recipient");
   }
 }
+function assertRelayNonceManagement(quote, wallet) {
+  const account = wallet.account;
+  if (!account || account.type !== "local" || account.nonceManager !== void 0) return;
+  const transactionCount = quote.steps.flatMap(
+    (step) => step.items.filter((item) => asString(asRecord(item.data).to) !== void 0)
+  ).length;
+  if (transactionCount > 1) throw errors.sourceNonceManagerRequired(transactionCount);
+}
 function isRelaySecretKey(key) {
   const normalized = key.toLowerCase();
   return normalized === "headers" || normalized === "apikey";
@@ -876,6 +884,7 @@ async function executeRelayQuote(quote, wallet, options = {}) {
     observedRequestId = quoteRequestId(rawQuote);
     assertCanonicalRelayDestination(rawQuote);
     await assertRelayExecutionIdentity(rawQuote, wallet, options.recipient);
+    assertRelayNonceManagement(rawQuote, wallet);
     const client = relayClient(options.relay);
     const sourceChainId = quoteSourceChainId(rawQuote);
     if (sourceChainId !== void 0 && !(client.chains ?? []).some((chain) => chain.id === sourceChainId)) {
@@ -1344,32 +1353,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 +1519,7 @@ function createCashClient(options) {
             executed
           );
         } catch (err) {
+          if (isCashError(err)) throw err;
           throw errors.sourceRouteCompletedCashoutFailed(
             routedSource,
             mapChainError("resolve same-chain Relay nonce", err)
@@ -2166,6 +2195,7 @@ var CASH_ERROR_CODES = defineCashErrorCodes([
   "SOURCE_RECIPIENT_MISMATCH",
   "SOURCE_CAPABILITIES_FAILED",
   "SOURCE_QUOTE_FAILED",
+  "SOURCE_NONCE_MANAGER_REQUIRED",
   "SOURCE_EXECUTION_FAILED",
   "SOURCE_STATUS_FAILED",
   "SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED",

package/dist/react.js

@@ -1,4 +1,4 @@
-import { isCashError, CASH_ORDER_POLL_INTERVAL_MS } from './chunk-P3KYZ2FX.js';
+import { isCashError, CASH_ORDER_POLL_INTERVAL_MS } from './chunk-TR6JVYYF.js';
 import { useState, useRef, useCallback, useEffect, useMemo } from 'react';
 
 function useEstimate({

package/dist/tools.cjs

@@ -2,7 +2,7 @@
 
 // package.json
 var package_default = {
-  version: "0.1.5"};
+  version: "0.1.7"};
 
 // 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.7"};
 
 // src/tools/index.ts
 var bigintString = {

package/docs/lifecycle-and-recovery.md

@@ -36,6 +36,16 @@ For any other EVM source asset, Peer Cash uses `@relayprotocol/relay-sdk`:
    `executeSourceQuote()` remains available for apps that want a separate
    bridge step.
 
+Routes that need more than one source-chain transaction (an ERC-20 `approve`,
+then the route transaction) are submitted back-to-back by the Relay SDK. On a
+plain local account the route transaction reuses the approval's nonce and
+reverts mid-route, so `executeSourceQuote()` and `cashout({ source })` refuse
+multi-transaction routes up front with `SOURCE_NONCE_MANAGER_REQUIRED` unless
+the source signer carries a viem nonce manager:
+`privateKeyToAccount(pk, { nonceManager })`. The check fires before anything
+is submitted. Browser (`json-rpc`) wallets are unaffected - the node
+allocates their nonces.
+
 Cash-out interfaces should use `tradeType: 'EXACT_INPUT'` (also the default),
 so `amount` always means source-token base units. A `RelayQuote.outputAmount`
 is the guaranteed minimum Base USDC output. The same value becomes
@@ -62,10 +72,16 @@ destination constant.
 
 Do not retry a source route merely because the Base cashout did not finish:
 
+- `SOURCE_NONCE_MANAGER_REQUIRED` is preflight: nothing was submitted.
+  Recreate the source signer with viem's nonce manager and execute a fresh
+  quote.
 - `SOURCE_EXECUTION_FAILED` means Relay execution did not report success. Check
   its `inspect-relay-route` recovery evidence, submitted wallet transactions,
   and `relayStatus(requestId)` before taking another action; a blind retry can
-  route twice.
+  route twice. A failed route whose only landed transaction is the approval
+  can sit in `relayStatus` `waiting` indefinitely - it never becomes terminal,
+  so decide from the persisted recovery payload and the origin transactions,
+  not from Relay reaching a final status.
 - `SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED` means Relay completed, but the Base
   cashout was not created. Its recovery payload has
   `kind: 'retry-base-usdc-cashout'`, the guaranteed Base USDC `amount`, Relay
@@ -132,7 +148,9 @@ UI built on this SDK is a bug in that UI.
 - **Partial withdrawal** - `withdraw(depositId, { amount })` pulls part of
   the _unlocked_ balance back out. A live buyer intent does not block it
   (their locked portion is untouched); asking for more than the unlocked
-  balance fails with `INSUFFICIENT_AVAILABLE_FUNDS`.
+  balance fails with `INSUFFICIENT_AVAILABLE_FUNDS`. Accounting note: a
+  partial withdrawal increments `returnedAmount`; `totalAmount` records
+  everything the order has ever held and does not shrink.
 - There is no retain-on-empty or rate knob to manage - a cash order cleans
   itself up when fully filled, and the market rate is not configurable.
 
@@ -252,6 +270,7 @@ explicit override.
 | `SOURCE_RECIPIENT_MISMATCH`             | no        | Relay output recipient differs from the cashout depositor. Use the depositor address.                                                        |
 | `SOURCE_CAPABILITIES_FAILED`            | yes       | Relay source discovery failed. Retry or use Base USDC.                                                                                       |
 | `SOURCE_QUOTE_FAILED`                   | yes       | Relay returned no valid canonical Base-USDC route. Refresh capabilities and quote again.                                                     |
+| `SOURCE_NONCE_MANAGER_REQUIRED`         | no        | Preflight; nothing was submitted. Recreate the source signer with viem's `nonceManager` and execute a fresh quote.                           |
 | `SOURCE_EXECUTION_FAILED`               | no        | Route execution did not report success. Inspect source transactions and Relay status before retrying.                                        |
 | `SOURCE_STATUS_FAILED`                  | yes       | Relay status is temporarily unavailable. Retry the status read without resubmitting.                                                         |
 | `SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED` | no        | Relay completed but no Base cashout was created. Use the recovery amount for a Base-USDC-only retry; never repeat Relay.                     |

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.7",
   "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"
   }
 }