@zkp2p/cash 0.1.2 → 0.1.4

package/llms.txt

@@ -15,18 +15,32 @@ Key facts:
   a buyer pays fiat and proves it with TEE-TLS; the protocol releases the USDC.
 - Destination is always Base USDC. Source chains/tokens come from Relay SDK
   metadata and quote execution, filtered to EVM chains this SDK can sign.
+- High-level source cashout uses EXACT_INPUT: amount is source-token base units.
+  source.amount is Relay's guaranteed minimum Base USDC output and the exact
+  order deposit amount, not the route's actual output.
 - There is NO locked fiat quote. estimate() reads the oracle; the binding rate
-  resolves at fill time. ETA is `{ seconds, label }` from recent indexer data,
-  not a guarantee.
+  resolves at fill time. ETA is `{ seconds, label }` from rolling 30-day,
+  zero-spread market-rate deposits in the same payout corridor, not a
+  guarantee.
 - Resume any order from its depositId alone (composite escrow_onchainId).
 - One unwind verb: withdraw(depositId) - prunes expired intents automatically;
   pass amount for a partial withdrawal of the unlocked balance.
 - topUp(depositId, amount) adds USDC to a live order (same payee, same rate).
 - Base-USDC mutating verbs have unsigned counterparts (prepare,
   prepareWithdraw, prepareTopUp) for host-side signing; source-routed cashout
-  needs Relay execution first. @zkp2p/cash/tools ships a JSON-schema tool
-  manifest.
-- Errors are typed: { code, retryable, remediation }.
+  needs signer-backed Relay execution first. prepare() and the cash_cashout tool
+  are Base-USDC-only; cash_source_quote/status do not execute the route.
+  @zkp2p/cash/tools ships a JSON-schema tool manifest.
+- Errors are typed: { code, retryable, remediation, recovery? }. Completed
+  Relay routes retain requestId, flat hashes, and origin/destination
+  transactions. Retry Base-only after SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED;
+  inspect Base activity/orders after SOURCE_CASHOUT_SUBMISSION_UNKNOWN; inspect
+  depositTxHash before any action after SOURCE_CASHOUT_STATUS_UNKNOWN. Treat
+  TRANSACTION_SUBMISSION_UNKNOWN as potentially broadcast. Retry
+  INDEXER_UNAVAILABLE and ORACLE_READ_FAILED reads without repeating a
+  transaction; fix SIGNER_CHAIN_MISMATCH or SIGNER_CHAIN_UNAVAILABLE before
+  quoting or submitting. TRANSACTION_STATUS_UNKNOWN carries the submitted
+  hash in recovery.transactionHash.
 - Everything is decoded to human units: platform ids and currency codes from
   their on-chain hashes, plain-number rates from 1e18 precision.
 - Fills are receipts: locked rate + fiat owed at signal; verified fiat paid,
@@ -38,6 +52,10 @@ Key facts:
 - Default path is same-chain Base USDC. Optional `source` on `cashout()` runs
   Relay source-to-Base-USDC first; non-Base source chains require
   `sourceSigner`.
+- Wise and PayPal require attestation for a new payee registration; a
+  previously registered bare handle can be reused.
+- Preproduction uses https://api-preprod.zkp2p.xyz by default; staging uses
+  https://api-staging.zkp2p.xyz. curatorUrl can override either.
 
 ## Links
 

package/package.json

@@ -1,20 +1,18 @@
 {
   "name": "@zkp2p/cash",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Peer Cash - offramp-only SDK for routing crypto to Base USDC, then cashing out to fiat at the live oracle market rate.",
   "license": "MIT",
   "author": "Peer (https://peer.xyz)",
   "type": "module",
   "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
   "publishConfig": {
     "access": "public"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/zkp2p/peer-cash.git"
-  },
-  "homepage": "https://github.com/zkp2p/peer-cash#readme",
-  "bugs": "https://github.com/zkp2p/peer-cash/issues",
+  "homepage": "https://peer.xyz/cash",
   "keywords": [
     "zkp2p",
     "peer",
@@ -32,25 +30,52 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "react": [
+        "./dist/react.d.ts"
+      ],
+      "tools": [
+        "./dist/tools.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     },
     "./react": {
-      "types": "./dist/react.d.ts",
-      "import": "./dist/react.js",
-      "require": "./dist/react.cjs"
+      "import": {
+        "types": "./dist/react.d.ts",
+        "default": "./dist/react.js"
+      },
+      "require": {
+        "types": "./dist/react.d.cts",
+        "default": "./dist/react.cjs"
+      }
     },
     "./tools": {
-      "types": "./dist/tools.d.ts",
-      "import": "./dist/tools.js",
-      "require": "./dist/tools.cjs"
+      "import": {
+        "types": "./dist/tools.d.ts",
+        "default": "./dist/tools.js"
+      },
+      "require": {
+        "types": "./dist/tools.d.cts",
+        "default": "./dist/tools.cjs"
+      }
     }
   },
   "files": [
     "dist",
+    "docs",
+    "examples",
     "skills",
     "AGENTS.md",
     "README.md",
@@ -65,16 +90,19 @@
     "format:check": "prettier --check .",
     "test": "vitest run",
     "test:watch": "vitest",
-    "ci": "bun run typecheck && bun run lint && bun run format:check && bun run test && bun run build"
+    "audit": "bun audit --production",
+    "pack:check": "bun scripts/check-packed-package.ts",
+    "prepack": "bun run build",
+    "ci": "bun run typecheck && bun run lint && bun run format:check && bun run test && bun run audit && bun run build && bun run pack:check"
   },
   "dependencies": {
     "@relayprotocol/relay-sdk": "^6.1.3",
-    "@zkp2p/sdk": "^0.8.0",
+    "@zkp2p/sdk": "^0.8.1",
     "zod": "^3.24.1"
   },
   "peerDependencies": {
     "react": ">=18",
-    "viem": ">=2.26.0"
+    "viem": ">=2.37.3 <3"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -85,14 +113,16 @@
     "@eslint/js": "^9.17.0",
     "@types/node": "^22.10.2",
     "@types/react": "^19.0.2",
+    "@types/react-test-renderer": "19.1.0",
     "eslint": "^9.17.0",
     "eslint-config-prettier": "^9.1.0",
     "prettier": "^3.4.2",
     "react": "^19.0.0",
+    "react-test-renderer": "19.2.7",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
     "typescript-eslint": "^8.18.1",
-    "viem": "^2.26.0",
-    "vitest": "^2.1.8"
+    "viem": "^2.55.0",
+    "vitest": "^4.1.10"
   }
 }

package/skills/peer-cash-integration/SKILL.md

@@ -20,7 +20,9 @@ custodial off-ramp provider.
   Base USDC remains the default/minimal path. Other source chains/tokens come
   from `@relayprotocol/relay-sdk` metadata and quote execution, filtered to
   EVM chains this viem SDK can sign. Non-Base source chains require
-  `sourceSigner`.
+  `sourceSigner`. Use `EXACT_INPUT` for high-level cash-out flows: `amount` is
+  source-token base units, while `source.amount` is Relay's guaranteed minimum
+  Base USDC output and the exact order deposit amount, not actual route output.
 - **Oracle-at-fill pricing. There is no quote.** The deposit carries
   `oracleRateConfig { spreadBps: 0 }`; the binding rate is whatever the
   Chainlink feed says when a buyer fills. `estimate()` is deliberately named
@@ -28,16 +30,17 @@ custodial off-ramp provider.
 - **Custody story.** Funds are held by the protocol contract only. An unmatched
   deposit is withdrawable by the maker at any time. The SDK never holds keys.
 - **Honest ETA.** Use `estimate().eta`: `{ seconds, label }` backed by rolling
-  7-day indexer data from deposit creation to first fill. Do not use
-  signal-to-fulfillment latency and never render it as a guarantee.
+  30-day indexer data from zero-spread (`spreadBps: 0`) market-rate deposits in
+  the same payout corridor, measured from deposit creation to first fill. Do
+  not use signal-to-fulfillment latency and never render it as a guarantee.
 
 ## 2. Decision tree - entry point by runtime
 
-| Runtime                   | Entry                                                             | Signer pattern                                                                      |
-| ------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| React app                 | `@zkp2p/cash/react` hooks + one `createCashClient` in a provider  | wagmi/viem `WalletClient` from the connected wallet                                 |
-| Node service              | `createCashClient` + `cashout()`/`withdraw()`                     | `createWalletClient({ account: privateKeyToAccount(...), chain: base, transport })` |
-| Agent host / policy layer | `prepare()` / `prepareWithdraw()` -> unsigned `txs[]` + `steps[]` | Host signs; see `@zkp2p/cash/tools` for the JSON-schema tool manifest               |
+| Runtime                   | Entry                                                            | Signer pattern                                                                      |
+| ------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| React app                 | `@zkp2p/cash/react` hooks + one `createCashClient` in a provider | wagmi/viem `WalletClient` from the connected wallet                                 |
+| Node service              | `createCashClient` + `cashout()`/`withdraw()`                    | `createWalletClient({ account: privateKeyToAccount(...), chain: base, transport })` |
+| Agent host / policy layer | Base-USDC `prepare*()` -> unsigned `txs[]` + `steps[]`           | Host signs; source quote/status tools do not execute Relay                          |
 
 ## 3. Recipes - the verbs
 
@@ -47,7 +50,8 @@ not copy types from here; import them.
 ```ts
 import { createCashClient, usdc } from '@zkp2p/cash';
 
-// env: 'production' | 'preproduction' | 'staging'
+// env: 'production' | 'preproduction' | 'staging'. Preproduction and staging
+// select api-preprod.zkp2p.xyz and api-staging.zkp2p.xyz curators by default.
 const cash = createCashClient({ environment: 'staging' });
 
 const caps = cash.capabilities(); // 0 discover (sync)
@@ -72,12 +76,44 @@ await cash.withdraw(res.depositId, { signer }); // 6 unwind (amount: for partial
 await cash.topUp(res.depositId, usdc(50), { signer }); // 7 top up a live order
 ```
 
+Signer-backed exact-input source path:
+
+```ts
+const routed = await cash.cashout(
+  {
+    amount: sourceAmount,
+    source: {
+      chainId: sourceChainId,
+      currency: sourceToken,
+      tradeType: 'EXACT_INPUT',
+    },
+    receive,
+  },
+  { signer, sourceSigner },
+);
+
+persist({
+  depositId: routed.depositId,
+  guaranteedBaseUsdc: routed.source?.amount,
+  requestId: routed.source?.requestId,
+  transactions: routed.source?.transactions,
+});
+```
+
 Base-USDC cashout, withdraw, and top-up also have unsigned `prepare*`
-counterparts. Source-routed cashout runs Relay first; use signed
-`cashout({ source }, { signer, sourceSigner })` for non-Base sources, or bridge first and then use `prepare()`.
+counterparts. `prepare()` rejects `source`. Source-routed cashout runs Relay
+first; use signed `cashout({ source }, { signer, sourceSigner })`, or execute
+and confirm Relay in the host before preparing a Base-USDC cashout.
+`cash_source_quote` and `cash_source_status` are quote/read tools, not a
+host-side execution path.
 Every protocol transaction carries ERC-8021 attribution (`peer-cash` + your
 `createCashClient({ referrer })` codes).
 
+Wise and PayPal require an identity attestation for a new payee registration.
+Do not disable them outright: a previously registered handle can be reused
+with bare payee data. Handle `PAYEE_VERIFICATION_REQUIRED` when registration
+is still needed.
+
 ## 4. Order management - indexer-native
 
 - A cash order IS a deposit; the chain is the database. No storage layer.
@@ -93,12 +129,33 @@ Every protocol transaction carries ERC-8021 attribution (`peer-cash` + your
 
 Every error is a `CashError` with `code`, `retryable`, `remediation`. The
 full table lives in `AGENTS.md` and `docs/lifecycle-and-recovery.md` - quote
-those, don't re-derive. The three that matter most in practice:
+those, don't re-derive. The recovery boundaries that matter most in practice:
 
 - `ORDER_NOT_FOUND` seconds after `cashout()` = indexer lag. The receipt is
   the truth; retry. `watch()` and the React hooks absorb it.
 - `ACTIVE_INTENT_BLOCKS_WITHDRAWAL` = a buyer may still deliver. Retry
   `withdraw()` after their intent expires; it prunes automatically.
+- `SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED` = Relay completed but the Base
+  cashout did not. Never repeat Relay; retry Base-only with
+  `BigInt(error.recovery.amount)`.
+- `SOURCE_CASHOUT_SUBMISSION_UNKNOWN` = Relay completed but Base submission
+  returned no hash. Inspect Base wallet activity and
+  `orders(error.recovery.depositor)` before any retry.
+- `SOURCE_CASHOUT_STATUS_UNKNOWN` = Relay completed and a Base transaction was
+  submitted, but its receipt is unknown. Inspect
+  `error.recovery.depositTxHash`; do not route or submit again until it is
+  known.
+- `TRANSACTION_STATUS_UNKNOWN` = a Base transaction may already have
+  succeeded. Inspect `error.recovery.transactionHash` before resubmitting.
+- `TRANSACTION_SUBMISSION_UNKNOWN` = a Base mutation returned no hash but may
+  have broadcast. Follow `error.recovery`, inspect Base wallet/protocol state,
+  and do not retry until absence is proven.
+- `INDEXER_UNAVAILABLE` / `ORACLE_READ_FAILED` = retry the read only. Do not
+  repeat the transaction that produced the id or balance being inspected.
+- `SIGNER_CHAIN_MISMATCH` = switch to the required chain and obtain a fresh
+  Relay quote before retrying.
+- `SIGNER_CHAIN_UNAVAILABLE` = reconnect the wallet and verify its live chain
+  before any quote or mutation.
 - Buyer never pays → nothing to do: the intent expires, `nextActions` gains
   `'withdraw'`, one `withdraw()` call returns the funds (prune + withdraw).
 
@@ -107,13 +164,19 @@ those, don't re-derive. The three that matter most in practice:
 Run against `environment: 'staging'` with a small funded wallet.
 **Maker-side only - never wait on a buyer.**
 
-1. Create a real 1–2 USDC deposit via `cashout()`; capture `depositId`.
-2. Assert `order(depositId).state === 'awaiting-buyer'` (retry through
-   indexer lag for up to ~60s).
-3. Assert `orders(owner)` contains the deposit.
-4. `withdraw(depositId, { signer })` succeeds.
-5. Assert `order(depositId).state === 'returned'` and the wallet balance is
-   restored minus gas.
+Prove both routes without waiting for a buyer:
+
+1. Create a real 1–2 USDC Base-USDC deposit; retain `depositId` and Base tx.
+2. Retry through indexer lag until `order(depositId)` is `awaiting-buyer`, and
+   assert `orders(owner)` contains it.
+3. Withdraw it; assert `returned` and the Base USDC balance is restored minus
+   gas.
+4. Select a live supported source from capabilities and create a real
+   exact-input route whose guaranteed Base USDC output is at least 1 USDC.
+   Retain Relay `requestId`, origin/destination transaction hashes, Base tx,
+   and `depositId`.
+5. Assert the routed order becomes `awaiting-buyer` and appears in
+   `orders(owner)`, then withdraw and confirm `returned` plus restored balance.
 
 If withdrawal fails with funds stuck: stop, do not retry blindly, escalate to
 a human with the `depositId` and tx hashes.

package/dist/chunk-FKVPZVFH.js

@@ -1,188 +0,0 @@
-// 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 }
-  ),
-  sourceRouteUnsupportedInPrepare: () => new CashError({
-    code: "SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE",
-    message: `prepare() cannot execute a Relay source route before creating the Base USDC cash-out.`,
-    retryable: false,
-    remediation: `Use cashout(inputWithSource, { signer }) for the one-call bridge-then-cashout flow, or call quoteSource()/executeSourceQuote() first and then prepare() a Base USDC cash-out.`
-  }),
-  sourceRecipientMismatch: (recipient, owner) => new CashError({
-    code: "SOURCE_RECIPIENT_MISMATCH",
-    message: `Source recipient ${recipient} does not match the cash-out depositor ${owner}.`,
-    retryable: false,
-    remediation: `For one-call source cashout, deliver Relay output to the depositor address. For a different recipient, bridge first and then cash out from that recipient's signer.`
-  }),
-  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-FKVPZVFH.js.map
-//# sourceMappingURL=chunk-FKVPZVFH.js.map

package/dist/chunk-FKVPZVFH.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/engine/constants.ts","../src/client/errors.ts"],"names":[],"mappings":"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","file":"chunk-FKVPZVFH.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  | 'SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE'\n  | 'SOURCE_RECIPIENT_MISMATCH'\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  sourceRouteUnsupportedInPrepare: () =>\n    new CashError({\n      code: 'SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE',\n      message: `prepare() cannot execute a Relay source route before creating the Base USDC cash-out.`,\n      retryable: false,\n      remediation: `Use cashout(inputWithSource, { signer }) for the one-call bridge-then-cashout flow, or call quoteSource()/executeSourceQuote() first and then prepare() a Base USDC cash-out.`,\n    }),\n  sourceRecipientMismatch: (recipient: string, owner: string) =>\n    new CashError({\n      code: 'SOURCE_RECIPIENT_MISMATCH',\n      message: `Source recipient ${recipient} does not match the cash-out depositor ${owner}.`,\n      retryable: false,\n      remediation: `For one-call source cashout, deliver Relay output to the depositor address. For a different recipient, bridge first and then cash out from that recipient's signer.`,\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"]}