@zkp2p/cash 0.4.7 → 0.4.9

package/AGENTS.md

@@ -1,5 +1,9 @@
 # @zkp2p/cash - agent integration manual
 
+> This file is the shipped manual for agents **using** the package. To
+> contribute to the SDK itself (layout, ground rules, CI, releasing), start at
+> [CLAUDE.md](https://github.com/zkp2p/peer-cash/blob/main/CLAUDE.md).
+
 You are integrating Peer Cash: an offramp that routes any Relay-supported EVM
 source asset into Base USDC, then converts Base USDC to fiat (Venmo, Revolut,
 Wise, Zelle, ...) at the live Chainlink market rate. The user whose USDC you
@@ -9,16 +13,18 @@ can withdraw an unmatched deposit.
 
 ## Decision tree: pick your entry point
 
-1. **You control a signer in-process** (viem `WalletClient`, e.g. a local
-   key or embedded wallet) → use `cashout()` / `topUp()` / `withdraw()`
-   directly.
+1. **You control a signer in-process** (any viem `WalletClient`, including a
+   local or externally connected EOA) → use `cashout()` / `topUp()` /
+   `withdraw()` directly. No Privy wallet is required.
 2. **Signing happens elsewhere** (AA bundler, policy engine, custody service,
    human approval step) → use `prepare()` / `prepareTopUp()` /
    `prepareWithdraw()`. Each returns unsigned `txs[]`
    (`{ to, data, value, chainId }`) plus same-index `steps[]` labels; inspect
    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`.
+   persist the returned `depositId`. If the original plan set
+   `accessPolicyRequired: true`, submit and confirm
+   `prepareAccessPolicy(depositId)` with the depositor next.
 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,
@@ -32,19 +38,23 @@ Every transaction (including approves) carries ERC-8021 attribution:
 code. The namespaced referral marker gives its Peer Privy wallet the direct
 deposit-level integration share instead of applying maker L1/L2.
 
-**Platform caveats, all surfaced in `capabilities()`:**
+**Platform caveats:**
 
-- **Venmo, Cash App, and PayPal** carry
-  `requiresAtomicAccessPolicy: true`. Generic `cashout()` and `prepare()` reject
-  them with `ATOMIC_ACCESS_POLICY_REQUIRED` before any side effect. Use Peer
-  web's Curator-backed atomic flow or a host with the same atomic guarantee;
-  never create the deposit and attach the group policy sequentially.
+- **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.
 
 - **Wise and PayPal** carry `requiresIdentityAttestation: true`. A new curator
   registration needs a signed maker identity attestation this SDK cannot mint
-  (it comes from the Peer app/extension). An already-registered handle can be
-  reused with bare payee data. A new handle without its attestation fails with
-  `PAYEE_VERIFICATION_REQUIRED` before funds move on-chain.
+  (first-party Peer web obtains it through the Peer TEE browser extension).
+  An already-registered handle can be reused with bare payee data. A new handle
+  without its attestation fails with `PAYEE_VERIFICATION_REQUIRED` before funds
+  move on-chain.
 - **Venmo, Revolut, Cash App, Monzo** validate the handle against the live
   platform at registration - the account must exist. The rest (Zelle, Chime,
   etc.) are format-checked only. Match handles to the `payeeHint`.
@@ -178,6 +188,10 @@ console.log(routed.source?.transactions?.origin, routed.source?.transactions?.de
   broadcast; follow its recovery action and inspect wallet/protocol state.
   `TRANSACTION_STATUS_UNKNOWN` means the returned hash may already have
   succeeded. Inspect `err.recovery.transactionHash` first.
+- **Never repeat a cash-out after an access-policy failure.** The deposit
+  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.
 - **`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.
@@ -212,10 +226,10 @@ Every `CashError` carries `code`, `retryable`, `remediation`. Behavior:
 | `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        | Register a new Wise/PayPal payee through Peer; an existing registered handle can be reused |
+| `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        | Use Peer web or an equivalent atomic host for Venmo, Cash App, or PayPal; nothing moved    |
-| `ACCESS_POLICY_CONFIGURATION_FAILED`    | no        | Recover an existing `0.4.4` deposit from its policy recovery data; do not create it again  |
+| `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                                                  |
@@ -255,7 +269,8 @@ and tool results.
 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`.
+1. `cashout()` a small amount (1–2 USDC) → capture `depositId` and, for a
+   restricted payout, `accessPolicyTxHash`.
 2. `order(depositId)` shows `awaiting-buyer` (retry through indexer lag).
 3. `orders(owner)` includes the deposit.
 4. `withdraw(depositId)` → transaction succeeds.

package/README.md

@@ -1,8 +1,8 @@
 # @zkp2p/cash
 
-Route any Relay-supported EVM source asset into Base USDC, then cash out to fiat
-on Venmo, Revolut, Wise, Zelle, and more at the live Chainlink market rate,
-with zero spread and no centralized off-ramp provider.
+Route any Relay-supported EVM source asset into Base USDC, then cash out to
+fiat 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 deposit in
@@ -12,18 +12,13 @@ No hosted widget, no provider custody, no quote engine to maintain.
 
 **[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:
+## Install
 
-| 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. |
+```sh
+npm install @zkp2p/cash viem
+```
 
-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.
+## Quickstart
 
 ```ts
 import { createCashClient, usdc } from '@zkp2p/cash';
@@ -43,13 +38,15 @@ const fillStats = await cash.fillStats();
 const pairStats = fillStats['venmo:USD'];
 const multiCurrencyStats = fillStats['revolut:EUR+GBP+USD'];
 
-const { depositId } = await cash.cashout(
+const { depositId, accessPolicyTxHash } = await cash.cashout(
   {
     amount: usdc(1000),
-    receive: { platform: 'chime', currency: 'USD', payee: '$you' },
+    receive: { platform: 'venmo', currency: 'USD', payee: '@you' },
   },
-  { signer }, // any viem WalletClient on Base
+  { 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);
 
 // One method can offer several currencies. The buyer chooses the fill
 // currency, and each option resolves at its own live oracle rate.
@@ -71,7 +68,7 @@ const widestReach = await cash.cashout(
   {
     amount: usdc(1000),
     receive: [
-      { platform: 'chime', currency: 'USD', payee: '$you' },
+      { platform: 'venmo', currency: 'USD', payee: '@you' },
       { platform: 'revolut', currencies: ['EUR', 'GBP'], payee: { offchainId: 'revtag' } },
     ],
   },
@@ -84,52 +81,18 @@ for await (const order of cash.watch(depositId)) {
 }
 ```
 
-## Earn the integration share
-
-Use the same six-character referral code shown in your Peer mobile or web app.
-No API key, registration transaction, or separate receiving address is needed:
-the referral code already belongs to your Peer Privy wallet.
-
-```ts
-const cash = createCashClient({
-  environment: 'production',
-  referralCode: 'ABC123',
-});
-```
-
-The SDK normalizes the value and stamps `peer-ref-ABC123` into ERC-8021
-attribution on the deposit transaction. When that liquidity is filled, Curator
-pays the code owner 50 bps, capped by the configured Peer service fee. This is
-the deposit-level integration path: it replaces the maker L1/L2 referral split
-for that deposit instead of enrolling the cashing-out user as your referee.
-
-The mapping is permanent. If you later customize your displayed Peer referral
-code, open deposits carrying the old code still pay the same wallet. Include at
-most one `peer-ref-XXXXXX` marker; an unknown or conflicting marker receives no
-integration share. The existing `referrer` option remains available for
-analytics-only ERC-8021 codes such as `acme-app`.
+## Pick the right SDK
 
-Source asset path:
+Peer Cash and the general ZKP2P SDK serve different integration depths:
 
-```ts
-const { depositId, source } = await cash.cashout(
-  {
-    amount: 10_000_000n, // exact input: 10 USDC in source-token base units
-    source: {
-      chainId: 1,
-      currency: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
-      tradeType: 'EXACT_INPUT',
-    },
-    receive: { platform: 'chime', currency: 'USD', payee: { offchainId: '$you' } },
-  },
-  { signer, sourceSigner },
-);
+| 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. |
 
-// source.amount is Relay's guaranteed minimum Base USDC output and the exact
-// 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);
-```
+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.
 
 ## The core verbs
 
@@ -141,9 +104,9 @@ console.log(source?.transactions?.origin, source?.transactions?.destination);
 | `quoteSource(input)` / `executeSourceQuote(quote, { signer })` | Relay SDK EVM source routing into Base USDC before cashout                                                                      |
 | `relayStatus(requestId)`                                       | Relay request status from the Relay SDK request path                                                                            |
 | `estimate({ amount, currency }, { includeEta? })`              | Base USDC oracle estimate; optionally skip the historical ETA for progressive rendering                                         |
-| `cashout(input, { signer })`                                   | Registers the payee and creates an unrestricted-rail order; protected rails fail before any side effect                         |
-| `prepare(input)` / `finalizePreparedCashout(receipt)`          | Prepare unrestricted-rail external signing, then resolve the confirmed createDeposit receipt into resumable state               |
-| `prepareAccessPolicy(depositId)`                               | Recover a restricted-rail deposit created by the unsafe `0.4.4` sequential flow; never use it to create a new order             |
+| `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                                                |
 | `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) |
@@ -165,31 +128,55 @@ Peer Cash transaction, including approves, carries ERC-8021 attribution:
 `peer-cash` first, optional `peer-ref-XXXXXX` from `referralCode` next, and your
 analytics-only `referrer` code(s) after it.
 
-Venmo, Cash App, and PayPal must attach Plus, Pro, Peer Makers, and Peer Pay in
-the same atomic operation that creates the deposit. A create-then-configure
-sequence leaves a public interval in which an unapproved taker can signal an
-intent. The generic `cashout()` and `prepare()` paths therefore throw
-`ATOMIC_ACCESS_POLICY_REQUIRED` before wallet access, Relay quoting, payee
-registration, allowance, or deposit submission. Peer web supports these rails
-through its atomic Curator-backed flow. Other hosts must provide an equivalent
-atomic batch rather than composing the two public SDK calls sequentially.
-`capabilities()` marks these platforms with
-`requiresAtomicAccessPolicy: true`.
-
-`prepareAccessPolicy(depositId)` remains available only to recover a restricted
-deposit already created by `0.4.4`. Configure that existing deposit immediately;
-do not call `cashout()` again and do not use this recovery helper as a new-order
-flow.
+Order reads fail closed against the same active catalog. If any method on an
+indexed deposit is unsupported, `orders()` excludes the whole deposit and
+`order()` returns `ORDER_NOT_FOUND`; Peer Cash never partially reclassifies a
+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 |
+
+No platform requires an atomic access-policy flow. `cashout()` and `prepare()`
+work with any viem `WalletClient`, including a local or externally connected
+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.
+
+If policy attachment fails, `ACCESS_POLICY_CONFIGURATION_FAILED.recovery`
+identifies the existing deposit and any submitted policy transaction. Never
+create another cash-out. When `recovery.transactionHash` is present, inspect
+that transaction before resubmitting; otherwise prepare the policy again with
+the same depositor wallet.
 
 `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
 never changes the on-chain payment method.
 
-Order reads fail closed against the same active catalog. If any method on an
-indexed deposit is unsupported, `orders()` excludes the whole deposit and
-`order()` returns `ORDER_NOT_FOUND`; Peer Cash never partially reclassifies a
-mixed historical deposit.
+`capabilities()` tells you which platforms need a verified identity for a new
+payee registration (`requiresIdentityAttestation` - Wise and PayPal today).
+The SDK accepts an `identityAttestation` in structured payee data but does not
+mint one. First-party Peer web obtains it through the Peer TEE browser
+extension. An already-registered Wise or PayPal handle can be reused with bare
+payee data. A new handle without its signed attestation fails during curator
+registration with `PAYEE_VERIFICATION_REQUIRED`, before funds move on-chain.
+
+## Source routing (any EVM asset in)
 
 The default/minimal flow is unchanged: pass Base USDC base units to
 `estimate()` and `cashout()`. For any other source asset, pass `source` to
@@ -201,6 +188,27 @@ The destination is always canonical Base USDC
 discovered and quoted by `@relayprotocol/relay-sdk`, not a static token
 allowlist.
 
+```ts
+const { depositId, accessPolicyTxHash, source } = await cash.cashout(
+  {
+    amount: 10_000_000n, // exact input: 10 USDC in source-token base units
+    source: {
+      chainId: 1,
+      currency: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+      tradeType: 'EXACT_INPUT',
+    },
+    receive: { platform: 'venmo', currency: 'USD', payee: { offchainId: '@you' } },
+  },
+  { signer, sourceSigner },
+);
+
+// source.amount is Relay's guaranteed minimum Base USDC output and the exact
+// 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
+```
+
 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
@@ -208,12 +216,6 @@ 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.
-A new handle without its signed attestation fails during curator registration
-with `PAYEE_VERIFICATION_REQUIRED`, before funds move on-chain.
-
 ## Source-route recovery
 
 Persist `depositId`, transaction hashes, and the Relay `requestId` as soon as
@@ -239,6 +241,11 @@ they are available. A source-routed result includes both a flat
 - `TRANSACTION_SUBMISSION_UNKNOWN`: a Base-only cashout or another mutation
   returned no hash. Treat it as potentially broadcast. Inspect recent Base
   wallet activity and the supplied recovery action before any retry.
+- `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
+  transaction did not succeed.
 
 Wallet clients pinned to the wrong chain fail with `SIGNER_CHAIN_MISMATCH`
 before a quote or transaction is submitted. Chainless wallets are checked
@@ -285,6 +292,31 @@ awaiting-buyer ──────────► matched ───────
 
 Deep dive: [docs/lifecycle-and-recovery.md](docs/lifecycle-and-recovery.md).
 
+## Earn the integration share
+
+Use the same six-character referral code shown in your Peer mobile or web app.
+No API key, registration transaction, or separate receiving address is needed:
+the referral code already belongs to your Peer Privy wallet.
+
+```ts
+const cash = createCashClient({
+  environment: 'production',
+  referralCode: 'ABC123',
+});
+```
+
+The SDK normalizes the value and stamps `peer-ref-ABC123` into ERC-8021
+attribution on the deposit transaction. When that liquidity is filled, Curator
+pays the code owner 50 bps, capped by the configured Peer service fee. This is
+the deposit-level integration path: it replaces the maker L1/L2 referral split
+for that deposit instead of enrolling the cashing-out user as your referee.
+
+The mapping is permanent. If you later customize your displayed Peer referral
+code, open deposits carrying the old code still pay the same wallet. Include at
+most one `peer-ref-XXXXXX` marker; an unknown or conflicting marker receives no
+integration share. The existing `referrer` option remains available for
+analytics-only ERC-8021 codes such as `acme-app`.
+
 ## For agents
 
 - `cashout`/`withdraw`/`topUp` have unsigned counterparts (`prepare`,
@@ -292,6 +324,9 @@ Deep dive: [docs/lifecycle-and-recovery.md](docs/lifecycle-and-recovery.md).
   before signing, then submit the matching `txs[]` in order.
 - 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.
 - 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
@@ -322,12 +357,6 @@ defaults to `https://api-staging.zkp2p.xyz`. Indexer, curator, and Relay
 options remain overridable via `createCashClient` options. Base USDC on Base
 is the default source and the only destination asset for cashout orders.
 
-## Install
-
-```sh
-npm install @zkp2p/cash viem
-```
-
 ## Examples
 
 Runnable first-party examples in [`examples/`](examples):
@@ -342,6 +371,13 @@ dependency currently ships from private source. Onchain custody is enforced by
 the protocol: only the contract holds funds, and only the maker can withdraw
 an unmatched deposit.
 
+## Contributing
+
+[CLAUDE.md](https://github.com/zkp2p/peer-cash/blob/main/CLAUDE.md) is the
+contributor guide: ground rules, repo layout, the `bun run ci` gate, and the
+release/publish process. `AGENTS.md` is the shipped manual for agents using
+the package, not the contributor entry point.
+
 ## License
 
 MIT

package/dist/{chunk-SYE25ICW.js → chunk-4LPWKZMW.js}

@@ -194,15 +194,16 @@ var errors = {
       code: "PAYEE_VERIFICATION_REQUIRED",
       message: `${platform} requires a verified maker identity attestation to register a payee; a bare handle is not accepted.`,
       retryable: false,
-      remediation: `Register this ${platform} payee through the ZKP2P app / extension (which produces the signed identity attestation) before cashing out. capabilities() flags such platforms with requiresIdentityAttestation: true.`
+      remediation: `Register this ${platform} payee through Peer web and its TEE browser extension, which produces the signed identity attestation, before cashing out. capabilities() flags such platforms with requiresIdentityAttestation: true.`
     },
     { cause }
   ),
+  /** @deprecated Cash-outs no longer require an atomic access-policy flow. */
   atomicAccessPolicyRequired: (platforms) => new CashError({
     code: "ATOMIC_ACCESS_POLICY_REQUIRED",
-    message: `${platforms.join(", ")} cash-outs require atomic deposit creation and access-policy configuration.`,
+    message: `Atomic access-policy enforcement for ${platforms.join(", ")} is deprecated.`,
     retryable: false,
-    remediation: `Use Peer web or a host that atomically batches guard-before, createDeposit, guard-after, and configureDeposit. Nothing was submitted by this call.`
+    remediation: `Upgrade @zkp2p/cash; current cash-out flows do not require atomic access-policy configuration.`
   }),
   sourceRouteUnsupportedInPrepare: () => new CashError({
     code: "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE",
@@ -405,20 +406,28 @@ var errors = {
     },
     { cause }
   ),
-  accessPolicyConfigurationFailed: (depositId, groupIds, cause, transactionHash) => new CashError(
+  accessPolicyConfigurationFailed: (depositId, groupIds, context = {}) => new CashError(
     {
       code: "ACCESS_POLICY_CONFIGURATION_FAILED",
-      message: `Cash-out deposit ${depositId} was created, but its required access policy was not confirmed.`,
+      message: `Cash-out deposit ${depositId} was created, but its access policy could not be confirmed.`,
       retryable: false,
-      remediation: `Do not call cashout() again. Inspect the existing deposit and any access-policy transaction, then configure that deposit with recovery.groupIds through @zkp2p/sdk accessPolicy.`,
+      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.`,
       recovery: {
         kind: "configure-cashout-access-policy",
         depositId,
         groupIds: [...groupIds],
-        ...transactionHash ? { transactionHash } : {}
+        ...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 }
+    { cause: context.cause }
   ),
   escrowPaused: () => new CashError({
     code: "ESCROW_PAUSED",

package/dist/{createCashClient-CL1SCbqF.d.cts → createCashClient-Br7uu4lQ.d.cts}

@@ -306,14 +306,15 @@ interface CashPlatformCapability {
     payeeHint: string;
     /**
      * When true, registering a payee for this platform requires a signed maker
-     * identity attestation the SDK cannot produce - register the payee via the
-     * ZKP2P app/extension first. A bare-handle `cashout()` throws
+     * identity attestation the SDK cannot produce. First-party Peer web obtains
+     * it through the Peer TEE browser extension. Existing registrations can be
+     * reused with bare payee data; a new bare handle throws
      * `PAYEE_VERIFICATION_REQUIRED`.
      */
     requiresIdentityAttestation: boolean;
     /**
-     * When true, the platform needs deposit creation and access-policy setup in
-     * one atomic host operation. Generic `cashout()` and `prepare()` fail closed.
+     * @deprecated Always false. This does not report the sequential restricted-
+     * platform policy; prepared hosts must inspect `PrepareResult.accessPolicyRequired`.
      */
     requiresAtomicAccessPolicy: boolean;
 }
@@ -549,7 +550,7 @@ interface CashoutInput {
     };
 }
 interface SignerOptions {
-    /** A viem WalletClient with an account, on Base. */
+    /** Any viem WalletClient with a Base account, including a local or external EOA. */
     signer: WalletClient;
 }
 interface CashoutOptions extends SignerOptions {
@@ -587,7 +588,7 @@ interface CashoutResult {
     onchainDepositId: bigint;
     /** Optimistic snapshot (`awaiting-buyer`); poll `order(depositId)` for live state. */
     order: CashOrder;
-    /** @deprecated Only present in recovery data produced by the unsafe 0.4.4 sequential flow. */
+    /** Confirmed access-policy transaction when any payout leg is Venmo, Cash App, or PayPal. */
     accessPolicyTxHash?: Hash;
     /** Present when `cashout()` first routed a source asset through Relay. */
     source?: {
@@ -615,7 +616,7 @@ interface PrepareResult {
     register: {
         hashedOnchainIds: string[];
     };
-    /** @deprecated Always false for new plans; restricted rails require an atomic host flow. */
+    /** Whether the host must submit and confirm the policy after `createDeposit` confirms. */
     accessPolicyRequired: boolean;
 }
 /** Confirmed createDeposit receipt from an externally executed prepare() plan. */
@@ -679,7 +680,7 @@ interface CashClient {
     prepare(input: CashoutInput): Promise<PrepareResult>;
     /** Resolve an externally executed createDeposit receipt into resumable cash-out state. */
     finalizePreparedCashout(receipt: PreparedCashoutReceipt): CashoutResult;
-    /** Recover an existing 0.4.4 restricted-rail deposit by preparing its four-group policy. */
+    /** Prepare the required four-group follow-up for a restricted cash-out. */
     prepareAccessPolicy(depositId: string): PreparedTransaction;
     /** 3 - Observe: resumable from `depositId` alone; no session state anywhere. */
     order(depositId: string): Promise<CashOrder>;

package/dist/{createCashClient-CL1SCbqF.d.ts → createCashClient-Br7uu4lQ.d.ts}

@@ -306,14 +306,15 @@ interface CashPlatformCapability {
     payeeHint: string;
     /**
      * When true, registering a payee for this platform requires a signed maker
-     * identity attestation the SDK cannot produce - register the payee via the
-     * ZKP2P app/extension first. A bare-handle `cashout()` throws
+     * identity attestation the SDK cannot produce. First-party Peer web obtains
+     * it through the Peer TEE browser extension. Existing registrations can be
+     * reused with bare payee data; a new bare handle throws
      * `PAYEE_VERIFICATION_REQUIRED`.
      */
     requiresIdentityAttestation: boolean;
     /**
-     * When true, the platform needs deposit creation and access-policy setup in
-     * one atomic host operation. Generic `cashout()` and `prepare()` fail closed.
+     * @deprecated Always false. This does not report the sequential restricted-
+     * platform policy; prepared hosts must inspect `PrepareResult.accessPolicyRequired`.
      */
     requiresAtomicAccessPolicy: boolean;
 }
@@ -549,7 +550,7 @@ interface CashoutInput {
     };
 }
 interface SignerOptions {
-    /** A viem WalletClient with an account, on Base. */
+    /** Any viem WalletClient with a Base account, including a local or external EOA. */
     signer: WalletClient;
 }
 interface CashoutOptions extends SignerOptions {
@@ -587,7 +588,7 @@ interface CashoutResult {
     onchainDepositId: bigint;
     /** Optimistic snapshot (`awaiting-buyer`); poll `order(depositId)` for live state. */
     order: CashOrder;
-    /** @deprecated Only present in recovery data produced by the unsafe 0.4.4 sequential flow. */
+    /** Confirmed access-policy transaction when any payout leg is Venmo, Cash App, or PayPal. */
     accessPolicyTxHash?: Hash;
     /** Present when `cashout()` first routed a source asset through Relay. */
     source?: {
@@ -615,7 +616,7 @@ interface PrepareResult {
     register: {
         hashedOnchainIds: string[];
     };
-    /** @deprecated Always false for new plans; restricted rails require an atomic host flow. */
+    /** Whether the host must submit and confirm the policy after `createDeposit` confirms. */
     accessPolicyRequired: boolean;
 }
 /** Confirmed createDeposit receipt from an externally executed prepare() plan. */
@@ -679,7 +680,7 @@ interface CashClient {
     prepare(input: CashoutInput): Promise<PrepareResult>;
     /** Resolve an externally executed createDeposit receipt into resumable cash-out state. */
     finalizePreparedCashout(receipt: PreparedCashoutReceipt): CashoutResult;
-    /** Recover an existing 0.4.4 restricted-rail deposit by preparing its four-group policy. */
+    /** Prepare the required four-group follow-up for a restricted cash-out. */
     prepareAccessPolicy(depositId: string): PreparedTransaction;
     /** 3 - Observe: resumable from `depositId` alone; no session state anywhere. */
     order(depositId: string): Promise<CashOrder>;