@bitcoinerlab/descriptors 2.3.6 → 3.0.0

package/dist/scriptExpressions.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.trLedger = exports.wpkhLedger = exports.shWpkhLedger = exports.pkhLedger = exports.trBIP32 = exports.wpkhBIP32 = exports.shWpkhBIP32 = exports.pkhBIP32 = void 0;
 const bitcoinjs_lib_1 = require("bitcoinjs-lib");
 const keyExpressions_1 = require("./keyExpressions");
+const networkUtils_1 = require("./networkUtils");
 function assertStandardKeyPath(keyPath) {
     // Regular expression to match "/change/index" or "/change/*" format
     const regex = /^\/[01]\/(\d+|\*)$/;
@@ -25,7 +26,7 @@ function standardExpressionsBIP32Maker(purpose, scriptTemplate) {
      * - `{change:0, index:'*'}`.
      */
     function standardScriptExpressionBIP32({ masterNode, network = bitcoinjs_lib_1.networks.bitcoin, keyPath, account, change, index, isPublic = true }) {
-        const originPath = `/${purpose}'/${network === bitcoinjs_lib_1.networks.bitcoin ? 0 : 1}'/${account}'`;
+        const originPath = `/${purpose}'/${(0, networkUtils_1.coinTypeFromNetwork)(network)}'/${account}'`;
         if (keyPath !== undefined)
             assertStandardKeyPath(keyPath);
         const keyExpression = (0, keyExpressions_1.keyExpressionBIP32)({
@@ -49,24 +50,26 @@ exports.wpkhBIP32 = standardExpressionsBIP32Maker(84, 'wpkh(KEYEXPRESSION)');
 /** @function */
 exports.trBIP32 = standardExpressionsBIP32Maker(86, 'tr(KEYEXPRESSION)');
 function standardExpressionsLedgerMaker(purpose, scriptTemplate) {
-    /** @overload */
-    async function standardScriptExpressionLedger({ ledgerClient, ledgerState, ledgerManager, network, account, keyPath, change, index }) {
-        if (ledgerManager && (ledgerClient || ledgerState))
-            throw new Error(`ledgerClient and ledgerState have been deprecated`);
-        if (ledgerManager && network)
-            throw new Error(`ledgerManager already includes the network object`);
-        if (!ledgerManager && !network)
-            network = bitcoinjs_lib_1.networks.bitcoin;
-        if (ledgerManager)
-            ({ ledgerClient, ledgerState, network } = ledgerManager);
-        if (!ledgerClient || !ledgerState)
-            throw new Error(`Could not retrieve ledgerClient or ledgerState`);
-        const originPath = `/${purpose}'/${network === bitcoinjs_lib_1.networks.bitcoin ? 0 : 1}'/${account}'`;
+    /**
+     * Computes the standard descriptor based on given parameters.
+     *
+     * You can define the output location either by:
+     * - Providing the full `keyPath` (e.g., "/0/2").
+     * OR
+     * - Specifying the `change` and `index` values separately (e.g., `{change:0, index:2}`).
+     *
+     * For ranged indexing, the `index` can be set as a wildcard '*'. For example:
+     * - `keyPath="/0/*"`
+     * OR
+     * - `{change:0, index:'*'}`.
+     */
+    async function standardScriptExpressionLedger({ ledgerManager, account, keyPath, change, index }) {
+        const { network } = ledgerManager;
+        const originPath = `/${purpose}'/${(0, networkUtils_1.coinTypeFromNetwork)(network)}'/${account}'`;
         if (keyPath !== undefined)
             assertStandardKeyPath(keyPath);
         const keyExpression = await (0, keyExpressions_1.keyExpressionLedger)({
-            ledgerClient,
-            ledgerState,
+            ledgerManager,
             originPath,
             keyPath,
             change,

package/dist/signers.d.ts

@@ -1,8 +1,7 @@
 import type { Psbt } from 'bitcoinjs-lib';
 import type { ECPairInterface } from 'ecpair';
 import type { BIP32Interface } from 'bip32';
-import type { DescriptorInstance } from './descriptors';
-import { LedgerState, LedgerManager } from './ledger';
+import { LedgerManager } from './ledger';
 /**
  * Signs a specific input of a PSBT with an ECPair.
  *
@@ -69,16 +68,6 @@ export declare function signInputLedger({ psbt, index, ledgerManager }: {
     index: number;
     ledgerManager: LedgerManager;
 }): Promise<void>;
-/**
- * @hidden
- */
-export declare function signInputLedger({ psbt, index, descriptor, ledgerClient, ledgerState }: {
-    psbt: Psbt;
-    index: number;
-    descriptor: DescriptorInstance;
-    ledgerClient: unknown;
-    ledgerState: LedgerState;
-}): Promise<void>;
 /**
  * Signs the inputs of the `psbt` where the keys are controlled by a Ledger
  * device.
@@ -93,12 +82,3 @@ export declare function signLedger({ psbt, ledgerManager }: {
     psbt: Psbt;
     ledgerManager: LedgerManager;
 }): Promise<void>;
-/**
- * @hidden
- */
-export declare function signLedger({ psbt, descriptors, ledgerClient, ledgerState }: {
-    psbt: Psbt;
-    descriptors: DescriptorInstance[];
-    ledgerClient: unknown;
-    ledgerState: LedgerState;
-}): Promise<void>;

package/dist/signers.js

@@ -8,8 +8,7 @@ exports.signInputBIP32 = signInputBIP32;
 exports.signBIP32 = signBIP32;
 exports.signInputLedger = signInputLedger;
 exports.signLedger = signLedger;
-const bip371_1 = require("bitcoinjs-lib/src/psbt/bip371");
-const bip341_1 = require("bitcoinjs-lib/src/payments/bip341");
+const bitcoinjs_lib_internals_1 = require("./bitcoinjs-lib-internals");
 const ledger_1 = require("./ledger");
 const applyPR2137_1 = require("./applyPR2137");
 function range(n) {
@@ -39,12 +38,12 @@ function signInputECPair({ psbt, index, ecpair }) {
     const input = psbt.data.inputs[index];
     if (!input)
         throw new Error('Invalid index');
-    if ((0, bip371_1.isTaprootInput)(input)) {
+    if ((0, bitcoinjs_lib_internals_1.isTaprootInput)(input)) {
         // If script-path (tapLeafScript present) -> DO NOT TWEAK
         if (input.tapLeafScript && input.tapLeafScript.length > 0)
             psbt.signInput(index, ecpair);
         else {
-            const hash = (0, bip341_1.tapTweakHash)(Buffer.from(ecpair.publicKey.slice(1, 33)), undefined);
+            const hash = (0, bitcoinjs_lib_internals_1.tapTweakHash)(ecpair.publicKey.slice(1, 33), undefined);
             const tweakedEcpair = ecpair.tweak(hash);
             psbt.signInput(index, tweakedEcpair);
         }
@@ -101,136 +100,91 @@ function signBIP32({ psbt, masterNode }) {
 }
 const ledgerSignaturesForInputIndex = (index, ledgerSignatures) => ledgerSignatures
     .filter(([i]) => i === index)
-    .map(([_i, partialSignature]) => ({
-    pubkey: partialSignature.pubkey,
-    signature: partialSignature.signature
-}));
-/**
- * To be removed in v3.0 and replaced by a version that does not accept
- * descriptor
- * @overload
- */
-async function signInputLedger({ psbt, index, descriptor, ledgerClient, ledgerState, ledgerManager }) {
-    if (!descriptor && !ledgerManager)
-        throw new Error(`ledgerManager not provided`);
-    if (descriptor && ledgerManager)
-        throw new Error(`Invalid usage: don't pass descriptor`);
-    if (ledgerManager && (ledgerClient || ledgerState))
-        throw new Error(`Invalid usage: either ledgerManager or ledgerClient + ledgerState`);
-    const output = descriptor;
-    if (ledgerManager)
-        ({ ledgerClient, ledgerState } = ledgerManager);
-    if (!ledgerClient)
-        throw new Error(`ledgerManager not provided`);
-    if (!ledgerState)
-        throw new Error(`ledgerManager not provided`);
-    const { PsbtV2, DefaultWalletPolicy, WalletPolicy, AppClient } = (await (0, ledger_1.importAndValidateLedgerBitcoin)(ledgerClient));
-    if (!(ledgerClient instanceof AppClient))
-        throw new Error(`Error: pass a valid ledgerClient`);
-    let ledgerSignatures;
-    if (ledgerManager) {
-        if (psbt.data.inputs[index]?.tapInternalKey)
-            throw new Error('Taproot inputs not yet supported for the Ledger device');
-        const policy = await (0, ledger_1.ledgerPolicyFromPsbtInput)({
-            psbt,
-            index,
-            ledgerManager
-        });
-        if (!policy)
-            throw new Error(`Error: the ledger cannot sign this pstb input`);
-        if (policy.policyName && policy.policyHmac && policy.policyId) {
-            //non-standard policy
-            const walletPolicy = new WalletPolicy(policy.policyName, policy.ledgerTemplate, policy.keyRoots);
-            ledgerSignatures = await ledgerClient.signPsbt(new PsbtV2().fromBitcoinJS(psbt), walletPolicy, policy.policyHmac);
+    .map(([_i, partialSignature]) => partialSignature);
+function addLedgerSignaturesToInput({ psbt, index, ledgerSignatures }) {
+    const input = psbt.data.inputs[index];
+    if (!input)
+        throw new Error(`Error: input ${index} not available`);
+    const signatures = ledgerSignaturesForInputIndex(index, ledgerSignatures);
+    if (signatures.length === 0)
+        throw new Error(`Error: no ledger signatures found for input ${index}`);
+    if ((0, bitcoinjs_lib_internals_1.isTaprootInput)(input)) {
+        // Ledger returns per-input signatures as [pubkey, signature, tapleafHash?].
+        // For taproot we must map them to PSBT taproot fields (not partialSig):
+        // - signatures with tapleafHash -> tapScriptSig[] (script-path)
+        // - signature without tapleafHash -> tapKeySig (key-path)
+        // A taproot input may contain script-path signatures, key-path signature,
+        // or both in edge cases; each must be written to its corresponding field.
+        const tapScriptSig = signatures
+            .filter((sig) => sig.tapleafHash)
+            .map((sig) => ({
+            pubkey: sig.pubkey,
+            signature: sig.signature,
+            leafHash: sig.tapleafHash
+        }));
+        const tapKeySigs = signatures.filter((sig) => !sig.tapleafHash);
+        if (tapScriptSig.length > 0) {
+            psbt.updateInput(index, { tapScriptSig });
         }
-        else {
-            //standard policy
-            ledgerSignatures = await ledgerClient.signPsbt(new PsbtV2().fromBitcoinJS(psbt), new DefaultWalletPolicy(policy.ledgerTemplate, policy.keyRoots[0]), null);
+        if (tapKeySigs.length > 1)
+            throw new Error(`Error: expected at most one tapKeySig for input ${index}`);
+        const tapKeySig = tapKeySigs[0]?.signature;
+        if (tapKeySig) {
+            psbt.updateInput(index, { tapKeySig });
         }
+        if (tapScriptSig.length === 0 && !tapKeySig)
+            throw new Error(`Error: no valid taproot ledger signatures found for input ${index}`);
     }
     else {
-        if (!output)
-            throw new Error(`outputs not provided`);
-        const result = await (0, ledger_1.ledgerPolicyFromOutput)({
-            output,
-            ledgerClient,
-            ledgerState
-        });
-        if (!result)
-            throw new Error(`Error: output does not have a ledger input`);
-        const { ledgerTemplate, keyRoots } = result;
-        const standardPolicy = await (0, ledger_1.ledgerPolicyFromStandard)({
-            output,
-            ledgerClient,
-            ledgerState
-        });
-        if (standardPolicy) {
-            ledgerSignatures = await ledgerClient.signPsbt(new PsbtV2().fromBitcoinJS(psbt), new DefaultWalletPolicy(ledgerTemplate, keyRoots[0]), null);
-        }
-        else {
-            const policy = await (0, ledger_1.ledgerPolicyFromState)({
-                output,
-                ledgerClient,
-                ledgerState
-            });
-            if (!policy || !policy.policyName || !policy.policyHmac)
-                throw new Error(`Error: the descriptor's policy is not registered`);
-            const walletPolicy = new WalletPolicy(policy.policyName, ledgerTemplate, keyRoots);
-            ledgerSignatures = await ledgerClient.signPsbt(new PsbtV2().fromBitcoinJS(psbt), walletPolicy, policy.policyHmac);
-        }
+        const partialSig = signatures.map((sig) => ({
+            pubkey: sig.pubkey,
+            signature: sig.signature
+        }));
+        psbt.updateInput(index, { partialSig });
     }
-    //Add the signatures to the Psbt object using PartialSig format:
-    psbt.updateInput(index, {
-        partialSig: ledgerSignaturesForInputIndex(index, ledgerSignatures)
+}
+async function signInputLedger({ psbt, index, ledgerManager }) {
+    const { ledgerClient } = ledgerManager;
+    const { DefaultWalletPolicy, WalletPolicy, AppClient } = (await (0, ledger_1.importAndValidateLedgerBitcoin)(ledgerClient));
+    if (!(ledgerClient instanceof AppClient))
+        throw new Error(`Error: pass a valid ledgerClient`);
+    const policy = await (0, ledger_1.ledgerPolicyFromPsbtInput)({
+        psbt,
+        index,
+        ledgerManager
     });
+    if (!policy)
+        throw new Error(`Error: the ledger cannot sign this pstb input`);
+    let ledgerSignatures;
+    if (policy.policyName && policy.policyHmac && policy.policyId) {
+        //non-standard policy
+        const walletPolicy = new WalletPolicy(policy.policyName, policy.ledgerTemplate, policy.keyRoots);
+        const walletHmac = policy.policyHmac;
+        ledgerSignatures = await ledgerClient.signPsbt(psbt.toBase64(), walletPolicy, walletHmac);
+    }
+    else {
+        //standard policy
+        ledgerSignatures = await ledgerClient.signPsbt(psbt.toBase64(), new DefaultWalletPolicy(policy.ledgerTemplate, policy.keyRoots[0]), null);
+    }
+    addLedgerSignaturesToInput({ psbt, index, ledgerSignatures });
 }
-/**
- * To be removed in v3.0 and replaced by a version that does not accept
- * descriptors
- * @overload
- */
-async function signLedger({ psbt, descriptors, ledgerClient, ledgerState, ledgerManager }) {
-    if (!descriptors && !ledgerManager)
-        throw new Error(`ledgerManager not provided`);
-    if (descriptors && ledgerManager)
-        throw new Error(`Invalid usage: don't pass descriptors`);
-    if (ledgerManager && (ledgerClient || ledgerState))
-        throw new Error(`Invalid usage: either ledgerManager or ledgerClient + ledgerState`);
-    const outputs = descriptors;
-    if (ledgerManager)
-        ({ ledgerClient, ledgerState } = ledgerManager);
-    if (!ledgerClient)
-        throw new Error(`ledgerManager not provided`);
-    if (!ledgerState)
-        throw new Error(`ledgerManager not provided`);
-    const { PsbtV2, DefaultWalletPolicy, WalletPolicy, AppClient } = (await (0, ledger_1.importAndValidateLedgerBitcoin)(ledgerClient));
+async function signLedger({ psbt, ledgerManager }) {
+    const { ledgerClient } = ledgerManager;
+    const { DefaultWalletPolicy, WalletPolicy, AppClient } = (await (0, ledger_1.importAndValidateLedgerBitcoin)(ledgerClient));
     if (!(ledgerClient instanceof AppClient))
         throw new Error(`Error: pass a valid ledgerClient`);
     const ledgerPolicies = [];
-    if (ledgerManager)
-        for (let index = 0; index < psbt.data.inputs.length; index++) {
-            if (psbt.data.inputs[index]?.tapInternalKey)
-                throw new Error('Taproot inputs not yet supported for the Ledger device');
-            const policy = await (0, ledger_1.ledgerPolicyFromPsbtInput)({
-                psbt,
-                index,
-                ledgerManager
-            });
-            if (policy)
-                ledgerPolicies.push(policy);
-        }
-    else {
-        if (!outputs)
-            throw new Error(`outputs not provided`);
-        for (const output of outputs) {
-            const policy = (await (0, ledger_1.ledgerPolicyFromState)({ output, ledgerClient, ledgerState })) ||
-                (await (0, ledger_1.ledgerPolicyFromStandard)({ output, ledgerClient, ledgerState }));
-            if (policy)
-                ledgerPolicies.push(policy);
-        }
-        if (ledgerPolicies.length === 0)
-            throw new Error(`Error: there are no inputs which could be signed`);
+    for (let index = 0; index < psbt.data.inputs.length; index++) {
+        const policy = await (0, ledger_1.ledgerPolicyFromPsbtInput)({
+            psbt,
+            index,
+            ledgerManager
+        });
+        if (policy)
+            ledgerPolicies.push(policy);
     }
+    if (ledgerPolicies.length === 0)
+        throw new Error(`Error: there are no inputs which could be signed`);
     //cluster unique LedgerPolicies
     const uniquePolicies = [];
     for (const policy of ledgerPolicies) {
@@ -244,16 +198,18 @@ async function signLedger({ psbt, descriptors, ledgerClient, ledgerState, ledger
             uniquePolicy.policyId) {
             //non-standard policy
             const walletPolicy = new WalletPolicy(uniquePolicy.policyName, uniquePolicy.ledgerTemplate, uniquePolicy.keyRoots);
-            ledgerSignatures = await ledgerClient.signPsbt(new PsbtV2().fromBitcoinJS(psbt), walletPolicy, uniquePolicy.policyHmac);
+            const walletHmac = uniquePolicy.policyHmac;
+            ledgerSignatures = await ledgerClient.signPsbt(psbt.toBase64(), walletPolicy, walletHmac);
         }
         else {
             //standard policy
-            ledgerSignatures = await ledgerClient.signPsbt(new PsbtV2().fromBitcoinJS(psbt), new DefaultWalletPolicy(uniquePolicy.ledgerTemplate, uniquePolicy.keyRoots[0]), null);
+            ledgerSignatures = await ledgerClient.signPsbt(psbt.toBase64(), new DefaultWalletPolicy(uniquePolicy.ledgerTemplate, uniquePolicy.keyRoots[0]), null);
         }
-        for (const [index, ,] of ledgerSignatures) {
-            psbt.updateInput(index, {
-                partialSig: ledgerSignaturesForInputIndex(index, ledgerSignatures)
-            });
+        const signedIndexes = [
+            ...new Set(ledgerSignatures.map(([index]) => index))
+        ];
+        for (const index of signedIndexes) {
+            addLedgerSignaturesToInput({ psbt, index, ledgerSignatures });
         }
     }
 }

package/dist/stackResourceLimits.d.ts

@@ -0,0 +1,17 @@
+export declare const MAX_STACK_SIZE = 1000;
+export declare const MAX_SCRIPT_ELEMENT_SIZE = 520;
+export declare function assertConsensusStackResourceLimits({ stackItems, stackLabel, stackItemLabel }: {
+    stackItems: Uint8Array[];
+    stackLabel?: string;
+    stackItemLabel?: string;
+}): void;
+export declare function assertStandardPolicyStackItemCountLimit({ stackItems, maxStackItems, stackLabel }: {
+    stackItems: Uint8Array[];
+    maxStackItems: number;
+    stackLabel: string;
+}): void;
+export declare function assertStandardPolicyStackItemSizeLimit({ stackItems, maxStackItemSize, stackItemLabel }: {
+    stackItems: Uint8Array[];
+    maxStackItemSize: number;
+    stackItemLabel: string;
+}): void;

package/dist/stackResourceLimits.js

@@ -0,0 +1,35 @@
+"use strict";
+// Copyright (c) 2026 Jose-Luis Landabaso
+// Distributed under the MIT software license
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SCRIPT_ELEMENT_SIZE = exports.MAX_STACK_SIZE = void 0;
+exports.assertConsensusStackResourceLimits = assertConsensusStackResourceLimits;
+exports.assertStandardPolicyStackItemCountLimit = assertStandardPolicyStackItemCountLimit;
+exports.assertStandardPolicyStackItemSizeLimit = assertStandardPolicyStackItemSizeLimit;
+// See Sipa's Miniscript "Resource limitations":
+// https://bitcoin.sipa.be/miniscript/
+// and Bitcoin Core policy/consensus constants.
+// Consensus: max number of elements in initial stack (and stack+altstack after
+// each opcode execution).
+exports.MAX_STACK_SIZE = 1000;
+// Consensus: max size for any pushed stack element. This is an element limit,
+// not a full script-size limit.
+exports.MAX_SCRIPT_ELEMENT_SIZE = 520;
+function assertConsensusStackResourceLimits({ stackItems, stackLabel = 'stack', stackItemLabel = 'stack item' }) {
+    if (stackItems.length > exports.MAX_STACK_SIZE)
+        throw new Error(`Error: ${stackLabel} has too many items, ${stackItems.length} is larger than ${exports.MAX_STACK_SIZE}`);
+    for (const stackItem of stackItems) {
+        if (stackItem.length > exports.MAX_SCRIPT_ELEMENT_SIZE)
+            throw new Error(`Error: ${stackItemLabel} is too large, ${stackItem.length} bytes is larger than ${exports.MAX_SCRIPT_ELEMENT_SIZE} bytes`);
+    }
+}
+function assertStandardPolicyStackItemCountLimit({ stackItems, maxStackItems, stackLabel }) {
+    if (stackItems.length > maxStackItems)
+        throw new Error(`Error: ${stackLabel} has too many items, ${stackItems.length} is larger than ${maxStackItems}`);
+}
+function assertStandardPolicyStackItemSizeLimit({ stackItems, maxStackItemSize, stackItemLabel }) {
+    for (const stackItem of stackItems) {
+        if (stackItem.length > maxStackItemSize)
+            throw new Error(`Error: ${stackItemLabel} exceeds standard policy, ${stackItem.length} bytes is larger than ${maxStackItemSize} bytes`);
+    }
+}

package/dist/tapMiniscript.d.ts

@@ -0,0 +1,193 @@
+import { Network } from 'bitcoinjs-lib';
+import type { BIP32API } from 'bip32';
+import type { ECPairAPI } from 'ecpair';
+import type { PartialSig, TapBip32Derivation } from 'bip174';
+import type { Taptree } from 'bitcoinjs-lib/src/cjs/types';
+import type { KeyInfo, Preimage, TimeConstraints } from './types';
+import type { TapLeafInfo, TapTreeInfoNode, TapTreeNode } from './tapTree';
+export type TaprootLeafSatisfaction = {
+    leaf: TapLeafInfo;
+    depth: number;
+    tapLeafHash: Uint8Array;
+    scriptSatisfaction: Uint8Array;
+    stackItems: Uint8Array[];
+    nLockTime: number | undefined;
+    nSequence: number | undefined;
+    totalWitnessSize: number;
+};
+export type TaprootPsbtLeafMetadata = {
+    leaf: TapLeafInfo;
+    depth: number;
+    tapLeafHash: Uint8Array;
+    controlBlock: Uint8Array;
+};
+/**
+ * Compiles a taproot miniscript tree into per-leaf metadata.
+ * Each leaf contains its expanded miniscript, expansion map, compiled tapscript
+ * and leaf version. This keeps the taproot script-path data ready for
+ * satisfactions and witness building.
+ */
+export declare function buildTapTreeInfo({ tapTree, network, BIP32, ECPair }: {
+    tapTree: TapTreeNode;
+    network?: Network;
+    BIP32: BIP32API;
+    ECPair: ECPairAPI;
+}): TapTreeInfoNode;
+export declare function tapTreeInfoToScriptTree(tapTreeInfo: TapTreeInfoNode): Taptree;
+/**
+ * Builds taproot PSBT leaf metadata for every leaf in a `tapTreeInfo`.
+ *
+ * For each leaf, this function computes:
+ * - `tapLeafHash`: BIP341 leaf hash of tapscript + leaf version
+ * - `depth`: leaf depth in the tree (root children have depth 1)
+ * - `controlBlock`: script-path proof used in PSBT `tapLeafScript`
+ *
+ * The control block layout is:
+ *
+ * ```text
+ * [1-byte (leafVersion | parity)] [32-byte internal key]
+ * [32-byte sibling hash #1] ... [32-byte sibling hash #N]
+ * ```
+ *
+ * where:
+ * - `parity` is derived from tweaking the internal key with the tree root
+ * - sibling hashes are the merkle path from that leaf to the root
+ *
+ * Example tree:
+ *
+ * ```text
+ *         root
+ *        /    \
+ *      L1      L2
+ *             /  \
+ *           L3    L4
+ * ```
+ *
+ * Depths:
+ * - L1 depth = 1
+ * - L3 depth = 2
+ * - L4 depth = 2
+ *
+ * Conceptual output:
+ *
+ * ```text
+ * [
+ *   L1 -> { depth: 1, tapLeafHash: h1, controlBlock: [v|p, ik, hash(L2)] }
+ *   L3 -> { depth: 2, tapLeafHash: h3, controlBlock: [v|p, ik, hash(L4), hash(L1)] }
+ *   L4 -> { depth: 2, tapLeafHash: h4, controlBlock: [v|p, ik, hash(L3), hash(L1)] }
+ * ]
+ * ```
+ *
+ * Legend:
+ * - `ik`: the 32-byte internal key placed in the control block.
+ * - `hash(X)`: the merkle sibling hash at each level when proving leaf `X`.
+ *
+ * Note: in this diagram, `L2` is a branch node (right subtree), not a leaf,
+ * so `hash(L2) = TapBranch(hash(L3), hash(L4))`.
+ *
+ * Notes:
+ * - Leaves are returned in deterministic left-first order.
+ * - One metadata entry is returned per leaf.
+ * - `controlBlock.length === 33 + 32 * depth`.
+ * - Throws if internal key is invalid or merkle path cannot be found.
+ *
+ * Typical usage:
+ * - Convert this metadata into PSBT `tapLeafScript[]` entries
+ *   for all leaves.
+ */
+export declare function buildTaprootLeafPsbtMetadata({ tapTreeInfo, internalPubkey }: {
+    tapTreeInfo: TapTreeInfoNode;
+    internalPubkey: Uint8Array;
+}): TaprootPsbtLeafMetadata[];
+/**
+ * Builds PSBT `tapBip32Derivation` entries for taproot script-path spends.
+ *
+ * Leaf keys include the list of tapleaf hashes where they appear.
+ * If `internalKeyInfo` has derivation data, it is included with empty
+ * `leafHashes`.
+ *
+ * Example tree:
+ *
+ * ```text
+ *         root
+ *        /    \
+ *      L1      L2
+ *
+ * L1 uses key A
+ * L2 uses key A and key B
+ *
+ * h1 = tapleafHash(L1)
+ * h2 = tapleafHash(L2)
+ * ```
+ *
+ * Then output is conceptually:
+ *
+ * ```text
+ * [
+ *   key A -> leafHashes [h1, h2]
+ *   key B -> leafHashes [h2]
+ *   internal key -> leafHashes []
+ * ]
+ * ```
+ *
+ * Notes:
+ * - Keys missing `masterFingerprint` or `path` are skipped.
+ * - Duplicate pubkeys are merged.
+ * - If the same pubkey appears with conflicting derivation metadata,
+ *   this function throws.
+ * - Output and `leafHashes` are sorted deterministically.
+ */
+export declare function buildTaprootBip32Derivations({ tapTreeInfo, internalKeyInfo }: {
+    tapTreeInfo: TapTreeInfoNode;
+    internalKeyInfo?: KeyInfo;
+}): TapBip32Derivation[];
+export declare function normalizeTaprootPubkey(pubkey: Uint8Array): Uint8Array;
+/**
+ * Computes satisfactions for taproot script-path leaves.
+ *
+ * If `tapLeaf` is undefined, all satisfiable leaves are returned. If `tapLeaf`
+ * is provided, only that leaf is considered.
+ *
+ * Callers are expected to pass real signatures, or fake signatures generated
+ * during planning. See satisfyMiniscript() for how timeConstraints keep the
+ * chosen leaf consistent between planning and signing.
+ */
+export declare function collectTaprootLeafSatisfactions({ tapTreeInfo, preimages, signatures, timeConstraints, tapLeaf }: {
+    tapTreeInfo: TapTreeInfoNode;
+    preimages: Preimage[];
+    signatures: PartialSig[];
+    timeConstraints?: TimeConstraints;
+    tapLeaf?: Uint8Array | string;
+}): TaprootLeafSatisfaction[];
+/**
+ * Selects the taproot leaf satisfaction with the smallest total witness size.
+ * Assumes the input list is in left-first tree order for deterministic ties.
+ */
+export declare function selectBestTaprootLeafSatisfaction(satisfactions: TaprootLeafSatisfaction[]): TaprootLeafSatisfaction;
+/**
+ * Collects a unique set of taproot leaf pubkeys (x-only) across the tree.
+ * This is useful for building fake signatures when no signer subset is given.
+ */
+export declare function collectTapTreePubkeys(tapTreeInfo: TapTreeInfoNode): Uint8Array[];
+/**
+ * Returns the best satisfaction for a taproot tree, by witness size.
+ *
+ * If `tapLeaf` is provided, only that leaf is considered. If `tapLeaf` is a
+ * bytes, it is treated as a tapLeafHash and must match exactly one leaf. If
+ * `tapLeaf` is a string, it is treated as a miniscript leaf and must match
+ * exactly one leaf (whitespace-insensitive).
+ *
+ * This function is typically called twice:
+ * 1) Planning pass: call it with fake signatures (built by the caller) to
+ *    choose the best leaf without requiring user signatures.
+ * 2) Signing pass: call it again with real signatures and the timeConstraints
+ *    returned from the first pass (see satisfyMiniscript() for why this keeps
+ *    the chosen leaf consistent between planning and signing).
+ */
+export declare function satisfyTapTree({ tapTreeInfo, signatures, preimages, tapLeaf, timeConstraints }: {
+    tapTreeInfo: TapTreeInfoNode;
+    signatures: PartialSig[];
+    preimages: Preimage[];
+    tapLeaf?: Uint8Array | string;
+    timeConstraints?: TimeConstraints;
+}): TaprootLeafSatisfaction;