@zkp2p/cash 0.1.3 → 0.1.4

package/dist/tools.js

@@ -1,14 +1,28 @@
+// package.json
+var package_default = {
+  version: "0.1.4"};
+
 // src/tools/index.ts
 var bigintString = {
   type: "string",
-  pattern: "^[0-9]+$",
+  pattern: "^0*[1-9][0-9]*$",
   description: "Base units as a decimal string. For the default path this is USDC 6 decimals; with source it is source-token base units."
 };
 var depositId = {
   type: "string",
+  pattern: "^0x[0-9a-fA-F]{40}_[0-9]+$",
   description: "Composite deposit id (escrow_onchainId) returned by cash_cashout - the resume key"
 };
-var cashTools = [
+var address = {
+  type: "string",
+  pattern: "^0x[0-9a-fA-F]{40}$"
+};
+var chainId = {
+  type: "integer",
+  minimum: 1,
+  maximum: Number.MAX_SAFE_INTEGER
+};
+var builtInCashTools = [
   {
     name: "cash_capabilities",
     description: "Discover what Peer Cash can do: payout platforms, oracle-priced currencies per platform, Base USDC destination, default Base USDC source, payee handle hints, and amount bounds. Set includeRelaySources=true to fetch live Relay-supported EVM source chains/tokens through the Relay SDK.",
@@ -25,23 +39,23 @@ var cashTools = [
   },
   {
     name: "cash_source_quote",
-    description: "Quote any Relay-supported EVM source asset into Base USDC through @relayprotocol/relay-sdk. Use this before cash_cashout when the user starts with an asset other than Base USDC.",
+    description: "Quote any Relay-supported EVM source asset into Base USDC through @relayprotocol/relay-sdk. A custody-capable host must submit the returned route, poll cash_source_status to success, then call Base-USDC cash_cashout with the guaranteed output amount. Never submit the route twice.",
     inputSchema: {
       type: "object",
       properties: {
-        user: { type: "string", description: "Source wallet submitting the Relay transaction." },
+        user: { ...address, description: "Source wallet submitting the Relay transaction." },
         amount: bigintString,
         source: {
           type: "object",
           properties: {
-            chainId: { type: "number", description: "Relay-supported EVM source chain id." },
-            currency: { type: "string", description: "Source token/native address." }
+            chainId: { ...chainId, description: "Relay-supported EVM source chain id." },
+            currency: { ...address, description: "Source token/native address." }
           },
           required: ["chainId", "currency"],
           additionalProperties: false
         },
         recipient: {
-          type: "string",
+          ...address,
           description: "Base recipient for Relay-delivered USDC. Defaults to user."
         },
         tradeType: {
@@ -73,14 +87,14 @@ var cashTools = [
           type: "object",
           description: "Optional Relay EVM source asset. Omit for the Base USDC default path.",
           properties: {
-            chainId: { type: "number", description: "Relay-supported EVM source chain id." },
-            currency: { type: "string", description: "Source token/native address." },
+            chainId: { ...chainId, description: "Relay-supported EVM source chain id." },
+            currency: { ...address, description: "Source token/native address." },
             user: {
-              type: "string",
+              ...address,
               description: "Source wallet submitting the Relay transaction."
             },
             recipient: {
-              type: "string",
+              ...address,
               description: "Base recipient for Relay-delivered USDC. Defaults to user."
             },
             tradeType: {
@@ -98,29 +112,11 @@ var cashTools = [
   },
   {
     name: "cash_cashout",
-    description: "Start a cash-out. Default path: Base USDC amount and tool hosts can return UNSIGNED transactions plus same-index steps [approve, createDeposit]. With source: signer-backed clients first execute a Relay SDK EVM route into Base USDC, then register the payee and create the protocol-held cash-out order. Non-Base source chains need a source-chain signer. Custody-separated hosts should use cash_source_quote/cash_source_status first, then Base USDC cash_cashout.",
+    description: "Start a Base-USDC cash-out using the custody-separated prepare path. Returns UNSIGNED transactions plus same-index steps [approve, createDeposit]; signing and ordered submission stay host-side. For another source asset, complete cash_source_quote and cash_source_status first, then pass the guaranteed Base USDC output amount here.",
     inputSchema: {
       type: "object",
       properties: {
         amount: bigintString,
-        source: {
-          type: "object",
-          description: "Optional Relay EVM source asset. Omit for the Base USDC default path.",
-          properties: {
-            chainId: { type: "number", description: "Relay-supported EVM source chain id." },
-            currency: { type: "string", description: "Source token/native address." },
-            recipient: {
-              type: "string",
-              description: "Base recipient for Relay-delivered USDC. Defaults to signer."
-            },
-            tradeType: {
-              type: "string",
-              enum: ["EXACT_INPUT", "EXACT_OUTPUT", "EXPECTED_OUTPUT"]
-            }
-          },
-          required: ["chainId", "currency"],
-          additionalProperties: false
-        },
         receive: {
           type: "object",
           description: "Where the fiat should arrive",
@@ -167,12 +163,17 @@ var cashTools = [
     inputSchema: {
       type: "object",
       properties: {
-        owner: { type: "string", description: "The maker wallet address (0x...)" },
+        owner: { ...address, description: "The maker wallet address (0x...)" },
         inFlight: {
           type: "boolean",
           description: "Only awaiting-buyer / matched / delivering orders"
         },
-        limit: { type: "number", description: "Max deposits to scan (default 100)" }
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 1e3,
+          description: "Max deposits to scan (default 100)"
+        }
       },
       required: ["owner"],
       additionalProperties: false
@@ -184,7 +185,7 @@ var cashTools = [
     inputSchema: {
       type: "object",
       properties: {
-        address: { type: "string", description: "The buyer (taker) wallet address (0x...)" }
+        address: { ...address, description: "The buyer (taker) wallet address (0x...)" }
       },
       required: ["address"],
       additionalProperties: false
@@ -229,13 +230,12 @@ var cashTools = [
     }
   }
 ];
+var cashTools = [...builtInCashTools];
 var cashToolManifest = {
   name: "@zkp2p/cash",
-  version: "0.1.2",
+  version: package_default.version,
   description: "Peer Cash - offramp-only: route any Relay-supported EVM source asset to Base USDC, then cash out to fiat at the live oracle market rate (0% spread). Mutating protocol tools return unsigned transactions plus step labels with ERC-8021 peer-cash attribution.",
   tools: cashTools
 };
 
 export { cashToolManifest, cashTools };
-//# sourceMappingURL=tools.js.map
-//# sourceMappingURL=tools.js.map

package/docs/lifecycle-and-recovery.md

@@ -0,0 +1,278 @@
+# Lifecycle and recovery
+
+The one deep guide: what states exist, how source routing works, how partial
+fills and ETA work, how unwinding works, and why every order survives a crash.
+
+## The model: you are the maker
+
+A Peer Cash order is a **deposit** in the ZKP2P protocol. When you
+`cashout()`, Base USDC becomes protocol-held funds priced at the live Chainlink
+oracle rate with zero spread. A buyer (a standard protocol taker) _signals an
+intent_ against your deposit, pays you fiat offchain (Venmo, Revolut, Wise,
+...), and proves the payment via TEE-TLS. The protocol then releases your USDC
+to them.
+The protocol runs in its normal direction - nothing here is inverted or
+special-cased.
+
+Because your deposit is priced at market with no spread, it is the best price
+a rational maker can offer. That is the fill incentive.
+
+## Source routing
+
+The cashout destination is always canonical Base USDC. The minimal/default path
+is still same-chain Base USDC: pass USDC base units to `estimate()` and
+`cashout()`.
+
+For any other EVM source asset, Peer Cash uses `@relayprotocol/relay-sdk`:
+
+1. `capabilities({ includeRelaySources: true })` or `sourceCapabilities()`
+   fetches live Relay-supported EVM chains and tokens, excluding disabled,
+   deposit-disabled, and block-lagging chains.
+2. `quoteSource()` calls Relay SDK `actions.getQuote` for source to Base USDC.
+3. `cashout({ amount, source, receive }, { signer, sourceSigner })` settles
+   Base allowance, calls Relay SDK `actions.execute`, then creates the Peer Cash
+   order with Relay's guaranteed minimum Base USDC output. Non-Base source
+   chains require `sourceSigner`.
+   `executeSourceQuote()` remains available for apps that want a separate
+   bridge step.
+
+Cash-out interfaces should use `tradeType: 'EXACT_INPUT'` (also the default),
+so `amount` always means source-token base units. A `RelayQuote.outputAmount`
+is the guaranteed minimum Base USDC output. The same value becomes
+`CashoutResult.source.amount` and the exact amount deposited into the Peer Cash
+order; it is not a claim about the route's actual output.
+
+When a source route succeeds, `CashoutResult.source` also retains the Relay
+`requestId`, a flat `txHashes` list, and chain-aware
+`transactions.origin` / `transactions.destination` entries. Persist them with
+the `depositId` so route and deposit recovery do not depend on browser state.
+
+The unsigned `prepare()` path is Base-USDC-only and rejects `source` with
+`SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE`. The tool manifest follows the same
+boundary: `cash_source_quote` and `cash_source_status` quote and observe Relay,
+but the host or a signer-backed client must execute the route before
+`cash_cashout` prepares the Base-USDC order.
+
+There is no static chain/token allowlist in Peer Cash. Relay decides source
+support through its metadata and quote execution, filtered to the viem/EVM
+execution surface this SDK can sign. Peer Cash hardcodes only the Base USDC
+destination constant.
+
+### Source-route failure boundaries
+
+Do not retry a source route merely because the Base cashout did not finish:
+
+- `SOURCE_EXECUTION_FAILED` means Relay execution did not report success. Check
+  its `inspect-relay-route` recovery evidence, submitted wallet transactions,
+  and `relayStatus(requestId)` before taking another action; a blind retry can
+  route twice.
+- `SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED` means Relay completed, but the Base
+  cashout was not created. Its recovery payload has
+  `kind: 'retry-base-usdc-cashout'`, the guaranteed Base USDC `amount`, Relay
+  request and transaction evidence. Do not route again; retry without `source`.
+- `SOURCE_CASHOUT_SUBMISSION_UNKNOWN` means Relay completed, but Base
+  submission returned no transaction hash. Inspect recent Base wallet activity
+  and `orders(recovery.depositor)` to prove no deposit exists before retrying.
+- `SOURCE_CASHOUT_STATUS_UNKNOWN` means Relay completed and the Base cashout
+  transaction was submitted, but its receipt could not be confirmed. Its
+  recovery payload has `kind: 'inspect-base-cashout-transaction'` and
+  `depositTxHash`. Do not submit anything again until that Base transaction is
+  known. If it succeeded, recover `depositId` from `DepositReceived`; if it
+  reverted, retry a Base-USDC-only cashout with the recovery amount.
+
+## States
+
+Every state derives from on-chain events. There are no synthetic states.
+
+| State            | On-chain meaning                                    | `nextActions`                                                 |
+| ---------------- | --------------------------------------------------- | ------------------------------------------------------------- |
+| `awaiting-buyer` | Deposit live, no active intent                      | `['wait', 'withdraw']`                                        |
+| `matched`        | A buyer signaled; funds locked                      | `['wait']` (or `['wait','withdraw']` once the intent expires) |
+| `delivering`     | Partial fill in progress: some delivered, more live | `['wait']` / `['wait','withdraw']`                            |
+| `delivered`      | Fully paid and proven; protocol released funds      | `[]`                                                          |
+| `returned`       | Funds back in your wallet (withdrawn)               | `[]`                                                          |
+
+Intent statuses underneath: `SIGNALED → FULFILLED` (paid + proven),
+`PRUNED` (expired unpaid), `MANUALLY_RELEASED` (support path, counts as
+fulfilled). Always query the full set - the indexer defaults to `SIGNALED`
+only, which silently hides terminal states.
+
+## Partial fills
+
+A 1,000 USDC order does not need one 1,000 USDC buyer. The deposit accepts
+intents between `intentAmountRange.min` (default 1 USDC) and the full amount.
+Three buyers can take 400 + 350 + 250. The order shows each as a `fill` and
+passes through `delivering` until the last one completes. `filledAmount`,
+`pendingAmount`, and `totalAmount` always add up against the chain.
+
+## The ETA principle
+
+`estimate().eta` is historical, not a promise. It uses rolling 30-day indexer
+data from deposit/order creation to the first fulfilled fill. It deliberately
+does **not** measure buyer signal to fulfillment; that would miss the
+buyer-arrival wait that users actually care about. The public shape is small:
+`{ seconds, label }`.
+
+- **Buyer arrival time is market-driven.** A deposit at market rate should
+  fill fast, but the ETA is only a recent historical sample.
+- **The binding rate resolves at fill time.** `estimate()` reads the same
+  Chainlink feed the escrow will read, but between estimate and fill the
+  market moves. `kind: 'oracle-estimate'` is the API telling you this.
+- **The label is display-ready.** Use `eta.label` in simple UIs; use
+  `eta.seconds` only if you need your own formatting.
+
+Anything that looks like a committed quote or guaranteed delivery timer in a
+UI built on this SDK is a bug in that UI.
+
+## Managing a live order
+
+- **Top up** - `topUp(depositId, amount)` adds USDC to a live order: same
+  payee, same market-rate pricing, no new registration. Closed orders reject
+  with `ORDER_NOT_ACTIVE`; start a new `cashout()` instead.
+- **Partial withdrawal** - `withdraw(depositId, { amount })` pulls part of
+  the _unlocked_ balance back out. A live buyer intent does not block it
+  (their locked portion is untouched); asking for more than the unlocked
+  balance fails with `INSUFFICIENT_AVAILABLE_FUNDS`.
+- There is no retain-on-empty or rate knob to manage - a cash order cleans
+  itself up when fully filled, and the market rate is not configurable.
+
+## Receipts, decoded
+
+Everything an order serves is decoded to human units: platform ids and
+currency codes instead of bytes32 hashes, plain-number rates instead of 1e18
+bigints (raw values stay available as `*Hash` / `conversionRate` fields).
+
+Each fill is a receipt that sharpens over its life:
+
+- **At signal**: `rate` (the oracle rate locked for THIS fill - the moment
+  "approximately" becomes exact) and `fiatOwed` (`amount × rate`, rounded up
+  to the cent, matching what the buyer's client tells them to pay).
+- **After the proof**: `fiatPaid` (the verified amount actually sent),
+  `paidCurrency`, `paymentId` (the platform's own payment reference),
+  `paidAt`, `releasedAmount` (USDC actually released), and
+  `fillLatencySeconds` (signal → proven delivery).
+
+`fiatOwed` and `fiatPaid` are decoded to whole currency units. The verified
+`paymentAmount` arrives from the indexer in cents (2 decimals) - the same
+convention the first-party Peer clients display it with - and the SDK
+divides by 100. The signal-time `fiatOwed` derives from `amount × rate` at
+1e18 precision; `resolveIntentFiatAmount` in the reference clients uses the
+same ceil-to-cent math, and the decode is verified against live production
+receipts.
+
+Orders also carry their `payouts` legs reconstructed from the chain -
+platform, currency, payee hash, and a pricing proof (`spreadBps: 0`,
+`kind: 'oracle_chainlink'`, `marketRate: true`): the zero-spread claim is a
+queryable fact, not marketing copy.
+
+## Who is this buyer?
+
+`buyer(address)` aggregates the matched buyer's full intent history into a
+track record: lifetime intents, fulfilled vs pruned counts, a success rate in
+basis points, first/last seen. Use it during `matched` - the moment a
+stranger's address is holding your order is exactly when a 95%-success,
+200-order counterparty reads very differently from a fresh wallet.
+
+## Unwinding: one verb
+
+`withdraw(depositId, { signer })` handles every recovery case:
+
+1. **No buyer yet** (`awaiting-buyer`): withdraws directly. Funds return in
+   one transaction.
+2. **Buyer signaled but never paid**: their intent expires on-chain. The
+   escrow still counts it as active, so `withdraw()` first sends
+   `pruneExpiredIntents`, then withdraws. Two transactions, one call.
+3. **Buyer is actively paying** (live intent): withdrawal would strand the
+   buyer, so the escrow blocks it and the SDK throws
+   `ACTIVE_INTENT_BLOCKS_WITHDRAWAL` (`retryable: true`). Wait for delivery
+   or expiry, then call `withdraw()` again.
+4. **Nothing left** (`delivered`/`returned`): throws `NOTHING_TO_WITHDRAW`.
+
+There is deliberately no `cancel` vs `recover` split - the deposit state
+decides, not the caller. Agents needing host-side signing use
+`prepareWithdraw(depositId)` for the same logic as unsigned `txs[]`.
+Prepare results also carry `steps[]` in the same order as `txs[]`, so a host
+can show `pruneExpiredIntents` before `withdrawDeposit` instead of asking a
+user or policy engine to approve opaque calldata.
+
+## Resumability
+
+The `depositId` (composite `escrow_onchainId`) is the only key you need:
+
+- `cashout()` returns it, parsed from the `DepositReceived` event in the
+  transaction receipt - available immediately, no indexer wait.
+- `order(depositId)` reconstructs the full order from the indexer at any
+  time, on any machine. There is no session, no cache, no local store.
+- Bind orders to your own users with one column in **your** database:
+  `userId → depositId`.
+
+## Indexer lag
+
+Right after `cashout()`, the indexer may not have seen the deposit yet
+(typically a few seconds). `order()` throws `ORDER_NOT_FOUND` with
+`retryable: true`; `watch()` and the React hooks absorb this and keep
+polling. Do not treat an immediate `ORDER_NOT_FOUND` as a lost deposit - the
+transaction receipt you already hold is the source of truth.
+
+## Payee registration, over time
+
+`cashout()` registers your payee with the curator once, keyed by a hash of the
+handle; the registration has no TTL and stays resolvable for the deposit's
+whole life. Two things to know for long-lived orders:
+
+- For the **live-validated platforms** (Venmo, Revolut, Cash App, Monzo), if
+  the underlying account is later deleted, the curator can revoke the payee at
+  a buyer's intent-signing time - a buyer then cannot take the deposit until
+  the payee is re-registered. Format-only platforms (Zelle, Chime, …) are
+  never re-checked.
+- **Wise and PayPal** require a signed identity attestation for a new payee
+  registration. A previously registered handle can be reused with bare payee
+  data. If the handle is new and no attestation is supplied, the SDK surfaces
+  `PAYEE_VERIFICATION_REQUIRED`; `capabilities()` flags these platforms with
+  `requiresIdentityAttestation: true`.
+
+The client selects a curator with its environment. Preproduction defaults to
+`https://api-preprod.zkp2p.xyz`, staging defaults to
+`https://api-staging.zkp2p.xyz`, and `curatorUrl` remains available as an
+explicit override.
+
+## Failure table
+
+| Code                                    | Retryable | What happened / what to do                                                                                                                   |
+| --------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ORACLE_UNSUPPORTED_CURRENCY`           | no        | Currency has no Chainlink feed. Pick from `capabilities()`.                                                                                  |
+| `ORACLE_READ_FAILED`                    | yes       | The live Chainlink read failed. Retry through a healthy Base RPC; do not present a cached value as live.                                     |
+| `UNSUPPORTED_PLATFORM`                  | no        | Platform is absent from this environment's catalog. Pick from `capabilities()`.                                                              |
+| `UNSUPPORTED_PLATFORM_CURRENCY`         | no        | The platform does not support that currency. Use its `capabilities()` currencies.                                                            |
+| `AMOUNT_BELOW_MINIMUM`                  | no        | Amount is below the $0.01 hard floor. The recommended minimum is 1 USDC.                                                                     |
+| `INVALID_INTENT_AMOUNT_RANGE`           | no        | Min/max is non-positive, inverted, or exceeds the deposit. Correct the range.                                                                |
+| `PAYEE_VERIFICATION_REQUIRED`           | no        | A new Wise/PayPal payee needs an attestation. Register it through Peer first; an existing registration can be reused.                        |
+| `PAYEE_REGISTRATION_FAILED`             | yes       | Curator rejected the handle or was unavailable. Check `payeeHint` and retry.                                                                 |
+| `SOURCE_ROUTE_UNSUPPORTED_IN_PREPARE`   | no        | `prepare()` accepts Base USDC only. Use signed source execution, or complete Relay first and then prepare the Base cashout.                  |
+| `SOURCE_RECIPIENT_MISMATCH`             | no        | Relay output recipient differs from the cashout depositor. Use the depositor address.                                                        |
+| `SOURCE_CAPABILITIES_FAILED`            | yes       | Relay source discovery failed. Retry or use Base USDC.                                                                                       |
+| `SOURCE_QUOTE_FAILED`                   | yes       | Relay returned no valid canonical Base-USDC route. Refresh capabilities and quote again.                                                     |
+| `SOURCE_EXECUTION_FAILED`               | no        | Route execution did not report success. Inspect source transactions and Relay status before retrying.                                        |
+| `SOURCE_STATUS_FAILED`                  | yes       | Relay status is temporarily unavailable. Retry the status read without resubmitting.                                                         |
+| `SOURCE_ROUTE_COMPLETED_CASHOUT_FAILED` | no        | Relay completed but no Base cashout was created. Use the recovery amount for a Base-USDC-only retry; never repeat Relay.                     |
+| `SOURCE_CASHOUT_SUBMISSION_UNKNOWN`     | no        | Relay completed but Base submission returned no hash. Inspect wallet activity and orders before any retry.                                   |
+| `SOURCE_CASHOUT_STATUS_UNKNOWN`         | no        | Relay completed and the Base tx was submitted, but its receipt is unknown. Inspect `depositTxHash`; do not resubmit while status is unknown. |
+| `INSUFFICIENT_TOKEN_BALANCE`            | no        | Wallet lacks the required token amount. Fund it, then retry.                                                                                 |
+| `ALLOWANCE_NOT_VISIBLE`                 | yes       | Approval mined but a stale RPC replica hid it. Retry the same call after the allowance becomes visible.                                      |
+| `TRANSACTION_FAILED`                    | no        | The on-chain call failed or reverted. Inspect the cause and transaction before another action.                                               |
+| `TRANSACTION_SUBMISSION_UNKNOWN`        | no        | A Base mutation returned no hash but may have broadcast. Inspect wallet/protocol state and its recovery action before any retry.             |
+| `TRANSACTION_STATUS_UNKNOWN`            | no        | A transaction was submitted but its receipt is unknown. Inspect `recovery.transactionHash` before resubmitting.                              |
+| `DEPOSIT_RESOLUTION_FAILED`             | no        | Base tx succeeded but no `DepositReceived` was decoded. Inspect its logs and recover the composite id.                                       |
+| `INVALID_DEPOSIT_ID`                    | no        | The id is not `escrowAddress_onchainId`. A bare number cannot cold-hydrate; use the value returned by `cashout()`.                           |
+| `ORDER_NOT_FOUND`                       | yes       | Unknown id or immediate indexer lag. Verify the id and retry shortly after creation.                                                         |
+| `INDEXER_LAG`                           | yes       | Indexer trails the chain. Retry the read shortly.                                                                                            |
+| `INDEXER_UNAVAILABLE`                   | yes       | The indexer read failed. Retry only that read with the same id or owner; never repeat an on-chain transaction.                               |
+| `ACTIVE_INTENT_BLOCKS_WITHDRAWAL`       | yes       | A buyer may still deliver. Wait for fill or expiry, or withdraw only the unlocked amount.                                                    |
+| `INSUFFICIENT_AVAILABLE_FUNDS`          | yes       | Partial withdrawal exceeds unlocked funds. Lower the amount.                                                                                 |
+| `NOTHING_TO_WITHDRAW`                   | no        | Order is terminal. Reconcile `order(depositId)`.                                                                                             |
+| `ORDER_NOT_ACTIVE`                      | no        | A closed order cannot be topped up. Start a new cashout.                                                                                     |
+| `SIGNER_REQUIRED`                       | no        | Pass a signer or use a Base-USDC `prepare*` path.                                                                                            |
+| `SIGNER_CHAIN_MISMATCH`                 | no        | Switch the signer to the required chain and refresh any Relay quote before retrying.                                                         |
+| `SIGNER_CHAIN_UNAVAILABLE`              | yes       | The wallet could not report its live chain. Reconnect it and prove the required chain before retrying.                                       |
+| `WATCH_TIMEOUT`                         | yes       | Order remains live. Resume `watch()` or `order()` later.                                                                                     |
+| `ESCROW_PAUSED`                         | yes       | Deposits are paused. Existing funds remain withdrawable.                                                                                     |

package/examples/agent-tool-use.ts

@@ -0,0 +1,122 @@
+/**
+ * Example: wiring the cash verbs into an agent tool-use loop.
+ *
+ * The host owns signing: mutating tools return UNSIGNED transactions the host
+ * submits with its own key management. Everything crossing the tool boundary
+ * is JSON - the codecs make that lossless.
+ *
+ * Run: bun examples/agent-tool-use.ts   (read-only tools run against staging)
+ */
+import { createCashClient, usdc, isCashError } from '@zkp2p/cash';
+import {
+  buyerProfileToJson,
+  capabilitiesToJson,
+  estimateToJson,
+  orderToJson,
+  prepareResultToJson,
+  preparedTxToJson,
+  relayQuoteToJson,
+  relayStatusToJson,
+} from '@zkp2p/cash';
+import { cashToolManifest } from '@zkp2p/cash/tools';
+
+const cash = createCashClient({ environment: 'staging' });
+
+/** The host's tool executor: tool name + JSON args in, JSON result out. */
+async function executeTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+  try {
+    switch (name) {
+      case 'cash_capabilities':
+        return capabilitiesToJson(
+          args.includeRelaySources
+            ? await cash.capabilities({ includeRelaySources: true })
+            : cash.capabilities(),
+        );
+      case 'cash_source_quote':
+        return relayQuoteToJson(
+          await cash.quoteSource({
+            user: args.user as string,
+            amount: BigInt(args.amount as string),
+            source: args.source as never,
+            ...(args.recipient ? { recipient: args.recipient as string } : {}),
+            ...(args.tradeType ? { tradeType: args.tradeType as never } : {}),
+          }),
+        );
+      case 'cash_estimate':
+        return estimateToJson(
+          await cash.estimate({
+            amount: BigInt(args.amount as string),
+            currency: args.currency as never,
+            ...(args.platform ? { platform: args.platform as string } : {}),
+            ...(args.source ? { source: args.source as never } : {}),
+          }),
+        );
+      case 'cash_cashout': {
+        // Tool/prepare path: Base USDC only. cash_source_quote is read-only;
+        // the host must execute and confirm Relay with its own signer/runtime,
+        // then call this tool with the guaranteed Base USDC amount.
+        const input = {
+          amount: BigInt(args.amount as string),
+          receive: args.receive as never,
+        };
+        return prepareResultToJson(await cash.prepare(input));
+      }
+      case 'cash_order':
+        return orderToJson(await cash.order(args.depositId as string));
+      case 'cash_orders': {
+        const orders = await cash.orders(args.owner as string, {
+          ...(args.inFlight !== undefined ? { inFlight: args.inFlight as boolean } : {}),
+          ...(args.limit !== undefined ? { limit: args.limit as number } : {}),
+        });
+        return orders.map(orderToJson);
+      }
+      case 'cash_buyer':
+        return buyerProfileToJson(await cash.buyer(args.address as string));
+      case 'cash_source_status':
+        return relayStatusToJson(await cash.relayStatus(args.requestId as string));
+      case 'cash_withdraw': {
+        const amount = args.amount !== undefined ? BigInt(args.amount as string) : undefined;
+        const { txs, steps } = await cash.prepareWithdraw(args.depositId as string, {
+          ...(amount !== undefined ? { amount } : {}),
+        });
+        return { txs: txs.map(preparedTxToJson), steps };
+      }
+      case 'cash_topup': {
+        const { txs, steps } = await cash.prepareTopUp(
+          args.depositId as string,
+          BigInt(args.amount as string),
+        );
+        return { txs: txs.map(preparedTxToJson), steps };
+      }
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (err) {
+    // Typed errors serialize cleanly into tool results the model can act on.
+    if (isCashError(err)) return { error: err.toJSON() };
+    throw err;
+  }
+}
+
+// --- Demo loop: what an agent host would do with the manifest ---
+
+console.log(`manifest: ${cashToolManifest.name}@${cashToolManifest.version}`);
+console.log(`tools: ${cashToolManifest.tools.map((t) => t.name).join(', ')}\n`);
+
+const caps = (await executeTool('cash_capabilities', {})) as {
+  platforms: { platform: string; currencies: string[]; payeeHint: string }[];
+};
+console.log(`agent sees ${caps.platforms.length} platforms; venmo hint:`);
+console.log(`  "${caps.platforms.find((p) => p.platform === 'venmo')?.payeeHint}"\n`);
+
+const est = await executeTool('cash_estimate', {
+  amount: usdc(250).toString(),
+  currency: 'EUR',
+});
+console.log('cash_estimate →', JSON.stringify(est), '\n');
+
+// A typed error round-trips as data, not an exception:
+const notFound = await executeTool('cash_order', {
+  depositId: '0x1111111111111111111111111111111111111111_999999',
+});
+console.log('cash_order on unknown id →', JSON.stringify(notFound));

package/examples/node-cashout.ts

@@ -0,0 +1,79 @@
+/**
+ * Example: server-side cash-out with a private-key signer, plus order tracking.
+ *
+ * Run: PRIVATE_KEY=0x... bun examples/node-cashout.ts
+ * (Use environment 'staging' and a throwaway dev wallet with a few USDC.)
+ *
+ * By default this demo withdraws its own deposit at the end so the test wallet
+ * is left untouched. A real integration leaves the deposit open for buyers -
+ * set CASH_KEEP_OPEN=1 for that behavior.
+ *
+ * The curator validates supported handles against the live platform, so the
+ * payee must be a real account. A new Wise/PayPal registration also needs the
+ * identity attestation created by Peer; an existing registered handle can be
+ * reused. Override the demo corridor with:
+ *   CASH_PLATFORM=venmo CASH_CURRENCY=USD CASH_PAYEE=@your-venmo
+ */
+import { createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { base } from 'viem/chains';
+import { createCashClient, usdc, formatUsdc, isCashError } from '@zkp2p/cash';
+import type { CurrencyType } from '@zkp2p/cash';
+
+const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
+const signer = createWalletClient({ account, chain: base, transport: http() });
+
+const receive = {
+  platform: process.env.CASH_PLATFORM ?? 'venmo',
+  currency: (process.env.CASH_CURRENCY ?? 'USD') as CurrencyType,
+  payee: { offchainId: process.env.CASH_PAYEE ?? '@your-venmo' },
+};
+
+const cash = createCashClient({ environment: 'staging' });
+
+// 0 - What can we do?
+const caps = cash.capabilities();
+console.log(
+  'platforms:',
+  caps.platforms.map((p) => `${p.platform}(${p.currencies.join(',')})`).join(' '),
+);
+
+// 1 - What would 1 USDC get us, roughly?
+const est = await cash.estimate({ amount: usdc(1), currency: receive.currency });
+console.log(
+  `estimate: ≈ ${est.receiveAmount} ${receive.currency} at rate ${est.rate} (${est.kind})`,
+);
+
+// 2 - Cash out.
+const result = await cash.cashout({ amount: usdc(1), receive }, { signer });
+console.log(`deposit created: ${result.depositId} (tx ${result.txHash})`);
+// Persist this in YOUR system: userId → result.depositId
+
+// 3/5 - Track it. A real service would watch until terminal; the demo bails
+// out after 30s (an unmatched deposit stays awaiting-buyer until someone bites).
+try {
+  for await (const order of cash.watch(result.depositId, { timeoutMs: 30_000 })) {
+    console.log(`[${order.state}] ${order.explain()}`);
+    if (order.nextActions.length === 0) break;
+  }
+} catch (err) {
+  if (isCashError(err) && err.code === 'WATCH_TIMEOUT') {
+    console.log('still live - resume any time with order(depositId)');
+  } else {
+    throw err;
+  }
+}
+
+// 4 - The wallet's full order history, in-flight first.
+const open = await cash.orders(account.address, { inFlight: true });
+console.log(`in-flight orders: ${open.length}`);
+for (const order of open) {
+  console.log(`  ${order.depositId}: ${order.state}, ${formatUsdc(order.totalAmount)} USDC`);
+}
+
+// 6 - Unwind. The demo cleans up after itself; a real integration would leave
+// the deposit open for buyers instead (CASH_KEEP_OPEN=1).
+if (!process.env.CASH_KEEP_OPEN) {
+  const withdrawn = await cash.withdraw(result.depositId, { signer });
+  console.log(`returned via ${withdrawn.withdrawTxHash}`);
+}