@zkp2p/cash 0.1.0-dev.0

package/AGENTS.md

@@ -0,0 +1,131 @@
+# @zkp2p/cash - agent integration manual
+
+You are integrating Peer Cash: an offramp that converts Base USDC to fiat
+(Venmo, Revolut, Wise, Zelle, ...) at the live Chainlink market rate. The user
+whose USDC you manage is the **maker**; a buyer pays them fiat and proves it
+with TEE-TLS; the protocol releases the USDC. Funds are held by the protocol,
+and only the maker 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.
+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.
+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. Mutating
+   tools return unsigned transactions; keep signing host-side.
+
+Every transaction (including approves) carries ERC-8021 attribution:
+`peer-cash`, then any `referrer` codes from `createCashClient` options, then
+the Base builder code.
+
+**Two platform caveats, both surfaced in `capabilities()`:**
+
+- **Wise and PayPal** carry `requiresIdentityAttestation: true`. Their curator
+  registration needs a signed maker identity attestation this SDK cannot mint
+  (it comes from the ZKP2P app/extension). A bare-handle `cashout()` to these
+  fails fast with `PAYEE_VERIFICATION_REQUIRED` before any transaction.
+- **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`.
+
+## The loop
+
+```ts
+import { createCashClient, usdc, isCashError } from '@zkp2p/cash';
+
+const cash = createCashClient({ environment: 'production' });
+
+// 1. Discover - static and side-effect free, do this once.
+const caps = cash.capabilities();
+
+// 2. Estimate - idempotent, cacheable, no side effects.
+const est = await cash.estimate({ amount: usdc(500), currency: 'EUR' });
+
+// 3. Execute.
+const { depositId } = await cash.cashout(
+  {
+    amount: usdc(500),
+    receive: { platform: 'revolut', currency: 'EUR', payee: { offchainId: 'revtag' } },
+  },
+  { signer },
+);
+
+// 4. Persist depositId ↔ your user. That row is the entire integration state.
+
+// 5. Drive the lifecycle from nextActions - no heuristics.
+const order = await cash.order(depositId);
+if (order.nextActions.includes('withdraw') && shouldUnwind) {
+  await cash.withdraw(depositId, { signer });
+} else if (order.nextActions.includes('wait')) {
+  // poll again later, or `for await (const o of cash.watch(depositId))`
+}
+```
+
+## Rules that prevent wrong behavior
+
+- **Never promise a rate.** `estimate()` is `kind: 'oracle-estimate'`; the
+  binding rate resolves at the oracle when a buyer fills. Do not display or
+  log it as a locked price.
+- **Never invent an ETA.** Use `order.explain()` - one honest sentence from
+  live data. Buyer arrival time is not knowable.
+- **`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.
+- **Unwind with `withdraw()` only.** It is state-aware (prunes expired
+  intents first). Do not call escrow functions directly.
+- **Read fills as receipts.** `fiatOwed` is the buyer's obligation at the
+  locked rate; after the proof, `fiatPaid`/`paymentId`/`releasedAmount` are
+  the verified outcome. Reconcile against those, not your own math.
+- **Check the buyer during `matched`.** `buyer(address)` (tool: `cash_buyer`)
+  returns their fulfilled/pruned history and success rate - surface it
+  instead of a raw address.
+- **Serialize with the codecs.** `orderToJson`/`orderFromJson` etc. round-trip
+  bigints losslessly and re-attach `explain()`. Plain `JSON.stringify` on a
+  live object throws on bigints.
+
+## Error → remediation table
+
+Every `CashError` carries `code`, `retryable`, `remediation`. Behavior:
+
+| Code                              | Retryable | Agent action                                                                                    |
+| --------------------------------- | --------- | ----------------------------------------------------------------------------------------------- |
+| `ORACLE_UNSUPPORTED_CURRENCY`     | no        | Re-pick currency from `capabilities()`                                                          |
+| `UNSUPPORTED_PLATFORM`            | no        | Re-pick platform from `capabilities()`                                                          |
+| `AMOUNT_BELOW_MINIMUM`            | no        | Raise amount (hard floor $0.01, recommended ≥ 1 USDC)                                           |
+| `PAYEE_VERIFICATION_REQUIRED`     | no        | Wise/PayPal need a signed identity attestation - register the payee via the ZKP2P app first     |
+| `PAYEE_REGISTRATION_FAILED`       | yes       | Validate handle against `payeeHint`, retry with backoff (curator caps at 20 registrations/min)  |
+| `ALLOWANCE_NOT_VISIBLE`           | yes       | Approve mined but a stale RPC replica hid it; retry the same call in a few seconds              |
+| `TRANSACTION_FAILED`              | no        | The on-chain call reverted or was mapped from a raw error; surface to operator; funds unchanged |
+| `DEPOSIT_RESOLUTION_FAILED`       | no        | Extract depositId from the `DepositReceived` log in the receipt                                 |
+| `ORDER_NOT_FOUND`                 | yes       | Retry (indexer lag) unless the id is provably wrong                                             |
+| `INDEXER_LAG`                     | yes       | Retry after a few seconds                                                                       |
+| `ACTIVE_INTENT_BLOCKS_WITHDRAWAL` | yes       | Wait; retry full `withdraw()` after intent expiry (or withdraw the unlocked part with `amount`) |
+| `INSUFFICIENT_AVAILABLE_FUNDS`    | yes       | Partial amount exceeds the unlocked balance; lower it or close fully later                      |
+| `NOTHING_TO_WITHDRAW`             | no        | Order is terminal; reconcile your records                                                       |
+| `ORDER_NOT_ACTIVE`                | no        | Top-up target is closed; start a new `cashout()` instead                                        |
+| `SIGNER_REQUIRED`                 | no        | Provide `{ signer }` or switch to the prepare path                                              |
+| `WATCH_TIMEOUT`                   | yes       | Resume `watch(depositId)` whenever convenient                                                   |
+| `ESCROW_PAUSED`                   | yes       | Back off; existing funds remain withdrawable                                                    |
+
+`isCashError(err)` narrows unknown errors; `err.toJSON()` is safe for logs
+and tool results.
+
+## Verification checklist (staging, maker-side only)
+
+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`.
+2. `order(depositId)` shows `awaiting-buyer` (retry through indexer lag).
+3. `orders(owner)` includes the deposit.
+4. `withdraw(depositId)` → transaction succeeds.
+5. `order(depositId)` shows `returned`; wallet balance is restored minus gas.
+
+If step 4 ever fails with funds stuck, stop and escalate - do not retry
+blindly.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZKP2P
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# @zkp2p/cash
+
+Cash out Base USDC 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
+protocol-held deposit, ZKP2P handles the buyer side, and the SDK gives the
+integrator a small set of typed verbs plus readable order state. No hosted
+widget, no provider custody, no quote engine to maintain.
+
+```ts
+import { createCashClient, usdc } from '@zkp2p/cash';
+
+const cash = createCashClient({ environment: 'production' });
+
+const est = await cash.estimate({ amount: usdc(1000), currency: 'USD' });
+// { rate: 1, receiveAmount: 1000, kind: 'oracle-estimate' } - "≈", never a locked quote
+
+const { depositId } = await cash.cashout(
+  {
+    amount: usdc(1000),
+    receive: { platform: 'venmo', currency: 'USD', payee: { offchainId: '@you' } },
+  },
+  { signer }, // any viem WalletClient on Base
+);
+
+for await (const order of cash.watch(depositId)) {
+  console.log(order.state, order.explain());
+  if (order.state === 'delivered') break;
+}
+```
+
+## The eight verbs
+
+| Verb                                       | What it does                                                                                                                    |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `capabilities()`                           | Sync discovery: platforms × currencies × payee format hints × amount bounds                                                     |
+| `estimate({ amount, currency })`           | Live oracle rate - no payee, no side effects, idempotent                                                                        |
+| `cashout(input, { signer })`               | Registers your payee, creates the protocol-held order, returns the `depositId`                                                  |
+| `prepare(input)`                           | Same as cashout but returns unsigned `txs[]` + readable `steps[]` - agent wallets, AA, server keys                              |
+| `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) |
+| `topUp(depositId, amount, { signer })`     | Add USDC to a live order - same payee, same market rate                                                                         |
+| `buyer(address)`                           | A buyer's track record from their intent history - who just matched your order?                                                 |
+
+Every mutating verb has an unsigned counterpart (`prepare`, `prepareWithdraw`,
+`prepareTopUp`). The unsigned path returns raw `txs[]` plus a same-index
+`steps[]` plan such as `approve`, `createDeposit`, or `withdrawDeposit`, so
+wallets, AA systems, and agents can show what each transaction does before
+signing. Every transaction - including approves - carries ERC-8021
+attribution: `peer-cash` first, your own `referrer` code(s) after it, so
+onchain analytics can segment cash flow end to end.
+
+`capabilities()` tells you which platforms need a verified identity to
+register a payee (`requiresIdentityAttestation` - Wise and PayPal today); a
+bare-handle `cashout()` to those fails fast with `PAYEE_VERIFICATION_REQUIRED`
+rather than reverting on-chain.
+
+## Lifecycle
+
+```
+            buyer signals            fiat proven
+awaiting-buyer ──────────► matched ──────────► delivered
+      │                       │    (partial fills pass through "delivering")
+      │ withdraw()            │ buyer never pays → intent expires
+      ▼                       ▼ withdraw() prunes + returns funds
+   returned ◄─────────────────┘
+```
+
+- **You are the maker.** Your deposit is priced by the live Chainlink oracle
+  with `spreadBps: 0`, making it the best offer on the book by construction.
+- **There is no quote.** The binding rate resolves at the oracle when a buyer
+  fills. `estimate()` says "approximately"; nothing in this API pretends to
+  lock a price.
+- **Everything is resumable.** An order is reconstructed from the chain by
+  `depositId` alone. Close the tab, switch devices, crash the process - then
+  call `order(depositId)`.
+- **Unwind is one verb.** Buyer never paid? Their intent expires; `withdraw()`
+  prunes it and returns your USDC. You never choose between cancel and recover.
+
+Deep dive: [docs/lifecycle-and-recovery.md](docs/lifecycle-and-recovery.md).
+
+## For agents
+
+- `cashout`/`withdraw`/`topUp` have unsigned counterparts (`prepare`,
+  `prepareWithdraw`, `prepareTopUp`) - inspect readable `steps[]` and calldata
+  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.
+- 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
+  boundaries losslessly.
+- Everything arrives decoded: platform ids and currency codes instead of
+  bytes32 hashes, plain-number rates instead of 1e18 bigints.
+- Fills are receipts: the locked rate and fiat owed at signal, then the
+  verified fiat paid, currency, platform payment id, released USDC, and
+  fill latency once the proof lands.
+- `@zkp2p/cash/tools` exports a JSON-schema tool manifest of the verbs.
+
+Start at [AGENTS.md](AGENTS.md), or load the
+[`peer-cash-integration` skill](skills/peer-cash-integration/SKILL.md).
+
+## React
+
+```ts
+import { useEstimate, useCashout, useOrder, useOrders } from '@zkp2p/cash/react';
+```
+
+React is an optional peer dependency - the root entry never imports it.
+
+## Environments
+
+`production` | `preproduction` | `staging` - selects contracts, curator, and
+indexer. Indexer and curator URLs are overridable via `createCashClient`
+options. v1 is same-chain only: Base USDC in.
+
+## Install
+
+```sh
+npm install @zkp2p/cash@dev viem
+```
+
+## Trust model, honestly
+
+This SDK is open source, so the code that constructs the parameters moving
+your USDC into protocol-held funds is auditable. It depends on the published
+`@zkp2p/sdk` for protocol internals, which currently ships from private source.
+The Peer Cash facade is verifiable here; the dependency is not yet fully open.
+Onchain custody is still enforced by the protocol: only the contract holds
+funds, and only you can withdraw an unmatched deposit.
+
+## License
+
+MIT

package/dist/chunk-4DRZRWWS.js

@@ -0,0 +1,176 @@
+// src/engine/constants.ts
+var BASE_CHAIN_ID = 8453;
+var BASE_USDC_ADDRESS = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
+var USDC_DECIMALS = 6;
+var MARKET_SPREAD_BPS = 0;
+var ORACLE_MIN_CONVERSION_RATE_SENTINEL = 1n;
+var CASH_ORDER_STATUSES = [
+  "SIGNALED",
+  "FULFILLED",
+  "PRUNED",
+  "MANUALLY_RELEASED"
+];
+var CASH_ORDER_POLL_INTERVAL_MS = 5e3;
+var CASH_RETAIN_ON_EMPTY = false;
+
+// src/client/errors.ts
+var CashError = class extends Error {
+  code;
+  retryable;
+  remediation;
+  constructor(shape, options) {
+    super(shape.message, options);
+    this.name = "CashError";
+    this.code = shape.code;
+    this.retryable = shape.retryable;
+    this.remediation = shape.remediation;
+  }
+  /** Serializable view (for tool results and logs). */
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      retryable: this.retryable,
+      remediation: this.remediation
+    };
+  }
+};
+function isCashError(value) {
+  return value instanceof CashError;
+}
+var errors = {
+  oracleUnsupportedCurrency: (currency) => new CashError({
+    code: "ORACLE_UNSUPPORTED_CURRENCY",
+    message: `${currency} has no live Chainlink oracle feed; Peer Cash is market-rate only.`,
+    retryable: false,
+    remediation: `Pick a currency listed in capabilities() - each one is priced by a live oracle feed.`
+  }),
+  unsupportedPlatform: (platform) => new CashError({
+    code: "UNSUPPORTED_PLATFORM",
+    message: `'${platform}' is not a supported payout platform in this environment.`,
+    retryable: false,
+    remediation: `Pick a platform listed in capabilities().`
+  }),
+  amountBelowMinimum: (amount, min) => new CashError({
+    code: "AMOUNT_BELOW_MINIMUM",
+    message: `Amount ${amount} is below the minimum cash-out of ${min} USDC base units.`,
+    retryable: false,
+    remediation: `Increase the amount to at least ${min} base units (${Number(min) / 1e6} USDC).`
+  }),
+  activeIntentBlocksWithdrawal: (depositId) => new CashError({
+    code: "ACTIVE_INTENT_BLOCKS_WITHDRAWAL",
+    message: `Order ${depositId} has a live buyer intent; escrow blocks withdrawal while a buyer may still deliver.`,
+    retryable: true,
+    remediation: `Wait for the buyer to complete or for their intent to expire, then call withdraw() again - it prunes expired intents automatically.`
+  }),
+  insufficientAvailableFunds: (depositId, requested, available) => new CashError({
+    code: "INSUFFICIENT_AVAILABLE_FUNDS",
+    message: `Order ${depositId} has ${available} base units available; ${requested} requested.`,
+    retryable: true,
+    remediation: `Withdraw at most the available (unlocked) amount, or omit the amount to close the order fully once no buyer intent is live.`
+  }),
+  orderNotActive: (depositId) => new CashError({
+    code: "ORDER_NOT_ACTIVE",
+    message: `Order ${depositId} is closed (delivered or returned); it cannot be topped up.`,
+    retryable: false,
+    remediation: `Start a new cash-out with cashout() instead.`
+  }),
+  nothingToWithdraw: (depositId) => new CashError({
+    code: "NOTHING_TO_WITHDRAW",
+    message: `Order ${depositId} holds no withdrawable funds (already delivered or returned).`,
+    retryable: false,
+    remediation: `Check order(depositId).state - this order is terminal.`
+  }),
+  indexerLag: (depositId) => new CashError({
+    code: "INDEXER_LAG",
+    message: `Order ${depositId} is not indexed yet (the deposit may be seconds old).`,
+    retryable: true,
+    remediation: `Retry in a few seconds; on-chain state is ahead of the indexer right after a transaction.`
+  }),
+  orderNotFound: (depositId) => new CashError({
+    code: "ORDER_NOT_FOUND",
+    message: `No deposit found for id ${depositId}.`,
+    retryable: true,
+    remediation: `Verify the composite depositId (escrow_onchainId). If the deposit was created seconds ago this is indexer lag - retry shortly.`
+  }),
+  payeeRegistrationFailed: (cause) => new CashError(
+    {
+      code: "PAYEE_REGISTRATION_FAILED",
+      message: `Registering payee details with the curator failed.`,
+      retryable: true,
+      remediation: `Check the payee handle format for the platform (see capabilities() hints) and retry.`
+    },
+    { cause }
+  ),
+  payeeVerificationRequired: (platform, cause) => new CashError(
+    {
+      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.`
+    },
+    { cause }
+  ),
+  allowanceNotVisible: (amount) => new CashError({
+    code: "ALLOWANCE_NOT_VISIBLE",
+    message: `USDC approval for ${amount} base units did not become visible on the read path in time.`,
+    retryable: true,
+    remediation: `The approve transaction mined but a load-balanced RPC is serving stale state. Retry the same call in a few seconds.`
+  }),
+  depositResolutionFailed: (txHash) => new CashError({
+    code: "DEPOSIT_RESOLUTION_FAILED",
+    message: `Deposit transaction ${txHash} succeeded but no DepositReceived event was found in the receipt.`,
+    retryable: false,
+    remediation: `Inspect the transaction on Basescan; recover the depositId from the DepositReceived log manually, then resume with order(depositId).`
+  }),
+  signerRequired: (verb) => new CashError({
+    code: "SIGNER_REQUIRED",
+    message: `${verb}() mutates on-chain state and needs a signer.`,
+    retryable: false,
+    remediation: `Pass { signer } (a viem WalletClient with an account), or use prepare() and submit the returned txs with your own signing infrastructure.`
+  }),
+  watchTimeout: (depositId, timeoutMs) => new CashError({
+    code: "WATCH_TIMEOUT",
+    message: `watch(${depositId}) exceeded ${timeoutMs}ms without reaching a terminal state.`,
+    retryable: true,
+    remediation: `The order is still live - resume any time with watch(depositId) or order(depositId).`
+  }),
+  transactionFailed: (txHash, cause) => new CashError(
+    {
+      code: "TRANSACTION_FAILED",
+      message: `Transaction ${txHash} reverted.`,
+      retryable: false,
+      remediation: `Inspect the transaction on Basescan; the deposit state is unchanged if the revert happened before escrow accepted funds.`
+    },
+    { cause }
+  ),
+  escrowPaused: () => new CashError({
+    code: "ESCROW_PAUSED",
+    message: `The escrow contract is paused; deposits are temporarily disabled.`,
+    retryable: true,
+    remediation: `Wait for the protocol to unpause and retry. Existing funds remain withdrawable.`
+  }),
+  /** Generic fallback for an on-chain call that failed for an unrecognized reason. */
+  chainCallFailed: (verb, cause) => new CashError(
+    {
+      code: "TRANSACTION_FAILED",
+      message: `The on-chain ${verb} call failed.`,
+      retryable: false,
+      remediation: `Inspect the error cause and the wallet on Basescan. Deposit state is unchanged if the call reverted before escrow accepted funds.`
+    },
+    { cause }
+  )
+};
+function mapChainError(verb, err) {
+  if (isCashError(err)) return err;
+  const message = err instanceof Error ? err.message : String(err);
+  if (/\bpaused\b/i.test(message)) return errors.escrowPaused();
+  if (/exceeds allowance|insufficient allowance|transfer amount exceeds/i.test(message)) {
+    return errors.allowanceNotVisible(0n);
+  }
+  return errors.chainCallFailed(verb, err);
+}
+
+export { BASE_CHAIN_ID, BASE_USDC_ADDRESS, CASH_ORDER_POLL_INTERVAL_MS, CASH_ORDER_STATUSES, CASH_RETAIN_ON_EMPTY, CashError, MARKET_SPREAD_BPS, ORACLE_MIN_CONVERSION_RATE_SENTINEL, USDC_DECIMALS, errors, isCashError, mapChainError };
+//# sourceMappingURL=chunk-4DRZRWWS.js.map
+//# sourceMappingURL=chunk-4DRZRWWS.js.map

package/dist/chunk-4DRZRWWS.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/engine/constants.ts","../src/client/errors.ts"],"names":[],"mappings":"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","file":"chunk-4DRZRWWS.js","sourcesContent":["/**\n * Peer Cash - engine constants.\n *\n * Peer Cash is an async crypto→fiat offramp built on the maker/deposit side of\n * the protocol: the cashing-out user IS the maker. They create a deposit at the\n * live oracle/market rate (0% spread); a buyer (a standard taker) signals an\n * intent, pays fiat, and proves it via the standard TEE-TLS flow, releasing the\n * user's crypto. The protocol is reused in its existing direction - no proof\n * inversion, no sell-side quote.\n */\nimport type { IntentStatus } from '../sdk-types';\n\n/** Base chain id - Peer Cash settles in Base USDC. */\nexport const BASE_CHAIN_ID = 8453;\n\n/** Canonical USDC on Base (6 decimals). The deposit asset for every cash-out. */\nexport const BASE_USDC_ADDRESS = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913' as const;\n\n/** USDC has 6 decimals. */\nexport const USDC_DECIMALS = 6;\n\n/**\n * Market rate = the live Chainlink oracle with **zero spread**. The user sets no\n * rate; selling at market is the fast-fill incentive (the deposit is the best\n * deal on the book, so buyers have reason to take it quickly).\n */\nexport const MARKET_SPREAD_BPS = 0;\n\n/**\n * EscrowV2 rejects a zero `minConversionRate` even when an oracle-backed rate\n * config is attached. Use the smallest non-zero sentinel so the oracle rate\n * still fully determines pricing while satisfying the on-chain invariant.\n */\nexport const ORACLE_MIN_CONVERSION_RATE_SENTINEL = 1n;\n\n/**\n * The full intent-status set a cash-out order can pass through. The indexer's\n * `getIntentsForDeposits` defaults to `['SIGNALED']` only - passing this\n * explicit set is REQUIRED, otherwise `delivered`/`returned` states are\n * silently filtered out.\n */\nexport const CASH_ORDER_STATUSES: IntentStatus[] = [\n  'SIGNALED',\n  'FULFILLED',\n  'PRUNED',\n  'MANUALLY_RELEASED',\n];\n\n/** Default polling cadence for an in-flight order (ms). Matches the protocol's active-intent polling. */\nexport const CASH_ORDER_POLL_INTERVAL_MS = 5_000;\n\n/**\n * Default deposit config for every Peer Cash deposit: a one-shot cash-out\n * cleans up when fully filled rather than lingering empty.\n */\nexport const CASH_RETAIN_ON_EMPTY = false;\n","/**\n * Typed errors - every failure carries a `code`, whether it is `retryable`,\n * and a `remediation` sentence so agents can self-drive recovery.\n */\nexport type CashErrorCode =\n  | 'ORACLE_UNSUPPORTED_CURRENCY'\n  | 'UNSUPPORTED_PLATFORM'\n  | 'AMOUNT_BELOW_MINIMUM'\n  | 'ACTIVE_INTENT_BLOCKS_WITHDRAWAL'\n  | 'NOTHING_TO_WITHDRAW'\n  | 'INSUFFICIENT_AVAILABLE_FUNDS'\n  | 'ORDER_NOT_ACTIVE'\n  | 'ESCROW_PAUSED'\n  | 'INDEXER_LAG'\n  | 'ORDER_NOT_FOUND'\n  | 'PAYEE_REGISTRATION_FAILED'\n  | 'PAYEE_VERIFICATION_REQUIRED'\n  | 'DEPOSIT_RESOLUTION_FAILED'\n  | 'ALLOWANCE_NOT_VISIBLE'\n  | 'SIGNER_REQUIRED'\n  | 'WATCH_TIMEOUT'\n  | 'TRANSACTION_FAILED';\n\nexport interface CashErrorShape {\n  code: CashErrorCode;\n  message: string;\n  retryable: boolean;\n  remediation: string;\n}\n\nexport class CashError extends Error implements CashErrorShape {\n  readonly code: CashErrorCode;\n  readonly retryable: boolean;\n  readonly remediation: string;\n\n  constructor(shape: CashErrorShape, options?: { cause?: unknown }) {\n    super(shape.message, options);\n    this.name = 'CashError';\n    this.code = shape.code;\n    this.retryable = shape.retryable;\n    this.remediation = shape.remediation;\n  }\n\n  /** Serializable view (for tool results and logs). */\n  toJSON(): CashErrorShape {\n    return {\n      code: this.code,\n      message: this.message,\n      retryable: this.retryable,\n      remediation: this.remediation,\n    };\n  }\n}\n\nexport function isCashError(value: unknown): value is CashError {\n  return value instanceof CashError;\n}\n\n/** Factory helpers keep call sites one-liners and remediation copy consistent. */\nexport const errors = {\n  oracleUnsupportedCurrency: (currency: string) =>\n    new CashError({\n      code: 'ORACLE_UNSUPPORTED_CURRENCY',\n      message: `${currency} has no live Chainlink oracle feed; Peer Cash is market-rate only.`,\n      retryable: false,\n      remediation: `Pick a currency listed in capabilities() - each one is priced by a live oracle feed.`,\n    }),\n  unsupportedPlatform: (platform: string) =>\n    new CashError({\n      code: 'UNSUPPORTED_PLATFORM',\n      message: `'${platform}' is not a supported payout platform in this environment.`,\n      retryable: false,\n      remediation: `Pick a platform listed in capabilities().`,\n    }),\n  amountBelowMinimum: (amount: bigint, min: bigint) =>\n    new CashError({\n      code: 'AMOUNT_BELOW_MINIMUM',\n      message: `Amount ${amount} is below the minimum cash-out of ${min} USDC base units.`,\n      retryable: false,\n      remediation: `Increase the amount to at least ${min} base units (${Number(min) / 1e6} USDC).`,\n    }),\n  activeIntentBlocksWithdrawal: (depositId: string) =>\n    new CashError({\n      code: 'ACTIVE_INTENT_BLOCKS_WITHDRAWAL',\n      message: `Order ${depositId} has a live buyer intent; escrow blocks withdrawal while a buyer may still deliver.`,\n      retryable: true,\n      remediation: `Wait for the buyer to complete or for their intent to expire, then call withdraw() again - it prunes expired intents automatically.`,\n    }),\n  insufficientAvailableFunds: (depositId: string, requested: bigint, available: bigint) =>\n    new CashError({\n      code: 'INSUFFICIENT_AVAILABLE_FUNDS',\n      message: `Order ${depositId} has ${available} base units available; ${requested} requested.`,\n      retryable: true,\n      remediation: `Withdraw at most the available (unlocked) amount, or omit the amount to close the order fully once no buyer intent is live.`,\n    }),\n  orderNotActive: (depositId: string) =>\n    new CashError({\n      code: 'ORDER_NOT_ACTIVE',\n      message: `Order ${depositId} is closed (delivered or returned); it cannot be topped up.`,\n      retryable: false,\n      remediation: `Start a new cash-out with cashout() instead.`,\n    }),\n  nothingToWithdraw: (depositId: string) =>\n    new CashError({\n      code: 'NOTHING_TO_WITHDRAW',\n      message: `Order ${depositId} holds no withdrawable funds (already delivered or returned).`,\n      retryable: false,\n      remediation: `Check order(depositId).state - this order is terminal.`,\n    }),\n  indexerLag: (depositId: string) =>\n    new CashError({\n      code: 'INDEXER_LAG',\n      message: `Order ${depositId} is not indexed yet (the deposit may be seconds old).`,\n      retryable: true,\n      remediation: `Retry in a few seconds; on-chain state is ahead of the indexer right after a transaction.`,\n    }),\n  orderNotFound: (depositId: string) =>\n    new CashError({\n      code: 'ORDER_NOT_FOUND',\n      message: `No deposit found for id ${depositId}.`,\n      retryable: true,\n      remediation: `Verify the composite depositId (escrow_onchainId). If the deposit was created seconds ago this is indexer lag - retry shortly.`,\n    }),\n  payeeRegistrationFailed: (cause: unknown) =>\n    new CashError(\n      {\n        code: 'PAYEE_REGISTRATION_FAILED',\n        message: `Registering payee details with the curator failed.`,\n        retryable: true,\n        remediation: `Check the payee handle format for the platform (see capabilities() hints) and retry.`,\n      },\n      { cause },\n    ),\n  payeeVerificationRequired: (platform: string, cause?: unknown) =>\n    new CashError(\n      {\n        code: 'PAYEE_VERIFICATION_REQUIRED',\n        message: `${platform} requires a verified maker identity attestation to register a payee; a bare handle is not accepted.`,\n        retryable: false,\n        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.`,\n      },\n      { cause },\n    ),\n  allowanceNotVisible: (amount: bigint) =>\n    new CashError({\n      code: 'ALLOWANCE_NOT_VISIBLE',\n      message: `USDC approval for ${amount} base units did not become visible on the read path in time.`,\n      retryable: true,\n      remediation: `The approve transaction mined but a load-balanced RPC is serving stale state. Retry the same call in a few seconds.`,\n    }),\n  depositResolutionFailed: (txHash: string) =>\n    new CashError({\n      code: 'DEPOSIT_RESOLUTION_FAILED',\n      message: `Deposit transaction ${txHash} succeeded but no DepositReceived event was found in the receipt.`,\n      retryable: false,\n      remediation: `Inspect the transaction on Basescan; recover the depositId from the DepositReceived log manually, then resume with order(depositId).`,\n    }),\n  signerRequired: (verb: string) =>\n    new CashError({\n      code: 'SIGNER_REQUIRED',\n      message: `${verb}() mutates on-chain state and needs a signer.`,\n      retryable: false,\n      remediation: `Pass { signer } (a viem WalletClient with an account), or use prepare() and submit the returned txs with your own signing infrastructure.`,\n    }),\n  watchTimeout: (depositId: string, timeoutMs: number) =>\n    new CashError({\n      code: 'WATCH_TIMEOUT',\n      message: `watch(${depositId}) exceeded ${timeoutMs}ms without reaching a terminal state.`,\n      retryable: true,\n      remediation: `The order is still live - resume any time with watch(depositId) or order(depositId).`,\n    }),\n  transactionFailed: (txHash: string, cause?: unknown) =>\n    new CashError(\n      {\n        code: 'TRANSACTION_FAILED',\n        message: `Transaction ${txHash} reverted.`,\n        retryable: false,\n        remediation: `Inspect the transaction on Basescan; the deposit state is unchanged if the revert happened before escrow accepted funds.`,\n      },\n      { cause },\n    ),\n  escrowPaused: () =>\n    new CashError({\n      code: 'ESCROW_PAUSED',\n      message: `The escrow contract is paused; deposits are temporarily disabled.`,\n      retryable: true,\n      remediation: `Wait for the protocol to unpause and retry. Existing funds remain withdrawable.`,\n    }),\n  /** Generic fallback for an on-chain call that failed for an unrecognized reason. */\n  chainCallFailed: (verb: string, cause?: unknown) =>\n    new CashError(\n      {\n        code: 'TRANSACTION_FAILED',\n        message: `The on-chain ${verb} call failed.`,\n        retryable: false,\n        remediation: `Inspect the error cause and the wallet on Basescan. Deposit state is unchanged if the call reverted before escrow accepted funds.`,\n      },\n      { cause },\n    ),\n};\n\n/**\n * Map a raw SDK/RPC/viem error from a mutating on-chain call to a typed\n * `CashError`, so the package's error contract holds even when the underlying\n * call reverts. Recognized reverts get specific codes; everything else falls\n * back to a wrapped `TRANSACTION_FAILED` (never a raw error to the consumer).\n */\nexport function mapChainError(verb: string, err: unknown): CashError {\n  if (isCashError(err)) return err;\n  const message = err instanceof Error ? err.message : String(err);\n  if (/\\bpaused\\b/i.test(message)) return errors.escrowPaused();\n  if (/exceeds allowance|insufficient allowance|transfer amount exceeds/i.test(message)) {\n    return errors.allowanceNotVisible(0n);\n  }\n  return errors.chainCallFailed(verb, err);\n}\n"]}