@zkp2p/cash 0.1.0-dev.0

package/dist/tools.cjs

@@ -0,0 +1,148 @@
+'use strict';
+
+// src/tools/index.ts
+var bigintString = {
+  type: "string",
+  pattern: "^[0-9]+$",
+  description: 'USDC base units (6 decimals) as a decimal string, e.g. "1000000000" for 1000 USDC'
+};
+var depositId = {
+  type: "string",
+  description: "Composite deposit id (escrow_onchainId) returned by cash_cashout - the resume key"
+};
+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 }
+  },
+  {
+    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.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        amount: bigintString,
+        currency: {
+          type: "string",
+          description: 'Fiat currency code from cash_capabilities, e.g. "USD"'
+        }
+      },
+      required: ["amount", "currency"],
+      additionalProperties: false
+    }
+  },
+  {
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        amount: bigintString,
+        receive: {
+          type: "object",
+          description: "Where the fiat should arrive",
+          properties: {
+            platform: {
+              type: "string",
+              description: 'Platform id from cash_capabilities, e.g. "venmo"'
+            },
+            currency: { type: "string", description: 'Fiat currency code, e.g. "USD"' },
+            payee: {
+              type: "object",
+              description: "Payee handle for the platform",
+              properties: {
+                offchainId: {
+                  type: "string",
+                  description: 'The handle, e.g. "@andrew" for Venmo - see payeeHint in cash_capabilities'
+                }
+              },
+              required: ["offchainId"],
+              additionalProperties: true
+            }
+          },
+          required: ["platform", "currency", "payee"],
+          additionalProperties: false
+        }
+      },
+      required: ["amount", "receive"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "cash_order",
+    description: "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.",
+    inputSchema: {
+      type: "object",
+      properties: { depositId },
+      required: ["depositId"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "cash_orders",
+    description: "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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        owner: { type: "string", 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)" }
+      },
+      required: ["owner"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "cash_buyer",
+    description: `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?".`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        address: { type: "string", description: "The buyer (taker) wallet address (0x...)" }
+      },
+      required: ["address"],
+      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).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        depositId,
+        amount: {
+          ...bigintString,
+          description: "Optional partial amount (USDC base units, decimal string). Omit to close the order fully."
+        }
+      },
+      required: ["depositId"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "cash_topup",
+    description: "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.",
+    inputSchema: {
+      type: "object",
+      properties: { depositId, amount: bigintString },
+      required: ["depositId", "amount"],
+      additionalProperties: false
+    }
+  }
+];
+var cashToolManifest = {
+  name: "@zkp2p/cash",
+  version: "0.1.0-dev.0",
+  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.",
+  tools: cashTools
+};
+
+exports.cashToolManifest = cashToolManifest;
+exports.cashTools = cashTools;
+//# sourceMappingURL=tools.cjs.map
+//# sourceMappingURL=tools.cjs.map

package/dist/tools.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tools/index.ts"],"names":[],"mappings":";;;AAsBA,IAAM,YAAA,GAAe;AAAA,EACnB,IAAA,EAAM,QAAA;AAAA,EACN,OAAA,EAAS,UAAA;AAAA,EACT,WAAA,EAAa;AACf,CAAA;AAEA,IAAM,SAAA,GAAY;AAAA,EAChB,IAAA,EAAM,QAAA;AAAA,EACN,WAAA,EAAa;AACf,CAAA;AAEO,IAAM,SAAA,GAAkC;AAAA,EAC7C;AAAA,IACE,IAAA,EAAM,mBAAA;AAAA,IACN,WAAA,EACE,uLAAA;AAAA,IACF,WAAA,EAAa,EAAE,IAAA,EAAM,QAAA,EAAU,YAAY,EAAC,EAAG,sBAAsB,KAAA;AAAM,GAC7E;AAAA,EACA;AAAA,IACE,IAAA,EAAM,eAAA;AAAA,IACN,WAAA,EACE,yOAAA;AAAA,IACF,WAAA,EAAa;AAAA,MACX,IAAA,EAAM,QAAA;AAAA,MACN,UAAA,EAAY;AAAA,QACV,MAAA,EAAQ,YAAA;AAAA,QACR,QAAA,EAAU;AAAA,UACR,IAAA,EAAM,QAAA;AAAA,UACN,WAAA,EAAa;AAAA;AACf,OACF;AAAA,MACA,QAAA,EAAU,CAAC,QAAA,EAAU,UAAU,CAAA;AAAA,MAC/B,oBAAA,EAAsB;AAAA;AACxB,GACF;AAAA,EACA;AAAA,IACE,IAAA,EAAM,cAAA;AAAA,IACN,WAAA,EACE,gVAAA;AAAA,IACF,WAAA,EAAa;AAAA,MACX,IAAA,EAAM,QAAA;AAAA,MACN,UAAA,EAAY;AAAA,QACV,MAAA,EAAQ,YAAA;AAAA,QACR,OAAA,EAAS;AAAA,UACP,IAAA,EAAM,QAAA;AAAA,UACN,WAAA,EAAa,8BAAA;AAAA,UACb,UAAA,EAAY;AAAA,YACV,QAAA,EAAU;AAAA,cACR,IAAA,EAAM,QAAA;AAAA,cACN,WAAA,EAAa;AAAA,aACf;AAAA,YACA,QAAA,EAAU,EAAE,IAAA,EAAM,QAAA,EAAU,aAAa,gCAAA,EAAiC;AAAA,YAC1E,KAAA,EAAO;AAAA,cACL,IAAA,EAAM,QAAA;AAAA,cACN,WAAA,EAAa,+BAAA;AAAA,cACb,UAAA,EAAY;AAAA,gBACV,UAAA,EAAY;AAAA,kBACV,IAAA,EAAM,QAAA;AAAA,kBACN,WAAA,EACE;AAAA;AACJ,eACF;AAAA,cACA,QAAA,EAAU,CAAC,YAAY,CAAA;AAAA,cACvB,oBAAA,EAAsB;AAAA;AACxB,WACF;AAAA,UACA,QAAA,EAAU,CAAC,UAAA,EAAY,UAAA,EAAY,OAAO,CAAA;AAAA,UAC1C,oBAAA,EAAsB;AAAA;AACxB,OACF;AAAA,MACA,QAAA,EAAU,CAAC,QAAA,EAAU,SAAS,CAAA;AAAA,MAC9B,oBAAA,EAAsB;AAAA;AACxB,GACF;AAAA,EACA;AAAA,IACE,IAAA,EAAM,YAAA;AAAA,IACN,WAAA,EACE,8UAAA;AAAA,IACF,WAAA,EAAa;AAAA,MACX,IAAA,EAAM,QAAA;AAAA,MACN,UAAA,EAAY,EAAE,SAAA,EAAU;AAAA,MACxB,QAAA,EAAU,CAAC,WAAW,CAAA;AAAA,MACtB,oBAAA,EAAsB;AAAA;AACxB,GACF;AAAA,EACA;AAAA,IACE,IAAA,EAAM,aAAA;AAAA,IACN,WAAA,EACE,2LAAA;AAAA,IACF,WAAA,EAAa;AAAA,MACX,IAAA,EAAM,QAAA;AAAA,MACN,UAAA,EAAY;AAAA,QACV,KAAA,EAAO,EAAE,IAAA,EAAM,QAAA,EAAU,aAAa,kCAAA,EAAmC;AAAA,QACzE,QAAA,EAAU;AAAA,UACR,IAAA,EAAM,SAAA;AAAA,UACN,WAAA,EAAa;AAAA,SACf;AAAA,QACA,KAAA,EAAO,EAAE,IAAA,EAAM,QAAA,EAAU,aAAa,oCAAA;AAAqC,OAC7E;AAAA,MACA,QAAA,EAAU,CAAC,OAAO,CAAA;AAAA,MAClB,oBAAA,EAAsB;AAAA;AACxB,GACF;AAAA,EACA;AAAA,IACE,IAAA,EAAM,YAAA;AAAA,IACN,WAAA,EACE,CAAA,oOAAA,CAAA;AAAA,IACF,WAAA,EAAa;AAAA,MACX,IAAA,EAAM,QAAA;AAAA,MACN,UAAA,EAAY;AAAA,QACV,OAAA,EAAS,EAAE,IAAA,EAAM,QAAA,EAAU,aAAa,0CAAA;AAA2C,OACrF;AAAA,MACA,QAAA,EAAU,CAAC,SAAS,CAAA;AAAA,MACpB,oBAAA,EAAsB;AAAA;AACxB,GACF;AAAA,EACA;AAAA,IACE,IAAA,EAAM,eAAA;AAAA,IACN,WAAA,EACE,2dAAA;AAAA,IACF,WAAA,EAAa;AAAA,MACX,IAAA,EAAM,QAAA;AAAA,MACN,UAAA,EAAY;AAAA,QACV,SAAA;AAAA,QACA,MAAA,EAAQ;AAAA,UACN,GAAG,YAAA;AAAA,UACH,WAAA,EACE;AAAA;AACJ,OACF;AAAA,MACA,QAAA,EAAU,CAAC,WAAW,CAAA;AAAA,MACtB,oBAAA,EAAsB;AAAA;AACxB,GACF;AAAA,EACA;AAAA,IACE,IAAA,EAAM,YAAA;AAAA,IACN,WAAA,EACE,gQAAA;AAAA,IACF,WAAA,EAAa;AAAA,MACX,IAAA,EAAM,QAAA;AAAA,MACN,UAAA,EAAY,EAAE,SAAA,EAAW,MAAA,EAAQ,YAAA,EAAa;AAAA,MAC9C,QAAA,EAAU,CAAC,WAAA,EAAa,QAAQ,CAAA;AAAA,MAChC,oBAAA,EAAsB;AAAA;AACxB;AAEJ;AAGO,IAAM,gBAAA,GAAmB;AAAA,EAC9B,IAAA,EAAM,aAAA;AAAA,EACN,OAAA,EAAS,aAAA;AAAA,EACT,WAAA,EACE,iNAAA;AAAA,EACF,KAAA,EAAO;AACT","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.0-dev.0',\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"]}

package/dist/tools.d.cts

@@ -0,0 +1,31 @@
+/**
+ * `@zkp2p/cash/tools` - JSON-schema tool definitions of the verbs, so
+ * agent hosts (peer-cli, zkp2p-mcp, any MCP server or tool-use loop) adopt
+ * Peer Cash without re-deriving schemas.
+ *
+ * Design rules:
+ * - Mutating verbs default to the **prepare path**: the tool returns unsigned
+ *   transactions plus readable step labels; signing stays host-side, where key
+ *   custody and policy live.
+ * - Every input/output is plain JSON (bigints as decimal strings) - see the
+ *   codecs exported from the package root for lossless (de)serialization.
+ * - `watch` is intentionally not a tool: agents poll `cash_order` between
+ *   other work instead of holding a streaming connection open.
+ */
+interface CashToolDefinition {
+    name: string;
+    description: string;
+    /** JSON Schema (draft-07 compatible) for the tool input. */
+    inputSchema: Record<string, unknown>;
+}
+declare const cashTools: CashToolDefinition[];
+/** Manifest wrapper with versioning for host registries. */
+declare const cashToolManifest: {
+    readonly name: "@zkp2p/cash";
+    readonly version: "0.1.0-dev.0";
+    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 tools: CashToolDefinition[];
+};
+type CashToolName = (typeof cashTools)[number]['name'];
+
+export { type CashToolDefinition, type CashToolName, cashToolManifest, cashTools };

package/dist/tools.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `@zkp2p/cash/tools` - JSON-schema tool definitions of the verbs, so
+ * agent hosts (peer-cli, zkp2p-mcp, any MCP server or tool-use loop) adopt
+ * Peer Cash without re-deriving schemas.
+ *
+ * Design rules:
+ * - Mutating verbs default to the **prepare path**: the tool returns unsigned
+ *   transactions plus readable step labels; signing stays host-side, where key
+ *   custody and policy live.
+ * - Every input/output is plain JSON (bigints as decimal strings) - see the
+ *   codecs exported from the package root for lossless (de)serialization.
+ * - `watch` is intentionally not a tool: agents poll `cash_order` between
+ *   other work instead of holding a streaming connection open.
+ */
+interface CashToolDefinition {
+    name: string;
+    description: string;
+    /** JSON Schema (draft-07 compatible) for the tool input. */
+    inputSchema: Record<string, unknown>;
+}
+declare const cashTools: CashToolDefinition[];
+/** Manifest wrapper with versioning for host registries. */
+declare const cashToolManifest: {
+    readonly name: "@zkp2p/cash";
+    readonly version: "0.1.0-dev.0";
+    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 tools: CashToolDefinition[];
+};
+type CashToolName = (typeof cashTools)[number]['name'];
+
+export { type CashToolDefinition, type CashToolName, cashToolManifest, cashTools };

package/dist/tools.js

@@ -0,0 +1,145 @@
+// src/tools/index.ts
+var bigintString = {
+  type: "string",
+  pattern: "^[0-9]+$",
+  description: 'USDC base units (6 decimals) as a decimal string, e.g. "1000000000" for 1000 USDC'
+};
+var depositId = {
+  type: "string",
+  description: "Composite deposit id (escrow_onchainId) returned by cash_cashout - the resume key"
+};
+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 }
+  },
+  {
+    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.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        amount: bigintString,
+        currency: {
+          type: "string",
+          description: 'Fiat currency code from cash_capabilities, e.g. "USD"'
+        }
+      },
+      required: ["amount", "currency"],
+      additionalProperties: false
+    }
+  },
+  {
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        amount: bigintString,
+        receive: {
+          type: "object",
+          description: "Where the fiat should arrive",
+          properties: {
+            platform: {
+              type: "string",
+              description: 'Platform id from cash_capabilities, e.g. "venmo"'
+            },
+            currency: { type: "string", description: 'Fiat currency code, e.g. "USD"' },
+            payee: {
+              type: "object",
+              description: "Payee handle for the platform",
+              properties: {
+                offchainId: {
+                  type: "string",
+                  description: 'The handle, e.g. "@andrew" for Venmo - see payeeHint in cash_capabilities'
+                }
+              },
+              required: ["offchainId"],
+              additionalProperties: true
+            }
+          },
+          required: ["platform", "currency", "payee"],
+          additionalProperties: false
+        }
+      },
+      required: ["amount", "receive"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "cash_order",
+    description: "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.",
+    inputSchema: {
+      type: "object",
+      properties: { depositId },
+      required: ["depositId"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "cash_orders",
+    description: "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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        owner: { type: "string", 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)" }
+      },
+      required: ["owner"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "cash_buyer",
+    description: `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?".`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        address: { type: "string", description: "The buyer (taker) wallet address (0x...)" }
+      },
+      required: ["address"],
+      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).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        depositId,
+        amount: {
+          ...bigintString,
+          description: "Optional partial amount (USDC base units, decimal string). Omit to close the order fully."
+        }
+      },
+      required: ["depositId"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "cash_topup",
+    description: "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.",
+    inputSchema: {
+      type: "object",
+      properties: { depositId, amount: bigintString },
+      required: ["depositId", "amount"],
+      additionalProperties: false
+    }
+  }
+];
+var cashToolManifest = {
+  name: "@zkp2p/cash",
+  version: "0.1.0-dev.0",
+  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.",
+  tools: cashTools
+};
+
+export { cashToolManifest, cashTools };
+//# sourceMappingURL=tools.js.map
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +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.0-dev.0',\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"]}

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@zkp2p/cash",
+  "version": "0.1.0-dev.0",
+  "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.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zkp2p/peer-cash.git"
+  },
+  "homepage": "https://github.com/zkp2p/peer-cash#readme",
+  "bugs": "https://github.com/zkp2p/peer-cash/issues",
+  "keywords": [
+    "zkp2p",
+    "offramp",
+    "usdc",
+    "base",
+    "crypto-to-fiat",
+    "payments",
+    "sdk"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "require": "./dist/react.cjs"
+    },
+    "./tools": {
+      "types": "./dist/tools.d.ts",
+      "import": "./dist/tools.js",
+      "require": "./dist/tools.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src test examples",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "ci": "bun run typecheck && bun run lint && bun run format:check && bun run test && bun run build"
+  },
+  "dependencies": {
+    "@zkp2p/sdk": "^0.8.0",
+    "zod": "^3.24.1"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "viem": "^2.21.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.0.2",
+    "eslint": "^9.17.0",
+    "eslint-config-prettier": "^9.1.0",
+    "prettier": "^3.4.2",
+    "react": "^19.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.18.1",
+    "viem": "^2.21.0",
+    "vitest": "^2.1.8"
+  }
+}