@bitcoinerlab/descriptors 0.2.0 → 0.2.2

package/README.md

@@ -1,18 +1,277 @@
-## Bitcoin Descriptors Library *Pre Release*
+# 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.
 
-**NOTE: This is a pre-release version only.** The Usage documentation is still being finalized. However, you can take a look at the [integration tests](https://github.com/bitcoinerlab/descriptors/tree/main/test/integration) for some examples of how to use this library.
+## Features
 
-### Features
-
-- Parses and creates Bitcoin Descriptors (including those based on the Miniscript language).
+- Parses and creates [Bitcoin Descriptors](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md) (including those based on the [Miniscript language](https://bitcoinerlab.com/modules/miniscript)).
 - Generates Partially Signed Bitcoin Transactions (PSBTs).
 - Provides PSBT finalizers and signers for single-signature, BIP32, and Hardware Wallets (currently supports Ledger devices; more devices are planned).
 
-### Usage
+## 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.
+
+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.
+
+<details>
+  <summary>Concepts</summary>
+
+### Descriptors
+
+In Bitcoin, a transaction consists of a set of inputs that are spent into a different set of outputs. Each input spends an output in a previous transaction. A Bitcoin descriptor is a string of text that describes the rules and conditions required to spend an output in a transaction.
+
+For example, `wpkh(02f9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9)` is a descriptor that describes a pay-to-witness-public-key-hash (P2WPKH) type of output with the specified public key. If you know the corresponding private key for the transaction for which this descriptor is an output, you can spend it.
+
+Descriptors can express much more complex conditions, such as multi-party cooperation, time-locked outputs, and more. These conditions can be expressed using the Bitcoin Miniscript language, which is a way of writing Bitcoin Scripts in a structured and more easily understandable way.
+
+### Partially Signed Bitcoin Transactions (PSBTs)
+
+A PSBT (Partially Signed Bitcoin Transaction) is a format for sharing Bitcoin transactions between different parties.
+
+PSBTs come in handy when working with descriptors, especially when using scripts, because they allow multiple parties to collaborate in the signing process. This is especially useful when using hardware wallets or other devices that require separate signatures or authorizations.
+
+</details>
+
+## Usage
+
+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).
+
+To use this library (and accompanying libraries), you can install them using:
+
+```bash
+npm install @bitcoinerlab/descriptors
+npm install @bitcoinerlab/miniscript
+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.
+- PSBT signers and finalizers, which are used to manage the signing and finalization of PSBTs.
+- Hardware wallet integration, which provides support for interacting with hardware wallets such as Ledger devices.
+
+### Descriptor class
+
+The Descriptor class is created dynamically by providing a cryptographic secp256k1 engine as shown below:
+
+```javascript
+import * as secp256k1 from '@bitcoinerlab/secp256k1';
+import * as descriptors from '@bitcoinerlab/descriptors';
+const { Descriptor } = descriptors.DescriptorsFactory(secp256k1);
+```
+
+After that, you can obtain an instance for a descriptor expression, such as a wpkh expression, like this:
+
+```javascript
+const wpkhDescriptor = new Descriptor({
+  expression:
+    'wpkh(02f9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9)'
+});
+```
+
+Here are the parameters that can be used to create a `new Descriptor`:
+
+```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, // Flag indicating if the descriptor is required
+                            // to include a checksum.
+  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
+}: DescriptorInfo);
+```
+
+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()`.
+
+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.
+
+To call `updatePsbt()`, use the following syntax:
+
+```javascript
+const inputIndex = descriptor.updatePsbt({ psbt, txHex, vout });
+```
+
+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`.
+
+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:
+
+```javascript
+descriptor.finalizePsbt({ index, psbt });
+```
+
+Here, `index` is the `inputIndex` obtained from the `updatePsbt()` method and `psbt` is an instance of a bitcoinjs-lib `Psbt` object.
+
+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`.
+
+### keyExpressions and scriptExpressions
+
+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:
+
+```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`.
+
+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.
+  network?: Network; //A bitcoinjs-lib network
+  account: number;
+  change?: number | undefined; //0 -> external (receive), 1 -> internal (change)
+  index?: number | undefined | '*';
+  keyPath?: string; //You can use change & index or a keyPath such as "/0/0"
+  isPublic?: boolean; //Whether to use xpub or xprv
+})
+```
+
+For Ledger, `ledgerClient` and `ledgerState` are used instead of `masterNode`. These will be explained later when we discuss Ledger integration.
+
+The `keyExpressions` category includes functions that generate string representations of key expressions for public keys. This is useful when working with miniscript-based descriptors.
 
-Usage instructions will be added to this README as soon as they are finalized. In the meantime, please refer to the [integration tests](https://github.com/bitcoinerlab/descriptors/tree/main/test/integration) for some examples of how to use this library.
+This library includes the following `keyExpressions`: `keyExpressionBIP32` and `keyExpressionLedger`. They can be imported as follows:
+
+```javascript
+import {
+  keyExpressionBIP32,
+  keyExpressionLedger
+} from '@bitcoinerlab/descriptors';
+```
+
+The parameters required for these functions are:
+
+```javascript
+function keyExpressionBIP32({
+  masterNode: BIP32Interface;
+  originPath: string;
+  change?: number | undefined; //0 -> external (receive), 1 -> internal (change)
+  index?: number | undefined | '*';
+  keyPath?: string | undefined; //In the case of the Ledger, keyPath must be /<1;0>/number
+  isPublic?: boolean;
+});
+```
+
+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:
+
+```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
+```
+
+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`.
+
+### Hardware Wallet Integration
+
+This library currently provides integration with Ledger wallets. Support for more devices is planned.
+
+To use a Ledger device for signing, you can import the necessary functions as follows:
+
+```javascript
+import { ledger } from '@bitcoinerlab/descriptors';
+```
+
+You can then use the following code to assert that the Ledger app is running Bitcoin Test version 2.1.0 or higher, and to create a new Ledger client:
+
+```javascript
+//Throws if not running Bitcoin Test >= 2.1.0
+await ledger.assertLedgerApp({
+  transport,
+  name: 'Bitcoin Test',
+  minVersion: '2.1.0'
+});
+
+const ledgerClient = new ledger.AppClient(transport);
+```
+
+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).
+
+To register the policies of non-standard descriptors on the Ledger device, you can use the following code:
+
+```javascript
+await ledger.registerLedgerWallet({
+  ledgerClient,
+  ledgerState,
+  descriptor: wshDescriptor,
+  policyName: 'BitcoinerLab'
+});
+```
+
+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.
+
+<a name="documentation"></a>
+
+## Additional Resources
+
+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:
+
+  ```bash
+  git clone https://github.com/bitcoinerlab/descriptors
+  cd descriptors/
+  npm install
+  npm run docs
+  ```
+
+  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
 
@@ -26,19 +285,19 @@ To download the source code and build the project, follow these steps:
 
 1. Clone the repository:
 
-```
+```bash
 git clone https://github.com/bitcoinerlab/descriptors.git
 ```
 
 2. Install the dependencies:
 
-```
+```bash
 npm install
 ```
 
 3. Build the project:
 
-```
+```bash
 npm run build
 ```
 
@@ -46,29 +305,27 @@ This will build the project and generate the necessary files in the `dist` direc
 
 ### Testing
 
-
-Before committing any code, make sure it passes all tests. First, make sure that you have a Bitcoin regtest node running and that you have set up the Express-based bitcoind manager from this repository: https://github.com/bitcoinjs/regtest-server. The manager should be running on 127.0.0.1:8080.
+Before committing any code, make sure it passes all tests. First, make sure that you have a Bitcoin regtest node running and that you have set up [this Express-based bitcoind manager](https://github.com/bitcoinjs/regtest-server) running on 127.0.0.1:8080.
 
 The easiest way to set up these services is to use a Docker image that comes preconfigured with them. You can use the following commands to download and run the Docker image:
 
 ```bash
-docker pull junderw/bitcoinjs-regtest-server
-docker run -d -p 127.0.0.1:8080:8080 junderw/bitcoinjs-regtest-server
+docker pull bitcoinerlab/tester
+docker run -d -p 8080:8080 -p 60401:60401 -p 3002:3002 bitcoinerlab/tester
 ```
 
 This will start a container running a Bitcoin regtest node and the bitcoind manager on your machine. Once you have your node and manager set up, you can run the tests using the following command:
 
-```
+```bash
 npm run test
 ```
 
 And, in case you have a Ledger device:
 
-```
+```bash
 npm run test:integration:ledger
 ```
 
 ### License
 
 This project is licensed under the MIT License.
-

package/dist/descriptors.d.ts

@@ -4,7 +4,6 @@ import type { TinySecp256k1Interface, ParseKeyExpression, DescriptorInterfaceCon
 /**
  * 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).
- * @returns {Object} an object containing functions, `parse` and `checksum`.
  * @namespace
  */
 export declare function DescriptorsFactory(ecc: TinySecp256k1Interface): {

package/dist/descriptors.js

@@ -95,7 +95,6 @@ function evaluate({ expression, checksumRequired, index }) {
 /**
  * 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).
- * @returns {Object} an object containing functions, `parse` and `checksum`.
  * @namespace
  */
 function DescriptorsFactory(ecc) {
@@ -133,13 +132,15 @@ function DescriptorsFactory(ecc) {
     }
     class Descriptor {
         /**
-         * @param {Object} params
+         * @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 {string} params.descriptor - The descriptor.
          * @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).
          *
-         * @see {@link https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/src/payments/index.d.ts}
          * @throws {Error} - when descriptor is invalid
          */
         constructor({ expression, index, checksumRequired = false, allowMiniscriptInP2SH = false, network = bitcoinjs_lib_1.networks.bitcoin, preimages = [], signersPubKeys }) {
@@ -418,6 +419,9 @@ function DescriptorsFactory(ecc) {
         getPayment() {
             return __classPrivateFieldGet(this, _Descriptor_payment, "f");
         }
+        /**
+         * Returns the Bitcoin Address
+         */
         getAddress() {
             if (!__classPrivateFieldGet(this, _Descriptor_payment, "f").address)
                 throw new Error(`Error: could extract an address from the payment`);
@@ -428,6 +432,11 @@ function DescriptorsFactory(ecc) {
                 throw new Error(`Error: could extract output.script from the payment`);
             return __classPrivateFieldGet(this, _Descriptor_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}
+         */
         getScriptSatisfaction(signatures) {
             const miniscript = __classPrivateFieldGet(this, _Descriptor_miniscript, "f");
             const expandedMiniscript = __classPrivateFieldGet(this, _Descriptor_expandedMiniscript, "f");

package/dist/index.d.ts

@@ -13,7 +13,7 @@ export declare function finalizePsbt({ psbt, descriptors, validate }: {
 export { keyExpressionBIP32, keyExpressionLedger } from './keyExpressions';
 import * as scriptExpressions from './scriptExpressions';
 export { scriptExpressions };
-import { AppClient } from '@bitcoinerlab/ledger';
+import { AppClient } from 'ledger-bitcoin';
 import { LedgerState, getLedgerMasterFingerPrint, getLedgerXpub, registerLedgerWallet, assertLedgerApp } from './ledger';
 export declare const ledger: {
     getLedgerMasterFingerPrint: typeof getLedgerMasterFingerPrint;

package/dist/index.js

@@ -42,12 +42,12 @@ Object.defineProperty(exports, "keyExpressionBIP32", { enumerable: true, get: fu
 Object.defineProperty(exports, "keyExpressionLedger", { enumerable: true, get: function () { return keyExpressions_1.keyExpressionLedger; } });
 const scriptExpressions = __importStar(require("./scriptExpressions"));
 exports.scriptExpressions = scriptExpressions;
-const ledger_1 = require("@bitcoinerlab/ledger");
-const ledger_2 = require("./ledger");
+const ledger_bitcoin_1 = require("ledger-bitcoin");
+const ledger_1 = require("./ledger");
 exports.ledger = {
-    getLedgerMasterFingerPrint: ledger_2.getLedgerMasterFingerPrint,
-    getLedgerXpub: ledger_2.getLedgerXpub,
-    registerLedgerWallet: ledger_2.registerLedgerWallet,
-    assertLedgerApp: ledger_2.assertLedgerApp,
-    AppClient: ledger_1.AppClient
+    getLedgerMasterFingerPrint: ledger_1.getLedgerMasterFingerPrint,
+    getLedgerXpub: ledger_1.getLedgerXpub,
+    registerLedgerWallet: ledger_1.registerLedgerWallet,
+    assertLedgerApp: ledger_1.assertLedgerApp,
+    AppClient: ledger_bitcoin_1.AppClient
 };

package/dist/keyExpressions.d.ts

@@ -3,7 +3,7 @@ import type { ECPairAPI } from 'ecpair';
 import type { BIP32API, BIP32Interface } from 'bip32';
 import type { KeyInfo } from './types';
 import { LedgerState } from './ledger';
-import type { AppClient } from '@bitcoinerlab/ledger';
+import type { AppClient } from 'ledger-bitcoin';
 export declare function parseKeyExpression({ keyExpression, isSegwit, ECPair, BIP32, network }: {
     keyExpression: string;
     network?: Network;

package/dist/keyExpressions.js

@@ -161,7 +161,7 @@ exports.parseKeyExpression = parseKeyExpression;
 function assertChangeIndexKeyPath({ change, index, keyPath }) {
     if (!((change === undefined && index === undefined) ||
         (change !== undefined && index !== undefined)))
-        throw new Error(`Error: Pass change, index and network or neither`);
+        throw new Error(`Error: Pass change and index or neither`);
     if ((change !== undefined) === (keyPath !== undefined))
         throw new Error(`Error: Pass either change and index or a keyPath`);
 }

package/dist/ledger.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="node" />
 import type { DescriptorInterface } from './types';
-import { AppClient } from '@bitcoinerlab/ledger';
+import { AppClient } from 'ledger-bitcoin';
 export declare function assertLedgerApp({ transport, name, minVersion }: {
     transport: any;
     name: string;

package/dist/ledger.js

@@ -3,7 +3,7 @@
 // Distributed under the MIT software license
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ledgerPolicyFromState = exports.comparePolicies = exports.ledgerPolicyFromStandard = exports.registerLedgerWallet = exports.descriptorToLedgerFormat = exports.getLedgerXpub = exports.getLedgerMasterFingerPrint = exports.assertLedgerApp = void 0;
-const ledger_1 = require("@bitcoinerlab/ledger");
+const ledger_bitcoin_1 = require("ledger-bitcoin");
 const bitcoinjs_lib_1 = require("bitcoinjs-lib");
 const re_1 = require("./re");
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -204,7 +204,7 @@ async function registerLedgerWallet({ descriptor, ledgerClient, ledgerState, pol
         //It already existed. No need to register it again.
     }
     else {
-        walletPolicy = new ledger_1.WalletPolicy(policyName, ledgerTemplate, keyRoots);
+        walletPolicy = new ledger_bitcoin_1.WalletPolicy(policyName, ledgerTemplate, keyRoots);
         let policyId;
         [policyId, policyHmac] = await ledgerClient.registerWallet(walletPolicy);
         const policy = {

package/dist/miniscript.js

@@ -91,7 +91,7 @@ function substituteAsm({ expandedAsm, expansionMap }) {
         //enclosed in <>, since <> represents hex code already encoded.
         //The regex below will match one or more digits within a string,
         //except if the sequence is surrounded by "<" and ">"
-        .replace(/(?<![<])\b\d+\b(?![>])/g, (num) => numberEncodeAsm(Number(num)))
+        .replace(/(<\d+>)|\b\d+\b/g, match => match.startsWith('<') ? match : numberEncodeAsm(Number(match)))
         //we don't have numbers anymore, now it's safe to remove < and > since we
         //know that every remaining is either an op_code or a hex encoded number
         .replace(/[<>]/g, '');

package/dist/psbt.js

@@ -144,26 +144,20 @@ function updatePsbt({ psbt, vout, txHex, txId, value, sequence, locktime, keysIn
     }
     if (txId === undefined || !value)
         throw new Error(`Error: txHex+vout required. Alternatively, but ONLY for Segwit inputs, txId+value can also be passed.`);
-    if (locktime !== undefined) {
-        if (psbt.locktime !== 0 && psbt.locktime !== undefined)
-            throw new Error(`Error: transaction locktime has already been set: ${psbt.locktime}`);
-        psbt.setLocktime(locktime);
-    }
-    let inputSequence;
-    if (locktime !== undefined) {
+    if (locktime) {
+        if (psbt.locktime && psbt.locktime !== locktime)
+            throw new Error(`Error: transaction locktime was already set with a different value: ${locktime} != ${psbt.locktime}`);
+        // nLockTime only works if at least one of the transaction inputs has an
+        // nSequence value that is below 0xffffffff. Let's make sure that at least
+        // this input's sequence < 0xffffffff
         if (sequence === undefined) {
-            // for CTV nSequence MUST be <= 0xfffffffe otherwise OP_CHECKLOCKTIMEVERIFY will fail.
-            inputSequence = 0xfffffffe;
+            //NOTE: if sequence is undefined, bitcoinjs-lib uses 0xffffffff as default
+            sequence = 0xfffffffe;
         }
         else if (sequence > 0xfffffffe) {
-            throw new Error(`Error: incompatible sequence: ${inputSequence} and locktime: ${locktime}`);
-        }
-        else {
-            inputSequence = sequence;
+            throw new Error(`Error: incompatible sequence: ${sequence} and locktime: ${locktime}`);
         }
-    }
-    else {
-        inputSequence = sequence;
+        psbt.setLocktime(locktime);
     }
     const input = {
         hash: reverseBuffer(Buffer.from(txId, 'hex')),
@@ -185,8 +179,8 @@ function updatePsbt({ psbt, vout, txHex, txId, value, sequence, locktime, keysIn
         //There's no need to put both witnessUtxo and nonWitnessUtxo
         input.witnessUtxo = { script: scriptPubKey, value };
     }
-    if (inputSequence !== undefined)
-        input.sequence = inputSequence;
+    if (sequence !== undefined)
+        input.sequence = sequence;
     if (witnessScript)
         input.witnessScript = witnessScript;
     if (redeemScript)

package/dist/scriptExpressions.d.ts

@@ -1,4 +1,4 @@
-import type { AppClient } from '@bitcoinerlab/ledger';
+import type { AppClient } from 'ledger-bitcoin';
 import { Network } from 'bitcoinjs-lib';
 import type { LedgerState } from './ledger';
 import type { BIP32Interface } from 'bip32';

package/dist/signers.d.ts

@@ -1,7 +1,7 @@
 import type { Psbt } from 'bitcoinjs-lib';
 import type { ECPairInterface } from 'ecpair';
 import type { BIP32Interface } from 'bip32';
-import { AppClient } from '@bitcoinerlab/ledger';
+import { AppClient } from 'ledger-bitcoin';
 import type { DescriptorInterface } from './types';
 import { LedgerState } from './ledger';
 export declare function signInputECPair({ psbt, index, ecpair }: {

package/dist/signers.js

@@ -3,8 +3,8 @@
 // Distributed under the MIT software license
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.signLedger = exports.signInputLedger = exports.signBIP32 = exports.signInputBIP32 = exports.signECPair = exports.signInputECPair = void 0;
-const ledger_1 = require("@bitcoinerlab/ledger");
-const ledger_2 = require("./ledger");
+const ledger_bitcoin_1 = require("ledger-bitcoin");
+const ledger_1 = require("./ledger");
 function signInputECPair({ psbt, index, ecpair }) {
     psbt.signInput(index, ecpair);
 }
@@ -23,12 +23,12 @@ function signBIP32({ psbt, masterNode }) {
 exports.signBIP32 = signBIP32;
 const ledgerSignaturesForInputIndex = (index, ledgerSignatures) => ledgerSignatures
     .filter(([i]) => i === index)
-    .map(([_i, pubkey, signature]) => ({
-    pubkey,
-    signature
+    .map(([_i, partialSignature]) => ({
+    pubkey: partialSignature.pubkey,
+    signature: partialSignature.signature
 }));
 async function signInputLedger({ psbt, index, descriptor, ledgerClient, ledgerState }) {
-    const result = await (0, ledger_2.descriptorToLedgerFormat)({
+    const result = await (0, ledger_1.descriptorToLedgerFormat)({
         descriptor,
         ledgerClient,
         ledgerState
@@ -37,24 +37,24 @@ async function signInputLedger({ psbt, index, descriptor, ledgerClient, ledgerSt
         throw new Error(`Error: descriptor does not have a ledger input`);
     const { ledgerTemplate, keyRoots } = result;
     let ledgerSignatures;
-    const standardPolicy = await (0, ledger_2.ledgerPolicyFromStandard)({
+    const standardPolicy = await (0, ledger_1.ledgerPolicyFromStandard)({
         descriptor,
         ledgerClient,
         ledgerState
     });
     if (standardPolicy) {
-        ledgerSignatures = await ledgerClient.signPsbt(new ledger_1.PsbtV2().fromBitcoinJS(psbt), new ledger_1.DefaultWalletPolicy(ledgerTemplate, keyRoots[0]), null);
+        ledgerSignatures = await ledgerClient.signPsbt(new ledger_bitcoin_1.PsbtV2().fromBitcoinJS(psbt), new ledger_bitcoin_1.DefaultWalletPolicy(ledgerTemplate, keyRoots[0]), null);
     }
     else {
-        const policy = await (0, ledger_2.ledgerPolicyFromState)({
+        const policy = await (0, ledger_1.ledgerPolicyFromState)({
             descriptor,
             ledgerClient,
             ledgerState
         });
         if (!policy || !policy.policyName || !policy.policyHmac)
             throw new Error(`Error: the descriptor's policy is not registered`);
-        const walletPolicy = new ledger_1.WalletPolicy(policy.policyName, ledgerTemplate, keyRoots);
-        ledgerSignatures = await ledgerClient.signPsbt(new ledger_1.PsbtV2().fromBitcoinJS(psbt), walletPolicy, policy.policyHmac);
+        const walletPolicy = new ledger_bitcoin_1.WalletPolicy(policy.policyName, ledgerTemplate, keyRoots);
+        ledgerSignatures = await ledgerClient.signPsbt(new ledger_bitcoin_1.PsbtV2().fromBitcoinJS(psbt), walletPolicy, policy.policyHmac);
     }
     //Add the signatures to the Psbt object using PartialSig format:
     psbt.updateInput(index, {
@@ -68,12 +68,12 @@ exports.signInputLedger = signInputLedger;
 async function signLedger({ psbt, descriptors, ledgerClient, ledgerState }) {
     const ledgerPolicies = [];
     for (const descriptor of descriptors) {
-        const policy = (await (0, ledger_2.ledgerPolicyFromState)({
+        const policy = (await (0, ledger_1.ledgerPolicyFromState)({
             descriptor,
             ledgerClient,
             ledgerState
         })) ||
-            (await (0, ledger_2.ledgerPolicyFromStandard)({
+            (await (0, ledger_1.ledgerPolicyFromStandard)({
                 descriptor,
                 ledgerClient,
                 ledgerState
@@ -86,7 +86,7 @@ async function signLedger({ psbt, descriptors, ledgerClient, ledgerState }) {
     //cluster unique LedgerPolicies
     const uniquePolicies = [];
     for (const policy of ledgerPolicies) {
-        if (!uniquePolicies.find((uniquePolicy) => (0, ledger_2.comparePolicies)(uniquePolicy, policy)))
+        if (!uniquePolicies.find((uniquePolicy) => (0, ledger_1.comparePolicies)(uniquePolicy, policy)))
             uniquePolicies.push(policy);
     }
     for (const uniquePolicy of uniquePolicies) {
@@ -95,12 +95,12 @@ async function signLedger({ psbt, descriptors, ledgerClient, ledgerState }) {
             uniquePolicy.policyHmac &&
             uniquePolicy.policyId) {
             //non-standard policy
-            const walletPolicy = new ledger_1.WalletPolicy(uniquePolicy.policyName, uniquePolicy.ledgerTemplate, uniquePolicy.keyRoots);
-            ledgerSignatures = await ledgerClient.signPsbt(new ledger_1.PsbtV2().fromBitcoinJS(psbt), walletPolicy, uniquePolicy.policyHmac);
+            const walletPolicy = new ledger_bitcoin_1.WalletPolicy(uniquePolicy.policyName, uniquePolicy.ledgerTemplate, uniquePolicy.keyRoots);
+            ledgerSignatures = await ledgerClient.signPsbt(new ledger_bitcoin_1.PsbtV2().fromBitcoinJS(psbt), walletPolicy, uniquePolicy.policyHmac);
         }
         else {
             //standard policy
-            ledgerSignatures = await ledgerClient.signPsbt(new ledger_1.PsbtV2().fromBitcoinJS(psbt), new ledger_1.DefaultWalletPolicy(uniquePolicy.ledgerTemplate, uniquePolicy.keyRoots[0]), null);
+            ledgerSignatures = await ledgerClient.signPsbt(new ledger_bitcoin_1.PsbtV2().fromBitcoinJS(psbt), new ledger_bitcoin_1.DefaultWalletPolicy(uniquePolicy.ledgerTemplate, uniquePolicy.keyRoots[0]), null);
         }
         for (const [index, ,] of ledgerSignatures) {
             psbt.updateInput(index, {

package/dist/types.d.ts

@@ -3,10 +3,23 @@ import type { ECPairInterface } from 'ecpair';
 import type { BIP32Interface } from 'bip32';
 import type { Network, Payment, Psbt } from 'bitcoinjs-lib';
 import type { PartialSig } from 'bip174/src/lib/interfaces';
-export interface Preimage {
+/**
+ * Preimage
+ * @alias Preimage
+ * @memberof Descriptor
+ */
+export type Preimage = {
+    /**
+     * Use same 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).
+     */
     preimage: string;
-}
+};
 export type TimeConstraints = {
     nLockTime: number | undefined;
     nSequence: number | undefined;
@@ -49,6 +62,12 @@ export interface TinySecp256k1Interface {
     xOnlyPointAddTweak(p: Uint8Array, tweak: Uint8Array): XOnlyPointAddTweakResult | null;
     privateNegate(d: Uint8Array): Uint8Array;
 }
+/**
+ * DescriptorInfo
+ * What defines a Descriptor. This is the type needed in the constructor.
+ * @alias DescriptorInfo
+ * @memberof Descriptor
+ */
 export type DescriptorInfo = {
     expression: string;
     index?: number;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bitcoinerlab/descriptors",
   "homepage": "https://github.com/bitcoinerlab/descriptors",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,7 @@
     "build": "npx tsc",
     "prepublishOnly": "npm run build && npm test && echo \"\\n\\n\" && npm run test:integration:ledger",
     "docs": "jsdoc -c jsdoc.json",
-    "regtest-docker": "docker ps | grep bitcoinjs-regtest-server > /dev/null || (docker pull junderw/bitcoinjs-regtest-server && docker run -d -p 8080:8080 junderw/bitcoinjs-regtest-server && sleep 5)",
+    "regtest-docker": "docker ps | grep bitcoinerlab/tester > /dev/null || (docker pull bitcoinerlab/tester && docker run -d -p 8080:8080 -p 60401:60401 -p 3002:3002 bitcoinerlab/tester && sleep 5)",
     "test:integration:soft": "npm run regtest-docker && npx ts-node test/integration/standardOutputs.ts && echo \"\\n\\n\" && npx ts-node test/integration/miniscript.ts",
     "test:integration:ledger": "npm run regtest-docker && npx ts-node test/integration/ledger.ts",
     "test:unit": "npm run build && node test/tools/generateBitcoinCoreFixtures.js && jest",
@@ -52,13 +52,14 @@
   "files": [
     "dist"
   ],
+  "COMMENT wrt ledger-bitcoin below": "ledger-bitcoin is installed using an alias. This package can be replaced with the official `ledger-bitcoin` npm package once [this PR](https://github.com/LedgerHQ/app-bitcoin-new/pull/147) is published to npm (likely in version > 0.2.1)",
   "dependencies": {
-    "@bitcoinerlab/ledger": "^0.1.6",
     "@bitcoinerlab/miniscript": "^1.2.1",
     "@bitcoinerlab/secp256k1": "^1.0.2",
     "bip32": "^3.1.0",
     "bitcoinjs-lib": "^6.1.0",
-    "ecpair": "^2.1.0"
+    "ecpair": "^2.1.0",
+    "ledger-bitcoin": "npm:@bitcoinerlab/ledger@^0.2.0"
   },
   "devDependencies": {
     "@babel/plugin-transform-modules-commonjs": "^7.20.11",
@@ -66,6 +67,7 @@
     "@typescript-eslint/eslint-plugin": "^5.53.0",
     "@typescript-eslint/parser": "^5.53.0",
     "babel-plugin-transform-import-meta": "^2.2.0",
+    "better-docs": "^2.7.2",
     "bip39": "^3.0.4",
     "bip65": "^1.0.3",
     "bip68": "^1.0.4",
@@ -74,7 +76,7 @@
     "eslint-plugin-prettier": "^4.2.1",
     "fs": "^0.0.1-security",
     "jest": "^29.4.3",
-    "jsdoc": "^4.0.0",
+    "jsdoc": "^3.6.11",
     "path": "^0.12.7",
     "prettier": "^2.8.4",
     "regtest-client": "^0.2.0",