/** * `@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; } declare const builtInCashTools: readonly [{ readonly name: "cash_capabilities"; readonly description: "Discover what Peer Cash can do: payout platforms, currencies and rate-binding semantics per platform, Base USDC destination, default Base USDC source, payee handle hints, and amount bounds. Opt into live Relay EVM or NEAR Intents source discovery."; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly includeRelaySources: { readonly type: "boolean"; readonly description: "Fetch live Relay SDK EVM source chain/token metadata."; }; readonly includeNearIntentsSources: { readonly type: "boolean"; readonly description: "Fetch live NEAR Intents 1Click source asset metadata."; }; }; readonly additionalProperties: false; }; }, { readonly name: "cash_source_quote"; readonly description: "Quote any Relay-supported EVM source asset into Base USDC through @relayprotocol/relay-sdk. A custody-capable host must submit the returned route, poll cash_source_status to success, then call Base-USDC cash_cashout with the guaranteed output amount. Never submit the route twice."; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly user: { readonly description: "Source wallet submitting the Relay transaction."; readonly type: "string"; readonly pattern: "^0x[0-9a-fA-F]{40}$"; }; readonly amount: { readonly type: "string"; readonly pattern: "^0*[1-9][0-9]*$"; readonly description: "Base units as a decimal string. For the default path this is USDC 6 decimals; with source it is source-token base units."; }; readonly source: { readonly type: "object"; readonly properties: { readonly chainId: { readonly description: "Relay-supported EVM source chain id."; readonly type: "integer"; readonly minimum: 1; readonly maximum: number; }; readonly currency: { readonly description: "Source token/native address."; readonly type: "string"; readonly pattern: "^0x[0-9a-fA-F]{40}$"; }; }; readonly required: readonly ["chainId", "currency"]; readonly additionalProperties: false; }; readonly recipient: { readonly description: "Base recipient for Relay-delivered USDC. Defaults to user."; readonly type: "string"; readonly pattern: "^0x[0-9a-fA-F]{40}$"; }; readonly tradeType: { readonly type: "string"; readonly enum: readonly ["EXACT_INPUT", "EXACT_OUTPUT", "EXPECTED_OUTPUT"]; readonly description: "Relay quote trade type. Defaults to EXACT_INPUT."; }; }; readonly required: readonly ["user", "amount", "source"]; readonly additionalProperties: false; }; }, { readonly name: "cash_near_intents_quote"; readonly description: "Quote a NEAR Intents 1Click external-deposit route into canonical Base USDC. Persist the returned depositAddress, optional depositMemo, signed quote, and deadline before sending source funds. The host must fund that origin-chain address itself; this tool never signs or broadcasts the source transfer."; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly sourceAsset: { readonly type: "string"; readonly description: "NEAR Intents asset id from cash_capabilities, e.g. nep141:zec.omft.near."; }; readonly amount: { readonly description: "Base units: source units for EXACT_INPUT or canonical Base USDC units for EXACT_OUTPUT."; readonly type: "string"; readonly pattern: "^0*[1-9][0-9]*$"; }; readonly recipient: { readonly description: "Base address that will receive canonical USDC."; readonly type: "string"; readonly pattern: "^0x[0-9a-fA-F]{40}$"; }; readonly refundTo: { readonly type: "string"; readonly description: "Refund address on the source chain."; }; readonly tradeType: { readonly type: "string"; readonly enum: readonly ["EXACT_INPUT", "EXACT_OUTPUT"]; }; readonly deadline: { readonly type: "string"; readonly format: "date-time"; readonly description: "Quote deadline as an ISO timestamp."; }; readonly slippageTolerance: { readonly type: "integer"; readonly minimum: 0; readonly maximum: 10000; readonly description: "Basis points; defaults to 100 (1%)."; }; readonly dry: { readonly type: "boolean"; readonly description: "Simulation only. A dry quote has no deposit address."; }; }; readonly required: readonly ["sourceAsset", "amount", "recipient", "refundTo", "tradeType", "deadline"]; readonly additionalProperties: false; }; }, { readonly name: "cash_near_intents_submit"; readonly description: "Optionally notify NEAR Intents of an already-broadcast origin transaction so deposit detection starts sooner. Retrying this notification is safe; never resend source funds because notification failed."; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly depositAddress: { readonly type: "string"; readonly description: "Deposit address from the signed quote."; }; readonly depositMemo: { readonly type: "string"; readonly description: "Optional memo from the signed quote."; }; readonly txHash: { readonly type: "string"; readonly description: "Already-broadcast origin-chain transaction hash."; }; }; readonly required: readonly ["depositAddress", "txHash"]; readonly additionalProperties: false; }; }, { readonly name: "cash_near_intents_status"; readonly description: "Track a NEAR Intents route by the exact depositAddress and optional depositMemo returned by its signed quote. Persist transaction evidence and wait for SUCCESS before creating the Base-USDC cash-out; never reuse an expired route."; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly depositAddress: { readonly type: "string"; readonly description: "Deposit address from the signed quote."; }; readonly depositMemo: { readonly type: "string"; readonly description: "Optional memo from the signed quote."; }; readonly expectedQuote: { readonly type: "object"; readonly description: "Exact serialized result from cash_near_intents_quote; used to reject status for a different route identity."; readonly additionalProperties: true; }; }; readonly required: readonly ["depositAddress", "expectedQuote"]; readonly additionalProperties: false; }; }, { readonly name: "cash_estimate"; readonly description: "Estimate fiat received at the corridor market rate, including whether it binds at intent signal or deposit creation, plus 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."; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly amount: { readonly type: "string"; readonly pattern: "^0*[1-9][0-9]*$"; readonly description: "Base units as a decimal string. For the default path this is USDC 6 decimals; with source it is source-token base units."; }; readonly currency: { readonly type: "string"; readonly description: "Fiat currency code from cash_capabilities, e.g. \"USD\""; }; readonly platform: { readonly type: "string"; readonly description: "Optional payout platform for platform-specific ETA sampling."; }; readonly source: { readonly type: "object"; readonly description: "Optional Relay EVM source asset. Omit for the Base USDC default path."; readonly properties: { readonly chainId: { readonly description: "Relay-supported EVM source chain id."; readonly type: "integer"; readonly minimum: 1; readonly maximum: number; }; readonly currency: { readonly description: "Source token/native address."; readonly type: "string"; readonly pattern: "^0x[0-9a-fA-F]{40}$"; }; readonly user: { readonly description: "Source wallet submitting the Relay transaction."; readonly type: "string"; readonly pattern: "^0x[0-9a-fA-F]{40}$"; }; readonly recipient: { readonly description: "Base recipient for Relay-delivered USDC. Defaults to user."; readonly type: "string"; readonly pattern: "^0x[0-9a-fA-F]{40}$"; }; readonly tradeType: { readonly type: "string"; readonly enum: readonly ["EXACT_INPUT", "EXACT_OUTPUT", "EXPECTED_OUTPUT"]; }; }; readonly required: readonly ["chainId", "currency", "user"]; readonly additionalProperties: false; }; }; readonly required: readonly ["amount", "currency"]; readonly additionalProperties: false; }; }, { readonly name: "cash_fill_stats"; readonly description: "Read raw 30-day demand and first-fill speed evidence for every observed platform:currency pair. Consumers should apply their own threshold and fail open to cash_capabilities when stats are unavailable or filtering would empty the catalog."; readonly inputSchema: { readonly type: "object"; readonly properties: {}; readonly additionalProperties: false; }; }, { readonly name: "cash_cashout"; readonly description: "Start a Base-USDC cash-out using the custody-separated prepare path. Returns UNSIGNED transactions plus same-index steps [approve, createDeposit]; signing and ordered submission stay host-side. If any payout leg is Venmo or PayPal, accessPolicyPaymentMethods lists every method-scoped Peer Pay policy required after createDeposit confirms. Cash App is non-chargebackable, stays public, and does not require stake. The host adapter must call CashClient.finalizePreparedCashout(receipt), then prepare and confirm CashClient.prepareAccessPolicy(depositId, paymentMethod) for each listed method with the depositor. These receipt/signing methods are not separate built-in tools. For another source asset, complete cash_source_quote and cash_source_status first, then pass the guaranteed Base USDC output amount here."; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly amount: { readonly type: "string"; readonly pattern: "^0*[1-9][0-9]*$"; readonly description: "Base units as a decimal string. For the default path this is USDC 6 decimals; with source it is source-token base units."; }; readonly receive: { readonly description: "Where the fiat should arrive: one payout leg, or an array of legs to offer several platforms (each platform at most once; consult cash_capabilities for each corridor binding point)"; readonly oneOf: readonly [{ readonly type: "object"; readonly description: "One payout leg: platform + currency choice + payee"; readonly properties: { readonly platform: { readonly type: "string"; readonly description: "Platform id from cash_capabilities, e.g. \"venmo\""; }; readonly currency: { readonly type: "string"; readonly description: "Fiat currency code, e.g. \"USD\""; }; readonly currencies: { readonly type: "array"; readonly minItems: 1; readonly uniqueItems: true; readonly items: { readonly type: "string"; }; readonly description: "Fiat currency choices for one payment method, e.g. [\"EUR\", \"GBP\"]"; }; readonly payee: { readonly description: "Raw payee handle or structured curator payee data"; readonly oneOf: readonly [{ readonly type: "string"; readonly description: "User-entered handle, e.g. \"@andrew\" for Venmo; Peer Cash normalizes it for the selected platform"; }, { readonly type: "object"; readonly properties: { readonly offchainId: { readonly type: "string"; readonly description: "Already-normalized handle for the platform"; }; }; readonly required: readonly ["offchainId"]; readonly additionalProperties: true; }]; }; }; readonly required: readonly ["platform", "payee"]; readonly oneOf: readonly [{ readonly required: readonly ["currency"]; }, { readonly required: readonly ["currencies"]; }]; readonly additionalProperties: false; }, { readonly type: "array"; readonly minItems: 1; readonly items: { readonly type: "object"; readonly description: "One payout leg: platform + currency choice + payee"; readonly properties: { readonly platform: { readonly type: "string"; readonly description: "Platform id from cash_capabilities, e.g. \"venmo\""; }; readonly currency: { readonly type: "string"; readonly description: "Fiat currency code, e.g. \"USD\""; }; readonly currencies: { readonly type: "array"; readonly minItems: 1; readonly uniqueItems: true; readonly items: { readonly type: "string"; }; readonly description: "Fiat currency choices for one payment method, e.g. [\"EUR\", \"GBP\"]"; }; readonly payee: { readonly description: "Raw payee handle or structured curator payee data"; readonly oneOf: readonly [{ readonly type: "string"; readonly description: "User-entered handle, e.g. \"@andrew\" for Venmo; Peer Cash normalizes it for the selected platform"; }, { readonly type: "object"; readonly properties: { readonly offchainId: { readonly type: "string"; readonly description: "Already-normalized handle for the platform"; }; }; readonly required: readonly ["offchainId"]; readonly additionalProperties: true; }]; }; }; readonly required: readonly ["platform", "payee"]; readonly oneOf: readonly [{ readonly required: readonly ["currency"]; }, { readonly required: readonly ["currencies"]; }]; readonly additionalProperties: false; }; readonly description: "Multiple payout legs across different platforms"; }]; }; }; readonly required: readonly ["amount", "receive"]; readonly additionalProperties: false; }; }, { readonly name: "cash_order"; readonly 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."; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly depositId: { readonly type: "string"; readonly pattern: "^0x[0-9a-fA-F]{40}_[0-9]+$"; readonly description: "Composite deposit id (escrow_onchainId) returned by cash_cashout - the resume key"; }; }; readonly required: readonly ["depositId"]; readonly additionalProperties: false; }; }, { readonly name: "cash_orders"; readonly 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."; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly owner: { readonly description: "The maker wallet address (0x...)"; readonly type: "string"; readonly pattern: "^0x[0-9a-fA-F]{40}$"; }; readonly inFlight: { readonly type: "boolean"; readonly description: "Only awaiting-buyer / matched / delivering orders"; }; readonly limit: { readonly type: "integer"; readonly minimum: 1; readonly maximum: 1000; readonly description: "Max deposits to scan (default 100)"; }; }; readonly required: readonly ["owner"]; readonly additionalProperties: false; }; }, { readonly name: "cash_buyer"; readonly 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?\"."; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly address: { readonly description: "The buyer (taker) wallet address (0x...)"; readonly type: "string"; readonly pattern: "^0x[0-9a-fA-F]{40}$"; }; }; readonly required: readonly ["address"]; readonly additionalProperties: false; }; }, { readonly name: "cash_source_status"; readonly description: "Read Relay request status through the Relay SDK request utility using the requestId returned from cash_source_quote or Relay execution progress."; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly requestId: { readonly type: "string"; readonly description: "Relay request id."; }; }; readonly required: readonly ["requestId"]; readonly additionalProperties: false; }; }, { readonly name: "cash_withdraw"; readonly 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)."; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly depositId: { readonly type: "string"; readonly pattern: "^0x[0-9a-fA-F]{40}_[0-9]+$"; readonly description: "Composite deposit id (escrow_onchainId) returned by cash_cashout - the resume key"; }; readonly amount: { readonly description: "Optional partial amount (USDC base units, decimal string). Omit to close the order fully."; readonly type: "string"; readonly pattern: "^0*[1-9][0-9]*$"; }; }; readonly required: readonly ["depositId"]; readonly additionalProperties: false; }; }, { readonly name: "cash_topup"; readonly 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."; readonly inputSchema: { readonly type: "object"; readonly properties: { readonly depositId: { readonly type: "string"; readonly pattern: "^0x[0-9a-fA-F]{40}_[0-9]+$"; readonly description: "Composite deposit id (escrow_onchainId) returned by cash_cashout - the resume key"; }; readonly amount: { readonly type: "string"; readonly pattern: "^0*[1-9][0-9]*$"; readonly description: "Base units as a decimal string. For the default path this is USDC 6 decimals; with source it is source-token base units."; }; }; readonly required: readonly ["depositId", "amount"]; readonly additionalProperties: false; }; }]; /** Literal names shipped by this package. Use this for exhaustive built-in dispatch. */ type BuiltInCashToolName = (typeof builtInCashTools)[number]['name']; /** * Mutable tool registry for hosts that append their own definitions. * * This was part of the 0.1.x public contract: keep the element name open as a * string rather than narrowing consumers to only the built-in verbs. */ declare const cashTools: CashToolDefinition[]; /** Manifest wrapper with versioning for host registries. */ declare const cashToolManifest: { readonly name: "@zkp2p/cash"; readonly version: string; readonly description: "Peer Cash - offramp-only: route Relay EVM or NEAR Intents external-deposit source assets to Base USDC, then cash out to fiat at a zero-spread Chainlink market rate. Mutating protocol tools return unsigned transactions plus step labels with ERC-8021 peer-cash attribution."; readonly tools: CashToolDefinition[]; }; /** Tool names accepted by an extensible host registry, including custom tools. */ type CashToolName = string; export { type BuiltInCashToolName, type CashToolDefinition, type CashToolName, cashToolManifest, cashTools };