@aibtc/mcp-server 1.68.0 → 1.69.0

package/dist/services/spend-limiter.d.ts

@@ -1,4 +1,57 @@
+/**
+ * Default-on cumulative spending limit for the wallet.
+ *
+ * The MCP server lets an LLM move real funds with no human click-through, so a
+ * single poisoned instruction (or a malicious x402 endpoint) could otherwise
+ * drain the wallet. This module is the safety rail: every outbound spend path
+ * (native STX transfer, BTC L1 transfer, x402/L402 auto-payments, Lightning
+ * pays, and contract calls carrying a bounded caller-owned post condition)
+ * routes through it, and the limiter blocks once cumulative outflow would
+ * exceed a per-session OR per-day cap.
+ *
+ * Two independent ledgers are tracked — micro-STX (`ustx`) and satoshis
+ * (`sats`); there is no cross-asset USD normalization. Daily totals are
+ * persisted to ~/.aibtc/spend-state.json (keyed by wallet address + UTC day) so
+ * the cap survives process restarts; session totals live in memory and reset on
+ * wallet unlock/lock/switch.
+ *
+ * Exceeding the cap is the intended human-in-the-loop checkpoint: it blocks and
+ * surfaces the remaining budget + the env var to raise. An LLM cannot set env
+ * vars mid-session, so it cannot raise its own ceiling.
+ *
+ * Disable entirely with SPEND_LIMIT_ENABLED=false. Override caps with
+ * SPEND_LIMIT_DAILY_USTX / _SESSION_USTX / _DAILY_SATS / _SESSION_SATS.
+ */
+import type { PostCondition } from "@stacks/transactions";
 export type SpendUnit = "ustx" | "sats";
+/**
+ * Read spend ceilings out of a contract call's post conditions.
+ *
+ * A post condition already says "at most N of asset A leaves principal P", in
+ * native units, enforced by the chain — which is exactly the bound this rail
+ * wants, without taking a price-oracle dependency inside a safety rail.
+ *
+ * Only conditions that BOUND THE SPEND FROM ABOVE count: `eq`, `lt` and `lte`.
+ * A `gt`/`gte` condition is a floor, not a cap, so metering it would invent a
+ * ceiling that does not exist. Conditions on another principal are somebody
+ * else's funds, and an FT that is not sBTC has no ledger here — both are
+ * skipped rather than guessed at.
+ *
+ * `lt` is metered at its face value (one micro-unit above the true ceiling).
+ * Over-metering by one is the safe direction for a cap.
+ */
+export declare function boundedPostConditionSpends(postConditions: PostCondition[] | undefined, accountAddress: string): Array<{
+    unit: SpendUnit;
+    amount: bigint;
+}>;
+/**
+ * Collapse per-unit so one contract call is metered once per ledger, not once
+ * per post condition.
+ */
+export declare function totalBoundedSpends(postConditions: PostCondition[] | undefined, accountAddress: string): Array<{
+    unit: SpendUnit;
+    amount: bigint;
+}>;
 export declare class SpendLimitError extends Error {
     readonly unit: SpendUnit;
     readonly attempted: number;

package/dist/services/spend-limiter.js

@@ -1,29 +1,63 @@
+import { promises as fs } from "fs";
+import os from "os";
+import path from "path";
+import { MAINNET_CONTRACTS, TESTNET_CONTRACTS } from "../config/contracts.js";
+/** Asset ids this rail can meter. Any other FT has no ledger to bill. */
+const SBTC_ASSETS = new Set([
+    `${MAINNET_CONTRACTS.SBTC_TOKEN}::sbtc-token`,
+    `${TESTNET_CONTRACTS.SBTC_TOKEN}::sbtc-token`,
+]);
 /**
- * Default-on cumulative spending limit for the wallet.
- *
- * The MCP server lets an LLM move real funds with no human click-through, so a
- * single poisoned instruction (or a malicious x402 endpoint) could otherwise
- * drain the wallet. This module is the safety rail: every outbound spend path
- * (native STX transfer, BTC L1 transfer, x402/L402 auto-payments, Lightning
- * pays) routes through it, and the limiter blocks once cumulative outflow would
- * exceed a per-session OR per-day cap.
+ * Read spend ceilings out of a contract call's post conditions.
  *
- * Two independent ledgers are tracked — micro-STX (`ustx`) and satoshis
- * (`sats`); there is no cross-asset USD normalization. Daily totals are
- * persisted to ~/.aibtc/spend-state.json (keyed by wallet address + UTC day) so
- * the cap survives process restarts; session totals live in memory and reset on
- * wallet unlock/lock/switch.
+ * A post condition already says "at most N of asset A leaves principal P", in
+ * native units, enforced by the chain — which is exactly the bound this rail
+ * wants, without taking a price-oracle dependency inside a safety rail.
  *
- * Exceeding the cap is the intended human-in-the-loop checkpoint: it blocks and
- * surfaces the remaining budget + the env var to raise. An LLM cannot set env
- * vars mid-session, so it cannot raise its own ceiling.
+ * Only conditions that BOUND THE SPEND FROM ABOVE count: `eq`, `lt` and `lte`.
+ * A `gt`/`gte` condition is a floor, not a cap, so metering it would invent a
+ * ceiling that does not exist. Conditions on another principal are somebody
+ * else's funds, and an FT that is not sBTC has no ledger here — both are
+ * skipped rather than guessed at.
  *
- * Disable entirely with SPEND_LIMIT_ENABLED=false. Override caps with
- * SPEND_LIMIT_DAILY_USTX / _SESSION_USTX / _DAILY_SATS / _SESSION_SATS.
+ * `lt` is metered at its face value (one micro-unit above the true ceiling).
+ * Over-metering by one is the safe direction for a cap.
  */
-import { promises as fs } from "fs";
-import os from "os";
-import path from "path";
+export function boundedPostConditionSpends(postConditions, accountAddress) {
+    const spends = [];
+    for (const condition of postConditions ?? []) {
+        const pc = condition;
+        if (pc.address !== accountAddress)
+            continue;
+        if (pc.condition !== "eq" && pc.condition !== "lt" && pc.condition !== "lte")
+            continue;
+        if (pc.amount === undefined)
+            continue;
+        const amount = BigInt(pc.amount);
+        if (amount < 0n)
+            continue;
+        if (pc.type === "stx-postcondition") {
+            spends.push({ unit: "ustx", amount });
+        }
+        else if (pc.type === "ft-postcondition" &&
+            pc.asset !== undefined &&
+            SBTC_ASSETS.has(pc.asset)) {
+            spends.push({ unit: "sats", amount });
+        }
+    }
+    return spends;
+}
+/**
+ * Collapse per-unit so one contract call is metered once per ledger, not once
+ * per post condition.
+ */
+export function totalBoundedSpends(postConditions, accountAddress) {
+    const totals = new Map();
+    for (const { unit, amount } of boundedPostConditionSpends(postConditions, accountAddress)) {
+        totals.set(unit, (totals.get(unit) ?? 0n) + amount);
+    }
+    return [...totals].map(([unit, amount]) => ({ unit, amount }));
+}
 const STORAGE_DIR = path.join(os.homedir(), ".aibtc");
 const DEFAULT_STATE_FILE = path.join(STORAGE_DIR, "spend-state.json");
 /**

package/dist/tools/legion.tools.d.ts

@@ -7,9 +7,10 @@
  *
  * EVERYTHING HERE MOVES REAL VALUE. The legion is on Stacks mainnet holding
  * real sBTC, and neither `contribute` nor `sponsor` has a withdrawal path, so
- * both meter against the wallet's `sats` spending rail before signing —
- * `callContract` is not itself a metered chokepoint, but these two take the
- * amount as a direct parameter, which is what the rail needs.
+ * both meter against the wallet's `sats` spending rail before signing. That
+ * metering happens inside `callContract`, which reads the exact sBTC
+ * post-condition these calls already sign in DENY mode — so it must NOT be
+ * repeated here, or every contribute would bill the rail twice.
  *
  * These tools pin their own network: `getLegionAccount()` re-derives the
  * unlocked wallet for the legion's chain, so a testnet-configured server still

package/dist/tools/legion.tools.js

@@ -7,9 +7,10 @@
  *
  * EVERYTHING HERE MOVES REAL VALUE. The legion is on Stacks mainnet holding
  * real sBTC, and neither `contribute` nor `sponsor` has a withdrawal path, so
- * both meter against the wallet's `sats` spending rail before signing —
- * `callContract` is not itself a metered chokepoint, but these two take the
- * amount as a direct parameter, which is what the rail needs.
+ * both meter against the wallet's `sats` spending rail before signing. That
+ * metering happens inside `callContract`, which reads the exact sBTC
+ * post-condition these calls already sign in DENY mode — so it must NOT be
+ * repeated here, or every contribute would bill the rail twice.
  *
  * These tools pin their own network: `getLegionAccount()` re-derives the
  * unlocked wallet for the legion's chain, so a testnet-configured server still
@@ -27,7 +28,6 @@ import { DUST_THRESHOLD } from "../config/bitcoin-constants.js";
 import { LEGION_ERAS, LEGION_ERRORS, LEGION_NETWORK, LEGION_SITE_URL, LIVE_ERA, MAX_DESCRIPTION_LENGTH, MAX_LINK_LENGTH, MAX_RATIONALE_LENGTH, MAX_SPONSOR_LINK_LENGTH, MAX_SPONSOR_MEMO_LENGTH, MAX_SPONSOR_NAME_LENGTH, MAX_TITLE_LENGTH, ORDINALS_CONTENT_BASE, ORDINALS_INSCRIPTION_BASE, STORY_STATUS, resolveEra, } from "../config/legion.js";
 import { assertAscii, buildTimeline, contentUrlFromLink, explainError, getClockHeight, getLastProposalId, getLegionAccount, getLegionToken, getMembership, getParams, getPhase, getProposeStatus, getStory, getStoryMeta, getVoteRecord, inscriptionIdFromLink, normalizeOrdinalsLink, num, predictOutcome, proposeBlockers, readGov, readLegionContract, readTreasury, } from "../services/legion.service.js";
 import { callContract } from "../transactions/builder.js";
-import { getSpendLimiter } from "../services/spend-limiter.js";
 import { getWalletManager } from "../services/wallet-manager.js";
 import { MempoolApi, getMempoolTxUrl } from "../services/mempool-api.js";
 import { buildCommitTransaction, buildRevealTransaction, deriveRevealScript, } from "../transactions/inscription-builder.js";
@@ -596,10 +596,9 @@ export function registerLegionTools(server) {
                 return createErrorResponse(new Error(`Your sBTC balance is ${balance} sats — not enough to contribute ${sats}. ` +
                     `Acquire sBTC with sbtc_deposit or styx_deposit first.`));
             }
-            // Real, unrecoverable sBTC leaves the wallet here. callContract is not
-            // itself a metered chokepoint, but the amount is a direct parameter, so
-            // the rail applies cleanly — and must, before anything is signed.
-            await getSpendLimiter().check("sats", BigInt(sats), account.address);
+            // Real, unrecoverable sBTC leaves the wallet here. The `sats` rail is
+            // metered by callContract off the willSendEq post-condition below —
+            // metering again here would double-bill the cap.
             const quotedWeight = num(await readGov("quote-weight", [uintCV(sats)]));
             const result = await callContract(account, {
                 contractAddress: GOV_ADDRESS,
@@ -613,7 +612,6 @@ export function registerLegionTools(server) {
                         .ft(token.contract, token.assetName),
                 ],
             });
-            await getSpendLimiter().record("sats", BigInt(sats), account.address);
             const weightAfter = num(weightBefore) + quotedWeight;
             const wasMember = num(weightBefore) >= params.minWeightToAct;
             const willBeMember = weightAfter >= params.minWeightToAct;
@@ -700,8 +698,8 @@ export function registerLegionTools(server) {
             if (balance < sats) {
                 return createErrorResponse(new Error(`Your sBTC balance is ${balance} sats — not enough to sponsor ${sats}.`));
             }
-            // Same rail as contribute: real sBTC, no refund, amount is a direct param.
-            await getSpendLimiter().check("sats", BigInt(sats), account.address);
+            // Same rail as contribute: real sBTC, no refund, metered by callContract
+            // off the post-condition below.
             const result = await callContract(account, {
                 contractAddress: TREASURY_ADDRESS,
                 contractName: TREASURY_NAME,
@@ -719,7 +717,6 @@ export function registerLegionTools(server) {
                         .ft(token.contract, token.assetName),
                 ],
             });
-            await getSpendLimiter().record("sats", BigInt(sats), account.address);
             return createJsonResponse({
                 success: true,
                 txid: result.txid,

package/dist/tools/ordinals.tools.js

@@ -10,6 +10,7 @@
  *
  * Uses micro-ordinals library to parse and create inscriptions.
  */
+import { createHash } from "node:crypto";
 import { z } from "zod";
 import { NETWORK } from "../config/networks.js";
 import { P2WPKH_INPUT_VBYTES, P2WPKH_OUTPUT_VBYTES, P2TR_OUTPUT_VBYTES, TX_OVERHEAD_VBYTES, DUST_THRESHOLD, P2TR_INPUT_BASE_VBYTES, WITNESS_OVERHEAD_VBYTES, } from "../config/bitcoin-constants.js";
@@ -223,8 +224,10 @@ export function registerOrdinalsTools(server) {
                 feeRate: actualFeeRate,
                 contentType,
                 contentSize: body.length,
+                contentSha256: createHash("sha256").update(body).digest("hex"),
                 nextStep: "After commit confirms, call inscribe_reveal with the same contentType, contentBase64, " +
-                    "plus commitTxid and revealAmount from this response.",
+                    "plus commitTxid and revealAmount from this response. Pass contentSha256 back to inscribe_reveal " +
+                    "to have the server abort before the reveal fee is spent if the decoded body differs by even one byte.",
             });
         }
         catch (error) {
@@ -252,12 +255,20 @@ export function registerOrdinalsTools(server) {
             contentBase64: z
                 .string()
                 .describe("Content as base64-encoded string (must match the commit step)"),
+            contentSha256: z
+                .string()
+                .regex(/^[0-9a-f]{64}$/i)
+                .optional()
+                .describe("Optional: sha256 hex digest of the decoded body from the inscribe commit response. " +
+                "If provided, the server computes sha256 over the locally-decoded body and aborts before " +
+                "broadcasting the reveal if they differ — prevents burning the reveal fee on a witness-hash " +
+                "mismatch when the base64 param drifts between the inscribe and inscribe_reveal calls."),
             feeRate: z
                 .union([z.enum(["fast", "medium", "slow"]), z.number().positive()])
                 .optional()
                 .describe("Fee rate for reveal tx (default: medium)"),
         },
-    }, async ({ commitTxid, revealAmount, contentType, contentBase64, feeRate }) => {
+    }, async ({ commitTxid, revealAmount, contentType, contentBase64, contentSha256, feeRate }) => {
         try {
             // Check wallet session
             const walletManager = getWalletManager();
@@ -277,6 +288,21 @@ export function registerOrdinalsTools(server) {
             const mempoolApi = new MempoolApi(NETWORK);
             // Reconstruct the inscription and reveal script
             const body = Buffer.from(contentBase64, "base64");
+            // If the caller supplied the sha256 digest from the commit response, verify the
+            // decoded body matches BEFORE we spend the reveal fee. Silent byte drift between
+            // the two calls would otherwise commit a tapscript hash that Bitcoin Core rejects
+            // as witness-hash-mismatch, burning the reveal-address sats permanently.
+            if (contentSha256) {
+                const localSha256 = createHash("sha256").update(body).digest("hex");
+                if (localSha256.toLowerCase() !== contentSha256.toLowerCase()) {
+                    return createErrorResponse(new Error(`contentSha256 mismatch: the decoded body's sha256 (${localSha256}) does not match ` +
+                        `the digest from the inscribe commit response (${contentSha256}). This means the ` +
+                        `base64 payload passed to inscribe_reveal is not the exact bytes committed on-chain. ` +
+                        `Aborting BEFORE broadcasting the reveal so the reveal-address sats are not burned. ` +
+                        `Re-send the exact base64 from the successful inscribe call (or fix the transport / ` +
+                        `serialization layer that mutated it).`));
+                }
+            }
             const inscription = {
                 contentType,
                 body,

package/dist/transactions/builder.js

@@ -3,7 +3,7 @@ import { hexToBytes } from "@stacks/common";
 import { getStacksNetwork, getApiBaseUrl } from "../config/networks.js";
 import { getHiroApi } from "../services/hiro-api.js";
 import { resolveDefaultFee } from "../utils/fee.js";
-import { getSpendLimiter } from "../services/spend-limiter.js";
+import { getSpendLimiter, totalBoundedSpends } from "../services/spend-limiter.js";
 import { getTrackedNonce, recordNonceUsed, resetTrackedNonce, reconcileWithChain, } from "../services/nonce-tracker.js";
 // ---------------------------------------------------------------------------
 // Pending nonce tracking (unified via SharedNonceTracker, issue #413)
@@ -117,6 +117,16 @@ export async function transferStx(account, recipient, amount, memo, fee) {
  * Call a smart contract function
  */
 export async function callContract(account, options) {
+    // Safety rail. Swaps, lending and pot entries all funnel through here, and
+    // their amounts are denominated in whatever token the call moves — there is no
+    // ledger to bill 1,000 ALEX against. The post conditions are the way in: they
+    // already bound, in native units, how much of each asset may leave this
+    // address. Meter the ones this rail has a ledger for and ignore the rest.
+    // Deliberately before makeContractCall, so an over-cap call never signs.
+    const meteredSpends = totalBoundedSpends(options.postConditions, account.address);
+    for (const spend of meteredSpends) {
+        await getSpendLimiter().check(spend.unit, spend.amount, account.address);
+    }
     const networkName = getStacksNetwork(account.network);
     const nonce = await getNextNonce(account.address, account.network);
     // Always resolve a clamped fee — prevents @stacks/transactions from over-estimating.
@@ -141,6 +151,9 @@ export async function callContract(account, options) {
         throw new Error(`Broadcast failed: ${broadcastResponse.error} - ${broadcastResponse.reason}`);
     }
     advancePendingNonce(account.address, nonce, broadcastResponse.txid);
+    for (const spend of meteredSpends) {
+        await getSpendLimiter().record(spend.unit, spend.amount, account.address);
+    }
     return {
         txid: broadcastResponse.txid,
         rawTx: transaction.serialize(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibtc/mcp-server",
-  "version": "1.68.0",
+  "version": "1.69.0",
   "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.68.0 # x-release-please-version
+  version: 1.69.0 # x-release-please-version
   npm: "@aibtc/mcp-server"
   github: https://github.com/aibtcdev/aibtc-mcp-server
 ---