Update library to v2.0.3: Ready for Coinselector Algorithm Integratio…

…n and Enhanced Documentation

This version updates the library to facilitate its use with external coinselector algorithms. The major change involves the library now returning the script satisfaction itself, instead of its size. This is particularly useful in scenarios where actual signatures are not available, as it allows the use of 72-byte zero-padded signatures (marked as 'DANGEROUSLY_USE_FAKE_SIGNATURES'). This feature should be utilized primarily for tx size estimation purposes and testing, and it's essential to be cautious with its application in real transactions.

Key Changes:
- Adapted `signatures` parameter to support 'DANGEROUSLY_USE_FAKE_SIGNATURES', enabling the generation of script satisfactions with 72-byte zero-padded signatures.
- Enhanced documentation to highlight the critical role of the `signersPubKeys` parameter in miniscript-based descriptors, especially for determining spending paths in previous outputs with various spending options.
- Included explicit warnings and guidance on the use of 'DANGEROUSLY_USE_FAKE_SIGNATURES' to prevent misuse in actual transaction scenarios.
- Comprehensive documentation updates for improved clarity and usability, including modifications to README.md and in-code comments.

These updates are designed to make the library more compatible and ready for use with coinselector algorithms, providing a more adaptable and efficient tool for Bitcoin transaction preparation and analysis.

Version: 2.0.3
Author: Jose-Luis Landabaso

README.md

@@ -73,11 +73,11 @@ const wpkhOutput = new Output({
 });
 ```
 
-Refer to [the API](https://bitcoinerlab.com/modules/descriptors/api/classes/_Internal_.Output.html#constructor) for the complete list of parameters in the constructor.
+For miniscript-based descriptors, the `signersPubKeys` parameter in the constuctor becomes particularly important. It specifies the spending path of a previous output with multiple spending paths. Detailed information about the constructor parameters, including `signersPubKeys`, can be found in [the API documentation](https://bitcoinerlab.com/modules/descriptors/api/classes/_Internal_.Output.html#constructor) and in [this Stack Exchange answer](https://bitcoin.stackexchange.com/a/118036/89665).
 
 The `Output` class [offers various helpful methods](https://bitcoinerlab.com/modules/descriptors/api/classes/_Internal_.Output.html), including `getAddress()`, which returns the address associated with the descriptor, `getScriptPubKey()`, which returns the `scriptPubKey` for the descriptor, `expand()`, which decomposes a descriptor into its elemental parts, `updatePsbtAsInput()` and `updatePsbtAsOutput()`.
 
-The `updatePsbtAsInput()` method is an essential part of the library, responsible for adding an input to the PSBT corresponding to the UTXO  described by the descriptor. Additionally, when the descriptor expresses an absolute time-spending condition, such as "This UTXO can only be spent after block N," `updatePsbtAsInput()` adds timelock information to the PSBT.
+The `updatePsbtAsInput()` method is an essential part of the library, responsible for adding an input to the PSBT corresponding to the UTXO  described by the descriptor. Additionally, when the descriptor expresses an absolute time-spending condition, such as "This UTXO can only be spent after block N", `updatePsbtAsInput()` adds timelock information to the PSBT.
 
 To call `updatePsbtAsInput()`, use the following syntax:
 

package.json

@@ -2,7 +2,7 @@
   "name": "@bitcoinerlab/descriptors",
   "description": "This library parses and creates Bitcoin Miniscript Descriptors and generates Partially Signed Bitcoin Transactions (PSBTs). It provides PSBT finalizers and signers for single-signature, BIP32 and Hardware Wallets.",
   "homepage": "https://github.com/bitcoinerlab/descriptors",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "author": "Jose-Luis Landabaso",
   "license": "MIT",
   "repository": {

src/descriptors.ts

@@ -590,23 +590,35 @@ export function DescriptorsFactory(ecc: TinySecp256k1Interface) {
       network?: Network;
 
       /**
-       * An array of preimages. This info is necessary to finalize Psbts.
+       * An array of preimages if the miniscript-based descriptor uses them.
+       *
+       * This info is necessary to finalize Psbts. Leave it `undefined` if your
+       * miniscript-based descriptor does not use preimages or you don't know
+       * or don't wanto use them.
+       *
+       * You can also leave it `undefined` if only need to generate the
+       * `scriptPubKey` or `address` for a descriptor.
+       *
        * @defaultValue `[]`
        */
       preimages?: Preimage[];
 
       /**
        * 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).
+       * spending the previous 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).
+       *
        * For more details on using this parameter, refer to [this Stack Exchange
        * answer](https://bitcoin.stackexchange.com/a/118036/89665).
        */
@@ -717,49 +729,6 @@ export function DescriptorsFactory(ecc: TinySecp256k1Interface) {
       } else return undefined;
     }
 
-    /**
-     * Retrieves the byte length of the script satisfaction for a Miniscript-based
-     * descriptor, using only the expression, signers' public keys, and preimages
-     * provided in the constructor.
-     *
-     * Useful in scenarios like coin selection algorithms for transaction creation,
-     * where signatures are not yet available. Since signatures are still to be
-     * computed, the function assigns a standard length of 72 bytes for each
-     * signature. However, note that this may not always be completely accurate,
-     * as approximately 50% of signatures are 71 bytes in length
-     * (source: https://transactionfee.info/charts/bitcoin-script-ecdsa-length/).
-     * The function returns the byte length for a worst-case scenario.
-     *
-     * @returns The byte length of the compiled script satisfaction, or `undefined`
-     *          if this was not a miniscript-based descriptor.
-     */
-    getScriptSatisfactionSize(): number | undefined {
-      const miniscript = this.#miniscript;
-      const preimages = this.#preimages;
-      const expandedMiniscript = this.#expandedMiniscript;
-      const expansionMap = this.#expansionMap;
-      const signersPubKeys = this.#signersPubKeys;
-      //Create a method. solvePreimages to solve them.
-      if (miniscript) {
-        if (expandedMiniscript === undefined || expansionMap === undefined)
-          throw new Error(
-            `Error: cannot get script satisfactions from not expanded miniscript ${miniscript}`
-          );
-        //We create some fakeSignatures since we may not have them yet.
-        const fakeSignatures = signersPubKeys.map(pubkey => ({
-          pubkey,
-          // https://transactionfee.info/charts/bitcoin-script-ecdsa-length/
-          signature: Buffer.alloc(72, 0)
-        }));
-        const { scriptSatisfaction } = satisfyMiniscript({
-          expandedMiniscript,
-          expansionMap,
-          signatures: fakeSignatures,
-          preimages
-        });
-        return scriptSatisfaction.length;
-      } else return undefined;
-    }
     /**
      * 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`.
@@ -801,9 +770,29 @@ export function DescriptorsFactory(ecc: TinySecp256k1Interface) {
        *
        * `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.
+       *
        */
-      signatures: PartialSig[]
+      signatures: PartialSig[] | 'DANGEROUSLY_USE_FAKE_SIGNATURES'
     ): Buffer {
+      if (signatures === 'DANGEROUSLY_USE_FAKE_SIGNATURES')
+        signatures = this.#signersPubKeys.map(pubkey => ({
+          pubkey,
+          // https://transactionfee.info/charts/bitcoin-script-ecdsa-length/
+          signature: Buffer.alloc(72, 0)
+        }));
       const miniscript = this.#miniscript;
       const expandedMiniscript = this.#expandedMiniscript;
       const expansionMap = this.#expansionMap;

src/types.ts

@@ -12,13 +12,15 @@ import type { Payment, Network } from 'bitcoinjs-lib';
  */
 export type Preimage = {
   /**
-   * Use same expressions as in miniscript. For example: "sha256(cdabb7f2dce7bfbd8a0b9570c6fd1e712e5d64045e9d6b517b3d5072251dc204)" or "ripemd160(095ff41131e5946f3c85f79e44adbcf8e27e080e)"
+   * Use same string expressions as in miniscript. For example: "sha256(cdabb7f2dce7bfbd8a0b9570c6fd1e712e5d64045e9d6b517b3d5072251dc204)" or "ripemd160(095ff41131e5946f3c85f79e44adbcf8e27e080e)"
+   *
    * Accepted functions: sha256, hash256, ripemd160, hash160
+   *
    * Digests must be: 64-character HEX for sha256, hash160 or 30-character HEX for ripemd160 or hash160.
    */
   digest: string;
   /**
-   * Hex encoded preimate. Preimages are always 32 bytes (so, 64 character in hex).
+   * Hex encoded preimage. Preimages are always 32 bytes (so, 64 character in hex).
    */
   preimage: string;
 };