@aibtc/mcp-server 1.36.0 → 1.37.0

package/dist/tools/taproot-multisig.tools.js

@@ -0,0 +1,236 @@
+/**
+ * Taproot Multisig Tools
+ *
+ * MCP tools for Taproot M-of-N multisig coordination between agents.
+ *
+ * - taproot_get_pubkey: Derive the x-only Taproot public key from the active wallet
+ *   (BIP-86 path m/86'/0'/0'/0/0). Requires wallet unlock.
+ *
+ * - taproot_verify_cosig: Verify a Schnorr signature against a BIP-341 sighash.
+ *   Read-only — no wallet needed.
+ *
+ * - taproot_multisig_guide: Return a step-by-step guide for M-of-N Taproot multisig
+ *   coordination using OP_CHECKSIGADD (BIP-341/342). Read-only.
+ */
+import { schnorr } from "@noble/curves/secp256k1.js";
+import { z } from "zod";
+import { getWalletManager } from "../services/wallet-manager.js";
+import { createErrorResponse, createJsonResponse } from "../utils/index.js";
+export function registerTaprootMultisigTools(server) {
+    // ---------------------------------------------------------------------------
+    // taproot_get_pubkey
+    // ---------------------------------------------------------------------------
+    server.registerTool("taproot_get_pubkey", {
+        description: "Derive the x-only Taproot public key (32 bytes hex) from the active wallet using the " +
+            "BIP-86 derivation path m/86'/0'/0'/0/0. " +
+            "Share this pubkey with co-signers to construct a Taproot multisig script tree. " +
+            "Requires the wallet to be unlocked (use wallet_unlock first).",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const walletManager = getWalletManager();
+            const account = walletManager.getActiveAccount();
+            if (!account?.taprootPublicKey) {
+                throw new Error("Taproot key not available. Unlock your wallet first with wallet_unlock.");
+            }
+            if (account.taprootPublicKey.length !== 32) {
+                throw new Error(`Unexpected taproot public key length: ${account.taprootPublicKey.length} bytes (expected 32).`);
+            }
+            const pubkeyHex = Buffer.from(account.taprootPublicKey).toString("hex");
+            return createJsonResponse({
+                success: true,
+                pubkey: pubkeyHex,
+                encoding: "x-only (BIP-340, 32 bytes hex)",
+                derivationPath: "m/86'/0'/0'/0/0",
+                note: "Share this pubkey with co-signers. Use taproot_multisig_guide for coordination steps.",
+            });
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // taproot_verify_cosig
+    // ---------------------------------------------------------------------------
+    server.registerTool("taproot_verify_cosig", {
+        description: "Verify a Schnorr co-signature against a BIP-341 sighash. " +
+            "Use this to confirm that a co-signer's signature is valid before combining and broadcasting. " +
+            "Read-only — no wallet unlock required.",
+        inputSchema: {
+            sighash: z
+                .string()
+                .length(64)
+                .regex(/^[0-9a-fA-F]+$/, "must be valid hex")
+                .describe("BIP-341 sighash as 32-byte hex string (64 hex chars). " +
+                "This is the transaction commitment that was signed."),
+            signature: z
+                .string()
+                .length(128)
+                .regex(/^[0-9a-fA-F]+$/, "must be valid hex")
+                .describe("Schnorr signature as 64-byte hex string (128 hex chars, BIP-340 format)."),
+            pubkey: z
+                .string()
+                .length(64)
+                .regex(/^[0-9a-fA-F]+$/, "must be valid hex")
+                .describe("Signer's x-only public key as 32-byte hex string (64 hex chars). " +
+                "Obtain via taproot_get_pubkey from each co-signer."),
+        },
+    }, async ({ sighash, signature, pubkey }) => {
+        try {
+            const sighashBytes = Buffer.from(sighash, "hex");
+            const signatureBytes = Buffer.from(signature, "hex");
+            const pubkeyBytes = Buffer.from(pubkey, "hex");
+            if (sighashBytes.length !== 32) {
+                throw new Error(`sighash must be exactly 32 bytes (64 hex chars), got ${sighashBytes.length} bytes.`);
+            }
+            if (signatureBytes.length !== 64) {
+                throw new Error(`signature must be exactly 64 bytes (128 hex chars), got ${signatureBytes.length} bytes.`);
+            }
+            if (pubkeyBytes.length !== 32) {
+                throw new Error(`pubkey must be exactly 32 bytes (64 hex chars), got ${pubkeyBytes.length} bytes.`);
+            }
+            const valid = schnorr.verify(signatureBytes, sighashBytes, pubkeyBytes);
+            return createJsonResponse({
+                valid,
+                sighash,
+                signature,
+                pubkey,
+                message: valid
+                    ? "Signature is valid. This co-signer's Schnorr signature is authentic."
+                    : "Signature is INVALID. Do not proceed with this co-signer's input.",
+            });
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // taproot_multisig_guide
+    // ---------------------------------------------------------------------------
+    server.registerTool("taproot_multisig_guide", {
+        description: "Return a step-by-step guide for M-of-N Taproot multisig coordination between agents " +
+            "using OP_CHECKSIGADD (BIP-341/342). Read-only — no wallet needed.",
+        inputSchema: {
+            m: z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .optional()
+                .default(2)
+                .describe("Number of required signatures (default: 2)."),
+            n: z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .optional()
+                .default(3)
+                .describe("Total number of co-signers (default: 3)."),
+        },
+    }, async ({ m, n }) => {
+        if (m > n) {
+            return createErrorResponse(new Error(`Invalid parameters: m (${m}) cannot exceed n (${n}).`));
+        }
+        const guide = {
+            title: `${m}-of-${n} Taproot Multisig Coordination Guide`,
+            overview: `Taproot M-of-N multisig uses OP_CHECKSIGADD (BIP-342) inside a Taproot script leaf (BIP-341). ` +
+                `Each co-signer holds an independent BIP-86 keypair and signs the same BIP-341 sighash ` +
+                `with a Schnorr signature. No interaction is required during signing — co-signers collect ` +
+                `each other's signatures and combine them off-chain before broadcast.`,
+            steps: [
+                {
+                    step: 1,
+                    title: "Exchange x-only public keys",
+                    details: [
+                        `Each of the ${n} co-signers calls taproot_get_pubkey to obtain their x-only BIP-86 pubkey (32 bytes).`,
+                        "Share pubkeys out-of-band (e.g. via the AIBTC inbox or a shared coordination channel).",
+                        "Agree on a canonical ordering of the pubkeys (e.g. lexicographic ascending). This order must be consistent across all participants.",
+                    ],
+                    bip: "BIP-86 (key derivation), BIP-340 (x-only pubkey encoding)",
+                },
+                {
+                    step: 2,
+                    title: "Construct the Taproot script leaf with OP_CHECKSIGADD",
+                    details: [
+                        `Assemble the ${m}-of-${n} script using the agreed pubkey order:`,
+                        `  <pubkey_1> OP_CHECKSIG <pubkey_2> OP_CHECKSIGADD ... <pubkey_${n}> OP_CHECKSIGADD OP_${m} OP_NUMEQUAL`,
+                        "Compute the TapLeaf hash: SHA256(0xC0 || compact_size(script_len) || script).",
+                        "Build the Taproot output key: internalKey = KeyAgg(pubkeys) tweaked by TapTweak.",
+                        "The final P2TR address is: OP_1 <32-byte_output_key>.",
+                        "All co-signers must independently verify they compute the same P2TR address before funding.",
+                    ],
+                    bip: "BIP-341 (Taproot output construction), BIP-342 (Tapscript OP_CHECKSIGADD)",
+                },
+                {
+                    step: 3,
+                    title: "Create the PSBT",
+                    details: [
+                        "One co-signer (the initiator) constructs the unsigned PSBT encoding the spending transaction.",
+                        "The PSBT input must include: witnessUtxo (the P2TR output being spent), tapLeafScript (the multisig leaf), and tapBip32Derivation for each signer.",
+                        "Compute the BIP-341 sighash (SIGHASH_DEFAULT = 0x00) over the PSBT using the script-path spending rules.",
+                        "Distribute the PSBT and the sighash hex to all co-signers.",
+                    ],
+                    bip: "BIP-174 (PSBT), BIP-341 §Common signature message",
+                },
+                {
+                    step: 4,
+                    title: "Sign independently with Schnorr",
+                    details: [
+                        "Each co-signer receives the PSBT and signs the BIP-341 sighash with their BIP-86 Taproot private key.",
+                        "Use psbt_sign (or use raw sighash signing when available) to produce a 64-byte BIP-340 Schnorr signature.",
+                        `Only ${m} of the ${n} co-signers need to sign — but all ${n} must verify.`,
+                        "Each signer returns their (pubkey, signature) pair to the combiner.",
+                    ],
+                    bip: "BIP-340 (Schnorr signatures), BIP-342 (script-path spending)",
+                },
+                {
+                    step: 5,
+                    title: "Verify co-signatures with taproot_verify_cosig",
+                    details: [
+                        "The combiner calls taproot_verify_cosig for each received (sighash, signature, pubkey) tuple.",
+                        `Collect at least ${m} valid signatures before proceeding.`,
+                        "Reject any signature that returns valid: false.",
+                        "This step ensures no invalid or malformed signatures enter the final PSBT.",
+                    ],
+                    tool: "taproot_verify_cosig",
+                },
+                {
+                    step: 6,
+                    title: "Combine signatures and broadcast",
+                    details: [
+                        `Insert the ${m} valid Schnorr signatures into the PSBT as tapScriptSig entries (one per signer).`,
+                        "The witness stack for OP_CHECKSIGADD script-path spending is: [sig_1, sig_2, ..., sig_m, script, control_block].",
+                        "Absent signers (in an M < N setup) provide an empty stack item (0x00) as placeholder.",
+                        "Finalize the PSBT (psbt_broadcast or psbt_sign with finalizeSignedInputs: true).",
+                        "Broadcast the finalized transaction to the Bitcoin network.",
+                    ],
+                    bip: "BIP-341 §Script path spending, BIP-342 §Validation",
+                    tool: "psbt_broadcast",
+                },
+            ],
+            securityNotes: [
+                "Never share your private key. Only share x-only public keys and signatures.",
+                "Always verify the P2TR address before funding — an incorrect script tree cannot be spent.",
+                "Verify co-signatures with taproot_verify_cosig before broadcasting.",
+                "Use a fresh nonce for each signing session to avoid nonce reuse attacks (handled automatically by @noble/curves).",
+                "For high-value multisig, use an air-gapped signer and verify the sighash independently.",
+            ],
+            tools: {
+                get_pubkey: "taproot_get_pubkey",
+                verify_cosig: "taproot_verify_cosig",
+                sign_psbt: "psbt_sign",
+                broadcast: "psbt_broadcast",
+                decode_psbt: "psbt_decode",
+            },
+            references: [
+                "BIP-340: https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki",
+                "BIP-341: https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki",
+                "BIP-342: https://github.com/bitcoin/bips/blob/master/bip-0342.mediawiki",
+                "BIP-86:  https://github.com/bitcoin/bips/blob/master/bip-0086.mediawiki",
+            ],
+        };
+        return createJsonResponse(guide);
+    });
+}
+//# sourceMappingURL=taproot-multisig.tools.js.map

package/dist/tools/taproot-multisig.tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"taproot-multisig.tools.js","sourceRoot":"","sources":["../../src/tools/taproot-multisig.tools.ts"],"names":[],"mappings":"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"}

package/dist/tools/transfer.tools.js

@@ -21,7 +21,7 @@ Example: To send 2 STX, use amount "2000000" (micro-STX).
             fee: z
                 .string()
                 .optional()
-                .describe("Optional fee: 'low' | 'medium' | 'high' preset or micro-STX amount. If omitted, auto-estimated. Ignored when sponsored=true."),
+                .describe("Optional fee: 'low' | 'medium' | 'high' preset or micro-STX amount. Clamped to 3,000 uSTX max for STX transfers. If omitted, medium-priority fee is auto-resolved. Ignored when sponsored=true."),
             sponsored: sponsoredSchema,
         },
     }, async ({ recipient, amount, memo, fee, sponsored }) => {

package/dist/tools/transfer.tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"transfer.tools.js","sourceRoot":"","sources":["../../src/tools/transfer.tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"transfer.tools.js","sourceRoot":"","sources":["../../src/tools/transfer.tools.ts"],"names":[],"mappings":"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"}

package/dist/transactions/builder.d.ts

@@ -1,6 +1,40 @@
 import { ClarityValue, PostConditionMode, PostCondition } from "@stacks/transactions";
 import { type Network } from "../config/networks.js";
 import type { WalletAddresses } from "../utils/storage.js";
+/**
+ * Maximum number of addresses tracked simultaneously in pendingNonces and
+ * pendingNonceTimestamps. When this limit is reached the oldest entry (by
+ * insertion order) is evicted before a new one is added. This prevents
+ * unbounded memory growth in long-running server processes (issue #336).
+ */
+export declare const MAX_NONCE_ENTRIES = 100;
+/**
+ * Exported references to the internal nonce Maps for unit testing only.
+ * Do not use these outside of test files.
+ */
+export declare const _testingNonceMaps: {
+    pendingNonces: Map<string, bigint>;
+    pendingNonceTimestamps: Map<string, number>;
+    STALE_NONCE_MS: number;
+};
+/**
+ * Reset the pending nonce for an address (called on wallet unlock/lock/switch
+ * so the counter re-syncs with the chain on the next transaction).
+ */
+export declare function resetPendingNonce(address: string): void;
+/**
+ * Force-resync the local pending nonce for an address.
+ * Identical to resetPendingNonce but exported under a name that makes the
+ * intent clear for the recover_sponsor_nonce tool's resync-local-nonce action.
+ */
+export declare function forceResyncNonce(address: string): void;
+/**
+ * Record that a transaction with `nonce` was successfully broadcast for
+ * `address`, so the next call advances past it.
+ *
+ * Exported for unit testing. Not part of the public API.
+ */
+export declare function advancePendingNonce(address: string, nonce: bigint): void;
 export interface Account extends WalletAddresses {
     privateKey: string;
     /**
@@ -57,7 +91,7 @@ export interface ContractDeployOptions {
 }
 /**
  * Transfer STX tokens to a recipient
- * @param fee Optional fee in micro-STX. If omitted, fee is auto-estimated.
+ * @param fee Optional fee in micro-STX. If omitted, a medium-priority clamped fee is resolved.
  */
 export declare function transferStx(account: Account, recipient: string, amount: bigint, memo?: string, fee?: bigint): Promise<TransferResult>;
 /**

package/dist/transactions/builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/transactions/builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACd,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAmC,KAAK,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,MAAM,WAAW,OAAQ,SAAQ,eAAe;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,aAAa,CAAC,EAAE,UAAU,CAAC;IAC3B;;OAEG;IACH,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B;;OAEG;IACH,gBAAgB,CAAC,EAAE,UAAU,CAAC;IAC9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,UAAU,CAAC;IAC7B;;;;OAIG;IACH,cAAc,CAAC,EAAE,UAAU,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,YAAY,EAAE,CAAC;IAC7B,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;IACjC,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,cAAc,CAAC,CA2BzB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,cAAc,CAAC,CA8BzB;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,cAAc,CAAC,CA0BzB;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAgB7C;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAmB7C;AAED;;GAEG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAmB3B;AAED,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/transactions/builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACd,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAmC,KAAK,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAGtF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAc3D;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAgCrC;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;CAI7B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAGvD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEtD;AAkDD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAcxE;AAED,MAAM,WAAW,OAAQ,SAAQ,eAAe;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,aAAa,CAAC,EAAE,UAAU,CAAC;IAC3B;;OAEG;IACH,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B;;OAEG;IACH,gBAAgB,CAAC,EAAE,UAAU,CAAC;IAC9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,UAAU,CAAC;IAC7B;;;;OAIG;IACH,cAAc,CAAC,EAAE,UAAU,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,YAAY,EAAE,CAAC;IAC7B,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;IACjC,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,cAAc,CAAC,CAkCzB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAqCzB;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,cAAc,CAAC,CAiCzB;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAgB7C;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAmB7C;AAED;;GAEG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAmB3B;AAED,cAAc,sBAAsB,CAAC"}

package/dist/transactions/builder.js

@@ -1,19 +1,157 @@
 import { makeSTXTokenTransfer, makeContractCall, makeContractDeploy, broadcastTransaction, PostConditionMode, } from "@stacks/transactions";
 import { hexToBytes } from "@stacks/common";
 import { getStacksNetwork, getApiBaseUrl } from "../config/networks.js";
+import { getHiroApi } from "../services/hiro-api.js";
+import { resolveDefaultFee } from "../utils/fee.js";
+// ---------------------------------------------------------------------------
+// Pending nonce tracking (fixes back-to-back tx nonce collision, issue #326)
+// ---------------------------------------------------------------------------
+/**
+ * How long a locally-tracked pending nonce is considered fresh.
+ * If no new transaction has been broadcast within this window the counter is
+ * stale (the tx likely confirmed or was dropped) and we fall back to the
+ * network value on the next call.
+ */
+const STALE_NONCE_MS = 10 * 60 * 1000; // 10 minutes
+/**
+ * Maximum number of addresses tracked simultaneously in pendingNonces and
+ * pendingNonceTimestamps. When this limit is reached the oldest entry (by
+ * insertion order) is evicted before a new one is added. This prevents
+ * unbounded memory growth in long-running server processes (issue #336).
+ */
+export const MAX_NONCE_ENTRIES = 100;
+/**
+ * Evict the oldest entry from a Map when it has reached MAX_NONCE_ENTRIES.
+ * JS Maps iterate in insertion order, so map.keys().next() yields the oldest
+ * key — no additional bookkeeping is needed.
+ */
+function evictOldestIfFull(map) {
+    if (map.size >= MAX_NONCE_ENTRIES) {
+        const oldestKey = map.keys().next().value;
+        if (oldestKey !== undefined) {
+            map.delete(oldestKey);
+        }
+    }
+}
+/**
+ * In-memory map of STX address -> next expected nonce for non-sponsored txs.
+ * Updated after each successful broadcast so sequential calls don't re-use
+ * the same network nonce before the first tx lands in the mempool.
+ * Bounded to MAX_NONCE_ENTRIES entries; oldest evicted on overflow (issue #336).
+ */
+const pendingNonces = new Map();
+/**
+ * Tracks when each address last advanced its local nonce counter.
+ * Used to detect stale entries: if no transaction was sent within STALE_NONCE_MS
+ * the counter is expired and the network value is authoritative again.
+ * Bounded to MAX_NONCE_ENTRIES entries; oldest evicted on overflow (issue #336).
+ */
+const pendingNonceTimestamps = new Map();
+/**
+ * Exported references to the internal nonce Maps for unit testing only.
+ * Do not use these outside of test files.
+ */
+export const _testingNonceMaps = {
+    pendingNonces,
+    pendingNonceTimestamps,
+    STALE_NONCE_MS,
+};
+/**
+ * Reset the pending nonce for an address (called on wallet unlock/lock/switch
+ * so the counter re-syncs with the chain on the next transaction).
+ */
+export function resetPendingNonce(address) {
+    pendingNonces.delete(address);
+    pendingNonceTimestamps.delete(address);
+}
+/**
+ * Force-resync the local pending nonce for an address.
+ * Identical to resetPendingNonce but exported under a name that makes the
+ * intent clear for the recover_sponsor_nonce tool's resync-local-nonce action.
+ */
+export function forceResyncNonce(address) {
+    resetPendingNonce(address);
+}
+/**
+ * Fetch the next nonce to use for `address`.
+ *
+ * Algorithm:
+ * 1. Fetch `possible_next_nonce` and `detected_missing_nonces` from Hiro.
+ * 2. If the local counter exists but is older than STALE_NONCE_MS, discard it
+ *    so a stale counter never permanently blocks a recovered wallet.
+ * 3. Return max(possible_next_nonce, local_pending) so rapid sequential calls
+ *    get strictly increasing nonces even before the mempool reflects the first tx.
+ * 4. Warn if the network reports missing nonces — gaps below the pending counter
+ *    can cause the queue to stall until the gaps are filled.
+ */
+async function getNextNonce(address, network) {
+    // Stale-timeout: discard local counter if it hasn't been refreshed recently.
+    const lastAdvanced = pendingNonceTimestamps.get(address);
+    const isStale = lastAdvanced !== undefined && Date.now() - lastAdvanced > STALE_NONCE_MS;
+    if (isStale) {
+        pendingNonces.delete(address);
+        pendingNonceTimestamps.delete(address);
+    }
+    const pending = pendingNonces.get(address) ?? 0n;
+    try {
+        const hiroApi = getHiroApi(network);
+        const nonceInfo = await hiroApi.getNonceInfo(address);
+        const networkNext = BigInt(nonceInfo.possible_next_nonce);
+        // Warn about detected nonce gaps that could stall the queue.
+        if (nonceInfo.detected_missing_nonces && nonceInfo.detected_missing_nonces.length > 0) {
+            console.warn(`[nonce] detected_missing_nonces for ${address}: [${nonceInfo.detected_missing_nonces.join(", ")}]. ` +
+                `These gaps may stall pending transactions. Use recover_sponsor_nonce with action=fill-gaps to resolve.`);
+        }
+        return networkNext > pending ? networkNext : pending;
+    }
+    catch (err) {
+        // Fallback: if we have a fresh local counter, use it to keep the queue moving
+        // even when Hiro is temporarily unreachable (e.g., between rapid sequential calls).
+        if (pending > 0n) {
+            console.warn(`[nonce] API call failed, using local pending counter (${pending}) for ${address}:`, err);
+            return pending;
+        }
+        throw err;
+    }
+}
+/**
+ * Record that a transaction with `nonce` was successfully broadcast for
+ * `address`, so the next call advances past it.
+ *
+ * Exported for unit testing. Not part of the public API.
+ */
+export function advancePendingNonce(address, nonce) {
+    const next = nonce + 1n;
+    const current = pendingNonces.get(address) ?? 0n;
+    if (next > current) {
+        // Evict oldest entry before inserting a new address to keep maps bounded.
+        // Only evict when this is a new address — updates to existing keys don't
+        // change Map size so no eviction is needed.
+        if (!pendingNonces.has(address)) {
+            evictOldestIfFull(pendingNonces);
+            evictOldestIfFull(pendingNonceTimestamps);
+        }
+        pendingNonces.set(address, next);
+        pendingNonceTimestamps.set(address, Date.now());
+    }
+}
 /**
  * Transfer STX tokens to a recipient
- * @param fee Optional fee in micro-STX. If omitted, fee is auto-estimated.
+ * @param fee Optional fee in micro-STX. If omitted, a medium-priority clamped fee is resolved.
  */
 export async function transferStx(account, recipient, amount, memo, fee) {
     const networkName = getStacksNetwork(account.network);
+    const nonce = await getNextNonce(account.address, account.network);
+    // Always resolve a clamped fee — prevents @stacks/transactions from over-estimating.
+    const resolvedFee = fee ?? await resolveDefaultFee(account.network, "token_transfer");
     const transaction = await makeSTXTokenTransfer({
         recipient,
         amount,
         senderKey: account.privateKey,
         network: networkName,
         memo: memo || "",
-        ...(fee !== undefined && { fee }),
+        nonce,
+        fee: resolvedFee,
     });
     const broadcastResponse = await broadcastTransaction({
         transaction,
@@ -22,6 +160,7 @@ export async function transferStx(account, recipient, amount, memo, fee) {
     if ("error" in broadcastResponse) {
         throw new Error(`Broadcast failed: ${broadcastResponse.error} - ${broadcastResponse.reason}`);
     }
+    advancePendingNonce(account.address, nonce);
     return {
         txid: broadcastResponse.txid,
         rawTx: transaction.serialize(),
@@ -32,6 +171,9 @@ export async function transferStx(account, recipient, amount, memo, fee) {
  */
 export async function callContract(account, options) {
     const networkName = getStacksNetwork(account.network);
+    const nonce = await getNextNonce(account.address, account.network);
+    // Always resolve a clamped fee — prevents @stacks/transactions from over-estimating.
+    const resolvedFee = options.fee ?? await resolveDefaultFee(account.network, "contract_call");
     const transaction = await makeContractCall({
         contractAddress: options.contractAddress,
         contractName: options.contractName,
@@ -39,9 +181,10 @@ export async function callContract(account, options) {
         functionArgs: options.functionArgs,
         senderKey: account.privateKey,
         network: networkName,
+        nonce,
         postConditionMode: options.postConditionMode || PostConditionMode.Deny,
         postConditions: options.postConditions || [],
-        ...(options.fee !== undefined && { fee: options.fee }),
+        fee: resolvedFee,
     });
     const broadcastResponse = await broadcastTransaction({
         transaction,
@@ -50,6 +193,7 @@ export async function callContract(account, options) {
     if ("error" in broadcastResponse) {
         throw new Error(`Broadcast failed: ${broadcastResponse.error} - ${broadcastResponse.reason}`);
     }
+    advancePendingNonce(account.address, nonce);
     return {
         txid: broadcastResponse.txid,
         rawTx: transaction.serialize(),
@@ -60,12 +204,16 @@ export async function callContract(account, options) {
  */
 export async function deployContract(account, options) {
     const networkName = getStacksNetwork(account.network);
+    const nonce = await getNextNonce(account.address, account.network);
+    // Always resolve a clamped fee — prevents @stacks/transactions from over-estimating.
+    const resolvedFee = options.fee ?? await resolveDefaultFee(account.network, "smart_contract");
     const transaction = await makeContractDeploy({
         contractName: options.contractName,
         codeBody: options.codeBody,
         senderKey: account.privateKey,
         network: networkName,
-        ...(options.fee !== undefined && { fee: options.fee }),
+        nonce,
+        fee: resolvedFee,
     });
     const broadcastResponse = await broadcastTransaction({
         transaction,
@@ -74,6 +222,7 @@ export async function deployContract(account, options) {
     if ("error" in broadcastResponse) {
         throw new Error(`Broadcast failed: ${broadcastResponse.error} - ${broadcastResponse.reason}`);
     }
+    advancePendingNonce(account.address, nonce);
     return {
         txid: broadcastResponse.txid,
         rawTx: transaction.serialize(),

package/dist/transactions/builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../src/transactions/builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../src/transactions/builder.ts"],"names":[],"mappings":"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"}

package/dist/utils/fee.d.ts

@@ -38,4 +38,19 @@ export declare function isFeePreset(value: string): value is FeePreset;
  * await resolveFee(undefined, "mainnet") // -> undefined
  */
 export declare function resolveFee(fee: string | undefined, network: Network, txType?: "all" | "token_transfer" | "contract_call" | "smart_contract"): Promise<bigint | undefined>;
+/**
+ * Resolve a default medium-priority fee for a given transaction type.
+ *
+ * Used by builder functions when the caller does not supply an explicit fee,
+ * so that ALL write paths receive a clamped fee rather than relying on the
+ * unclamped @stacks/transactions auto-estimation which can over-shoot.
+ *
+ * Falls back gracefully: if the Hiro mempool API is unreachable, returns the
+ * floor × 2 (medium multiplier) for the tx type.
+ *
+ * @param network - The Stacks network to fetch fee estimates from
+ * @param txType - The transaction type for ceiling/floor selection
+ * @returns Fee in micro-STX as bigint
+ */
+export declare function resolveDefaultFee(network: Network, txType?: "token_transfer" | "contract_call" | "smart_contract"): Promise<bigint>;
 //# sourceMappingURL=fee.d.ts.map

package/dist/utils/fee.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fee.d.ts","sourceRoot":"","sources":["../../src/utils/fee.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAarD;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAElD;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,SAAS,CAE7D;AAwBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,OAAO,EAAE,OAAO,EAChB,MAAM,GAAE,KAAK,GAAG,gBAAgB,GAAG,eAAe,GAAG,gBAAwB,GAC5E,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAuC7B"}
+{"version":3,"file":"fee.d.ts","sourceRoot":"","sources":["../../src/utils/fee.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAmBrD;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAElD;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,SAAS,CAE7D;AAwBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,OAAO,EAAE,OAAO,EAChB,MAAM,GAAE,KAAK,GAAG,gBAAgB,GAAG,eAAe,GAAG,gBAAwB,GAC5E,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA4C7B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,OAAO,EAChB,MAAM,GAAE,gBAAgB,GAAG,eAAe,GAAG,gBAAkC,GAC9E,OAAO,CAAC,MAAM,CAAC,CAOjB"}