@zkp2p/cash 0.1.1 → 0.1.2

package/dist/tools.cjs

@@ -4,7 +4,7 @@
 var bigintString = {
   type: "string",
   pattern: "^[0-9]+$",
-  description: 'USDC base units (6 decimals) as a decimal string, e.g. "1000000000" for 1000 USDC'
+  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",
@@ -13,12 +13,52 @@ var depositId = {
 var cashTools = [
   {
     name: "cash_capabilities",
-    description: "Discover what Peer Cash can do: payout platforms, oracle-priced currencies per platform, payee handle format hints, and amount bounds. Static and side-effect free - call this first.",
-    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        includeRelaySources: {
+          type: "boolean",
+          description: "Fetch live Relay SDK EVM source chain/token metadata."
+        }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        user: { type: "string", 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." }
+          },
+          required: ["chainId", "currency"],
+          additionalProperties: false
+        },
+        recipient: {
+          type: "string",
+          description: "Base recipient for Relay-delivered USDC. Defaults to user."
+        },
+        tradeType: {
+          type: "string",
+          enum: ["EXACT_INPUT", "EXACT_OUTPUT", "EXPECTED_OUTPUT"],
+          description: "Relay quote trade type. Defaults to EXACT_INPUT."
+        }
+      },
+      required: ["user", "amount", "source"],
+      additionalProperties: false
+    }
   },
   {
     name: "cash_estimate",
-    description: 'Estimate fiat received for a USDC amount at the live oracle market rate. No payee, no side effects, no expiry - the binding rate resolves at the oracle when a buyer fills, so this is always "approximately", never a committed quote.',
+    description: "Estimate fiat received at the live oracle market rate and include a simple recent-fill ETA. Without source, amount is Base USDC. With source, the SDK first quotes source->Base USDC through Relay SDK, then estimates the cashout.",
     inputSchema: {
       type: "object",
       properties: {
@@ -26,6 +66,32 @@ var cashTools = [
         currency: {
           type: "string",
           description: 'Fiat currency code from cash_capabilities, e.g. "USD"'
+        },
+        platform: {
+          type: "string",
+          description: "Optional payout platform for platform-specific ETA sampling."
+        },
+        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." },
+            user: {
+              type: "string",
+              description: "Source wallet submitting the Relay transaction."
+            },
+            recipient: {
+              type: "string",
+              description: "Base recipient for Relay-delivered USDC. Defaults to user."
+            },
+            tradeType: {
+              type: "string",
+              enum: ["EXACT_INPUT", "EXACT_OUTPUT", "EXPECTED_OUTPUT"]
+            }
+          },
+          required: ["chainId", "currency", "user"],
+          additionalProperties: false
         }
       },
       required: ["amount", "currency"],
@@ -34,11 +100,29 @@ var cashTools = [
   },
   {
     name: "cash_cashout",
-    description: "Start a cash-out: registers the payee with the curator and returns UNSIGNED transactions plus same-index steps [approve, createDeposit] for the host to sign and submit (prepare path - signing stays host-side). After submission, parse the depositId from the DepositReceived event or find it via cash_orders, then track with cash_order.",
+    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.",
     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",
@@ -108,6 +192,18 @@ var cashTools = [
       additionalProperties: false
     }
   },
+  {
+    name: "cash_source_status",
+    description: "Read Relay request status through the Relay SDK request utility using the requestId returned from cash_source_quote or Relay execution progress.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        requestId: { type: "string", description: "Relay request id." }
+      },
+      required: ["requestId"],
+      additionalProperties: false
+    }
+  },
   {
     name: "cash_withdraw",
     description: "Unwind a cash-out: returns UNSIGNED transaction(s) plus same-index steps (prepare path - signing stays host-side). With amount: partial withdrawal of the unlocked balance (a live buyer intent does not block it). Without amount: closes the order fully, state-aware - when the only live intents have expired it includes a pruneExpiredIntents transaction first; while a live buyer intent locks funds it fails with ACTIVE_INTENT_BLOCKS_WITHDRAWAL (retryable - wait for expiry).",
@@ -137,8 +233,8 @@ var cashTools = [
 ];
 var cashToolManifest = {
   name: "@zkp2p/cash",
-  version: "0.1.1",
-  description: "Peer Cash - offramp-only: cash out Base USDC to fiat at the live oracle market rate (0% spread). Eight verbs; mutating tools return unsigned transactions plus step labels with ERC-8021 peer-cash attribution.",
+  version: "0.1.2",
+  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
 };
 

package/dist/tools.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/tools/index.ts"],"names":[],"mappings":"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","file":"tools.cjs","sourcesContent":["/**\n * `@zkp2p/cash/tools` - JSON-schema tool definitions of the verbs, so\n * agent hosts (peer-cli, zkp2p-mcp, any MCP server or tool-use loop) adopt\n * Peer Cash without re-deriving schemas.\n *\n * Design rules:\n * - Mutating verbs default to the **prepare path**: the tool returns unsigned\n *   transactions plus readable step labels; signing stays host-side, where key\n *   custody and policy live.\n * - Every input/output is plain JSON (bigints as decimal strings) - see the\n *   codecs exported from the package root for lossless (de)serialization.\n * - `watch` is intentionally not a tool: agents poll `cash_order` between\n *   other work instead of holding a streaming connection open.\n */\n\nexport interface CashToolDefinition {\n  name: string;\n  description: string;\n  /** JSON Schema (draft-07 compatible) for the tool input. */\n  inputSchema: Record<string, unknown>;\n}\n\nconst bigintString = {\n  type: 'string',\n  pattern: '^[0-9]+$',\n  description: 'USDC base units (6 decimals) as a decimal string, e.g. \"1000000000\" for 1000 USDC',\n} as const;\n\nconst depositId = {\n  type: 'string',\n  description: 'Composite deposit id (escrow_onchainId) returned by cash_cashout - the resume key',\n} as const;\n\nexport const cashTools: CashToolDefinition[] = [\n  {\n    name: 'cash_capabilities',\n    description:\n      'Discover what Peer Cash can do: payout platforms, oracle-priced currencies per platform, payee handle format hints, and amount bounds. Static and side-effect free - call this first.',\n    inputSchema: { type: 'object', properties: {}, additionalProperties: false },\n  },\n  {\n    name: 'cash_estimate',\n    description:\n      'Estimate fiat received for a USDC amount at the live oracle market rate. No payee, no side effects, no expiry - the binding rate resolves at the oracle when a buyer fills, so this is always \"approximately\", never a committed quote.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        amount: bigintString,\n        currency: {\n          type: 'string',\n          description: 'Fiat currency code from cash_capabilities, e.g. \"USD\"',\n        },\n      },\n      required: ['amount', 'currency'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_cashout',\n    description:\n      'Start a cash-out: registers the payee with the curator and returns UNSIGNED transactions plus same-index steps [approve, createDeposit] for the host to sign and submit (prepare path - signing stays host-side). After submission, parse the depositId from the DepositReceived event or find it via cash_orders, then track with cash_order.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        amount: bigintString,\n        receive: {\n          type: 'object',\n          description: 'Where the fiat should arrive',\n          properties: {\n            platform: {\n              type: 'string',\n              description: 'Platform id from cash_capabilities, e.g. \"venmo\"',\n            },\n            currency: { type: 'string', description: 'Fiat currency code, e.g. \"USD\"' },\n            payee: {\n              type: 'object',\n              description: 'Payee handle for the platform',\n              properties: {\n                offchainId: {\n                  type: 'string',\n                  description:\n                    'The handle, e.g. \"@andrew\" for Venmo - see payeeHint in cash_capabilities',\n                },\n              },\n              required: ['offchainId'],\n              additionalProperties: true,\n            },\n          },\n          required: ['platform', 'currency', 'payee'],\n          additionalProperties: false,\n        },\n      },\n      required: ['amount', 'receive'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_order',\n    description:\n      'Observe one cash-out order by depositId - fully resumable, no session state. Returns state (awaiting-buyer | matched | delivering | delivered | returned), amounts, fills, and nextActions (wait | withdraw). Errors are typed with retryable + remediation; ORDER_NOT_FOUND right after cashout means indexer lag - retry in a few seconds.',\n    inputSchema: {\n      type: 'object',\n      properties: { depositId },\n      required: ['depositId'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_orders',\n    description:\n      'List all cash-out orders for a wallet address (the chain is the database - a cash order IS a deposit, keyed by depositor). Use inFlight=true for only the orders still needing attention.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        owner: { type: 'string', description: 'The maker wallet address (0x...)' },\n        inFlight: {\n          type: 'boolean',\n          description: 'Only awaiting-buyer / matched / delivering orders',\n        },\n        limit: { type: 'number', description: 'Max deposits to scan (default 100)' },\n      },\n      required: ['owner'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_buyer',\n    description:\n      'Look up a buyer\\'s protocol track record from their full intent history: lifetime intents, fulfilled vs pruned counts, success rate (bps), first/last seen. Use during the matched state to answer \"who just committed to my order?\".',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        address: { type: 'string', description: 'The buyer (taker) wallet address (0x...)' },\n      },\n      required: ['address'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_withdraw',\n    description:\n      'Unwind a cash-out: returns UNSIGNED transaction(s) plus same-index steps (prepare path - signing stays host-side). With amount: partial withdrawal of the unlocked balance (a live buyer intent does not block it). Without amount: closes the order fully, state-aware - when the only live intents have expired it includes a pruneExpiredIntents transaction first; while a live buyer intent locks funds it fails with ACTIVE_INTENT_BLOCKS_WITHDRAWAL (retryable - wait for expiry).',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        depositId,\n        amount: {\n          ...bigintString,\n          description:\n            'Optional partial amount (USDC base units, decimal string). Omit to close the order fully.',\n        },\n      },\n      required: ['depositId'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_topup',\n    description:\n      'Add USDC to a live cash-out order (same payee, same market rate). Returns UNSIGNED transactions plus same-index steps [approve, addFunds] for the host to sign and submit in order. Fails with ORDER_NOT_ACTIVE if the order is already delivered or returned.',\n    inputSchema: {\n      type: 'object',\n      properties: { depositId, amount: bigintString },\n      required: ['depositId', 'amount'],\n      additionalProperties: false,\n    },\n  },\n];\n\n/** Manifest wrapper with versioning for host registries. */\nexport const cashToolManifest = {\n  name: '@zkp2p/cash',\n  version: '0.1.1',\n  description:\n    'Peer Cash - offramp-only: cash out Base USDC to fiat at the live oracle market rate (0% spread). Eight verbs; mutating tools return unsigned transactions plus step labels with ERC-8021 peer-cash attribution.',\n  tools: cashTools,\n} as const;\n\nexport type CashToolName = (typeof cashTools)[number]['name'];\n"]}
+{"version":3,"sources":["../src/tools/index.ts"],"names":[],"mappings":"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","file":"tools.cjs","sourcesContent":["/**\n * `@zkp2p/cash/tools` - JSON-schema tool definitions of the verbs, so\n * agent hosts (peer-cli, zkp2p-mcp, any MCP server or tool-use loop) adopt\n * Peer Cash without re-deriving schemas.\n *\n * Design rules:\n * - Mutating verbs default to the **prepare path**: the tool returns unsigned\n *   transactions plus readable step labels; signing stays host-side, where key\n *   custody and policy live.\n * - Every input/output is plain JSON (bigints as decimal strings) - see the\n *   codecs exported from the package root for lossless (de)serialization.\n * - `watch` is intentionally not a tool: agents poll `cash_order` between\n *   other work instead of holding a streaming connection open.\n */\n\nexport interface CashToolDefinition {\n  name: string;\n  description: string;\n  /** JSON Schema (draft-07 compatible) for the tool input. */\n  inputSchema: Record<string, unknown>;\n}\n\nconst bigintString = {\n  type: 'string',\n  pattern: '^[0-9]+$',\n  description:\n    'Base units as a decimal string. For the default path this is USDC 6 decimals; with source it is source-token base units.',\n} as const;\n\nconst depositId = {\n  type: 'string',\n  description: 'Composite deposit id (escrow_onchainId) returned by cash_cashout - the resume key',\n} as const;\n\nexport const cashTools: CashToolDefinition[] = [\n  {\n    name: 'cash_capabilities',\n    description:\n      '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.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        includeRelaySources: {\n          type: 'boolean',\n          description: 'Fetch live Relay SDK EVM source chain/token metadata.',\n        },\n      },\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_source_quote',\n    description:\n      '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.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        user: { type: 'string', description: 'Source wallet submitting the Relay transaction.' },\n        amount: bigintString,\n        source: {\n          type: 'object',\n          properties: {\n            chainId: { type: 'number', description: 'Relay-supported EVM source chain id.' },\n            currency: { type: 'string', description: 'Source token/native address.' },\n          },\n          required: ['chainId', 'currency'],\n          additionalProperties: false,\n        },\n        recipient: {\n          type: 'string',\n          description: 'Base recipient for Relay-delivered USDC. Defaults to user.',\n        },\n        tradeType: {\n          type: 'string',\n          enum: ['EXACT_INPUT', 'EXACT_OUTPUT', 'EXPECTED_OUTPUT'],\n          description: 'Relay quote trade type. Defaults to EXACT_INPUT.',\n        },\n      },\n      required: ['user', 'amount', 'source'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_estimate',\n    description:\n      'Estimate fiat received at the live oracle market rate and include a simple recent-fill ETA. Without source, amount is Base USDC. With source, the SDK first quotes source->Base USDC through Relay SDK, then estimates the cashout.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        amount: bigintString,\n        currency: {\n          type: 'string',\n          description: 'Fiat currency code from cash_capabilities, e.g. \"USD\"',\n        },\n        platform: {\n          type: 'string',\n          description: 'Optional payout platform for platform-specific ETA sampling.',\n        },\n        source: {\n          type: 'object',\n          description: 'Optional Relay EVM source asset. Omit for the Base USDC default path.',\n          properties: {\n            chainId: { type: 'number', description: 'Relay-supported EVM source chain id.' },\n            currency: { type: 'string', description: 'Source token/native address.' },\n            user: {\n              type: 'string',\n              description: 'Source wallet submitting the Relay transaction.',\n            },\n            recipient: {\n              type: 'string',\n              description: 'Base recipient for Relay-delivered USDC. Defaults to user.',\n            },\n            tradeType: {\n              type: 'string',\n              enum: ['EXACT_INPUT', 'EXACT_OUTPUT', 'EXPECTED_OUTPUT'],\n            },\n          },\n          required: ['chainId', 'currency', 'user'],\n          additionalProperties: false,\n        },\n      },\n      required: ['amount', 'currency'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_cashout',\n    description:\n      '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.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        amount: bigintString,\n        source: {\n          type: 'object',\n          description: 'Optional Relay EVM source asset. Omit for the Base USDC default path.',\n          properties: {\n            chainId: { type: 'number', description: 'Relay-supported EVM source chain id.' },\n            currency: { type: 'string', description: 'Source token/native address.' },\n            recipient: {\n              type: 'string',\n              description: 'Base recipient for Relay-delivered USDC. Defaults to signer.',\n            },\n            tradeType: {\n              type: 'string',\n              enum: ['EXACT_INPUT', 'EXACT_OUTPUT', 'EXPECTED_OUTPUT'],\n            },\n          },\n          required: ['chainId', 'currency'],\n          additionalProperties: false,\n        },\n        receive: {\n          type: 'object',\n          description: 'Where the fiat should arrive',\n          properties: {\n            platform: {\n              type: 'string',\n              description: 'Platform id from cash_capabilities, e.g. \"venmo\"',\n            },\n            currency: { type: 'string', description: 'Fiat currency code, e.g. \"USD\"' },\n            payee: {\n              type: 'object',\n              description: 'Payee handle for the platform',\n              properties: {\n                offchainId: {\n                  type: 'string',\n                  description:\n                    'The handle, e.g. \"@andrew\" for Venmo - see payeeHint in cash_capabilities',\n                },\n              },\n              required: ['offchainId'],\n              additionalProperties: true,\n            },\n          },\n          required: ['platform', 'currency', 'payee'],\n          additionalProperties: false,\n        },\n      },\n      required: ['amount', 'receive'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_order',\n    description:\n      'Observe one cash-out order by depositId - fully resumable, no session state. Returns state (awaiting-buyer | matched | delivering | delivered | returned), amounts, fills, and nextActions (wait | withdraw). Errors are typed with retryable + remediation; ORDER_NOT_FOUND right after cashout means indexer lag - retry in a few seconds.',\n    inputSchema: {\n      type: 'object',\n      properties: { depositId },\n      required: ['depositId'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_orders',\n    description:\n      'List all cash-out orders for a wallet address (the chain is the database - a cash order IS a deposit, keyed by depositor). Use inFlight=true for only the orders still needing attention.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        owner: { type: 'string', description: 'The maker wallet address (0x...)' },\n        inFlight: {\n          type: 'boolean',\n          description: 'Only awaiting-buyer / matched / delivering orders',\n        },\n        limit: { type: 'number', description: 'Max deposits to scan (default 100)' },\n      },\n      required: ['owner'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_buyer',\n    description:\n      'Look up a buyer\\'s protocol track record from their full intent history: lifetime intents, fulfilled vs pruned counts, success rate (bps), first/last seen. Use during the matched state to answer \"who just committed to my order?\".',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        address: { type: 'string', description: 'The buyer (taker) wallet address (0x...)' },\n      },\n      required: ['address'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_source_status',\n    description:\n      'Read Relay request status through the Relay SDK request utility using the requestId returned from cash_source_quote or Relay execution progress.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        requestId: { type: 'string', description: 'Relay request id.' },\n      },\n      required: ['requestId'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_withdraw',\n    description:\n      'Unwind a cash-out: returns UNSIGNED transaction(s) plus same-index steps (prepare path - signing stays host-side). With amount: partial withdrawal of the unlocked balance (a live buyer intent does not block it). Without amount: closes the order fully, state-aware - when the only live intents have expired it includes a pruneExpiredIntents transaction first; while a live buyer intent locks funds it fails with ACTIVE_INTENT_BLOCKS_WITHDRAWAL (retryable - wait for expiry).',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        depositId,\n        amount: {\n          ...bigintString,\n          description:\n            'Optional partial amount (USDC base units, decimal string). Omit to close the order fully.',\n        },\n      },\n      required: ['depositId'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_topup',\n    description:\n      'Add USDC to a live cash-out order (same payee, same market rate). Returns UNSIGNED transactions plus same-index steps [approve, addFunds] for the host to sign and submit in order. Fails with ORDER_NOT_ACTIVE if the order is already delivered or returned.',\n    inputSchema: {\n      type: 'object',\n      properties: { depositId, amount: bigintString },\n      required: ['depositId', 'amount'],\n      additionalProperties: false,\n    },\n  },\n];\n\n/** Manifest wrapper with versioning for host registries. */\nexport const cashToolManifest = {\n  name: '@zkp2p/cash',\n  version: '0.1.2',\n  description:\n    '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.',\n  tools: cashTools,\n} as const;\n\nexport type CashToolName = (typeof cashTools)[number]['name'];\n"]}

package/dist/tools.d.cts

@@ -22,8 +22,8 @@ declare const cashTools: CashToolDefinition[];
 /** Manifest wrapper with versioning for host registries. */
 declare const cashToolManifest: {
     readonly name: "@zkp2p/cash";
-    readonly version: "0.1.1";
-    readonly description: "Peer Cash - offramp-only: cash out Base USDC to fiat at the live oracle market rate (0% spread). Eight verbs; mutating tools return unsigned transactions plus step labels with ERC-8021 peer-cash attribution.";
+    readonly version: "0.1.2";
+    readonly 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.";
     readonly tools: CashToolDefinition[];
 };
 type CashToolName = (typeof cashTools)[number]['name'];

package/dist/tools.d.ts

@@ -22,8 +22,8 @@ declare const cashTools: CashToolDefinition[];
 /** Manifest wrapper with versioning for host registries. */
 declare const cashToolManifest: {
     readonly name: "@zkp2p/cash";
-    readonly version: "0.1.1";
-    readonly description: "Peer Cash - offramp-only: cash out Base USDC to fiat at the live oracle market rate (0% spread). Eight verbs; mutating tools return unsigned transactions plus step labels with ERC-8021 peer-cash attribution.";
+    readonly version: "0.1.2";
+    readonly 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.";
     readonly tools: CashToolDefinition[];
 };
 type CashToolName = (typeof cashTools)[number]['name'];

package/dist/tools.js

@@ -2,7 +2,7 @@
 var bigintString = {
   type: "string",
   pattern: "^[0-9]+$",
-  description: 'USDC base units (6 decimals) as a decimal string, e.g. "1000000000" for 1000 USDC'
+  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",
@@ -11,12 +11,52 @@ var depositId = {
 var cashTools = [
   {
     name: "cash_capabilities",
-    description: "Discover what Peer Cash can do: payout platforms, oracle-priced currencies per platform, payee handle format hints, and amount bounds. Static and side-effect free - call this first.",
-    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        includeRelaySources: {
+          type: "boolean",
+          description: "Fetch live Relay SDK EVM source chain/token metadata."
+        }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        user: { type: "string", 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." }
+          },
+          required: ["chainId", "currency"],
+          additionalProperties: false
+        },
+        recipient: {
+          type: "string",
+          description: "Base recipient for Relay-delivered USDC. Defaults to user."
+        },
+        tradeType: {
+          type: "string",
+          enum: ["EXACT_INPUT", "EXACT_OUTPUT", "EXPECTED_OUTPUT"],
+          description: "Relay quote trade type. Defaults to EXACT_INPUT."
+        }
+      },
+      required: ["user", "amount", "source"],
+      additionalProperties: false
+    }
   },
   {
     name: "cash_estimate",
-    description: 'Estimate fiat received for a USDC amount at the live oracle market rate. No payee, no side effects, no expiry - the binding rate resolves at the oracle when a buyer fills, so this is always "approximately", never a committed quote.',
+    description: "Estimate fiat received at the live oracle market rate and include a simple recent-fill ETA. Without source, amount is Base USDC. With source, the SDK first quotes source->Base USDC through Relay SDK, then estimates the cashout.",
     inputSchema: {
       type: "object",
       properties: {
@@ -24,6 +64,32 @@ var cashTools = [
         currency: {
           type: "string",
           description: 'Fiat currency code from cash_capabilities, e.g. "USD"'
+        },
+        platform: {
+          type: "string",
+          description: "Optional payout platform for platform-specific ETA sampling."
+        },
+        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." },
+            user: {
+              type: "string",
+              description: "Source wallet submitting the Relay transaction."
+            },
+            recipient: {
+              type: "string",
+              description: "Base recipient for Relay-delivered USDC. Defaults to user."
+            },
+            tradeType: {
+              type: "string",
+              enum: ["EXACT_INPUT", "EXACT_OUTPUT", "EXPECTED_OUTPUT"]
+            }
+          },
+          required: ["chainId", "currency", "user"],
+          additionalProperties: false
         }
       },
       required: ["amount", "currency"],
@@ -32,11 +98,29 @@ var cashTools = [
   },
   {
     name: "cash_cashout",
-    description: "Start a cash-out: registers the payee with the curator and returns UNSIGNED transactions plus same-index steps [approve, createDeposit] for the host to sign and submit (prepare path - signing stays host-side). After submission, parse the depositId from the DepositReceived event or find it via cash_orders, then track with cash_order.",
+    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.",
     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",
@@ -106,6 +190,18 @@ var cashTools = [
       additionalProperties: false
     }
   },
+  {
+    name: "cash_source_status",
+    description: "Read Relay request status through the Relay SDK request utility using the requestId returned from cash_source_quote or Relay execution progress.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        requestId: { type: "string", description: "Relay request id." }
+      },
+      required: ["requestId"],
+      additionalProperties: false
+    }
+  },
   {
     name: "cash_withdraw",
     description: "Unwind a cash-out: returns UNSIGNED transaction(s) plus same-index steps (prepare path - signing stays host-side). With amount: partial withdrawal of the unlocked balance (a live buyer intent does not block it). Without amount: closes the order fully, state-aware - when the only live intents have expired it includes a pruneExpiredIntents transaction first; while a live buyer intent locks funds it fails with ACTIVE_INTENT_BLOCKS_WITHDRAWAL (retryable - wait for expiry).",
@@ -135,8 +231,8 @@ var cashTools = [
 ];
 var cashToolManifest = {
   name: "@zkp2p/cash",
-  version: "0.1.1",
-  description: "Peer Cash - offramp-only: cash out Base USDC to fiat at the live oracle market rate (0% spread). Eight verbs; mutating tools return unsigned transactions plus step labels with ERC-8021 peer-cash attribution.",
+  version: "0.1.2",
+  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
 };
 

package/dist/tools.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/tools/index.ts"],"names":[],"mappings":"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","file":"tools.js","sourcesContent":["/**\n * `@zkp2p/cash/tools` - JSON-schema tool definitions of the verbs, so\n * agent hosts (peer-cli, zkp2p-mcp, any MCP server or tool-use loop) adopt\n * Peer Cash without re-deriving schemas.\n *\n * Design rules:\n * - Mutating verbs default to the **prepare path**: the tool returns unsigned\n *   transactions plus readable step labels; signing stays host-side, where key\n *   custody and policy live.\n * - Every input/output is plain JSON (bigints as decimal strings) - see the\n *   codecs exported from the package root for lossless (de)serialization.\n * - `watch` is intentionally not a tool: agents poll `cash_order` between\n *   other work instead of holding a streaming connection open.\n */\n\nexport interface CashToolDefinition {\n  name: string;\n  description: string;\n  /** JSON Schema (draft-07 compatible) for the tool input. */\n  inputSchema: Record<string, unknown>;\n}\n\nconst bigintString = {\n  type: 'string',\n  pattern: '^[0-9]+$',\n  description: 'USDC base units (6 decimals) as a decimal string, e.g. \"1000000000\" for 1000 USDC',\n} as const;\n\nconst depositId = {\n  type: 'string',\n  description: 'Composite deposit id (escrow_onchainId) returned by cash_cashout - the resume key',\n} as const;\n\nexport const cashTools: CashToolDefinition[] = [\n  {\n    name: 'cash_capabilities',\n    description:\n      'Discover what Peer Cash can do: payout platforms, oracle-priced currencies per platform, payee handle format hints, and amount bounds. Static and side-effect free - call this first.',\n    inputSchema: { type: 'object', properties: {}, additionalProperties: false },\n  },\n  {\n    name: 'cash_estimate',\n    description:\n      'Estimate fiat received for a USDC amount at the live oracle market rate. No payee, no side effects, no expiry - the binding rate resolves at the oracle when a buyer fills, so this is always \"approximately\", never a committed quote.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        amount: bigintString,\n        currency: {\n          type: 'string',\n          description: 'Fiat currency code from cash_capabilities, e.g. \"USD\"',\n        },\n      },\n      required: ['amount', 'currency'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_cashout',\n    description:\n      'Start a cash-out: registers the payee with the curator and returns UNSIGNED transactions plus same-index steps [approve, createDeposit] for the host to sign and submit (prepare path - signing stays host-side). After submission, parse the depositId from the DepositReceived event or find it via cash_orders, then track with cash_order.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        amount: bigintString,\n        receive: {\n          type: 'object',\n          description: 'Where the fiat should arrive',\n          properties: {\n            platform: {\n              type: 'string',\n              description: 'Platform id from cash_capabilities, e.g. \"venmo\"',\n            },\n            currency: { type: 'string', description: 'Fiat currency code, e.g. \"USD\"' },\n            payee: {\n              type: 'object',\n              description: 'Payee handle for the platform',\n              properties: {\n                offchainId: {\n                  type: 'string',\n                  description:\n                    'The handle, e.g. \"@andrew\" for Venmo - see payeeHint in cash_capabilities',\n                },\n              },\n              required: ['offchainId'],\n              additionalProperties: true,\n            },\n          },\n          required: ['platform', 'currency', 'payee'],\n          additionalProperties: false,\n        },\n      },\n      required: ['amount', 'receive'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_order',\n    description:\n      'Observe one cash-out order by depositId - fully resumable, no session state. Returns state (awaiting-buyer | matched | delivering | delivered | returned), amounts, fills, and nextActions (wait | withdraw). Errors are typed with retryable + remediation; ORDER_NOT_FOUND right after cashout means indexer lag - retry in a few seconds.',\n    inputSchema: {\n      type: 'object',\n      properties: { depositId },\n      required: ['depositId'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_orders',\n    description:\n      'List all cash-out orders for a wallet address (the chain is the database - a cash order IS a deposit, keyed by depositor). Use inFlight=true for only the orders still needing attention.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        owner: { type: 'string', description: 'The maker wallet address (0x...)' },\n        inFlight: {\n          type: 'boolean',\n          description: 'Only awaiting-buyer / matched / delivering orders',\n        },\n        limit: { type: 'number', description: 'Max deposits to scan (default 100)' },\n      },\n      required: ['owner'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_buyer',\n    description:\n      'Look up a buyer\\'s protocol track record from their full intent history: lifetime intents, fulfilled vs pruned counts, success rate (bps), first/last seen. Use during the matched state to answer \"who just committed to my order?\".',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        address: { type: 'string', description: 'The buyer (taker) wallet address (0x...)' },\n      },\n      required: ['address'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_withdraw',\n    description:\n      'Unwind a cash-out: returns UNSIGNED transaction(s) plus same-index steps (prepare path - signing stays host-side). With amount: partial withdrawal of the unlocked balance (a live buyer intent does not block it). Without amount: closes the order fully, state-aware - when the only live intents have expired it includes a pruneExpiredIntents transaction first; while a live buyer intent locks funds it fails with ACTIVE_INTENT_BLOCKS_WITHDRAWAL (retryable - wait for expiry).',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        depositId,\n        amount: {\n          ...bigintString,\n          description:\n            'Optional partial amount (USDC base units, decimal string). Omit to close the order fully.',\n        },\n      },\n      required: ['depositId'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_topup',\n    description:\n      'Add USDC to a live cash-out order (same payee, same market rate). Returns UNSIGNED transactions plus same-index steps [approve, addFunds] for the host to sign and submit in order. Fails with ORDER_NOT_ACTIVE if the order is already delivered or returned.',\n    inputSchema: {\n      type: 'object',\n      properties: { depositId, amount: bigintString },\n      required: ['depositId', 'amount'],\n      additionalProperties: false,\n    },\n  },\n];\n\n/** Manifest wrapper with versioning for host registries. */\nexport const cashToolManifest = {\n  name: '@zkp2p/cash',\n  version: '0.1.1',\n  description:\n    'Peer Cash - offramp-only: cash out Base USDC to fiat at the live oracle market rate (0% spread). Eight verbs; mutating tools return unsigned transactions plus step labels with ERC-8021 peer-cash attribution.',\n  tools: cashTools,\n} as const;\n\nexport type CashToolName = (typeof cashTools)[number]['name'];\n"]}
+{"version":3,"sources":["../src/tools/index.ts"],"names":[],"mappings":"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","file":"tools.js","sourcesContent":["/**\n * `@zkp2p/cash/tools` - JSON-schema tool definitions of the verbs, so\n * agent hosts (peer-cli, zkp2p-mcp, any MCP server or tool-use loop) adopt\n * Peer Cash without re-deriving schemas.\n *\n * Design rules:\n * - Mutating verbs default to the **prepare path**: the tool returns unsigned\n *   transactions plus readable step labels; signing stays host-side, where key\n *   custody and policy live.\n * - Every input/output is plain JSON (bigints as decimal strings) - see the\n *   codecs exported from the package root for lossless (de)serialization.\n * - `watch` is intentionally not a tool: agents poll `cash_order` between\n *   other work instead of holding a streaming connection open.\n */\n\nexport interface CashToolDefinition {\n  name: string;\n  description: string;\n  /** JSON Schema (draft-07 compatible) for the tool input. */\n  inputSchema: Record<string, unknown>;\n}\n\nconst bigintString = {\n  type: 'string',\n  pattern: '^[0-9]+$',\n  description:\n    'Base units as a decimal string. For the default path this is USDC 6 decimals; with source it is source-token base units.',\n} as const;\n\nconst depositId = {\n  type: 'string',\n  description: 'Composite deposit id (escrow_onchainId) returned by cash_cashout - the resume key',\n} as const;\n\nexport const cashTools: CashToolDefinition[] = [\n  {\n    name: 'cash_capabilities',\n    description:\n      '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.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        includeRelaySources: {\n          type: 'boolean',\n          description: 'Fetch live Relay SDK EVM source chain/token metadata.',\n        },\n      },\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_source_quote',\n    description:\n      '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.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        user: { type: 'string', description: 'Source wallet submitting the Relay transaction.' },\n        amount: bigintString,\n        source: {\n          type: 'object',\n          properties: {\n            chainId: { type: 'number', description: 'Relay-supported EVM source chain id.' },\n            currency: { type: 'string', description: 'Source token/native address.' },\n          },\n          required: ['chainId', 'currency'],\n          additionalProperties: false,\n        },\n        recipient: {\n          type: 'string',\n          description: 'Base recipient for Relay-delivered USDC. Defaults to user.',\n        },\n        tradeType: {\n          type: 'string',\n          enum: ['EXACT_INPUT', 'EXACT_OUTPUT', 'EXPECTED_OUTPUT'],\n          description: 'Relay quote trade type. Defaults to EXACT_INPUT.',\n        },\n      },\n      required: ['user', 'amount', 'source'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_estimate',\n    description:\n      'Estimate fiat received at the live oracle market rate and include a simple recent-fill ETA. Without source, amount is Base USDC. With source, the SDK first quotes source->Base USDC through Relay SDK, then estimates the cashout.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        amount: bigintString,\n        currency: {\n          type: 'string',\n          description: 'Fiat currency code from cash_capabilities, e.g. \"USD\"',\n        },\n        platform: {\n          type: 'string',\n          description: 'Optional payout platform for platform-specific ETA sampling.',\n        },\n        source: {\n          type: 'object',\n          description: 'Optional Relay EVM source asset. Omit for the Base USDC default path.',\n          properties: {\n            chainId: { type: 'number', description: 'Relay-supported EVM source chain id.' },\n            currency: { type: 'string', description: 'Source token/native address.' },\n            user: {\n              type: 'string',\n              description: 'Source wallet submitting the Relay transaction.',\n            },\n            recipient: {\n              type: 'string',\n              description: 'Base recipient for Relay-delivered USDC. Defaults to user.',\n            },\n            tradeType: {\n              type: 'string',\n              enum: ['EXACT_INPUT', 'EXACT_OUTPUT', 'EXPECTED_OUTPUT'],\n            },\n          },\n          required: ['chainId', 'currency', 'user'],\n          additionalProperties: false,\n        },\n      },\n      required: ['amount', 'currency'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_cashout',\n    description:\n      '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.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        amount: bigintString,\n        source: {\n          type: 'object',\n          description: 'Optional Relay EVM source asset. Omit for the Base USDC default path.',\n          properties: {\n            chainId: { type: 'number', description: 'Relay-supported EVM source chain id.' },\n            currency: { type: 'string', description: 'Source token/native address.' },\n            recipient: {\n              type: 'string',\n              description: 'Base recipient for Relay-delivered USDC. Defaults to signer.',\n            },\n            tradeType: {\n              type: 'string',\n              enum: ['EXACT_INPUT', 'EXACT_OUTPUT', 'EXPECTED_OUTPUT'],\n            },\n          },\n          required: ['chainId', 'currency'],\n          additionalProperties: false,\n        },\n        receive: {\n          type: 'object',\n          description: 'Where the fiat should arrive',\n          properties: {\n            platform: {\n              type: 'string',\n              description: 'Platform id from cash_capabilities, e.g. \"venmo\"',\n            },\n            currency: { type: 'string', description: 'Fiat currency code, e.g. \"USD\"' },\n            payee: {\n              type: 'object',\n              description: 'Payee handle for the platform',\n              properties: {\n                offchainId: {\n                  type: 'string',\n                  description:\n                    'The handle, e.g. \"@andrew\" for Venmo - see payeeHint in cash_capabilities',\n                },\n              },\n              required: ['offchainId'],\n              additionalProperties: true,\n            },\n          },\n          required: ['platform', 'currency', 'payee'],\n          additionalProperties: false,\n        },\n      },\n      required: ['amount', 'receive'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_order',\n    description:\n      'Observe one cash-out order by depositId - fully resumable, no session state. Returns state (awaiting-buyer | matched | delivering | delivered | returned), amounts, fills, and nextActions (wait | withdraw). Errors are typed with retryable + remediation; ORDER_NOT_FOUND right after cashout means indexer lag - retry in a few seconds.',\n    inputSchema: {\n      type: 'object',\n      properties: { depositId },\n      required: ['depositId'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_orders',\n    description:\n      'List all cash-out orders for a wallet address (the chain is the database - a cash order IS a deposit, keyed by depositor). Use inFlight=true for only the orders still needing attention.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        owner: { type: 'string', description: 'The maker wallet address (0x...)' },\n        inFlight: {\n          type: 'boolean',\n          description: 'Only awaiting-buyer / matched / delivering orders',\n        },\n        limit: { type: 'number', description: 'Max deposits to scan (default 100)' },\n      },\n      required: ['owner'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_buyer',\n    description:\n      'Look up a buyer\\'s protocol track record from their full intent history: lifetime intents, fulfilled vs pruned counts, success rate (bps), first/last seen. Use during the matched state to answer \"who just committed to my order?\".',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        address: { type: 'string', description: 'The buyer (taker) wallet address (0x...)' },\n      },\n      required: ['address'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_source_status',\n    description:\n      'Read Relay request status through the Relay SDK request utility using the requestId returned from cash_source_quote or Relay execution progress.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        requestId: { type: 'string', description: 'Relay request id.' },\n      },\n      required: ['requestId'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_withdraw',\n    description:\n      'Unwind a cash-out: returns UNSIGNED transaction(s) plus same-index steps (prepare path - signing stays host-side). With amount: partial withdrawal of the unlocked balance (a live buyer intent does not block it). Without amount: closes the order fully, state-aware - when the only live intents have expired it includes a pruneExpiredIntents transaction first; while a live buyer intent locks funds it fails with ACTIVE_INTENT_BLOCKS_WITHDRAWAL (retryable - wait for expiry).',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        depositId,\n        amount: {\n          ...bigintString,\n          description:\n            'Optional partial amount (USDC base units, decimal string). Omit to close the order fully.',\n        },\n      },\n      required: ['depositId'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'cash_topup',\n    description:\n      'Add USDC to a live cash-out order (same payee, same market rate). Returns UNSIGNED transactions plus same-index steps [approve, addFunds] for the host to sign and submit in order. Fails with ORDER_NOT_ACTIVE if the order is already delivered or returned.',\n    inputSchema: {\n      type: 'object',\n      properties: { depositId, amount: bigintString },\n      required: ['depositId', 'amount'],\n      additionalProperties: false,\n    },\n  },\n];\n\n/** Manifest wrapper with versioning for host registries. */\nexport const cashToolManifest = {\n  name: '@zkp2p/cash',\n  version: '0.1.2',\n  description:\n    '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.',\n  tools: cashTools,\n} as const;\n\nexport type CashToolName = (typeof cashTools)[number]['name'];\n"]}

package/llms.txt

@@ -1,28 +1,31 @@
 # @zkp2p/cash - Peer Cash
 
-> Offramp-only SDK for the ZKP2P protocol: cash out Base USDC to fiat (Venmo,
-> Revolut, Wise, Zelle, ...) at the live Chainlink oracle market rate with zero
-> spread and no centralized off-ramp provider. The user is the maker,
-> Peer handles the buyer side, and eight verbs expose readable order state.
-> Every operation is available as pure serializable data; a React app, a Node service, and an AI agent are equal
-> consumers.
+> Offramp-only SDK for the ZKP2P protocol: route any Relay-supported EVM source
+> asset to Base USDC, then cash out to fiat (Venmo, Revolut, Wise, Zelle, ...)
+> at the live Chainlink oracle market rate with zero spread and no centralized
+> off-ramp provider. The user is the maker, Peer handles the buyer side, and the
+> SDK exposes readable order state.
+> Base-USDC flows are serializable through prepare paths; source-routed cashout
+> uses Relay execution first. React apps, Node services, and agent hosts use the
+> same typed surface.
 
 Key facts:
 
 - The cashing-out user is the MAKER: their USDC becomes a protocol-held order;
   a buyer pays fiat and proves it with TEE-TLS; the protocol releases the USDC.
-- There is NO quote. estimate() reads the oracle; the binding rate resolves
-  at fill time. Never present a locked price or an ETA.
+- Destination is always Base USDC. Source chains/tokens come from Relay SDK
+  metadata and quote execution, filtered to EVM chains this SDK can sign.
+- 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.
 - 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).
-- Mutating verbs have unsigned counterparts (prepare, prepareWithdraw,
-  prepareTopUp) for host-side signing; @zkp2p/cash/tools ships a JSON-schema
-  tool manifest. Prepare results include `txs[]` plus same-index `steps[]`
-  labels so hosts can explain approvals and deposits before signing. Every
-  transaction carries ERC-8021 attribution ('peer-cash' plus integrator
-  referrer codes).
+- 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 }.
 - Everything is decoded to human units: platform ids and currency codes from
   their on-chain hashes, plain-number rates from 1e18 precision.
@@ -32,7 +35,9 @@ Key facts:
   verifiable pricing proof (spreadBps: 0, oracle kind) from indexed data.
 - buyer(address) aggregates a buyer's track record (fulfilled/pruned/success
   rate) from their full intent history.
-- v1 is same-chain only: Base USDC in.
+- Default path is same-chain Base USDC. Optional `source` on `cashout()` runs
+  Relay source-to-Base-USDC first; non-Base source chains require
+  `sourceSigner`.
 
 ## Links
 
@@ -45,8 +50,8 @@ Key facts:
 - [README](README.md): quickstart, verb table, lifecycle diagram
 - [AGENTS.md](AGENTS.md): agent integration manual - decision tree,
   prepare-path patterns, error → remediation table
-- [Lifecycle and recovery](docs/lifecycle-and-recovery.md): states, partial
-  fills, honest-ETA principle, unwind, resumability, failure table
+- [Lifecycle and recovery](docs/lifecycle-and-recovery.md): source routing,
+  states, partial fills, ETA principle, unwind, resumability, failure table
 - [Integration skill](skills/peer-cash-integration/SKILL.md): step-by-step
   onboarding for coding agents, with the staging verification checklist
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zkp2p/cash",
-  "version": "0.1.1",
-  "description": "Peer Cash - offramp-only SDK for the ZKP2P protocol: eight verbs to cash out Base USDC to fiat at the live oracle market rate.",
+  "version": "0.1.2",
+  "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",
@@ -68,12 +68,13 @@
     "ci": "bun run typecheck && bun run lint && bun run format:check && bun run test && bun run build"
   },
   "dependencies": {
+    "@relayprotocol/relay-sdk": "^6.1.3",
     "@zkp2p/sdk": "^0.8.0",
     "zod": "^3.24.1"
   },
   "peerDependencies": {
     "react": ">=18",
-    "viem": "^2.21.0"
+    "viem": ">=2.26.0"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -91,7 +92,7 @@
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
     "typescript-eslint": "^8.18.1",
-    "viem": "^2.21.0",
+    "viem": "^2.26.0",
     "vitest": "^2.1.8"
   }
 }