@bitcoinerlab/descriptors 1.1.1 → 2.0.1

package/README.md

@@ -1,6 +1,6 @@
 # Bitcoin Descriptors Library
 
-This library is designed to parse and create Bitcoin Descriptors, including Miniscript, and generate Partially Signed Bitcoin Transactions (PSBTs). It also provides PSBT finalizers and signers for single-signature, BIP32, and Hardware Wallets.
+This library is designed to parse and create Bitcoin Descriptors, including Miniscript, and generate Partially Signed Bitcoin Transactions (PSBTs). It also provides PSBT signers and finalizers for single-signature, BIP32, and Hardware Wallets.
 
 ## Features
 
@@ -10,7 +10,7 @@ This library is designed to parse and create Bitcoin Descriptors, including Mini
 
 ## Concepts
 
-This library has two main capabilities related to Bitcoin descriptors. Firstly, it can generate addresses and scriptPubKeys from descriptors. These addresses and scriptPubKeys can be used to receive funds from other parties. Secondly, the library is able to sign and spend unspent outputs described by those same descriptors. In order to do this, the descriptors must first be set into a PSBT.
+This library has two main capabilities related to Bitcoin descriptors. Firstly, it can generate `addresses` and `scriptPubKeys` from descriptors. These `addresses` and `scriptPubKeys` can be used to receive funds from other parties. Secondly, the library is able to sign transactions and spend unspent outputs described by those same descriptors. In order to do this, the descriptors must first be set into a PSBT.
 
 If you are not familiar with _Bitcoin descriptors_ and _partially signed Bitcoin transactions (PSBTs)_, click on the section below to expand and read more about these concepts.
 
@@ -37,6 +37,8 @@ PSBTs come in handy when working with descriptors, especially when using scripts
 
 Before we dive in, it's worth mentioning that we have several comprehensive guides available covering different aspects of the library. These guides provide explanations and code examples in interactive playgrounds, allowing you to see the changes in the output as you modify the code. This hands-on learning experience, combined with clear explanations, helps you better understand how to use the library effectively. [Check out the available guides here](https://bitcoinerlab.com/guides).
 
+Furthermore, we've meticulously documented our API. For an in-depth look into Classes, functions, and types, head over [here](https://bitcoinerlab.com/modules/descriptors/api).
+
 To use this library (and accompanying libraries), you can install them using:
 
 ```bash
@@ -47,163 +49,175 @@ npm install @bitcoinerlab/secp256k1
 
 The library can be split into four main parts:
 
-- The `Descriptor` class, which is the core component that parses descriptors and can be used to finalize partially signed Bitcoin transactions (PSBTs).
-- `keyExpressions` and `scriptExpressions`, which provide functions to create descriptor and key expressions (strings) from structured data, making it easier to work with complex descriptors.
+- 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).
 - PSBT signers and finalizers, which are used to manage the signing and finalization of PSBTs.
+- `keyExpressions` and `scriptExpressions`, which provide functions to create key and standard descriptor expressions (strings) from structured data.
 - Hardware wallet integration, which provides support for interacting with hardware wallets such as Ledger devices.
 
-### Descriptor class
+### Output class
 
-The Descriptor class is created dynamically by providing a cryptographic secp256k1 engine as shown below:
+The `Output` class is dynamically created by providing a cryptographic secp256k1 engine as shown below:
 
 ```javascript
-import * as secp256k1 from '@bitcoinerlab/secp256k1';
+import * as ecc from '@bitcoinerlab/secp256k1';
 import * as descriptors from '@bitcoinerlab/descriptors';
-const { Descriptor } = descriptors.DescriptorsFactory(secp256k1);
+const { Output } = descriptors.DescriptorsFactory(ecc);
 ```
 
-After that, you can obtain an instance for a descriptor expression, such as a wpkh expression, like this:
+Once set up, you can obtain an instance for an output, described by a descriptor such as a `wpkh`, as follows:
 
 ```javascript
-const wpkhDescriptor = new Descriptor({
-  expression:
+const wpkhOutput = new Output({
+  descriptor:
     'wpkh(02f9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9)'
 });
 ```
 
-Here are the parameters that can be used to create a `new Descriptor`:
+Refer to [the API](https://bitcoinerlab.com/modules/descriptors/api/classes/_Internal_.Output.html#constructor) for the complete list of parameters in the constructor.
+
+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.
+
+To call `updatePsbtAsInput()`, use the following syntax:
 
 ```javascript
-constructor({
-  expression, // The descriptor string in ASCII format. It may include a "*"
-              // to denote an arbitrary index.
-  index,      // The descriptor's index in the case of a range descriptor
-              // (must be an integer >= 0).
-  checksumRequired = false // Optional flag indicating if the descriptor is
-                           // required to include a checksum. Defaults to false.
-  allowMiniscriptInP2SH = false, // Flag indicating if this instance can parse
-                                 // and generate script satisfactions for
-                                 // sh(miniscript) top-level expressions of
-                                 // miniscripts. This is not recommended.
-  network = networks.bitcoin, // One of bitcoinjs-lib `networks`
-                              // (https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/src/networks.js)
-                              // or another one with the same interface.
-  preimages = [], // An array of preimages of type `Preimage`: `Preimage[]`.
-                  // This info is necessary to finalize Psbts.
-  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 in terms
-                 // of tx size (if more than one path is available).
-                 // For more details on using this parameter, refer to this
-                 // Stack Exchange answer: https://bitcoin.stackexchange.com/a/118036/89665
-});
+import { Psbt } from 'bitcoinjs-lib';
+const psbt = new Psbt();
+const inputFinalizer = output.updatePsbtAsInput({ psbt, txHex, vout });
 ```
 
-The `Descriptor` class offers various helpful methods, 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, `updatePsbt()` and `finalizePsbt()`.
+Here, `psbt` refers to an instance of the [bitcoinjs-lib Psbt class](https://github.com/bitcoinjs/bitcoinjs-lib). The parameter `txHex` denotes a hex string that serializes the previous transaction containing this output. Meanwhile, `vout` is an integer that marks the position of the output within that transaction.
 
-The `updatePsbt()` method is an essential part of the library, responsible for adding an input to the PSBT corresponding to the UTXO (unspent transaction output) 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," `updatePsbt()` adds timelock information to the PSBT.
+The method returns the `inputFinalizer()` function. This finalizer function completes a PSBT input by adding the unlocking script (`scriptWitness` or `scriptSig`) that satisfies the previous 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 `inputFinalizer()`. Detailed [explanations on the `inputFinalizer` method](#signers-and-finalizers-finalize-psbt-input) can be found in the Signers and Finalizers section.
 
-To call `updatePsbt()`, use the following syntax:
+Conversely, `updatePsbtAsOutput` allows you to add an output to a PSBT. For instance, to configure a `psbt` that sends `10,000` sats to the SegWit address `bc1qgw6xanldsz959z45y4dszehx4xkuzf7nfhya8x`:
 
 ```javascript
-const inputIndex = descriptor.updatePsbt({ psbt, txHex, vout });
+const recipientOutput = 
+ new Output({ descriptor: `addr(bc1qgw6xanldsz959z45y4dszehx4xkuzf7nfhya8x)` });
+recipientOutput.updatePsbtAsOutput({ psbt, value: 10000 });
 ```
 
-Here, `psbt` is an instance of a [bitconjs-lib Psbt class](https://github.com/bitcoinjs/bitcoinjs-lib), `txHex` is the hex string that serializes the previous transaction, and `vout` is an integer corresponding to the output index of the descriptor in the previous transaction. The method returns a number that corresponds to the input number that this descriptor will take in the `psbt`.
+For further information on using the `Output` class, refer to the [comprehensive guides](https://bitcoinerlab.com/guides) that offer explanations and playgrounds to help learn the module. For specific details on the methods, refer directly to [the API](https://bitcoinerlab.com/modules/descriptors/api/classes/_Internal_.Output.html). For insights into the constructor, especially regarding the `signersPubKeys` parameter, as well as the usage of `updatePsbtAsInput`, `getAddress`, and `getScriptPubKey`, see this detailed [Stack Exchange answer](https://bitcoin.stackexchange.com/a/118036/89665).
 
-The `finalizePsbt()` method is the final step in adding the unlocking script (scriptWitness or scriptSig) that satisfies the spending condition to the transaction, effectively finalizing the Psbt. It should be called after all necessary signing operations have been completed. The syntax for calling this method is as follows:
+#### Parsing Descriptors with `expand()`
 
-```javascript
-descriptor.finalizePsbt({ index, psbt });
-```
+The `expand()` function serves as a mechanism to parse Bitcoin descriptors, unveiling a detailed breakdown of the descriptor's content. There are two main pathways to utilize this function:
 
-Here, `index` is the `inputIndex` obtained from the `updatePsbt()` method and `psbt` is an instance of a bitcoinjs-lib `Psbt` object.
+##### 1. Directly from an `Output` Instance
 
-For further information on using the Descriptor class, refer to the [comprehensive guides](https://bitcoinerlab.com/guides) that offer explanations and playgrounds to help learn the module. Additionally, a [Stack Exchange answer](https://bitcoin.stackexchange.com/a/118036/89665) provides a focused explanation on the constructor, specifically the `signersPubKeys` parameter, and the usage of `updatePsbt`, `finalizePsbt`, `getAddress`, and `getScriptPubKey`.
+If you have already instantiated the `Output` class and created an output, you can directly use the [`expand()` method](https://bitcoinerlab.com/modules/descriptors/api/classes/_Internal_.Output.html#expand) on that `Output` instance. This method provides a straightforward way to parse descriptors without the need for additional utilities.
 
-#### Tip: Parsing descriptors without instantiating a class
+```javascript
+const output = new Output({ descriptor: "your-descriptor-here" });
+const result = output.expand();
+```
 
-`DescriptorsFactory` provides a convenient `expand()` function that allows you to parse a descriptor expression without the need to instantiate the `Descriptor` class. This function can be used as follows:
+##### 2. Through the `DescriptorsFactory`
+
+If you haven't instantiated the `Output` class or simply prefer a standalone utility, the `DescriptorsFactory` provides an `expand()` function that allows you to directly parse the descriptor. For a comprehensive understanding of all the function arguments, refer to [this reference](https://bitcoinerlab.com/modules/descriptors/api/functions/DescriptorsFactory.html#DescriptorsFactory). Here's how you can use it:
 
 ```javascript
-const { expand } = descriptors.DescriptorsFactory(secp256k1);
+const { expand } = descriptors.DescriptorsFactory(ecc);
 const result = expand({
-  expression: 'sh(wsh(andor(pk(0252972572d465d016d4c501887b8df303eee3ed602c056b1eb09260dfa0da0ab2),older(8640),pk([d34db33f/49'/0'/0']tpubDCdxmvzJ5QBjTN8oCjjyT2V58AyZvA1fkmCeZRC75QMoaHcVP2m45Bv3hmnR7ttAwkb2UNYyoXdHVt4gwBqRrJqLUU2JrM43HippxiWpHra/1/2/3/4/*))))',
-  network: networks.testnet, // One of bitcoinjs-lib `networks`
-                             // (https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/src/networks.js)
-                             // or another one with the same interface.
-                             // Optional (defaults to bitcoin mainnet). 
-  allowMiniscriptInP2SH: true, // Optional flag to allow miniscript in P2SH.
-                              // Defaults to false.
-  index, // Optional. The descriptor's index in the case of a range descriptor
-         // (must be an integer >= 0). If not set for ranged descriptors, then 
-         // the function will return an expansionMap with ranged keyPaths and
-         // won't compute Payment or scripts.
-  checksumRequired = false // Optional flag indicating if the descriptor is
-                           // required to include a checksum. Defaults to false.
+  descriptor: "sh(wsh(andor(pk(0252972572d465d016d4c501887b8df303eee3ed602c056b1eb09260dfa0da0ab2),older(8640),pk([d34db33f/49'/0'/0']tpubDCdxmvzJ5QBjTN8oCjjyT2V58AyZvA1fkmCeZRC75QMoaHcVP2m45Bv3hmnR7ttAwkb2UNYyoXdHVt4gwBqRrJqLUU2JrM43HippxiWpHra/1/2/3/4/*))))"
 });
 ```
 
-The `expand()` function returns an object with the following properties:
-
-- `payment: Payment | undefined`: 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: string | undefined`: The expanded descriptor expression.
-- `miniscript: string | undefined`: The extracted miniscript from the expression, if any.
-- `expansionMap: ExpansionMap | undefined`: A map of key expressions in the descriptor to their corresponding expanded keys.
-- `isSegwit: boolean | undefined`: A boolean indicating whether the descriptor represents a SegWit script.
-- `expandedMiniscript: string | undefined`: The expanded miniscript, if any.
-- `redeemScript: Buffer | undefined`: The redeem script for the descriptor, if applicable.
-- `witnessScript: Buffer | undefined`: The witness script for the descriptor, if applicable.
-- `isRanged: boolean` : Whether the expression represents 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.
+Regardless of your chosen pathway, the outcome from `expand()` grants an insightful exploration into the descriptor's structure. For an exhaustive list of return properties, you can refer to [the API](https://bitcoinerlab.com/modules/descriptors/api/types/Expansion.html).
 
-For the example expression provided, the `expandedExpression` and a portion of the `expansionMap` would be as follows:
+For illustration, given the descriptor above, the corresponding `expandedExpression` and a section of the `expansionMap` would appear as:
 
 ```javascript
-// expression: 'sh(wsh(andor(pk(0252972572d465d016d4c501887b8df303eee3ed602c056b1eb09260dfa0da0ab2),older(8640),pk([d34db33f/49'/0'/0']tpubDCdxmvzJ5QBjTN8oCjjyT2V58AyZvA1fkmCeZRC75QMoaHcVP2m45Bv3hmnR7ttAwkb2UNYyoXdHVt4gwBqRrJqLUU2JrM43HippxiWpHra/1/2/3/4/*))))'
-
-expandedExpression: 'sh(wsh(andor(pk(@0),older(8640),pk(@1))))',
-expansionMap: {
-  '@0': {
-    keyExpression:
-      '0252972572d465d016d4c501887b8df303eee3ed602c056b1eb09260dfa0da0ab2'
-  },
-  '@1': {
-    keyExpression:
-      "[d34db33f/49'/0'/0']tpubDCdxmvzJ5QBjTN8oCjjyT2V58AyZvA1fkmCeZRC75QMoaHcVP2m45Bv3hmnR7ttAwkb2UNYyoXdHVt4gwBqRrJqLUU2JrM43HippxiWpHra/1/2/3/4/*",
-    keyPath: '/1/2/3/4/*',
-    originPath: "/49'/0'/0'",
-    path: "m/49'/0'/0'/1/2/3/4/*",
-    // Other relevant properties returned: `pubkey`, `ecpair` & `bip32` interfaces, `masterFingerprint`, etc.
-  }
+{
+    expandedExpression: 'sh(wsh(andor(pk(@0),older(8640),pk(@1))))',
+    expansionMap: {
+      '@0': {
+        keyExpression:
+          '0252972572d465d016d4c501887b8df303eee3ed602c056b1eb09260dfa0da0ab2'
+      },
+      '@1': {
+        keyExpression:
+          "[d34db33f/49'/0'/0']tpubDCdxmvzJ5QBjTN8oCjjyT2V58AyZvA1fkmCeZRC75QMoaHcVP2m45Bv3hmnR7ttAwkb2UNYyoXdHVt4gwBqRrJqLUU2JrM43HippxiWpHra/1/2/3/4/*",
+        keyPath: '/1/2/3/4/*',
+        originPath: "/49'/0'/0'",
+        path: "m/49'/0'/0'/1/2/3/4/*",
+        // Other relevant properties returned: `pubkey`, `ecpair` & `bip32` interfaces, `masterFingerprint`, etc.
+      }
+    }
+    //...
 }
 ```
 
-### keyExpressions and scriptExpressions
+### Signers and Finalizers
+
+This library encompasses a PSBT finalizer as well as three distinct signers: ECPair for single-signatures, BIP32, and Ledger (specifically crafted for Ledger Wallet devices, with upcoming support for other devices planned).
 
-This library also includes a set of function helpers that facilitate the generation of the `expression` parameter in the constructor of the `Descriptor` class. These helpers are located under the `scriptExpressions` module, which can be imported using the following statement:
+To incorporate these functionalities, use the following import statement:
+
+```javascript
+import { signers } from '@bitcoinerlab/descriptors';
+```
+
+For signing operations, utilize the methods provided by the [`signers`](https://bitcoinerlab.com/modules/descriptors/api/modules/signers.html):
+
+```javascript
+// For Ledger
+await signers.signLedger({ psbt, ledgerManager });
+
+// For BIP32 - https://github.com/bitcoinjs/bip32
+signers.signBIP32({ psbt, masterNode });
+
+// For ECPair - https://github.com/bitcoinjs/ecpair
+signers.signECPair({ psbt, ecpair }); // Here, `ecpair` is an instance of the bitcoinjs-lib ECPairInterface
+```
+
+Detailed information on Ledger integration will be provided in subsequent sections.
+
+<a name="signers-and-finalizers-finalize-psbt-input"></a>
+
+#### Finalizing the `psbt`
+
+When finalizing the `psbt`, the [`updatePsbtAsInput` method](https://bitcoinerlab.com/modules/descriptors/api/classes/_Internal_.Output.html#updatePsbtAsInput) plays a key role. When invoked, the `output.updatePsbtAsInput()` sets up the `psbt` by designating the output as an input and, if required, adjusts the transaction locktime. In addition, it returns a `inputFinalizer` function tailored for this specific `psbt` input.
+
+##### Procedure:
+
+1. For each unspent output from a previous transaction that you're referencing in a `psbt` as an input to be spent, call the `updatePsbtAsInput` method:
+
+   ```javascript
+   const inputFinalizer = output.updatePsbtAsInput({ psbt, txHex, vout });
+   ```
+
+2. Once you've completed the necessary signing operations on the `psbt`, use the returned finalizer function on each input:
+
+   ```javascript
+   inputFinalizer({ psbt });
+   ```
+
+##### Important Notes:
+
+- The finalizer function returned from `updatePsbtAsInput` adds the necessary unlocking script (`scriptWitness` or `scriptSig`) that satisfies the `Output`'s spending conditions. Remember, both `scriptSig` and `scriptWitness` contain signatures. Ensure that all necessary signing operations are completed before finalizing.
+
+- When using `updatePsbtAsInput`, the `txHex` parameter is crucial. For Segwit inputs, you can choose to pass `txId` and `value` instead of `txHex`. However, ensure the accuracy of the `value` to avoid potential fee attacks. When unsure, use `txHex` and skip `txId` and `value`.
+
+- Hardware wallets require 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).
+
+### Key Expressions and Script Expressions
+
+This library also provides a series of function helpers designed to streamline the generation of `descriptor` strings. These strings can serve as input parameters in the `Output` class constructor. These helpers are nested within the `scriptExpressions` module. You can import them as illustrated below:
 
 ```javascript
 import { scriptExpressions } from '@bitcoinerlab/descriptors';
 ```
 
-`scriptExpressions` includes functions that generate script expressions for commonly used script expressions. Some of the available functions are `pkhBIP32()`, `shWpkhBIP32`, `wpkhBIP32`, `pkhLedger()`, `shWpkhLedger` and `wpkhLedger`.
+Within the `scriptExpressions` module, there are functions designed to generate descriptors for commonly used scripts. Some examples include `pkhBIP32()`, `shWpkhBIP32()`, `wpkhBIP32()`, `pkhLedger()`, `shWpkhLedger()`, and `wpkhLedger()`. Refer to [the API](https://bitcoinerlab.com/modules/descriptors/api/modules/scriptExpressions.html#expand) for a detailed list and further information.
 
 When using BIP32-based descriptors, the following parameters are required for the `scriptExpressions` functions:
 
 ```javascript
 pkhBIP32(params: {
-  masterNode: BIP32Interface; //A bitcoinjs-lib instance of a BIP32 object.
+  masterNode: BIP32Interface; //bitcoinjs-lib BIP32 - https://github.com/bitcoinjs/bip32
   network?: Network; //A bitcoinjs-lib network
   account: number;
   change?: number | undefined; //0 -> external (receive), 1 -> internal (change)
@@ -213,11 +227,11 @@ pkhBIP32(params: {
 })
 ```
 
-For Ledger, `ledgerClient` and `ledgerState` are used instead of `masterNode`. These will be explained later when we discuss Ledger integration.
+For functions suffixed with *Ledger* (designed to generate descriptors for Ledger Hardware devices), replace `masterNode` with `ledgerManager`. Detailed information on Ledger integration will be provided in the following section.
 
-The `keyExpressions` category includes functions that generate string representations of key expressions for public keys. This is useful when working with miniscript-based descriptors.
+The `keyExpressions` category includes functions that generate string representations of key expressions for public keys.
 
-This library includes the following `keyExpressions`: `keyExpressionBIP32` and `keyExpressionLedger`. They can be imported as follows:
+This library includes the following `keyExpressions`: [`keyExpressionBIP32`](https://bitcoinerlab.com/modules/descriptors/api/functions/keyExpressionBIP32.html) and [`keyExpressionLedger`](https://bitcoinerlab.com/modules/descriptors/api/functions/keyExpressionLedger.html). They can be imported as follows:
 
 ```javascript
 import {
@@ -230,7 +244,7 @@ The parameters required for these functions are:
 
 ```javascript
 function keyExpressionBIP32({
-  masterNode: BIP32Interface;
+  masterNode: BIP32Interface; //bitcoinjs-lib BIP32 - https://github.com/bitcoinjs/bip32
   originPath: string;
   change?: number | undefined; //0 -> external (receive), 1 -> internal (change)
   index?: number | undefined | '*';
@@ -239,35 +253,13 @@ function keyExpressionBIP32({
 });
 ```
 
-For Ledger, `ledgerClient` and `ledgerState` are used instead of `masterNode`.
-
-Both functions will generate strings that fully define BIP32 keys. For example: `[d34db33f/44'/0'/0']xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/1/*`. Read [Bitcoin Core descriptors documentation](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md) to learn more about Key Expressions.
-
-### Signers and Finalizers
-
-This library provides a Psbt finalizer and three types of signers: ECPair for single-signature, BIP32, and Ledger (for Ledger Wallet devices, with plans for other devices).
-
-To use them, import them as follows:
-
-```javascript
-import { signers, finalizePsbt } from '@bitcoinerlab/descriptors';
-```
-
-To sign with the signers:
+For the `keyExpressionLedger` function, you'd use `ledgerManager` instead of `masterNode`.
 
-```javascript
-await signers.signLedger({
-  ledgerClient,
-  ledgerState,
-  psbt,
-  descriptors: psbtInputDescriptors
-});
-//Here psbtInputDescriptors is an array of descriptors odered by their respective inputIndex in the psbt
-signers.signBIP32({ psbt, masterNode });
-signers.signECPair({ psbt, ecpair }); //Where ecpair is an instance of bitcoinjs-lib ECPairInterface
+Both functions will generate strings that fully define BIP32 keys. For example:
+```text
+[d34db33f/44'/0'/0']xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/1/*
 ```
-
-To finalize the `psbt`, you can either call the method `finalizePsbtInput({ index, psbt })` on each descriptor, passing as arguments the `psbt` and its input `index`, or call the helper function: `finalizePsbt({psbt, descriptors })`. In the latter case, `descriptors` is an array of descriptors ordered by their respective input index in the `psbt`.
+Read [Bitcoin Core descriptors documentation](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md) to learn more about Key Expressions.
 
 ### Hardware Wallet Integration
 
@@ -301,6 +293,7 @@ await ledger.assertLedgerApp({
 });
 
 const ledgerClient = new AppClient(transport);
+const ledgerManager = { ledgerClient, ledgerState: {}, ecc, network };
 ```
 
 Here, `transport` is an instance of a Transport object that allows communication with Ledger devices. You can use any of the transports [provided by Ledger](https://github.com/LedgerHQ/ledger-live#libs---libraries).
@@ -309,8 +302,7 @@ To register the policies of non-standard descriptors on the Ledger device, use t
 
 ```javascript
 await ledger.registerLedgerWallet({
-  ledgerClient,
-  ledgerState,
+  ledgerManager,
   descriptor: wshDescriptor,
   policyName: 'BitcoinerLab'
 });
@@ -318,7 +310,9 @@ await ledger.registerLedgerWallet({
 
 This code will auto-skip the policy registration process if it already exists. Please refer to [Ledger documentation](https://github.com/LedgerHQ/app-bitcoin-new/blob/develop/doc/wallet.md) to learn more about their Wallet Policies registration procedures.
 
-Finally, `ledgerState` is an object used to store information related to Ledger devices. Although Ledger devices themselves are stateless, this object can be used to store information such as xpubs, master fingerprints, and wallet policies. You can pass an initially empty object that will be updated with more information as it is used. The object can be serialized and stored for future use.
+Finally, `ledgerManager.ledgerState` is an object used to store information related to Ledger devices. Although Ledger devices themselves are stateless, this object can be used to store information such as xpubs, master fingerprints, and wallet policies. You can pass an initially empty object that will be updated with more information as it is used. The object can be serialized and stored for future use.
+
+The [API reference for the ledger module](https://bitcoinerlab.com/modules/descriptors/api/variables/ledger.html) provides a comprehensive list of functions related to the Ledger Hardware Wallet, along with detailed explanations of their parameters and behavior.
 
 <a name="documentation"></a>
 
@@ -326,10 +320,11 @@ Finally, `ledgerState` is an object used to store information related to Ledger
 
 For more information, refer to the following resources:
 
-- [Guides](https://bitcoinerlab.com/guides): Comprehensive explanations and playgrounds to help you learn how to use the module.
-- [Stack Exchange answer](https://bitcoin.stackexchange.com/a/118036/89665): Focused explanation on the constructor, specifically the `signersPubKeys` parameter, and the usage of `updatePsbt`, `finalizePsbt`, `getAddress`, and `getScriptPubKey`.
-- [Integration tests](https://github.com/bitcoinerlab/descriptors/tree/main/test/integration): Well-commented code examples showcasing the usage of all functions in the module.
-- API Documentation: Auto-generated documentation from the source code, providing detailed information about the library and its methods. To generate the API documentation locally, follow these commands:
+- **[Guides](https://bitcoinerlab.com/guides)**: Comprehensive explanations and playgrounds to help you learn how to use the module.
+- **[API](https://bitcoinerlab.com/modules/descriptors/api)**: Dive into the details of the Classes, functions, and types.
+- **[Stack Exchange answer](https://bitcoin.stackexchange.com/a/118036/89665)**: Focused explanation on the constructor, specifically the `signersPubKeys` parameter, and the usage of `updatePsbtAsInput`, `getAddress`, and `getScriptPubKey`.
+- **[Integration tests](https://github.com/bitcoinerlab/descriptors/tree/main/test/integration)**: Well-commented code examples showcasing the usage of all functions in the module.
+- **Local Documentation**: Generate comprehensive API documentation from the source code:
 
   ```bash
   git clone https://github.com/bitcoinerlab/descriptors
@@ -340,8 +335,6 @@ For more information, refer to the following resources:
 
   The generated documentation will be available in the `docs/` directory. Open the `index.html` file to view the documentation.
 
-  Please note that not all the functions have been fully documented yet. However, you can easily understand their usage by reading the source code or by checking the integration tests or playgrounds.
-
 ## Authors and Contributors
 
 The project was initially developed and is currently maintained by [Jose-Luis Landabaso](https://github.com/landabaso). Contributions and help from other developers are welcome.

package/dist/checksum.d.ts

@@ -1,2 +1,6 @@
 export declare const CHECKSUM_CHARSET: string;
+/**
+ * Implements the Bitcoin descriptor's checksum algorithm described in
+ * {@link https://github.com/bitcoin/bitcoin/blob/master/src/script/descriptor.cpp}
+ */
 export declare const DescriptorChecksum: (span: string) => string;

package/dist/checksum.js

@@ -20,6 +20,10 @@ const PolyMod = (c, val) => {
     return c;
 };
 exports.CHECKSUM_CHARSET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+/**
+ * Implements the Bitcoin descriptor's checksum algorithm described in
+ * {@link https://github.com/bitcoin/bitcoin/blob/master/src/script/descriptor.cpp}
+ */
 const DescriptorChecksum = (span) => {
     const INPUT_CHARSET = '0123456789()[],\'/*abcdefgh@:$%{}IJKLMNOPQRSTUVWXYZ&+-.;<=>?!^_|~ijklmnopqrstuvwxyzABCDEFGH`#"\\ ';
     let c = 1n;