@bitcoinerlab/descriptors 1.0.2 → 2.0.0

package/dist/signers.js

@@ -26,37 +26,77 @@ const ledgerSignaturesForInputIndex = (index, ledgerSignatures) => ledgerSignatu
     pubkey: partialSignature.pubkey,
     signature: partialSignature.signature
 }));
-async function signInputLedger({ psbt, index, descriptor, ledgerClient, ledgerState }) {
+/**
+ * To be removed in v3.0 and replaced by a version that does not accept
+ * descriptor
+ * @hidden
+ */
+async function signInputLedger({ psbt, index, descriptor, ledgerClient, ledgerState, ledgerManager }) {
+    if (!descriptor && !ledgerManager)
+        throw new Error(`ledgerManager not provided`);
+    if (descriptor && ledgerManager)
+        throw new Error(`Invalid usage: don't pass descriptor`);
+    if (ledgerManager && (ledgerClient || ledgerState))
+        throw new Error(`Invalid usage: either ledgerManager or ledgerClient + ledgerState`);
+    const output = descriptor;
+    if (ledgerManager)
+        ({ ledgerClient, ledgerState } = ledgerManager);
+    if (!ledgerClient)
+        throw new Error(`ledgerManager not provided`);
+    if (!ledgerState)
+        throw new Error(`ledgerManager not provided`);
     const { PsbtV2, DefaultWalletPolicy, WalletPolicy, AppClient } = (await (0, ledger_1.importAndValidateLedgerBitcoin)(ledgerClient));
     if (!(ledgerClient instanceof AppClient))
         throw new Error(`Error: pass a valid ledgerClient`);
-    const result = await (0, ledger_1.descriptorToLedgerFormat)({
-        descriptor,
-        ledgerClient,
-        ledgerState
-    });
-    if (!result)
-        throw new Error(`Error: descriptor does not have a ledger input`);
-    const { ledgerTemplate, keyRoots } = result;
     let ledgerSignatures;
-    const standardPolicy = await (0, ledger_1.ledgerPolicyFromStandard)({
-        descriptor,
-        ledgerClient,
-        ledgerState
-    });
-    if (standardPolicy) {
-        ledgerSignatures = await ledgerClient.signPsbt(new PsbtV2().fromBitcoinJS(psbt), new DefaultWalletPolicy(ledgerTemplate, keyRoots[0]), null);
+    if (ledgerManager) {
+        const policy = await (0, ledger_1.ledgerPolicyFromPsbtInput)({
+            psbt,
+            index,
+            ledgerManager
+        });
+        if (!policy)
+            throw new Error(`Error: the ledger cannot sign this pstb input`);
+        if (policy.policyName && policy.policyHmac && policy.policyId) {
+            //non-standard policy
+            const walletPolicy = new WalletPolicy(policy.policyName, policy.ledgerTemplate, policy.keyRoots);
+            ledgerSignatures = await ledgerClient.signPsbt(new PsbtV2().fromBitcoinJS(psbt), walletPolicy, policy.policyHmac);
+        }
+        else {
+            //standard policy
+            ledgerSignatures = await ledgerClient.signPsbt(new PsbtV2().fromBitcoinJS(psbt), new DefaultWalletPolicy(policy.ledgerTemplate, policy.keyRoots[0]), null);
+        }
     }
     else {
-        const policy = await (0, ledger_1.ledgerPolicyFromState)({
-            descriptor,
+        if (!output)
+            throw new Error(`outputs not provided`);
+        const result = await (0, ledger_1.ledgerPolicyFromOutput)({
+            output,
+            ledgerClient,
+            ledgerState
+        });
+        if (!result)
+            throw new Error(`Error: output does not have a ledger input`);
+        const { ledgerTemplate, keyRoots } = result;
+        const standardPolicy = await (0, ledger_1.ledgerPolicyFromStandard)({
+            output,
             ledgerClient,
             ledgerState
         });
-        if (!policy || !policy.policyName || !policy.policyHmac)
-            throw new Error(`Error: the descriptor's policy is not registered`);
-        const walletPolicy = new WalletPolicy(policy.policyName, ledgerTemplate, keyRoots);
-        ledgerSignatures = await ledgerClient.signPsbt(new PsbtV2().fromBitcoinJS(psbt), walletPolicy, policy.policyHmac);
+        if (standardPolicy) {
+            ledgerSignatures = await ledgerClient.signPsbt(new PsbtV2().fromBitcoinJS(psbt), new DefaultWalletPolicy(ledgerTemplate, keyRoots[0]), null);
+        }
+        else {
+            const policy = await (0, ledger_1.ledgerPolicyFromState)({
+                output,
+                ledgerClient,
+                ledgerState
+            });
+            if (!policy || !policy.policyName || !policy.policyHmac)
+                throw new Error(`Error: the descriptor's policy is not registered`);
+            const walletPolicy = new WalletPolicy(policy.policyName, ledgerTemplate, keyRoots);
+            ledgerSignatures = await ledgerClient.signPsbt(new PsbtV2().fromBitcoinJS(psbt), walletPolicy, policy.policyHmac);
+        }
     }
     //Add the signatures to the Psbt object using PartialSig format:
     psbt.updateInput(index, {
@@ -64,30 +104,51 @@ async function signInputLedger({ psbt, index, descriptor, ledgerClient, ledgerSt
     });
 }
 exports.signInputLedger = signInputLedger;
-//signLedger is able to sign several inputs of the same wallet policy since it
-//it clusters together wallet policy types before signing
-//it throws if it cannot sign any input.
-async function signLedger({ psbt, descriptors, ledgerClient, ledgerState }) {
+/**
+ * To be removed in v3.0 and replaced by a version that does not accept
+ * descriptors
+ * @hidden
+ */
+async function signLedger({ psbt, descriptors, ledgerClient, ledgerState, ledgerManager }) {
+    if (!descriptors && !ledgerManager)
+        throw new Error(`ledgerManager not provided`);
+    if (descriptors && ledgerManager)
+        throw new Error(`Invalid usage: don't pass descriptors`);
+    if (ledgerManager && (ledgerClient || ledgerState))
+        throw new Error(`Invalid usage: either ledgerManager or ledgerClient + ledgerState`);
+    const outputs = descriptors;
+    if (ledgerManager)
+        ({ ledgerClient, ledgerState } = ledgerManager);
+    if (!ledgerClient)
+        throw new Error(`ledgerManager not provided`);
+    if (!ledgerState)
+        throw new Error(`ledgerManager not provided`);
     const { PsbtV2, DefaultWalletPolicy, WalletPolicy, AppClient } = (await (0, ledger_1.importAndValidateLedgerBitcoin)(ledgerClient));
     if (!(ledgerClient instanceof AppClient))
         throw new Error(`Error: pass a valid ledgerClient`);
     const ledgerPolicies = [];
-    for (const descriptor of descriptors) {
-        const policy = (await (0, ledger_1.ledgerPolicyFromState)({
-            descriptor,
-            ledgerClient,
-            ledgerState
-        })) ||
-            (await (0, ledger_1.ledgerPolicyFromStandard)({
-                descriptor,
-                ledgerClient,
-                ledgerState
-            }));
-        if (policy)
-            ledgerPolicies.push(policy);
+    if (ledgerManager)
+        for (let index = 0; index < psbt.data.inputs.length; index++) {
+            const policy = await (0, ledger_1.ledgerPolicyFromPsbtInput)({
+                psbt,
+                index,
+                ledgerManager
+            });
+            if (policy)
+                ledgerPolicies.push(policy);
+        }
+    else {
+        if (!outputs)
+            throw new Error(`outputs not provided`);
+        for (const output of outputs) {
+            const policy = (await (0, ledger_1.ledgerPolicyFromState)({ output, ledgerClient, ledgerState })) ||
+                (await (0, ledger_1.ledgerPolicyFromStandard)({ output, ledgerClient, ledgerState }));
+            if (policy)
+                ledgerPolicies.push(policy);
+        }
+        if (ledgerPolicies.length === 0)
+            throw new Error(`Error: there are no inputs which could be signed`);
     }
-    if (ledgerPolicies.length === 0)
-        throw new Error(`Error: there are no inputs which could be signed`);
     //cluster unique LedgerPolicies
     const uniquePolicies = [];
     for (const policy of ledgerPolicies) {

package/dist/types.d.ts

@@ -1,8 +1,7 @@
 /// <reference types="node" />
 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';
+import type { Payment, Network } from 'bitcoinjs-lib';
 /**
  * Preimage
  * @alias Preimage
@@ -24,6 +23,9 @@ export type TimeConstraints = {
     nLockTime: number | undefined;
     nSequence: number | undefined;
 };
+/**
+ * See {@link _Internal_.ParseKeyExpression | ParseKeyExpression}.
+ */
 export type KeyInfo = {
     keyExpression: string;
     pubkey?: Buffer;
@@ -34,40 +36,44 @@ export type KeyInfo = {
     keyPath?: string;
     path?: string;
 };
+/**
+ * An `ExpansionMap` contains destructured information of a descritptor expression.
+ *
+ * For example, this descriptor `sh(wsh(andor(pk(0252972572d465d016d4c501887b8df303eee3ed602c056b1eb09260dfa0da0ab2),older(8640),pk([d34db33f/49'/0'/0']tpubDCdxmvzJ5QBjTN8oCjjyT2V58AyZvA1fkmCeZRC75QMoaHcVP2m45Bv3hmnR7ttAwkb2UNYyoXdHVt4gwBqRrJqLUU2JrM43HippxiWpHra/1/2/3/4/*))))` has the following
+ * `expandedExpression`: `sh(wsh(andor(pk(@0),older(8640),pk(@1))))`
+ *
+ * `key`'s are set using this format: `@i`, where `i` is an integer starting from `0` assigned by parsing and retrieving keys from the descriptor from left to right.
+ *
+ * For the given example, the `ExpansionMap` is:
+ *
+ * ```javascript
+ *  {
+ *    '@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 of the type `KeyInfo`: `pubkey`, `ecpair` & `bip32` interfaces, `masterFingerprint`, etc.
+ *    }
+ *  }
+ *```
+ *
+ *
+ */
 export type ExpansionMap = {
     [key: string]: KeyInfo;
 };
-export interface ParseKeyExpression {
-    (params: {
-        keyExpression: string;
-        isSegwit?: boolean;
-        network?: Network;
-    }): KeyInfo;
-}
-export interface Expand {
-    (params: {
-        expression: string;
-        index?: number;
-        checksumRequired?: boolean;
-        network?: Network;
-        allowMiniscriptInP2SH?: boolean;
-    }): {
-        payment?: Payment;
-        expandedExpression?: string;
-        miniscript?: string;
-        expansionMap?: ExpansionMap;
-        isSegwit?: boolean;
-        expandedMiniscript?: string;
-        redeemScript?: Buffer;
-        witnessScript?: Buffer;
-        isRanged: boolean;
-        canonicalExpression: string;
-    };
-}
+/** @ignore */
 interface XOnlyPointAddTweakResult {
     parity: 1 | 0;
     xOnlyPubkey: Uint8Array;
 }
+/** @ignore */
 export interface TinySecp256k1Interface {
     isPoint(p: Uint8Array): boolean;
     pointCompress(p: Uint8Array, compressed?: boolean): Uint8Array;
@@ -83,51 +89,92 @@ export interface TinySecp256k1Interface {
     privateNegate(d: Uint8Array): Uint8Array;
 }
 /**
- * DescriptorInfo
- * What defines a Descriptor. This is the type needed in the constructor.
- * @alias DescriptorInfo
- * @memberof Descriptor
+ * `DescriptorsFactory` creates and returns the {@link DescriptorsFactory | `expand()`}
+ * function that parses a descriptor expression and destructures it
+ * into its elemental parts. `Expansion` is the type that `expand()` returns.
  */
-export type DescriptorInfo = {
-    expression: string;
-    index?: number;
-    checksumRequired?: boolean;
-    allowMiniscriptInP2SH?: boolean;
-    network?: Network;
-    preimages?: Preimage[];
-    signersPubKeys?: Buffer[];
+export type Expansion = {
+    /**
+     * The corresponding [bitcoinjs-lib Payment](https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/ts_src/payments/index.ts) for the provided expression, if applicable.
+     */
+    payment?: Payment;
+    /**
+     * The expanded descriptor expression.
+     * See {@link ExpansionMap ExpansionMap} for a detailed explanation.
+     */
+    expandedExpression?: string;
+    /**
+     * The extracted miniscript from the expression, if any.
+     */
+    miniscript?: string;
+    /**
+     * A map of key expressions in the descriptor to their corresponding expanded keys.
+     * See {@link ExpansionMap ExpansionMap} for a detailed explanation.
+     */
+    expansionMap?: ExpansionMap;
+    /**
+     * A boolean indicating whether the descriptor uses SegWit.
+     */
+    isSegwit?: boolean;
+    /**
+     * The expanded miniscript, if any.
+     * It corresponds to the `expandedExpression` without the top-level script
+     * expression.
+     */
+    expandedMiniscript?: string;
+    /**
+     * The redeem script for the descriptor, if applicable.
+     */
+    redeemScript?: Buffer;
+    /**
+     * The witness script for the descriptor, if applicable.
+     */
+    witnessScript?: Buffer;
+    /**
+     * Whether the descriptor is a ranged-descriptor.
+     */
+    isRanged: boolean;
+    /**
+     * This is the preferred or authoritative representation of an output
+     * descriptor expression.
+     * It removes the checksum and, if it is a ranged-descriptor, it
+     * particularizes it to its index.
+     */
+    canonicalExpression: string;
 };
-export interface DescriptorInterface {
-    getPayment(): Payment;
-    getAddress(): string;
-    getScriptPubKey(): Buffer;
-    getScriptSatisfaction(signatures: PartialSig[]): Buffer;
-    getSequence(): number | undefined;
-    getLockTime(): number | undefined;
-    getWitnessScript(): Buffer | undefined;
-    getRedeemScript(): Buffer | undefined;
-    getNetwork(): Network;
-    isSegwit(): boolean | undefined;
-    updatePsbt({ psbt, vout, txHex, txId, value }: {
-        psbt: Psbt;
-        vout: number;
-        txHex?: string;
-        txId?: string;
-        value?: number;
-    }): number;
-    finalizePsbtInput({ index, psbt, validate }: {
-        index: number;
-        psbt: Psbt;
-        validate?: boolean | undefined;
-    }): void;
-    expand(): {
-        expandedExpression?: string;
-        miniscript?: string;
-        expandedMiniscript?: string;
-        expansionMap?: ExpansionMap;
-    };
-}
-export interface DescriptorInterfaceConstructor {
-    new (args: DescriptorInfo): DescriptorInterface;
+/**
+ * The {@link DescriptorsFactory | `DescriptorsFactory`} function creates and
+ * returns the `parseKeyExpression` function, which is an implementation of this
+ * interface.
+ *
+ * It parses and destructures a key expression string (xpub, xprv, pubkey or
+ * wif) into {@link KeyInfo | `KeyInfo`}.
+ *
+ * For example, given this `keyExpression`: `[d34db33f/49'/0'/0']tpubDCdxmvzJ5QBjTN8oCjjyT2V58AyZvA1fkmCeZRC75QMoaHcVP2m45Bv3hmnR7ttAwkb2UNYyoXdHVt4gwBqRrJqLUU2JrM43HippxiWpHra/1/2/3/4/*`, this is the parsed result:
+ *
+ * ```javascript
+ *  {
+ *    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 of the type `KeyInfo`: `pubkey`, `ecpair` & `bip32` interfaces, `masterFingerprint`, etc.
+ *  }
+ * ```
+ *
+ * See {@link KeyInfo} for the complete list of elements retrieved by this function.
+ */
+export interface ParseKeyExpression {
+    (params: {
+        keyExpression: string;
+        /**
+         * Indicates if this key expression belongs to a a SegWit output. When set,
+         * further checks are done to ensure the public key (if present in the
+         * expression) is compressed (33 bytes).
+         */
+        isSegwit?: boolean;
+        network?: Network;
+    }): KeyInfo;
 }
 export {};

package/package.json

@@ -1,39 +1,10 @@
 {
   "name": "@bitcoinerlab/descriptors",
-  "homepage": "https://github.com/bitcoinerlab/descriptors",
-  "version": "1.0.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",
-  "scripts": {
-    "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 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",
-    "test": "npm run lint && npm run lint:test && npm run test:unit && npm run test:integration:soft",
-    "lint": "eslint --ignore-path .gitignore --ext .js,.ts src/",
-    "lint:test": "eslint --ignore-path .gitignore --ext .js,.ts test/"
-  },
-  "COMMENT_babel": "Babel plugins are are only needed for the jest testing environment. Jest needs to use commonjs. Also, jest cannot handle ESM converted code, since it uses 'import.meta.url'. See src/bindings.js. babel-plugin-transform-import-meta fixes it.",
-  "babel": {
-    "env": {
-      "test": {
-        "plugins": [
-          "@babel/plugin-transform-modules-commonjs",
-          "babel-plugin-transform-import-meta"
-        ]
-      }
-    }
-  },
-  "jest": {
-    "testPathIgnorePatterns": [
-      "example/",
-      "dist/"
-    ]
-  },
+  "homepage": "https://github.com/bitcoinerlab/descriptors",
+  "version": "2.0.0",
+  "author": "Jose-Luis Landabaso",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/bitcoinerlab/descriptors.git"
@@ -44,11 +15,35 @@
     "bitcoinjs",
     "miniscript"
   ],
-  "author": "Jose-Luis Landabaso",
-  "license": "MIT",
   "bugs": {
     "url": "https://github.com/bitcoinerlab/descriptors/issues"
   },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "prettier": "@bitcoinerlab/configs/prettierConfig.json",
+  "eslintConfig": {
+    "extends": "./node_modules/@bitcoinerlab/configs/eslintConfig"
+  },
+  "jest": {
+    "preset": "@bitcoinerlab/configs"
+  },
+  "scripts": {
+    "webdocs": "typedoc --options ./node_modules/@bitcoinerlab/configs/webtypedoc.json",
+    "docs": "typedoc --options ./node_modules/@bitcoinerlab/configs/typedoc.json",
+    "build:src": "tsc --project ./node_modules/@bitcoinerlab/configs/tsconfig.src.json",
+    "build:fixtures": "node test/tools/generateBitcoinCoreFixtures.js -i test/fixtures/descriptor_tests.cpp | npx prettier --parser typescript > test/fixtures/bitcoinCore.ts",
+    "build:test": "npm run build:fixtures && tsc --project ./node_modules/@bitcoinerlab/configs/tsconfig.test.json",
+    "build": "npm run build:src && npm run build:test",
+    "lint": "eslint --ignore-path .gitignore --ext .ts src/ test/",
+    "ensureTester": "./node_modules/@bitcoinerlab/configs/scripts/ensureTester.sh",
+    "test:integration:soft": "npm run ensureTester && node test/integration/standardOutputs.js && echo \"\\n\\n\" && node test/integration/miniscript.js",
+    "test:integration:ledger": "npm run ensureTester && node test/integration/ledger.js",
+    "test:integration:deprecated": "npm run ensureTester && node test/integration/standardOutputs-deprecated.js && echo \"\\n\\n\" && node test/integration/miniscript-deprecated.js && echo \"\\n\\n\" && node test/integration/ledger-deprecated.js",
+    "test:unit": "jest",
+    "test": "npm run lint && npm run build && npm run test:unit && npm run test:integration:soft",
+    "testledger": "npm run lint && npm run build && npm run test:integration:ledger",
+    "prepublishOnly": "npm run test && echo \"\\n\\n\" && npm run test:integration:deprecated && npm run test:integration:ledger"
+  },
   "files": [
     "dist"
   ],
@@ -61,27 +56,14 @@
     }
   },
   "devDependencies": {
-    "@babel/plugin-transform-modules-commonjs": "^7.20.11",
+    "@bitcoinerlab/configs": "github:bitcoinerlab/configs",
     "@ledgerhq/hw-transport-node-hid": "^6.27.12",
-    "@typescript-eslint/eslint-plugin": "^5.60.1",
-    "@typescript-eslint/parser": "^5.60.1",
-    "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",
-    "eslint-config-prettier": "^8.6.0",
-    "eslint-plugin-jest": "^27.2.1",
-    "eslint-plugin-prettier": "^4.2.1",
-    "fs": "^0.0.1-security",
-    "jest": "^29.4.3",
-    "jsdoc": "^3.6.11",
     "ledger-bitcoin": "^0.2.2",
-    "path": "^0.12.7",
-    "prettier": "^2.8.8",
     "regtest-client": "^0.2.0",
-    "ts-node-dev": "^2.0.0",
-    "typescript": "5.0"
+    "yargs": "^17.7.2"
   },
   "dependencies": {
     "@bitcoinerlab/miniscript": "^1.2.1",