@aibtc/mcp-server 1.70.1 → 1.72.0

package/dist/index.js

@@ -4,13 +4,17 @@ import fs from "fs/promises";
 import path from "path";
 import os from "os";
 import { createRequire } from "module";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { randomBytes } from "crypto";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { McpServer } from "@modelcontextprotocol/server";
 import { registerAllTools } from "./tools/index.js";
+import { describeSelection, resolveToolSelection } from "./tools/profiles.js";
 import { installBountyHint } from "./tools/bounty-hint.js";
 import { NETWORK, API_URL } from "./config/index.js";
 import { redactSensitive } from "./utils/redact.js";
 import { initializeStorage } from "./utils/storage.js";
+import { getWalletManager } from "./services/wallet-manager.js";
+import { getLightningManager } from "./services/lightning-manager.js";
 const require = createRequire(import.meta.url);
 const packageJson = require("../package.json");
 // =============================================================================
@@ -64,30 +68,30 @@ async function writeJsonConfig(filePath, config) {
     await fs.writeFile(filePath, JSON.stringify(config, null, 2));
 }
 // Standard MCP server entry shared by every JSON-based client config.
-function serverEntry(network) {
+function serverEntry(env) {
     return {
         command: "npx",
         args: ["-y", SERVER_NPM],
-        env: { NETWORK: network },
+        env,
     };
 }
 // Most clients (Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI) use
 // the same `{ "mcpServers": { "aibtc": {...} } }` JSON shape.
-async function writeMcpServersJson(configPath, network) {
+async function writeMcpServersJson(configPath, env) {
     const config = await readJsonConfig(configPath);
     const servers = (config.mcpServers ??= {});
-    servers["aibtc"] = serverEntry(network);
+    servers["aibtc"] = serverEntry(env);
     await writeJsonConfig(configPath, config);
 }
 // VS Code (.vscode/mcp.json) uses a `servers` key and a typed stdio entry.
-async function writeVsCodeJson(configPath, network) {
+async function writeVsCodeJson(configPath, env) {
     const config = await readJsonConfig(configPath);
     const servers = (config.servers ??= {});
     servers["aibtc"] = {
         type: "stdio",
         command: "npx",
         args: ["-y", SERVER_NPM],
-        env: { NETWORK: network },
+        env,
     };
     await writeJsonConfig(configPath, config);
 }
@@ -106,7 +110,7 @@ function stripCodexSection(content) {
     }
     return out.join("\n");
 }
-async function writeCodexToml(configPath, network) {
+async function writeCodexToml(configPath, env) {
     let existing = "";
     try {
         existing = await fs.readFile(configPath, "utf8");
@@ -123,7 +127,7 @@ async function writeCodexToml(configPath, network) {
         `args = ["-y", "${SERVER_NPM}"]`,
         "",
         "[mcp_servers.aibtc.env]",
-        `NETWORK = "${network}"`,
+        ...Object.entries(env).map(([key, value]) => `${key} = "${value}"`),
     ].join("\n");
     const content = (preserved ? `${preserved}\n\n` : "") + block + "\n";
     await fs.mkdir(path.dirname(configPath), { recursive: true });
@@ -188,23 +192,86 @@ function resolveInstallTarget() {
     // Default to the entry explicitly marked as default (flag === null) — Claude Code.
     return matched[0] ?? INSTALL_TARGETS.find((t) => t.flag === null);
 }
+/**
+ * Create the agent's wallet during install so a fresh user can fund it right
+ * away. The generated password and the mnemonic are printed once and not
+ * stored in plain text; the password can be changed with wallet_rotate_password.
+ * Returns the Stacks address of the new or already-existing wallet.
+ */
+async function ensureInstallWallet(network) {
+    await initializeStorage();
+    const walletManager = getWalletManager();
+    const existing = (await walletManager.listWallets()).find((w) => w.network === network);
+    if (existing) {
+        console.log(`\n👛 Existing ${network} wallet kept: ${existing.name} (${existing.address})`);
+        return existing.address;
+    }
+    const password = randomBytes(18).toString("base64url");
+    const wallet = await walletManager.createWallet("main", password, network);
+    // Print the credentials before anything else can fail: the wallet is already
+    // on disk, and without the password it can never be unlocked.
+    console.log(`\n👛 Wallet created (${network}), stored encrypted in ~/.aibtc/`);
+    console.log(`   Stacks:    ${wallet.address}`);
+    if (wallet.btcAddress)
+        console.log(`   Bitcoin:   ${wallet.btcAddress}`);
+    console.log(`\n   Password:  ${password}`);
+    console.log(`   Mnemonic:  ${wallet.mnemonic}`);
+    console.log("\n⚠️  Write both down now. They are shown once and the password is not saved anywhere.");
+    console.log("   The password unlocks the wallet; change it any time by asking your agent to rotate it.");
+    console.log("   The mnemonic is the only way to recover the wallet and its funds.");
+    // Same unified setup as wallet_create: a Lightning wallet derived from the
+    // same mnemonic (mainnet only). Its failure is reported, the main wallet stands.
+    try {
+        const lightning = await getLightningManager().setupFromMainMnemonic(wallet.mnemonic, password, "main", network);
+        if (lightning.kind === "setup") {
+            console.log(`   Lightning: ${lightning.depositAddress} (deposit address, same mnemonic)`);
+        }
+    }
+    catch (error) {
+        console.error(`   Lightning setup failed: ${redactSensitive(error instanceof Error ? error.message : String(error))}. ` +
+            "Ask your agent to run lightning_create later.");
+    }
+    return wallet.address;
+}
 async function runInstall() {
     const network = process.argv.includes("--testnet") ? "testnet" : "mainnet";
+    // Only --profile full installs everything; resolving against AIBTC_TOOLS=core
+    // also validates the flag.
+    const fullProfile = resolveToolSelection(process.argv, { AIBTC_TOOLS: "core" }).all;
     const target = resolveInstallTarget();
     const configPath = target.configPath();
     console.log(`🔧 Installing @aibtc/mcp-server to ${target.label}...\n`);
-    await target.write(configPath, network);
+    const env = { NETWORK: network };
+    env.AIBTC_TOOLS = fullProfile ? "all" : "core";
+    await target.write(configPath, env);
     console.log("✅ Successfully installed!\n");
     console.log(`   Client:  ${target.label}`);
     console.log(`   Config:  ${configPath}`);
     console.log(`   Network: ${network}`);
-    console.log("\n📋 Next steps:");
-    console.log(`   1. ${target.restart}`);
-    console.log("   2. Ask the agent: \"What's your wallet address?\"");
-    console.log("   3. The agent will guide you through wallet setup\n");
-    if (network === "testnet") {
-        console.log("💡 Tip: Get testnet STX at https://explorer.hiro.so/sandbox/faucet?chain=testnet\n");
+    console.log(`   Tools:   ${fullProfile ? "all" : "lean core (set AIBTC_TOOLS=core,defi,ordinals,... in the env, or re-run with --profile full)"}`);
+    // The wallet's password and mnemonic are printed once, so only create it when
+    // a person is reading the terminal, never into a pipe, file or CI log.
+    let address = null;
+    if (process.argv.includes("--no-wallet")) {
+        // Explicitly skipped
+    }
+    else if (!process.stdout.isTTY) {
+        console.log("\n👛 Wallet not created: output is not a terminal, and the password and mnemonic");
+        console.log("   are only ever printed to one. Re-run --install in a terminal, or ask the agent to create one.");
+    }
+    else {
+        address = await ensureInstallWallet(network);
     }
+    console.log(`\n📋 ${target.restart}, then try:`);
+    const fund = network === "testnet"
+        ? "testnet STX from https://explorer.hiro.so/sandbox/faucet?chain=testnet"
+        : "0.01 STX";
+    console.log(address
+        ? `   1. Send ${fund} to ${address}`
+        : `   1. Ask your agent: "What's your wallet address?" and send it ${fund}`);
+    console.log(`   2. Ask your agent: "Unlock my wallet" and give it the password`);
+    const x402Host = network === "testnet" ? "x402.aibtc.dev" : "x402.aibtc.com";
+    console.log(`   3. Ask it: "Make a paid inference call on ${x402Host}" (0.001 STX per call)\n`);
 }
 // =============================================================================
 // YIELD HUNTER DAEMON
@@ -251,36 +318,45 @@ else if (process.argv.includes("--install") || process.argv.includes("install"))
 }
 else {
     // Normal MCP server mode
-    const server = new McpServer({
-        name: "aibtc-mcp-server",
-        version: packageJson.version,
-    }, {
-        instructions: [
-            "This server lets an agent earn and move real Bitcoin/sBTC on Stacks.",
-            "",
-            "Hunt bounties. The most direct way to earn here is the sBTC bounty board:",
-            "call bounty_list to see open bounties, bounty_get for the task detail, do",
-            "the work, then bounty_submit your deliverable. Accepted submissions are paid",
-            "in sBTC. Check periodically for new open bounties.",
-            "",
-            "For the full menu of ways to put assets to work (stacking, DeFi yield,",
-            "trading, paid endpoints), call earning_opportunities. Submitting to a bounty",
-            "requires a Registered (L1+) on-chain identity — see identity_register.",
-        ].join("\n"),
-    });
-    // Append a bounty-board hint to spend/onboarding-tool output.
-    // Must wrap registerTool before registration; restore it after.
-    const restoreBountyHint = installBountyHint(server);
-    // Register all tools from the modular registry
-    registerAllTools(server);
-    restoreBountyHint();
+    // One instance per connection. serveStdio picks the protocol era from the
+    // opening message (2025-era `initialize` or a 2026-07-28 envelope) and pins
+    // the instance built by this factory to the connection.
+    function createServer(toolSelection) {
+        const server = new McpServer({
+            name: "aibtc-mcp-server",
+            version: packageJson.version,
+        }, {
+            instructions: [
+                "This server lets an agent earn and move real Bitcoin/sBTC on Stacks.",
+                "",
+                "Hunt bounties. The most direct way to earn here is the sBTC bounty board:",
+                "call bounty_list to see open bounties, bounty_get for the task detail, do",
+                "the work, then bounty_submit your deliverable. Accepted submissions are paid",
+                "in sBTC. Check periodically for new open bounties.",
+                "",
+                "For the full menu of ways to put assets to work (stacking, DeFi yield,",
+                "trading, paid endpoints), call earning_opportunities. Submitting to a bounty",
+                "requires a Registered (L1+) on-chain identity — see identity_register.",
+                "",
+                describeSelection(toolSelection),
+            ].join("\n"),
+        });
+        // Append a bounty-board hint to spend/onboarding-tool output.
+        // Must wrap registerTool before registration; restore it after.
+        const restoreBountyHint = installBountyHint(server);
+        // Register all tools from the modular registry
+        registerAllTools(server, toolSelection);
+        restoreBountyHint();
+        return server;
+    }
     async function main() {
+        const toolSelection = resolveToolSelection();
         await initializeStorage();
-        const transport = new StdioServerTransport();
-        await server.connect(transport);
+        serveStdio(() => createServer(toolSelection), { onerror: (error) => console.error("MCP error:", redactSensitive(String(error))) });
         console.error("aibtc-mcp-server running on stdio");
         console.error(`Network: ${NETWORK}`);
         console.error(`API URL: ${API_URL}`);
+        console.error(`Tools: ${toolSelection.all ? "all" : ["core", ...toolSelection.groups].join(", ")}`);
     }
     main().catch((error) => {
         console.error("Fatal error:", redactSensitive(String(error)));

package/dist/services/stacking.service.d.ts

@@ -1,58 +1,157 @@
-import { PoxInfo } from "./hiro-api.js";
+/**
+ * PoX-5 stacking.
+ *
+ * PoX-5 replaced pox-4 at reward cycle 141 on mainnet, and it is not a rename:
+ *
+ * - Every stake names a SIGNER MANAGER, a contract implementing pox-5's
+ *   `signer-manager-trait`. There is no pool delegation (`delegate-stx`) and no
+ *   PoX reward address on the stake itself; the manager's `validate-stake!`
+ *   decides who may join and reads any payout preferences out of
+ *   `signer-calldata`.
+ * - Rewards are paid in sBTC to the signer manager, not the staker. Getting a
+ *   staker paid takes the manager pulling its share out of pox-5
+ *   (`manager.claim-rewards`) and then paying the staker
+ *   (`manager.claim-staker-rewards`). Each manager implements that second step
+ *   its own way, and some pay out off-chain, so the claim path is read from the
+ *   manager's interface rather than assumed.
+ * - `stake`, `stake-update` and `unstake` are refused during the prepare phase
+ *   (the last `prepare-cycle-length` blocks of a cycle).
+ *
+ * Locking STX is not a transfer, so these calls carry pox-5's own post-condition
+ * types (a staking lock amount, or "performs PoX") rather than STX transfer
+ * conditions, and they are not metered against the spend limit.
+ */
 import { type Network } from "../config/index.js";
 import { type Account, type TransferResult } from "../transactions/builder.js";
-export interface StackingStatus {
-    stacked: boolean;
-    amountMicroStx: string;
-    amountStx: string;
+/** pox-5 `MAX_NUM_CYCLES`. */
+export declare const MAX_STAKE_CYCLES = 96;
+export interface PoxState {
+    contractId: string;
+    burnHeight: number;
+    rewardCycle: number;
+    firstBurnHeight: number;
+    rewardCycleLength: number;
+    prepareCycleLength: number;
+    /** Burn height where the next reward cycle begins. */
+    nextCycleStartHeight: number;
+    /** Burn height where this cycle's prepare phase begins. */
+    preparePhaseStartHeight: number;
+    inPreparePhase: boolean;
+    /** Minimum a signer needs delegated to join the signer set (not a per-staker minimum). */
+    signerSetMinUstx: bigint;
+    totalLiquidSupplyUstx: bigint;
+}
+export interface StakerInfo {
+    amountUstx: bigint;
     firstRewardCycle: number;
-    lockPeriod: number;
-    unlockHeight: number;
-    poxAddress?: string;
+    numCycles: number;
+    /** First cycle in which the STX is unlocked. */
+    unlockCycle: number;
+    unlockBurnHeight: number;
+    signerManager: string;
+}
+export interface BondMembership {
+    bondIndex: number;
+    amountUstx: bigint;
+    amountSats: bigint;
+    isL1Lock: boolean;
+    signerManager: string;
+}
+export interface StakingStatus {
+    address: string;
+    pox: PoxState;
+    staking: StakerInfo | null;
+    bond: BondMembership | null;
+    account: {
+        balanceUstx: bigint;
+        lockedUstx: bigint;
+        unlockedUstx: bigint;
+        burnchainUnlockHeight: number;
+    };
+}
+export interface SignerSetEntry {
+    signerManager: string;
+    delegatedUstx: bigint;
+}
+/**
+ * How a signer manager pays its stakers, read from its public interface.
+ * - `staker-arg`: `claim-staker-rewards(staker, reward-cycle, bond-index)`, callable by anyone
+ * - `caller`:     `claim-staker-rewards(reward-cycle, bond-index)`, pays the caller
+ * - `none`:       no on-chain staker claim (the manager pays off-chain, or not at all)
+ */
+export type ClaimStyle = "staker-arg" | "caller" | "none";
+export interface StakeOptions {
+    signerManager: string;
+    amountUstx: bigint;
+    numCycles: number;
+    signerCalldata?: Uint8Array;
 }
+export interface UpdateStakeOptions {
+    /** New signer manager; defaults to the current one. */
+    signerManager?: string;
+    cyclesToExtend: number;
+    amountIncreaseUstx: bigint;
+    signerCalldata?: Uint8Array;
+}
+/**
+ * Payout calldata in the shape reference signer managers decode:
+ * `{ pox-addr: { version, hashbytes }, max-fee }`. Managers derived from the
+ * pox-5 reference implementation use it to pay rewards to a Bitcoin address via
+ * an sBTC withdrawal, capped at `max-fee` sats of withdrawal fee. Whether a given
+ * manager accepts it is up to that manager's `validate-stake!`.
+ */
+export declare function buildPayoutCalldata(poxAddr: {
+    version: number;
+    hashbytesHex: string;
+}, maxFeeSats: bigint): Uint8Array;
 export declare class StackingService {
     private network;
     private hiro;
-    private contracts;
+    private poxContract;
     constructor(network: Network);
+    get contractId(): string;
+    private read;
+    private readPox;
+    getPoxState(): Promise<PoxState>;
+    private rewardCycleStartHeight;
+    getStakerInfo(address: string, pox?: PoxState): Promise<StakerInfo | null>;
+    getBondMembership(address: string): Promise<BondMembership | null>;
+    getStakingStatus(address: string): Promise<StakingStatus>;
+    /** Whether pox-5 has a signer key registered for this manager. */
+    isRegisteredSigner(signerManager: string): Promise<boolean>;
+    /** Walk pox-5's signer-set linked list for a reward cycle. */
+    getSignerSet(cycle: number): Promise<SignerSetEntry[]>;
+    getClaimStyle(signerManager: string): Promise<ClaimStyle>;
+    /** sBTC the staker has earned from this signer for a cycle and not yet claimed (before manager fees). */
+    getStakerUnclaimedRewards(signerManager: string, rewardCycle: number, staker: string): Promise<bigint>;
+    /** sBTC pox-5 still holds for the signer manager for a cycle (not yet pulled by the manager). */
+    getSignerUnpulledRewards(signerManager: string, rewardCycle: number): Promise<bigint>;
+    private assertNotPreparePhase;
+    stake(account: Account, options: StakeOptions): Promise<TransferResult & {
+        pox: PoxState;
+        unlockCycle: number;
+        unlockBurnHeight: number;
+    }>;
+    updateStake(account: Account, options: UpdateStakeOptions): Promise<TransferResult & {
+        previous: StakerInfo;
+        newAmountUstx: bigint;
+        signerManager: string;
+        unlockCycle: number;
+        unlockBurnHeight: number;
+    }>;
+    unstake(account: Account): Promise<TransferResult & {
+        previous: StakerInfo;
+        unlockCycle: number;
+        unlockBurnHeight: number;
+    }>;
     /**
-     * Get current PoX (Proof of Transfer) info
-     */
-    getPoxInfo(): Promise<PoxInfo>;
-    /**
-     * Get stacking status for an address
-     * Note: Returns whether the address is stacking, but detailed amounts require proper CV parsing
-     */
-    getStackingStatus(address: string): Promise<StackingStatus>;
-    /**
-     * Stack STX tokens
-     */
-    stack(account: Account, amount: bigint, poxAddress: {
-        version: number;
-        hashbytes: string;
-    }, startBurnHeight: number, lockPeriod: number): Promise<TransferResult>;
-    /**
-     * Extend stacking period
-     */
-    extendStacking(account: Account, extendCount: number, poxAddress: {
-        version: number;
-        hashbytes: string;
-    }): Promise<TransferResult>;
-    /**
-     * Increase stacking amount
-     */
-    increaseStacking(account: Account, increaseAmount: bigint): Promise<TransferResult>;
-    /**
-     * Delegate STX to a stacking pool
-     */
-    delegateStx(account: Account, amount: bigint, delegateTo: string, untilBurnHeight?: number, poxAddress?: {
-        version: number;
-        hashbytes: string;
-    }): Promise<TransferResult>;
-    /**
-     * Revoke delegation
+     * Have the signer manager pull its STX-staking rewards for a cycle out of pox-5.
+     * Permissionless on reference managers. An empty bond-period list claims the
+     * STX-staker bucket only, which is all an STX staker's payout draws on.
      */
-    revokeDelegation(account: Account): Promise<TransferResult>;
+    pullSignerRewards(account: Account, signerManager: string, rewardCycle: number, unpulledSats: bigint): Promise<TransferResult>;
+    /** Pay this staker their share of a cycle's rewards through the signer manager. */
+    claimStakerRewards(account: Account, signerManager: string, rewardCycle: number, style: Exclude<ClaimStyle, "none">): Promise<TransferResult>;
 }
 export declare function getStackingService(network: Network): StackingService;
 //# sourceMappingURL=stacking.service.d.ts.map