@sequence0/sdk 1.0.3 → 1.1.2

package/dist/chains/bitcoin-taproot.js

@@ -0,0 +1,1241 @@
+"use strict";
+/**
+ * Bitcoin Taproot (P2TR) Chain Adapter
+ *
+ * Full Taproot transaction lifecycle: address derivation, UTXO management,
+ * transaction building, FROST Schnorr signing, and broadcast.
+ *
+ * FROST-secp256k1 produces BIP-340 compatible Schnorr signatures that are
+ * NATIVE to Taproot key-path spends -- no signature format conversion needed.
+ *
+ * Key features:
+ * - **Real secp256k1 EC point arithmetic** for BIP-341 key tweaking
+ *   (lift_x, point_add, scalar_mul -- no external crypto dependencies)
+ * - **Per-input sighash computation** for multi-input transactions
+ *   (each input gets its own BIP-341 sighash for independent FROST signing)
+ * - **Full transaction serialization** with proper segwit witness structure
+ * - **Broadcast via Mempool.space API** (mainnet, testnet, signet, regtest)
+ *
+ * No external dependencies beyond Node.js crypto (SHA-256).
+ *
+ * @example
+ * ```typescript
+ * import { BitcoinTaprootAdapter } from '@sequence0/sdk';
+ *
+ * const btc = new BitcoinTaprootAdapter({ network: 'mainnet' });
+ *
+ * // Derive a Taproot address from a FROST group public key
+ * const addr = btc.deriveAddress('02abcdef...');
+ * console.log(addr.address); // bc1p...
+ *
+ * // Get balance and UTXOs
+ * const balance = await btc.getBalance('bc1p...');
+ * const utxos = await btc.getUTXOs('bc1p...');
+ *
+ * // Build, sign, and broadcast
+ * const unsignedTx = await btc.buildTransaction(
+ *   { to: 'bc1p...recipient', amount: 50000, feeRate: 15 },
+ *   'bc1p...sender'
+ * );
+ * // ... sign via FROST ...
+ * const txid = await btc.broadcast(signedTxHex);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BitcoinTaprootAdapter = void 0;
+exports.createBitcoinTaprootAdapter = createBitcoinTaprootAdapter;
+exports.createBitcoinTestnetTaprootAdapter = createBitcoinTestnetTaprootAdapter;
+const errors_1 = require("../utils/errors");
+// ── Constants ──
+const DEFAULT_APIS = {
+    mainnet: 'https://mempool.space/api',
+    testnet: 'https://mempool.space/testnet/api',
+    signet: 'https://mempool.space/signet/api',
+    regtest: 'http://localhost:3000/api', // Local mempool instance
+};
+/** Minimum output value in satoshis (dust limit for P2TR) */
+const DUST_THRESHOLD = 546;
+/** Estimated vbytes per Taproot key-path input */
+const VBYTES_PER_INPUT = 58;
+/** Estimated vbytes per P2TR output */
+const VBYTES_PER_OUTPUT = 43;
+/** Fixed overhead vbytes per transaction */
+const TX_OVERHEAD_VBYTES = 11;
+// ── Adapter ──
+class BitcoinTaprootAdapter {
+    constructor(options = {}) {
+        this.network = options.network || 'mainnet';
+        this.apiUrl = options.apiUrl || DEFAULT_APIS[this.network];
+    }
+    getRpcUrl() {
+        return this.apiUrl;
+    }
+    // ────────────────────────────────────────────────
+    //  Address Derivation
+    // ────────────────────────────────────────────────
+    /**
+     * Derive a Taproot (P2TR) address from a FROST group public key.
+     *
+     * The FROST group verifying key is a secp256k1 point. For Taproot:
+     * 1. Extract the x-only public key (32 bytes)
+     * 2. Compute the Taproot tweak: t = hash_TapTweak(x_only_pubkey)
+     * 3. Compute the output key: Q = P + t*G
+     * 4. Encode as Bech32m with witness version 1
+     *
+     * @param groupPubkeyHex - Hex-encoded FROST group verifying key (33 bytes compressed or 32 bytes x-only)
+     * @returns TaprootAddressInfo with address, keys, and scriptPubkey
+     */
+    deriveAddress(groupPubkeyHex) {
+        const pubkeyClean = groupPubkeyHex.startsWith('0x')
+            ? groupPubkeyHex.slice(2)
+            : groupPubkeyHex;
+        const pubkeyBytes = hexToBytes(pubkeyClean);
+        // Extract x-only public key
+        const xOnly = extractXOnlyPubkey(pubkeyBytes);
+        // Compute Taproot tweak (key-path only, no script tree)
+        const tweak = computeTapTweak(xOnly);
+        // Compute tweaked output key
+        const outputKey = tweakPublicKey(xOnly, tweak);
+        // Encode as Bech32m
+        const hrp = networkToHrp(this.network);
+        const address = encodeBech32m(hrp, outputKey);
+        // Build scriptPubKey: OP_1 <32-byte output key>
+        const scriptPubkey = '51' + '20' + bytesToHex(outputKey);
+        return {
+            address,
+            xOnlyPubkey: bytesToHex(xOnly),
+            outputKey: bytesToHex(outputKey),
+            scriptPubkey,
+            tapTweak: bytesToHex(tweak),
+            network: this.network,
+        };
+    }
+    /**
+     * Compute the Taproot tweak for a FROST group public key.
+     *
+     * The FROST signing protocol must apply this tweak to the group private key
+     * before signing. This ensures the Schnorr signature verifies against the
+     * tweaked output key (which is what the scriptPubKey commits to).
+     *
+     * The tweak scalar t = hash_TapTweak(internal_key) is returned as hex.
+     * During FROST signing, the group's secret share is tweaked:
+     *   tweaked_share = share + t  (mod n)
+     *
+     * @param groupPubkeyHex - Hex-encoded FROST group verifying key (33 or 32 bytes)
+     * @returns Hex-encoded 32-byte tweak scalar
+     */
+    getTapTweak(groupPubkeyHex) {
+        const pubkeyClean = groupPubkeyHex.startsWith('0x')
+            ? groupPubkeyHex.slice(2)
+            : groupPubkeyHex;
+        const pubkeyBytes = hexToBytes(pubkeyClean);
+        const xOnly = extractXOnlyPubkey(pubkeyBytes);
+        const tweak = computeTapTweak(xOnly);
+        return bytesToHex(tweak);
+    }
+    // ────────────────────────────────────────────────
+    //  UTXO Management
+    // ────────────────────────────────────────────────
+    /**
+     * Fetch unspent transaction outputs (UTXOs) for a Taproot address.
+     *
+     * @param address - Bech32m Taproot address (bc1p... / tb1p...)
+     * @returns Array of UTXOs sorted by value (largest first)
+     */
+    async getUTXOs(address) {
+        try {
+            const response = await fetch(`${this.apiUrl}/address/${address}/utxo`);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+            }
+            const rawUtxos = await response.json();
+            // Derive scriptPubkey from the address for all UTXOs
+            const scriptPubkey = this.addressToScriptPubkey(address);
+            const utxos = rawUtxos.map((u) => ({
+                txid: u.txid,
+                vout: u.vout,
+                value: u.value,
+                scriptPubkey,
+                status: {
+                    confirmed: u.status?.confirmed ?? false,
+                    blockHeight: u.status?.block_height,
+                    blockHash: u.status?.block_hash,
+                    blockTime: u.status?.block_time,
+                },
+            }));
+            // Sort by value descending (largest first for optimal UTXO selection)
+            utxos.sort((a, b) => b.value - a.value);
+            return utxos;
+        }
+        catch (e) {
+            throw new errors_1.ChainError(`Failed to fetch UTXOs for ${address}: ${e.message}`, 'bitcoin');
+        }
+    }
+    // ────────────────────────────────────────────────
+    //  Balance
+    // ────────────────────────────────────────────────
+    /**
+     * Get the balance of a Bitcoin address in satoshis.
+     * Includes both confirmed and unconfirmed (mempool) balances.
+     *
+     * @param address - Taproot address
+     * @returns Balance in satoshis as a string
+     */
+    async getBalance(address) {
+        try {
+            const response = await fetch(`${this.apiUrl}/address/${address}`);
+            if (!response.ok) {
+                return '0';
+            }
+            const data = await response.json();
+            const confirmed = (data.chain_stats?.funded_txo_sum ?? 0) -
+                (data.chain_stats?.spent_txo_sum ?? 0);
+            const unconfirmed = (data.mempool_stats?.funded_txo_sum ?? 0) -
+                (data.mempool_stats?.spent_txo_sum ?? 0);
+            return Math.max(0, confirmed + unconfirmed).toString();
+        }
+        catch {
+            return '0';
+        }
+    }
+    /**
+     * Get the confirmed balance only (excluding mempool transactions).
+     *
+     * @param address - Taproot address
+     * @returns Confirmed balance in satoshis as a string
+     */
+    async getConfirmedBalance(address) {
+        try {
+            const response = await fetch(`${this.apiUrl}/address/${address}`);
+            if (!response.ok) {
+                return '0';
+            }
+            const data = await response.json();
+            const confirmed = (data.chain_stats?.funded_txo_sum ?? 0) -
+                (data.chain_stats?.spent_txo_sum ?? 0);
+            return Math.max(0, confirmed).toString();
+        }
+        catch {
+            return '0';
+        }
+    }
+    // ────────────────────────────────────────────────
+    //  Fee Estimation
+    // ────────────────────────────────────────────────
+    /**
+     * Get recommended fee rates from the mempool.
+     *
+     * @returns Fee rate estimates in sat/vB
+     */
+    async getFeeRates() {
+        try {
+            const response = await fetch(`${this.apiUrl}/v1/fees/recommended`);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            const data = await response.json();
+            return {
+                fastest: data.fastestFee ?? 20,
+                halfHour: data.halfHourFee ?? 15,
+                hour: data.hourFee ?? 10,
+                economy: data.economyFee ?? 5,
+                minimum: data.minimumFee ?? 1,
+            };
+        }
+        catch (e) {
+            throw new errors_1.ChainError(`Failed to fetch fee rates: ${e.message}`, 'bitcoin');
+        }
+    }
+    /**
+     * Estimate the fee for a transaction with the given number of inputs and outputs.
+     *
+     * @param inputCount - Number of Taproot inputs
+     * @param outputCount - Number of outputs (including change)
+     * @param feeRate - Fee rate in sat/vB
+     * @returns Estimated fee in satoshis
+     */
+    estimateFee(inputCount, outputCount, feeRate) {
+        const vsize = TX_OVERHEAD_VBYTES +
+            inputCount * VBYTES_PER_INPUT +
+            outputCount * VBYTES_PER_OUTPUT;
+        return Math.ceil(vsize * feeRate);
+    }
+    // ────────────────────────────────────────────────
+    //  Transaction Building (ChainAdapter interface)
+    // ────────────────────────────────────────────────
+    /**
+     * Build an unsigned Bitcoin Taproot transaction.
+     *
+     * Fetches UTXOs, selects inputs using a largest-first strategy,
+     * constructs outputs (recipient + change), computes the BIP-341
+     * sighash, and returns the serialized unsigned transaction.
+     *
+     * The returned sighash is what gets passed to the FROST signing
+     * protocol. The resulting 64-byte Schnorr signature is directly
+     * usable as the Taproot witness.
+     *
+     * @param tx - Transaction parameters (to, amount, feeRate)
+     * @param fromAddress - Sender's Taproot address
+     * @returns Hex-encoded unsigned transaction data (JSON-encoded internally)
+     */
+    async buildTransaction(tx, fromAddress) {
+        try {
+            // Validate addresses
+            if (!this.isTaprootAddress(fromAddress)) {
+                throw new Error(`Sender address is not a valid Taproot address: ${fromAddress}`);
+            }
+            if (!this.isTaprootAddress(tx.to)) {
+                throw new Error(`Recipient address is not a valid Taproot address: ${tx.to}`);
+            }
+            // Fetch UTXOs
+            const utxos = await this.getUTXOs(fromAddress);
+            if (utxos.length === 0) {
+                throw new Error('No UTXOs available for this address');
+            }
+            // Determine fee rate
+            const feeRate = tx.feeRate || 10; // Default 10 sat/vB
+            // Select UTXOs (largest first)
+            const selection = this.selectUTXOs(utxos, tx.amount, feeRate);
+            // Build outputs
+            const outputs = [
+                { address: tx.to, value: tx.amount },
+            ];
+            // Add change output if above dust threshold
+            const change = selection.totalValue - tx.amount - selection.fee;
+            if (change > DUST_THRESHOLD) {
+                outputs.push({ address: fromAddress, value: change });
+            }
+            // Compute sighash for FROST signing
+            const inputs = selection.selectedUtxos.map(u => ({
+                txid: u.txid,
+                vout: u.vout,
+                value: u.value,
+                scriptPubkey: u.scriptPubkey,
+            }));
+            // Build the unsigned transaction with per-input sighashes
+            const sighashes = this.computeAllSighashes(inputs, outputs);
+            const unsignedTx = {
+                sighash: sighashes[0],
+                sighashes,
+                rawUnsigned: this.serializeUnsignedTx(inputs, outputs),
+                inputs,
+                outputs,
+                estimatedVsize: selection.estimatedVsize,
+                estimatedFee: selection.fee,
+            };
+            // Return as hex-encoded JSON for the ChainAdapter interface
+            return Buffer.from(JSON.stringify(unsignedTx)).toString('hex');
+        }
+        catch (e) {
+            throw new errors_1.ChainError(`Failed to build Taproot transaction: ${e.message}`, 'bitcoin');
+        }
+    }
+    /**
+     * Build an unsigned Taproot transaction with explicit control over inputs and outputs.
+     *
+     * For advanced usage when you want to manually select UTXOs and construct
+     * the transaction outputs.
+     *
+     * @param inputs - UTXOs to spend
+     * @param outputs - Transaction outputs
+     * @param xOnlyInternalKey - 32-byte x-only internal key (hex-encoded)
+     * @param feeRate - Fee rate in sat/vB
+     * @returns UnsignedTaprootTx ready for FROST signing
+     */
+    buildUnsignedTx(inputs, outputs, feeRate) {
+        if (inputs.length === 0) {
+            throw new errors_1.ChainError('No inputs provided', 'bitcoin');
+        }
+        if (outputs.length === 0) {
+            throw new errors_1.ChainError('No outputs provided', 'bitcoin');
+        }
+        const totalInput = inputs.reduce((sum, i) => sum + i.value, 0);
+        const totalOutput = outputs.reduce((sum, o) => sum + o.value, 0);
+        const estimatedVsize = TX_OVERHEAD_VBYTES +
+            inputs.length * VBYTES_PER_INPUT +
+            outputs.length * VBYTES_PER_OUTPUT;
+        const fee = Math.ceil(estimatedVsize * feeRate);
+        if (totalInput < totalOutput + fee) {
+            throw new errors_1.ChainError(`Insufficient funds: ${totalInput} sat available, ` +
+                `${totalOutput + fee} sat needed (${totalOutput} output + ${fee} fee)`, 'bitcoin');
+        }
+        const sighashes = this.computeAllSighashes(inputs, outputs);
+        return {
+            sighash: sighashes[0],
+            sighashes,
+            rawUnsigned: this.serializeUnsignedTx(inputs, outputs),
+            inputs,
+            outputs,
+            estimatedVsize,
+            estimatedFee: fee,
+        };
+    }
+    /**
+     * Attach FROST Schnorr signature(s) to an unsigned Taproot transaction.
+     *
+     * The FROST signing protocol produces 64-byte BIP-340 Schnorr signatures
+     * (R_x || s) that are directly used as Taproot witness for key-path spends.
+     *
+     * For single-input transactions: pass a single 128-char hex signature.
+     * For multi-input transactions: pass signatures separated by commas, or
+     * a single signature that will be applied to all inputs (if all inputs
+     * share the same signing key and the caller signs each sighash separately).
+     *
+     * @param unsignedTxHex - Hex-encoded unsigned transaction (from buildTransaction)
+     * @param signatureHex - 64-byte FROST Schnorr signature(s). For multi-input
+     *   transactions, separate per-input signatures with commas.
+     * @returns Hex-encoded signed transaction ready for broadcast
+     */
+    async attachSignature(unsignedTxHex, signatureHex) {
+        try {
+            // Parse the unsigned transaction
+            const unsignedTx = JSON.parse(Buffer.from(unsignedTxHex, 'hex').toString());
+            // Parse signature(s)
+            const signatures = this.parseSignatures(signatureHex, unsignedTx.inputs.length);
+            // Build the signed transaction with Taproot witness
+            const signedTx = this.serializeSignedTx(unsignedTx, signatures);
+            return Buffer.from(JSON.stringify(signedTx)).toString('hex');
+        }
+        catch (e) {
+            throw new errors_1.ChainError(`Failed to attach Taproot signature: ${e.message}`, 'bitcoin');
+        }
+    }
+    /**
+     * Attach FROST Schnorr signature(s) with full output (returns structured data).
+     *
+     * @param unsignedTx - The UnsignedTaprootTx from buildUnsignedTx
+     * @param signatureHex - 64-byte FROST Schnorr signature(s) (hex). For multi-input
+     *   transactions, pass an array of per-input signatures or a comma-separated string.
+     * @returns SignedTaprootTx with raw_signed, txid, and vsize
+     */
+    attachSignatureToTx(unsignedTx, signatureHex) {
+        const sigs = Array.isArray(signatureHex)
+            ? signatureHex.map(s => {
+                const clean = s.startsWith('0x') ? s.slice(2) : s;
+                if (clean.length !== 128) {
+                    throw new errors_1.ChainError(`Schnorr signature must be 64 bytes (128 hex chars), got ${clean.length}`, 'bitcoin');
+                }
+                return clean;
+            })
+            : this.parseSignatures(signatureHex, unsignedTx.inputs.length);
+        return this.serializeSignedTx(unsignedTx, sigs);
+    }
+    /**
+     * Parse signature hex into per-input signatures.
+     * Supports: single sig (applied to all inputs), comma-separated, or concatenated.
+     */
+    parseSignatures(signatureHex, inputCount) {
+        const raw = signatureHex.startsWith('0x') ? signatureHex.slice(2) : signatureHex;
+        // Check for comma-separated signatures
+        if (raw.includes(',')) {
+            const parts = raw.split(',').map(s => s.trim());
+            if (parts.length !== inputCount) {
+                throw new Error(`Expected ${inputCount} signatures for ${inputCount} inputs, got ${parts.length}`);
+            }
+            for (const s of parts) {
+                if (s.length !== 128) {
+                    throw new Error(`Each Schnorr signature must be 128 hex chars, got ${s.length}`);
+                }
+            }
+            return parts;
+        }
+        // Single signature (128 hex chars) — replicate for all inputs
+        if (raw.length === 128) {
+            return new Array(inputCount).fill(raw);
+        }
+        // Concatenated signatures (128 * inputCount hex chars)
+        if (raw.length === 128 * inputCount) {
+            const sigs = [];
+            for (let i = 0; i < inputCount; i++) {
+                sigs.push(raw.slice(i * 128, (i + 1) * 128));
+            }
+            return sigs;
+        }
+        throw new Error(`Invalid signature format: expected 128 hex chars (single), ` +
+            `${128 * inputCount} chars (concatenated), or comma-separated. Got ${raw.length} chars.`);
+    }
+    // ────────────────────────────────────────────────
+    //  Broadcast
+    // ────────────────────────────────────────────────
+    /**
+     * Broadcast a signed Taproot transaction to the Bitcoin network.
+     *
+     * Accepts either a raw Bitcoin transaction hex or the hex-encoded JSON
+     * format from attachSignature().
+     *
+     * @param signedTx - Hex-encoded signed transaction
+     * @returns Transaction ID (txid)
+     */
+    async broadcast(signedTx) {
+        try {
+            let rawHex;
+            // Check if this is our JSON-wrapped format
+            const decoded = Buffer.from(signedTx, 'hex').toString();
+            if (decoded.startsWith('{')) {
+                const parsed = JSON.parse(decoded);
+                rawHex = parsed.rawSigned;
+            }
+            else {
+                rawHex = signedTx;
+            }
+            const response = await fetch(`${this.apiUrl}/tx`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'text/plain' },
+                body: rawHex,
+            });
+            if (!response.ok) {
+                const error = await response.text();
+                throw new Error(`Broadcast rejected: ${error}`);
+            }
+            return await response.text(); // Returns the txid
+        }
+        catch (e) {
+            throw new errors_1.ChainError(`Failed to broadcast Taproot TX: ${e.message}`, 'bitcoin');
+        }
+    }
+    // ────────────────────────────────────────────────
+    //  Transaction Lookup
+    // ────────────────────────────────────────────────
+    /**
+     * Get transaction details by txid.
+     *
+     * @param txid - Transaction ID
+     * @returns Transaction data or null if not found
+     */
+    async getTransaction(txid) {
+        try {
+            const response = await fetch(`${this.apiUrl}/tx/${txid}`);
+            if (!response.ok)
+                return null;
+            return await response.json();
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Get the current block height.
+     */
+    async getBlockHeight() {
+        try {
+            const response = await fetch(`${this.apiUrl}/blocks/tip/height`);
+            if (!response.ok)
+                throw new Error(`HTTP ${response.status}`);
+            return parseInt(await response.text(), 10);
+        }
+        catch (e) {
+            throw new errors_1.ChainError(`Failed to get block height: ${e.message}`, 'bitcoin');
+        }
+    }
+    // ────────────────────────────────────────────────
+    //  Utilities
+    // ────────────────────────────────────────────────
+    /**
+     * Check if an address is a valid Taproot (P2TR) address.
+     */
+    isTaprootAddress(address) {
+        if (this.network === 'mainnet')
+            return address.startsWith('bc1p');
+        if (this.network === 'testnet' || this.network === 'signet')
+            return address.startsWith('tb1p');
+        if (this.network === 'regtest')
+            return address.startsWith('bcrt1p');
+        return false;
+    }
+    /**
+     * Convert a Taproot address to its scriptPubKey.
+     * P2TR scriptPubKey: OP_1 (0x51) + PUSH32 (0x20) + <32-byte witness program>
+     */
+    addressToScriptPubkey(address) {
+        const witnessProgram = decodeBech32m(address);
+        return '51' + '20' + bytesToHex(witnessProgram);
+    }
+    // ────────────────────────────────────────────────
+    //  Internal: UTXO Selection
+    // ────────────────────────────────────────────────
+    selectUTXOs(utxos, targetAmount, feeRate) {
+        const selected = [];
+        let total = 0;
+        // Largest-first selection
+        for (const utxo of utxos) {
+            selected.push(utxo);
+            total += utxo.value;
+            // Estimate fee with current selection (2 outputs: recipient + change)
+            const outputCount = 2;
+            const vsize = TX_OVERHEAD_VBYTES +
+                selected.length * VBYTES_PER_INPUT +
+                outputCount * VBYTES_PER_OUTPUT;
+            const fee = Math.ceil(vsize * feeRate);
+            if (total >= targetAmount + fee) {
+                return {
+                    selectedUtxos: selected,
+                    totalValue: total,
+                    fee,
+                    estimatedVsize: vsize,
+                };
+            }
+        }
+        // Not enough funds
+        const minFee = this.estimateFee(utxos.length, 2, feeRate);
+        throw new Error(`Insufficient balance: have ${total} sat, need ${targetAmount + minFee} sat ` +
+            `(${targetAmount} amount + ~${minFee} fee)`);
+    }
+    // ────────────────────────────────────────────────
+    //  Internal: Transaction Serialization
+    // ────────────────────────────────────────────────
+    /**
+     * Serialize an unsigned Taproot transaction.
+     *
+     * Bitcoin transaction format (segwit):
+     * - Version (4 bytes LE)
+     * - Marker + Flag (00 01 for segwit)
+     * - Input count (varint)
+     * - Inputs (outpoint + empty scriptSig + sequence)
+     * - Output count (varint)
+     * - Outputs (value + scriptPubkey)
+     * - Witness (placeholder for signing)
+     * - Locktime (4 bytes LE)
+     */
+    serializeUnsignedTx(inputs, outputs) {
+        const buf = [];
+        // Version 2 (for Taproot)
+        pushLE32(buf, 2);
+        // Segwit marker + flag
+        buf.push(0x00, 0x01);
+        // Input count
+        pushVarint(buf, inputs.length);
+        // Inputs
+        for (const input of inputs) {
+            // Previous txid (reversed byte order)
+            const txidBytes = hexToBytes(input.txid);
+            txidBytes.reverse();
+            buf.push(...txidBytes);
+            // Previous vout (4 bytes LE)
+            pushLE32(buf, input.vout);
+            // ScriptSig length (0 for segwit)
+            buf.push(0x00);
+            // Sequence (0xFFFFFFFD for RBF compatibility)
+            pushLE32(buf, 0xfffffffd);
+        }
+        // Output count
+        pushVarint(buf, outputs.length);
+        // Outputs
+        for (const output of outputs) {
+            // Value (8 bytes LE)
+            pushLE64(buf, output.value);
+            // ScriptPubKey
+            const script = hexToBytes(this.addressToScriptPubkey(output.address));
+            pushVarint(buf, script.length);
+            buf.push(...script);
+        }
+        // Witness placeholder (1 item per input: 64 zero bytes for Schnorr sig)
+        for (let i = 0; i < inputs.length; i++) {
+            buf.push(0x01); // 1 witness item
+            buf.push(0x40); // 64 bytes
+            buf.push(...new Array(64).fill(0)); // placeholder
+        }
+        // Locktime
+        pushLE32(buf, 0);
+        return bytesToHex(new Uint8Array(buf));
+    }
+    /**
+     * Serialize a signed Taproot transaction with per-input signatures.
+     *
+     * @param unsignedTx - The unsigned transaction data
+     * @param signatures - Array of per-input signature hex strings (128 chars each)
+     */
+    serializeSignedTx(unsignedTx, signatures) {
+        if (signatures.length !== unsignedTx.inputs.length) {
+            throw new Error(`Signature count (${signatures.length}) does not match ` +
+                `input count (${unsignedTx.inputs.length})`);
+        }
+        const buf = [];
+        // Version 2
+        pushLE32(buf, 2);
+        // Segwit marker + flag
+        buf.push(0x00, 0x01);
+        // Input count
+        pushVarint(buf, unsignedTx.inputs.length);
+        // Inputs
+        for (const input of unsignedTx.inputs) {
+            const txidBytes = hexToBytes(input.txid);
+            txidBytes.reverse();
+            buf.push(...txidBytes);
+            pushLE32(buf, input.vout);
+            buf.push(0x00); // Empty scriptSig
+            pushLE32(buf, 0xfffffffd);
+        }
+        // Output count
+        pushVarint(buf, unsignedTx.outputs.length);
+        // Outputs
+        for (const output of unsignedTx.outputs) {
+            pushLE64(buf, output.value);
+            const script = hexToBytes(this.addressToScriptPubkey(output.address));
+            pushVarint(buf, script.length);
+            buf.push(...script);
+        }
+        // Witness: per-input Schnorr signatures for key-path spend
+        for (let i = 0; i < unsignedTx.inputs.length; i++) {
+            const sigBytes = hexToBytes(signatures[i]);
+            buf.push(0x01); // 1 witness item
+            buf.push(0x40); // 64 bytes (Schnorr signature, no sighash type suffix)
+            buf.push(...sigBytes);
+        }
+        // Locktime
+        pushLE32(buf, 0);
+        const rawSigned = bytesToHex(new Uint8Array(buf));
+        // Compute txid (double SHA-256 of non-witness serialization)
+        const txid = computeTxid(buf, unsignedTx.inputs.length, unsignedTx.outputs, this);
+        // Compute vsize
+        const witnessSize = unsignedTx.inputs.length * (1 + 1 + 64); // items + length + sig
+        const totalSize = buf.length;
+        const baseSize = totalSize - witnessSize - 2; // subtract witness + marker/flag
+        const weight = baseSize * 3 + totalSize;
+        const vsize = Math.ceil(weight / 4);
+        return {
+            rawSigned,
+            txid,
+            vsize,
+        };
+    }
+    /**
+     * Compute the BIP-341 Taproot sighash for key-path spend.
+     *
+     * The sighash message for SIGHASH_DEFAULT (0x00) includes:
+     * - Epoch (0x00)
+     * - Sighash type (0x00)
+     * - Transaction version (4 bytes LE)
+     * - Locktime (4 bytes LE)
+     * - SHA-256 of prevouts
+     * - SHA-256 of amounts
+     * - SHA-256 of scriptPubKeys
+     * - SHA-256 of sequences
+     * - SHA-256 of outputs
+     * - Spend type (0x00 for key-path, no annex)
+     * - Input index (4 bytes LE)
+     */
+    /**
+     * Compute all per-input BIP-341 sighashes for the transaction.
+     *
+     * Each input has its own sighash because the input_index field differs.
+     * The common transaction-level hashes (prevouts, amounts, scripts, sequences,
+     * outputs) are precomputed once and reused across all inputs.
+     *
+     * @returns Array of hex-encoded sighashes, one per input
+     */
+    computeAllSighashes(inputs, outputs) {
+        // Precompute the transaction-level hashes (shared across all inputs)
+        const tagHash = sha256(new TextEncoder().encode('TapSighash'));
+        // SHA-256 of prevouts
+        const prevoutsBuf = [];
+        for (const input of inputs) {
+            const txidBytes = hexToBytes(input.txid);
+            txidBytes.reverse();
+            prevoutsBuf.push(...txidBytes);
+            pushLE32(prevoutsBuf, input.vout);
+        }
+        const hashPrevouts = sha256(new Uint8Array(prevoutsBuf));
+        // SHA-256 of amounts
+        const amountsBuf = [];
+        for (const input of inputs) {
+            pushLE64(amountsBuf, input.value);
+        }
+        const hashAmounts = sha256(new Uint8Array(amountsBuf));
+        // SHA-256 of scriptPubKeys (with compact size prefix)
+        const scriptsBuf = [];
+        for (const input of inputs) {
+            const script = hexToBytes(input.scriptPubkey);
+            pushVarint(scriptsBuf, script.length);
+            scriptsBuf.push(...script);
+        }
+        const hashScripts = sha256(new Uint8Array(scriptsBuf));
+        // SHA-256 of sequences
+        const seqsBuf = [];
+        for (let i = 0; i < inputs.length; i++) {
+            pushLE32(seqsBuf, 0xfffffffd);
+        }
+        const hashSequences = sha256(new Uint8Array(seqsBuf));
+        // SHA-256 of outputs
+        const outputsBuf = [];
+        for (const output of outputs) {
+            pushLE64(outputsBuf, output.value);
+            const script = hexToBytes(this.addressToScriptPubkey(output.address));
+            pushVarint(outputsBuf, script.length);
+            outputsBuf.push(...script);
+        }
+        const hashOutputs = sha256(new Uint8Array(outputsBuf));
+        // Compute per-input sighash
+        const sighashes = [];
+        for (let inputIdx = 0; inputIdx < inputs.length; inputIdx++) {
+            const parts = [];
+            // Tag hash prefix (used twice per BIP-340 tagged hash convention)
+            parts.push(...tagHash, ...tagHash);
+            // Epoch (1 byte)
+            parts.push(0x00);
+            // Sighash type: SIGHASH_DEFAULT (1 byte)
+            parts.push(0x00);
+            // Transaction version (4 bytes LE)
+            pushLE32(parts, 2);
+            // Locktime (4 bytes LE)
+            pushLE32(parts, 0);
+            // Precomputed hashes
+            parts.push(...hashPrevouts);
+            parts.push(...hashAmounts);
+            parts.push(...hashScripts);
+            parts.push(...hashSequences);
+            parts.push(...hashOutputs);
+            // Spend type: 0x00 (key-path, no annex)
+            parts.push(0x00);
+            // Input index (4 bytes LE) — THIS is what differs per input
+            pushLE32(parts, inputIdx);
+            // Final sighash = SHA-256 of the tagged hash message
+            const sighash = sha256(new Uint8Array(parts));
+            sighashes.push(bytesToHex(sighash));
+        }
+        return sighashes;
+    }
+}
+exports.BitcoinTaprootAdapter = BitcoinTaprootAdapter;
+const Secp256k1 = {
+    /** Field prime */
+    P: 0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2fn,
+    /** Curve order */
+    N: 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n,
+    /** Generator x */
+    Gx: 0x79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798n,
+    /** Generator y */
+    Gy: 0x483ada7726a3c4655da4fbfc0e1108a8fd17b448a68554199c47d08ffb10d4b8n,
+    /** Get generator point */
+    G() {
+        return { x: this.Gx, y: this.Gy };
+    },
+    /**
+     * Modular exponentiation: base^exp mod m
+     * Uses square-and-multiply for efficiency.
+     */
+    modPow(base, exp, m) {
+        let result = 1n;
+        base = ((base % m) + m) % m;
+        while (exp > 0n) {
+            if (exp & 1n) {
+                result = (result * base) % m;
+            }
+            exp >>= 1n;
+            base = (base * base) % m;
+        }
+        return result;
+    },
+    /** Modular inverse using Fermat's little theorem: a^(p-2) mod p */
+    modInverse(a, m) {
+        return this.modPow(((a % m) + m) % m, m - 2n, m);
+    },
+    /** Modular square root: returns r such that r^2 = a (mod p), or throws.
+     *  Uses the Tonelli-Shanks shortcut for p = 3 mod 4: r = a^((p+1)/4) mod p */
+    modSqrt(a) {
+        const p = this.P;
+        // secp256k1 p % 4 == 3, so we can use the simple formula
+        const r = this.modPow(((a % p) + p) % p, (p + 1n) / 4n, p);
+        if ((r * r) % p !== ((a % p) + p) % p) {
+            throw new Error('No square root exists for this value');
+        }
+        return r;
+    },
+    /**
+     * Lift an x-only public key to a full curve point with even y-coordinate.
+     * Per BIP-340: given x, compute y = sqrt(x^3 + 7), pick the even root.
+     */
+    liftX(xBytes) {
+        const x = bytesToBigInt(xBytes);
+        const p = this.P;
+        if (x >= p) {
+            throw new Error('x-coordinate exceeds field prime');
+        }
+        // y^2 = x^3 + 7 mod p
+        const y2 = (this.modPow(x, 3n, p) + 7n) % p;
+        let y = this.modSqrt(y2);
+        // BIP-340: pick the even y (y % 2 == 0)
+        if (y & 1n) {
+            y = p - y;
+        }
+        return { x, y };
+    },
+    /**
+     * Point addition: P + Q on secp256k1.
+     * Handles identity, doubling, and general addition.
+     */
+    pointAdd(p1, p2) {
+        if (p1 === null)
+            return p2;
+        if (p2 === null)
+            return p1;
+        const p = this.P;
+        if (p1.x === p2.x) {
+            if (p1.y === p2.y) {
+                // Point doubling
+                return this.pointDouble(p1);
+            }
+            // P + (-P) = O (point at infinity)
+            return null;
+        }
+        // General addition: lambda = (y2 - y1) / (x2 - x1)
+        const dy = ((p2.y - p1.y) % p + p) % p;
+        const dx = ((p2.x - p1.x) % p + p) % p;
+        const lambda = (dy * this.modInverse(dx, p)) % p;
+        const x3 = ((lambda * lambda - p1.x - p2.x) % p + p) % p;
+        const y3 = ((lambda * (p1.x - x3) - p1.y) % p + p) % p;
+        return { x: x3, y: y3 };
+    },
+    /** Point doubling: 2P on secp256k1 */
+    pointDouble(pt) {
+        const p = this.P;
+        if (pt.y === 0n)
+            return null;
+        // lambda = (3 * x^2 + a) / (2 * y)   where a = 0 for secp256k1
+        const num = (3n * pt.x * pt.x) % p;
+        const den = (2n * pt.y) % p;
+        const lambda = (num * this.modInverse(den, p)) % p;
+        const x3 = ((lambda * lambda - 2n * pt.x) % p + p) % p;
+        const y3 = ((lambda * (pt.x - x3) - pt.y) % p + p) % p;
+        return { x: x3, y: y3 };
+    },
+    /**
+     * Scalar multiplication: n * G using double-and-add.
+     * Only used for tweaking, so performance is not critical.
+     */
+    mulG(n) {
+        const order = this.N;
+        n = ((n % order) + order) % order;
+        if (n === 0n) {
+            throw new Error('Zero scalar in mulG');
+        }
+        let result = null;
+        let base = this.G();
+        let k = n;
+        while (k > 0n) {
+            if (k & 1n) {
+                result = this.pointAdd(result, base);
+            }
+            base = this.pointAdd(base, base);
+            k >>= 1n;
+        }
+        if (result === null) {
+            throw new Error('mulG produced point at infinity');
+        }
+        return result;
+    },
+};
+/** Convert a Uint8Array to a bigint (big-endian) */
+function bytesToBigInt(bytes) {
+    let result = 0n;
+    for (const b of bytes) {
+        result = (result << 8n) | BigInt(b);
+    }
+    return result;
+}
+/** Convert a bigint to a 32-byte Uint8Array (big-endian, zero-padded) */
+function bigIntToBytes32(n) {
+    const bytes = new Uint8Array(32);
+    let val = n;
+    for (let i = 31; i >= 0; i--) {
+        bytes[i] = Number(val & 0xffn);
+        val >>= 8n;
+    }
+    return bytes;
+}
+// ────────────────────────────────────────────────
+//  Pure Helper Functions
+// ────────────────────────────────────────────────
+/** Extract x-only (32-byte) public key from compressed (33-byte) or raw format */
+function extractXOnlyPubkey(bytes) {
+    if (bytes.length === 33) {
+        // Compressed: drop the 02/03 prefix
+        if (bytes[0] !== 0x02 && bytes[0] !== 0x03) {
+            throw new Error(`Invalid compressed key prefix: 0x${bytes[0].toString(16)}`);
+        }
+        return bytes.slice(1, 33);
+    }
+    if (bytes.length === 32) {
+        return bytes;
+    }
+    if (bytes.length === 65) {
+        // Uncompressed: drop the 04 prefix, take x
+        if (bytes[0] !== 0x04) {
+            throw new Error(`Invalid uncompressed key prefix: 0x${bytes[0].toString(16)}`);
+        }
+        return bytes.slice(1, 33);
+    }
+    throw new Error(`Invalid public key length: ${bytes.length} (expected 32, 33, or 65)`);
+}
+/** Compute BIP-341 TapTweak hash for key-path only (no script tree) */
+function computeTapTweak(internalKey) {
+    const tag = sha256(new TextEncoder().encode('TapTweak'));
+    const msg = new Uint8Array(tag.length * 2 + internalKey.length);
+    msg.set(tag, 0);
+    msg.set(tag, tag.length);
+    msg.set(internalKey, tag.length * 2);
+    return sha256(msg);
+}
+/**
+ * Tweak a public key per BIP-341:  Q = lift_x(P) + int(tweak) * G
+ *
+ * Uses real secp256k1 EC point arithmetic. The output key Q is the
+ * x-only coordinate of the resulting point. If the resulting point
+ * has an odd y-coordinate, the tweak is negated (BIP-341 spec).
+ *
+ * @param internalKey - 32-byte x-only internal public key
+ * @param tweak - 32-byte tweak scalar (hash_TapTweak output)
+ * @returns 32-byte x-only output key
+ */
+function tweakPublicKey(internalKey, tweak) {
+    // Lift the x-only key to a full point with even y
+    const P = Secp256k1.liftX(internalKey);
+    // Convert tweak bytes to a bigint scalar
+    const t = bytesToBigInt(tweak);
+    if (t >= Secp256k1.N) {
+        throw new Error('Tweak scalar exceeds curve order');
+    }
+    // Compute t * G
+    const tG = Secp256k1.mulG(t);
+    // Compute Q = P + t * G
+    const Q = Secp256k1.pointAdd(P, tG);
+    if (Q === null) {
+        throw new Error('Tweaked key is point at infinity');
+    }
+    // Return x-coordinate of Q as 32 bytes
+    return bigIntToBytes32(Q.x);
+}
+/** Get the Bech32 HRP for a Bitcoin network */
+function networkToHrp(network) {
+    switch (network) {
+        case 'mainnet': return 'bc';
+        case 'testnet':
+        case 'signet': return 'tb';
+        case 'regtest': return 'bcrt';
+    }
+}
+/** Encode data as Bech32m with witness version 1 */
+function encodeBech32m(hrp, data) {
+    const data5 = [1]; // witness version 1
+    // Convert 8-bit to 5-bit groups
+    const converted = convertBits(Array.from(data), 8, 5, true);
+    data5.push(...converted);
+    // Compute Bech32m checksum
+    const checksum = bech32mChecksum(hrp, data5);
+    data5.push(...checksum);
+    // Encode to Bech32 characters
+    const charset = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+    let result = hrp + '1';
+    for (const b of data5) {
+        result += charset[b];
+    }
+    return result;
+}
+/** Decode a Bech32m address to get the 32-byte witness program */
+function decodeBech32m(address) {
+    const charset = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+    const sepPos = address.lastIndexOf('1');
+    if (sepPos < 1)
+        throw new Error('No separator found in Bech32m address');
+    const hrp = address.slice(0, sepPos);
+    const dataPart = address.slice(sepPos + 1);
+    if (dataPart.length < 7)
+        throw new Error('Data part too short');
+    // Decode characters to 5-bit values
+    const data5 = [];
+    for (const c of dataPart) {
+        const idx = charset.indexOf(c);
+        if (idx === -1)
+            throw new Error(`Invalid Bech32m character: ${c}`);
+        data5.push(idx);
+    }
+    // Verify checksum
+    const verifyData = [...hrpExpand(hrp), ...data5];
+    if (bech32Polymod(verifyData) !== 0x2bc830a3) {
+        throw new Error('Invalid Bech32m checksum');
+    }
+    // Remove witness version (first) and checksum (last 6)
+    const payload = data5.slice(1, data5.length - 6);
+    // Convert 5-bit to 8-bit
+    const bytes = convertBits(payload, 5, 8, false);
+    if (bytes.length !== 32) {
+        throw new Error(`Invalid witness program length: ${bytes.length} (expected 32)`);
+    }
+    return new Uint8Array(bytes);
+}
+/** Convert between bit widths */
+function convertBits(data, from, to, pad) {
+    let acc = 0;
+    let bits = 0;
+    const result = [];
+    const maxv = (1 << to) - 1;
+    for (const value of data) {
+        if (value >> from !== 0) {
+            throw new Error(`Invalid value for ${from}-bit conversion: ${value}`);
+        }
+        acc = (acc << from) | value;
+        bits += from;
+        while (bits >= to) {
+            bits -= to;
+            result.push((acc >> bits) & maxv);
+        }
+    }
+    if (pad) {
+        if (bits > 0) {
+            result.push((acc << (to - bits)) & maxv);
+        }
+    }
+    else if (bits >= from || ((acc << (to - bits)) & maxv) !== 0) {
+        throw new Error('Invalid padding');
+    }
+    return result;
+}
+/** Compute Bech32m checksum */
+function bech32mChecksum(hrp, data) {
+    const values = [...hrpExpand(hrp), ...data, 0, 0, 0, 0, 0, 0];
+    const polymod = bech32Polymod(values) ^ 0x2bc830a3;
+    const checksum = [];
+    for (let i = 0; i < 6; i++) {
+        checksum.push((polymod >> (5 * (5 - i))) & 31);
+    }
+    return checksum;
+}
+/** Expand HRP for Bech32 polymod */
+function hrpExpand(hrp) {
+    const result = [];
+    for (const c of hrp) {
+        result.push(c.charCodeAt(0) >> 5);
+    }
+    result.push(0);
+    for (const c of hrp) {
+        result.push(c.charCodeAt(0) & 31);
+    }
+    return result;
+}
+/** Bech32 polymod function */
+function bech32Polymod(values) {
+    const generator = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
+    let chk = 1;
+    for (const v of values) {
+        const top = chk >> 25;
+        chk = ((chk & 0x1ffffff) << 5) ^ v;
+        for (let i = 0; i < 5; i++) {
+            if ((top >> i) & 1) {
+                chk ^= generator[i];
+            }
+        }
+    }
+    return chk;
+}
+// ── Byte manipulation helpers ──
+function hexToBytes(hex) {
+    const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+    const bytes = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+function bytesToHex(bytes) {
+    const arr = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    return Array.from(arr).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+function pushLE32(buf, value) {
+    buf.push(value & 0xff, (value >> 8) & 0xff, (value >> 16) & 0xff, (value >> 24) & 0xff);
+}
+function pushLE64(buf, value) {
+    // JavaScript safe integer limit is 2^53, sufficient for satoshis
+    const low = value & 0xffffffff;
+    const high = Math.floor(value / 0x100000000);
+    pushLE32(buf, low);
+    pushLE32(buf, high);
+}
+function pushVarint(buf, value) {
+    if (value < 0xfd) {
+        buf.push(value);
+    }
+    else if (value <= 0xffff) {
+        buf.push(0xfd, value & 0xff, (value >> 8) & 0xff);
+    }
+    else if (value <= 0xffffffff) {
+        buf.push(0xfe);
+        pushLE32(buf, value);
+    }
+    else {
+        buf.push(0xff);
+        pushLE64(buf, value);
+    }
+}
+/**
+ * Compute SHA-256 hash using Web Crypto API (synchronous fallback via Node.js crypto).
+ *
+ * Note: In a browser environment, this would use crypto.subtle.digest.
+ * For Node.js, we use the built-in crypto module.
+ */
+function sha256(data) {
+    // Use Node.js crypto module
+    const crypto = require('crypto');
+    const hash = crypto.createHash('sha256');
+    hash.update(data);
+    return new Uint8Array(hash.digest());
+}
+/**
+ * Compute txid: double SHA-256 of non-witness serialization, reversed.
+ */
+function computeTxid(fullTxBytes, inputCount, outputs, adapter) {
+    // Build non-witness serialization (strip marker, flag, and witness sections)
+    const buf = [];
+    // Version (first 4 bytes)
+    buf.push(...fullTxBytes.slice(0, 4));
+    // Skip marker (0x00) and flag (0x01) at bytes 4-5
+    // Input count + inputs start at byte 6
+    let pos = 6;
+    // Input count varint
+    const inputCountByte = fullTxBytes[pos];
+    buf.push(inputCountByte);
+    pos++;
+    // Copy inputs (each: 32 txid + 4 vout + 1 scriptSig len + 0 scriptSig + 4 sequence = 41 bytes)
+    for (let i = 0; i < inputCount; i++) {
+        buf.push(...fullTxBytes.slice(pos, pos + 41));
+        pos += 41;
+    }
+    // Output count
+    const outputCountByte = fullTxBytes[pos];
+    buf.push(outputCountByte);
+    pos++;
+    // Copy outputs
+    for (const output of outputs) {
+        // Value (8 bytes)
+        buf.push(...fullTxBytes.slice(pos, pos + 8));
+        pos += 8;
+        // ScriptPubKey length varint
+        const scriptLen = fullTxBytes[pos];
+        buf.push(scriptLen);
+        pos++;
+        // ScriptPubKey data
+        buf.push(...fullTxBytes.slice(pos, pos + scriptLen));
+        pos += scriptLen;
+    }
+    // Skip witness data
+    // Locktime (last 4 bytes of the full transaction)
+    buf.push(...fullTxBytes.slice(fullTxBytes.length - 4));
+    // Double SHA-256
+    const first = sha256(new Uint8Array(buf));
+    const second = sha256(first);
+    // Reverse for display order
+    const reversed = Array.from(second).reverse();
+    return bytesToHex(new Uint8Array(reversed));
+}
+// ── Factory Functions ──
+/**
+ * Create a Bitcoin Taproot adapter for mainnet.
+ */
+function createBitcoinTaprootAdapter(options) {
+    return new BitcoinTaprootAdapter({ ...options, network: 'mainnet' });
+}
+/**
+ * Create a Bitcoin Taproot adapter for testnet.
+ */
+function createBitcoinTestnetTaprootAdapter(options) {
+    return new BitcoinTaprootAdapter({ ...options, network: 'testnet' });
+}
+//# sourceMappingURL=bitcoin-taproot.js.map