recon-crypto-mcp 0.1.0

package/dist/modules/bitcoin/index.js

@@ -0,0 +1,128 @@
+import { cache } from "../../data/cache.js";
+import { CACHE_TTL } from "../../config/cache.js";
+/**
+ * Bitcoin mainnet portfolio reads.
+ *
+ * Data source: mempool.space REST API (no key required, no rate-limit issues for
+ * occasional lookups). We only fetch the address-summary endpoint — no block or
+ * tx history, since portfolio integration only needs the confirmed balance.
+ *
+ * Scope is intentionally read-only. Tx construction (UTXO selection, fee-rate,
+ * PSBT assembly) and signing via WalletConnect `bip122:` are phase-2 work — a
+ * separate module when we wire Ledger Live's Bitcoin app.
+ *
+ * Prices come from DefiLlama's `coingecko:bitcoin` key to stay consistent with
+ * the EVM pricing path; cached for the same TTL as ERC-20 prices.
+ */
+const MEMPOOL_API = "https://mempool.space/api";
+const SATS_PER_BTC = 100000000n;
+function satsToBtcString(sats) {
+    const whole = sats / SATS_PER_BTC;
+    const frac = sats % SATS_PER_BTC;
+    if (frac === 0n)
+        return whole.toString();
+    const fracStr = frac.toString().padStart(8, "0").replace(/0+$/, "");
+    return `${whole.toString()}.${fracStr}`;
+}
+async function fetchBitcoinPrice() {
+    const cacheKey = "price:coingecko:bitcoin";
+    const hit = cache.get(cacheKey);
+    if (hit !== undefined)
+        return hit;
+    try {
+        const res = await fetch("https://coins.llama.fi/prices/current/coingecko:bitcoin");
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        const price = body.coins["coingecko:bitcoin"]?.price;
+        if (typeof price === "number") {
+            cache.set(cacheKey, price, CACHE_TTL.PRICE);
+            return price;
+        }
+    }
+    catch {
+        // Swallow — degrade to undefined USD so callers can still return sats.
+    }
+    return undefined;
+}
+async function fetchAddressSummary(address) {
+    const res = await fetch(`${MEMPOOL_API}/address/${encodeURIComponent(address)}`);
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`mempool.space ${res.status}: ${body.slice(0, 200)}`);
+    }
+    return (await res.json());
+}
+export async function getBitcoinBalance(args) {
+    const [summary, priceUsd] = await Promise.all([
+        fetchAddressSummary(args.address),
+        fetchBitcoinPrice(),
+    ]);
+    return toBalance(args.address, summary, priceUsd);
+}
+export async function getBitcoinPortfolio(args) {
+    const priceUsd = await fetchBitcoinPrice();
+    // Fetch each address in parallel; an individual failure shouldn't kill the whole report.
+    const balances = await Promise.all(args.addresses.map(async (addr) => {
+        try {
+            const summary = await fetchAddressSummary(addr);
+            return toBalance(addr, summary, priceUsd);
+        }
+        catch {
+            return toBalance(addr, emptySummary(addr), priceUsd);
+        }
+    }));
+    const totalSats = balances.reduce((sum, b) => sum + BigInt(b.amountSats), 0n);
+    const totalBtc = satsToBtcString(totalSats);
+    const totalUsd = priceUsd !== undefined
+        ? Number(totalBtc) * priceUsd
+        : undefined;
+    return {
+        chain: "bitcoin",
+        addresses: args.addresses,
+        balances,
+        totalSats: totalSats.toString(),
+        totalBtc,
+        totalUsd,
+        priceUsd,
+    };
+}
+function toBalance(address, summary, priceUsd) {
+    const confirmedSats = BigInt(summary.chain_stats.funded_txo_sum) -
+        BigInt(summary.chain_stats.spent_txo_sum);
+    const unconfirmedSats = BigInt(summary.mempool_stats.funded_txo_sum) -
+        BigInt(summary.mempool_stats.spent_txo_sum);
+    const formattedBtc = satsToBtcString(confirmedSats);
+    const valueUsd = priceUsd !== undefined ? Number(formattedBtc) * priceUsd : undefined;
+    return {
+        chain: "bitcoin",
+        address,
+        amountSats: confirmedSats.toString(),
+        unconfirmedSats: unconfirmedSats.toString(),
+        formattedBtc,
+        symbol: "BTC",
+        decimals: 8,
+        priceUsd,
+        valueUsd,
+    };
+}
+function emptySummary(address) {
+    return {
+        address,
+        chain_stats: {
+            funded_txo_count: 0,
+            funded_txo_sum: 0,
+            spent_txo_count: 0,
+            spent_txo_sum: 0,
+            tx_count: 0,
+        },
+        mempool_stats: {
+            funded_txo_count: 0,
+            funded_txo_sum: 0,
+            spent_txo_count: 0,
+            spent_txo_sum: 0,
+            tx_count: 0,
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/modules/bitcoin/index.js.map

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

package/dist/modules/bitcoin/schemas.d.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+export declare const bitcoinAddressSchema: z.ZodString;
+export declare const getBitcoinBalanceInput: z.ZodObject<{
+    address: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    address: string;
+}, {
+    address: string;
+}>;
+export declare const getBitcoinPortfolioInput: z.ZodObject<{
+    addresses: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    addresses: string[];
+}, {
+    addresses: string[];
+}>;
+export type GetBitcoinBalanceArgs = z.infer<typeof getBitcoinBalanceInput>;
+export type GetBitcoinPortfolioArgs = z.infer<typeof getBitcoinPortfolioInput>;
+export declare const prepareBitcoinSendInput: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    /** Amount to send to the recipient, in satoshis. Use a string to avoid JS precision issues for > 2^53. */
+    amountSats: z.ZodString;
+    feeRate: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"fastest">, z.ZodLiteral<"halfhour">, z.ZodLiteral<"hour">, z.ZodLiteral<"economy">, z.ZodLiteral<"minimum">, z.ZodNumber]>>;
+    /** Include unconfirmed (mempool) UTXOs as spendable. Default false. */
+    includeUnconfirmed: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    from: string;
+    to: string;
+    amountSats: string;
+    feeRate?: number | "minimum" | "fastest" | "halfhour" | "hour" | "economy" | undefined;
+    includeUnconfirmed?: boolean | undefined;
+}, {
+    from: string;
+    to: string;
+    amountSats: string;
+    feeRate?: number | "minimum" | "fastest" | "halfhour" | "hour" | "economy" | undefined;
+    includeUnconfirmed?: boolean | undefined;
+}>;
+export declare const broadcastBitcoinTxInput: z.ZodObject<{
+    /** Fully signed raw Bitcoin transaction as lowercase hex (no 0x prefix). */
+    hex: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    hex: string;
+}, {
+    hex: string;
+}>;
+export type PrepareBitcoinSendArgs = z.infer<typeof prepareBitcoinSendInput>;
+export type BroadcastBitcoinTxArgs = z.infer<typeof broadcastBitcoinTxInput>;

package/dist/modules/bitcoin/schemas.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+/**
+ * Mainnet-only. Covers:
+ *   - P2PKH (legacy, starts with "1")
+ *   - P2SH (starts with "3")
+ *   - P2WPKH / P2WSH (bech32, starts with "bc1q" / "bc1Q")
+ *   - P2TR (taproot, bech32m, starts with "bc1p")
+ *
+ * Testnet ("tb1…") and regtest are intentionally excluded — this is a portfolio tool.
+ */
+const BITCOIN_ADDRESS_REGEX = /^(bc1[a-zA-HJ-NP-Z0-9]{25,87}|[13][a-km-zA-HJ-NP-Z1-9]{25,34})$/;
+export const bitcoinAddressSchema = z
+    .string()
+    .regex(BITCOIN_ADDRESS_REGEX, "Not a valid Bitcoin mainnet address");
+export const getBitcoinBalanceInput = z.object({
+    address: bitcoinAddressSchema,
+});
+export const getBitcoinPortfolioInput = z.object({
+    addresses: z.array(bitcoinAddressSchema).min(1).max(20),
+});
+/**
+ * Fee rate hint. Either a specific sat/vB number, or a named tier that maps to
+ * mempool.space's recommended-fees endpoint. Default is "hour" (conservative).
+ */
+const feeRateSchema = z.union([
+    z.literal("fastest"),
+    z.literal("halfhour"),
+    z.literal("hour"),
+    z.literal("economy"),
+    z.literal("minimum"),
+    z.number().positive().max(1000),
+]);
+export const prepareBitcoinSendInput = z.object({
+    from: bitcoinAddressSchema,
+    to: bitcoinAddressSchema,
+    /** Amount to send to the recipient, in satoshis. Use a string to avoid JS precision issues for > 2^53. */
+    amountSats: z
+        .string()
+        .regex(/^\d+$/, "amountSats must be a positive integer string"),
+    feeRate: feeRateSchema.optional(),
+    /** Include unconfirmed (mempool) UTXOs as spendable. Default false. */
+    includeUnconfirmed: z.boolean().optional(),
+});
+export const broadcastBitcoinTxInput = z.object({
+    /** Fully signed raw Bitcoin transaction as lowercase hex (no 0x prefix). */
+    hex: z
+        .string()
+        .regex(/^[0-9a-fA-F]+$/, "hex must contain only hex characters")
+        .min(20),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/modules/bitcoin/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../src/modules/bitcoin/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,MAAM,qBAAqB,GACzB,iEAAiE,CAAC;AAEpE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,MAAM,EAAE;KACR,KAAK,CAAC,qBAAqB,EAAE,qCAAqC,CAAC,CAAC;AAEvE,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,OAAO,EAAE,oBAAoB;CAC9B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;CACxD,CAAC,CAAC;AAKH;;;GAGG;AACH,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC;IAC5B,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IACpB,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IACrB,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IACjB,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IACpB,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IACpB,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC;CAChC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,IAAI,EAAE,oBAAoB;IAC1B,EAAE,EAAE,oBAAoB;IACxB,0GAA0G;IAC1G,UAAU,EAAE,CAAC;SACV,MAAM,EAAE;SACR,KAAK,CAAC,OAAO,EAAE,8CAA8C,CAAC;IACjE,OAAO,EAAE,aAAa,CAAC,QAAQ,EAAE;IACjC,uEAAuE;IACvE,kBAAkB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAC3C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,4EAA4E;IAC5E,GAAG,EAAE,CAAC;SACH,MAAM,EAAE;SACR,KAAK,CAAC,gBAAgB,EAAE,sCAAsC,CAAC;SAC/D,GAAG,CAAC,EAAE,CAAC;CACX,CAAC,CAAC"}

package/dist/modules/bitcoin/send.d.ts

@@ -0,0 +1,52 @@
+import { type BitcoinScriptType } from "./utxo.js";
+import type { PrepareBitcoinSendArgs, BroadcastBitcoinTxArgs } from "./schemas.js";
+export interface PreparedBitcoinSend {
+    chain: "bitcoin";
+    from: string;
+    to: string;
+    amountSats: string;
+    amountBtc: string;
+    inputs: {
+        txid: string;
+        vout: number;
+        valueSats: string;
+        confirmed: boolean;
+    }[];
+    outputs: ({
+        role: "recipient";
+        address: string;
+        valueSats: string;
+        valueBtc: string;
+    } | {
+        role: "change";
+        address: string;
+        valueSats: string;
+        valueBtc: string;
+    })[];
+    fee: {
+        sats: string;
+        btc: string;
+        rateSatVb: number;
+        rateSource: string;
+        effectiveRateSatVb: number;
+        vsize: number;
+    };
+    /** Script type of the source — determines input witness sizing. */
+    sourceScriptType: BitcoinScriptType;
+    /**
+     * Plain-English summary of what the user will sign. Shown by default so the
+     * agent has something human-readable to relay before any external signer sees
+     * the tx.
+     */
+    description: string;
+}
+export declare function prepareBitcoinSend(args: PrepareBitcoinSendArgs): Promise<PreparedBitcoinSend>;
+/**
+ * POST a signed raw Bitcoin transaction hex to mempool.space, which forwards it
+ * into the mempool. Returns the txid on success. The caller is responsible for
+ * producing a correctly signed tx (this tool doesn't validate it).
+ */
+export declare function broadcastBitcoinTx(args: BroadcastBitcoinTxArgs): Promise<{
+    txid: string;
+    chain: "bitcoin";
+}>;

package/dist/modules/bitcoin/send.js

@@ -0,0 +1,158 @@
+import { SEGWIT_OVERHEAD_VBYTES, LEGACY_OVERHEAD_VBYTES, VBYTES, detectScriptType, dustThreshold, selectUtxos, } from "./utxo.js";
+/**
+ * Prepare an unsigned Bitcoin send: fetch UTXOs, run consolidation selection,
+ * and return a structured plan (not a PSBT, not a serialized tx). The caller
+ * signs it with their preferred tool (Sparrow, Electrum, hardware wallet) and
+ * broadcasts the resulting hex via `broadcast_bitcoin_tx`.
+ *
+ * Why no PSBT / no serialized unsigned hex:
+ *   - PSBT requires pulling in bitcoinjs-lib and carries complexity we don't
+ *     need for a dev-facing MCP tool.
+ *   - Returning a pure selection plan + vsize + fee lets any wallet build the
+ *     actual tx. It's the data contract that matters, not the binary layout.
+ *
+ * Selection strategy lives in ./utxo.ts — spend every spendable UTXO to
+ * minimize the post-confirmation UTXO count in the source wallet.
+ */
+const MEMPOOL_API = "https://mempool.space/api";
+async function fetchUtxos(address) {
+    const res = await fetch(`${MEMPOOL_API}/address/${encodeURIComponent(address)}/utxo`);
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`mempool.space UTXO ${res.status}: ${body.slice(0, 200)}`);
+    }
+    return (await res.json());
+}
+async function fetchFeeRecommendations() {
+    const res = await fetch(`${MEMPOOL_API}/v1/fees/recommended`);
+    if (!res.ok) {
+        throw new Error(`mempool.space fee rec ${res.status}`);
+    }
+    return (await res.json());
+}
+function resolveFeeRate(input, recs) {
+    if (typeof input === "number")
+        return { satVb: input, source: "user" };
+    switch (input) {
+        case "fastest":
+            return { satVb: recs.fastestFee, source: "fastest (mempool.space)" };
+        case "halfhour":
+            return { satVb: recs.halfHourFee, source: "halfhour (mempool.space)" };
+        case "hour":
+        case undefined:
+            return { satVb: recs.hourFee, source: "hour (mempool.space)" };
+        case "economy":
+            return { satVb: recs.economyFee, source: "economy (mempool.space)" };
+        case "minimum":
+            return { satVb: recs.minimumFee, source: "minimum (mempool.space)" };
+    }
+}
+function satsToBtc(sats) {
+    const whole = sats / 100000000n;
+    const frac = sats % 100000000n;
+    if (frac === 0n)
+        return whole.toString();
+    const fracStr = frac.toString().padStart(8, "0").replace(/0+$/, "");
+    return `${whole.toString()}.${fracStr}`;
+}
+export async function prepareBitcoinSend(args) {
+    const sourceScriptType = detectScriptType(args.from);
+    const recipientScriptType = detectScriptType(args.to);
+    const changeScriptType = sourceScriptType; // Always return change to the sender.
+    const isSegwitSource = sourceScriptType === "p2wpkh" ||
+        sourceScriptType === "p2wsh" ||
+        sourceScriptType === "p2tr" ||
+        sourceScriptType === "p2sh"; // P2SH-P2WPKH is the practical case.
+    const overhead = isSegwitSource ? SEGWIT_OVERHEAD_VBYTES : LEGACY_OVERHEAD_VBYTES;
+    const [utxos, feeRecs] = await Promise.all([
+        fetchUtxos(args.from),
+        fetchFeeRecommendations(),
+    ]);
+    if (utxos.length === 0) {
+        throw new Error(`Address ${args.from} has no UTXOs.`);
+    }
+    const feeRate = resolveFeeRate(args.feeRate, feeRecs);
+    const targetSats = BigInt(args.amountSats);
+    if (targetSats <= 0n) {
+        throw new Error("amountSats must be a positive integer.");
+    }
+    const selection = selectUtxos({
+        utxos: utxos.map((u) => ({
+            txid: u.txid,
+            vout: u.vout,
+            value: u.value,
+            confirmed: u.status.confirmed,
+        })),
+        targetSats,
+        feeRateSatVb: feeRate.satVb,
+        inputVbytes: VBYTES[sourceScriptType].input,
+        outputVbytesRecipient: VBYTES[recipientScriptType].output,
+        outputVbytesChange: VBYTES[changeScriptType].output,
+        overheadVbytes: overhead,
+        dustSats: dustThreshold(changeScriptType),
+        includeUnconfirmed: args.includeUnconfirmed ?? false,
+    });
+    const outputs = [
+        {
+            role: "recipient",
+            address: args.to,
+            valueSats: targetSats.toString(),
+            valueBtc: satsToBtc(targetSats),
+        },
+    ];
+    if (selection.changeSats > 0n) {
+        outputs.push({
+            role: "change",
+            address: args.from,
+            valueSats: selection.changeSats.toString(),
+            valueBtc: satsToBtc(selection.changeSats),
+        });
+    }
+    return {
+        chain: "bitcoin",
+        from: args.from,
+        to: args.to,
+        amountSats: targetSats.toString(),
+        amountBtc: satsToBtc(targetSats),
+        inputs: selection.chosen.map((u) => ({
+            txid: u.txid,
+            vout: u.vout,
+            valueSats: u.value.toString(),
+            confirmed: u.confirmed,
+        })),
+        outputs,
+        fee: {
+            sats: selection.feeSats.toString(),
+            btc: satsToBtc(selection.feeSats),
+            rateSatVb: feeRate.satVb,
+            rateSource: feeRate.source,
+            effectiveRateSatVb: Math.round(selection.effectiveFeeRateSatVb * 100) / 100,
+            vsize: selection.vbytes,
+        },
+        sourceScriptType,
+        description: `Send ${satsToBtc(targetSats)} BTC from ${args.from} to ${args.to}. ` +
+            `Consumes ${selection.chosen.length} UTXO(s) totaling ${satsToBtc(selection.totalInSats)} BTC. ` +
+            `Fee ${selection.feeSats} sats (${satsToBtc(selection.feeSats)} BTC) at ${feeRate.satVb} sat/vB (${feeRate.source}). ` +
+            (selection.changeSats > 0n
+                ? `Change ${satsToBtc(selection.changeSats)} BTC returned to sender.`
+                : `No change output — dust absorbed into fee.`),
+    };
+}
+/**
+ * POST a signed raw Bitcoin transaction hex to mempool.space, which forwards it
+ * into the mempool. Returns the txid on success. The caller is responsible for
+ * producing a correctly signed tx (this tool doesn't validate it).
+ */
+export async function broadcastBitcoinTx(args) {
+    const res = await fetch(`${MEMPOOL_API}/tx`, {
+        method: "POST",
+        headers: { "Content-Type": "text/plain" },
+        body: args.hex,
+    });
+    const body = await res.text().catch(() => "");
+    if (!res.ok) {
+        throw new Error(`Broadcast failed (${res.status}): ${body.slice(0, 300)}`);
+    }
+    return { txid: body.trim(), chain: "bitcoin" };
+}
+//# sourceMappingURL=send.js.map

package/dist/modules/bitcoin/send.js.map

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

package/dist/modules/bitcoin/utxo.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Pure UTXO-selection logic, independent of any network I/O. Kept here so the
+ * coin-selection algorithm can be unit-tested without mocking the HTTP client.
+ *
+ * Objective: minimize the number of UTXOs remaining in the wallet *after* the
+ * transaction confirms — i.e., consolidate. Post-tx UTXO count equals (pool −
+ * chosen) + (1 if change else 0), so this is minimized by spending every
+ * spendable UTXO and, when possible, absorbing the residue into fee so no
+ * change output is created.
+ *
+ * Strategy: always spend the entire spendable pool. Then:
+ *   - If totalIn < target + fee(no-change): insufficient funds.
+ *   - Else if change (= totalIn − target − fee-with-change) ≥ dust: emit a
+ *     change output. Post-tx wallet has 1 UTXO (the change).
+ *   - Else: absorb the residue into fee and emit no change output. Post-tx
+ *     wallet has 0 UTXOs.
+ *
+ * Tradeoff: consolidation increases the fee on *this* transaction roughly
+ * linearly in input count, but eliminates the ongoing cost of carrying — and
+ * eventually spending — every small UTXO. The user asked explicitly for this
+ * objective, so we take the one-time fee hit.
+ */
+export interface Utxo {
+    txid: string;
+    vout: number;
+    /** Output value in satoshis. */
+    value: number;
+    confirmed: boolean;
+}
+export interface SelectionInput {
+    utxos: Utxo[];
+    /** Amount the recipient should receive, in satoshis. */
+    targetSats: bigint;
+    /** Fee rate in sat/vB. */
+    feeRateSatVb: number;
+    /** vsize cost of each input (depends on script type of the source address). */
+    inputVbytes: number;
+    /** vsize cost of the recipient output. */
+    outputVbytesRecipient: number;
+    /** vsize cost of the change output (if any). */
+    outputVbytesChange: number;
+    /** Fixed overhead: version, locktime, witness marker/flag, input/output counts. */
+    overheadVbytes: number;
+    /** Outputs below this value are absorbed into fee instead of created. */
+    dustSats: number;
+    /** If true, include unconfirmed (mempool) UTXOs as spendable. */
+    includeUnconfirmed?: boolean;
+}
+export interface SelectionResult {
+    chosen: Utxo[];
+    totalInSats: bigint;
+    /** Fee that will actually be paid (totalIn − target − change). */
+    feeSats: bigint;
+    /** Change amount in sats (0 if absorbed). */
+    changeSats: bigint;
+    /** Estimated vsize of the final transaction. */
+    vbytes: number;
+    /** Effective fee rate actually paid (may exceed feeRateSatVb when change is absorbed). */
+    effectiveFeeRateSatVb: number;
+}
+export declare function selectUtxos(input: SelectionInput): SelectionResult;
+/**
+ * vsize constants by Bitcoin script type. Numbers come from BIP-141/BIP-341
+ * worst-case witness sizes; close enough for fee estimation.
+ */
+export declare const VBYTES: {
+    readonly p2pkh: {
+        readonly input: 148;
+        readonly output: 34;
+    };
+    readonly p2sh: {
+        readonly input: 91;
+        readonly output: 32;
+    };
+    readonly p2wpkh: {
+        readonly input: 68;
+        readonly output: 31;
+    };
+    readonly p2wsh: {
+        readonly input: 104;
+        readonly output: 43;
+    };
+    readonly p2tr: {
+        readonly input: 58;
+        readonly output: 43;
+    };
+};
+export type BitcoinScriptType = keyof typeof VBYTES;
+/** Detect script type from a mainnet address prefix. */
+export declare function detectScriptType(address: string): BitcoinScriptType;
+/** Dust threshold per script type (sats). From Bitcoin Core policy. */
+export declare function dustThreshold(scriptType: BitcoinScriptType): number;
+/**
+ * Overhead vbytes for a SegWit-eligible transaction (inputs-from-segwit-address
+ * paths). For a pure-legacy spend this is slightly smaller (~10 vB), but
+ * overestimating by a couple of bytes just overpays fee by pennies.
+ */
+export declare const SEGWIT_OVERHEAD_VBYTES = 11;
+export declare const LEGACY_OVERHEAD_VBYTES = 10;