@aibtc/mcp-server 1.67.0 → 1.69.0

package/dist/services/legion.service.js

@@ -1,14 +1,23 @@
 /**
- * AIBTC News Legion (news-gov-v5) chain reads.
+ * AIBTC News Legion chain reads.
  *
  * Everything here reads the deployed contracts rather than trusting constants:
- * governance parameters, the timing mode (which clock the windows count on),
- * and the sBTC token the treasury actually holds all come off chain and are
- * cached per process. A doc that drifts from the contract is a doc; a read that
- * drifts from the contract is a bug, so there is nothing to drift.
+ * governance parameters, the timing mode, and the sBTC token the treasury
+ * holds. A doc that drifts from the contract is a doc; a read that drifts from
+ * the contract is a bug, so there is nothing to drift.
+ *
+ * The mainnet legion has NO VETO and NO QUORUM. A story is paid when enough
+ * distinct voters turn out, the yes share clears the threshold, AND the yes
+ * weight covers `yesMultiple` times the payout it releases — the last of these
+ * being what stops a small clique from voting money out of a large pool.
+ * Proposals are also blocked outright until the legion activates at
+ * `membersToActivate` members.
+ *
+ * Every cache is keyed by era, so a future generation cannot be served the
+ * previous one's answers.
  */
 import { ClarityType, cvToJSON, deserializeCV, getAddressFromPrivateKey, principalCV, uintCV, } from "@stacks/transactions";
-import { LEGION_GOV_CONTRACT, LEGION_NETWORK, LEGION_TREASURY_CONTRACT, ORDINALS_CONTENT_BASE, ORDINALS_INSCRIPTION_BASE, } from "../config/legion.js";
+import { LEGION_NETWORK, LIVE_ERA, ORDINALS_CONTENT_BASE, ORDINALS_INSCRIPTION_BASE, } from "../config/legion.js";
 import { getHiroApi } from "./hiro-api.js";
 import { getAccount } from "./x402.service.js";
 // ---------------------------------------------------------------------------
@@ -79,71 +88,191 @@ export async function readLegionContract(contractId, functionName, functionArgs
         : result.result;
     return simplifyCV(deserializeCV(Buffer.from(hex, "hex")));
 }
-export function readGov(functionName, functionArgs = []) {
-    return readLegionContract(LEGION_GOV_CONTRACT, functionName, functionArgs);
+// ---------------------------------------------------------------------------
+// Contract shape assertion
+// ---------------------------------------------------------------------------
+/**
+ * Gov functions the tools call, with the arity they are called with.
+ *
+ * Contract ids are constants, so nothing stops a redeploy under the same name
+ * from having a different shape — the reason this legion moved chains in the
+ * first place. Without this check a renamed read surfaces as `undefined` deep
+ * inside a tally, and a changed `vote` arity surfaces as a broadcast that
+ * reverts after paying gas. Checked once per contract per process.
+ */
+const REQUIRED_GOV_FUNCTIONS = {
+    // reads
+    "get-params": 0,
+    "get-timing-mode": 0,
+    "get-phase": 1,
+    "get-story": 1,
+    "get-story-meta": 1,
+    "get-last-proposal-id": 0,
+    "get-vote-record": 2,
+    "get-weight": 1,
+    "get-free-weight": 1,
+    "get-locked-weight": 1,
+    "get-locked-until": 1,
+    "get-live-proposal": 1,
+    "get-total-weight": 0,
+    "get-next-propose-height": 0,
+    "get-member-count": 0,
+    "is-activated": 0,
+    "propose-status": 1,
+    "quote-payout": 0,
+    "quote-weight": 1,
+    // writes — arity mismatches here cost gas to discover on chain
+    contribute: 1,
+    "propose-story": 3,
+    vote: 3,
+    conclude: 1,
+};
+/** Treasury functions the tools call. `execute-payout` is gov's to call, not ours. */
+const REQUIRED_TREASURY_FUNCTIONS = {
+    "get-balance": 0,
+    "get-weighted-balance": 0,
+    "get-min-sponsor": 0,
+    "get-gov": 0,
+    "get-token": 0,
+    "sponsor-in": 4,
+};
+/**
+ * Which required functions a published interface fails to satisfy.
+ *
+ * Pure, so the comparison is testable without a chain. Extra functions are
+ * fine — a contract may offer more than we call. Only missing names and
+ * changed arities matter.
+ */
+export function diffContractShape(functions, required) {
+    const found = new Map(functions.map((f) => [f.name, f.args.length]));
+    const problems = [];
+    for (const [name, arity] of Object.entries(required)) {
+        const actual = found.get(name);
+        if (actual === undefined) {
+            problems.push(`missing "${name}"`);
+        }
+        else if (actual !== arity) {
+            problems.push(`"${name}" takes ${actual} args, expected ${arity}`);
+        }
+    }
+    return problems;
 }
-export function readTreasury(functionName, functionArgs = []) {
-    return readLegionContract(LEGION_TREASURY_CONTRACT, functionName, functionArgs);
+/** One in-flight or settled check per contract id. */
+const shapeChecks = new Map();
+async function assertContractShape(contractId, required, label) {
+    const cached = shapeChecks.get(contractId);
+    if (cached)
+        return cached;
+    const check = (async () => {
+        const iface = await getHiroApi(LEGION_NETWORK).getContractInterface(contractId);
+        const problems = diffContractShape(iface.functions, required);
+        if (problems.length > 0) {
+            throw new Error(`${contractId} is not the ${label} contract these tools expect: ` +
+                `${problems.join("; ")}. The contract id is a constant in ` +
+                `src/config/legion.ts — either it points at the wrong deployment, or the ` +
+                `legion redeployed with a changed interface and the tools need updating. ` +
+                `Nothing was read or signed.`);
+        }
+    })();
+    shapeChecks.set(contractId, check);
+    // A transient interface fetch failure must not poison the process; only a
+    // successful check is worth keeping.
+    check.catch(() => shapeChecks.delete(contractId));
+    return check;
+}
+export async function readGov(functionName, functionArgs = [], era = LIVE_ERA) {
+    await assertContractShape(era.gov, REQUIRED_GOV_FUNCTIONS, "governance");
+    return readLegionContract(era.gov, functionName, functionArgs);
 }
-let paramsCache = null;
-let timingModeCache = null;
-let tokenCache = null;
+export async function readTreasury(functionName, functionArgs = [], era = LIVE_ERA) {
+    await assertContractShape(era.treasury, REQUIRED_TREASURY_FUNCTIONS, "treasury");
+    return readLegionContract(era.treasury, functionName, functionArgs);
+}
+const paramsCache = new Map();
+const timingModeCache = new Map();
+const tokenCache = new Map();
 /** Every governance parameter, straight from `get-params`. */
-export async function getParams() {
-    if (paramsCache)
-        return paramsCache;
-    const raw = (await readGov("get-params"));
-    paramsCache = {
-        votingQuorum: num(raw.votingQuorum),
+export async function getParams(era = LIVE_ERA) {
+    const cached = paramsCache.get(era.gov);
+    if (cached)
+        return cached;
+    const raw = (await readGov("get-params", [], era));
+    const params = {
         votingThreshold: num(raw.votingThreshold),
-        vetoQuorum: num(raw.vetoQuorum),
-        minParticipants: num(raw.minParticipants),
-        minWeight: num(raw.minWeight),
-        minContribution: num(raw.minContribution),
-        drawBps: num(raw.drawBps),
-        votingDelay: num(raw.votingDelay),
+        minVoters: num(raw.minVoters),
+        membersToActivate: num(raw.membersToActivate),
+        yesMultiple: num(raw.yesMultiple),
+        minWeightToAct: num(raw.minWeightToAct),
+        minJoinSats: num(raw.minJoinSats),
+        payoutBps: num(raw.payoutBps),
+        voteDelay: num(raw.voteDelay),
         voteWindow: num(raw.voteWindow),
-        vetoWindow: num(raw.vetoWindow),
         concludeWindow: num(raw.concludeWindow),
-        proposeInterval: num(raw.proposeInterval),
+        globalProposeInterval: num(raw.globalProposeInterval),
+    };
+    paramsCache.set(era.gov, params);
+    return params;
+}
+/**
+ * Whether the legion has enough members to accept proposals at all.
+ *
+ * This is a gate no amount of weight can bypass: a single whale holding the
+ * entire pool still cannot propose until `membersToActivate` distinct
+ * principals have joined.
+ */
+export async function getMembership(era = LIVE_ERA) {
+    const [count, activated, params] = await Promise.all([
+        readGov("get-member-count", [], era),
+        readGov("is-activated", [], era),
+        getParams(era),
+    ]);
+    const memberCount = num(count);
+    return {
+        memberCount,
+        membersToActivate: params.membersToActivate,
+        activated: Boolean(activated),
+        membersNeeded: Math.max(0, params.membersToActivate - memberCount),
     };
-    return paramsCache;
 }
 /**
  * Which clock the windows count on. `"TEST-STACKS-BLOCKS"` counts Stacks
  * blocks; `"PROD-BURN"` counts Bitcoin burn blocks. Never assume — a window
  * measured against the wrong tip is off by a factor of ten.
  */
-export async function getTimingMode() {
-    if (timingModeCache)
-        return timingModeCache;
-    timingModeCache = (await readGov("get-timing-mode"));
-    return timingModeCache;
+export async function getTimingMode(era = LIVE_ERA) {
+    const cached = timingModeCache.get(era.gov);
+    if (cached)
+        return cached;
+    const mode = (await readGov("get-timing-mode", [], era));
+    timingModeCache.set(era.gov, mode);
+    return mode;
 }
 /**
  * The sBTC token the treasury actually moves, plus its fungible-token asset
  * name — both needed to write an exact post-condition. Read from the treasury
  * and its contract interface so a post-condition can never name the wrong asset.
  */
-export async function getLegionToken() {
-    if (tokenCache)
-        return tokenCache;
-    const contract = (await readTreasury("get-token"));
+export async function getLegionToken(era = LIVE_ERA) {
+    const cached = tokenCache.get(era.treasury);
+    if (cached)
+        return cached;
+    const contract = (await readTreasury("get-token", [], era));
     const iface = await getHiroApi(LEGION_NETWORK).getContractInterface(contract);
     const assetName = iface.fungible_tokens?.[0]?.name;
     if (!assetName) {
         throw new Error(`${contract} declares no fungible token — cannot build a post-condition for it.`);
     }
-    tokenCache = { contract, assetName };
-    return tokenCache;
+    const token = { contract, assetName };
+    tokenCache.set(era.treasury, token);
+    return token;
 }
 /**
  * The height the contract's windows are measured against, on the clock
  * `get-timing-mode` names.
  */
-export async function getClockHeight() {
+export async function getClockHeight(era = LIVE_ERA) {
     const [timingMode, info] = await Promise.all([
-        getTimingMode(),
+        getTimingMode(era),
         getHiroApi(LEGION_NETWORK).getCoreApiInfo(),
     ]);
     const clock = timingMode === "PROD-BURN" ? "burn" : "stacks";
@@ -173,27 +302,26 @@ export async function getLegionAccount() {
         network: LEGION_NETWORK,
     };
 }
-export async function getStory(proposalId) {
-    const raw = (await readGov("get-story", [uintCV(proposalId)]));
+export async function getStory(proposalId, era = LIVE_ERA) {
+    const raw = (await readGov("get-story", [uintCV(proposalId)], era));
     if (!raw)
         return null;
     return {
         proposer: String(raw.proposer),
-        bond: num(raw.bond),
-        draw: num(raw.draw),
+        lockedWeight: num(raw.lockedWeight),
+        payout: num(raw.payout),
         createdAt: num(raw.createdAt),
         voteEnd: num(raw.voteEnd),
-        eligibleSnapshot: num(raw.eligibleSnapshot),
+        totalWeightAtOpen: num(raw.totalWeightAtOpen),
         yesWeight: num(raw.yesWeight),
         noWeight: num(raw.noWeight),
-        vetoWeight: num(raw.vetoWeight),
         voterCount: num(raw.voterCount),
         status: num(raw.status),
         reason: String(raw.reason ?? ""),
     };
 }
-export async function getStoryMeta(proposalId) {
-    const raw = (await readGov("get-story-meta", [uintCV(proposalId)]));
+export async function getStoryMeta(proposalId, era = LIVE_ERA) {
+    const raw = (await readGov("get-story-meta", [uintCV(proposalId)], era));
     if (!raw)
         return null;
     return {
@@ -203,53 +331,56 @@ export async function getStoryMeta(proposalId) {
     };
 }
 /**
- * `"none" | "pending" | "voting" | "veto" | "concludable" | "expired" |
- * "passed" | "failed"` — the contract's own view of where a piece stands.
+ * `"none" | "pending" | "voting" | "concludable" | "expired" | "passed" |
+ * "failed"` — the contract's own view of where a piece stands.
  */
-export async function getPhase(proposalId) {
-    return (await readGov("get-phase", [uintCV(proposalId)]));
+export async function getPhase(proposalId, era = LIVE_ERA) {
+    return (await readGov("get-phase", [uintCV(proposalId)], era));
 }
-export async function getLastProposalId() {
-    return num(await readGov("get-last-proposal-id"));
+export async function getLastProposalId(era = LIVE_ERA) {
+    return num(await readGov("get-last-proposal-id", [], era));
 }
-export async function getVoteRecord(proposalId, voter) {
+export async function getVoteRecord(proposalId, voter, era = LIVE_ERA) {
     const raw = (await readGov("get-vote-record", [
         uintCV(proposalId),
         principalCV(voter),
-    ]));
+    ], era));
     if (!raw)
         return null;
-    return { support: Boolean(raw.support), weight: num(raw.weight) };
-}
-export async function getVetoRecord(proposalId, voter) {
-    const raw = (await readGov("get-veto-record", [
-        uintCV(proposalId),
-        principalCV(voter),
-    ]));
-    if (!raw)
-        return null;
-    return { weight: num(raw.weight) };
+    return {
+        support: Boolean(raw.support),
+        weight: num(raw.weight),
+        rationale: String(raw.rationale ?? ""),
+    };
 }
 /** Every propose precondition folded into one read, with the individual gates. */
-export async function getProposeStatus(who) {
-    const raw = (await readGov("propose-status", [principalCV(who)]));
+export async function getProposeStatus(who, era = LIVE_ERA) {
+    const raw = (await readGov("propose-status", [principalCV(who)], era));
     return {
         canPropose: Boolean(raw.canPropose),
         eligible: Boolean(raw.eligible),
         slotOpen: Boolean(raw.slotOpen),
         noLiveProposal: Boolean(raw.noLiveProposal),
         poolOk: Boolean(raw.poolOk),
+        membersOk: Boolean(raw.membersOk),
+        memberCount: num(raw.memberCount),
+        membersToActivate: num(raw.membersToActivate),
         nextProposeHeight: num(raw.nextProposeHeight),
         lockOnPropose: num(raw.lockOnPropose),
-        draw: num(raw.draw),
+        payout: num(raw.payout),
         freeWeight: num(raw.freeWeight),
     };
 }
 /** Why a propose would revert right now, in the caller's words. */
-export function proposeBlockers(status, minWeight) {
+export function proposeBlockers(status, minWeightToAct) {
     const blockers = [];
+    if (!status.membersOk) {
+        blockers.push(`the legion is not activated — ${status.memberCount}/${status.membersToActivate} ` +
+            `members hold the minimum weight, so ${status.membersToActivate - status.memberCount} more must join before ANY story can be proposed (u441). ` +
+            `Nothing you do alone clears this gate`);
+    }
     if (!status.eligible) {
-        blockers.push(`your weight is below minWeight (${minWeight}) — call legion_contribute first`);
+        blockers.push(`your weight is below minWeightToAct (${minWeightToAct}) — call legion_contribute first`);
     }
     if (!status.noLiveProposal) {
         blockers.push("you already have a live proposal — one per principal until it concludes or lapses");
@@ -258,21 +389,20 @@ export function proposeBlockers(status, minWeight) {
         blockers.push(`the contract-wide propose interval has not elapsed — next open at height ${status.nextProposeHeight}`);
     }
     if (!status.poolOk) {
-        blockers.push("the pool is empty or the draw would round to zero sats");
+        blockers.push("the pool is empty or the payout would round to zero sats");
     }
     return blockers;
 }
 /** When each window opens and closes, on the clock the contract counts. */
 export function buildTimeline(story, params, height, clock) {
-    const votingOpensAt = story.createdAt + params.votingDelay;
-    const vetoEnd = story.voteEnd + params.vetoWindow;
-    const concludeDeadline = vetoEnd + params.concludeWindow;
-    const nextBoundary = [votingOpensAt, story.voteEnd, vetoEnd, concludeDeadline].find((boundary) => boundary > height);
+    const votingOpensAt = story.createdAt + params.voteDelay;
+    const concludeDeadline = story.voteEnd + params.concludeWindow;
+    const nextBoundary = [votingOpensAt, story.voteEnd, concludeDeadline].find((boundary) => boundary > height);
     return {
         createdAt: story.createdAt,
         votingOpensAt,
         voteEnd: story.voteEnd,
-        vetoEnd,
+        concludeOpensAt: story.voteEnd,
         concludeDeadline,
         currentHeight: height,
         clock,
@@ -291,24 +421,14 @@ export function buildTimeline(story, params, height, clock) {
  */
 export function predictOutcome(story, params, poolBalance, height) {
     const cast = story.yesWeight + story.noWeight;
-    const eligible = story.eligibleSnapshot;
-    const quorumPct = eligible > 0 ? Math.floor((cast * 100) / eligible) : 0;
     const yesPct = cast > 0 ? Math.floor((story.yesWeight * 100) / cast) : 0;
-    const vetoPct = eligible > 0 ? Math.floor((story.vetoWeight * 100) / eligible) : 0;
-    const participantsMet = story.voterCount >= params.minParticipants;
-    const quorumMet = eligible > 0 && participantsMet && quorumPct >= params.votingQuorum;
+    const yesWeightRequired = story.payout * params.yesMultiple;
+    // The contract's three gates, in its order. There is no quorum here: nothing
+    // divides by totalWeightAtOpen, so a story cannot fail for turnout alone.
+    const votersMet = story.voterCount >= params.minVoters;
     const thresholdMet = cast > 0 && yesPct >= params.votingThreshold;
-    const vetoed = eligible > 0 && vetoPct >= params.vetoQuorum;
-    const base = {
-        cast,
-        quorumPct,
-        yesPct,
-        vetoPct,
-        quorumMet,
-        thresholdMet,
-        vetoed,
-        participantsMet,
-    };
+    const yesMet = story.yesWeight >= yesWeightRequired;
+    const base = { cast, yesPct, yesWeightRequired, votersMet, thresholdMet, yesMet };
     // Already terminal: report the record.
     if (story.status !== 0) {
         const settledOutcome = story.status === 1 ? "passed" : story.status === 3 ? "expired" : "failed";
@@ -317,11 +437,10 @@ export function predictOutcome(story, params, poolBalance, height) {
             settled: true,
             outcome: settledOutcome,
             reason: story.reason || settledOutcome,
-            payout: story.status === 1 ? story.draw : 0,
+            payout: story.status === 1 ? story.payout : 0,
         };
     }
-    const concludeDeadline = story.voteEnd + params.vetoWindow + params.concludeWindow;
-    if (height >= concludeDeadline) {
+    if (height >= story.voteEnd + params.concludeWindow) {
         return {
             ...base,
             settled: false,
@@ -330,19 +449,20 @@ export function predictOutcome(story, params, poolBalance, height) {
             payout: 0,
         };
     }
-    if (vetoed) {
-        return { ...base, settled: false, outcome: "failed", reason: "vetoed", payout: 0 };
-    }
-    if (!quorumMet) {
-        return { ...base, settled: false, outcome: "failed", reason: "no-quorum", payout: 0 };
+    if (!votersMet) {
+        return { ...base, settled: false, outcome: "failed", reason: "no-voters", payout: 0 };
     }
     if (!thresholdMet) {
         return { ...base, settled: false, outcome: "failed", reason: "voted-down", payout: 0 };
     }
-    if (story.draw > poolBalance) {
+    if (!yesMet) {
+        // Approved, but by too little weight to justify the sats it would release.
+        return { ...base, settled: false, outcome: "failed", reason: "yes-short", payout: 0 };
+    }
+    if (story.payout > poolBalance) {
         return { ...base, settled: false, outcome: "failed", reason: "pool-short", payout: 0 };
     }
-    return { ...base, settled: false, outcome: "passed", reason: "paid", payout: story.draw };
+    return { ...base, settled: false, outcome: "passed", reason: "paid", payout: story.payout };
 }
 // ---------------------------------------------------------------------------
 // Links and validation

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/index.js

@@ -168,7 +168,7 @@ export function registerAllTools(server) {
     registerInferenceMarketplaceTools(server);
     // AIBTC News (signal feed, leaderboard, file signals)
     registerNewsTools(server);
-    // AIBTC News Legion (news-gov-v5 governance — inscribe, propose, vote, veto, conclude)
+    // AIBTC News Legion (mainnet aibtc-news-gov — inscribe, propose, vote, conclude)
     registerLegionTools(server);
     // Identity (ERC-8004 on-chain agent identity management)
     registerIdentityTools(server);

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

@@ -1,13 +1,22 @@
 /**
- * AIBTC News Legion tools (news-gov-v5).
+ * AIBTC News Legion tools (mainnet `aibtc-news-gov`).
  *
- * Lifecycle: inscribe → reveal → propose → vote → veto → conclude, plus
- * contribute (buys weight) and sponsor (does not).
+ * Lifecycle: inscribe → reveal → propose → vote → conclude, plus contribute
+ * (buys weight) and sponsor (does not). There is no veto in this era: voting no
+ * while the window is open is the only way to stop a piece.
+ *
+ * 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. 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 mainnet-configured server signs
- * against testnet. Inscription is the exception — real BTC on whatever chain
- * NETWORK names.
+ * unlocked wallet for the legion's chain, so a testnet-configured server still
+ * signs against the mainnet contracts rather than quietly reading a chain the
+ * legion does not live on. Inscription is the exception — it follows the global
+ * NETWORK, because ordinals.com indexes Bitcoin mainnet only.
  *
  * Fund-moving calls sign in DENY mode with an exact post-condition.
  */