@bitcoinerlab/descriptors 3.0.6 → 3.1.0

package/dist/tapMiniscript.js

@@ -1,510 +0,0 @@
-"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;
-const { p2tr } = bitcoinjs_lib_1.payments;
-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 control block cannot be derived.
- *
- * Typical usage:
- * - Convert this metadata into PSBT `tapLeafScript[]` entries
- *   for all leaves.
- */
-function buildTaprootLeafPsbtMetadata({ tapTreeInfo, internalPubkey }) {
-    const normalizedInternalPubkey = normalizeTaprootPubkey(internalPubkey);
-    const scriptTree = tapTreeInfoToScriptTree(tapTreeInfo);
-    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 payment = p2tr({
-            internalPubkey: normalizedInternalPubkey,
-            scriptTree,
-            redeem: {
-                output: leaf.tapScript,
-                redeemVersion: leaf.version
-            }
-        });
-        const controlBlock = payment.witness?.[1];
-        if (!controlBlock)
-            throw new Error(`Error: could not build controlBlock for taproot leaf ${leaf.expression}`);
-        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

@@ -1,86 +0,0 @@
-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;