@bitcoinerlab/descriptors 2.3.6 → 3.0.1

package/dist/tapMiniscript.js

@@ -0,0 +1,515 @@
+"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.compileSortedMultiAExpandedExpression = compileSortedMultiAExpandedExpression;
+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 expanded expression metadata, key expansion map,
+ * compiled tapscript and leaf version. This keeps the taproot script-path data
+ * ready for satisfactions and witness building.
+ *
+ * `leafExpansionOverride` allows descriptor-level script expressions to provide:
+ * - user-facing expanded expression metadata (for selector/template use), and
+ * - custom expansion map and tapscript bytes for compilation.
+ *
+ * Example: sortedmulti_a can expose `expandedExpression=sortedmulti_a(...)`
+ * while providing a tapscript already compiled.
+ */
+function buildTapTreeInfo({ tapTree, network = bitcoinjs_lib_1.networks.bitcoin, BIP32, ECPair, leafExpansionOverride }) {
+    // Defensive: parseTapTreeExpression() already enforces this for descriptor
+    // strings, but buildTapTreeInfo is exported and can be called directly.
+    (0, tapTree_1.assertTapTreeDepth)(tapTree);
+    if ('expression' in tapTree) {
+        // Tap-tree leaves store generic descriptor expressions. Most leaves are
+        // miniscript fragments, but descriptor-level script expressions (such as
+        // sortedmulti_a) can also appear and be normalized through
+        // `leafExpansionOverride`.
+        const expression = tapTree.expression;
+        const override = leafExpansionOverride(expression);
+        let expandedExpression;
+        let expandedMiniscript;
+        let expansionMap;
+        let tapScript;
+        if (override) {
+            // Descriptor-level expression overrides (e.g. sortedmulti_a) preserve a
+            // user-facing expanded expression while allowing custom compilation.
+            expandedExpression = override.expandedExpression;
+            expansionMap = override.expansionMap;
+            tapScript = override.tapScript;
+        }
+        else {
+            const expanded = expandTaprootMiniscript({
+                miniscript: expression,
+                network,
+                BIP32,
+                ECPair
+            });
+            expandedExpression = expanded.expandedMiniscript;
+            expandedMiniscript = expanded.expandedMiniscript;
+            expansionMap = expanded.expansionMap;
+            tapScript = (0, miniscript_1.miniscript2Script)({
+                expandedMiniscript: expanded.expandedMiniscript,
+                expansionMap,
+                tapscript: true
+            });
+        }
+        return {
+            expression,
+            expandedExpression,
+            ...(expandedMiniscript !== undefined ? { expandedMiniscript } : {}),
+            expansionMap,
+            tapScript,
+            version: TAPROOT_LEAF_VERSION_TAPSCRIPT
+        };
+    }
+    return {
+        left: buildTapTreeInfo({
+            tapTree: tapTree.left,
+            network,
+            BIP32,
+            ECPair,
+            leafExpansionOverride
+        }),
+        right: buildTapTreeInfo({
+            tapTree: tapTree.right,
+            network,
+            BIP32,
+            ECPair,
+            leafExpansionOverride
+        })
+    };
+}
+function tapTreeInfoToScriptTree(tapTreeInfo) {
+    if ('expression' 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.expression}`);
+        // 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`);
+}
+/**
+ * Compiles an expanded `sortedmulti_a(...)` leaf expression to its internal
+ * `multi_a(...)` form by sorting placeholders using the resolved pubkeys from
+ * `expansionMap`.
+ */
+function compileSortedMultiAExpandedExpression({ expandedExpression, expansionMap }) {
+    const trimmed = expandedExpression.trim();
+    const match = trimmed.match(/^sortedmulti_a\((.*)\)$/);
+    if (!match)
+        throw new Error(`Error: invalid sortedmulti_a() expression: ${trimmed}`);
+    const inner = match[1];
+    if (!inner)
+        throw new Error(`Error: invalid sortedmulti_a() expression: ${trimmed}`);
+    const parts = inner.split(',').map(part => part.trim());
+    if (parts.length < 2)
+        throw new Error(`Error: invalid sortedmulti_a() expression: ${trimmed}`);
+    const threshold = parts[0];
+    if (!threshold)
+        throw new Error(`Error: invalid sortedmulti_a() threshold: ${trimmed}`);
+    const placeholders = parts.slice(1);
+    const sortedPlaceholders = placeholders
+        .map(placeholder => {
+        const keyInfo = expansionMap[placeholder];
+        if (!keyInfo?.pubkey)
+            throw new Error(`Error: sortedmulti_a() placeholder ${placeholder} not found in expansionMap`);
+        return { placeholder, pubkey: keyInfo.pubkey };
+    })
+        .sort((a, b) => (0, uint8array_tools_1.compare)(a.pubkey, b.pubkey))
+        .map(({ placeholder }) => placeholder);
+    return `multi_a(${[threshold, ...sortedPlaceholders].join(',')})`;
+}
+/**
+ * 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 {
+            let satisfierMiniscript = leaf.expandedMiniscript;
+            // Most taproot leaves are Miniscript fragments, so `expandedMiniscript`
+            // is available (and currently matches `expandedExpression`).
+            // Descriptor-level leaf expressions (currently `sortedmulti_a`)
+            // expose only `expandedExpression`, so we derive an internal
+            // Miniscript-equivalent form here before calling `satisfyMiniscript(...)`
+            if (!satisfierMiniscript) {
+                if (!/^sortedmulti_a\(/.test(leaf.expandedExpression.trim()))
+                    throw new Error(`Error: taproot leaf does not provide a satisfier miniscript`);
+                satisfierMiniscript = compileSortedMultiAExpandedExpression({
+                    expandedExpression: leaf.expandedExpression,
+                    expansionMap: leaf.expansionMap
+                });
+            }
+            const { scriptSatisfaction, nLockTime, nSequence } = (0, miniscript_1.satisfyMiniscript)({
+                expandedMiniscript: satisfierMiniscript,
+                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 raw leaf expression 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,86 @@
+import type { ExpansionMap } from './types';
+export type TreeNode<TLeaf> = TLeaf | {
+    left: TreeNode<TLeaf>;
+    right: TreeNode<TLeaf>;
+};
+export type TapLeaf = {
+    /** Raw leaf expression as written in tr(KEY,TREE). */
+    expression: string;
+};
+export type TapTreeNode = TreeNode<TapLeaf>;
+export type TapLeafInfo = {
+    /** Raw leaf expression as written in tr(KEY,TREE). */
+    expression: string;
+    /** Expanded descriptor-level expression for this leaf. */
+    expandedExpression: string;
+    /**
+     * Expanded miniscript form when the leaf expression is a miniscript fragment.
+     *
+     * For descriptor-level script expressions (e.g. sortedmulti_a), this can be
+     * undefined even though `tapScript` is available.
+     */
+    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 raw taproot leaf expression
+ * (not expanded). Matching is whitespace-insensitive. If the expression appears
+ * more than once, this function throws an error.
+ *
+ * Example:
+ * ```
+ * const candidates = selectTapLeafCandidates({ tapTreeInfo, tapLeaf });
+ * // tapLeaf can be undefined, bytes (tapleaf hash) or a leaf expression:
+ * // f.ex.: 'pk(03bb...)'
+ * ```
+ */
+export declare function selectTapLeafCandidates({ tapTreeInfo, tapLeaf }: {
+    tapTreeInfo: TapTreeInfoNode;
+    tapLeaf?: Uint8Array | string;
+}): TapLeafSelection[];
+export declare function parseTapTreeExpression(expression: string): TapTreeNode;