@quackai/q402-mcp 0.8.18 → 0.8.19

package/README.md

@@ -156,7 +156,7 @@ Then export the values in `~/.zshrc` / `~/.bashrc`. See the [Codex config refere
 
 ## Tools exposed
 
-**20 tools** — read-only by default; live mode needs an API key + signing path + `Q402_ENABLE_REAL_PAYMENTS=1`.
+**24 tools** — read-only by default; live mode needs an API key + signing path + `Q402_ENABLE_REAL_PAYMENTS=1`.
 
 | Tool | Auth | Purpose |
 |---|---|---|
@@ -180,8 +180,12 @@ Then export the values in `~/.zshrc` / `~/.bashrc`. See the [Codex config refere
 | `q402_bridge_send` | live mode | Execute a CCIP bridge from the user's Agent Wallet. Mode C only (server-managed). Sandbox-by-default; `sandbox: false` + live Multichain key + `Q402_ENABLE_REAL_PAYMENTS=1` fires a real on-chain bridge. |
 | `q402_bridge_history` | not yet wired | Pointer to the dashboard. Returns `{ implemented: false, dashboardUrl, dashboardPath }` — read-only guidance until owner-sig auth lands in MCP. |
 | `q402_bridge_gas_tank` | not yet wired | Static guidance + dashboard pointer for the Bridge Gas Tank top-up flow. Live balance lookup needs owner-sig auth (dashboard for now). |
+| `q402_yield_reserves` | none | List Q402 Yield (Aave V3) lending markets — protocol, chain, asset, market address, supply APY. BNB Chain only today. |
+| `q402_yield_positions` | api key | Show the Agent Wallet's open Q402 Yield positions (balance, principal, accrued interest, APY) + total supplied in USD. Mode C. |
+| `q402_yield_deposit` | live mode | Supply the Agent Wallet's USDC/USDT into Aave V3 (Q402 Yield) to earn supply APY. Mode C, BNB-only. Requires `confirm: true`; sandbox-by-default. |
+| `q402_yield_withdraw` | live mode | Withdraw supplied USDC/USDT out of Aave V3 back to the Agent Wallet (`amount: "max"` = full position). Mode C, BNB-only. Requires `confirm: true`; sandbox-by-default. |
 
-`q402_pay` + `q402_batch_pay` + `q402_bridge_send` require explicit in-chat confirmation. Batch confirmation = full batch, not per-row.
+`q402_pay` + `q402_batch_pay` + `q402_bridge_send` + `q402_yield_deposit` + `q402_yield_withdraw` require explicit in-chat confirmation. Batch confirmation = full batch, not per-row.
 
 > ℹ️ `q402_pay` expects a 0x address — ENS isn't resolved server-side. Resolve client-side first.
 > Per-chain Gas Tank balances + full TX history live in the [dashboard](https://q402.quackai.ai/dashboard) (wallet-signature only).

package/dist/index.js

@@ -212,7 +212,7 @@ var isValidPrivateKey = (s) => typeof s === "string" && PRIVATE_KEY_RE.test(s);
 // package.json
 var package_default = {
   name: "@quackai/q402-mcp",
-  version: "0.8.18",
+  version: "0.8.19",
   description: "MCP server for Q402 \u2014 gasless USDC/USDT/RLUSD payments on 10 EVM chains + Chainlink CCIP USDC bridge on the eth/avax/arbitrum triangle, callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.",
   mcpName: "io.github.bitgett/q402-mcp",
   keywords: [
@@ -3480,7 +3480,10 @@ async function runYieldPositions(input) {
     };
   }
   const positions = data.positions ?? [];
-  const summary = positions.length ? `Total supplied: $${(data.totalSuppliedUsd ?? 0).toFixed(2)} across ${positions.length} position(s).` : "No open Q402 Yield positions for this wallet.";
+  const unavailableChains = Array.isArray(data.unavailableChains) ? data.unavailableChains : [];
+  const hasUnavailable = data.unavailable === true || unavailableChains.length > 0;
+  const unavailableNote = hasUnavailable ? ` Some chains could not be read this cycle${unavailableChains.length ? ` (${unavailableChains.join(", ")})` : ""} \u2014 this snapshot may be incomplete; retry before treating a balance as zero.` : "";
+  const summary = positions.length ? `Total supplied: $${(data.totalSuppliedUsd ?? 0).toFixed(2)} across ${positions.length} position(s).${unavailableNote}` : hasUnavailable ? `No positions returned, but a read failure occurred${unavailableChains.length ? ` on ${unavailableChains.join(", ")}` : ""} \u2014 this is NOT a confirmed empty position; retry.` : "No open Q402 Yield positions for this wallet.";
   return {
     content: [
       { type: "text", text: summary },
@@ -3493,7 +3496,9 @@ async function runYieldPositions(input) {
             supplyApyPct: Math.round(p.supplyApy * 100 * 100) / 100
           })),
           totalSuppliedUsd: data.totalSuppliedUsd ?? null,
-          asOf: data.asOf ?? null
+          asOf: data.asOf ?? null,
+          unavailable: hasUnavailable,
+          unavailableChains
         }, null, 2)
       }
     ]
@@ -3501,7 +3506,7 @@ async function runYieldPositions(input) {
 }
 
 // src/tools/yield-deposit.ts
-import { id } from "ethers";
+import { hexlify as hexlify2, randomBytes as randomBytes2 } from "ethers";
 import { z as z16 } from "zod";
 var YieldDepositInputSchema = z16.object({
   chain: z16.enum(["bnb"]).default("bnb").describe("Chain the Aave market lives on. Q402 Yield is BNB-only today \u2014 only 'bnb' is accepted."),
@@ -3511,7 +3516,7 @@ var YieldDepositInputSchema = z16.object({
     "Optional Agent Wallet address to supply from (max 10 per owner). Omit to use Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet (resolved server-side from the API key)."
   ),
   idempotencyKey: z16.string().optional().describe(
-    "Optional durable idempotency key for this logical deposit. When omitted the tool derives a STABLE key from (walletId, chain, token, amount) so a lost response can be safely retried without double-supplying. Pass your own only if you need two genuinely distinct same-amount deposits to be treated separately."
+    "Optional durable idempotency key for this logical deposit. When omitted the tool generates a FRESH random key per invocation, so each call executes a distinct deposit (two intentional same-amount deposits both run, and a re-deposit after a withdrawal is NOT replayed). Pass your own STABLE key only when you want retry-safety: re-calling with the same key replays the first result instead of double-supplying."
   ),
   confirm: z16.boolean().optional().describe(
     "MUST be true to actually supply funds. Set this only after the user has explicitly approved this exact deposit (amount, token, chain, wallet) in the conversation. When omitted or false the tool previews the action and does NOT move any funds."
@@ -3543,7 +3548,7 @@ var YIELD_DEPOSIT_TOOL = {
       },
       idempotencyKey: {
         type: "string",
-        description: "Optional durable idempotency key. Omit and the tool derives a stable key from (walletId, chain, token, amount) so a lost response is safe to retry without double-supplying. Pass your own only to force two same-amount deposits apart."
+        description: "Optional durable idempotency key. Omit and the tool generates a FRESH random key per invocation, so every call executes a distinct deposit. Pass your own STABLE key only for opt-in retry-safety \u2014 re-calling with the same key replays the first result instead of double-supplying."
       },
       confirm: {
         type: "boolean",
@@ -3565,7 +3570,7 @@ async function runYieldDeposit(input) {
     };
   }
   const walletId = typeof input.walletId === "string" && input.walletId.length > 0 ? input.walletId.toLowerCase() : CONFIG.walletId ?? void 0;
-  const idempotencyKey = typeof input.idempotencyKey === "string" && input.idempotencyKey.length > 0 ? input.idempotencyKey : id(`yield:supply:${walletId ?? "default"}:${input.chain}:${input.token}:${input.amount}`);
+  const idempotencyKey = typeof input.idempotencyKey === "string" && input.idempotencyKey.length > 0 ? input.idempotencyKey : hexlify2(randomBytes2(32));
   if (input.confirm !== true) {
     const walletDesc = walletId ? `wallet ${walletId}` : "your default Agent Wallet";
     return {
@@ -3651,7 +3656,7 @@ async function runYieldDeposit(input) {
 }
 
 // src/tools/yield-withdraw.ts
-import { id as id2 } from "ethers";
+import { hexlify as hexlify3, randomBytes as randomBytes3 } from "ethers";
 import { z as z17 } from "zod";
 var YieldWithdrawInputSchema = z17.object({
   chain: z17.enum(["bnb"]).default("bnb").describe("Chain the Aave market lives on. Q402 Yield is BNB-only today \u2014 only 'bnb' is accepted."),
@@ -3661,7 +3666,7 @@ var YieldWithdrawInputSchema = z17.object({
     "Optional Agent Wallet address to withdraw to (max 10 per owner). Omit to use Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet (resolved server-side from the API key)."
   ),
   idempotencyKey: z17.string().optional().describe(
-    "Optional durable idempotency key for this logical withdrawal. When omitted the tool derives a STABLE key from (walletId, chain, token, amount) so a lost response can be safely retried without double-withdrawing. Pass your own only if you need two genuinely distinct same-amount withdrawals to be treated separately."
+    "Optional durable idempotency key for this logical withdrawal. When omitted the tool generates a FRESH random key per invocation, so each call executes a distinct withdrawal (a re-deposit followed by another `withdraw max` is NOT replayed). Pass your own STABLE key only when you want retry-safety: re-calling with the same key replays the first result instead of double-withdrawing."
   ),
   confirm: z17.boolean().optional().describe(
     "MUST be true to actually withdraw funds. Set this only after the user has explicitly approved this exact withdrawal (amount, token, chain, wallet) in the conversation. When omitted or false the tool previews the action and does NOT move any funds."
@@ -3693,7 +3698,7 @@ var YIELD_WITHDRAW_TOOL = {
       },
       idempotencyKey: {
         type: "string",
-        description: "Optional durable idempotency key. Omit and the tool derives a stable key from (walletId, chain, token, amount) so a lost response is safe to retry without double-withdrawing. Pass your own only to force two same-amount withdrawals apart."
+        description: "Optional durable idempotency key. Omit and the tool generates a FRESH random key per invocation, so every call executes a distinct withdrawal. Pass your own STABLE key only for opt-in retry-safety \u2014 re-calling with the same key replays the first result instead of double-withdrawing."
       },
       confirm: {
         type: "boolean",
@@ -3715,7 +3720,7 @@ async function runYieldWithdraw(input) {
     };
   }
   const walletId = typeof input.walletId === "string" && input.walletId.length > 0 ? input.walletId.toLowerCase() : CONFIG.walletId ?? void 0;
-  const idempotencyKey = typeof input.idempotencyKey === "string" && input.idempotencyKey.length > 0 ? input.idempotencyKey : id2(`yield:withdraw:${walletId ?? "default"}:${input.chain}:${input.token}:${input.amount}`);
+  const idempotencyKey = typeof input.idempotencyKey === "string" && input.idempotencyKey.length > 0 ? input.idempotencyKey : hexlify3(randomBytes3(32));
   const amountDesc = input.amount === "max" ? "the FULL position" : `${input.amount} ${input.token}`;
   if (input.confirm !== true) {
     const walletDesc = walletId ? `wallet ${walletId}` : "your default Agent Wallet";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quackai/q402-mcp",
-  "version": "0.8.18",
+  "version": "0.8.19",
   "description": "MCP server for Q402 — gasless USDC/USDT/RLUSD payments on 10 EVM chains + Chainlink CCIP USDC bridge on the eth/avax/arbitrum triangle, callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.",
   "mcpName": "io.github.bitgett/q402-mcp",
   "keywords": [