@aibtc/mcp-server 1.70.0 → 1.71.0

package/dist/tools/pillar-direct.tools.js

@@ -88,6 +88,21 @@ function formatSigAuthForApi(sigAuth) {
             : "0x" + sigAuth.pubkey,
     };
 }
+/**
+ * The Pillar smart wallet's Fast Pool functions are hardcoded to pox-4
+ * (`pox-4.allow-contract-caller` + `pox4-fast-pool-v3.delegate-stx`, and
+ * `pox-4.revoke-delegate-stx`). Once PoX has moved past pox-4 those calls abort
+ * on chain, so refuse before signing instead of burning gas on a sure failure.
+ */
+async function assertFastPoolPoxActive(action) {
+    const pox = await getHiroApi(NETWORK).getPoxInfo();
+    if (!pox.contract_id.endsWith(".pox-4")) {
+        throw new Error(`${action} is unavailable: the Pillar smart wallet's Fast Pool path calls pox-4, but the ` +
+            `active PoX contract is ${pox.contract_id}, so the transaction would abort on chain. ` +
+            `This needs a Pillar wallet contract update. For STX staking on PoX-5, use stack_stx ` +
+            `with a signer manager (see list_stacking_signers).`);
+    }
+}
 // ============================================================================
 // Tool Registration
 // ============================================================================
@@ -1041,7 +1056,8 @@ export function registerPillarDirectTools(server) {
     server.registerTool("pillar_direct_stack_stx", {
         description: "Stack STX from your Pillar smart wallet via Fast Pool or Stacking DAO. " +
             "Agent-signed, no browser needed. Backend sponsors gas. " +
-            "Fast Pool delegates STX to the pox4-fast-pool-v3 contract. " +
+            "Fast Pool delegates STX to the pox4-fast-pool-v3 contract through pox-4, and is refused while " +
+            "pox-4 is not the active PoX contract (PoX-5 is live; use stack_stx for PoX-5 staking). " +
             "Stacking DAO deposits STX into Stacking DAO core for stSTX yield. " +
             "Your wallet must be enrolled in dual stacking first (automatic for v2 wallets with sBTC).",
         inputSchema: {
@@ -1056,6 +1072,9 @@ export function registerPillarDirectTools(server) {
         },
     }, async ({ stxAmount, pool }) => {
         try {
+            if (pool === "fast-pool") {
+                await assertFastPoolPoxActive("Fast Pool stacking");
+            }
             const { keyService, session } = await requireActiveKey();
             const authId = generateAuthId();
             // Build SIP-018 structured data matching the contract's hash builder.
@@ -1099,12 +1118,14 @@ export function registerPillarDirectTools(server) {
     });
     // --- pillar_direct_revoke_fast_pool ---
     server.registerTool("pillar_direct_revoke_fast_pool", {
-        description: "Revoke Fast Pool STX delegation from your Pillar smart wallet. " +
+        description: "Revoke Fast Pool STX delegation from your Pillar smart wallet (pox-4 revoke-delegate-stx; " +
+            "refused while pox-4 is not the active PoX contract). " +
             "Agent-signed, no browser needed. Backend sponsors gas. " +
             "After revoking, STX stays locked until the current PoX cycle ends, then returns to liquid.",
         inputSchema: {},
     }, async () => {
         try {
+            await assertFastPoolPoxActive("Revoking Fast Pool");
             const { keyService, session } = await requireActiveKey();
             const authId = generateAuthId();
             const structuredData = tupleCV({

package/dist/tools/sbtc.tools.js

@@ -1,4 +1,3 @@
-import * as btc from "@scure/btc-signer";
 import { z } from "zod";
 import { getAccount, getWalletAddress, NETWORK } from "../services/x402.service.js";
 import { getSbtcService } from "../services/sbtc.service.js";
@@ -8,26 +7,8 @@ import { getContracts, parseContractId } from "../config/contracts.js";
 import { createJsonResponse, createErrorResponse, resolveFee } from "../utils/index.js";
 import { getWalletManager } from "../services/wallet-manager.js";
 import { MempoolApi, getMempoolTxUrl } from "../services/mempool-api.js";
-import { getBtcNetwork } from "../transactions/bitcoin-builder.js";
 import { sponsoredSchema } from "./schemas.js";
-function parseBtcRecipientTuple(btcRecipientAddress) {
-    const decoded = btc.Address(getBtcNetwork(NETWORK)).decode(btcRecipientAddress);
-    if (decoded.type === "tr" && decoded.pubkey) {
-        return { version: 0x06, hashbytesHex: Buffer.from(decoded.pubkey).toString("hex") };
-    }
-    switch (decoded.type) {
-        case "pkh":
-            return { version: 0x00, hashbytesHex: Buffer.from(decoded.hash).toString("hex") };
-        case "sh":
-            return { version: 0x01, hashbytesHex: Buffer.from(decoded.hash).toString("hex") };
-        case "wpkh":
-            return { version: 0x04, hashbytesHex: Buffer.from(decoded.hash).toString("hex") };
-        case "wsh":
-            return { version: 0x05, hashbytesHex: Buffer.from(decoded.hash).toString("hex") };
-        default:
-            throw new Error("Unsupported BTC recipient address type. Supported: P2PKH, P2SH, P2WPKH, P2WSH, P2TR.");
-    }
-}
+import { btcAddressToPoxAddr } from "../utils/bitcoin.js";
 function getReadonlySenderAddress() {
     const contracts = getContracts(NETWORK);
     return parseContractId(contracts.SBTC_REGISTRY).address;
@@ -107,7 +88,7 @@ Example: To send 0.001 sBTC, use amount "100000" (satoshis).`,
         const sbtcService = getSbtcService(NETWORK);
         const account = await getAccount();
         const resolvedFee = await resolveFee(fee, NETWORK, "contract_call");
-        const recipientTuple = parseBtcRecipientTuple(btcRecipientAddress);
+        const recipientTuple = btcAddressToPoxAddr(btcRecipientAddress, NETWORK);
         const result = await sbtcService.initiateWithdrawal(account, BigInt(amount), BigInt(maxFee), recipientTuple, resolvedFee, sponsored);
         let requestId = null;
         try {

package/dist/tools/skill-mappings.js

@@ -68,6 +68,10 @@ export const TOOL_SKILL_MAP = {
     get_stacking_status: "stacking",
     stack_stx: "stacking",
     extend_stacking: "stacking",
+    list_stacking_signers: "stacking",
+    unstake_stx: "stacking",
+    get_stacking_rewards: "stacking",
+    claim_stacking_rewards: "stacking",
     // dual-stacking skill — sBTC Dual Stacking yield protocol
     dual_stacking_status: "dual-stacking",
     dual_stacking_get_rewards: "dual-stacking",
@@ -225,8 +229,6 @@ export const TOOL_SKILL_MAP = {
     taproot_verify_cosig: "ordinals-p2p",
     taproot_multisig_guide: "ordinals-p2p",
     // identity skill — ERC-8004 on-chain agent identity
-    register_identity: "identity",
-    get_identity: "identity",
     identity_get_last_id: "identity",
     identity_get: "identity",
     identity_get_metadata: "identity",
@@ -238,12 +240,7 @@ export const TOOL_SKILL_MAP = {
     identity_unset_wallet: "identity",
     identity_transfer: "identity",
     // reputation skill — ERC-8004 on-chain agent reputation
-    give_feedback: "reputation",
-    get_reputation: "reputation",
     // validation skill — ERC-8004 on-chain agent validation
-    request_validation: "validation",
-    get_validation_status: "validation",
-    get_validation_summary: "validation",
     // stackspot skill — stacking lottery pots
     stackspot_list_pots: "stackspot",
     stackspot_get_pot_state: "stackspot",

package/dist/tools/stacking.tools.js

@@ -1,107 +1,415 @@
 import { z } from "zod";
 import { getAccount, getWalletAddress, NETWORK } from "../services/x402.service.js";
-import { getStackingService } from "../services/stacking.service.js";
+import { MAX_STAKE_CYCLES, buildPayoutCalldata, getStackingService, } from "../services/stacking.service.js";
 import { getExplorerTxUrl } from "../config/networks.js";
 import { createJsonResponse, createErrorResponse } from "../utils/index.js";
+import { btcAddressToPoxAddr } from "../utils/bitcoin.js";
+const POX5_NOTE = "PoX-5: every stake names a signer manager contract; rewards are paid in sBTC through that manager.";
+function stx(ustx) {
+    const whole = ustx / 1000000n;
+    const frac = (ustx % 1000000n).toString().padStart(6, "0");
+    return `${whole}.${frac} STX`;
+}
+function poxSummary(pox) {
+    return {
+        contract: pox.contractId,
+        burnHeight: pox.burnHeight,
+        rewardCycle: pox.rewardCycle,
+        nextCycleStartHeight: pox.nextCycleStartHeight,
+        preparePhaseStartHeight: pox.preparePhaseStartHeight,
+        inPreparePhase: pox.inPreparePhase,
+    };
+}
+function stakerSummary(info) {
+    return {
+        signerManager: info.signerManager,
+        amountUstx: info.amountUstx.toString(),
+        amount: stx(info.amountUstx),
+        firstRewardCycle: info.firstRewardCycle,
+        numCycles: info.numCycles,
+        unlockCycle: info.unlockCycle,
+        unlockBurnHeight: info.unlockBurnHeight,
+    };
+}
+const payoutInputs = {
+    btcRewardAddress: z
+        .string()
+        .optional()
+        .describe("Optional Bitcoin address to receive rewards. Encoded as `{ pox-addr, max-fee }` signer calldata, " +
+        "the shape reference signer managers (e.g. Xverse, Fast Pool) use to pay rewards to BTC via an " +
+        "sBTC withdrawal. Some managers require it (PlanBetter), some ignore it (native-pool). " +
+        "Omit to receive sBTC where the manager supports that."),
+    maxWithdrawalFeeSats: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("Max sBTC withdrawal fee (sats) per payout when btcRewardAddress is set. Default 3000."),
+    signerCalldataHex: z
+        .string()
+        .optional()
+        .describe("Advanced: raw signer calldata (hex, max 500 bytes) for managers with a custom format. " +
+        "Cannot be combined with btcRewardAddress."),
+};
+function resolveCalldata(input) {
+    if (input.btcRewardAddress && input.signerCalldataHex) {
+        throw new Error("Pass either btcRewardAddress or signerCalldataHex, not both.");
+    }
+    if (input.btcRewardAddress) {
+        return buildPayoutCalldata(btcAddressToPoxAddr(input.btcRewardAddress, NETWORK), BigInt(input.maxWithdrawalFeeSats ?? 3000));
+    }
+    if (input.signerCalldataHex) {
+        const hex = input.signerCalldataHex.replace(/^0x/, "");
+        if (!/^([0-9a-fA-F]{2})*$/.test(hex)) {
+            throw new Error("signerCalldataHex must be an even-length hex string.");
+        }
+        return Uint8Array.from(Buffer.from(hex, "hex"));
+    }
+    return undefined;
+}
 export function registerStackingTools(server) {
-    // Get PoX info
+    // --- get_pox_info ---
     server.registerTool("get_pox_info", {
-        description: "Get current Proof of Transfer (PoX) cycle information.",
+        description: "Current PoX-5 state: reward cycle, burn height, next cycle start, and whether the prepare " +
+            "phase is active (stake, extend and unstake are refused during it).",
     }, async () => {
         try {
-            const stackingService = getStackingService(NETWORK);
-            const poxInfo = await stackingService.getPoxInfo();
+            const pox = await getStackingService(NETWORK).getPoxState();
             return createJsonResponse({
                 network: NETWORK,
-                currentCycle: poxInfo.current_cycle,
-                nextCycle: poxInfo.next_cycle,
-                minAmountUstx: poxInfo.min_amount_ustx,
-                rewardCycleLength: poxInfo.reward_cycle_length,
-                prepareCycleLength: poxInfo.prepare_cycle_length,
-                currentBurnchainBlockHeight: poxInfo.current_burnchain_block_height,
-                totalLiquidSupplyUstx: poxInfo.total_liquid_supply_ustx,
+                ...poxSummary(pox),
+                firstBurnHeight: pox.firstBurnHeight,
+                rewardCycleLength: pox.rewardCycleLength,
+                prepareCycleLength: pox.prepareCycleLength,
+                signerSetMinUstx: pox.signerSetMinUstx.toString(),
+                totalLiquidSupplyUstx: pox.totalLiquidSupplyUstx.toString(),
+                note: POX5_NOTE,
             });
         }
         catch (error) {
             return createErrorResponse(error);
         }
     });
-    // Get stacking status
+    // --- get_stacking_status ---
     server.registerTool("get_stacking_status", {
-        description: "Check if an address is currently stacking STX.",
+        description: "PoX-5 staking status for an address: locked amount, signer manager, lock period, unlock " +
+            "cycle and burn height, any protocol bond membership, and locked/unlocked STX balance.",
         inputSchema: {
             address: z
                 .string()
                 .optional()
-                .describe("Wallet address to check. Uses configured wallet if not provided."),
+                .describe("Stacks address to check. Uses the active wallet if omitted."),
         },
     }, async ({ address }) => {
         try {
-            const stackingService = getStackingService(NETWORK);
             const walletAddress = address || (await getWalletAddress());
-            const status = await stackingService.getStackingStatus(walletAddress);
+            const status = await getStackingService(NETWORK).getStakingStatus(walletAddress);
             return createJsonResponse({
                 address: walletAddress,
                 network: NETWORK,
-                ...status,
+                staking: status.staking !== null,
+                stake: status.staking ? stakerSummary(status.staking) : null,
+                bond: status.bond
+                    ? {
+                        bondIndex: status.bond.bondIndex,
+                        signerManager: status.bond.signerManager,
+                        amountUstx: status.bond.amountUstx.toString(),
+                        amountSats: status.bond.amountSats.toString(),
+                        isL1Lock: status.bond.isL1Lock,
+                    }
+                    : null,
+                balance: {
+                    totalUstx: status.account.balanceUstx.toString(),
+                    lockedUstx: status.account.lockedUstx.toString(),
+                    unlockedUstx: status.account.unlockedUstx.toString(),
+                    burnchainUnlockHeight: status.account.burnchainUnlockHeight,
+                },
+                pox: poxSummary(status.pox),
             });
         }
         catch (error) {
             return createErrorResponse(error);
         }
     });
-    // Stack STX
+    // --- list_stacking_signers ---
+    server.registerTool("list_stacking_signers", {
+        description: "List PoX-5 signer managers in the signer set for a reward cycle (default: next cycle), with " +
+            "the STX delegated to each. A signer manager is what stack_stx stakes with. Only signers with " +
+            "at least the signer-set minimum delegated appear here; other registered managers can still be " +
+            "staked with by contract id. Set withPayoutInfo to see how each manager pays stakers (slower).",
+        inputSchema: {
+            rewardCycle: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Reward cycle to list. Defaults to the next cycle (the one a new stake joins)."),
+            withPayoutInfo: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Also read each manager's claim path (one extra request per signer)."),
+        },
+    }, async ({ rewardCycle, withPayoutInfo }) => {
+        try {
+            const service = getStackingService(NETWORK);
+            const pox = await service.getPoxState();
+            const cycle = rewardCycle ?? pox.rewardCycle + 1;
+            const signers = (await service.getSignerSet(cycle)).sort((a, b) => b.delegatedUstx > a.delegatedUstx ? 1 : b.delegatedUstx < a.delegatedUstx ? -1 : 0);
+            const rows = [];
+            for (const s of signers) {
+                rows.push({
+                    signerManager: s.signerManager,
+                    delegatedUstx: s.delegatedUstx.toString(),
+                    delegated: stx(s.delegatedUstx),
+                    ...(withPayoutInfo && { stakerClaim: await service.getClaimStyle(s.signerManager) }),
+                });
+            }
+            return createJsonResponse({
+                network: NETWORK,
+                rewardCycle: cycle,
+                count: rows.length,
+                signers: rows,
+                ...(withPayoutInfo && {
+                    stakerClaimKey: {
+                        "staker-arg": "on-chain; claim_stacking_rewards works",
+                        caller: "on-chain; claim_stacking_rewards works (paid to the caller)",
+                        none: "no on-chain staker claim; the manager pays off-chain or not at all",
+                    },
+                }),
+                note: "Managers can restrict who may stake (allowlists, minimums, required payout calldata). " +
+                    "Check a manager's own terms before staking; a refused stake aborts on chain.",
+            });
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // --- stack_stx ---
     server.registerTool("stack_stx", {
-        description: `Lock STX for stacking to earn BTC rewards.
+        description: `Lock STX in PoX-5 with a signer manager to earn sBTC rewards.
 
-Requires a Bitcoin address (hash) for receiving rewards.`,
+The lock starts next reward cycle and lasts numCycles cycles (1-${MAX_STAKE_CYCLES}). Pick a signer manager with list_stacking_signers. Refused during the prepare phase and if the address is already staking (use extend_stacking). Locking is not a transfer: the transaction carries a staking post-condition for exactly the locked amount.`,
         inputSchema: {
-            amount: z.string().describe("Amount of STX to stack (in micro-STX)"),
-            poxAddressVersion: z.number().describe("Bitcoin address version (0 for P2PKH, 1 for P2SH, etc.)"),
-            poxAddressHashbytes: z.string().describe("Bitcoin address hash (hex string)"),
-            startBurnHeight: z.number().describe("Bitcoin block height to start stacking"),
-            lockPeriod: z.number().min(1).max(12).describe("Number of reward cycles to lock (1-12)"),
+            signerManager: z
+                .string()
+                .describe("Signer manager contract id, e.g. SP8HK160YD5GHXP69VGA0TC7AQJ1X4CDW3XVERSE.xverse-signer-manager-2"),
+            amount: z.string().describe("Amount to lock, in micro-STX"),
+            numCycles: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_STAKE_CYCLES)
+                .describe(`Reward cycles to lock (1-${MAX_STAKE_CYCLES}; one cycle is about two weeks)`),
+            ...payoutInputs,
         },
-    }, async ({ amount, poxAddressVersion, poxAddressHashbytes, startBurnHeight, lockPeriod }) => {
+    }, async ({ signerManager, amount, numCycles, ...payout }) => {
         try {
-            const stackingService = getStackingService(NETWORK);
             const account = await getAccount();
-            const result = await stackingService.stack(account, BigInt(amount), { version: poxAddressVersion, hashbytes: poxAddressHashbytes }, startBurnHeight, lockPeriod);
+            const result = await getStackingService(NETWORK).stake(account, {
+                signerManager,
+                amountUstx: BigInt(amount),
+                numCycles,
+                signerCalldata: resolveCalldata(payout),
+            });
             return createJsonResponse({
                 success: true,
                 txid: result.txid,
-                stacker: account.address,
-                amount,
-                lockPeriod,
-                startBurnHeight,
-                network: NETWORK,
                 explorerUrl: getExplorerTxUrl(result.txid, NETWORK),
+                staker: account.address,
+                signerManager,
+                amountUstx: amount,
+                amount: stx(BigInt(amount)),
+                firstRewardCycle: result.pox.rewardCycle + 1,
+                numCycles,
+                unlockCycle: result.unlockCycle,
+                unlockBurnHeight: result.unlockBurnHeight,
+                rewardPayout: payout.btcRewardAddress
+                    ? `BTC to ${payout.btcRewardAddress} (if the manager supports it)`
+                    : payout.signerCalldataHex
+                        ? "custom signer calldata"
+                        : "sBTC (if the manager supports it)",
+                network: NETWORK,
             });
         }
         catch (error) {
             return createErrorResponse(error);
         }
     });
-    // Extend stacking
+    // --- extend_stacking ---
     server.registerTool("extend_stacking", {
-        description: "Extend an existing stacking lock period.",
+        description: `Update an existing PoX-5 stake: extend the lock, add STX, switch signer manager, or change payout calldata (pox-5 stake-update).
+
+Any combination in one call. Increasing locks more of the address's unlocked STX. Refused during the prepare phase. The lock may not run more than ${MAX_STAKE_CYCLES} cycles past the next cycle.`,
         inputSchema: {
-            extendCount: z.number().min(1).max(12).describe("Number of additional cycles to lock"),
-            poxAddressVersion: z.number().describe("Bitcoin address version"),
-            poxAddressHashbytes: z.string().describe("Bitcoin address hash (hex string)"),
+            cyclesToExtend: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .default(0)
+                .describe("Cycles to add to the current unlock cycle"),
+            amountIncrease: z
+                .string()
+                .optional()
+                .default("0")
+                .describe("Additional micro-STX to lock"),
+            signerManager: z
+                .string()
+                .optional()
+                .describe("New signer manager contract id. Defaults to the current one."),
+            ...payoutInputs,
         },
-    }, async ({ extendCount, poxAddressVersion, poxAddressHashbytes }) => {
+    }, async ({ cyclesToExtend, amountIncrease, signerManager, ...payout }) => {
         try {
-            const stackingService = getStackingService(NETWORK);
             const account = await getAccount();
-            const result = await stackingService.extendStacking(account, extendCount, { version: poxAddressVersion, hashbytes: poxAddressHashbytes });
+            const result = await getStackingService(NETWORK).updateStake(account, {
+                signerManager,
+                cyclesToExtend,
+                amountIncreaseUstx: BigInt(amountIncrease),
+                signerCalldata: resolveCalldata(payout),
+            });
             return createJsonResponse({
                 success: true,
                 txid: result.txid,
-                stacker: account.address,
-                extendCount,
+                explorerUrl: getExplorerTxUrl(result.txid, NETWORK),
+                staker: account.address,
+                previous: stakerSummary(result.previous),
+                signerManager: result.signerManager,
+                newAmountUstx: result.newAmountUstx.toString(),
+                newAmount: stx(result.newAmountUstx),
+                unlockCycle: result.unlockCycle,
+                unlockBurnHeight: result.unlockBurnHeight,
                 network: NETWORK,
+            });
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // --- unstake_stx ---
+    server.registerTool("unstake_stx", {
+        description: "Stop a PoX-5 stake early (pox-5 unstake). The STX stays locked through the current reward " +
+            "cycle and unlocks at the start of the next one. Refused during the prepare phase.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const account = await getAccount();
+            const result = await getStackingService(NETWORK).unstake(account);
+            return createJsonResponse({
+                success: true,
+                txid: result.txid,
                 explorerUrl: getExplorerTxUrl(result.txid, NETWORK),
+                staker: account.address,
+                previous: stakerSummary(result.previous),
+                unlockCycle: result.unlockCycle,
+                unlockBurnHeight: result.unlockBurnHeight,
+                network: NETWORK,
+            });
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // --- get_stacking_rewards ---
+    server.registerTool("get_stacking_rewards", {
+        description: "PoX-5 sBTC rewards an address has earned from its signer manager for one reward cycle and not " +
+            "yet claimed (before the manager's fees), whether the manager still has to pull them from pox-5, " +
+            "and whether the manager supports an on-chain staker claim.",
+        inputSchema: {
+            rewardCycle: z.number().int().nonnegative().describe("Reward cycle to check"),
+            address: z
+                .string()
+                .optional()
+                .describe("Stacks address. Uses the active wallet if omitted."),
+            signerManager: z
+                .string()
+                .optional()
+                .describe("Signer manager to check. Defaults to the address's current signer manager."),
+        },
+    }, async ({ rewardCycle, address, signerManager }) => {
+        try {
+            const service = getStackingService(NETWORK);
+            const staker = address || (await getWalletAddress());
+            const manager = signerManager ?? (await service.getStakerInfo(staker))?.signerManager;
+            if (!manager) {
+                throw new Error(`${staker} is not currently staking; pass signerManager to check rewards from a past signer.`);
+            }
+            const [earnedSats, unpulledSats, claimStyle] = await Promise.all([
+                service.getStakerUnclaimedRewards(manager, rewardCycle, staker),
+                service.getSignerUnpulledRewards(manager, rewardCycle),
+                service.getClaimStyle(manager),
+            ]);
+            return createJsonResponse({
+                address: staker,
+                network: NETWORK,
+                rewardCycle,
+                signerManager: manager,
+                unclaimedSatsBeforeFees: earnedSats.toString(),
+                managerUnpulledSats: unpulledSats.toString(),
+                stakerClaim: claimStyle,
+                next: earnedSats === 0n
+                    ? "Nothing to claim for this cycle."
+                    : claimStyle === "none"
+                        ? "This manager has no on-chain staker claim; it pays stakers off-chain."
+                        : "Call claim_stacking_rewards with this rewardCycle.",
+            });
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // --- claim_stacking_rewards ---
+    server.registerTool("claim_stacking_rewards", {
+        description: "Claim PoX-5 sBTC rewards for one reward cycle through the staker's signer manager. If the " +
+            "manager has not yet pulled that cycle's rewards from pox-5, this first sends the manager's " +
+            "permissionless claim-rewards (a second transaction, paid by this wallet), then the staker " +
+            "claim. Rewards arrive as sBTC, or as a BTC withdrawal if a payout address was set when " +
+            "staking. Not available for managers that pay off-chain.",
+        inputSchema: {
+            rewardCycle: z.number().int().nonnegative().describe("Reward cycle to claim"),
+            signerManager: z
+                .string()
+                .optional()
+                .describe("Signer manager to claim from. Defaults to the wallet's current signer manager."),
+        },
+    }, async ({ rewardCycle, signerManager }) => {
+        try {
+            const service = getStackingService(NETWORK);
+            const account = await getAccount();
+            const manager = signerManager ?? (await service.getStakerInfo(account.address))?.signerManager;
+            if (!manager) {
+                throw new Error(`${account.address} is not currently staking; pass signerManager to claim from a past signer.`);
+            }
+            const [earnedSats, unpulledSats, claimStyle] = await Promise.all([
+                service.getStakerUnclaimedRewards(manager, rewardCycle, account.address),
+                service.getSignerUnpulledRewards(manager, rewardCycle),
+                service.getClaimStyle(manager),
+            ]);
+            if (claimStyle === "none") {
+                throw new Error(`${manager} has no on-chain staker claim (claim-staker-rewards); it pays stakers off-chain.`);
+            }
+            if (earnedSats === 0n) {
+                throw new Error(`No unclaimed rewards for ${account.address} from ${manager} in cycle ${rewardCycle}.`);
+            }
+            let pull = null;
+            if (unpulledSats > 0n) {
+                const pulled = await service.pullSignerRewards(account, manager, rewardCycle, unpulledSats);
+                pull = { txid: pulled.txid, explorerUrl: getExplorerTxUrl(pulled.txid, NETWORK) };
+            }
+            const claim = await service.claimStakerRewards(account, manager, rewardCycle, claimStyle);
+            return createJsonResponse({
+                success: true,
+                network: NETWORK,
+                rewardCycle,
+                signerManager: manager,
+                unclaimedSatsBeforeFees: earnedSats.toString(),
+                managerPull: pull,
+                txid: claim.txid,
+                explorerUrl: getExplorerTxUrl(claim.txid, NETWORK),
+                note: pull
+                    ? "Two transactions were sent in nonce order: the manager's pull, then the staker claim."
+                    : undefined,
             });
         }
         catch (error) {

package/dist/tools/yield-dashboard.tools.js

@@ -17,6 +17,7 @@ import { contractPrincipalCV, standardPrincipalCV, uintCV, hexToCV, cvToValue, }
 import { NETWORK } from "../services/x402.service.js";
 import { getWalletAddress } from "../services/x402.service.js";
 import { getHiroApi } from "../services/hiro-api.js";
+import { getStackingService } from "../services/stacking.service.js";
 import { createJsonResponse, createErrorResponse } from "../utils/index.js";
 // ============================================================================
 // Constants
@@ -41,10 +42,6 @@ const ALEX_TOKEN_Y_NAME = "token-abtc";
 const ALEX_FACTOR = 100_000_000;
 // Bitflow public API
 const BITFLOW_API = "https://app.bitflow.finance/api";
-// Stacking (PoX-4)
-const POX_CONTRACT = "SP000000000000000000002Q6VF78";
-const POX_NAME = "pox-4";
-const POX_CONTRACT_ID = `${POX_CONTRACT}.${POX_NAME}`;
 // Mainnet Hiro API base URL (direct — not network-switched, this skill is mainnet-only)
 const MAINNET_HIRO_API = "https://api.hiro.so";
 // ============================================================================
@@ -225,24 +222,18 @@ async function readStackingPosition(walletAddress) {
         details: {},
     };
     try {
-        const hiro = getHiroApi("mainnet");
-        const res = await hiro.callReadOnlyFunction(POX_CONTRACT_ID, "get-stacker-info", [standardPrincipalCV(walletAddress)], POX_CONTRACT);
-        if (res.okay && res.result) {
-            const hex = res.result.startsWith("0x") ? res.result.slice(2) : res.result;
-            const cv = hexToCV(hex);
-            const val = cvToValue(cv, true);
-            if (val && typeof val === "object" && "lock-amount" in val) {
-                const lockAmount = val["lock-amount"];
-                pos.valueSats =
-                    typeof lockAmount === "bigint"
-                        ? Number(lockAmount)
-                        : typeof lockAmount === "number"
-                            ? lockAmount
-                            : 0;
-                pos.apyPct = 8.0;
-                pos.details.apySource = "static estimate, not live";
-                pos.details.stackerInfo = val;
-            }
+        const info = await getStackingService("mainnet").getStakerInfo(walletAddress);
+        if (info) {
+            pos.valueSats = Number(info.amountUstx);
+            pos.apyPct = 8.0;
+            pos.details.apySource = "static estimate, not live";
+            pos.details.stakerInfo = {
+                signerManager: info.signerManager,
+                firstRewardCycle: info.firstRewardCycle,
+                numCycles: info.numCycles,
+                unlockCycle: info.unlockCycle,
+                unlockBurnHeight: info.unlockBurnHeight,
+            };
         }
     }
     catch (e) {

package/dist/utils/bip322.d.ts

@@ -7,9 +7,8 @@
  *
  * Spec: https://github.com/bitcoin/bips/blob/master/bip-0322.mediawiki
  *
- * These primitives are shared across:
- * - src/tools/signing.tools.ts (btc_sign_message / btc_verify_message)
- * - src/tools/news.tools.ts (news_file_signal auth headers)
+ * Used by src/tools/signing.tools.ts (btc_sign_message / btc_verify_message)
+ * and the BIP-322-authenticated aibtc.com tools.
  */
 /**
  * BIP-322 tagged hash: SHA256(SHA256(tag) || SHA256(tag) || msg)