@bitcoinerlab/descriptors 1.1.1 → 2.0.0

package/dist/descriptors.js

@@ -60,44 +60,68 @@ 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).
+ * 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);
@@ -114,11 +138,16 @@ function DescriptorsFactory(ecc) {
         });
     };
     /**
-     * Takes a descriptor (expression) and expands it to its corresponding Bitcoin script and other relevant details.
-     *
-     * @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;
@@ -127,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
         });
@@ -145,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);
@@ -184,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 };
@@ -192,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 });
             }
         }
@@ -203,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 });
             }
         }
@@ -221,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
@@ -242,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 });
             }
         }
@@ -258,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,
@@ -281,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)
@@ -291,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
@@ -323,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,
@@ -344,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 } : {}),
@@ -358,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, ...
@@ -375,32 +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 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,
@@ -409,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(
+        /**
+         * 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; }`
          */
-        getScriptSatisfaction(signatures) {
-            const miniscript = __classPrivateFieldGet(this, _Descriptor_miniscript, "f");
-            const expandedMiniscript = __classPrivateFieldGet(this, _Descriptor_expandedMiniscript, "f");
-            const expansionMap = __classPrivateFieldGet(this, _Descriptor_expansionMap, "f");
+        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)
@@ -484,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
@@ -497,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`);
@@ -545,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 } : {}),
@@ -553,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)) {
@@ -575,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)
@@ -629,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)
@@ -653,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;