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

package/AGENTS.md

@@ -24,8 +24,10 @@ can withdraw an unmatched deposit.
    the plan, submit the transactions in order, and wait for each receipt. After
    `createDeposit` confirms, pass its receipt to `finalizePreparedCashout()` and
    persist the returned `depositId`. If the original plan set
-   `accessPolicyRequired: true`, submit and confirm
-   `prepareAccessPolicy(depositId)` with the depositor next.
+   a non-empty `accessPolicyPaymentMethods`, submit and confirm
+   `prepareAccessPolicy(depositId, paymentMethod)` with the depositor for each
+   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,
@@ -44,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.**
-  If any payout leg uses one of these platforms, signed
-  `cashout()` confirms `createDeposit`, then submits and confirms the Plus, Pro,
-  Peer Makers, and Peer Pay policy using the same viem wallet. This is a
-  deliberate non-atomic follow-up with a brief unprotected interval. For
-  `prepare()`, check `accessPolicyRequired`; after `createDeposit` confirms,
-  finalize its receipt and submit `prepareAccessPolicy(depositId)` with the
-  depositor. 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
@@ -233,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.
@@ -257,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.
@@ -312,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, `accessPolicyTxHash`.
+   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, accessPolicyTxHash } = 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, accessPolicyTxHash);
+// 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; Venmo, Cash App, and PayPal then attach the canonical access groups                     |
-| `prepare(input)` / `finalizePreparedCashout(receipt)`          | Prepare external signing, resolve the deposit, then check `accessPolicyRequired` for the follow-up                              |
-| `prepareAccessPolicy(depositId)`                               | Prepare the post-deposit Plus, Pro, Peer Makers, and Peer Pay policy transaction                                                |
+| `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      | Four groups attach after deposit confirmation                              | Curator validates the live handle                                                      |
-| PayPal                | Same four-group 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
@@ -152,14 +154,16 @@ EOA; no Privy wallet or signer API is required. The deprecated
 `requiresAtomicAccessPolicy` capability remains for wire compatibility and is
 always `false`.
 
-Venmo, Cash App, and PayPal cash-outs restrict intent signaling to Plus, Pro,
-Peer Makers, and Peer Pay groups by default. If any payout leg uses one of
-those platforms, signed `cashout()` creates the deposit first, then uses the
-same wallet to submit and confirm the policy transaction; this intentionally
-leaves a brief non-atomic interval. Prepared integrations receive
-`accessPolicyRequired: true` and, after confirming `createDeposit`, must call
-`finalizePreparedCashout(receipt)` followed by
-`prepareAccessPolicy(depositId)`. Other platforms do not need the follow-up.
+Venmo, Cash App, and PayPal cash-outs restrict intent signaling to the Peer Pay
+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
@@ -167,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
@@ -195,7 +205,7 @@ discovered and quoted by `@relayprotocol/relay-sdk`, not a static token
 allowlist.
 
 ```ts
-const { depositId, accessPolicyTxHash, source } = await cash.cashout(
+const { depositId, accessPolicyTxHashes, source } = await cash.cashout(
   {
     amount: 10_000_000n, // exact input: 10 USDC in source-token base units
     source: {
@@ -212,7 +222,7 @@ const { depositId, accessPolicyTxHash, source } = await cash.cashout(
 // amount deposited into the cash-out order. It is not the route's actual output.
 console.log(source?.amount, source?.requestId);
 console.log(source?.transactions?.origin, source?.transactions?.destination);
-console.log(accessPolicyTxHash); // present because this example uses Venmo
+console.log(accessPolicyTxHashes); // one entry because this example uses Venmo
 ```
 
 Routes that submit more than one source-chain transaction (approve, then
@@ -305,8 +315,14 @@ they are available. A source-routed result includes both a flat
 - `ACCESS_POLICY_CONFIGURATION_FAILED`: the deposit exists, but its required
   Venmo, Cash App, or PayPal policy was not confirmed. Do not cash out again;
   inspect `recovery.transactionHash` when present, then retry
-  `prepareAccessPolicy(error.recovery.depositId)` only if the prior policy
+  `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
@@ -386,8 +402,12 @@ analytics-only ERC-8021 codes such as `acme-app`.
 - Mutating tool calls return unsigned transactions by default; signing stays
   with the host that owns custody, policy, and user approval.
 - After a prepared restricted cash-out confirms, the host adapter must call
-  `finalizePreparedCashout(receipt)` and `prepareAccessPolicy(depositId)`; these
-  receipt/signing operations are `CashClient` methods, not built-in tool calls.
+  `finalizePreparedCashout(receipt)` and submit
+  `prepareAccessPolicy(depositId, paymentMethod)` for every value in
+  `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.
 - Every wire type has a zod schema + JSON codec - state crosses process
@@ -424,7 +444,10 @@ Runnable first-party examples in [`examples/`](examples):
 
 - [`node-cashout.ts`](examples/node-cashout.ts) - server-side cash-out with a private-key signer, plus order tracking.
 - [`agent-tool-use.ts`](examples/agent-tool-use.ts) - wiring the verbs into an agent tool-use loop with host-side signing.
+- [`carpe-diem-provider-cashout`](examples/carpe-diem-provider-cashout) - cash out confirmed Carpe Diem provider DIEM revenue through the connected Base wallet.
 - [`mpp-merchant-cashout`](examples/mpp-merchant-cashout) - turn confirmed MPP merchant revenue into an unsigned Peer Cash plan while the merchant keeps custody and signing.
+- [`onchain-demo`](examples/onchain-demo) - the Peer Cash Demo: the express sell flow as one page that bundles the SDK and is stored on Base as contract bytecode, served by an immutable ERC-5219 wrapper,
+  [live on Base](https://basescan.org/address/0x6d6c7af86bfc6f49f32761e1718cf982224cf343).
 
 ## Trust model, honestly
 

package/dist/{chunk-3PAHKWJ2.js → chunk-AAWRU4JK.js}

@@ -3,24 +3,9 @@ var BASE_CHAIN_ID = 8453;
 var BASE_USDC_ADDRESS = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
 var CASH_RESTRICTED_PLATFORMS = /* @__PURE__ */ new Set(["venmo", "cashapp", "paypal"]);
 var CASH_ACCESS_GROUP_IDS = {
-  production: [
-    "0xb8747401b308d4891385620071b5916e9c61284f25c4611541c529703de5babf",
-    "0xf030f72e772f954059ca28f94974088aaf6ba37bb1f264df48843a3d0c221dc3",
-    "0xdf1c64c54745aa1ce00642a5874f97e3183bf5e993c1f559d0a37a4df0b803c7",
-    "0x174b8a29536721a3eae290bfd55651b85a53fc334b971d993fa93ed8dde15e48"
-  ],
-  preproduction: [
-    "0xb8747401b308d4891385620071b5916e9c61284f25c4611541c529703de5babf",
-    "0xf030f72e772f954059ca28f94974088aaf6ba37bb1f264df48843a3d0c221dc3",
-    "0xdf1c64c54745aa1ce00642a5874f97e3183bf5e993c1f559d0a37a4df0b803c7",
-    "0x174b8a29536721a3eae290bfd55651b85a53fc334b971d993fa93ed8dde15e48"
-  ],
-  staging: [
-    "0xf6133c227eab8ae7da1ee143945bf7f31204394f3ba801dc9691f8af6ca8efa5",
-    "0xa6beb459bc621e7b050e431736c1c3298da26356d7095719185e859d68f70d9e",
-    "0x9cded1332f25c3ee0a9a822a4c827d3fbd081a8d7b2ba39c49917ec1983b8d6c",
-    "0xc82c20c00033046a2f017b65532d7148a337282f17c73296663a530e49ba00f7"
-  ]
+  production: ["0x174b8a29536721a3eae290bfd55651b85a53fc334b971d993fa93ed8dde15e48"],
+  preproduction: ["0x174b8a29536721a3eae290bfd55651b85a53fc334b971d993fa93ed8dde15e48"],
+  staging: ["0xc82c20c00033046a2f017b65532d7148a337282f17c73296663a530e49ba00f7"]
 };
 var USDC_DECIMALS = 6;
 var MARKET_SPREAD_BPS = 0;
@@ -420,11 +405,44 @@ var errors = {
       code: "ACCESS_POLICY_CONFIGURATION_FAILED",
       message: `Cash-out deposit ${depositId} was created, but its access policy could not be confirmed.`,
       retryable: false,
-      remediation: `Do not create another cash-out. If recovery.transactionHash is present, inspect that policy transaction first. Otherwise, or if it is confirmed reverted, submit and confirm prepareAccessPolicy(recovery.depositId) with the same depositor wallet.`,
+      remediation: `Do not create another cash-out. If recovery.transactionHash is present, inspect that policy transaction first. Otherwise, or if it is confirmed reverted, submit and confirm prepareAccessPolicy(recovery.depositId, recovery.paymentMethod) with the same depositor wallet.`,
       recovery: {
         kind: "configure-cashout-access-policy",
         depositId,
         groupIds: [...groupIds],
+        ...context.paymentMethod ? { paymentMethod: context.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 }
+  ),
+  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: {

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

@@ -1,4 +1,4 @@
-import { Address, WalletClient, Hash, Log, Transport } from 'viem';
+import { Address, WalletClient, Hash, Hex, Log, Transport } from 'viem';
 import { IndexerIntentStatus, Zkp2pClient, IndexerIntent, CurrencyType, PreparedTransaction, RuntimeEnv } from '@zkp2p/sdk';
 import { Execute, RelayClient, RelayChain, ProgressData } from '@relayprotocol/relay-sdk';
 
@@ -486,7 +486,8 @@ interface CashPlatformCapability {
     requiresIdentityAttestation: boolean;
     /**
      * @deprecated Always false. This does not report the sequential restricted-
-     * platform policy; prepared hosts must inspect `PrepareResult.accessPolicyRequired`.
+     * platform defaults; prepared hosts must inspect both method lists on
+     * `PrepareResult`.
      */
     requiresAtomicAccessPolicy: boolean;
 }
@@ -764,8 +765,12 @@ interface CashoutResult {
     onchainDepositId: bigint;
     /** Optimistic snapshot (`awaiting-buyer`); poll `order(depositId)` for live state. */
     order: CashOrder;
-    /** Confirmed access-policy transaction when any payout leg is Venmo, Cash App, or PayPal. */
+    /** Last confirmed access-policy transaction. Retained for single-policy compatibility. */
     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). */
@@ -794,6 +799,12 @@ interface PrepareResult {
     };
     /** Whether the host must submit and confirm the policy after `createDeposit` confirms. */
     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 {
@@ -870,8 +881,10 @@ interface CashClient {
     prepare(input: CashoutInput): Promise<PrepareResult>;
     /** Resolve an externally executed createDeposit receipt into resumable cash-out state. */
     finalizePreparedCashout(receipt: PreparedCashoutReceipt): CashoutResult;
-    /** Prepare the required four-group follow-up for a restricted cash-out. */
-    prepareAccessPolicy(depositId: string): PreparedTransaction;
+    /** 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-BDp6CSBD.d.ts → createCashClient-G8ksaisL.d.ts}

@@ -1,4 +1,4 @@
-import { Address, WalletClient, Hash, Log, Transport } from 'viem';
+import { Address, WalletClient, Hash, Hex, Log, Transport } from 'viem';
 import { IndexerIntentStatus, Zkp2pClient, IndexerIntent, CurrencyType, PreparedTransaction, RuntimeEnv } from '@zkp2p/sdk';
 import { Execute, RelayClient, RelayChain, ProgressData } from '@relayprotocol/relay-sdk';
 
@@ -486,7 +486,8 @@ interface CashPlatformCapability {
     requiresIdentityAttestation: boolean;
     /**
      * @deprecated Always false. This does not report the sequential restricted-
-     * platform policy; prepared hosts must inspect `PrepareResult.accessPolicyRequired`.
+     * platform defaults; prepared hosts must inspect both method lists on
+     * `PrepareResult`.
      */
     requiresAtomicAccessPolicy: boolean;
 }
@@ -764,8 +765,12 @@ interface CashoutResult {
     onchainDepositId: bigint;
     /** Optimistic snapshot (`awaiting-buyer`); poll `order(depositId)` for live state. */
     order: CashOrder;
-    /** Confirmed access-policy transaction when any payout leg is Venmo, Cash App, or PayPal. */
+    /** Last confirmed access-policy transaction. Retained for single-policy compatibility. */
     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). */
@@ -794,6 +799,12 @@ interface PrepareResult {
     };
     /** Whether the host must submit and confirm the policy after `createDeposit` confirms. */
     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 {
@@ -870,8 +881,10 @@ interface CashClient {
     prepare(input: CashoutInput): Promise<PrepareResult>;
     /** Resolve an externally executed createDeposit receipt into resumable cash-out state. */
     finalizePreparedCashout(receipt: PreparedCashoutReceipt): CashoutResult;
-    /** Prepare the required four-group follow-up for a restricted cash-out. */
-    prepareAccessPolicy(depositId: string): PreparedTransaction;
+    /** 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>;
     /**