@zkp2p/cash 0.4.11-rc.1 → 0.4.11-rc.2

package/AGENTS.md

@@ -26,7 +26,8 @@ can withdraw an unmatched deposit.
    persist the returned `depositId`. If the original plan set
    a non-empty `accessPolicyPaymentMethods`, submit and confirm
    `prepareAccessPolicy(depositId, paymentMethod)` with the depositor for each
-   returned method.
+   returned method. Do the same for `disputeProtectionPaymentMethods` with
+   `prepareDisputeProtection(depositId, paymentMethod)`.
 3. **You are a tool-use host** (MCP server, CLI) → import the manifest from
    `@zkp2p/cash/tools` and map the tool names to the verbs above. Base-USDC
    mutating tools return unsigned transactions. `cash_source_quote` is a quote,
@@ -45,14 +46,13 @@ deposit-level integration share instead of applying maker L1/L2.
 
 **Platform caveats:**
 
-- **Venmo, Cash App, and PayPal restrict who can signal intents by default.**
-  Signed `cashout()` confirms `createDeposit`, then submits and confirms a
-  method-scoped Peer Pay merchant policy for every restricted payout leg using
-  the same viem wallet. This is a deliberate non-atomic follow-up with a brief
-  unprotected interval. For `prepare()`, read `accessPolicyPaymentMethods`;
-  after `createDeposit` confirms, finalize its receipt and submit
-  `prepareAccessPolicy(depositId, paymentMethod)` for every returned method.
-  Any viem EOA works; Privy is not required.
+- **Venmo, Cash App, and PayPal use both restricted-rail defaults.** Signed
+  `cashout()` proves dispute protection is ready, confirms `createDeposit`,
+  then submits and confirms a method-scoped Peer Pay merchant policy and
+  dispute-protection opt-in for every restricted payout leg using the same
+  viem wallet. For `prepare()`, finalize the confirmed receipt, then iterate
+  both `accessPolicyPaymentMethods` and `disputeProtectionPaymentMethods` with
+  their matching prepare methods. Any viem EOA works; Privy is not required.
 
 - **Wise and PayPal** carry `requiresIdentityAttestation: true`. A new curator
   registration needs a signed maker identity attestation this SDK cannot mint
@@ -234,6 +234,10 @@ const route = await cash.nearIntentsStatus({
   already exists. If `recovery.transactionHash` is present, inspect that policy
   transaction first; prepare another policy transaction only when the previous
   one is absent or confirmed reverted.
+- **Fail closed on dispute protection.** `DISPUTE_PROTECTION_UNAVAILABLE`
+  occurs before deposit creation. `DISPUTE_PROTECTION_CONFIGURATION_FAILED`
+  means the deposit exists; inspect its recovery hash and use
+  `prepareDisputeProtection` only when resubmission is safe.
 - **`ORDER_NOT_FOUND` seconds after `cashout()` is indexer lag**, not a lost
   deposit. The tx receipt you hold is the truth. Retry; `watch()` absorbs
   this automatically.
@@ -258,51 +262,53 @@ const route = await cash.nearIntentsStatus({
 
 Every `CashError` carries `code`, `retryable`, `remediation`. Behavior:
 
-| Code                                    | Retryable | Agent action                                                                               |
-| --------------------------------------- | --------- | ------------------------------------------------------------------------------------------ |
-| `ORACLE_UNSUPPORTED_CURRENCY`           | no        | Re-pick currency from `capabilities()`                                                     |
-| `ORACLE_READ_FAILED`                    | yes       | Retry the read through a healthy Base RPC; do not present a cached value as live           |
-| `UNSUPPORTED_PLATFORM`                  | no        | Re-pick platform from `capabilities()`                                                     |
-| `UNSUPPORTED_PLATFORM_CURRENCY`         | no        | Use a currency listed for that platform                                                    |
-| `AMOUNT_BELOW_MINIMUM`                  | no        | Raise amount (hard floor $0.01, recommended at least 1 USDC)                               |
-| `INVALID_INTENT_AMOUNT_RANGE`           | no        | Use a positive min, max at least min, and max no greater than amount                       |
-| `INVALID_PAYOUT_CURRENCIES`             | no        | Pass one or more unique currencies listed for the platform                                 |
-| `INVALID_PAYOUT_PLATFORMS`              | no        | Pass one leg or an array of legs, using each platform at most once                         |
-| `PAYEE_VERIFICATION_REQUIRED`           | no        | Use Peer web + TEE extension for new Wise/PayPal; reuse registered handles                 |
-| `PAYEE_REGISTRATION_FAILED`             | yes       | Validate against `payeeHint`, then retry                                                   |
-| `ATOMIC_ACCESS_POLICY_REQUIRED`         | no        | Deprecated compatibility code; current SDK flows never emit it                             |
-| `ACCESS_POLICY_CONFIGURATION_FAILED`    | no        | Deposit exists; inspect policy tx first, attach only if needed; never repeat the cash-out. |
-| `SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE`   | no        | Execute Relay with a signer first, then prepare a Base-USDC cashout                        |
-| `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_DEPOSIT_SUBMISSION_FAILED`      | yes       | Retry only the 1Click notification; never resend source funds                              |
-| `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`                                 |
-| `SOURCE_CASHOUT_SUBMISSION_UNKNOWN`     | no        | Inspect Base activity and orders; prove no deposit exists before retrying                  |
-| `SOURCE_CASHOUT_STATUS_UNKNOWN`         | no        | Inspect `recovery.depositTxHash`; do not resubmit while its receipt is unknown             |
-| `INSUFFICIENT_TOKEN_BALANCE`            | no        | Fund the required token amount, then retry                                                 |
-| `ALLOWANCE_NOT_VISIBLE`                 | yes       | Approval mined but a stale RPC hid it; retry after it becomes visible                      |
-| `TRANSACTION_REJECTED`                  | yes       | Retry when ready and approve the wallet request                                            |
-| `TRANSACTION_FAILED`                    | no        | Inspect the failed/reverted call before another action                                     |
-| `TRANSACTION_SUBMISSION_UNKNOWN`        | no        | Inspect Base wallet/protocol state and the recovery action before any resubmission         |
-| `TRANSACTION_STATUS_UNKNOWN`            | no        | Inspect `recovery.transactionHash` before resubmitting                                     |
-| `DEPOSIT_RESOLUTION_FAILED`             | no        | Inspect the confirmed Base receipt and recover the id from `DepositReceived`               |
-| `INVALID_DEPOSIT_ID`                    | no        | Use the exact id returned by `cashout()`                                                   |
-| `ORDER_NOT_FOUND`                       | yes       | Retry through immediate indexer lag; otherwise verify the id                               |
-| `INDEXER_LAG`                           | yes       | Retry after a few seconds                                                                  |
-| `INDEXER_UNAVAILABLE`                   | yes       | Retry only the failed read; keep the id/owner and never repeat a transaction               |
-| `ACTIVE_INTENT_BLOCKS_WITHDRAWAL`       | yes       | Wait for fill/expiry, or withdraw only the unlocked amount                                 |
-| `INSUFFICIENT_AVAILABLE_FUNDS`          | yes       | Lower the partial withdrawal amount                                                        |
-| `NOTHING_TO_WITHDRAW`                   | no        | Order is terminal; reconcile records                                                       |
-| `ORDER_NOT_ACTIVE`                      | no        | Start a new cashout instead of topping up                                                  |
-| `SIGNER_REQUIRED`                       | no        | Provide a signer or use a Base-USDC prepare path                                           |
-| `SIGNER_CHAIN_MISMATCH`                 | no        | Switch to the required chain and refresh any Relay quote before retrying                   |
-| `SIGNER_CHAIN_UNAVAILABLE`              | yes       | Reconnect the wallet and prove its chain before retrying                                   |
-| `WATCH_TIMEOUT`                         | yes       | Resume `watch(depositId)` later                                                            |
-| `ESCROW_PAUSED`                         | yes       | Back off; existing funds remain withdrawable                                               |
+| Code                                      | Retryable | Agent action                                                                               |
+| ----------------------------------------- | --------- | ------------------------------------------------------------------------------------------ |
+| `ORACLE_UNSUPPORTED_CURRENCY`             | no        | Re-pick currency from `capabilities()`                                                     |
+| `ORACLE_READ_FAILED`                      | yes       | Retry the read through a healthy Base RPC; do not present a cached value as live           |
+| `UNSUPPORTED_PLATFORM`                    | no        | Re-pick platform from `capabilities()`                                                     |
+| `UNSUPPORTED_PLATFORM_CURRENCY`           | no        | Use a currency listed for that platform                                                    |
+| `AMOUNT_BELOW_MINIMUM`                    | no        | Raise amount (hard floor $0.01, recommended at least 1 USDC)                               |
+| `INVALID_INTENT_AMOUNT_RANGE`             | no        | Use a positive min, max at least min, and max no greater than amount                       |
+| `INVALID_PAYOUT_CURRENCIES`               | no        | Pass one or more unique currencies listed for the platform                                 |
+| `INVALID_PAYOUT_PLATFORMS`                | no        | Pass one leg or an array of legs, using each platform at most once                         |
+| `PAYEE_VERIFICATION_REQUIRED`             | no        | Use Peer web + TEE extension for new Wise/PayPal; reuse registered handles                 |
+| `PAYEE_REGISTRATION_FAILED`               | yes       | Validate against `payeeHint`, then retry                                                   |
+| `ATOMIC_ACCESS_POLICY_REQUIRED`           | no        | Deprecated compatibility code; current SDK flows never emit it                             |
+| `ACCESS_POLICY_CONFIGURATION_FAILED`      | no        | Deposit exists; inspect policy tx first, attach only if needed; never repeat the cash-out. |
+| `DISPUTE_PROTECTION_UNAVAILABLE`          | yes       | No deposit exists; wait for the protected stack or choose an unrestricted rail.            |
+| `DISPUTE_PROTECTION_CONFIGURATION_FAILED` | no        | Deposit exists; inspect the protection tx and recover it without repeating the cash-out.   |
+| `SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE`     | no        | Execute Relay with a signer first, then prepare a Base-USDC cashout                        |
+| `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_DEPOSIT_SUBMISSION_FAILED`        | yes       | Retry only the 1Click notification; never resend source funds                              |
+| `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`                                 |
+| `SOURCE_CASHOUT_SUBMISSION_UNKNOWN`       | no        | Inspect Base activity and orders; prove no deposit exists before retrying                  |
+| `SOURCE_CASHOUT_STATUS_UNKNOWN`           | no        | Inspect `recovery.depositTxHash`; do not resubmit while its receipt is unknown             |
+| `INSUFFICIENT_TOKEN_BALANCE`              | no        | Fund the required token amount, then retry                                                 |
+| `ALLOWANCE_NOT_VISIBLE`                   | yes       | Approval mined but a stale RPC hid it; retry after it becomes visible                      |
+| `TRANSACTION_REJECTED`                    | yes       | Retry when ready and approve the wallet request                                            |
+| `TRANSACTION_FAILED`                      | no        | Inspect the failed/reverted call before another action                                     |
+| `TRANSACTION_SUBMISSION_UNKNOWN`          | no        | Inspect Base wallet/protocol state and the recovery action before any resubmission         |
+| `TRANSACTION_STATUS_UNKNOWN`              | no        | Inspect `recovery.transactionHash` before resubmitting                                     |
+| `DEPOSIT_RESOLUTION_FAILED`               | no        | Inspect the confirmed Base receipt and recover the id from `DepositReceived`               |
+| `INVALID_DEPOSIT_ID`                      | no        | Use the exact id returned by `cashout()`                                                   |
+| `ORDER_NOT_FOUND`                         | yes       | Retry through immediate indexer lag; otherwise verify the id                               |
+| `INDEXER_LAG`                             | yes       | Retry after a few seconds                                                                  |
+| `INDEXER_UNAVAILABLE`                     | yes       | Retry only the failed read; keep the id/owner and never repeat a transaction               |
+| `ACTIVE_INTENT_BLOCKS_WITHDRAWAL`         | yes       | Wait for fill/expiry, or withdraw only the unlocked amount                                 |
+| `INSUFFICIENT_AVAILABLE_FUNDS`            | yes       | Lower the partial withdrawal amount                                                        |
+| `NOTHING_TO_WITHDRAW`                     | no        | Order is terminal; reconcile records                                                       |
+| `ORDER_NOT_ACTIVE`                        | no        | Start a new cashout instead of topping up                                                  |
+| `SIGNER_REQUIRED`                         | no        | Provide a signer or use a Base-USDC prepare path                                           |
+| `SIGNER_CHAIN_MISMATCH`                   | no        | Switch to the required chain and refresh any Relay quote before retrying                   |
+| `SIGNER_CHAIN_UNAVAILABLE`                | yes       | Reconnect the wallet and prove its chain before retrying                                   |
+| `WATCH_TIMEOUT`                           | yes       | Resume `watch(depositId)` later                                                            |
+| `ESCROW_PAUSED`                           | yes       | Back off; existing funds remain withdrawable                                               |
 
 `isCashError(err)` narrows unknown errors; `err.toJSON()` is safe for logs
 and tool results.
@@ -313,7 +319,8 @@ Prove your integration against `environment: 'staging'` with a funded test
 wallet. Never wait on a buyer - buyer-side is out of your scope:
 
 1. `cashout()` a small amount (1–2 USDC) → capture `depositId` and, for a
-   restricted payout, every entry in `accessPolicyTxHashes`.
+   restricted payout, every entry in `accessPolicyTxHashes` and
+   `disputeProtectionTxHashes`.
 2. `order(depositId)` shows `awaiting-buyer` (retry through indexer lag).
 3. `orders(owner)` includes the deposit.
 4. `withdraw(depositId)` → transaction succeeds.

package/README.md

@@ -39,15 +39,15 @@ const fillStats = await cash.fillStats();
 const pairStats = fillStats['venmo:USD'];
 const multiCurrencyStats = fillStats['revolut:EUR+GBP+USD'];
 
-const { depositId, accessPolicyTxHashes } = await cash.cashout(
+const { depositId, accessPolicyTxHashes, disputeProtectionTxHashes } = await cash.cashout(
   {
     amount: usdc(1000),
     receive: { platform: 'venmo', currency: 'USD', payee: '@you' },
   },
   { signer }, // any viem WalletClient on Base, including an EOA
 );
-// Venmo, Cash App, and PayPal return only after their access policy confirms.
-console.log(depositId, accessPolicyTxHashes);
+// Restricted rails return only after both defaults confirm.
+console.log(depositId, accessPolicyTxHashes, disputeProtectionTxHashes);
 
 // One method can offer several currencies. The buyer chooses the fill
 // currency, and each option resolves at its own live oracle rate.
@@ -92,8 +92,9 @@ Peer Cash and the general ZKP2P SDK serve different integration depths:
 | `@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.
+cannot express custom spreads, buyer-side proof flows, vaults, dispute
+management, or arbitrary protocol operations. The protected restricted-rail
+default is fixed rather than a configurable dispute surface.
 
 ## The core verbs
 
@@ -108,9 +109,10 @@ arbitrary protocol operations.
 | `quoteNearIntentsSource(input)`                                | Signed 1Click quote with an origin-chain deposit address and optional memo                                                      |
 | `submitNearIntentsDeposit(input)` / `nearIntentsStatus(input)` | Optionally register an origin tx, then track 1Click delivery/refund evidence                                                    |
 | `estimate({ amount, currency }, { includeEta? })`              | Base USDC oracle estimate; optionally skip the historical ETA for progressive rendering                                         |
-| `cashout(input, { signer })`                                   | Creates the order with any viem wallet; restricted methods then attach the Peer Pay merchant policy                             |
-| `prepare(input)` / `finalizePreparedCashout(receipt)`          | Prepare external signing, resolve the deposit, then iterate `accessPolicyPaymentMethods` for follow-ups                         |
+| `cashout(input, { signer })`                                   | Creates the order; restricted methods then attach the Peer Pay merchant policy and enable dispute protection                    |
+| `prepare(input)` / `finalizePreparedCashout(receipt)`          | Prepare external signing, resolve the deposit, then iterate both restricted-method follow-up lists                              |
 | `prepareAccessPolicy(depositId, paymentMethod)`                | Prepare one post-deposit, method-scoped Peer Pay merchant policy transaction                                                    |
+| `prepareDisputeProtection(depositId, paymentMethod)`           | Prepare one post-deposit, method-scoped dispute-protection transaction                                                          |
 | `order(depositId)` / `orders(owner)`                           | Resume any order from its id alone; list all orders for a wallet                                                                |
 | `watch(depositId)`                                             | Async iterator: yields on every state change until terminal, abort, or timeout                                                  |
 | `withdraw(depositId, { signer, amount? })`                     | The ONE unwind verb - partial with an `amount` (live intents don't block it), full close without (prunes expired intents first) |
@@ -139,12 +141,12 @@ mixed historical deposit.
 
 ## Payout rails and access policies
 
-| Payout rail           | Access-policy behavior                                                     | New payee registration                                                                 |
-| --------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| Venmo / Cash App      | Peer Pay merchant policy attaches for that payment method                  | Curator validates the live handle                                                      |
-| PayPal                | Same method-scoped Peer Pay follow-up                                      | Requires a Peer TEE browser-extension identity attestation                             |
-| Wise                  | No access-policy follow-up                                                 | Requires a Peer TEE browser-extension identity attestation                             |
-| Other supported rails | No access-policy follow-up; use `capabilities()` for currencies and format | Follow the `payeeHint`; live-validation behavior is described in the integration guide |
+| Payout rail           | Restricted-rail defaults                                                     | New payee registration                                                                 |
+| --------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Venmo / Cash App      | Method-scoped Peer Pay merchant policy plus dispute protection               | Curator validates the live handle                                                      |
+| PayPal                | Same method-scoped merchant-group and dispute-protection follow-ups          | Requires a Peer TEE browser-extension identity attestation                             |
+| Wise                  | No restricted-rail follow-up                                                 | Requires a Peer TEE browser-extension identity attestation                             |
+| Other supported rails | No restricted-rail follow-up; use `capabilities()` for currencies and format | Follow the `payeeHint`; live-validation behavior is described in the integration guide |
 
 No platform requires an atomic access-policy flow. `cashout()` and `prepare()`
 work with any viem `WalletClient`, including a local or externally connected
@@ -153,14 +155,15 @@ EOA; no Privy wallet or signer API is required. The deprecated
 always `false`.
 
 Venmo, Cash App, and PayPal cash-outs restrict intent signaling to the Peer Pay
-merchant group by default. Each restricted payout method gets its own policy.
-Signed `cashout()` creates the deposit first, then uses the same wallet to
-submit and confirm every required policy transaction; this intentionally
-leaves a brief non-atomic interval. Prepared integrations receive
-`accessPolicyPaymentMethods`; after confirming `createDeposit`, call
-`finalizePreparedCashout(receipt)`, then submit
-`prepareAccessPolicy(depositId, paymentMethod)` once for every returned method.
-Other platforms do not need the follow-up.
+merchant group and enable dispute protection by default. Both defaults are
+method-scoped. Signed `cashout()` first proves the dispute-protection stack is
+ready, then creates the deposit and uses the same wallet to submit and confirm
+both follow-ups. Prepared integrations receive matching
+`accessPolicyPaymentMethods` and `disputeProtectionPaymentMethods`; after
+confirming `createDeposit`, call `finalizePreparedCashout(receipt)`, then submit
+`prepareAccessPolicy(depositId, paymentMethod)` and
+`prepareDisputeProtection(depositId, paymentMethod)` for every returned method.
+Other platforms do not need either follow-up.
 
 If policy attachment fails, `ACCESS_POLICY_CONFIGURATION_FAILED.recovery`
 identifies the existing deposit and any submitted policy transaction. Never
@@ -168,6 +171,12 @@ create another cash-out. When `recovery.transactionHash` is present, inspect
 that transaction before resubmitting; otherwise prepare the policy again with
 the same depositor wallet.
 
+If protection is not ready, `DISPUTE_PROTECTION_UNAVAILABLE` fails before the
+deposit is created. If its post-deposit transaction fails,
+`DISPUTE_PROTECTION_CONFIGURATION_FAILED.recovery` identifies the existing
+deposit and submitted hash, if any; inspect it before using
+`prepareDisputeProtection` for recovery and never repeat the cash-out.
+
 `capabilities()` presents Zelle as one platform. A cashout with
 `receive.platform: 'zelle'` attaches only the generic Zelle payment method to
 the deposit. Bank-specific capture routing is outside this maker-side SDK and
@@ -309,6 +318,11 @@ they are available. A source-routed result includes both a flat
   `prepareAccessPolicy(error.recovery.depositId, error.recovery.paymentMethod)`
   only if the prior policy
   transaction did not succeed.
+- `DISPUTE_PROTECTION_UNAVAILABLE`: the protected contract stack is not ready;
+  no deposit was created. Retry later or use an unrestricted payout platform.
+- `DISPUTE_PROTECTION_CONFIGURATION_FAILED`: the deposit exists, but one
+  required protection transaction was not confirmed. Inspect its recovery hash
+  before calling `prepareDisputeProtection`; never create another cash-out.
 
 Wallet clients pinned to the wrong chain fail with `SIGNER_CHAIN_MISMATCH`
 before a quote or transaction is submitted. Chainless wallets are checked
@@ -390,7 +404,9 @@ analytics-only ERC-8021 codes such as `acme-app`.
 - After a prepared restricted cash-out confirms, the host adapter must call
   `finalizePreparedCashout(receipt)` and submit
   `prepareAccessPolicy(depositId, paymentMethod)` for every value in
-  `accessPolicyPaymentMethods`; these receipt/signing operations are
+  `accessPolicyPaymentMethods`, plus
+  `prepareDisputeProtection(depositId, paymentMethod)` for every value in
+  `disputeProtectionPaymentMethods`; these receipt/signing operations are
   `CashClient` methods, not built-in tool calls.
 - Every error carries `code`, `retryable`, and a `remediation` sentence.
 - Every order carries `nextActions: ('wait' | 'withdraw')[]` - no heuristics.

package/dist/{chunk-JRJLMQS4.js → chunk-AAWRU4JK.js}

@@ -424,6 +424,38 @@ var errors = {
     },
     { cause: context.cause }
   ),
+  disputeProtectionUnavailable: (state, cause) => new CashError(
+    {
+      code: "DISPUTE_PROTECTION_UNAVAILABLE",
+      message: `Dispute protection is not ready for restricted Peer Cash payouts${state ? ` (${state})` : ""}.`,
+      retryable: true,
+      remediation: `Retry after the dispute-protection contracts are active and accepting protected deposits, or choose an unrestricted payout platform. No cash-out deposit was created.`
+    },
+    { cause }
+  ),
+  disputeProtectionConfigurationFailed: (depositId, paymentMethod, context = {}) => new CashError(
+    {
+      code: "DISPUTE_PROTECTION_CONFIGURATION_FAILED",
+      message: `Cash-out deposit ${depositId} was created, but dispute protection could not be confirmed for ${paymentMethod}.`,
+      retryable: false,
+      remediation: `Do not create another cash-out. If recovery.transactionHash is present, inspect that dispute-protection transaction first. Otherwise, or if it is confirmed reverted, submit and confirm prepareDisputeProtection(recovery.depositId, recovery.paymentMethod) with the same depositor wallet.`,
+      recovery: {
+        kind: "configure-cashout-dispute-protection",
+        depositId,
+        paymentMethod,
+        ...context.transactionHash ? { transactionHash: context.transactionHash } : {},
+        ...context.source ? {
+          source: {
+            amount: context.source.amount.toString(),
+            ...context.source.requestId ? { requestId: context.source.requestId } : {},
+            txHashes: context.source.txHashes,
+            ...context.source.transactions ? { transactions: context.source.transactions } : {}
+          }
+        } : {}
+      }
+    },
+    { cause: context.cause }
+  ),
   escrowPaused: () => new CashError({
     code: "ESCROW_PAUSED",
     message: `The escrow contract is paused; deposits are temporarily disabled.`,

package/dist/{createCashClient-BD8YNt-E.d.cts → createCashClient-G8ksaisL.d.cts}

@@ -486,8 +486,8 @@ interface CashPlatformCapability {
     requiresIdentityAttestation: boolean;
     /**
      * @deprecated Always false. This does not report the sequential restricted-
-     * platform policy; prepared hosts must inspect
-     * `PrepareResult.accessPolicyPaymentMethods`.
+     * platform defaults; prepared hosts must inspect both method lists on
+     * `PrepareResult`.
      */
     requiresAtomicAccessPolicy: boolean;
 }
@@ -769,6 +769,8 @@ interface CashoutResult {
     accessPolicyTxHash?: Hash;
     /** Confirmed method-scoped policy transactions for restricted payout legs. */
     accessPolicyTxHashes?: Hash[];
+    /** Confirmed method-scoped dispute-protection transactions for restricted payout legs. */
+    disputeProtectionTxHashes?: Hash[];
     /** Present when `cashout()` first routed a source asset through Relay. */
     source?: {
         /** Conservative Base USDC amount deposited (Relay's guaranteed minimum output). */
@@ -799,6 +801,10 @@ interface PrepareResult {
     accessPolicyRequired: boolean;
     /** Method hashes that each require a post-deposit Peer Pay policy transaction. */
     accessPolicyPaymentMethods: Hex[];
+    /** Whether the host must enable dispute protection after `createDeposit` confirms. */
+    disputeProtectionRequired: boolean;
+    /** Method hashes that each require a post-deposit dispute-protection transaction. */
+    disputeProtectionPaymentMethods: Hex[];
 }
 /** Confirmed createDeposit receipt from an externally executed prepare() plan. */
 interface PreparedCashoutReceipt {
@@ -877,6 +883,8 @@ interface CashClient {
     finalizePreparedCashout(receipt: PreparedCashoutReceipt): CashoutResult;
     /** Prepare one method-scoped Peer Pay follow-up for a restricted cash-out. */
     prepareAccessPolicy(depositId: string, paymentMethod: Hex): PreparedTransaction;
+    /** Prepare one method-scoped dispute-protection follow-up for a restricted cash-out. */
+    prepareDisputeProtection(depositId: string, paymentMethod: Hex): Promise<PreparedTransaction>;
     /** 3 - Observe: resumable from `depositId` alone; no session state anywhere. */
     order(depositId: string): Promise<CashOrder>;
     /**

package/dist/{createCashClient-BD8YNt-E.d.ts → createCashClient-G8ksaisL.d.ts}

@@ -486,8 +486,8 @@ interface CashPlatformCapability {
     requiresIdentityAttestation: boolean;
     /**
      * @deprecated Always false. This does not report the sequential restricted-
-     * platform policy; prepared hosts must inspect
-     * `PrepareResult.accessPolicyPaymentMethods`.
+     * platform defaults; prepared hosts must inspect both method lists on
+     * `PrepareResult`.
      */
     requiresAtomicAccessPolicy: boolean;
 }
@@ -769,6 +769,8 @@ interface CashoutResult {
     accessPolicyTxHash?: Hash;
     /** Confirmed method-scoped policy transactions for restricted payout legs. */
     accessPolicyTxHashes?: Hash[];
+    /** Confirmed method-scoped dispute-protection transactions for restricted payout legs. */
+    disputeProtectionTxHashes?: Hash[];
     /** Present when `cashout()` first routed a source asset through Relay. */
     source?: {
         /** Conservative Base USDC amount deposited (Relay's guaranteed minimum output). */
@@ -799,6 +801,10 @@ interface PrepareResult {
     accessPolicyRequired: boolean;
     /** Method hashes that each require a post-deposit Peer Pay policy transaction. */
     accessPolicyPaymentMethods: Hex[];
+    /** Whether the host must enable dispute protection after `createDeposit` confirms. */
+    disputeProtectionRequired: boolean;
+    /** Method hashes that each require a post-deposit dispute-protection transaction. */
+    disputeProtectionPaymentMethods: Hex[];
 }
 /** Confirmed createDeposit receipt from an externally executed prepare() plan. */
 interface PreparedCashoutReceipt {
@@ -877,6 +883,8 @@ interface CashClient {
     finalizePreparedCashout(receipt: PreparedCashoutReceipt): CashoutResult;
     /** Prepare one method-scoped Peer Pay follow-up for a restricted cash-out. */
     prepareAccessPolicy(depositId: string, paymentMethod: Hex): PreparedTransaction;
+    /** Prepare one method-scoped dispute-protection follow-up for a restricted cash-out. */
+    prepareDisputeProtection(depositId: string, paymentMethod: Hex): Promise<PreparedTransaction>;
     /** 3 - Observe: resumable from `depositId` alone; no session state anywhere. */
     order(depositId: string): Promise<CashOrder>;
     /**