@bitcoinerlab/descriptors 1.0.2 → 2.0.0

package/dist/descriptors.js

@@ -60,49 +60,72 @@ function countNonPushOnlyOPs(script) {
 /*
  * Returns a bare descriptor without checksum and particularized for a certain
  * index (if desc was a range descriptor)
+ * @hidden
  */
-function evaluate({ expression, checksumRequired, index }) {
-    const mChecksum = expression.match(String.raw `(${RE.reChecksum})$`);
+function evaluate({ descriptor, checksumRequired, index }) {
+    if (!descriptor)
+        throw new Error('You must provide a descriptor.');
+    const mChecksum = descriptor.match(String.raw `(${RE.reChecksum})$`);
     if (mChecksum === null && checksumRequired === true)
-        throw new Error(`Error: descriptor ${expression} has not checksum`);
-    //evaluatedExpression: a bare desc without checksum and particularized for a certain
+        throw new Error(`Error: descriptor ${descriptor} has not checksum`);
+    //evaluatedDescriptor: a bare desc without checksum and particularized for a certain
     //index (if desc was a range descriptor)
-    let evaluatedExpression = expression;
+    let evaluatedDescriptor = descriptor;
     if (mChecksum !== null) {
         const checksum = mChecksum[0].substring(1); //remove the leading #
-        evaluatedExpression = expression.substring(0, expression.length - mChecksum[0].length);
-        if (checksum !== (0, checksum_1.DescriptorChecksum)(evaluatedExpression)) {
-            throw new Error(`Error: invalid descriptor checksum for ${expression}`);
+        evaluatedDescriptor = descriptor.substring(0, descriptor.length - mChecksum[0].length);
+        if (checksum !== (0, checksum_1.DescriptorChecksum)(evaluatedDescriptor)) {
+            throw new Error(`Error: invalid descriptor checksum for ${descriptor}`);
         }
     }
     if (index !== undefined) {
-        const mWildcard = evaluatedExpression.match(/\*/g);
+        const mWildcard = evaluatedDescriptor.match(/\*/g);
         if (mWildcard && mWildcard.length > 0) {
             //From  https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md
             //To prevent a combinatorial explosion of the search space, if more than
             //one of the multi() key arguments is a BIP32 wildcard path ending in /* or
-            //*', the multi() expression only matches multisig scripts with the ith
+            //*', the multi() descriptor only matches multisig scripts with the ith
             //child key from each wildcard path in lockstep, rather than scripts with
             //any combination of child keys from each wildcard path.
             //We extend this reasoning for musig for all cases
-            evaluatedExpression = evaluatedExpression.replaceAll('*', index.toString());
+            evaluatedDescriptor = evaluatedDescriptor.replaceAll('*', index.toString());
         }
         else
-            throw new Error(`Error: index passed for non-ranged descriptor: ${expression}`);
+            throw new Error(`Error: index passed for non-ranged descriptor: ${descriptor}`);
     }
-    return evaluatedExpression;
+    return evaluatedDescriptor;
 }
 /**
- * Builds the functions needed to operate with descriptors using an external elliptic curve (ecc) library.
- * @param {Object} ecc - an object containing elliptic curve operations, such as [tiny-secp256k1](https://github.com/bitcoinjs/tiny-secp256k1) or [@bitcoinerlab/secp256k1](https://github.com/bitcoinerlab/secp256k1).
- * @namespace
+ * Constructs the necessary functions and classes for working with descriptors
+ * using an external elliptic curve (ecc) library.
+ *
+ * Notably, it returns the {@link _Internal_.Output | `Output`} class, which
+ * 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}).
+ *
+ * Additionally, for convenience, the function returns `BIP32` and `ECPair`.
+ * These are {@link https://github.com/bitcoinjs bitcoinjs-lib} classes designed
+ * for managing {@link https://github.com/bitcoinjs/bip32 | `BIP32`} keys and
+ * public/private key pairs:
+ * {@link https://github.com/bitcoinjs/ecpair | `ECPair`}, respectively.
+ *
+ * @param {Object} ecc - An object with elliptic curve operations, such as
+ * [tiny-secp256k1](https://github.com/bitcoinjs/tiny-secp256k1) or
+ * [@bitcoinerlab/secp256k1](https://github.com/bitcoinerlab/secp256k1).
  */
 function DescriptorsFactory(ecc) {
-    var _Descriptor_instances, _Descriptor_payment, _Descriptor_preimages, _Descriptor_signersPubKeys, _Descriptor_miniscript, _Descriptor_witnessScript, _Descriptor_redeemScript, _Descriptor_isSegwit, _Descriptor_expandedExpression, _Descriptor_expandedMiniscript, _Descriptor_expansionMap, _Descriptor_network, _Descriptor_getTimeConstraints, _Descriptor_assertPsbtInput;
+    var _Output_instances, _Output_payment, _Output_preimages, _Output_signersPubKeys, _Output_miniscript, _Output_witnessScript, _Output_redeemScript, _Output_isSegwit, _Output_expandedExpression, _Output_expandedMiniscript, _Output_expansionMap, _Output_network, _Output_getTimeConstraints, _Output_assertPsbtInput;
     const BIP32 = (0, bip32_1.BIP32Factory)(ecc);
     const ECPair = (0, ecpair_1.ECPairFactory)(ecc);
     const signatureValidator = (pubkey, msghash, signature) => ECPair.fromPublicKey(pubkey).verify(msghash, signature);
-    /*
+    /**
      * Takes a string key expression (xpub, xprv, pubkey or wif) and parses it
      */
     const parseKeyExpression = ({ keyExpression, isSegwit, network = bitcoinjs_lib_1.networks.bitcoin }) => {
@@ -115,32 +138,16 @@ function DescriptorsFactory(ecc) {
         });
     };
     /**
-     * Takes a descriptor (expression) and expands it to its corresponding Bitcoin script and other relevant details.
-     *
-     * @param {Object} params The parameters for the function.
-     * @param {string} params.expression The descriptor expression to be expanded.
-     * @param {string} [params.loggedExpression] The descriptor expression used for logging error messages. If not provided, defaults to the original expression.
-     * @param {Object} [params.network=networks.bitcoin] The Bitcoin network to use. If not provided, defaults to Bitcoin mainnet.
-     * @param {boolean} [params.allowMiniscriptInP2SH=false] Flag to allow miniscript in P2SH. If not provided, defaults to false.
-     *
-     * @returns {Object} An object containing various details about the expanded descriptor:
-     *     - payment: The corresponding [bitcoinjs-lib Payment](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/ts_src/payments/index.ts) for the provided expression, if applicable.
-     *     - expandedExpression: The expanded descriptor expression.
-     *     - miniscript: The extracted miniscript from the expression, if any.
-     *     - expansionMap: A map of key expressions in the descriptor to their corresponding expanded keys.
-     *     - isSegwit: A boolean indicating whether the descriptor represents a SegWit script.
-     *     - expandedMiniscript: The expanded miniscript, if any.
-     *     - redeemScript: The redeem script for the descriptor, if applicable.
-     *     - witnessScript: The witness script for the descriptor, if applicable.
-     *     - isRanged: Whether this expression representas a ranged-descriptor
-     *     - canonicalExpression: This is the preferred or authoritative
-     *     representation of the descriptor expression. It standardizes the
-     *     descriptor by replacing indexes on wildcards and eliminating checksums.
-     *     This helps ensure consistency and facilitates efficient interpretation and handling by systems or software.
-     *
-     * @throws {Error} Throws an error if the descriptor cannot be parsed or does not conform to the expected format.
+     * @hidden
+     * To be removed in v3.0 and replaced by the version with the signature that
+     * does not accept descriptors
      */
-    const expand = ({ expression, index, checksumRequired = false, network = bitcoinjs_lib_1.networks.bitcoin, allowMiniscriptInP2SH = false }) => {
+    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;
+        if (!descriptor)
+            throw new Error(`descriptor not provided`);
         let expandedExpression;
         let miniscript;
         let expansionMap;
@@ -149,14 +156,14 @@ function DescriptorsFactory(ecc) {
         let payment;
         let witnessScript;
         let redeemScript;
-        const isRanged = expression.indexOf('*') !== -1;
+        const isRanged = descriptor.indexOf('*') !== -1;
         if (index !== undefined)
             if (!Number.isInteger(index) || index < 0)
                 throw new Error(`Error: invalid index ${index}`);
         //Verify and remove checksum (if exists) and
         //particularize range descriptor for index (if desc is range descriptor)
         const canonicalExpression = evaluate({
-            expression,
+            descriptor,
             ...(index !== undefined ? { index } : {}),
             checksumRequired
         });
@@ -167,7 +174,7 @@ function DescriptorsFactory(ecc) {
                 throw new Error(`Error: addr() cannot be ranged`);
             const matchedAddress = canonicalExpression.match(RE.reAddrAnchored)?.[1]; //[1]-> whatever is found addr(->HERE<-)
             if (!matchedAddress)
-                throw new Error(`Error: could not get an address in ${expression}`);
+                throw new Error(`Error: could not get an address in ${descriptor}`);
             let output;
             try {
                 output = bitcoinjs_lib_1.address.toOutputScript(matchedAddress, network);
@@ -206,7 +213,7 @@ function DescriptorsFactory(ecc) {
             if (!keyExpression)
                 throw new Error(`Error: keyExpression could not me extracted`);
             if (canonicalExpression !== `pk(${keyExpression})`)
-                throw new Error(`Error: invalid expression ${expression}`);
+                throw new Error(`Error: invalid expression ${descriptor}`);
             expandedExpression = 'pk(@0)';
             const pKE = parseKeyExpression({ keyExpression, network, isSegwit });
             expansionMap = { '@0': pKE };
@@ -214,7 +221,7 @@ function DescriptorsFactory(ecc) {
                 const pubkey = pKE.pubkey;
                 //Note there exists no address for p2pk, but we can still use the script
                 if (!pubkey)
-                    throw new Error(`Error: could not extract a pubkey from ${expression}`);
+                    throw new Error(`Error: could not extract a pubkey from ${descriptor}`);
                 payment = p2pk({ pubkey, network });
             }
         }
@@ -225,14 +232,14 @@ function DescriptorsFactory(ecc) {
             if (!keyExpression)
                 throw new Error(`Error: keyExpression could not me extracted`);
             if (canonicalExpression !== `pkh(${keyExpression})`)
-                throw new Error(`Error: invalid expression ${expression}`);
+                throw new Error(`Error: invalid expression ${descriptor}`);
             expandedExpression = 'pkh(@0)';
             const pKE = parseKeyExpression({ keyExpression, network, isSegwit });
             expansionMap = { '@0': pKE };
             if (!isCanonicalRanged) {
                 const pubkey = pKE.pubkey;
                 if (!pubkey)
-                    throw new Error(`Error: could not extract a pubkey from ${expression}`);
+                    throw new Error(`Error: could not extract a pubkey from ${descriptor}`);
                 payment = p2pkh({ pubkey, network });
             }
         }
@@ -243,18 +250,18 @@ function DescriptorsFactory(ecc) {
             if (!keyExpression)
                 throw new Error(`Error: keyExpression could not me extracted`);
             if (canonicalExpression !== `sh(wpkh(${keyExpression}))`)
-                throw new Error(`Error: invalid expression ${expression}`);
+                throw new Error(`Error: invalid expression ${descriptor}`);
             expandedExpression = 'sh(wpkh(@0))';
             const pKE = parseKeyExpression({ keyExpression, network, isSegwit });
             expansionMap = { '@0': pKE };
             if (!isCanonicalRanged) {
                 const pubkey = pKE.pubkey;
                 if (!pubkey)
-                    throw new Error(`Error: could not extract a pubkey from ${expression}`);
+                    throw new Error(`Error: could not extract a pubkey from ${descriptor}`);
                 payment = p2sh({ redeem: p2wpkh({ pubkey, network }), network });
                 redeemScript = payment.redeem?.output;
                 if (!redeemScript)
-                    throw new Error(`Error: could not calculate redeemScript for ${expression}`);
+                    throw new Error(`Error: could not calculate redeemScript for ${descriptor}`);
             }
         }
         //wpkh(KEY) - native segwit
@@ -264,14 +271,14 @@ function DescriptorsFactory(ecc) {
             if (!keyExpression)
                 throw new Error(`Error: keyExpression could not me extracted`);
             if (canonicalExpression !== `wpkh(${keyExpression})`)
-                throw new Error(`Error: invalid expression ${expression}`);
+                throw new Error(`Error: invalid expression ${descriptor}`);
             expandedExpression = 'wpkh(@0)';
             const pKE = parseKeyExpression({ keyExpression, network, isSegwit });
             expansionMap = { '@0': pKE };
             if (!isCanonicalRanged) {
                 const pubkey = pKE.pubkey;
                 if (!pubkey)
-                    throw new Error(`Error: could not extract a pubkey from ${expression}`);
+                    throw new Error(`Error: could not extract a pubkey from ${descriptor}`);
                 payment = p2wpkh({ pubkey, network });
             }
         }
@@ -280,7 +287,7 @@ function DescriptorsFactory(ecc) {
             isSegwit = true;
             miniscript = canonicalExpression.match(RE.reShWshMiniscriptAnchored)?.[1]; //[1]-> whatever is found sh(wsh(->HERE<-))
             if (!miniscript)
-                throw new Error(`Error: could not get miniscript in ${expression}`);
+                throw new Error(`Error: could not get miniscript in ${descriptor}`);
             ({ expandedMiniscript, expansionMap } = expandMiniscript({
                 miniscript,
                 isSegwit,
@@ -303,7 +310,7 @@ function DescriptorsFactory(ecc) {
                 });
                 redeemScript = payment.redeem?.output;
                 if (!redeemScript)
-                    throw new Error(`Error: could not calculate redeemScript for ${expression}`);
+                    throw new Error(`Error: could not calculate redeemScript for ${descriptor}`);
             }
         }
         //sh(miniscript)
@@ -313,7 +320,7 @@ function DescriptorsFactory(ecc) {
             isSegwit = false;
             miniscript = canonicalExpression.match(RE.reShMiniscriptAnchored)?.[1]; //[1]-> whatever is found sh(->HERE<-)
             if (!miniscript)
-                throw new Error(`Error: could not get miniscript in ${expression}`);
+                throw new Error(`Error: could not get miniscript in ${descriptor}`);
             if (allowMiniscriptInP2SH === false &&
                 //These top-level expressions within sh are allowed within sh.
                 //They can be parsed with miniscript2Script, but first we must make sure
@@ -345,7 +352,7 @@ function DescriptorsFactory(ecc) {
             isSegwit = true;
             miniscript = canonicalExpression.match(RE.reWshMiniscriptAnchored)?.[1]; //[1]-> whatever is found wsh(->HERE<-)
             if (!miniscript)
-                throw new Error(`Error: could not get miniscript in ${expression}`);
+                throw new Error(`Error: could not get miniscript in ${descriptor}`);
             ({ expandedMiniscript, expansionMap } = expandMiniscript({
                 miniscript,
                 isSegwit,
@@ -366,7 +373,7 @@ function DescriptorsFactory(ecc) {
             }
         }
         else {
-            throw new Error(`Error: Could not parse descriptor ${expression}`);
+            throw new Error(`Error: Could not parse descriptor ${descriptor}`);
         }
         return {
             ...(payment !== undefined ? { payment } : {}),
@@ -380,7 +387,7 @@ function DescriptorsFactory(ecc) {
             isRanged,
             canonicalExpression
         };
-    };
+    }
     /**
      * Expand a miniscript to a generalized form using variables instead of key
      * expressions. Variables will be of this form: @0, @1, ...
@@ -397,40 +404,38 @@ function DescriptorsFactory(ecc) {
             ECPair
         });
     }
-    class Descriptor {
+    /**
+     * The `Output` class is the central component for managing descriptors.
+     * It facilitates the creation of outputs to receive funds and enables the
+     * signing and finalization of PSBTs (Partially Signed Bitcoin Transactions)
+     * for spending UTXOs (Unspent Transaction Outputs).
+     */
+    class Output {
         /**
-         * @param {DescriptorInfo} params
-         * @param {string} params.expression - The descriptor string in ASCII format. It may include a "*" to denote an arbitrary index.
-         * @param {number} params.index - The descriptor's index in the case of a range descriptor (must be an interger >=0).
-         * @param {boolean} [params.checksumRequired=false] - A flag indicating whether the descriptor is required to include a checksum.
-         * @param {boolean} [params.allowMiniscriptInP2SH=false] - A flag indicating whether this instance can parse and generate script satisfactions for sh(miniscript) top-level expressions of miniscripts. This is not recommended.
-         * @param {object} [params.network=networks.bitcoin] One of bitcoinjs-lib [`networks`](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/src/networks.js) (or another one following the same interface).
-         * @param {Preimage[]} [params.preimages=[]] An array of preimages. This info is necessary to finalize Psbts.
-         * @param {Buffer[]} [params.signersPubKeys] (Optional): An array of the public keys used for signing the transaction when spending the output associated with this descriptor. This parameter is only used if the descriptor object is being used to finalize a transaction. It is necessary to specify the spending path when working with miniscript-based expressions that have multiple spending paths. Set this parameter to an array containing the public keys involved in the desired spending path. Leave it `undefined` if you only need to generate the `scriptPubKey` or `address` for a descriptor, or if all the public keys involved in the descriptor will sign the transaction. In the latter case, the satisfier will automatically choose the most optimal spending path (if more than one is available).
-         *
+         * @param options
          * @throws {Error} - when descriptor is invalid
          */
-        constructor({ expression, index, checksumRequired = false, allowMiniscriptInP2SH = false, network = bitcoinjs_lib_1.networks.bitcoin, preimages = [], signersPubKeys }) {
-            _Descriptor_instances.add(this);
-            _Descriptor_payment.set(this, void 0);
-            _Descriptor_preimages.set(this, []);
-            _Descriptor_signersPubKeys.set(this, void 0);
-            _Descriptor_miniscript.set(this, void 0);
-            _Descriptor_witnessScript.set(this, void 0);
-            _Descriptor_redeemScript.set(this, void 0);
+        constructor({ descriptor, index, checksumRequired = false, allowMiniscriptInP2SH = false, network = bitcoinjs_lib_1.networks.bitcoin, preimages = [], signersPubKeys }) {
+            _Output_instances.add(this);
+            _Output_payment.set(this, void 0);
+            _Output_preimages.set(this, []);
+            _Output_signersPubKeys.set(this, void 0);
+            _Output_miniscript.set(this, void 0);
+            _Output_witnessScript.set(this, void 0);
+            _Output_redeemScript.set(this, void 0);
             //isSegwit true if witnesses are needed to the spend coins sent to this descriptor.
             //may be unset because we may get addr(P2SH) which we don't know if they have segwit.
-            _Descriptor_isSegwit.set(this, void 0);
-            _Descriptor_expandedExpression.set(this, void 0);
-            _Descriptor_expandedMiniscript.set(this, void 0);
-            _Descriptor_expansionMap.set(this, void 0);
-            _Descriptor_network.set(this, void 0);
-            __classPrivateFieldSet(this, _Descriptor_network, network, "f");
-            __classPrivateFieldSet(this, _Descriptor_preimages, preimages, "f");
-            if (typeof expression !== 'string')
+            _Output_isSegwit.set(this, void 0);
+            _Output_expandedExpression.set(this, void 0);
+            _Output_expandedMiniscript.set(this, void 0);
+            _Output_expansionMap.set(this, void 0);
+            _Output_network.set(this, void 0);
+            __classPrivateFieldSet(this, _Output_network, network, "f");
+            __classPrivateFieldSet(this, _Output_preimages, preimages, "f");
+            if (typeof descriptor !== 'string')
                 throw new Error(`Error: invalid descriptor type`);
             const expandedResult = expand({
-                expression,
+                descriptor,
                 ...(index !== undefined ? { index } : {}),
                 checksumRequired,
                 network,
@@ -439,68 +444,89 @@ function DescriptorsFactory(ecc) {
             if (expandedResult.isRanged && index === undefined)
                 throw new Error(`Error: index was not provided for ranged descriptor`);
             if (!expandedResult.payment)
-                throw new Error(`Error: could not extract a payment from ${expression}`);
-            __classPrivateFieldSet(this, _Descriptor_payment, expandedResult.payment, "f");
+                throw new Error(`Error: could not extract a payment from ${descriptor}`);
+            __classPrivateFieldSet(this, _Output_payment, expandedResult.payment, "f");
             if (expandedResult.expandedExpression !== undefined)
-                __classPrivateFieldSet(this, _Descriptor_expandedExpression, expandedResult.expandedExpression, "f");
+                __classPrivateFieldSet(this, _Output_expandedExpression, expandedResult.expandedExpression, "f");
             if (expandedResult.miniscript !== undefined)
-                __classPrivateFieldSet(this, _Descriptor_miniscript, expandedResult.miniscript, "f");
+                __classPrivateFieldSet(this, _Output_miniscript, expandedResult.miniscript, "f");
             if (expandedResult.expansionMap !== undefined)
-                __classPrivateFieldSet(this, _Descriptor_expansionMap, expandedResult.expansionMap, "f");
+                __classPrivateFieldSet(this, _Output_expansionMap, expandedResult.expansionMap, "f");
             if (expandedResult.isSegwit !== undefined)
-                __classPrivateFieldSet(this, _Descriptor_isSegwit, expandedResult.isSegwit, "f");
+                __classPrivateFieldSet(this, _Output_isSegwit, expandedResult.isSegwit, "f");
             if (expandedResult.expandedMiniscript !== undefined)
-                __classPrivateFieldSet(this, _Descriptor_expandedMiniscript, expandedResult.expandedMiniscript, "f");
+                __classPrivateFieldSet(this, _Output_expandedMiniscript, expandedResult.expandedMiniscript, "f");
             if (expandedResult.redeemScript !== undefined)
-                __classPrivateFieldSet(this, _Descriptor_redeemScript, expandedResult.redeemScript, "f");
+                __classPrivateFieldSet(this, _Output_redeemScript, expandedResult.redeemScript, "f");
             if (expandedResult.witnessScript !== undefined)
-                __classPrivateFieldSet(this, _Descriptor_witnessScript, expandedResult.witnessScript, "f");
+                __classPrivateFieldSet(this, _Output_witnessScript, expandedResult.witnessScript, "f");
             if (signersPubKeys) {
-                __classPrivateFieldSet(this, _Descriptor_signersPubKeys, signersPubKeys, "f");
+                __classPrivateFieldSet(this, _Output_signersPubKeys, signersPubKeys, "f");
             }
             else {
-                if (__classPrivateFieldGet(this, _Descriptor_expansionMap, "f")) {
-                    __classPrivateFieldSet(this, _Descriptor_signersPubKeys, Object.values(__classPrivateFieldGet(this, _Descriptor_expansionMap, "f")).map(keyInfo => {
+                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 ${expression}`);
+                            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 ${expression} that is not an address`);
+                        throw new Error(`Error: expansionMap not available for expression ${descriptor} that is not an address`);
                     }
-                    __classPrivateFieldSet(this, _Descriptor_signersPubKeys, [this.getScriptPubKey()], "f");
+                    __classPrivateFieldSet(this, _Output_signersPubKeys, [this.getScriptPubKey()], "f");
                 }
             }
         }
+        /**
+         * 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, _Descriptor_payment, "f");
+            return __classPrivateFieldGet(this, _Output_payment, "f");
         }
         /**
-         * Returns the Bitcoin Address
+         * Returns the Bitcoin Address of this `Output`.
          */
         getAddress() {
-            if (!__classPrivateFieldGet(this, _Descriptor_payment, "f").address)
+            if (!__classPrivateFieldGet(this, _Output_payment, "f").address)
                 throw new Error(`Error: could extract an address from the payment`);
-            return __classPrivateFieldGet(this, _Descriptor_payment, "f").address;
+            return __classPrivateFieldGet(this, _Output_payment, "f").address;
         }
+        /**
+         * Returns this `Output`'s scriptPubKey.
+         */
         getScriptPubKey() {
-            if (!__classPrivateFieldGet(this, _Descriptor_payment, "f").output)
+            if (!__classPrivateFieldGet(this, _Output_payment, "f").output)
                 throw new Error(`Error: could extract output.script from the payment`);
-            return __classPrivateFieldGet(this, _Descriptor_payment, "f").output;
+            return __classPrivateFieldGet(this, _Output_payment, "f").output;
         }
         /**
-         * Returns the compiled script satisfaction
-         * @param {PartialSig[]} signatures An array of signatures using this format: `interface PartialSig { pubkey: Buffer; signature: Buffer; }`
-         * @returns {Buffer}
+         * Returns the compiled Script Satisfaction if this `Output` was created
+         * using a miniscript-based descriptor.
+         *
+         * 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/).
+         *
+         * Important: As mentioned above, note that this function only applies to
+         * miniscript descriptors.
          */
-        getScriptSatisfaction(signatures) {
-            const miniscript = __classPrivateFieldGet(this, _Descriptor_miniscript, "f");
-            const expandedMiniscript = __classPrivateFieldGet(this, _Descriptor_expandedMiniscript, "f");
-            const expansionMap = __classPrivateFieldGet(this, _Descriptor_expansionMap, "f");
+        getScriptSatisfaction(
+        /**
+         * 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: Buffer; signature: Buffer; }`
+         */
+        signatures) {
+            const miniscript = __classPrivateFieldGet(this, _Output_miniscript, "f");
+            const expandedMiniscript = __classPrivateFieldGet(this, _Output_expandedMiniscript, "f");
+            const expansionMap = __classPrivateFieldGet(this, _Output_expansionMap, "f");
             if (miniscript === undefined ||
                 expandedMiniscript === undefined ||
                 expansionMap === undefined)
@@ -514,7 +540,7 @@ function DescriptorsFactory(ecc) {
                 expandedMiniscript,
                 expansionMap,
                 signatures,
-                preimages: __classPrivateFieldGet(this, _Descriptor_preimages, "f"),
+                preimages: __classPrivateFieldGet(this, _Output_preimages, "f"),
                 //Here we pass the TimeConstraints obtained using signersPubKeys to
                 //verify that the solutions found using the final signatures have not
                 //changed
@@ -527,45 +553,76 @@ function DescriptorsFactory(ecc) {
                 throw new Error(`Error: could not produce a valid satisfaction`);
             return scriptSatisfaction;
         }
+        /**
+         * Gets the nSequence required to fulfill this `Output`.
+         */
         getSequence() {
-            return __classPrivateFieldGet(this, _Descriptor_instances, "m", _Descriptor_getTimeConstraints).call(this)?.nSequence;
+            return __classPrivateFieldGet(this, _Output_instances, "m", _Output_getTimeConstraints).call(this)?.nSequence;
         }
+        /**
+         * Gets the nLockTime required to fulfill this `Output`.
+         */
         getLockTime() {
-            return __classPrivateFieldGet(this, _Descriptor_instances, "m", _Descriptor_getTimeConstraints).call(this)?.nLockTime;
+            return __classPrivateFieldGet(this, _Output_instances, "m", _Output_getTimeConstraints).call(this)?.nLockTime;
         }
+        /**
+         * Gets the witnessScript required to fulfill this `Output`. Only applies to
+         * Segwit outputs.
+         */
         getWitnessScript() {
-            return __classPrivateFieldGet(this, _Descriptor_witnessScript, "f");
+            return __classPrivateFieldGet(this, _Output_witnessScript, "f");
         }
+        /**
+         * Gets the redeemScript required to fullfill this `Output`. Only applies to
+         * SH outputs: sh(wpkh), sh(wsh), sh(lockingScript).
+         */
         getRedeemScript() {
-            return __classPrivateFieldGet(this, _Descriptor_redeemScript, "f");
+            return __classPrivateFieldGet(this, _Output_redeemScript, "f");
         }
+        /**
+         * Gets the bitcoinjs-lib [`network`](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/ts_src/networks.ts) used to create this `Output`.
+         */
         getNetwork() {
-            return __classPrivateFieldGet(this, _Descriptor_network, "f");
+            return __classPrivateFieldGet(this, _Output_network, "f");
         }
+        /**
+         * Whether this `Output` is Segwit.
+         */
         isSegwit() {
-            return __classPrivateFieldGet(this, _Descriptor_isSegwit, "f");
+            return __classPrivateFieldGet(this, _Output_isSegwit, "f");
+        }
+        /** @deprecated - Use updatePsbtAsInput instead
+         * @hidden
+         */
+        updatePsbt(params) {
+            this.updatePsbtAsInput(params);
+            return params.psbt.data.inputs.length - 1;
         }
         /**
-         * Updates a Psbt where the descriptor describes an utxo.
-         * The txHex (nonWitnessUtxo) and vout of the utxo must be passed.
+         * Sets this output as an input of the provided `psbt` and updates the
+         * `psbt` locktime if required by the descriptor.
+         *
+         * `psbt` and `vout` are mandatory. Include `txHex` as well. The pair
+         * `vout` and `txHex` define the transaction and output number this instance
+         * pertains to.
+         *
+         * Though not advised, for Segwit inputs you can pass `txId` and `value`
+         * in lieu of `txHex`. If doing so, ensure `value` accuracy to avoid
+         * potential fee attacks -
+         * [See this issue](https://github.com/bitcoinjs/bitcoinjs-lib/issues/1625).
+         *
+         * Note: Hardware wallets need the [full `txHex` for Segwit](https://blog.trezor.io/details-of-firmware-updates-for-trezor-one-version-1-9-1-and-trezor-model-t-version-2-3-1-1eba8f60f2dd).
          *
-         * updatePsbt adds an input to the psbt and updates the tx locktime if needed.
-         * It also adds a new input to the Psbt based on txHex
-         * It returns the number of the input that is added.
-         * psbt and vout are mandatory. Also pass txHex.
+         * When unsure, always use `txHex`, and skip `txId` and `value` for safety.
          *
-         * The following is not recommended but, alternatively, ONLY for Segwit inputs,
-         * you can pass txId and value, instead of txHex.
-         * If you do so, it is your responsibility to make sure that `value` is
-         * correct to avoid possible fee vulnerability attacks:
-         * https://github.com/bitcoinjs/bitcoinjs-lib/issues/1625
-         * Note that HW wallets require the full txHex also for Segwit anyways:
-         * https://blog.trezor.io/details-of-firmware-updates-for-trezor-one-version-1-9-1-and-trezor-model-t-version-2-3-1-1eba8f60f2dd
+         * @returns A finalizer function to be used after signing the `psbt`.
+         * This function ensures that this input is properly finalized.
+         * The finalizer has this signature:
+         *
+         * `( { psbt, validate = true } : { psbt: Psbt; validate: boolean | undefined } ) => void`
          *
-         * In doubt, simply pass txHex (and you can skip passing txId and value) and
-         * you shall be fine.
          */
-        updatePsbt({ psbt, txHex, txId, value, vout //vector output index
+        updatePsbtAsInput({ psbt, txHex, txId, value, vout //vector output index
          }) {
             if (txHex === undefined) {
                 console.warn(`Warning: missing txHex may allow fee attacks`);
@@ -575,7 +632,7 @@ function DescriptorsFactory(ecc) {
                 //This should only happen when using addr() expressions
                 throw new Error(`Error: could not determine whether this is a segwit descriptor`);
             }
-            return (0, psbt_1.updatePsbt)({
+            const index = (0, psbt_1.updatePsbt)({
                 psbt,
                 vout,
                 ...(txHex !== undefined ? { txHex } : {}),
@@ -583,13 +640,55 @@ function DescriptorsFactory(ecc) {
                 ...(value !== undefined ? { value } : {}),
                 sequence: this.getSequence(),
                 locktime: this.getLockTime(),
-                keysInfo: __classPrivateFieldGet(this, _Descriptor_expansionMap, "f") ? Object.values(__classPrivateFieldGet(this, _Descriptor_expansionMap, "f")) : [],
+                keysInfo: __classPrivateFieldGet(this, _Output_expansionMap, "f") ? Object.values(__classPrivateFieldGet(this, _Output_expansionMap, "f")) : [],
                 scriptPubKey: this.getScriptPubKey(),
                 isSegwit,
                 witnessScript: this.getWitnessScript(),
                 redeemScript: this.getRedeemScript()
             });
+            const finalizer = ({ psbt, validate = true }) => this.finalizePsbtInput({ index, psbt, validate });
+            return finalizer;
+        }
+        /**
+         * Adds this output as an output of the provided `psbt` with the given
+         * value.
+         *
+         * @param psbt - The Partially Signed Bitcoin Transaction.
+         * @param value - The value for the output in satoshis.
+         */
+        updatePsbtAsOutput({ psbt, value }) {
+            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)) {
@@ -605,39 +704,43 @@ function DescriptorsFactory(ecc) {
             const signatures = psbt.data.inputs[index]?.partialSig;
             if (!signatures)
                 throw new Error(`Error: cannot finalize without signatures`);
-            __classPrivateFieldGet(this, _Descriptor_instances, "m", _Descriptor_assertPsbtInput).call(this, { index, psbt });
-            if (!__classPrivateFieldGet(this, _Descriptor_miniscript, "f")) {
+            __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 scriptSatisfaction = this.getScriptSatisfaction(signatures);
-                psbt.finalizeInput(index, (0, psbt_1.finalScriptsFuncFactory)(scriptSatisfaction, __classPrivateFieldGet(this, _Descriptor_network, "f")));
+                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.
+         */
         expand() {
             return {
-                ...(__classPrivateFieldGet(this, _Descriptor_expandedExpression, "f") !== undefined
-                    ? { expandedExpression: __classPrivateFieldGet(this, _Descriptor_expandedExpression, "f") }
+                ...(__classPrivateFieldGet(this, _Output_expandedExpression, "f") !== undefined
+                    ? { expandedExpression: __classPrivateFieldGet(this, _Output_expandedExpression, "f") }
                     : {}),
-                ...(__classPrivateFieldGet(this, _Descriptor_miniscript, "f") !== undefined
-                    ? { miniscript: __classPrivateFieldGet(this, _Descriptor_miniscript, "f") }
+                ...(__classPrivateFieldGet(this, _Output_miniscript, "f") !== undefined
+                    ? { miniscript: __classPrivateFieldGet(this, _Output_miniscript, "f") }
                     : {}),
-                ...(__classPrivateFieldGet(this, _Descriptor_expandedMiniscript, "f") !== undefined
-                    ? { expandedMiniscript: __classPrivateFieldGet(this, _Descriptor_expandedMiniscript, "f") }
+                ...(__classPrivateFieldGet(this, _Output_expandedMiniscript, "f") !== undefined
+                    ? { expandedMiniscript: __classPrivateFieldGet(this, _Output_expandedMiniscript, "f") }
                     : {}),
-                ...(__classPrivateFieldGet(this, _Descriptor_expansionMap, "f") !== undefined
-                    ? { expansionMap: __classPrivateFieldGet(this, _Descriptor_expansionMap, "f") }
+                ...(__classPrivateFieldGet(this, _Output_expansionMap, "f") !== undefined
+                    ? { expansionMap: __classPrivateFieldGet(this, _Output_expansionMap, "f") }
                     : {})
             };
         }
     }
-    _Descriptor_payment = new WeakMap(), _Descriptor_preimages = new WeakMap(), _Descriptor_signersPubKeys = new WeakMap(), _Descriptor_miniscript = new WeakMap(), _Descriptor_witnessScript = new WeakMap(), _Descriptor_redeemScript = new WeakMap(), _Descriptor_isSegwit = new WeakMap(), _Descriptor_expandedExpression = new WeakMap(), _Descriptor_expandedMiniscript = new WeakMap(), _Descriptor_expansionMap = new WeakMap(), _Descriptor_network = new WeakMap(), _Descriptor_instances = new WeakSet(), _Descriptor_getTimeConstraints = function _Descriptor_getTimeConstraints() {
-        const miniscript = __classPrivateFieldGet(this, _Descriptor_miniscript, "f");
-        const preimages = __classPrivateFieldGet(this, _Descriptor_preimages, "f");
-        const expandedMiniscript = __classPrivateFieldGet(this, _Descriptor_expandedMiniscript, "f");
-        const expansionMap = __classPrivateFieldGet(this, _Descriptor_expansionMap, "f");
-        const signersPubKeys = __classPrivateFieldGet(this, _Descriptor_signersPubKeys, "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_expandedExpression = new WeakMap(), _Output_expandedMiniscript = new WeakMap(), _Output_expansionMap = new WeakMap(), _Output_network = new WeakMap(), _Output_instances = new WeakSet(), _Output_getTimeConstraints = function _Output_getTimeConstraints() {
+        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");
         //Create a method. solvePreimages to solve them.
         if (miniscript) {
             if (expandedMiniscript === undefined || expansionMap === undefined)
@@ -659,7 +762,7 @@ function DescriptorsFactory(ecc) {
         }
         else
             return undefined;
-    }, _Descriptor_assertPsbtInput = function _Descriptor_assertPsbtInput({ psbt, index }) {
+    }, _Output_assertPsbtInput = function _Output_assertPsbtInput({ psbt, index }) {
         const input = psbt.data.inputs[index];
         const txInput = psbt.txInputs[index];
         if (!input || !txInput)
@@ -683,14 +786,34 @@ function DescriptorsFactory(ecc) {
             sequence = 0xfffffffe;
         if (sequence === undefined && locktime === 0)
             sequence = 0xffffffff;
+        const eqBuffers = (buf1, buf2) => buf1 instanceof Buffer && buf2 instanceof Buffer
+            ? Buffer.compare(buf1, buf2) === 0
+            : buf1 === buf2;
         if (Buffer.compare(scriptPubKey, this.getScriptPubKey()) !== 0 ||
             sequence !== inputSequence ||
             locktime !== psbt.locktime ||
-            this.getWitnessScript() !== input.witnessScript ||
-            this.getRedeemScript() !== input.redeemScript) {
+            !eqBuffers(this.getWitnessScript(), input.witnessScript) ||
+            !eqBuffers(this.getRedeemScript(), input.redeemScript)) {
             throw new Error(`Error: cannot finalize psbt index ${index} since it does not correspond to this descriptor`);
         }
     };
-    return { Descriptor, parseKeyExpression, expand, ECPair, BIP32 };
+    /**
+     * @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 */ Descriptor,
+        Output,
+        parseKeyExpression,
+        expand,
+        ECPair,
+        BIP32
+    };
 }
 exports.DescriptorsFactory = DescriptorsFactory;