@bitcoinerlab/descriptors 2.3.6 → 3.0.0

package/dist/descriptors.js

@@ -1,5 +1,5 @@
 "use strict";
-// Copyright (c) 2025 Jose-Luis Landabaso - https://bitcoinerlab.com
+// Copyright (c) 2026 Jose-Luis Landabaso - https://bitcoinerlab.com
 // Distributed under the MIT software license
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -50,9 +50,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DescriptorsFactory = DescriptorsFactory;
-const lodash_memoize_1 = __importDefault(require("lodash.memoize"));
+const lodash_memoize_1 = __importDefault(require("lodash.memoize")); //TODO: make sure this is propoely used
 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 { p2sh, p2wpkh, p2pkh, p2pk, p2wsh, p2tr } = bitcoinjs_lib_1.payments;
 const bip32_1 = require("bip32");
 const ecpair_1 = require("ecpair");
@@ -61,17 +63,13 @@ const checksum_1 = require("./checksum");
 const keyExpressions_1 = require("./keyExpressions");
 const RE = __importStar(require("./re"));
 const miniscript_1 = require("./miniscript");
-//See "Resource limitations" https://bitcoin.sipa.be/miniscript/
-//https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2019-September/017306.html
-const MAX_SCRIPT_ELEMENT_SIZE = 520;
-const MAX_STANDARD_P2WSH_SCRIPT_SIZE = 3600;
-const MAX_OPS_PER_SCRIPT = 201;
-function countNonPushOnlyOPs(script) {
-    const decompile = bitcoinjs_lib_1.script.decompile(script);
-    if (!decompile)
-        throw new Error(`Error: cound not decompile ${script}`);
-    return decompile.filter(op => typeof op === 'number' && op > bitcoinjs_lib_1.script.OPS['OP_16']).length;
-}
+const tapTree_1 = require("./tapTree");
+const tapMiniscript_1 = require("./tapMiniscript");
+const parseUtils_1 = require("./parseUtils");
+const multipath_1 = require("./multipath");
+const resourceLimits_1 = require("./resourceLimits");
+const ECDSA_FAKE_SIGNATURE_SIZE = 72;
+const TAPROOT_FAKE_SIGNATURE_SIZE = 64;
 function vectorSize(someVector) {
     const length = someVector.length;
     return ((0, varuint_bitcoin_1.encodingLength)(length) +
@@ -83,23 +81,12 @@ function varSliceSize(someScript) {
     const length = someScript.length;
     return (0, varuint_bitcoin_1.encodingLength)(length) + length;
 }
-/**
- * This function will typically return 73; since it assumes a signature size of
- * 72 bytes (this is the max size of a DER encoded signature) and it adds 1
- * extra byte for encoding its length
- */
-function signatureSize(signature) {
-    const length = signature === 'DANGEROUSLY_USE_FAKE_SIGNATURES'
-        ? 72
-        : signature.signature.length;
-    return (0, varuint_bitcoin_1.encodingLength)(length) + length;
-}
 /*
  * Returns a bare descriptor without checksum and particularized for a certain
  * index (if desc was a range descriptor)
  * @hidden
  */
-function evaluate({ descriptor, checksumRequired, index }) {
+function evaluate({ descriptor, checksumRequired, index, change }) {
     if (!descriptor)
         throw new Error('You must provide a descriptor.');
     const mChecksum = descriptor.match(String.raw `(${RE.reChecksum})$`);
@@ -115,6 +102,10 @@ function evaluate({ descriptor, checksumRequired, index }) {
             throw new Error(`Error: invalid descriptor checksum for ${descriptor}`);
         }
     }
+    evaluatedDescriptor = (0, multipath_1.resolveMultipathDescriptor)({
+        descriptor: evaluatedDescriptor,
+        ...(change !== undefined ? { change } : {})
+    });
     if (index !== undefined) {
         const mWildcard = evaluatedDescriptor.match(/\*/g);
         if (mWildcard && mWildcard.length > 0) {
@@ -148,6 +139,21 @@ function parseSortedMulti(inner) {
         throw new Error(`sortedmulti(): descriptors support up to 20 keys (per BIP 380/383).`);
     return { m, keyExpressions };
 }
+function parseTrExpression(expression) {
+    if (!expression.startsWith('tr(') || !expression.endsWith(')'))
+        throw new Error(`Error: invalid descriptor ${expression}`);
+    const innerExpression = expression.slice(3, -1).trim();
+    if (!innerExpression)
+        throw new Error(`Error: invalid descriptor ${expression}`);
+    const splitResult = (0, parseUtils_1.splitTopLevelComma)({
+        expression: innerExpression,
+        onError: () => new Error(`Error: invalid descriptor ${expression}`)
+    });
+    //if no commas: innerExpression === keyExpression
+    if (!splitResult)
+        return { keyExpression: innerExpression };
+    return { keyExpression: splitResult.left, treeExpression: splitResult.right };
+}
 /**
  * Constructs the necessary functions and classes for working with descriptors
  * using an external elliptic curve (ecc) library.
@@ -156,12 +162,8 @@ function parseSortedMulti(inner) {
  * provides methods to create, sign, and finalize PSBTs based on descriptor
  * expressions.
  *
- * While this Factory function includes the `Descriptor` class, note that
- * this class was deprecated in v2.0 in favor of `Output`. For backward
- * compatibility, the `Descriptor` class remains, but using `Output` is advised.
- *
  * The Factory also returns utility methods like `expand` (detailed below)
- * and `parseKeyExpression` (see {@link ParseKeyExpression}).
+ * and `parseKeyExpression` (see {@link KeyExpressionParser}).
  *
  * Additionally, for convenience, the function returns `BIP32` and `ECPair`.
  * These are {@link https://github.com/bitcoinjs bitcoinjs-lib} classes designed
@@ -174,7 +176,7 @@ function parseSortedMulti(inner) {
  * [@bitcoinerlab/secp256k1](https://github.com/bitcoinerlab/secp256k1).
  */
 function DescriptorsFactory(ecc) {
-    var _Output_instances, _Output_payment, _Output_preimages, _Output_signersPubKeys, _Output_miniscript, _Output_witnessScript, _Output_redeemScript, _Output_isSegwit, _Output_isTaproot, _Output_expandedExpression, _Output_expandedMiniscript, _Output_expansionMap, _Output_network, _Output_getTimeConstraints, _Output_assertPsbtInput;
+    var _Output_instances, _Output_payment, _Output_preimages, _Output_signersPubKeys, _Output_miniscript, _Output_witnessScript, _Output_redeemScript, _Output_isSegwit, _Output_isTaproot, _Output_expandedExpression, _Output_expandedMiniscript, _Output_tapTreeExpression, _Output_tapTree, _Output_tapTreeInfo, _Output_taprootSpendPath, _Output_tapLeaf, _Output_expansionMap, _Output_network, _Output_resolveMiniscriptSignersPubKeys, _Output_assertMiniscriptSatisfactionResourceLimits, _Output_resolveTapTreeSignersPubKeys, _Output_getConstraints, _Output_assertPsbtInput;
     (0, bitcoinjs_lib_1.initEccLib)(ecc); //Taproot requires initEccLib
     const BIP32 = (0, bip32_1.BIP32Factory)(ecc);
     const ECPair = (0, ecpair_1.ECPairFactory)(ecc);
@@ -203,15 +205,7 @@ function DescriptorsFactory(ecc) {
             BIP32
         });
     };
-    /**
-     * @overload
-     * To be removed in v3.0 and replaced by the version with the signature that
-     * does not accept descriptors
-     */
-    function expand({ descriptor, expression, index, checksumRequired = false, network = bitcoinjs_lib_1.networks.bitcoin, allowMiniscriptInP2SH = false }) {
-        if (descriptor && expression)
-            throw new Error(`expression param has been deprecated`);
-        descriptor = descriptor || expression;
+    function expand({ descriptor, index, change, checksumRequired = false, network = bitcoinjs_lib_1.networks.bitcoin, allowMiniscriptInP2SH = false }) {
         if (!descriptor)
             throw new Error(`descriptor not provided`);
         let expandedExpression;
@@ -220,6 +214,9 @@ function DescriptorsFactory(ecc) {
         let isSegwit;
         let isTaproot;
         let expandedMiniscript;
+        let tapTreeExpression;
+        let tapTree;
+        let tapTreeInfo;
         let payment;
         let witnessScript;
         let redeemScript;
@@ -232,6 +229,7 @@ function DescriptorsFactory(ecc) {
         const canonicalExpression = evaluate({
             descriptor,
             ...(index !== undefined ? { index } : {}),
+            ...(change !== undefined ? { change } : {}),
             checksumRequired
         });
         const isCanonicalRanged = canonicalExpression.indexOf('*') !== -1;
@@ -398,7 +396,7 @@ function DescriptorsFactory(ecc) {
                         throw new Error(`Error: key has no pubkey`);
                     return p.pubkey;
                 });
-                pubkeys.sort((a, b) => a.compare(b));
+                pubkeys.sort((a, b) => (0, uint8array_tools_1.compare)(a, b));
                 const redeem = bitcoinjs_lib_1.payments.p2ms({ m, pubkeys, network });
                 redeemScript = redeem.output;
                 if (!redeemScript)
@@ -428,7 +426,7 @@ function DescriptorsFactory(ecc) {
                         throw new Error(`Error: key has no pubkey`);
                     return p.pubkey;
                 });
-                pubkeys.sort((a, b) => a.compare(b));
+                pubkeys.sort((a, b) => (0, uint8array_tools_1.compare)(a, b));
                 const redeem = bitcoinjs_lib_1.payments.p2ms({ m, pubkeys, network });
                 witnessScript = redeem.output;
                 if (!witnessScript)
@@ -458,7 +456,7 @@ function DescriptorsFactory(ecc) {
                         throw new Error(`Error: key has no pubkey`);
                     return p.pubkey;
                 });
-                pubkeys.sort((a, b) => a.compare(b));
+                pubkeys.sort((a, b) => (0, uint8array_tools_1.compare)(a, b));
                 const redeem = bitcoinjs_lib_1.payments.p2ms({ m, pubkeys, network });
                 const wsh = bitcoinjs_lib_1.payments.p2wsh({ redeem, network });
                 witnessScript = redeem.output;
@@ -482,13 +480,10 @@ function DescriptorsFactory(ecc) {
             if (!isCanonicalRanged) {
                 const script = (0, miniscript_1.miniscript2Script)({ expandedMiniscript, expansionMap });
                 witnessScript = script;
-                if (script.byteLength > MAX_STANDARD_P2WSH_SCRIPT_SIZE) {
-                    throw new Error(`Error: script is too large, ${script.byteLength} bytes is larger than ${MAX_STANDARD_P2WSH_SCRIPT_SIZE} bytes`);
-                }
-                const nonPushOnlyOps = countNonPushOnlyOPs(script);
-                if (nonPushOnlyOps > MAX_OPS_PER_SCRIPT) {
-                    throw new Error(`Error: too many non-push ops, ${nonPushOnlyOps} non-push ops is larger than ${MAX_OPS_PER_SCRIPT}`);
+                if (script.byteLength > resourceLimits_1.MAX_STANDARD_P2WSH_SCRIPT_SIZE) {
+                    throw new Error(`Error: script is too large, ${script.byteLength} bytes is larger than ${resourceLimits_1.MAX_STANDARD_P2WSH_SCRIPT_SIZE} bytes`);
                 }
+                (0, resourceLimits_1.assertScriptNonPushOnlyOpsLimit)({ script });
                 payment = p2sh({
                     redeem: p2wsh({ redeem: { output: script, network }, network }),
                     network
@@ -523,13 +518,10 @@ function DescriptorsFactory(ecc) {
             if (!isCanonicalRanged) {
                 const script = (0, miniscript_1.miniscript2Script)({ expandedMiniscript, expansionMap });
                 redeemScript = script;
-                if (script.byteLength > MAX_SCRIPT_ELEMENT_SIZE) {
-                    throw new Error(`Error: P2SH script is too large, ${script.byteLength} bytes is larger than ${MAX_SCRIPT_ELEMENT_SIZE} bytes`);
-                }
-                const nonPushOnlyOps = countNonPushOnlyOPs(script);
-                if (nonPushOnlyOps > MAX_OPS_PER_SCRIPT) {
-                    throw new Error(`Error: too many non-push ops, ${nonPushOnlyOps} non-push ops is larger than ${MAX_OPS_PER_SCRIPT}`);
+                if (script.byteLength > resourceLimits_1.MAX_SCRIPT_ELEMENT_SIZE) {
+                    throw new Error(`Error: P2SH script is too large, ${script.byteLength} bytes is larger than ${resourceLimits_1.MAX_SCRIPT_ELEMENT_SIZE} bytes`);
                 }
+                (0, resourceLimits_1.assertScriptNonPushOnlyOpsLimit)({ script });
                 payment = p2sh({ redeem: { output: script, network }, network });
             }
         }
@@ -549,26 +541,21 @@ function DescriptorsFactory(ecc) {
             if (!isCanonicalRanged) {
                 const script = (0, miniscript_1.miniscript2Script)({ expandedMiniscript, expansionMap });
                 witnessScript = script;
-                if (script.byteLength > MAX_STANDARD_P2WSH_SCRIPT_SIZE) {
-                    throw new Error(`Error: script is too large, ${script.byteLength} bytes is larger than ${MAX_STANDARD_P2WSH_SCRIPT_SIZE} bytes`);
-                }
-                const nonPushOnlyOps = countNonPushOnlyOPs(script);
-                if (nonPushOnlyOps > MAX_OPS_PER_SCRIPT) {
-                    throw new Error(`Error: too many non-push ops, ${nonPushOnlyOps} non-push ops is larger than ${MAX_OPS_PER_SCRIPT}`);
+                if (script.byteLength > resourceLimits_1.MAX_STANDARD_P2WSH_SCRIPT_SIZE) {
+                    throw new Error(`Error: script is too large, ${script.byteLength} bytes is larger than ${resourceLimits_1.MAX_STANDARD_P2WSH_SCRIPT_SIZE} bytes`);
                 }
+                (0, resourceLimits_1.assertScriptNonPushOnlyOpsLimit)({ script });
                 payment = p2wsh({ redeem: { output: script, network }, network });
             }
         }
-        //tr(KEY) - taproot - TODO: tr(KEY,TREE) not yet supported
-        else if (canonicalExpression.match(RE.reTrSingleKeyAnchored)) {
+        //tr(KEY) or tr(KEY,TREE) - taproot
+        else if (canonicalExpression.startsWith('tr(')) {
             isSegwit = true;
             isTaproot = true;
-            const keyExpression = canonicalExpression.match(RE.reTaprootKeyExp)?.[0];
-            if (!keyExpression)
-                throw new Error(`Error: keyExpression could not me extracted`);
-            if (canonicalExpression !== `tr(${keyExpression})`)
-                throw new Error(`Error: invalid expression ${expression}`);
-            expandedExpression = 'tr(@0)';
+            const { keyExpression, treeExpression } = parseTrExpression(canonicalExpression);
+            expandedExpression = treeExpression
+                ? `tr(@0,${treeExpression})`
+                : 'tr(@0)';
             const pKE = parseKeyExpression({
                 keyExpression,
                 network,
@@ -576,17 +563,30 @@ function DescriptorsFactory(ecc) {
                 isTaproot
             });
             expansionMap = { '@0': pKE };
+            if (treeExpression) {
+                tapTreeExpression = treeExpression;
+                tapTree = (0, tapTree_1.parseTapTreeExpression)(treeExpression);
+                if (!isCanonicalRanged) {
+                    tapTreeInfo = (0, tapMiniscript_1.buildTapTreeInfo)({ tapTree, network, BIP32, ECPair });
+                }
+            }
             if (!isCanonicalRanged) {
                 const pubkey = pKE.pubkey;
                 if (!pubkey)
-                    throw new Error(`Error: could not extract a pubkey from ${expression}`);
-                payment = p2tr({ internalPubkey: pubkey, network });
-                //console.log('TRACE', {
-                //  pKE,
-                //  pubkey: pubkey?.toString('hex'),
-                //  payment,
-                //  paymentPubKey: payment.pubkey
-                //});
+                    throw new Error(`Error: could not extract a pubkey from ${descriptor}`);
+                const internalPubkey = (0, tapMiniscript_1.normalizeTaprootPubkey)(pubkey);
+                if (treeExpression) {
+                    if (!tapTreeInfo)
+                        throw new Error(`Error: taproot tree info not available`);
+                    payment = p2tr({
+                        internalPubkey,
+                        scriptTree: (0, tapMiniscript_1.tapTreeInfoToScriptTree)(tapTreeInfo),
+                        network
+                    });
+                }
+                else {
+                    payment = p2tr({ internalPubkey, network });
+                }
             }
         }
         else {
@@ -600,6 +600,9 @@ function DescriptorsFactory(ecc) {
             ...(isSegwit !== undefined ? { isSegwit } : {}),
             ...(isTaproot !== undefined ? { isTaproot } : {}),
             ...(expandedMiniscript !== undefined ? { expandedMiniscript } : {}),
+            ...(tapTreeExpression !== undefined ? { tapTreeExpression } : {}),
+            ...(tapTree !== undefined ? { tapTree } : {}),
+            ...(tapTreeInfo !== undefined ? { tapTreeInfo } : {}),
             ...(redeemScript !== undefined ? { redeemScript } : {}),
             ...(witnessScript !== undefined ? { witnessScript } : {}),
             isRanged,
@@ -634,7 +637,7 @@ function DescriptorsFactory(ecc) {
          * @param options
          * @throws {Error} - when descriptor is invalid
          */
-        constructor({ descriptor, index, checksumRequired = false, allowMiniscriptInP2SH = false, network = bitcoinjs_lib_1.networks.bitcoin, preimages = [], signersPubKeys }) {
+        constructor({ descriptor, index, change, checksumRequired = false, allowMiniscriptInP2SH = false, network = bitcoinjs_lib_1.networks.bitcoin, preimages = [], signersPubKeys, taprootSpendPath, tapLeaf }) {
             _Output_instances.add(this);
             _Output_payment.set(this, void 0);
             _Output_preimages.set(this, []);
@@ -648,6 +651,11 @@ function DescriptorsFactory(ecc) {
             _Output_isTaproot.set(this, void 0);
             _Output_expandedExpression.set(this, void 0);
             _Output_expandedMiniscript.set(this, void 0);
+            _Output_tapTreeExpression.set(this, void 0);
+            _Output_tapTree.set(this, void 0);
+            _Output_tapTreeInfo.set(this, void 0);
+            _Output_taprootSpendPath.set(this, void 0);
+            _Output_tapLeaf.set(this, void 0);
             _Output_expansionMap.set(this, void 0);
             _Output_network.set(this, void 0);
             __classPrivateFieldSet(this, _Output_network, network, "f");
@@ -657,10 +665,26 @@ function DescriptorsFactory(ecc) {
             const expandedResult = expand({
                 descriptor,
                 ...(index !== undefined ? { index } : {}),
+                ...(change !== undefined ? { change } : {}),
                 checksumRequired,
                 network,
                 allowMiniscriptInP2SH
             });
+            const isTaprootDescriptor = expandedResult.isTaproot === true;
+            const hasTapTree = expandedResult.expandedExpression?.startsWith('tr(@0,') ?? false;
+            const resolvedTaprootSpendPath = taprootSpendPath ?? (hasTapTree ? 'script' : 'key');
+            if (!isTaprootDescriptor) {
+                if (taprootSpendPath !== undefined || tapLeaf !== undefined)
+                    throw new Error(`Error: taprootSpendPath/tapLeaf require a taproot descriptor`);
+            }
+            else {
+                if (taprootSpendPath === 'script' && !hasTapTree)
+                    throw new Error(`Error: taprootSpendPath=script requires a tr(KEY,TREE) descriptor`);
+                if (resolvedTaprootSpendPath === 'key' && tapLeaf !== undefined)
+                    throw new Error(`Error: tapLeaf cannot be used when taprootSpendPath is key`);
+                if (tapLeaf !== undefined && !hasTapTree)
+                    throw new Error(`Error: tapLeaf can only be used with tr(KEY,TREE) descriptors`);
+            }
             if (expandedResult.isRanged && index === undefined)
                 throw new Error(`Error: index was not provided for ranged descriptor`);
             if (!expandedResult.payment)
@@ -678,83 +702,55 @@ function DescriptorsFactory(ecc) {
                 __classPrivateFieldSet(this, _Output_isTaproot, expandedResult.isTaproot, "f");
             if (expandedResult.expandedMiniscript !== undefined)
                 __classPrivateFieldSet(this, _Output_expandedMiniscript, expandedResult.expandedMiniscript, "f");
+            if (expandedResult.tapTreeExpression !== undefined)
+                __classPrivateFieldSet(this, _Output_tapTreeExpression, expandedResult.tapTreeExpression, "f");
+            if (expandedResult.tapTree !== undefined)
+                __classPrivateFieldSet(this, _Output_tapTree, expandedResult.tapTree, "f");
+            if (expandedResult.tapTreeInfo !== undefined)
+                __classPrivateFieldSet(this, _Output_tapTreeInfo, expandedResult.tapTreeInfo, "f");
             if (expandedResult.redeemScript !== undefined)
                 __classPrivateFieldSet(this, _Output_redeemScript, expandedResult.redeemScript, "f");
             if (expandedResult.witnessScript !== undefined)
                 __classPrivateFieldSet(this, _Output_witnessScript, expandedResult.witnessScript, "f");
-            if (signersPubKeys) {
+            if (signersPubKeys)
                 __classPrivateFieldSet(this, _Output_signersPubKeys, signersPubKeys, "f");
-            }
-            else {
-                if (__classPrivateFieldGet(this, _Output_expansionMap, "f")) {
-                    __classPrivateFieldSet(this, _Output_signersPubKeys, Object.values(__classPrivateFieldGet(this, _Output_expansionMap, "f")).map(keyInfo => {
-                        const pubkey = keyInfo.pubkey;
-                        if (!pubkey)
-                            throw new Error(`Error: could not extract a pubkey from ${descriptor}`);
-                        return pubkey;
-                    }), "f");
-                }
-                else {
-                    //We should only miss expansionMap in addr() expressions:
-                    if (!expandedResult.canonicalExpression.match(RE.reAddrAnchored)) {
-                        throw new Error(`Error: expansionMap not available for expression ${descriptor} that is not an address`);
-                    }
-                    __classPrivateFieldSet(this, _Output_signersPubKeys, [this.getScriptPubKey()], "f");
-                }
-            }
+            __classPrivateFieldSet(this, _Output_taprootSpendPath, resolvedTaprootSpendPath, "f");
+            if (tapLeaf !== undefined)
+                __classPrivateFieldSet(this, _Output_tapLeaf, tapLeaf, "f");
             this.getSequence = (0, lodash_memoize_1.default)(this.getSequence);
             this.getLockTime = (0, lodash_memoize_1.default)(this.getLockTime);
             const getSignaturesKey = (signatures) => signatures === 'DANGEROUSLY_USE_FAKE_SIGNATURES'
                 ? signatures
                 : signatures
-                    .map(s => `${s.pubkey.toString('hex')}-${s.signature.toString('hex')}`)
+                    .map(s => `${(0, uint8array_tools_1.toHex)(s.pubkey)}-${(0, uint8array_tools_1.toHex)(s.signature)}`)
                     .join('|');
-            this.getScriptSatisfaction = (0, lodash_memoize_1.default)(this.getScriptSatisfaction, 
-            // resolver function:
-            getSignaturesKey);
             this.guessOutput = (0, lodash_memoize_1.default)(this.guessOutput);
             this.inputWeight = (0, lodash_memoize_1.default)(this.inputWeight, 
             // resolver function:
-            (isSegwitTx, signatures) => {
+            (isSegwitTx, signatures, options) => {
                 const segwitKey = isSegwitTx ? 'segwit' : 'non-segwit';
                 const signaturesKey = getSignaturesKey(signatures);
-                return `${segwitKey}-${signaturesKey}`;
+                const taprootSighashKey = options?.taprootSighash ?? 'SIGHASH_DEFAULT';
+                return `${segwitKey}-${signaturesKey}-taprootSighash:${taprootSighashKey}`;
             });
             this.outputWeight = (0, lodash_memoize_1.default)(this.outputWeight);
         }
         /**
-         * Creates and returns an instance of bitcoinjs-lib
-         * [`Payment`](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/ts_src/payments/index.ts)'s interface with the `scriptPubKey` of this `Output`.
-         */
-        getPayment() {
-            return __classPrivateFieldGet(this, _Output_payment, "f");
-        }
-        /**
-         * Returns the Bitcoin Address of this `Output`.
-         */
-        getAddress() {
-            if (!__classPrivateFieldGet(this, _Output_payment, "f").address)
-                throw new Error(`Error: could extract an address from the payment`);
-            return __classPrivateFieldGet(this, _Output_payment, "f").address;
-        }
-        /**
-         * Returns this `Output`'s scriptPubKey.
-         */
-        getScriptPubKey() {
-            if (!__classPrivateFieldGet(this, _Output_payment, "f").output)
-                throw new Error(`Error: could extract output.script from the payment`);
-            return __classPrivateFieldGet(this, _Output_payment, "f").output;
-        }
-        /**
-         * Returns the compiled Script Satisfaction if this `Output` was created
-         * using a miniscript-based descriptor.
+         * Returns the compiled Script Satisfaction for a miniscript-based Output.
+         * The satisfaction is the unlocking script, derived by the Satisfier
+         * algorithm (https://bitcoin.sipa.be/miniscript/).
          *
-         * The Satisfaction is the unlocking script that fulfills
-         * (satisfies) this `Output` and it is derived using the Safisfier algorithm
-         * [described here](https://bitcoin.sipa.be/miniscript/).
+         * This method uses a two-pass flow:
+         * 1) Planning: constraints (nLockTime/nSequence) are computed using fake
+         *    signatures. This is done since the final solution may not need all the
+         *    signatures in signersPubKeys. And we may avoid the user do extra
+         *    signing (tedious op with HWW).
+         * 2) Signing: the provided signatures are used to build the final
+         *    satisfaction, while enforcing the planned constraints so the same
+         *    solution is selected. Not all the signatures of signersPubKeys may
+         *    be required.
          *
-         * Important: As mentioned above, note that this function only applies to
-         * miniscript descriptors.
+         * The return value includes the satisfaction script and the constraints.
          */
         getScriptSatisfaction(
         /**
@@ -762,29 +758,9 @@ function DescriptorsFactory(ecc) {
          * build the Satisfaction of this miniscript-based `Output`.
          *
          * `signatures` must be passed using this format (pairs of `pubKey/signature`):
-         * `interface PartialSig { pubkey: Buffer; signature: Buffer; }`
-         *
-         *  * Alternatively, if you do not have the signatures, you can use the option
-         * `'DANGEROUSLY_USE_FAKE_SIGNATURES'`. This will generate script satisfactions
-         * using 72-byte zero-padded signatures. While this can be useful in
-         * modules like coinselector that require estimating transaction size before
-         * signing, it is critical to understand the risks:
-         * - Using this option generales invalid unlocking scripts.
-         * - It should NEVER be used with real transactions.
-         * - Its primary use is for testing and size estimation purposes only.
-         *
-         * ⚠️ Warning: Misuse of 'DANGEROUSLY_USE_FAKE_SIGNATURES' can lead to security
-         * vulnerabilities, including but not limited to invalid transaction generation.
-         * Ensure you fully understand the implications before use.
-         *
+         * `interface PartialSig { pubkey: Uint8Array; signature: Uint8Array; }`
          */
         signatures) {
-            if (signatures === 'DANGEROUSLY_USE_FAKE_SIGNATURES')
-                signatures = __classPrivateFieldGet(this, _Output_signersPubKeys, "f").map(pubkey => ({
-                    pubkey,
-                    // https://transactionfee.info/charts/bitcoin-script-ecdsa-length/
-                    signature: Buffer.alloc(72, 0)
-                }));
             const miniscript = __classPrivateFieldGet(this, _Output_miniscript, "f");
             const expandedMiniscript = __classPrivateFieldGet(this, _Output_expandedMiniscript, "f");
             const expansionMap = __classPrivateFieldGet(this, _Output_expansionMap, "f");
@@ -792,12 +768,9 @@ function DescriptorsFactory(ecc) {
                 expandedMiniscript === undefined ||
                 expansionMap === undefined)
                 throw new Error(`Error: cannot get satisfaction from not expanded miniscript ${miniscript}`);
-            //Note that we pass the nLockTime and nSequence that is deduced
-            //using preimages and signersPubKeys.
-            //satisfyMiniscript will make sure
-            //that the actual solution given, using real signatures, still meets the
-            //same nLockTime and nSequence constraints
-            const scriptSatisfaction = (0, miniscript_1.satisfyMiniscript)({
+            //This crates the plans using fake signatures
+            const constraints = __classPrivateFieldGet(this, _Output_instances, "m", _Output_getConstraints).call(this);
+            const satisfaction = (0, miniscript_1.satisfyMiniscript)({
                 expandedMiniscript,
                 expansionMap,
                 signatures,
@@ -806,25 +779,96 @@ function DescriptorsFactory(ecc) {
                 //verify that the solutions found using the final signatures have not
                 //changed
                 timeConstraints: {
-                    nLockTime: this.getLockTime(),
-                    nSequence: this.getSequence()
+                    nLockTime: constraints?.nLockTime,
+                    nSequence: constraints?.nSequence
                 }
-            }).scriptSatisfaction;
-            if (!scriptSatisfaction)
-                throw new Error(`Error: could not produce a valid satisfaction`);
-            return scriptSatisfaction;
+            });
+            __classPrivateFieldGet(this, _Output_instances, "m", _Output_assertMiniscriptSatisfactionResourceLimits).call(this, satisfaction.scriptSatisfaction);
+            return satisfaction;
+        }
+        /**
+         * Returns the taproot script‑path satisfaction for a tap miniscript
+         * descriptor. This mirrors {@link getScriptSatisfaction} and uses the same
+         * two‑pass plan/sign flow.
+         *
+         * In addition to nLockTime/nSequence, it returns the selected tapLeafHash
+         * (the leaf chosen during planning) and the leaf’s tapscript.
+         */
+        getTapScriptSatisfaction(
+        /**
+         * An array with all the signatures needed to
+         * build the Satisfaction of this miniscript-based `Output`.
+         *
+         * `signatures` must be passed using this format (pairs of `pubKey/signature`):
+         * `interface PartialSig { pubkey: Uint8Array; signature: Uint8Array; }`
+         */
+        signatures) {
+            if (__classPrivateFieldGet(this, _Output_taprootSpendPath, "f") !== 'script')
+                throw new Error(`Error: taprootSpendPath is key; script-path satisfaction is not allowed`);
+            const tapTreeInfo = __classPrivateFieldGet(this, _Output_tapTreeInfo, "f");
+            if (!tapTreeInfo)
+                throw new Error(`Error: taproot tree info not available`);
+            const constraints = __classPrivateFieldGet(this, _Output_instances, "m", _Output_getConstraints).call(this);
+            return (0, tapMiniscript_1.satisfyTapTree)({
+                tapTreeInfo,
+                preimages: __classPrivateFieldGet(this, _Output_preimages, "f"),
+                signatures,
+                ...(constraints?.tapLeafHash
+                    ? { tapLeaf: constraints.tapLeafHash }
+                    : {}),
+                ...(constraints
+                    ? {
+                        timeConstraints: {
+                            nLockTime: constraints.nLockTime,
+                            nSequence: constraints.nSequence
+                        }
+                    }
+                    : {})
+            });
+        }
+        /**
+         * Creates and returns an instance of bitcoinjs-lib
+         * [`Payment`](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/ts_src/payments/index.ts)'s interface with the `scriptPubKey` of this `Output`.
+         */
+        getPayment() {
+            return __classPrivateFieldGet(this, _Output_payment, "f");
+        }
+        /**
+         * Returns the Bitcoin Address of this `Output`.
+         */
+        getAddress() {
+            if (!__classPrivateFieldGet(this, _Output_payment, "f").address)
+                throw new Error(`Error: could extract an address from the payment`);
+            return __classPrivateFieldGet(this, _Output_payment, "f").address;
+        }
+        /**
+         * Returns this `Output`'s scriptPubKey.
+         */
+        getScriptPubKey() {
+            if (!__classPrivateFieldGet(this, _Output_payment, "f").output)
+                throw new Error(`Error: could extract output.script from the payment`);
+            return __classPrivateFieldGet(this, _Output_payment, "f").output;
         }
         /**
          * Gets the nSequence required to fulfill this `Output`.
          */
         getSequence() {
-            return __classPrivateFieldGet(this, _Output_instances, "m", _Output_getTimeConstraints).call(this)?.nSequence;
+            return __classPrivateFieldGet(this, _Output_instances, "m", _Output_getConstraints).call(this)?.nSequence;
         }
         /**
          * Gets the nLockTime required to fulfill this `Output`.
          */
         getLockTime() {
-            return __classPrivateFieldGet(this, _Output_instances, "m", _Output_getTimeConstraints).call(this)?.nLockTime;
+            return __classPrivateFieldGet(this, _Output_instances, "m", _Output_getConstraints).call(this)?.nLockTime;
+        }
+        /**
+         * Returns the tapleaf hash selected during planning for taproot script-path
+         * spends. If signersPubKeys are provided, selection is optimized for those
+         * pubkeys. If a specific tapLeaf selector is used in spending calls, this
+         * reflects that selection.
+         */
+        getTapLeafHash() {
+            return __classPrivateFieldGet(this, _Output_instances, "m", _Output_getConstraints).call(this)?.tapLeafHash;
         }
         /**
          * Gets the witnessScript required to fulfill this `Output`. Only applies to
@@ -955,10 +999,19 @@ function DescriptorsFactory(ecc) {
          *, Also any `addr(SINGLE_KEY_ADDRESS)` * is assumed to be a single key Taproot
          * address (like those defined in BIP86).
          * For inputs using arbitrary scripts (not standard addresses),
-         * use a descriptor in the format `sh(MINISCRIPT)` or `tr(MINISCRIPT)`.
-         * Note however that tr(MINISCRIPT) is not yet supported for non-single-key
-         * expressions.
+         * use a descriptor in the format `sh(MINISCRIPT)`, `wsh(MINISCRIPT)` or
+         * `tr(KEY,TREE)` for taproot script-path expressions.
          */
+        // NOTE(taproot-weight): Output instances are concrete. If descriptor has
+        // wildcards, constructor requires `index`. No ranged-without-index
+        // estimation is attempted here.
+        // TODO(taproot-weight): Remaining items:
+        // - Annex: not modeled; if annex is used, add witness item sizing.
+        // - Taproot sighash defaults: options.taprootSighash currently drives fake
+        //   signature sizing; ensure coinselector passes the intended mode.
+        // - After PSBT taproot script-path fields are fully populated, add regtest
+        //   integration fixtures comparing real tx vsize with inputWeight/outputWeight
+        //   estimates for taproot key-path and script-path spends.
         inputWeight(
         /**
          * Indicates if the transaction is a Segwit transaction.
@@ -973,12 +1026,23 @@ function DescriptorsFactory(ecc) {
          *  Array of `PartialSig`. Each `PartialSig` includes
          *  a public key and its corresponding signature. This parameter
          *  enables the accurate calculation of signature sizes for ECDSA.
-         *  Pass 'DANGEROUSLY_USE_FAKE_SIGNATURES' to assume 72 bytes in length
-         *  for ECDSA.
-         *  Schnorr signatures are always 64 bytes.
+         *  Pass 'DANGEROUSLY_USE_FAKE_SIGNATURES' to assume
+         *  ECDSA_FAKE_SIGNATURE_SIZE bytes for ECDSA.
+         *  For taproot, the fake signature size is controlled by
+         *  options.taprootSighash (64 for 'SIGHASH_DEFAULT', 65
+         *  for 'non-SIGHASH_DEFAULT'). default value is SIGHASH_DEFAULT
          *  Mainly used for testing.
          */
-        signatures) {
+        signatures, 
+        /*
+         *  Options that affect taproot fake signature sizing.
+         *  taprootSighash: 'SIGHASH_DEFAULT' | 'non-SIGHASH_DEFAULT' (default: 'SIGHASH_DEFAULT').
+         *  This is only used when signatures === 'DANGEROUSLY_USE_FAKE_SIGNATURES'.
+         */
+        options = {
+            taprootSighash: 'SIGHASH_DEFAULT'
+        }) {
+            const taprootSighash = options.taprootSighash ?? 'SIGHASH_DEFAULT';
             if (this.isSegwit() && !isSegwitTx)
                 throw new Error(`a tx is segwit if at least one input is segwit`);
             //expand any miniscript-based descriptor. If not miniscript-based, then it's
@@ -991,13 +1055,59 @@ addr(PKH_ADDRESS), addr(WPKH_ADDRESS), addr(SH_WPKH_ADDRESS), addr(SINGLE_KEY_AD
 expansion=${expansion}, isPKH=${isPKH}, isWPKH=${isWPKH}, isSH=${isSH}, isTR=${isTR}.`;
             if (!expansion && !isPKH && !isWPKH && !isSH && !isTR)
                 throw new Error(errorMsg);
-            const firstSignature = signatures && typeof signatures[0] === 'object'
-                ? signatures[0]
-                : 'DANGEROUSLY_USE_FAKE_SIGNATURES';
+            const resolveEcdsaSignatureSize = () => {
+                if (signatures === 'DANGEROUSLY_USE_FAKE_SIGNATURES')
+                    return ((0, varuint_bitcoin_1.encodingLength)(ECDSA_FAKE_SIGNATURE_SIZE) +
+                        ECDSA_FAKE_SIGNATURE_SIZE);
+                if (signatures.length !== 1)
+                    throw new Error('More than one signture was not expected');
+                const singleSignature = signatures[0];
+                if (!singleSignature)
+                    throw new Error('Signatures not present');
+                const length = singleSignature.signature.length;
+                return (0, varuint_bitcoin_1.encodingLength)(length) + length;
+            };
+            const resolveMiniscriptSignatures = () => {
+                if (signatures !== 'DANGEROUSLY_USE_FAKE_SIGNATURES')
+                    return signatures;
+                return __classPrivateFieldGet(this, _Output_instances, "m", _Output_resolveMiniscriptSignersPubKeys).call(this).map(pubkey => ({
+                    pubkey,
+                    // https://transactionfee.info/charts/bitcoin-script-ecdsa-length/
+                    signature: new Uint8Array(ECDSA_FAKE_SIGNATURE_SIZE)
+                }));
+            };
+            const taprootFakeSignatureSize = taprootSighash === 'SIGHASH_DEFAULT'
+                ? TAPROOT_FAKE_SIGNATURE_SIZE
+                : TAPROOT_FAKE_SIGNATURE_SIZE + 1;
+            const resolveTaprootSignatures = () => {
+                if (signatures !== 'DANGEROUSLY_USE_FAKE_SIGNATURES')
+                    return signatures;
+                return __classPrivateFieldGet(this, _Output_instances, "m", _Output_resolveTapTreeSignersPubKeys).call(this).map(pubkey => ({
+                    pubkey,
+                    signature: new Uint8Array(taprootFakeSignatureSize)
+                }));
+            };
+            const resolveTaprootSignatureSize = () => {
+                let length;
+                if (signatures === 'DANGEROUSLY_USE_FAKE_SIGNATURES') {
+                    length = taprootFakeSignatureSize;
+                }
+                else {
+                    if (signatures.length !== 1)
+                        throw new Error('More than one signture was not expected');
+                    const singleSignature = signatures[0];
+                    if (!singleSignature)
+                        throw new Error('Signatures not present');
+                    length = singleSignature.signature.length;
+                }
+                return (0, varuint_bitcoin_1.encodingLength)(length) + length;
+            };
+            const taprootSpendPath = __classPrivateFieldGet(this, _Output_taprootSpendPath, "f");
+            const tapLeaf = __classPrivateFieldGet(this, _Output_tapLeaf, "f");
             if (expansion ? expansion.startsWith('pkh(') : isPKH) {
                 return (
                 // Non-segwit: (txid:32) + (vout:4) + (sequence:4) + (script_len:1) + (sig:73) + (pubkey:34)
-                (32 + 4 + 4 + 1 + signatureSize(firstSignature) + 34) * 4 +
+                (32 + 4 + 4 + 1 + resolveEcdsaSignatureSize() + 34) * 4 +
                     //Segwit:
                     (isSegwitTx ? 1 : 0));
             }
@@ -1008,7 +1118,7 @@ expansion=${expansion}, isPKH=${isPKH}, isWPKH=${isWPKH}, isSH=${isSH}, isTR=${i
                 // Non-segwit: (txid:32) + (vout:4) + (sequence:4) + (script_len:1)
                 41 * 4 +
                     // Segwit: (push_count:1) + (sig:73) + (pubkey:34)
-                    (1 + signatureSize(firstSignature) + 34));
+                    (1 + resolveEcdsaSignatureSize() + 34));
             }
             else if (expansion ? expansion.startsWith('sh(wpkh(') : isSH) {
                 if (!isSegwitTx)
@@ -1019,7 +1129,7 @@ expansion=${expansion}, isPKH=${isPKH}, isWPKH=${isWPKH}, isSH=${isSH}, isTR=${i
                 //  -> p2wpkh: (script_len:1) + (script:22)
                 64 * 4 +
                     // Segwit: (push_count:1) + (sig:73) + (pubkey:34)
-                    (1 + signatureSize(firstSignature) + 34));
+                    (1 + resolveEcdsaSignatureSize() + 34));
             }
             else if (expansion?.startsWith('sh(wsh(')) {
                 if (!isSegwitTx)
@@ -1030,7 +1140,8 @@ expansion=${expansion}, isPKH=${isPKH}, isWPKH=${isWPKH}, isSH=${isSH}, isTR=${i
                 const payment = bitcoinjs_lib_1.payments.p2sh({
                     redeem: bitcoinjs_lib_1.payments.p2wsh({
                         redeem: {
-                            input: this.getScriptSatisfaction(signatures || 'DANGEROUSLY_USE_FAKE_SIGNATURES'),
+                            input: this.getScriptSatisfaction(resolveMiniscriptSignatures())
+                                .scriptSatisfaction,
                             output: witnessScript
                         }
                     })
@@ -1049,7 +1160,8 @@ expansion=${expansion}, isPKH=${isPKH}, isWPKH=${isWPKH}, isSH=${isSH}, isTR=${i
                     throw new Error('sh() must provide redeemScript');
                 const payment = bitcoinjs_lib_1.payments.p2sh({
                     redeem: {
-                        input: this.getScriptSatisfaction(signatures || 'DANGEROUSLY_USE_FAKE_SIGNATURES'),
+                        input: this.getScriptSatisfaction(resolveMiniscriptSignatures())
+                            .scriptSatisfaction,
                         output: redeemScript
                     }
                 });
@@ -1069,7 +1181,8 @@ expansion=${expansion}, isPKH=${isPKH}, isWPKH=${isWPKH}, isSH=${isSH}, isTR=${i
                     throw new Error('wsh must provide witnessScript');
                 const payment = bitcoinjs_lib_1.payments.p2wsh({
                     redeem: {
-                        input: this.getScriptSatisfaction(signatures || 'DANGEROUSLY_USE_FAKE_SIGNATURES'),
+                        input: this.getScriptSatisfaction(resolveMiniscriptSignatures())
+                            .scriptSatisfaction,
                         output: witnessScript
                     }
                 });
@@ -1080,8 +1193,24 @@ expansion=${expansion}, isPKH=${isPKH}, isWPKH=${isWPKH}, isSH=${isSH}, isTR=${i
                 4 * (40 + varSliceSize(payment.input)) +
                     //Segwit
                     vectorSize(payment.witness));
-                //when addr(SINGLE_KEY_ADDRESS) or tr(KEY) (single key):
-                //TODO: only single-key taproot outputs currently supported
+                // when tr(KEY,TREE): choose key-path or script-path based on
+                // constructor taprootSpendPath policy.
+            }
+            else if (expansion?.startsWith('tr(@0,')) {
+                if (!isSegwitTx)
+                    throw new Error('Should be SegwitTx');
+                if (taprootSpendPath === 'key')
+                    return 41 * 4 + (0, varuint_bitcoin_1.encodingLength)(1) + resolveTaprootSignatureSize();
+                const resolvedTapTreeInfo = __classPrivateFieldGet(this, _Output_tapTreeInfo, "f");
+                if (!resolvedTapTreeInfo)
+                    throw new Error(`Error: taproot tree info not available`);
+                const taprootSatisfaction = (0, tapMiniscript_1.satisfyTapTree)({
+                    tapTreeInfo: resolvedTapTreeInfo,
+                    preimages: __classPrivateFieldGet(this, _Output_preimages, "f"),
+                    signatures: resolveTaprootSignatures(),
+                    ...(tapLeaf !== undefined ? { tapLeaf } : {})
+                });
+                return 41 * 4 + taprootSatisfaction.totalWitnessSize;
             }
             else if (isTR && (!expansion || expansion === 'tr(@0)')) {
                 if (!isSegwitTx)
@@ -1089,8 +1218,8 @@ expansion=${expansion}, isPKH=${isPKH}, isWPKH=${isWPKH}, isSH=${isSH}, isTR=${i
                 return (
                 // Non-segwit: (txid:32) + (vout:4) + (sequence:4) + (script_len:1)
                 41 * 4 +
-                    // Segwit: (push_count:1) + (sig_length(1) + schnorr_sig(64): 65)
-                    (1 + 65));
+                    // Segwit: (push_count:1) + (sig_length(1) + schnorr_sig(64/65))
+                    ((0, varuint_bitcoin_1.encodingLength)(1) + resolveTaprootSignatureSize()));
             }
             else {
                 throw new Error(errorMsg);
@@ -1129,13 +1258,6 @@ expansion=${expansion}, isPKH=${isPKH}, isWPKH=${isWPKH}, isSH=${isSH}, isTR=${i
                 throw new Error(errorMsg);
             }
         }
-        /** @deprecated - Use updatePsbtAsInput instead
-         * @hidden
-         */
-        updatePsbt(params) {
-            this.updatePsbtAsInput(params);
-            return params.psbt.data.inputs.length - 1;
-        }
         /**
          * Sets this output as an input of the provided `psbt` and updates the
          * `psbt` locktime if required by the descriptor.
@@ -1163,6 +1285,10 @@ expansion=${expansion}, isPKH=${isPKH}, isWPKH=${isWPKH}, isSH=${isSH}, isTR=${i
          *
          * @returns A finalizer function to be used after signing the `psbt`.
          * This function ensures that this input is properly finalized.
+         * The finalizer completes the PSBT input by adding the unlocking script
+         * (`scriptWitness` or `scriptSig`) that satisfies this `Output`'s spending
+         * conditions. Because these scripts include signatures, you should finish
+         * all signing operations before calling the finalizer.
          * The finalizer has this signature:
          *
          * `( { psbt, validate = true } : { psbt: Psbt; validate: boolean | undefined } ) => void`
@@ -1170,6 +1296,10 @@ expansion=${expansion}, isPKH=${isPKH}, isWPKH=${isWPKH}, isSH=${isSH}, isTR=${i
          */
         updatePsbtAsInput({ psbt, txHex, txId, value, vout, //vector output index
         rbf = true }) {
+            if (value !== undefined && typeof value !== 'bigint')
+                throw new Error(`Error: value must be a bigint`);
+            if (value !== undefined && value < 0n)
+                throw new Error(`Error: value must be >= 0n`);
             if (txHex === undefined) {
                 console.warn(`Warning: missing txHex may allow fee attacks`);
             }
@@ -1183,15 +1313,46 @@ expansion=${expansion}, isPKH=${isPKH}, isWPKH=${isWPKH}, isSH=${isSH}, isTR=${i
                 //This should only happen when using addr() expressions
                 throw new Error(`Error: could not determine whether this is a taproot descriptor`);
             }
-            const index = (0, psbt_1.updatePsbt)({
+            const paymentInternalPubkey = this.getPayment().internalPubkey;
+            const tapInternalKey = isTaproot
+                ? paymentInternalPubkey
+                    ? paymentInternalPubkey
+                    : undefined
+                : undefined;
+            let tapLeafScript;
+            let tapBip32Derivation;
+            if (isTaproot && __classPrivateFieldGet(this, _Output_taprootSpendPath, "f") === 'script') {
+                const tapTreeInfo = __classPrivateFieldGet(this, _Output_tapTreeInfo, "f");
+                if (!tapTreeInfo)
+                    throw new Error(`Error: taprootSpendPath=script requires taproot tree info`);
+                if (!tapInternalKey)
+                    throw new Error(`Error: taprootSpendPath=script requires taproot internal key`);
+                const taprootLeafMetadata = (0, tapMiniscript_1.buildTaprootLeafPsbtMetadata)({
+                    tapTreeInfo,
+                    internalPubkey: tapInternalKey
+                });
+                tapLeafScript = taprootLeafMetadata.map(({ leaf, controlBlock }) => ({
+                    script: leaf.tapScript,
+                    leafVersion: leaf.version,
+                    controlBlock
+                }));
+                const internalKeyInfo = __classPrivateFieldGet(this, _Output_expansionMap, "f")?.['@0'];
+                if (!internalKeyInfo)
+                    throw new Error(`Error: taproot internal key info not available in expansionMap`);
+                tapBip32Derivation = (0, tapMiniscript_1.buildTaprootBip32Derivations)({
+                    tapTreeInfo,
+                    internalKeyInfo
+                });
+            }
+            const index = (0, psbt_1.addPsbtInput)({
                 psbt,
                 vout,
                 ...(txHex !== undefined ? { txHex } : {}),
                 ...(txId !== undefined ? { txId } : {}),
                 ...(value !== undefined ? { value } : {}),
-                ...(isTaproot
-                    ? { tapInternalKey: this.getPayment().internalPubkey }
-                    : {}),
+                tapInternalKey,
+                tapLeafScript,
+                tapBip32Derivation,
                 sequence: this.getSequence(),
                 locktime: this.getLockTime(),
                 keysInfo: __classPrivateFieldGet(this, _Output_expansionMap, "f") ? Object.values(__classPrivateFieldGet(this, _Output_expansionMap, "f")) : [],
@@ -1201,7 +1362,64 @@ expansion=${expansion}, isPKH=${isPKH}, isWPKH=${isWPKH}, isSH=${isSH}, isTR=${i
                 redeemScript: this.getRedeemScript(),
                 rbf
             });
-            const finalizer = ({ psbt, validate = true }) => this.finalizePsbtInput({ index, psbt, validate });
+            //The finalizer adds the unlocking script (scriptSig/scriptWitness) once
+            //signatures are ready.
+            const finalizer = ({ psbt, validate = true }) => {
+                if (validate &&
+                    !psbt.validateSignaturesOfInput(index, signatureValidator)) {
+                    throw new Error(`Error: invalid signatures on input ${index}`);
+                }
+                //An index must be passed since finding the index in the psbt cannot be
+                //done:
+                //Imagine the case where you received money twice to
+                //the same miniscript-based address. You would have the same scriptPubKey,
+                //same sequences, ... The descriptor does not store the hash of the previous
+                //transaction since it is a general Output instance. Indices must be kept
+                //out of the scope of this class and then passed.
+                __classPrivateFieldGet(this, _Output_instances, "m", _Output_assertPsbtInput).call(this, { index, psbt });
+                if (__classPrivateFieldGet(this, _Output_isTaproot, "f") &&
+                    __classPrivateFieldGet(this, _Output_taprootSpendPath, "f") === 'script' &&
+                    !__classPrivateFieldGet(this, _Output_tapTreeInfo, "f"))
+                    throw new Error(`Error: taprootSpendPath=script requires taproot tree info`);
+                if (__classPrivateFieldGet(this, _Output_tapTreeInfo, "f") && __classPrivateFieldGet(this, _Output_taprootSpendPath, "f") === 'script') {
+                    const input = psbt.data.inputs[index];
+                    const tapLeafScript = input?.tapLeafScript;
+                    if (!tapLeafScript || tapLeafScript.length === 0)
+                        throw new Error(`Error: cannot finalize taproot script-path without tapLeafScript`);
+                    const tapScriptSig = input?.tapScriptSig;
+                    if (!tapScriptSig || tapScriptSig.length === 0)
+                        throw new Error(`Error: cannot finalize taproot script-path without tapScriptSig`);
+                    const taprootSatisfaction = this.getTapScriptSatisfaction(tapScriptSig);
+                    const matchingLeaf = tapLeafScript.find(leafScript => (0, uint8array_tools_1.compare)((0, bitcoinjs_lib_internals_1.tapleafHash)({
+                        output: leafScript.script,
+                        version: leafScript.leafVersion
+                    }), taprootSatisfaction.tapLeafHash) === 0);
+                    if (!matchingLeaf)
+                        throw new Error(`Error: tapLeafScript does not match planned tapLeafHash`);
+                    if ((0, uint8array_tools_1.compare)(matchingLeaf.script, taprootSatisfaction.leaf.tapScript) !==
+                        0 ||
+                        matchingLeaf.leafVersion !== taprootSatisfaction.leaf.version)
+                        throw new Error(`Error: tapLeafScript does not match planned leaf script`);
+                    const witness = [
+                        ...taprootSatisfaction.stackItems,
+                        matchingLeaf.script,
+                        matchingLeaf.controlBlock
+                    ];
+                    const finalScriptWitness = (0, bitcoinjs_lib_internals_1.witnessStackToScriptWitness)(witness);
+                    psbt.finalizeTaprootInput(index, taprootSatisfaction.tapLeafHash, () => ({ finalScriptWitness }));
+                }
+                else if (!__classPrivateFieldGet(this, _Output_miniscript, "f")) {
+                    //Use standard finalizers
+                    psbt.finalizeInput(index);
+                }
+                else {
+                    const signatures = psbt.data.inputs[index]?.partialSig;
+                    if (!signatures)
+                        throw new Error(`Error: cannot finalize without signatures`);
+                    const { scriptSatisfaction } = this.getScriptSatisfaction(signatures);
+                    psbt.finalizeInput(index, (0, psbt_1.finalScriptsFuncFactory)(scriptSatisfaction, __classPrivateFieldGet(this, _Output_network, "f")));
+                }
+            };
             return finalizer;
         }
         /**
@@ -1212,63 +1430,12 @@ expansion=${expansion}, isPKH=${isPKH}, isWPKH=${isWPKH}, isSH=${isSH}, isTR=${i
          * @param params.value - The value for the output in satoshis.
          */
         updatePsbtAsOutput({ psbt, value }) {
+            if (typeof value !== 'bigint')
+                throw new Error(`Error: value must be a bigint`);
+            if (value < 0n)
+                throw new Error(`Error: value must be >= 0n`);
             psbt.addOutput({ script: this.getScriptPubKey(), value });
         }
-        /**
-         * Finalizes a PSBT input by adding the necessary unlocking script that satisfies this `Output`'s
-         * spending conditions.
-         *
-         * 🔴 IMPORTANT 🔴
-         * It is STRONGLY RECOMMENDED to use the finalizer function returned by
-         * {@link _Internal_.Output.updatePsbtAsInput | `updatePsbtAsInput`} instead
-         * of calling this method directly.
-         * This approach eliminates the need to manage the `Output` instance and the
-         * input's index, simplifying the process.
-         *
-         * The `finalizePsbtInput` method completes a PSBT input by adding the
-         * unlocking script (`scriptWitness` or `scriptSig`) that satisfies
-         * this `Output`'s spending conditions. Bear in mind that both
-         * `scriptSig` and `scriptWitness` incorporate signatures. As such, you
-         * should complete all necessary signing operations before calling this
-         * method.
-         *
-         * For each unspent output from a previous transaction that you're
-         * referencing in a `psbt` as an input to be spent, apply this method as
-         * follows: `output.finalizePsbtInput({ index, psbt })`.
-         *
-         * It's essential to specify the exact position (or `index`) of the input in
-         * the `psbt` that references this unspent `Output`. This `index` should
-         * align with the value returned by the `updatePsbtAsInput` method.
-         * Note:
-         * The `index` corresponds to the position of the input in the `psbt`.
-         * To get this index, right after calling `updatePsbtAsInput()`, use:
-         * `index = psbt.data.inputs.length - 1`.
-         */
-        finalizePsbtInput({ index, psbt, validate = true }) {
-            if (validate &&
-                !psbt.validateSignaturesOfInput(index, signatureValidator)) {
-                throw new Error(`Error: invalid signatures on input ${index}`);
-            }
-            //An index must be passed since finding the index in the psbt cannot be
-            //done:
-            //Imagine the case where you received money twice to
-            //the same miniscript-based address. You would have the same scriptPubKey,
-            //same sequences, ... The descriptor does not store the hash of the previous
-            //transaction since it is a general Descriptor object. Indices must be kept
-            //out of the scope of this class and then passed.
-            __classPrivateFieldGet(this, _Output_instances, "m", _Output_assertPsbtInput).call(this, { index, psbt });
-            if (!__classPrivateFieldGet(this, _Output_miniscript, "f")) {
-                //Use standard finalizers
-                psbt.finalizeInput(index);
-            }
-            else {
-                const signatures = psbt.data.inputs[index]?.partialSig;
-                if (!signatures)
-                    throw new Error(`Error: cannot finalize without signatures`);
-                const scriptSatisfaction = this.getScriptSatisfaction(signatures);
-                psbt.finalizeInput(index, (0, psbt_1.finalScriptsFuncFactory)(scriptSatisfaction, __classPrivateFieldGet(this, _Output_network, "f")));
-            }
-        }
         /**
          * Decomposes the descriptor used to form this `Output` into its elemental
          * parts. See {@link ExpansionMap ExpansionMap} for a detailed explanation.
@@ -1284,18 +1451,80 @@ expansion=${expansion}, isPKH=${isPKH}, isWPKH=${isWPKH}, isSH=${isSH}, isTR=${i
                 ...(__classPrivateFieldGet(this, _Output_expandedMiniscript, "f") !== undefined
                     ? { expandedMiniscript: __classPrivateFieldGet(this, _Output_expandedMiniscript, "f") }
                     : {}),
+                ...(__classPrivateFieldGet(this, _Output_tapTreeExpression, "f") !== undefined
+                    ? { tapTreeExpression: __classPrivateFieldGet(this, _Output_tapTreeExpression, "f") }
+                    : {}),
+                ...(__classPrivateFieldGet(this, _Output_tapTree, "f") !== undefined ? { tapTree: __classPrivateFieldGet(this, _Output_tapTree, "f") } : {}),
+                ...(__classPrivateFieldGet(this, _Output_tapTreeInfo, "f") !== undefined
+                    ? { tapTreeInfo: __classPrivateFieldGet(this, _Output_tapTreeInfo, "f") }
+                    : {}),
                 ...(__classPrivateFieldGet(this, _Output_expansionMap, "f") !== undefined
                     ? { expansionMap: __classPrivateFieldGet(this, _Output_expansionMap, "f") }
                     : {})
             };
         }
     }
-    _Output_payment = new WeakMap(), _Output_preimages = new WeakMap(), _Output_signersPubKeys = new WeakMap(), _Output_miniscript = new WeakMap(), _Output_witnessScript = new WeakMap(), _Output_redeemScript = new WeakMap(), _Output_isSegwit = new WeakMap(), _Output_isTaproot = new WeakMap(), _Output_expandedExpression = new WeakMap(), _Output_expandedMiniscript = new WeakMap(), _Output_expansionMap = new WeakMap(), _Output_network = new WeakMap(), _Output_instances = new WeakSet(), _Output_getTimeConstraints = function _Output_getTimeConstraints() {
+    _Output_payment = new WeakMap(), _Output_preimages = new WeakMap(), _Output_signersPubKeys = new WeakMap(), _Output_miniscript = new WeakMap(), _Output_witnessScript = new WeakMap(), _Output_redeemScript = new WeakMap(), _Output_isSegwit = new WeakMap(), _Output_isTaproot = new WeakMap(), _Output_expandedExpression = new WeakMap(), _Output_expandedMiniscript = new WeakMap(), _Output_tapTreeExpression = new WeakMap(), _Output_tapTree = new WeakMap(), _Output_tapTreeInfo = new WeakMap(), _Output_taprootSpendPath = new WeakMap(), _Output_tapLeaf = new WeakMap(), _Output_expansionMap = new WeakMap(), _Output_network = new WeakMap(), _Output_instances = new WeakSet(), _Output_resolveMiniscriptSignersPubKeys = function _Output_resolveMiniscriptSignersPubKeys() {
+        //If the user did not provide a pubkey subset (signersPubKeys), assume all
+        //miniscript pubkeys can sign.
+        if (__classPrivateFieldGet(this, _Output_signersPubKeys, "f"))
+            return __classPrivateFieldGet(this, _Output_signersPubKeys, "f");
+        const expansionMap = __classPrivateFieldGet(this, _Output_expansionMap, "f");
+        if (!expansionMap)
+            throw new Error(`Error: expansionMap not available for miniscript`);
+        return Object.values(expansionMap).map(keyInfo => {
+            const pubkey = keyInfo.pubkey;
+            if (!pubkey)
+                throw new Error(`Error: miniscript key missing pubkey`);
+            return pubkey;
+        });
+    }, _Output_assertMiniscriptSatisfactionResourceLimits = function _Output_assertMiniscriptSatisfactionResourceLimits(scriptSatisfaction) {
+        if (!__classPrivateFieldGet(this, _Output_miniscript, "f"))
+            return;
+        const satisfactionStackItems = bitcoinjs_lib_1.script.toStack(scriptSatisfaction);
+        // For wsh(...) and sh(wsh(...)), enforce witness stack limits.
+        if (__classPrivateFieldGet(this, _Output_isSegwit, "f") && !__classPrivateFieldGet(this, _Output_isTaproot, "f")) {
+            (0, resourceLimits_1.assertWitnessV0SatisfactionResourceLimits)({
+                stackItems: satisfactionStackItems
+            });
+            return;
+        }
+        if (!__classPrivateFieldGet(this, _Output_isSegwit, "f")) {
+            // In legacy P2SH, after scriptSig execution, the stack is:
+            //   [ ...satisfactionStackItems, redeemScript ]
+            // Consensus limits apply here: each element must be <= 520 bytes and total
+            // stack items must be <= 1000.
+            // redeemScript size is already validated during script construction
+            // to fail early (look for MAX_SCRIPT_ELEMENT_SIZE checks in this file).
+            // Below we re-validate again the redeemScript + the rest of stack items.
+            const redeemScript = __classPrivateFieldGet(this, _Output_redeemScript, "f");
+            if (!redeemScript)
+                throw new Error(`Error: redeemScript not available for P2SH spend`);
+            (0, resourceLimits_1.assertConsensusStackResourceLimits)({
+                stackItems: [...satisfactionStackItems, redeemScript]
+            });
+            (0, resourceLimits_1.assertP2shScriptSigStandardSize)({
+                scriptSatisfaction,
+                redeemScript,
+                network: __classPrivateFieldGet(this, _Output_network, "f")
+            });
+        }
+    }, _Output_resolveTapTreeSignersPubKeys = function _Output_resolveTapTreeSignersPubKeys() {
+        //If the user did not provide a pubkey subset (signersPubKeys), assume all
+        //taproot leaf pubkeys can sign.
+        const tapTreeInfo = __classPrivateFieldGet(this, _Output_tapTreeInfo, "f");
+        if (!tapTreeInfo)
+            throw new Error(`Error: taproot tree info not available`);
+        const candidatePubkeys = __classPrivateFieldGet(this, _Output_signersPubKeys, "f")
+            ? __classPrivateFieldGet(this, _Output_signersPubKeys, "f").map(tapMiniscript_1.normalizeTaprootPubkey)
+            : (0, tapMiniscript_1.collectTapTreePubkeys)(tapTreeInfo);
+        return Array.from(new Set(candidatePubkeys.map(pubkey => (0, uint8array_tools_1.toHex)(pubkey)))).map(hex => (0, uint8array_tools_1.fromHex)(hex));
+    }, _Output_getConstraints = function _Output_getConstraints() {
         const miniscript = __classPrivateFieldGet(this, _Output_miniscript, "f");
         const preimages = __classPrivateFieldGet(this, _Output_preimages, "f");
         const expandedMiniscript = __classPrivateFieldGet(this, _Output_expandedMiniscript, "f");
         const expansionMap = __classPrivateFieldGet(this, _Output_expansionMap, "f");
-        const signersPubKeys = __classPrivateFieldGet(this, _Output_signersPubKeys, "f");
+        const tapTreeInfo = __classPrivateFieldGet(this, _Output_tapTreeInfo, "f");
         //Create a method. solvePreimages to solve them.
         if (miniscript) {
             if (expandedMiniscript === undefined || expansionMap === undefined)
@@ -1303,21 +1532,34 @@ expansion=${expansion}, isPKH=${isPKH}, isWPKH=${isWPKH}, isSH=${isSH}, isTR=${i
             //We create some fakeSignatures since we may not have them yet.
             //We only want to retrieve the nLockTime and nSequence of the satisfaction and
             //signatures don't matter
-            const fakeSignatures = signersPubKeys.map(pubkey => ({
+            const fakeSignatures = __classPrivateFieldGet(this, _Output_instances, "m", _Output_resolveMiniscriptSignersPubKeys).call(this).map(pubkey => ({
                 pubkey,
-                // https://transactionfee.info/charts/bitcoin-script-ecdsa-length/
-                signature: Buffer.alloc(72, 0)
+                signature: new Uint8Array(ECDSA_FAKE_SIGNATURE_SIZE)
             }));
-            const { nLockTime, nSequence } = (0, miniscript_1.satisfyMiniscript)({
+            const satisfaction = (0, miniscript_1.satisfyMiniscript)({
                 expandedMiniscript,
                 expansionMap,
                 signatures: fakeSignatures,
                 preimages
             });
-            return { nLockTime, nSequence };
+            __classPrivateFieldGet(this, _Output_instances, "m", _Output_assertMiniscriptSatisfactionResourceLimits).call(this, satisfaction.scriptSatisfaction);
+            const { nLockTime, nSequence } = satisfaction;
+            return { nLockTime, nSequence, tapLeafHash: undefined };
         }
-        else
-            return undefined;
+        else if (tapTreeInfo && __classPrivateFieldGet(this, _Output_taprootSpendPath, "f") === 'script') {
+            const fakeSignatures = __classPrivateFieldGet(this, _Output_instances, "m", _Output_resolveTapTreeSignersPubKeys).call(this).map(pubkey => ({
+                pubkey,
+                signature: new Uint8Array(TAPROOT_FAKE_SIGNATURE_SIZE)
+            }));
+            const { nLockTime, nSequence, tapLeafHash } = (0, tapMiniscript_1.satisfyTapTree)({
+                tapTreeInfo,
+                preimages: __classPrivateFieldGet(this, _Output_preimages, "f"),
+                signatures: fakeSignatures,
+                ...(__classPrivateFieldGet(this, _Output_tapLeaf, "f") !== undefined ? { tapLeaf: __classPrivateFieldGet(this, _Output_tapLeaf, "f") } : {})
+            });
+            return { nLockTime, nSequence, tapLeafHash };
+        }
+        return undefined;
     }, _Output_assertPsbtInput = function _Output_assertPsbtInput({ psbt, index }) {
         const input = psbt.data.inputs[index];
         const txInput = psbt.txInputs[index];
@@ -1346,29 +1588,18 @@ expansion=${expansion}, isPKH=${isPKH}, isWPKH=${isWPKH}, isSH=${isSH}, isTR=${i
                 ? 0xffffffff
                 : 0xfffffffe;
         const sequenceRBF = sequence !== undefined ? sequence : 0xfffffffd;
-        const eqBuffers = (buf1, buf2) => buf1 instanceof Buffer && buf2 instanceof Buffer
-            ? Buffer.compare(buf1, buf2) === 0
-            : buf1 === buf2;
-        if (Buffer.compare(scriptPubKey, this.getScriptPubKey()) !== 0 ||
+        const eqBytes = (bytes1, bytes2) => bytes1 === undefined || bytes2 === undefined
+            ? bytes1 === bytes2
+            : (0, uint8array_tools_1.compare)(bytes1, bytes2) === 0;
+        if ((0, uint8array_tools_1.compare)(scriptPubKey, this.getScriptPubKey()) !== 0 ||
             (sequenceRBF !== inputSequence && sequenceNoRBF !== inputSequence) ||
             locktime !== psbt.locktime ||
-            !eqBuffers(this.getWitnessScript(), input.witnessScript) ||
-            !eqBuffers(this.getRedeemScript(), input.redeemScript)) {
+            !eqBytes(this.getWitnessScript(), input.witnessScript) ||
+            !eqBytes(this.getRedeemScript(), input.redeemScript)) {
             throw new Error(`Error: cannot finalize psbt index ${index} since it does not correspond to this descriptor`);
         }
     };
-    /**
-     * @hidden
-     * @deprecated Use `Output` instead
-     */
-    class Descriptor extends Output {
-        constructor({ expression, ...rest }) {
-            super({ descriptor: expression, ...rest });
-        }
-    }
     return {
-        // deprecated TAG must also be below so it is exported to descriptors.d.ts
-        /** @deprecated @hidden */ Descriptor,
         Output,
         parseKeyExpression,
         expand,