@aibtc/mcp-server 1.61.0 → 1.62.1

package/README.md

@@ -99,6 +99,8 @@ npx @aibtc/mcp-server@latest bridge --read-only --list-tools
 npx @aibtc/mcp-server@latest bridge --read-only --allow transfer_stx "send 1 STX to SP3..."
 ```
 
+Before any agent loop runs (and on `--list-tools`), the bridge prints a compact **safety receipt** to stderr — network, read-only mode, exposed/write/blocked tool counts, the session spend cap, and the number of known x402 endpoints — so the configured execution boundaries are visible up front. It reports boundaries only; it never claims any value moved.
+
 The allowlist is re-enforced at execution time, so a model can never call a tool outside the exposed set. Any MCP-capable agent framework (`@openrouter/agent`, OpenAI Agents SDK, Claude Agent SDK) can also point at this server directly — the bridge is for driving it through OpenRouter's raw API without adopting a framework.
 
 ### Testnet Mode

package/dist/bridge/index.js

@@ -29,6 +29,7 @@
  */
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { ALL_ENDPOINTS } from "../endpoints/registry.js";
 const OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions";
 const DEFAULT_MODEL = "anthropic/claude-3.5-haiku";
 /**
@@ -136,6 +137,28 @@ function parseArgs(argv) {
     opts.prompt = promptWords.join(" ").trim();
     return opts;
 }
+/**
+ * Compact safety receipt printed before any agent loop runs (#583). Makes the
+ * configured execution boundaries visible up front so a user can trust the
+ * bridge without digging through flags/config. It reports ONLY configured
+ * boundaries — it never claims that any value moved. Emitted on stderr so it
+ * can't pollute stdout (the final assistant reply / --list-tools piping).
+ */
+function printSafetyReceipt(opts, exposed, totalTools) {
+    const writeToolCount = exposed.filter((t) => !isReadOnly(t.name)).length;
+    const lines = [
+        "aibtc-mcp bridge — safety receipt",
+        `  network=${opts.network}`,
+        `  read_only=${opts.readOnly}`,
+        `  exposed_tools=${exposed.length}/${totalTools}`,
+        `  write_tool_count=${writeToolCount}`,
+        `  blocked_tool_count=${opts.block.size}`,
+        `  session_spend_cap=${opts.maxSpendUstx ?? "default"} uSTX / ${opts.maxSpendSats ?? "default"} sats`,
+        `  x402_endpoints_known=${ALL_ENDPOINTS.length}`,
+        "  (reports configured execution boundaries only; no value has moved)",
+    ];
+    console.error(lines.join("\n"));
+}
 /** Apply read-only + allow + block to the raw MCP tool list. */
 function selectTools(tools, opts) {
     return tools.filter((t) => {
@@ -193,6 +216,7 @@ export async function runBridge(argv) {
     const { tools: allTools } = await client.listTools();
     const exposed = selectTools(allTools, opts);
     if (opts.listTools) {
+        printSafetyReceipt(opts, exposed, allTools.length);
         console.log(`Exposed ${exposed.length}/${allTools.length} tools` +
             (opts.readOnly ? " (read-only)" : "") + ":");
         for (const t of exposed)
@@ -211,12 +235,8 @@ export async function runBridge(argv) {
         await client.close();
         process.exit(1);
     }
-    const writeCount = exposed.filter((t) => !isReadOnly(t.name)).length;
-    console.error(`Bridge: ${exposed.length} tools -> ${opts.model}` +
-        (opts.readOnly ? " [read-only]" : ` [${writeCount} can write/spend]`) +
-        (opts.maxSpendUstx || opts.maxSpendSats
-            ? ` (cap ${opts.maxSpendUstx ?? "-"} uSTX / ${opts.maxSpendSats ?? "-"} sats)`
-            : ""));
+    printSafetyReceipt(opts, exposed, allTools.length);
+    console.error(`  model=${opts.model}, max_turns=${opts.maxTurns}`);
     const openaiTools = exposed.map(toOpenAITool);
     const messages = [
         {

package/dist/tools/dual-stacking.tools.js

@@ -64,13 +64,33 @@ Note: Dual Stacking is only available on mainnet.`,
                 });
             }
             const resolvedAddress = address || (await getWalletAddress());
-            const [enrolledThisCycleRaw, enrolledNextCycleRaw, minimumAmountRaw, aprDataRaw, cycleOverviewRaw,] = await Promise.all([
+            // Use allSettled, not all: `is-enrolled-this-cycle` fails contract-side
+            // on mainnet with RuntimeCheck(AtBlockUnavailable) (it reads historical
+            // block state Hiro has pruned). With Promise.all a single failing read
+            // sinks the whole response, hiding the other 4 useful fields. Recover
+            // per-call and surface a `warnings` array instead. (#554)
+            const warnings = [];
+            const settled = await Promise.allSettled([
                 callDualStackingReadOnly("is-enrolled-this-cycle", [principalCV(resolvedAddress)]),
                 callDualStackingReadOnly("is-enrolled-in-next-cycle", [principalCV(resolvedAddress)]),
                 callDualStackingReadOnly("get-minimum-enrollment-amount", []),
                 callDualStackingReadOnly("get-apr-data", []),
                 callDualStackingReadOnly("current-overview-data", []),
             ]);
+            const readNames = [
+                "is-enrolled-this-cycle",
+                "is-enrolled-in-next-cycle",
+                "get-minimum-enrollment-amount",
+                "get-apr-data",
+                "current-overview-data",
+            ];
+            const values = settled.map((r, i) => {
+                if (r.status === "fulfilled")
+                    return r.value;
+                warnings.push(`${readNames[i]}: ${r.reason instanceof Error ? r.reason.message : String(r.reason)}`);
+                return null;
+            });
+            const [enrolledThisCycleRaw, enrolledNextCycleRaw, minimumAmountRaw, aprDataRaw, cycleOverviewRaw,] = values;
             // Parse APR data — returns {min-apr: uint, max-apr: uint} divided by 1_000_000 for %
             let apr = {
                 minApr: 0,
@@ -107,10 +127,11 @@ Note: Dual Stacking is only available on mainnet.`,
                 const raw = minimumAmountRaw;
                 minimumEnrollmentSats = raw.value !== undefined ? Number(raw.value) : 0;
             }
-            // Parse boolean enrollment flags
+            // Parse boolean enrollment flags. A failed read stays null (unknown)
+            // rather than collapsing to a misleading `false`.
             const parseBoolean = (raw) => {
                 if (raw === null || raw === undefined)
-                    return false;
+                    return null;
                 if (typeof raw === "boolean")
                     return raw;
                 const obj = raw;
@@ -126,6 +147,7 @@ Note: Dual Stacking is only available on mainnet.`,
                 minimumEnrollmentSats,
                 apr,
                 cycleOverview,
+                ...(warnings.length > 0 && { warnings }),
             });
         }
         catch (error) {

package/dist/tools/inbox.tools.js

@@ -1,192 +1,26 @@
 import { z } from "zod";
-import { makeContractCall, uintCV, principalCV, noneCV, someCV, bufferCV, } from "@stacks/transactions";
-import { decodePaymentRequired, decodePaymentResponse, encodePaymentPayload, generatePaymentId, buildPaymentIdentifierExtension, X402_HEADERS } from "../utils/x402-protocol.js";
-import { getAccount, NETWORK } from "../services/x402.service.js";
-import { getSbtcService } from "../services/sbtc.service.js";
-import { getStacksNetwork, getExplorerTxUrl } from "../config/networks.js";
-import { getContracts, parseContractId } from "../config/contracts.js";
-import { createFungiblePostCondition } from "../transactions/post-conditions.js";
-import { createJsonResponse, createErrorResponse } from "../utils/index.js";
-import { InsufficientBalanceError } from "../utils/errors.js";
-import { formatSbtc } from "../utils/formatting.js";
-import { getHiroApi } from "../services/hiro-api.js";
-import { extractPaymentIdFromPaymentSignature, extractTxidFromPaymentSignature, pollTransactionConfirmation, } from "../utils/x402-recovery.js";
-import { classifyCanonicalPaymentStatus, extractCanonicalPaymentHints, formatCanonicalPaymentStatus, normalizeCallerFacingStatus, resolveCanonicalPaymentStatus, } from "../utils/x402-payment-state.js";
-import { emitCanonicalPaymentDecisionLogs, emitCanonicalPaymentPollLogs, emitPaymentLog, } from "../utils/x402-payment-logging.js";
-const INBOX_BASE = "https://aibtc.com/api/inbox";
-// Deprecation switch for the sponsored relay send. The full implementation is
-// retained below but gated off behind this flag — the relay-sponsored path was
-// unstable, so all inbox sends go through send_inbox_message_direct. Flip to
-// `false` to re-enable. Typed as `boolean` (not a literal) so TypeScript keeps
-// type-checking the retained handler body instead of treating it as dead code.
-const SPONSORED_INBOX_DISABLED = true;
+import { createJsonResponse } from "../utils/index.js";
 // ============================================================================
-// Nonce Manager (delegated to SharedNonceTracker — issue #413)
+// send_inbox_message — DEPRECATED redirect
 //
-// All nonce tracking is now handled by the shared tracker, which persists to
-// ~/.aibtc/nonce-state.json and is shared across MCP tools and CLI skills.
-// ============================================================================
-import { getTrackedNonce, recordNonceUsed, reconcileWithChain, } from "../services/nonce-tracker.js";
-/**
- * Compute the next safe nonce for a sender address.
- *
- * Always fetches chain state and reconciles with the shared tracker,
- * consistent with the builder path (both take max of local vs chain).
- */
-async function getNextNonce(address) {
-    // 1. Check shared tracker (fast, no network)
-    const localNext = await getTrackedNonce(address);
-    // 2. Fetch chain state for reconciliation
-    const hiroApi = getHiroApi(NETWORK);
-    const accountInfo = await hiroApi.getAccountInfo(address);
-    const confirmedNonce = accountInfo.nonce;
-    // The mempool scan is what makes the nonce safe against pending txs —
-    // silently skipping it on failure risks a nonce collision, so let it fail.
-    let highestMempoolNonce = -1;
-    const mempool = await hiroApi.getMempoolTransactions({
-        sender_address: address,
-        limit: 50,
-    });
-    for (const tx of mempool.results) {
-        if (tx.nonce > highestMempoolNonce) {
-            highestMempoolNonce = tx.nonce;
-        }
-    }
-    const chainNext = Math.max(confirmedNonce, highestMempoolNonce + 1);
-    // 3. Reconcile tracker with chain state
-    await reconcileWithChain(address, chainNext);
-    // 4. Return max(chain, local) — same logic as builder path
-    return Math.max(chainNext, localNext ?? 0);
-}
-/**
- * Record that we used a nonce for an address so subsequent calls use a higher value.
- */
-async function advanceNonceCache(address, usedNonce, txid = "") {
-    await recordNonceUsed(address, usedNonce, txid);
-}
-// ============================================================================
-// Transaction Builder
-// ============================================================================
-/**
- * Build a sponsored sBTC transfer transaction (signed, not broadcast).
- * The inbox API handles settlement via the x402 relay.
- * Explicit nonce avoids ConflictingNonceInMempool; optional memo (max 34 bytes)
- * can be used for on-chain labeling.
- */
-async function buildSponsoredSbtcTransfer(senderKey, senderAddress, recipient, amount, nonce, memo) {
-    const contracts = getContracts(NETWORK);
-    const { address: contractAddress, name: contractName } = parseContractId(contracts.SBTC_TOKEN);
-    const networkName = getStacksNetwork(NETWORK);
-    const postCondition = createFungiblePostCondition(senderAddress, contracts.SBTC_TOKEN, "sbtc-token", "eq", amount);
-    // Encode memo as (optional (buff 34)): some(buff) if provided, none() otherwise.
-    const memoArg = memo
-        ? someCV(bufferCV(Buffer.from(memo).slice(0, 34)))
-        : noneCV();
-    const transaction = await makeContractCall({
-        contractAddress,
-        contractName,
-        functionName: "transfer",
-        functionArgs: [
-            uintCV(amount),
-            principalCV(senderAddress),
-            principalCV(recipient),
-            memoArg,
-        ],
-        senderKey,
-        network: networkName,
-        postConditions: [postCondition],
-        sponsored: true,
-        fee: 0n,
-        nonce,
-    });
-    // serialize() returns Hex string (no 0x prefix) in @stacks/transactions v7+
-    return "0x" + transaction.serialize();
-}
-/** Default delay when no retryAfter hint is provided. */
-const DEFAULT_RETRY_DELAY_MS = 2_000;
-/** Cap retryAfter to avoid blocking too long (seconds). */
-const MAX_RETRY_AFTER_CAP_S = 60;
-/**
- * Classify a response as retryable and extract retry timing.
- */
-function classifyLegacyRetryableError(status, body) {
-    const NOT_RETRYABLE = { retryable: false, delayMs: 0, relaySideConflict: false };
-    // Duplicate-message 409 from the inbox API must NOT be retried —
-    // the message was already delivered and retrying would re-pay.
-    if (status === 409) {
-        const bodyStr = typeof body === "string" ? body : JSON.stringify(body);
-        if (/already exists|duplicate/i.test(bodyStr)) {
-            return NOT_RETRYABLE;
-        }
-    }
-    if (typeof body === "object" && body !== null) {
-        const b = body;
-        // Parse relay's retryAfter hint (seconds → ms), capped.
-        const rawRetryAfter = typeof b["retryAfter"] === "number" ? b["retryAfter"] : 0;
-        const retryAfterMs = rawRetryAfter > 0
-            ? Math.min(rawRetryAfter, MAX_RETRY_AFTER_CAP_S) * 1000
-            : DEFAULT_RETRY_DELAY_MS;
-        // Relay returns retryable: true for SETTLEMENT_BROADCAST_FAILED (issue #157)
-        if (b["retryable"] === true) {
-            return { retryable: true, delayMs: retryAfterMs, relaySideConflict: false };
-        }
-        // Relay returns HTTP 409 with code: "NONCE_CONFLICT" — relay-side conflict,
-        // safe to resubmit the same transaction for dedup.
-        if (status === 409 && b["code"] === "NONCE_CONFLICT") {
-            return { retryable: true, delayMs: retryAfterMs, relaySideConflict: true };
-        }
-    }
-    // Sender-side nonce conflict from the Stacks node (not relay) — needs fresh tx.
-    if (typeof body === "string") {
-        if (body.includes("ConflictingNonceInMempool") || body.includes("BadNonce")) {
-            return { retryable: true, delayMs: DEFAULT_RETRY_DELAY_MS, relaySideConflict: false };
-        }
-    }
-    return NOT_RETRYABLE;
-}
-function getInboxPaymentStatusUrl(paymentId) {
-    const inboxBaseUrl = new URL(INBOX_BASE);
-    return `${inboxBaseUrl.origin}/api/payment-status/${paymentId}`;
-}
-/**
- * Sleep for ms milliseconds.
- */
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-/**
- * POST a message to the inbox using a confirmed txid as payment proof.
- * Returns a structured result so callers can decide how to handle failure
- * (manual recovery throws, auto-recovery tries the next txid).
- */
-async function submitWithPaymentTxid(recipientBtcAddress, recipientStxAddress, content, txid) {
-    const url = `${INBOX_BASE}/${recipientBtcAddress}`;
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-            toBtcAddress: recipientBtcAddress,
-            toStxAddress: recipientStxAddress,
-            content,
-            paymentTxid: txid,
-        }),
-    });
-    const body = await res.text();
-    const ok = res.status === 200 || res.status === 201 || res.status === 409;
-    return { ok, status: res.status, body };
-}
-// ============================================================================
-// Tool Registration
+// The sponsored (relay) inbox send has been removed. The relay-sponsored path
+// was unstable: a burst of sends with an uninitialized local nonce could wedge
+// the relay's sponsor queue (nonces stuck `held(gap)`), leaving payments
+// accepted but messages undelivered (issue #540/#592). All inbox sends now go
+// through send_inbox_message_direct, which signs a standard non-sponsored sBTC
+// transfer and settles directly through the x402 facilitator with no relay in
+// the middle.
+//
+// This tool is retained only as a redirect so existing agents that still call
+// send_inbox_message get pointed to the working tool instead of an
+// "unknown tool" error.
 // ============================================================================
 export function registerInboxTools(server) {
     server.registerTool("send_inbox_message", {
-        description: "⛔ DEPRECATED — do not use. This sponsored (relay) inbox send no longer executes; it returns " +
-            "a redirect to send_inbox_message_direct.\n\n" +
+        description: "⛔ DEPRECATED — do not use. The sponsored (relay) inbox send has been removed. " +
             "Use send_inbox_message_direct instead. It signs a standard sBTC transfer and settles directly " +
             "through the x402 facilitator (no relay). Requires an unlocked wallet holding sBTC (message cost) " +
-            "and STX (gas). Mainnet only.\n\n" +
-            "The sponsored implementation below is retained but gated off behind a deprecation guard — the " +
-            "relay-sponsored path was unstable, so it is disabled rather than removed.",
+            "and STX (gas). Mainnet only.",
         inputSchema: {
             recipientBtcAddress: z
                 .string()
@@ -198,395 +32,18 @@ export function registerInboxTools(server) {
                 .string()
                 .max(500)
                 .describe("Message content (max 500 characters)"),
-            paymentTxid: z
-                .string()
-                .optional()
-                .describe("Optional: a confirmed on-chain sBTC transfer txid to use as payment proof. " +
-                "When provided, skips the x402 payment flow and resubmits the message directly. " +
-                "Use for manual recovery after a settlement timeout left the payment confirmed but the message undelivered."),
         },
-    }, async ({ recipientBtcAddress, recipientStxAddress, content, paymentTxid }) => {
-        // Deprecation guard: the sponsored relay path is disabled (see
-        // SPONSORED_INBOX_DISABLED). The full implementation below is kept intact
-        // and can be re-enabled by flipping that flag — relay-sponsored sends were
-        // unstable, so all inbox sends go through send_inbox_message_direct.
-        if (SPONSORED_INBOX_DISABLED) {
-            return createJsonResponse({
-                success: false,
-                deprecated: true,
-                error: "send_inbox_message is deprecated and no longer sends. The sponsored relay path " +
-                    "is disabled because relay-sponsored transactions were unstable.",
-                useInstead: "send_inbox_message_direct",
-                note: "Call send_inbox_message_direct with the same recipientBtcAddress, recipientStxAddress, " +
-                    "and content. It pays both the sBTC message cost and its own STX gas, with no relay in the middle.",
-            });
-        }
-        try {
-            // Network mismatch guard: fail early if testnet MCP server targets mainnet inbox.
-            // Match the parsed hostname exactly (not a substring) so lookalike hosts can't pass.
-            if (NETWORK === "testnet" && new URL(INBOX_BASE).hostname === "aibtc.com") {
-                throw new Error("Network mismatch: MCP server is configured for testnet but the inbox service at aibtc.com requires mainnet. " +
-                    "Set NETWORK=mainnet or use a testnet inbox endpoint.");
-            }
-            const account = await getAccount();
-            // Manual recovery: skip x402 flow and POST with the provided txid as proof
-            if (paymentTxid) {
-                const result = await submitWithPaymentTxid(recipientBtcAddress, recipientStxAddress, content, paymentTxid);
-                if (!result.ok) {
-                    throw new Error(`paymentTxid recovery failed (${result.status}): ${result.body}`);
-                }
-                return createJsonResponse({
-                    success: true,
-                    message: result.status === 409
-                        ? "Message already delivered"
-                        : "Message delivered (manual txid recovery)",
-                    recipient: {
-                        btcAddress: recipientBtcAddress,
-                        stxAddress: recipientStxAddress,
-                    },
-                    contentLength: content.length,
-                    payment: {
-                        txid: paymentTxid,
-                        recovered: true,
-                        explorer: getExplorerTxUrl(paymentTxid, NETWORK),
-                    },
-                });
-            }
-            // Step 1: POST without payment → get 402 challenge
-            const inboxUrl = `${INBOX_BASE}/${recipientBtcAddress}`;
-            const body = {
-                toBtcAddress: recipientBtcAddress,
-                toStxAddress: recipientStxAddress,
-                content,
-            };
-            const initialRes = await fetch(inboxUrl, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify(body),
-            });
-            if (initialRes.status !== 402) {
-                const text = await initialRes.text();
-                if (initialRes.ok) {
-                    return createJsonResponse({
-                        success: true,
-                        message: "Message sent (no payment required)",
-                        response: text,
-                    });
-                }
-                throw new Error(`Expected 402 payment challenge, got ${initialRes.status}: ${text}`);
-            }
-            // Step 2: Parse payment requirements
-            const paymentHeader = initialRes.headers.get(X402_HEADERS.PAYMENT_REQUIRED);
-            if (!paymentHeader) {
-                throw new Error("402 response missing payment-required header");
-            }
-            const paymentRequired = decodePaymentRequired(paymentHeader);
-            if (!paymentRequired || !paymentRequired.accepts || paymentRequired.accepts.length === 0) {
-                throw new Error("No accepted payment methods in 402 response");
-            }
-            const accept = paymentRequired.accepts[0];
-            const amount = BigInt(accept.amount);
-            // Pre-check sBTC balance only — sponsored txs have fee: 0n so STX gas is not required
-            const sbtcService = getSbtcService(NETWORK);
-            const balanceInfo = await sbtcService.getBalance(account.address);
-            const sbtcBalance = BigInt(balanceInfo.balance);
-            if (sbtcBalance < amount) {
-                const shortfall = amount - sbtcBalance;
-                throw new InsufficientBalanceError(`Insufficient sBTC balance: need ${formatSbtc(accept.amount)}, have ${formatSbtc(balanceInfo.balance)} (shortfall: ${formatSbtc(shortfall.toString())}). ` +
-                    `Deposit more sBTC via the bridge at https://bridge.stx.eco or use a different wallet.`, "sBTC", balanceInfo.balance, accept.amount, shortfall.toString());
-            }
-            // Steps 3-5: Build payment and send with retry loop
-            // Up to 3 attempts, waiting nextRetryDelayMs (or retryAfter) before each retry.
-            const MAX_ATTEMPTS = 3;
-            let lastError = "";
-            let paymentSignature = null;
-            // Track relay txids across failed attempts to detect stale dedup.
-            const seenRelayTxids = new Set();
-            // Stash first attempt's tx + paymentId for reuse on relay-side conflicts.
-            let cachedTxHex = null;
-            let cachedPaymentId = null;
-            let cachedNonce = null;
-            let nextRetryDelayMs = 0;
-            for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
-                if (attempt > 0 && nextRetryDelayMs > 0) {
-                    console.error(`[send_inbox_message] Retry attempt ${attempt}/${MAX_ATTEMPTS - 1} after ${nextRetryDelayMs}ms`);
-                    await sleep(nextRetryDelayMs);
-                }
-                // Step 3: Build sponsored sBTC transfer.
-                // Reuse the cached transaction on relay-side nonce conflicts (the relay
-                // deduplicates by paymentId so we avoid consuming additional nonce slots).
-                let nonce;
-                let txHex;
-                let paymentId;
-                if (cachedTxHex && cachedPaymentId && cachedNonce !== null) {
-                    // Relay-side conflict: resubmit the same tx for dedup
-                    nonce = cachedNonce;
-                    txHex = cachedTxHex;
-                    paymentId = cachedPaymentId;
-                    console.error(`[send_inbox_message] Reusing cached tx (nonce=${nonce}) for relay-side dedup`);
-                }
-                else {
-                    // Fresh tx: sender-side conflict or first attempt
-                    nonce = await getNextNonce(account.address);
-                    txHex = await buildSponsoredSbtcTransfer(account.privateKey, account.address, accept.payTo, amount, BigInt(nonce));
-                    paymentId = generatePaymentId();
-                    // Cache for potential reuse on relay-side conflicts
-                    cachedTxHex = txHex;
-                    cachedPaymentId = paymentId;
-                    cachedNonce = nonce;
-                }
-                // Step 4: Encode PaymentPayloadV2 with payment-identifier extension.
-                paymentSignature = encodePaymentPayload({
-                    x402Version: 2,
-                    resource: paymentRequired.resource,
-                    accepted: accept,
-                    payload: { transaction: txHex },
-                    extensions: buildPaymentIdentifierExtension(paymentId),
-                });
-                emitPaymentLog("payment.accepted", {
-                    tool: "send_inbox_message",
-                    paymentId,
-                    action: "payment_submitted",
-                    compatShimUsed: false,
-                });
-                // Step 5: Send with payment header
-                const finalRes = await fetch(inboxUrl, {
-                    method: "POST",
-                    headers: {
-                        "Content-Type": "application/json",
-                        [X402_HEADERS.PAYMENT_SIGNATURE]: paymentSignature,
-                    },
-                    body: JSON.stringify(body),
-                });
-                const responseData = await finalRes.text();
-                let parsed;
-                try {
-                    parsed = JSON.parse(responseData);
-                }
-                catch {
-                    parsed = { raw: responseData };
-                }
-                if (finalRes.status === 200 || finalRes.status === 201 || finalRes.status === 202) {
-                    // Extract payment response header for txid
-                    const settlement = decodePaymentResponse(finalRes.headers.get(X402_HEADERS.PAYMENT_RESPONSE));
-                    const txid = settlement?.transaction;
-                    // Extract paymentId and paymentStatus from inbox response body.
-                    // The inbox API nests these under "inbox": { paymentId, paymentStatus }.
-                    const inboxData = parsed.inbox;
-                    const inboxPaymentId = (inboxData?.paymentId ?? parsed.paymentId);
-                    const inboxPaymentStatus = (inboxData?.paymentStatus ?? parsed.paymentStatus);
-                    const resolvedPaymentId = inboxPaymentId || paymentId;
-                    const canonicalHints = extractCanonicalPaymentHints({
-                        payload: parsed,
-                        paymentId: resolvedPaymentId,
-                        baseUrl: INBOX_BASE,
-                    });
-                    let compatShimUsed = false;
-                    const canonicalStatus = await resolveCanonicalPaymentStatus({
-                        payload: parsed,
-                        paymentId: resolvedPaymentId,
-                        baseUrl: INBOX_BASE,
-                        fallbackCheckStatusUrl: resolvedPaymentId
-                            ? getInboxPaymentStatusUrl(resolvedPaymentId)
-                            : undefined,
-                        onPoll: ({ paymentId: polledPaymentId, checkStatusUrl, source }) => {
-                            compatShimUsed = emitCanonicalPaymentPollLogs({
-                                tool: "send_inbox_message",
-                                paymentId: polledPaymentId ?? resolvedPaymentId,
-                                checkStatusUrl,
-                                source,
-                            });
-                        },
-                    });
-                    if (canonicalStatus) {
-                        const decision = classifyCanonicalPaymentStatus(canonicalStatus);
-                        emitCanonicalPaymentDecisionLogs({
-                            tool: "send_inbox_message",
-                            status: canonicalStatus,
-                            decision,
-                            compatShimUsed,
-                        });
-                    }
-                    // Advance shared nonce tracker on success.
-                    // When no txid is available (pending settlement), record the paymentId
-                    // so the agent can correlate the nonce with a trackable reference.
-                    // Fall back to the client-generated paymentId if the response body is
-                    // missing/malformed, so success responses always record a non-empty ref.
-                    const nonceRef = txid || `pending:${resolvedPaymentId}`;
-                    await advanceNonceCache(account.address, nonce, nonceRef);
-                    // Build payment info — always include when we have any payment reference.
-                    // This ensures the agent sees payment status even when settlement is pending.
-                    // Prefer canonical poll hints when available; synthesize an inbox-local
-                    // payment-status URL only as an explicit compatibility fallback.
-                    const paymentCheckUrl = canonicalStatus?.checkStatusUrl ??
-                        canonicalHints.checkStatusUrl ??
-                        (resolvedPaymentId ? getInboxPaymentStatusUrl(resolvedPaymentId) : undefined);
-                    return createJsonResponse({
-                        success: true,
-                        message: "Message delivered",
-                        recipient: {
-                            btcAddress: recipientBtcAddress,
-                            stxAddress: recipientStxAddress,
-                        },
-                        contentLength: content.length,
-                        inbox: parsed,
-                        payment: {
-                            ...(txid && {
-                                txid,
-                                explorer: getExplorerTxUrl(txid, NETWORK),
-                            }),
-                            amount: accept.amount + " sats sBTC",
-                            status: canonicalStatus?.status ??
-                                normalizeCallerFacingStatus(inboxPaymentStatus) ??
-                                (txid ? "confirmed" : resolvedPaymentId ? "queued" : "unknown"),
-                            paymentId: resolvedPaymentId,
-                            ...(canonicalStatus?.terminalReason && {
-                                terminalReason: canonicalStatus.terminalReason,
-                            }),
-                            ...(paymentCheckUrl && { checkStatusUrl: paymentCheckUrl }),
-                        },
-                    });
-                }
-                // Extract relay txid from payment-response header (forwarded even on failure).
-                // If we have seen it before, the relay is serving a stale cached result.
-                const failedTxid = decodePaymentResponse(finalRes.headers.get(X402_HEADERS.PAYMENT_RESPONSE))?.transaction;
-                if (failedTxid && seenRelayTxids.has(failedTxid)) {
-                    console.error(`[send_inbox_message] Stale dedup: relay returned previously-seen txid ${failedTxid} on attempt ${attempt + 1}`);
-                }
-                else if (failedTxid) {
-                    seenRelayTxids.add(failedTxid);
-                }
-                const paymentIdForStatus = cachedPaymentId ??
-                    extractPaymentIdFromPaymentSignature(paymentSignature) ??
-                    undefined;
-                let compatShimUsed = false;
-                const canonicalStatus = await resolveCanonicalPaymentStatus({
-                    payload: parsed,
-                    paymentId: paymentIdForStatus,
-                    baseUrl: INBOX_BASE,
-                    fallbackCheckStatusUrl: paymentIdForStatus
-                        ? getInboxPaymentStatusUrl(paymentIdForStatus)
-                        : undefined,
-                    onPoll: ({ paymentId: polledPaymentId, checkStatusUrl, source }) => {
-                        compatShimUsed = emitCanonicalPaymentPollLogs({
-                            tool: "send_inbox_message",
-                            paymentId: polledPaymentId ?? paymentIdForStatus,
-                            checkStatusUrl,
-                            source,
-                        });
-                    },
-                });
-                if (canonicalStatus) {
-                    const decision = classifyCanonicalPaymentStatus(canonicalStatus);
-                    emitCanonicalPaymentDecisionLogs({
-                        tool: "send_inbox_message",
-                        status: canonicalStatus,
-                        decision,
-                        compatShimUsed,
-                    });
-                    if ((decision.action === "poll_same_payment" || decision.action === "rebuild_sender") &&
-                        attempt < MAX_ATTEMPTS - 1) {
-                        nextRetryDelayMs = decision.action === "poll_same_payment" ? DEFAULT_RETRY_DELAY_MS : 0;
-                        if (decision.action === "rebuild_sender") {
-                            cachedTxHex = null;
-                            cachedPaymentId = null;
-                            cachedNonce = null;
-                            await advanceNonceCache(account.address, nonce);
-                        }
-                        lastError = `${finalRes.status}: ${decision.summary}`;
-                        continue;
-                    }
-                    const errorBase = `Message delivery failed (${finalRes.status}). ${decision.summary}` +
-                        (canonicalStatus.error ? ` Relay detail: ${canonicalStatus.error}` : "");
-                    throw new Error(`${errorBase}\n\nCanonical payment status:\n${formatCanonicalPaymentStatus(canonicalStatus)}`);
-                }
-                // Fall back to transport-specific retry hints only when canonical status is unavailable.
-                const retry = classifyLegacyRetryableError(finalRes.status, parsed);
-                if (retry.retryable && attempt < MAX_ATTEMPTS - 1) {
-                    console.error(`[send_inbox_message] Retryable error on attempt ${attempt + 1}: status=${finalRes.status} relaySide=${retry.relaySideConflict} delayMs=${retry.delayMs} body=${responseData}`);
-                    nextRetryDelayMs = retry.delayMs;
-                    if (retry.relaySideConflict) {
-                        // Keep cached tx/paymentId — relay will dedup on resubmit
-                    }
-                    else {
-                        // Sender-side conflict: need a fresh tx with new nonce
-                        cachedTxHex = null;
-                        cachedPaymentId = null;
-                        cachedNonce = null;
-                        // Advance nonce cache so the next attempt uses a strictly higher nonce.
-                        await advanceNonceCache(account.address, nonce);
-                    }
-                    lastError = `${finalRes.status}: ${responseData}`;
-                    continue;
-                }
-                // Non-retryable or last attempt — build error with txid recovery info
-                const txid = paymentSignature
-                    ? extractTxidFromPaymentSignature(paymentSignature)
-                    : null;
-                const errorBase = `Message delivery failed (${finalRes.status}): ${responseData}`;
-                if (txid) {
-                    // Poll briefly for on-chain status so the error includes actionable info
-                    const confirmation = await pollTransactionConfirmation(txid, NETWORK);
-                    emitPaymentLog("payment.fallback_used", {
-                        tool: "send_inbox_message",
-                        paymentId: paymentIdForStatus,
-                        status: confirmation.status,
-                        action: "txid_recovery",
-                        compatShimUsed: false,
-                    });
-                    throw new Error(`${errorBase}\n\nCanonical payment status was unavailable, so only txid recovery fallback is available. ` +
-                        `Payment transaction may already exist on-chain. ` +
-                        `Transaction recovery info:\n  txid: ${confirmation.txid}\n  status: ${confirmation.status}\n  explorer: ${confirmation.explorer}`);
-                }
-                throw new Error(errorBase);
-            }
-            // Retries exhausted -- check if any relay txid confirmed on-chain and
-            // resubmit with the confirmed txid as payment proof.
-            if (seenRelayTxids.size > 0) {
-                console.error(`[send_inbox_message] Checking on-chain status of ${seenRelayTxids.size} seen txid(s) before giving up.`);
-                for (const seenTxid of seenRelayTxids) {
-                    try {
-                        const confirmation = await pollTransactionConfirmation(seenTxid, NETWORK, 5_000);
-                        if (confirmation.status !== "success" && confirmation.status !== "confirmed") {
-                            continue;
-                        }
-                        console.error(`[send_inbox_message] Auto-recovery: txid ${seenTxid} confirmed on-chain. Resubmitting.`);
-                        const result = await submitWithPaymentTxid(recipientBtcAddress, recipientStxAddress, content, seenTxid);
-                        if (result.ok) {
-                            return createJsonResponse({
-                                success: true,
-                                message: result.status === 409
-                                    ? "Message already delivered"
-                                    : "Message delivered (auto-recovered with confirmed txid)",
-                                recipient: {
-                                    btcAddress: recipientBtcAddress,
-                                    stxAddress: recipientStxAddress,
-                                },
-                                contentLength: content.length,
-                                payment: {
-                                    txid: seenTxid,
-                                    amount: accept.amount + " sats sBTC",
-                                    explorer: getExplorerTxUrl(seenTxid, NETWORK),
-                                    recovered: true,
-                                },
-                            });
-                        }
-                        console.error(`[send_inbox_message] Auto-recovery resubmission failed for txid ${seenTxid}: ${result.status} ${result.body}`);
-                    }
-                    catch {
-                        // Non-fatal: move on to the next txid
-                    }
-                }
-            }
-            // Include all seen txids in the error for diagnostics
-            const txidSummary = seenRelayTxids.size > 0
-                ? `\n\nSeen relay txids (all failed or pending):\n${[...seenRelayTxids].map((id) => `  ${id}`).join("\n")}`
-                : "";
-            throw new Error(`Message delivery failed after ${MAX_ATTEMPTS} attempts. Last error: ${lastError}${txidSummary}`);
-        }
-        catch (error) {
-            return createErrorResponse(error);
-        }
+    }, async () => {
+        return createJsonResponse({
+            success: false,
+            deprecated: true,
+            error: "send_inbox_message has been removed. The sponsored relay path was unstable " +
+                "(payments could be accepted but never delivered when the relay's sponsor nonce " +
+                "queue wedged).",
+            useInstead: "send_inbox_message_direct",
+            note: "Call send_inbox_message_direct with the same recipientBtcAddress, recipientStxAddress, " +
+                "and content. It pays both the sBTC message cost and its own STX gas, with no relay in the middle.",
+        });
     });
 }
 //# sourceMappingURL=inbox.tools.js.map

package/dist/tools/lightning.tools.js

@@ -7,9 +7,11 @@
  * same LightningProvider singleton to auto-pay invoice challenges on 402s.
  */
 import { z } from "zod";
+import { decode as decodeBolt11 } from "light-bolt11-decoder";
 import { createJsonResponse, createErrorResponse } from "../utils/index.js";
 import { getLightningManager } from "../services/lightning-manager.js";
 import { getWalletManager } from "../services/wallet-manager.js";
+import { getSpendLimiter } from "../services/spend-limiter.js";
 import { MempoolApi, getMempoolTxUrl, } from "../services/mempool-api.js";
 import { buildAndSignBtcTransaction } from "../transactions/bitcoin-builder.js";
 import { UnisatIndexer } from "../services/unisat-indexer.js";
@@ -284,11 +286,39 @@ export function registerLightningTools(server) {
             if (!provider) {
                 throw new Error("Lightning wallet is locked. Use lightning_unlock first.");
             }
+            // Meter the invoice face value against the cumulative sats spend limit
+            // (#572). maxFeeSats only bounds the routing fee, not the payable amount,
+            // so without this a single invoice can pay out an unbounded amount.
+            // Decode the invoice to read the amount (millisats), mirroring the L402
+            // auto-pay path in x402.service.ts.
+            let decoded;
+            try {
+                decoded = decodeBolt11(bolt11);
+            }
+            catch (decodeErr) {
+                throw new Error(`BOLT-11 invoice could not be decoded: ${decodeErr instanceof Error ? decodeErr.message : String(decodeErr)}`);
+            }
+            const amountSection = decoded.sections.find((s) => s.name === "amount");
+            const amountMsat = amountSection?.value ? BigInt(amountSection.value) : 0n;
+            const amountSats = Number(amountMsat / 1000n);
+            if (amountSats === 0) {
+                throw new Error("Invoice has no amount; refusing to pay amountless invoices for safety (an unmeterable spend defeats the spending cap).");
+            }
+            // Key the sats ledger by the active Stacks address so BTC L1 / sBTC /
+            // L402 / Lightning spends share one budget. When the main wallet is
+            // locked (Lightning has its own session), fall back to a dedicated
+            // Lightning bucket so the pay is always metered. Note: a locked-STX
+            // user therefore gets a separate Lightning ledger from their STX-address
+            // ledger — see SECURITY.md.
+            const ledgerKey = getWalletManager().getActiveAccount()?.address ?? "__lightning__";
+            await getSpendLimiter().check("sats", BigInt(amountSats), ledgerKey);
             const result = await provider.payInvoice(bolt11, maxFeeSats);
+            await getSpendLimiter().record("sats", BigInt(amountSats), ledgerKey);
             return createJsonResponse({
                 success: true,
                 preimage: result.preimage,
                 feesPaidSats: result.feesPaid,
+                amountSats,
             });
         }
         catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibtc/mcp-server",
-  "version": "1.61.0",
+  "version": "1.62.1",
   "description": "Bitcoin-native MCP server for AI agents: BTC/STX wallets, DeFi yield, sBTC peg, NFTs, and x402 payments.",
   "mcpName": "io.github.aibtcdev/mcp-server",
   "type": "module",

package/skill/SKILL.md

@@ -4,7 +4,7 @@ description: Bitcoin L1 wallet for agents - check balances, send BTC, manage UTX
 license: MIT
 metadata:
   author: aibtcdev
-  version: 1.61.0 # x-release-please-version
+  version: 1.62.1 # x-release-please-version
   npm: "@aibtc/mcp-server"
   github: https://github.com/aibtcdev/aibtc-mcp-server
 ---