@bitcoinerlab/descriptors 2.3.6 → 3.0.0

package/dist/tapMiniscript.js

@@ -0,0 +1,428 @@
+"use strict";
+// Distributed under the MIT software license
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTapTreeInfo = buildTapTreeInfo;
+exports.tapTreeInfoToScriptTree = tapTreeInfoToScriptTree;
+exports.buildTaprootLeafPsbtMetadata = buildTaprootLeafPsbtMetadata;
+exports.buildTaprootBip32Derivations = buildTaprootBip32Derivations;
+exports.normalizeTaprootPubkey = normalizeTaprootPubkey;
+exports.collectTaprootLeafSatisfactions = collectTaprootLeafSatisfactions;
+exports.selectBestTaprootLeafSatisfaction = selectBestTaprootLeafSatisfaction;
+exports.collectTapTreePubkeys = collectTapTreePubkeys;
+exports.satisfyTapTree = satisfyTapTree;
+const bitcoinjs_lib_1 = require("bitcoinjs-lib");
+const bitcoinjs_lib_internals_1 = require("./bitcoinjs-lib-internals");
+const varuint_bitcoin_1 = require("varuint-bitcoin");
+const uint8array_tools_1 = require("uint8array-tools");
+const miniscript_1 = require("./miniscript");
+const tapTree_1 = require("./tapTree");
+const resourceLimits_1 = require("./resourceLimits");
+const TAPROOT_LEAF_VERSION_TAPSCRIPT = 0xc0;
+function expandTaprootMiniscript({ miniscript, network = bitcoinjs_lib_1.networks.bitcoin, BIP32, ECPair }) {
+    return (0, miniscript_1.expandMiniscript)({
+        miniscript,
+        isSegwit: true,
+        isTaproot: true,
+        network,
+        BIP32,
+        ECPair
+    });
+}
+/**
+ * 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.
+ */
+function buildTapTreeInfo({ tapTree, network = bitcoinjs_lib_1.networks.bitcoin, BIP32, ECPair }) {
+    // Defensive: parseTapTreeExpression() already enforces this for descriptor
+    // strings, but buildTapTreeInfo is exported and can be called directly.
+    (0, tapTree_1.assertTapTreeDepth)(tapTree);
+    if ('miniscript' in tapTree) {
+        const miniscript = tapTree.miniscript;
+        const { expandedMiniscript, expansionMap } = expandTaprootMiniscript({
+            miniscript,
+            network,
+            BIP32,
+            ECPair
+        });
+        const tapScript = (0, miniscript_1.miniscript2Script)({
+            expandedMiniscript,
+            expansionMap,
+            tapscript: true
+        });
+        return {
+            miniscript,
+            expandedMiniscript,
+            expansionMap,
+            tapScript,
+            version: TAPROOT_LEAF_VERSION_TAPSCRIPT
+        };
+    }
+    return {
+        left: buildTapTreeInfo({ tapTree: tapTree.left, network, BIP32, ECPair }),
+        right: buildTapTreeInfo({ tapTree: tapTree.right, network, BIP32, ECPair })
+    };
+}
+function tapTreeInfoToScriptTree(tapTreeInfo) {
+    if ('miniscript' in tapTreeInfo) {
+        return {
+            output: tapTreeInfo.tapScript,
+            version: tapTreeInfo.version
+        };
+    }
+    return [
+        tapTreeInfoToScriptTree(tapTreeInfo.left),
+        tapTreeInfoToScriptTree(tapTreeInfo.right)
+    ];
+}
+/**
+ * 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.
+ */
+function buildTaprootLeafPsbtMetadata({ tapTreeInfo, internalPubkey }) {
+    const normalizedInternalPubkey = normalizeTaprootPubkey(internalPubkey);
+    const scriptTree = tapTreeInfoToScriptTree(tapTreeInfo);
+    const hashTree = (0, bitcoinjs_lib_internals_1.toHashTree)(scriptTree);
+    const tweaked = (0, bitcoinjs_lib_internals_1.tweakKey)(normalizedInternalPubkey, hashTree.hash);
+    if (!tweaked)
+        throw new Error(`Error: invalid taproot internal pubkey`);
+    return (0, tapTree_1.collectTapTreeLeaves)(tapTreeInfo).map(({ leaf, depth }) => {
+        if (depth > tapTree_1.MAX_TAPTREE_DEPTH)
+            throw new Error(`Error: taproot tree depth is too large, ${depth} is larger than ${tapTree_1.MAX_TAPTREE_DEPTH}`);
+        const tapLeafHash = (0, bitcoinjs_lib_internals_1.tapleafHash)({
+            output: leaf.tapScript,
+            version: leaf.version
+        });
+        const merklePath = (0, bitcoinjs_lib_internals_1.findScriptPath)(hashTree, tapLeafHash);
+        if (!merklePath)
+            throw new Error(`Error: could not build controlBlock for taproot leaf ${leaf.miniscript}`);
+        // controlBlock[0] packs:
+        // - leaf version (high bits), and
+        // - parity of the tweaked output key Q = P + t*G (low bit).
+        // `normalizedInternalPubkey` is x-only P, so parity is not encoded there.
+        // BIP341 requires carrying Q parity in controlBlock[0].
+        const controlBlock = (0, uint8array_tools_1.concat)([
+            Uint8Array.from([leaf.version | tweaked.parity]),
+            normalizedInternalPubkey,
+            ...merklePath
+        ]);
+        return { leaf, depth, tapLeafHash, controlBlock };
+    });
+}
+/**
+ * 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.
+ */
+function buildTaprootBip32Derivations({ tapTreeInfo, internalKeyInfo }) {
+    const entries = new Map();
+    const updateAndInsert = ({ pubkey, masterFingerprint, path, leafHash }) => {
+        const normalizedPubkey = normalizeTaprootPubkey(pubkey);
+        const pubkeyHex = (0, uint8array_tools_1.toHex)(normalizedPubkey);
+        const current = entries.get(pubkeyHex);
+        if (!current) {
+            const next = {
+                masterFingerprint,
+                pubkey: normalizedPubkey,
+                path,
+                leafHashes: new Map()
+            };
+            if (leafHash)
+                next.leafHashes.set((0, uint8array_tools_1.toHex)(leafHash), leafHash);
+            entries.set(pubkeyHex, next);
+            return;
+        }
+        if ((0, uint8array_tools_1.compare)(current.masterFingerprint, masterFingerprint) !== 0 ||
+            current.path !== path) {
+            throw new Error(`Error: inconsistent taproot key derivation metadata for pubkey ${pubkeyHex}`);
+        }
+        if (leafHash)
+            current.leafHashes.set((0, uint8array_tools_1.toHex)(leafHash), leafHash);
+    };
+    const leaves = (0, tapTree_1.collectTapTreeLeaves)(tapTreeInfo);
+    for (const { leaf } of leaves) {
+        const leafHash = (0, bitcoinjs_lib_internals_1.tapleafHash)({
+            output: leaf.tapScript,
+            version: leaf.version
+        });
+        for (const keyInfo of Object.values(leaf.expansionMap)) {
+            if (!keyInfo.pubkey || !keyInfo.masterFingerprint || !keyInfo.path)
+                continue;
+            updateAndInsert({
+                pubkey: keyInfo.pubkey,
+                masterFingerprint: keyInfo.masterFingerprint,
+                path: keyInfo.path,
+                leafHash
+            });
+        }
+    }
+    if (internalKeyInfo?.pubkey &&
+        internalKeyInfo.masterFingerprint &&
+        internalKeyInfo.path) {
+        updateAndInsert({
+            pubkey: internalKeyInfo.pubkey,
+            masterFingerprint: internalKeyInfo.masterFingerprint,
+            path: internalKeyInfo.path
+        });
+    }
+    return [...entries.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([, entry]) => ({
+        masterFingerprint: entry.masterFingerprint,
+        pubkey: entry.pubkey,
+        path: entry.path,
+        leafHashes: [...entry.leafHashes.entries()]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([, leafHash]) => leafHash)
+    }));
+}
+function varSliceSize(someScript) {
+    const length = someScript.length;
+    return (0, varuint_bitcoin_1.encodingLength)(length) + length;
+}
+function vectorSize(someVector) {
+    const length = someVector.length;
+    return ((0, varuint_bitcoin_1.encodingLength)(length) +
+        someVector.reduce((sum, witness) => sum + varSliceSize(witness), 0));
+}
+function witnessStackSize(witness) {
+    return vectorSize(witness);
+}
+function estimateTaprootWitnessSize({ stackItems, tapScript, depth }) {
+    if (depth > tapTree_1.MAX_TAPTREE_DEPTH)
+        throw new Error(`Error: taproot tree depth is too large, ${depth} is larger than ${tapTree_1.MAX_TAPTREE_DEPTH}`);
+    const controlBlock = new Uint8Array(33 + 32 * depth);
+    return witnessStackSize([...stackItems, tapScript, controlBlock]);
+}
+function normalizeTaprootPubkey(pubkey) {
+    if (pubkey.length === 32)
+        return pubkey;
+    if (pubkey.length === 33)
+        return pubkey.slice(1, 33);
+    throw new Error(`Error: invalid taproot pubkey length`);
+}
+/**
+ * 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.
+ */
+function collectTaprootLeafSatisfactions({ tapTreeInfo, preimages, signatures, timeConstraints, tapLeaf }) {
+    const candidates = (0, tapTree_1.selectTapLeafCandidates)({
+        tapTreeInfo,
+        ...(tapLeaf !== undefined ? { tapLeaf } : {})
+    });
+    const getLeafPubkeys = (leaf) => {
+        return Object.values(leaf.expansionMap).map(keyInfo => {
+            if (!keyInfo.pubkey)
+                throw new Error(`Error: taproot leaf key missing pubkey`);
+            return normalizeTaprootPubkey(keyInfo.pubkey);
+        });
+    };
+    const resolveLeafSignatures = (leaf) => {
+        const leafPubkeys = getLeafPubkeys(leaf);
+        const leafPubkeySet = new Set(leafPubkeys.map(pubkey => (0, uint8array_tools_1.toHex)(pubkey)));
+        return signatures
+            .map((sig) => ({
+            pubkey: normalizeTaprootPubkey(sig.pubkey),
+            signature: sig.signature
+        }))
+            .filter((sig) => leafPubkeySet.has((0, uint8array_tools_1.toHex)(sig.pubkey)));
+    };
+    const satisfactions = [];
+    for (const candidate of candidates) {
+        const { leaf } = candidate;
+        const leafSignatures = resolveLeafSignatures(leaf);
+        try {
+            const { scriptSatisfaction, nLockTime, nSequence } = (0, miniscript_1.satisfyMiniscript)({
+                expandedMiniscript: leaf.expandedMiniscript,
+                expansionMap: leaf.expansionMap,
+                signatures: leafSignatures,
+                preimages,
+                ...(timeConstraints !== undefined ? { timeConstraints } : {}),
+                tapscript: true
+            });
+            const satisfactionStackItems = bitcoinjs_lib_1.script.toStack(scriptSatisfaction);
+            (0, resourceLimits_1.assertTaprootScriptPathSatisfactionResourceLimits)({
+                stackItems: satisfactionStackItems
+            });
+            const totalWitnessSize = estimateTaprootWitnessSize({
+                stackItems: satisfactionStackItems,
+                tapScript: leaf.tapScript,
+                depth: candidate.depth
+            });
+            satisfactions.push({
+                leaf,
+                depth: candidate.depth,
+                tapLeafHash: candidate.tapLeafHash,
+                scriptSatisfaction,
+                stackItems: satisfactionStackItems,
+                nLockTime,
+                nSequence,
+                totalWitnessSize
+            });
+        }
+        catch (error) {
+            if (tapLeaf !== undefined)
+                throw error;
+        }
+    }
+    if (satisfactions.length === 0)
+        throw new Error(`Error: no satisfiable taproot leaves found`);
+    return satisfactions;
+}
+/**
+ * Selects the taproot leaf satisfaction with the smallest total witness size.
+ * Assumes the input list is in left-first tree order for deterministic ties.
+ */
+function selectBestTaprootLeafSatisfaction(satisfactions) {
+    return satisfactions.reduce((best, current) => {
+        if (!best)
+            return current;
+        if (current.totalWitnessSize < best.totalWitnessSize)
+            return current;
+        return best;
+    });
+}
+/**
+ * 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.
+ */
+function collectTapTreePubkeys(tapTreeInfo) {
+    const pubkeySet = new Set();
+    const pubkeys = [];
+    const leaves = (0, tapTree_1.collectTapTreeLeaves)(tapTreeInfo);
+    for (const entry of leaves) {
+        for (const keyInfo of Object.values(entry.leaf.expansionMap)) {
+            if (!keyInfo.pubkey)
+                throw new Error(`Error: taproot leaf key missing pubkey`);
+            const normalized = normalizeTaprootPubkey(keyInfo.pubkey);
+            const hex = (0, uint8array_tools_1.toHex)(normalized);
+            if (pubkeySet.has(hex))
+                continue;
+            pubkeySet.add(hex);
+            pubkeys.push(normalized);
+        }
+    }
+    return pubkeys;
+}
+/**
+ * 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).
+ */
+function satisfyTapTree({ tapTreeInfo, signatures, preimages, tapLeaf, timeConstraints }) {
+    const satisfactions = collectTaprootLeafSatisfactions({
+        tapTreeInfo,
+        preimages,
+        signatures,
+        ...(tapLeaf !== undefined ? { tapLeaf } : {}),
+        ...(timeConstraints !== undefined ? { timeConstraints } : {})
+    });
+    return selectBestTaprootLeafSatisfaction(satisfactions);
+}

package/dist/tapTree.d.ts

@@ -0,0 +1,76 @@
+import type { ExpansionMap } from './types';
+export type TreeNode<TLeaf> = TLeaf | {
+    left: TreeNode<TLeaf>;
+    right: TreeNode<TLeaf>;
+};
+export type TapLeaf = {
+    miniscript: string;
+};
+export type TapTreeNode = TreeNode<TapLeaf>;
+export type TapLeafInfo = {
+    miniscript: string;
+    expandedMiniscript: string;
+    expansionMap: ExpansionMap;
+    tapScript: Uint8Array;
+    version: number;
+};
+export type TapTreeInfoNode = TreeNode<TapLeafInfo>;
+export type TapLeafSelection = {
+    leaf: TapLeafInfo;
+    depth: number;
+    tapLeafHash: Uint8Array;
+};
+export declare const MAX_TAPTREE_DEPTH = 128;
+export declare function assertTapTreeDepth(tapTree: TapTreeNode): void;
+/**
+ * Collects taproot leaf metadata with depth from a tree.
+ * Traversal is left-first, following the order of `{left,right}` in the
+ * expression so tie-breaks are deterministic.
+ *
+ * Example tree:
+ * ```
+ * {pk(A),{pk(B),pk(C)}}
+ * ```
+ * Visual shape:
+ * ```
+ *         root
+ *        /    \
+ *     pk(A)  branch
+ *            /   \
+ *         pk(B) pk(C)
+ * ```
+ * Collected leaves with depth:
+ * ```
+ * [
+ *   { leaf: pk(A), depth: 1 },
+ *   { leaf: pk(B), depth: 2 },
+ *   { leaf: pk(C), depth: 2 }
+ * ]
+ * ```
+ */
+export declare function collectTapTreeLeaves(tapTreeInfo: TapTreeInfoNode): Array<{
+    leaf: TapLeafInfo;
+    depth: number;
+}>;
+/**
+ * Resolves taproot leaf candidates based on an optional selector.
+ *
+ * If `tapLeaf` is undefined, all leaves are returned for auto-selection.
+ * If `tapLeaf` is bytes, it is treated as a tapleaf hash and must match
+ * exactly one leaf.
+ * If `tapLeaf` is a string, it is treated as a miniscript leaf (raw, not
+ * expanded). Matching is whitespace-insensitive. If the miniscript appears
+ * more than once, this function throws an error.
+ *
+ * Example:
+ * ```
+ * const candidates = selectTapLeafCandidates({ tapTreeInfo, tapLeaf });
+ * // tapLeaf can be undefined, bytes (tapleaf hash) or a miniscript string:
+ * // f.ex.: 'pk(03bb...)'
+ * ```
+ */
+export declare function selectTapLeafCandidates({ tapTreeInfo, tapLeaf }: {
+    tapTreeInfo: TapTreeInfoNode;
+    tapLeaf?: Uint8Array | string;
+}): TapLeafSelection[];
+export declare function parseTapTreeExpression(expression: string): TapTreeNode;

package/dist/tapTree.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TAPTREE_DEPTH = void 0;
+exports.assertTapTreeDepth = assertTapTreeDepth;
+exports.collectTapTreeLeaves = collectTapTreeLeaves;
+exports.selectTapLeafCandidates = selectTapLeafCandidates;
+exports.parseTapTreeExpression = parseTapTreeExpression;
+// NOTE: This uses an internal bitcoinjs-lib module. Consider adding a local wrapper.
+const bitcoinjs_lib_internals_1 = require("./bitcoinjs-lib-internals");
+const uint8array_tools_1 = require("uint8array-tools");
+const parseUtils_1 = require("./parseUtils");
+// See BIP341 control block limits and Sipa's Miniscript "Resource limitations":
+// https://bitcoin.sipa.be/miniscript/
+// Taproot script path depth is encoded in the control block as 32-byte hashes,
+// with consensus max depth 128.
+exports.MAX_TAPTREE_DEPTH = 128;
+function tapTreeMaxDepth(tapTree, depth = 0) {
+    if ('miniscript' in tapTree)
+        return depth;
+    return Math.max(tapTreeMaxDepth(tapTree.left, depth + 1), tapTreeMaxDepth(tapTree.right, depth + 1));
+}
+function assertTapTreeDepth(tapTree) {
+    const maxDepth = tapTreeMaxDepth(tapTree);
+    if (maxDepth > exports.MAX_TAPTREE_DEPTH)
+        throw new Error(`Error: taproot tree depth is too large, ${maxDepth} is larger than ${exports.MAX_TAPTREE_DEPTH}`);
+}
+/**
+ * Collects taproot leaf metadata with depth from a tree.
+ * Traversal is left-first, following the order of `{left,right}` in the
+ * expression so tie-breaks are deterministic.
+ *
+ * Example tree:
+ * ```
+ * {pk(A),{pk(B),pk(C)}}
+ * ```
+ * Visual shape:
+ * ```
+ *         root
+ *        /    \
+ *     pk(A)  branch
+ *            /   \
+ *         pk(B) pk(C)
+ * ```
+ * Collected leaves with depth:
+ * ```
+ * [
+ *   { leaf: pk(A), depth: 1 },
+ *   { leaf: pk(B), depth: 2 },
+ *   { leaf: pk(C), depth: 2 }
+ * ]
+ * ```
+ */
+function collectTapTreeLeaves(tapTreeInfo) {
+    const leaves = [];
+    const walk = (node, depth) => {
+        if ('miniscript' in node) {
+            leaves.push({ leaf: node, depth });
+            return;
+        }
+        walk(node.left, depth + 1);
+        walk(node.right, depth + 1);
+    };
+    walk(tapTreeInfo, 0);
+    return leaves;
+}
+function computeTapLeafHash(leaf) {
+    return (0, bitcoinjs_lib_internals_1.tapleafHash)({ output: leaf.tapScript, version: leaf.version });
+}
+function normalizeMiniscriptForMatch(miniscript) {
+    return miniscript.replace(/\s+/g, '');
+}
+/**
+ * Resolves taproot leaf candidates based on an optional selector.
+ *
+ * If `tapLeaf` is undefined, all leaves are returned for auto-selection.
+ * If `tapLeaf` is bytes, it is treated as a tapleaf hash and must match
+ * exactly one leaf.
+ * If `tapLeaf` is a string, it is treated as a miniscript leaf (raw, not
+ * expanded). Matching is whitespace-insensitive. If the miniscript appears
+ * more than once, this function throws an error.
+ *
+ * Example:
+ * ```
+ * const candidates = selectTapLeafCandidates({ tapTreeInfo, tapLeaf });
+ * // tapLeaf can be undefined, bytes (tapleaf hash) or a miniscript string:
+ * // f.ex.: 'pk(03bb...)'
+ * ```
+ */
+function selectTapLeafCandidates({ tapTreeInfo, tapLeaf }) {
+    const leaves = collectTapTreeLeaves(tapTreeInfo).map(({ leaf, depth }) => ({
+        leaf,
+        depth,
+        tapLeafHash: computeTapLeafHash(leaf)
+    }));
+    if (tapLeaf === undefined)
+        return leaves;
+    if (tapLeaf instanceof Uint8Array) {
+        const match = leaves.find(entry => (0, uint8array_tools_1.compare)(entry.tapLeafHash, tapLeaf) === 0);
+        if (!match)
+            throw new Error(`Error: tapleaf hash not found in tapTreeInfo`);
+        return [match];
+    }
+    const normalizedSelector = normalizeMiniscriptForMatch(tapLeaf);
+    const matches = leaves.filter(entry => normalizeMiniscriptForMatch(entry.leaf.miniscript) === normalizedSelector);
+    if (matches.length === 0)
+        throw new Error(`Error: miniscript leaf not found in tapTreeInfo: ${tapLeaf}`);
+    if (matches.length > 1)
+        throw new Error(`Error: miniscript leaf is ambiguous in tapTreeInfo: ${tapLeaf}`);
+    return matches;
+}
+function tapTreeError(expression) {
+    return new Error(`Error: invalid taproot tree expression: ${expression}`);
+}
+/**
+ * Splits the inner tree expression of a branch into left/right parts.
+ * The input must be the contents inside `{}` (no outer braces).
+ * Example: `pk(@0),{pk(@1),pk(@2)}` => left: `pk(@0)`, right: `{pk(@1),pk(@2)}`.
+ */
+function splitTapTreeExpression(expression) {
+    const result = (0, parseUtils_1.splitTopLevelComma)({ expression, onError: tapTreeError });
+    if (!result)
+        throw tapTreeError(expression);
+    return result;
+}
+/**
+ * Parses a single taproot tree node expression.
+ * Examples:
+ * - `pk(@0)` => { miniscript: 'pk(@0)' }
+ * - `{pk(@0),pk(@1)}` => { left: { miniscript: 'pk(@0)' }, right: { miniscript: 'pk(@1)' } }
+ * - `{pk(@0),{pk(@1),pk(@2)}}` =>
+ *   {
+ *     left: { miniscript: 'pk(@0)' },
+ *     right: { left: { miniscript: 'pk(@1)' }, right: { miniscript: 'pk(@2)' } }
+ *   }
+ */
+function parseTapTreeNode(expression) {
+    const trimmedExpression = expression.trim();
+    if (!trimmedExpression)
+        throw tapTreeError(expression);
+    if (trimmedExpression.startsWith('{')) {
+        if (!trimmedExpression.endsWith('}'))
+            throw tapTreeError(expression);
+        const inner = trimmedExpression.slice(1, -1).trim();
+        if (!inner)
+            throw tapTreeError(expression);
+        const { left, right } = splitTapTreeExpression(inner);
+        return {
+            left: parseTapTreeNode(left),
+            right: parseTapTreeNode(right)
+        };
+    }
+    if (trimmedExpression.includes('{') || trimmedExpression.includes('}'))
+        throw tapTreeError(expression);
+    return { miniscript: trimmedExpression };
+}
+function parseTapTreeExpression(expression) {
+    const trimmed = expression.trim();
+    if (!trimmed)
+        throw tapTreeError(expression);
+    const tapTree = parseTapTreeNode(trimmed);
+    assertTapTreeDepth(tapTree);
+    return tapTree;
+}