@aibtc/mcp-server 1.68.0 → 1.70.0

package/dist/services/at-stake.service.js

@@ -0,0 +1,272 @@
+/**
+ * Chain reads for the At Stake market and its two side legions.
+ *
+ * Every read here goes to the chain the contracts live on, not the chain the
+ * server is configured for — see the note in `config/at-stake.ts`.
+ *
+ * Clarity values come back through `cvToJSON`, whose shape is nested and
+ * stringly typed. The unwrapping lives here so the tool layer reads as the
+ * market's own vocabulary rather than as tuple spelunking.
+ */
+import { cvToJSON, deserializeCV, getAddressFromPrivateKey, principalCV, uintCV, } from "@stacks/transactions";
+import { getHiroApi } from "./hiro-api.js";
+import { getAccount } from "./x402.service.js";
+import { AT_STAKE_NETWORK, CLOSE_HEIGHT, LEGION_ERRORS, MARKET_ADDRESS, MARKET_CONTRACT, MARKET_ERRORS, MARKET_STATUS, PROPOSAL_STATUS, STATUS_OPEN, } from "../config/at-stake.js";
+/**
+ * The wallet, re-derived for the legion's chain.
+ *
+ * A testnet-configured server still holds the same private key; only the
+ * c32 encoding of the address differs. Re-deriving means a mainnet call is
+ * signed by the mainnet form of the same wallet rather than failing, or worse,
+ * quoting one address while signing as another.
+ */
+export async function getAtStakeAccount() {
+    const base = await getAccount();
+    if (base.network === AT_STAKE_NETWORK)
+        return base;
+    return {
+        ...base,
+        address: getAddressFromPrivateKey(base.privateKey, AT_STAKE_NETWORK),
+        network: AT_STAKE_NETWORK,
+    };
+}
+/** Call a read-only function on either contract and return its JSON form. */
+export async function readContract(contractId, functionName, args = []) {
+    const hiro = getHiroApi(AT_STAKE_NETWORK);
+    const result = await hiro.callReadOnlyFunction(contractId, functionName, args, MARKET_ADDRESS);
+    if (!result.okay) {
+        throw new Error(`${contractId} ${functionName} failed: ${result.cause ?? "unknown error"}`);
+    }
+    if (!result.result)
+        return null;
+    const hex = result.result.startsWith("0x")
+        ? result.result.slice(2)
+        : result.result;
+    return cvToJSON(deserializeCV(Buffer.from(hex, "hex")));
+}
+/** Read a market function. */
+export function readMarket(functionName, args = []) {
+    return readContract(MARKET_CONTRACT, functionName, args);
+}
+/**
+ * Flatten one layer of `cvToJSON`'s `{type, value}` nesting.
+ *
+ * A Clarity tuple arrives as `{type, value: {field: {type, value}}}`, and an
+ * optional wraps that again. Callers want the field, not the envelope.
+ */
+function unwrap(cv) {
+    if (cv && typeof cv === "object" && "value" in cv) {
+        return cv.value;
+    }
+    return cv;
+}
+/** Read a uint out of a `cvToJSON` node. */
+export function num(cv) {
+    const v = unwrap(cv);
+    if (v === null || v === undefined)
+        return 0;
+    return Number(v);
+}
+/** Read a bool out of a `cvToJSON` node. */
+function bool(cv) {
+    return unwrap(cv) === true || unwrap(cv) === "true";
+}
+/** Read a string out of a `cvToJSON` node. */
+function str(cv) {
+    const v = unwrap(cv);
+    return v === null || v === undefined ? "" : String(v);
+}
+/** Fields of a tuple node, or `null` for a `none`. */
+function fields(cv) {
+    const v = unwrap(cv);
+    if (v === null || v === undefined)
+        return null;
+    // An optional's payload is itself a {type, value} node.
+    if (typeof v === "object" && "value" in v && "type" in v) {
+        return fields(v);
+    }
+    return v;
+}
+export async function getMarket() {
+    const f = fields(await readMarket("get-market"));
+    if (!f)
+        throw new Error("get-market returned nothing.");
+    const status = num(f["status"]);
+    return {
+        title: str(f["title"]),
+        opened: bool(f["opened"]),
+        status,
+        statusLabel: MARKET_STATUS[status] ?? `unknown(${status})`,
+        closeHeight: num(f["close-height"]),
+        vault: num(f["vault"]),
+        idleCirc: num(f["idle-circ"]),
+        bondedCirc: num(f["bonded-circ"]),
+        createdAt: num(f["created-at"]),
+    };
+}
+export async function getPosition(who) {
+    const f = fields(await readMarket("get-position", [principal(who)]));
+    if (!f)
+        return { idle: 0, bonded: 0 };
+    return { idle: num(f["idle"]), bonded: num(f["bonded"]) };
+}
+export async function getBid(who, side) {
+    const f = fields(await readMarket("get-bid", [principal(who), uint(side.side)]));
+    if (!f)
+        return null;
+    return { amount: num(f["amount"]), escrow: num(f["escrow"]) };
+}
+/** Current burn height — the clock every window in both contracts uses. */
+export async function getBurnHeight() {
+    const info = await getHiroApi(AT_STAKE_NETWORK).getCoreApiInfo();
+    return info.burn_block_height;
+}
+/**
+ * Whether the market still accepts trades.
+ *
+ * Mirrors the contract's own `assert-tradeable`: open status AND the close
+ * height not yet passed. Derived rather than read so a caller can be told
+ * which of the two conditions failed.
+ */
+export function isTradeable(market, burnHeight) {
+    return market.status === STATUS_OPEN && burnHeight <= CLOSE_HEIGHT;
+}
+export async function getLegionParams(side) {
+    const f = fields(await readContract(side.legion, "get-params"));
+    if (!f)
+        throw new Error(`${side.legion} get-params returned nothing.`);
+    return {
+        minPosition: num(f["minPosition"]),
+        payout: num(f["payout"]),
+        minVoters: num(f["minVoters"]),
+        proposerCooldown: num(f["proposerCooldown"]),
+        votingThreshold: num(f["votingThreshold"]),
+        voteDelay: num(f["voteDelay"]),
+        voteWindow: num(f["voteWindow"]),
+        concludeWindow: num(f["concludeWindow"]),
+        globalProposeInterval: num(f["globalProposeInterval"]),
+    };
+}
+export async function getProposeStatus(side, who) {
+    const f = fields(await readContract(side.legion, "propose-status", [principal(who)]));
+    if (!f)
+        throw new Error(`${side.legion} propose-status returned nothing.`);
+    return {
+        canPropose: bool(f["canPropose"]),
+        eligible: bool(f["eligible"]),
+        slotOpen: bool(f["slotOpen"]),
+        cooledDown: bool(f["cooledDown"]),
+        noLiveProposal: bool(f["noLiveProposal"]),
+        potOk: bool(f["potOk"]),
+        marketTradeable: bool(f["marketTradeable"]),
+        weight: num(f["weight"]),
+        vault: num(f["vault"]),
+        winsLeft: num(f["winsLeft"]),
+        payout: num(f["payout"]),
+        votable: num(f["votable"]),
+        nextProposeHeight: num(f["nextProposeHeight"]),
+        proposerNextHeight: num(f["proposerNextHeight"]),
+    };
+}
+export async function getProposal(side, proposalId) {
+    const f = fields(await readContract(side.legion, "get-proposal", [uint(proposalId)]));
+    if (!f)
+        return null;
+    const status = num(f["status"]);
+    return {
+        proposer: str(f["proposer"]),
+        payout: num(f["payout"]),
+        createdAt: num(f["createdAt"]),
+        voteEnd: num(f["voteEnd"]),
+        votableAtOpen: num(f["votableAtOpen"]),
+        yesWeight: num(f["yesWeight"]),
+        noWeight: num(f["noWeight"]),
+        voterCount: num(f["voterCount"]),
+        yesVoterCount: num(f["yesVoterCount"]),
+        status,
+        statusLabel: PROPOSAL_STATUS[status] ?? `unknown(${status})`,
+        reason: str(f["reason"]),
+        paidInShares: bool(f["paidInShares"]),
+    };
+}
+export async function getProposalMeta(side, proposalId) {
+    const f = fields(await readContract(side.legion, "get-proposal-meta", [uint(proposalId)]));
+    if (!f)
+        return null;
+    return {
+        title: str(f["title"]),
+        description: str(f["description"]),
+        link: str(f["link"]),
+    };
+}
+/** The contract's own phase word for a proposal. */
+export async function getPhase(side, proposalId) {
+    return str(await readContract(side.legion, "get-phase", [uint(proposalId)]));
+}
+export async function getSettlement(side) {
+    const f = fields(await readContract(side.legion, "get-settlement"));
+    if (!f)
+        throw new Error(`${side.legion} get-settlement returned nothing.`);
+    return {
+        redeemed: bool(f["redeemed"]),
+        redeemedSats: num(f["redeemedSats"]),
+        paidSats: num(f["paidSats"]),
+        unpaidSats: num(f["unpaidSats"]),
+        totalCredits: num(f["totalCredits"]),
+        won: bool(f["won"]),
+    };
+}
+/**
+ * Predict what `conclude` will decide, in the contract's own decision order.
+ *
+ * The chain decides for real at the block that mines the transaction; this is
+ * the tally as of now, so a caller can see that they are about to burn gas on
+ * a proposal that fails for want of one more voter.
+ */
+export function predictOutcome(proposal, params, proposerStillHolding, vault, totalCredits, tradeable) {
+    const cast = proposal.yesWeight + proposal.noWeight;
+    if (proposal.yesVoterCount < params.minVoters) {
+        return { outcome: "failed", reason: "no-voters", payout: 0 };
+    }
+    if (cast === 0 || (proposal.yesWeight * 100) / cast < params.votingThreshold) {
+        return { outcome: "failed", reason: "voted-down", payout: 0 };
+    }
+    if (!proposerStillHolding) {
+        return { outcome: "failed", reason: "not-holding", payout: 0 };
+    }
+    if (vault < totalCredits + params.payout) {
+        return { outcome: "failed", reason: "pot-short", payout: 0 };
+    }
+    return {
+        outcome: "passed",
+        reason: tradeable ? "paid-shares" : "credited",
+        payout: params.payout,
+    };
+}
+// ---------------------------------------------------------------------------
+// Clarity argument helpers and error translation
+// ---------------------------------------------------------------------------
+function principal(address) {
+    return principalCV(address);
+}
+function uint(value) {
+    return uintCV(value);
+}
+/**
+ * Turn a contract abort into the sentence behind its code.
+ *
+ * The two contracts use disjoint ranges — the market is 100-313, the legions
+ * 401-450 — so one lookup across both tables cannot collide.
+ */
+export function explainAbort(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const match = message.match(/\bu(\d+)\b/);
+    if (!match)
+        return error instanceof Error ? error : new Error(message);
+    const code = Number(match[1]);
+    const explanation = MARKET_ERRORS[code] ?? LEGION_ERRORS[code];
+    if (!explanation)
+        return error instanceof Error ? error : new Error(message);
+    return new Error(`${explanation} (u${code})\n\nRaw: ${message}`);
+}
+//# sourceMappingURL=at-stake.service.js.map

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,64 @@
+import { promises as fs } from "fs";
+import os from "os";
+import path from "path";
+import { withSharedStateLock } from "./state-lock.js";
+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");
 /**
@@ -161,27 +196,50 @@ class SpendLimiter {
             return;
         const amt = Number(amount);
         this.getSession(addr)[unit] += amt;
-        // Serialize read-modify-write to avoid lost updates under concurrency.
-        this.writeLock = this.writeLock.then(async () => {
-            const state = await this.readState();
-            const today = todayKey();
-            // Prune stale days so the file does not grow unbounded.
-            for (const a of Object.keys(state)) {
-                for (const day of Object.keys(state[a])) {
-                    if (day !== today)
-                        delete state[a][day];
+        // Two locks, for two different races.
+        //
+        // The promise chain serializes concurrent record() calls INSIDE this
+        // process. The file lease excludes the OTHER process writing this file:
+        // the skills engine's direct x402 path shares spend-state.json so one
+        // wallet has one daily cap. Without the lease, its writes and ours
+        // overwrite each other and the day total under-counts, which is the
+        // direction that permits spending past the cap.
+        //
+        // Note the prune below walks EVERY address, so an unlocked concurrent
+        // write can lose another wallet's day too, not just this one's.
+        const write = this.writeLock.then(async () => {
+            const run = await withSharedStateLock(this.stateFile, async () => {
+                const state = await this.readState();
+                const today = todayKey();
+                // Prune stale days so the file does not grow unbounded.
+                for (const a of Object.keys(state)) {
+                    for (const day of Object.keys(state[a])) {
+                        if (day !== today)
+                            delete state[a][day];
+                    }
+                    if (Object.keys(state[a]).length === 0)
+                        delete state[a];
                 }
-                if (Object.keys(state[a]).length === 0)
-                    delete state[a];
+                if (!state[addr])
+                    state[addr] = {};
+                if (!state[addr][today])
+                    state[addr][today] = { ustx: 0, sats: 0 };
+                state[addr][today][unit] += amt;
+                await this.writeState(state);
+            });
+            // The spend already happened on chain by the time record() is called, so
+            // an unavailable lease must not throw: that would turn a broadcast
+            // transaction into an unrecorded one. Write anyway and say so, because a
+            // silent under-count is the failure this whole lease exists to prevent.
+            if (!run.held) {
+                console.error(`[spend-limit] Recorded ${amt} ${unit} for ${addr} WITHOUT the shared lock: ` +
+                    `${run.unavailable} The daily total may under-count if another tool wrote ` +
+                    `concurrently.`);
             }
-            if (!state[addr])
-                state[addr] = {};
-            if (!state[addr][today])
-                state[addr][today] = { ustx: 0, sats: 0 };
-            state[addr][today][unit] += amt;
-            await this.writeState(state);
         });
-        await this.writeLock;
+        // A failed write must not poison the chain for every later record().
+        this.writeLock = write.catch(() => { });
+        await write;
     }
     /** Remaining session/day budget for status reporting. */
     async status(addr) {

package/dist/services/state-lock.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Cross-process lock for the shared `~/.aibtc` state files.
+ *
+ * `spend-state.json` has TWO writers: this server, and the aibtc skills engine's
+ * direct x402 payment path (aibtcdev/skills#423), which reads and writes the
+ * same file in the same shape so one wallet has one daily cap no matter which
+ * tool spends from it. Sharing the file is the point; sharing it without a lock
+ * is a lost update:
+ *
+ *   1. this server reads the day total and sees 100
+ *   2. the other tool takes its lock, reads 100, writes 150, releases
+ *   3. this server writes 130 from the copy it read in step 1
+ *
+ * The other tool's 50 is gone and the daily cap now UNDER-counts, which is the
+ * direction that lets a wallet spend past the cap it was supposed to share. An
+ * in-process promise chain cannot fix this: the other writer is another process.
+ *
+ * THE PROTOCOL HERE IS NOT OURS TO CHANGE UNILATERALLY. It is byte-compatible
+ * with `x402-guards.ts` in the skills engine so the two tools' leases are
+ * interchangeable — same lock directory name, same `owner` file format, same
+ * mtime heartbeat, same staleness window. A lock only excludes writers that
+ * agree on where it lives, so "x402-guards.lock" is deliberately kept even
+ * though nothing here is x402: renaming it on this side would silently return
+ * both tools to the race above while each believed it held a lock.
+ *
+ * A STALE LEASE IS NEVER RECLAIMED AUTOMATICALLY. Deleting a lock this process
+ * did not create needs an atomic "remove only if unchanged since I looked",
+ * which the filesystem does not offer; guessing wrong there is precisely the
+ * concurrent write the lock exists to prevent. A dead holder is reported with
+ * its pid and left for an operator, who can see whether it is really dead.
+ */
+/** Mutable so tests do not have to wait real seconds. */
+declare const timing: {
+    maxWaitMs: number;
+    staleMs: number;
+    heartbeatMs: number;
+    retryMs: number;
+};
+/** Test seam. Not part of the public contract. */
+export declare const _stateLockTesting: {
+    set(overrides: Partial<typeof timing>): void;
+    reset(): void;
+    lockDirFor: typeof lockDirFor;
+};
+/**
+ * The lease guarding a state file, derived from its directory so a test that
+ * redirects the state file redirects the lock with it.
+ */
+declare function lockDirFor(stateFile: string): string;
+export interface LockedRun<T> {
+    /** False when the body ran WITHOUT the lease. */
+    held: boolean;
+    /** Set when `held` is false: why the lease could not be taken. */
+    unavailable?: string;
+    value: T;
+}
+/**
+ * Run `fn` under the shared lease for `stateFile`.
+ *
+ * `fn` RUNS EITHER WAY. This guards a read-modify-write that records something
+ * which has ALREADY HAPPENED on chain, so refusing to run it would turn a
+ * broadcast transaction into an unrecorded one — strictly worse than the race
+ * it is trying to avoid. The caller is told which case it got and is expected
+ * to say so loudly rather than let an under-count pass silently.
+ *
+ * That is the deliberate difference from the skills engine, which takes this
+ * same lease and DOES refuse: there the lock guards a payment not yet signed,
+ * so refusing costs nothing but a retry. Authorising a future spend and
+ * recording a past one fail in opposite directions.
+ */
+export declare function withSharedStateLock<T>(stateFile: string, fn: () => Promise<T>): Promise<LockedRun<T>>;
+export {};
+//# sourceMappingURL=state-lock.d.ts.map