@bitcoinerlab/descriptors 1.1.1 → 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

@@ -23,6 +23,9 @@ export type TimeConstraints = {
     nLockTime: number | undefined;
     nSequence: number | undefined;
 };
+/**
+ * See {@link _Internal_.ParseKeyExpression | ParseKeyExpression}.
+ */
 export type KeyInfo = {
     keyExpression: string;
     pubkey?: Buffer;
@@ -33,6 +36,35 @@ 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;
 };
@@ -56,6 +88,11 @@ export interface TinySecp256k1Interface {
     xOnlyPointAddTweak(p: Uint8Array, tweak: Uint8Array): XOnlyPointAddTweakResult | null;
     privateNegate(d: Uint8Array): Uint8Array;
 }
+/**
+ * `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 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.
@@ -63,6 +100,7 @@ export type Expansion = {
     payment?: Payment;
     /**
      * The expanded descriptor expression.
+     * See {@link ExpansionMap ExpansionMap} for a detailed explanation.
      */
     expandedExpression?: string;
     /**
@@ -71,14 +109,17 @@ export type Expansion = {
     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 represents a SegWit script.
+     * 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;
     /**
@@ -90,56 +131,47 @@ export type Expansion = {
      */
     witnessScript?: Buffer;
     /**
-     * Whether this expression represents a ranged-descriptor.
+     * Whether the descriptor is a ranged-descriptor.
      */
     isRanged: boolean;
     /**
-     * This is the preferred or authoritative representation of the descriptor expression.
+     * 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;
 };
 /**
- * The {@link DescriptorsFactory | `DescriptorsFactory`} function creates and returns an implementation of the `Expand` interface.
- * This returned implementation is tailored for the provided `TinySecp256k1Interface`.
- */
-export interface Expand {
-    (params: {
-        /**
-         * The descriptor expression to be expanded.
-         */
-        expression: string;
-        /**
-         * The descriptor index, if ranged.
-         */
-        index?: number;
-        /**
-         * A flag indicating whether the descriptor is required to include a checksum.
-         * @defaultValue false
-         */
-        checksumRequired?: boolean;
-        /**
-         * The Bitcoin network to use.
-         * @defaultValue `networks.bitcoin`
-         */
-        network?: Network;
-        /**
-         * Flag to allow miniscript in P2SH.
-         * @defaultValue false
-         */
-        allowMiniscriptInP2SH?: boolean;
-    }): Expansion;
-}
-/**
- * The {@link DescriptorsFactory | `DescriptorsFactory`} function creates and returns an implementation of the `ParseKeyExpression` interface.
- * This returned implementation is tailored for the provided `TinySecp256k1Interface`.
+ * 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 is a SegWit key expression. When set, further checks
-         * ensure the public key (if present in the expression) is compressed
-         * (33 bytes).
+         * 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;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@bitcoinerlab/descriptors",
   "description": "This library parses and creates Bitcoin Miniscript Descriptors and generates Partially Signed Bitcoin Transactions (PSBTs). It provides PSBT finalizers and signers for single-signature, BIP32 and Hardware Wallets.",
   "homepage": "https://github.com/bitcoinerlab/descriptors",
-  "version": "1.1.1",
+  "version": "2.0.0",
   "author": "Jose-Luis Landabaso",
   "license": "MIT",
   "repository": {
@@ -38,10 +38,11 @@
     "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:ledger"
+    "prepublishOnly": "npm run test && echo \"\\n\\n\" && npm run test:integration:deprecated && npm run test:integration:ledger"
   },
   "files": [
     "dist"