@bitcoinerlab/descriptors 3.0.5 → 3.1.0

package/dist/signers.d.ts

@@ -1,84 +0,0 @@
-import type { Psbt } from 'bitcoinjs-lib';
-import type { ECPairInterface } from 'ecpair';
-import type { BIP32Interface } from 'bip32';
-import { LedgerManager } from './ledger';
-/**
- * Signs a specific input of a PSBT with an ECPair.
- *
- * Unlike bitcoinjs-lib's native `psbt.signInput()`, this function automatically detects
- * if the input is a Taproot input and internally tweaks the key if needed.
- *
- * This behavior matches how `signInputBIP32` works, where the BIP32 node is automatically
- * tweaked for Taproot inputs. In contrast, bitcoinjs-lib's native implementation requires
- * manual pre-tweaking of ECPair signers for Taproot inputs.
- *
- * @see https://github.com/bitcoinjs/bitcoinjs-lib/pull/2137#issuecomment-2713264848
- *
- * @param {Object} params - The parameters object
- * @param {Psbt} params.psbt - The PSBT to sign
- * @param {number} params.index - The input index to sign
- * @param {ECPairInterface} params.ecpair - The ECPair to sign with
- */
-export declare function signInputECPair({ psbt, index, ecpair }: {
-    psbt: Psbt;
-    index: number;
-    ecpair: ECPairInterface;
-}): void;
-/**
- * Signs all inputs of a PSBT with an ECPair.
- *
- * This function improves upon bitcoinjs-lib's native `psbt.signAllInputs()` by automatically
- * handling Taproot inputs. For each input, it detects if it's a Taproot input and internally
- * tweaks the key if needed.
- *
- * This creates consistency with the BIP32 signing methods (`signBIP32`/`signInputBIP32`),
- * which also automatically handle key tweaking for Taproot inputs. In contrast, bitcoinjs-lib's
- * native implementation requires users to manually pre-tweak ECPair signers for Taproot inputs.
- *
- * With this implementation, you can use a single ECPair to sign both Taproot and non-Taproot
- * inputs in the same PSBT, similar to how `signBIP32` allows using a common node for both types.
- *
- * @see https://github.com/bitcoinjs/bitcoinjs-lib/pull/2137#issuecomment-2713264848
- *
- * @param {Object} params - The parameters object
- * @param {Psbt} params.psbt - The PSBT to sign
- * @param {ECPairInterface} params.ecpair - The ECPair to sign with
- */
-export declare function signECPair({ psbt, ecpair }: {
-    psbt: Psbt;
-    ecpair: ECPairInterface;
-}): void;
-export declare function signInputBIP32({ psbt, index, node }: {
-    psbt: Psbt;
-    index: number;
-    node: BIP32Interface;
-}): void;
-export declare function signBIP32({ psbt, masterNode }: {
-    psbt: Psbt;
-    masterNode: BIP32Interface;
-}): void;
-/**
- * Signs an input of the `psbt` where the keys are controlled by a Ledger
- * device.
- *
- * The function will throw an error if it's unable to sign the input.
- */
-export declare function signInputLedger({ psbt, index, ledgerManager }: {
-    psbt: Psbt;
-    index: number;
-    ledgerManager: LedgerManager;
-}): Promise<void>;
-/**
- * Signs the inputs of the `psbt` where the keys are controlled by a Ledger
- * device.
- *
- * `signLedger` can sign multiple inputs of the same wallet policy in a single
- * pass by grouping inputs by their wallet policy type before the signing
- * process.
- *
- * The function will throw an error if it's unable to sign any input.
- */
-export declare function signLedger({ psbt, ledgerManager }: {
-    psbt: Psbt;
-    ledgerManager: LedgerManager;
-}): Promise<void>;

package/dist/signers.js

@@ -1,215 +0,0 @@
-"use strict";
-// Copyright (c) 2025 Jose-Luis Landabaso - https://bitcoinerlab.com
-// Distributed under the MIT software license
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.signInputECPair = signInputECPair;
-exports.signECPair = signECPair;
-exports.signInputBIP32 = signInputBIP32;
-exports.signBIP32 = signBIP32;
-exports.signInputLedger = signInputLedger;
-exports.signLedger = signLedger;
-const bitcoinjs_lib_internals_1 = require("./bitcoinjs-lib-internals");
-const ledger_1 = require("./ledger");
-const applyPR2137_1 = require("./applyPR2137");
-function range(n) {
-    return [...Array(n).keys()];
-}
-/**
- * Signs a specific input of a PSBT with an ECPair.
- *
- * Unlike bitcoinjs-lib's native `psbt.signInput()`, this function automatically detects
- * if the input is a Taproot input and internally tweaks the key if needed.
- *
- * This behavior matches how `signInputBIP32` works, where the BIP32 node is automatically
- * tweaked for Taproot inputs. In contrast, bitcoinjs-lib's native implementation requires
- * manual pre-tweaking of ECPair signers for Taproot inputs.
- *
- * @see https://github.com/bitcoinjs/bitcoinjs-lib/pull/2137#issuecomment-2713264848
- *
- * @param {Object} params - The parameters object
- * @param {Psbt} params.psbt - The PSBT to sign
- * @param {number} params.index - The input index to sign
- * @param {ECPairInterface} params.ecpair - The ECPair to sign with
- */
-function signInputECPair({ psbt, index, ecpair }) {
-    //psbt.signInput(index, ecpair); <- Replaced for the code below
-    //that can handle taproot inputs automatically.
-    //See https://github.com/bitcoinjs/bitcoinjs-lib/pull/2137#issuecomment-2713264848
-    const input = psbt.data.inputs[index];
-    if (!input)
-        throw new Error('Invalid index');
-    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, bitcoinjs_lib_internals_1.tapTweakHash)(ecpair.publicKey.slice(1, 33), undefined);
-            const tweakedEcpair = ecpair.tweak(hash);
-            psbt.signInput(index, tweakedEcpair);
-        }
-    }
-    else
-        psbt.signInput(index, ecpair);
-}
-/**
- * Signs all inputs of a PSBT with an ECPair.
- *
- * This function improves upon bitcoinjs-lib's native `psbt.signAllInputs()` by automatically
- * handling Taproot inputs. For each input, it detects if it's a Taproot input and internally
- * tweaks the key if needed.
- *
- * This creates consistency with the BIP32 signing methods (`signBIP32`/`signInputBIP32`),
- * which also automatically handle key tweaking for Taproot inputs. In contrast, bitcoinjs-lib's
- * native implementation requires users to manually pre-tweak ECPair signers for Taproot inputs.
- *
- * With this implementation, you can use a single ECPair to sign both Taproot and non-Taproot
- * inputs in the same PSBT, similar to how `signBIP32` allows using a common node for both types.
- *
- * @see https://github.com/bitcoinjs/bitcoinjs-lib/pull/2137#issuecomment-2713264848
- *
- * @param {Object} params - The parameters object
- * @param {Psbt} params.psbt - The PSBT to sign
- * @param {ECPairInterface} params.ecpair - The ECPair to sign with
- */
-function signECPair({ psbt, ecpair }) {
-    //psbt.signAllInputs(ecpair); <- replaced for the code below that handles
-    //taptoot automatically.
-    //See https://github.com/bitcoinjs/bitcoinjs-lib/pull/2137#issuecomment-2713264848
-    const results = [];
-    for (const index of range(psbt.data.inputs.length)) {
-        try {
-            signInputECPair({ psbt, index, ecpair });
-            results.push(true);
-        }
-        catch (err) {
-            void err;
-            results.push(false);
-        }
-    }
-    if (results.every(v => v === false)) {
-        throw new Error('No inputs were signed');
-    }
-}
-function signInputBIP32({ psbt, index, node }) {
-    (0, applyPR2137_1.applyPR2137)(psbt);
-    psbt.signInputHD(index, node);
-}
-function signBIP32({ psbt, masterNode }) {
-    (0, applyPR2137_1.applyPR2137)(psbt);
-    psbt.signAllInputsHD(masterNode);
-}
-const ledgerSignaturesForInputIndex = (index, ledgerSignatures) => ledgerSignatures
-    .filter(([i]) => i === index)
-    .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 });
-        }
-        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 {
-        const partialSig = signatures.map((sig) => ({
-            pubkey: sig.pubkey,
-            signature: sig.signature
-        }));
-        psbt.updateInput(index, { partialSig });
-    }
-}
-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 });
-}
-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 = [];
-    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) {
-        if (!uniquePolicies.find((uniquePolicy) => (0, ledger_1.comparePolicies)(uniquePolicy, policy)))
-            uniquePolicies.push(policy);
-    }
-    for (const uniquePolicy of uniquePolicies) {
-        let ledgerSignatures;
-        if (uniquePolicy.policyName &&
-            uniquePolicy.policyHmac &&
-            uniquePolicy.policyId) {
-            //non-standard policy
-            const walletPolicy = new WalletPolicy(uniquePolicy.policyName, uniquePolicy.ledgerTemplate, uniquePolicy.keyRoots);
-            const walletHmac = uniquePolicy.policyHmac;
-            ledgerSignatures = await ledgerClient.signPsbt(psbt.toBase64(), walletPolicy, walletHmac);
-        }
-        else {
-            //standard policy
-            ledgerSignatures = await ledgerClient.signPsbt(psbt.toBase64(), new DefaultWalletPolicy(uniquePolicy.ledgerTemplate, uniquePolicy.keyRoots[0]), null);
-        }
-        const signedIndexes = [
-            ...new Set(ledgerSignatures.map(([index]) => index))
-        ];
-        for (const index of signedIndexes) {
-            addLedgerSignaturesToInput({ psbt, index, ledgerSignatures });
-        }
-    }
-}

package/dist/tapMiniscript.d.ts

@@ -1,215 +0,0 @@
-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 { ExpansionMap, KeyInfo, Preimage, TimeConstraints } from './types';
-import type { TapLeafInfo, TapTreeInfoNode, TapTreeNode } from './tapTree';
-export type TapLeafExpansionOverride = {
-    expandedExpression: string;
-    expansionMap: ExpansionMap;
-    tapScript: Uint8Array;
-};
-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 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.
- */
-export declare function buildTapTreeInfo({ tapTree, network, BIP32, ECPair, leafExpansionOverride }: {
-    tapTree: TapTreeNode;
-    network?: Network;
-    BIP32: BIP32API;
-    ECPair: ECPairAPI;
-    leafExpansionOverride: (expression: string) => TapLeafExpansionOverride | undefined;
-}): 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;
-/**
- * Compiles an expanded `sortedmulti_a(...)` leaf expression to its internal
- * `multi_a(...)` form by sorting placeholders using the resolved pubkeys from
- * `expansionMap`.
- */
-export declare function compileSortedMultiAExpandedExpression({ expandedExpression, expansionMap }: {
-    expandedExpression: string;
-    expansionMap: ExpansionMap;
-}): string;
-/**
- * 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 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).
- */
-export declare function satisfyTapTree({ tapTreeInfo, signatures, preimages, tapLeaf, timeConstraints }: {
-    tapTreeInfo: TapTreeInfoNode;
-    signatures: PartialSig[];
-    preimages: Preimage[];
-    tapLeaf?: Uint8Array | string;
-    timeConstraints?: TimeConstraints;
-}): TaprootLeafSatisfaction;