@bitcoinerlab/descriptors 1.1.1 → 2.0.0

package/dist/index.d.ts

@@ -1,23 +1,43 @@
 export type { KeyInfo, Expansion } from './types';
 import type { Psbt } from 'bitcoinjs-lib';
-import type { DescriptorInstance } from './descriptors';
-export { DescriptorsFactory, DescriptorInstance, DescriptorConstructor } from './descriptors';
+import type { DescriptorInstance, OutputInstance } from './descriptors';
+export { DescriptorsFactory, DescriptorInstance, DescriptorConstructor, OutputInstance, OutputConstructor } from './descriptors';
 export { DescriptorChecksum as checksum } from './checksum';
 import * as signers from './signers';
 export { signers };
-export declare function finalizePsbt({ psbt, descriptors, validate }: {
+/**
+ * @hidden @deprecated
+ * To finalize the `psbt`, you can either call the method
+ * `output.finalizePsbtInput({ index, psbt })` on each descriptor, passing as
+ * arguments the `psbt` and its input `index`, or call this helper function:
+ * `finalizePsbt({psbt, outputs })`. In the latter case, `outputs` is an
+ * array of {@link _Internal_.Output | Output elements} ordered in the array by
+ * their respective input index in the `psbt`.
+ */
+declare function finalizePsbt(params: {
+    psbt: Psbt;
+    outputs: OutputInstance[];
+    validate?: boolean | undefined;
+}): void;
+/**
+ * @deprecated
+ * @hidden
+ * To be removed in version 3.0
+ */
+declare function finalizePsbt(params: {
     psbt: Psbt;
     descriptors: DescriptorInstance[];
     validate?: boolean | undefined;
 }): void;
+export { finalizePsbt };
 export { keyExpressionBIP32, keyExpressionLedger } from './keyExpressions';
 import * as scriptExpressions from './scriptExpressions';
 export { scriptExpressions };
-import { LedgerState, getLedgerMasterFingerPrint, getLedgerXpub, registerLedgerWallet, assertLedgerApp } from './ledger';
+import { LedgerState, getLedgerMasterFingerPrint, getLedgerXpub, registerLedgerWallet, assertLedgerApp, LedgerManager } from './ledger';
 export declare const ledger: {
     getLedgerMasterFingerPrint: typeof getLedgerMasterFingerPrint;
     getLedgerXpub: typeof getLedgerXpub;
     registerLedgerWallet: typeof registerLedgerWallet;
     assertLedgerApp: typeof assertLedgerApp;
 };
-export type { LedgerState };
+export type { LedgerState, LedgerManager };

package/dist/index.js

@@ -32,8 +32,18 @@ var checksum_1 = require("./checksum");
 Object.defineProperty(exports, "checksum", { enumerable: true, get: function () { return checksum_1.DescriptorChecksum; } });
 const signers = __importStar(require("./signers"));
 exports.signers = signers;
-function finalizePsbt({ psbt, descriptors, validate = true }) {
-    descriptors.forEach((descriptor, inputIndex) => descriptor.finalizePsbtInput({ index: inputIndex, psbt, validate }));
+/**
+ * @hidden
+ * To be removed in v3.0 and replaced by the version with the signature that
+ * does not accept descriptors
+ */
+function finalizePsbt({ psbt, outputs, descriptors, validate = true }) {
+    if (descriptors && outputs)
+        throw new Error(`descriptors param has been deprecated`);
+    outputs = descriptors || outputs;
+    if (!outputs)
+        throw new Error(`outputs not provided`);
+    outputs.forEach((output, inputIndex) => output.finalizePsbtInput({ index: inputIndex, psbt, validate }));
 }
 exports.finalizePsbt = finalizePsbt;
 var keyExpressions_1 = require("./keyExpressions");

package/dist/keyExpressions.d.ts

@@ -2,22 +2,59 @@ import { Network } from 'bitcoinjs-lib';
 import type { ECPairAPI } from 'ecpair';
 import type { BIP32API, BIP32Interface } from 'bip32';
 import type { KeyInfo } from './types';
-import { LedgerState } from './ledger';
+import { LedgerState, LedgerManager } from './ledger';
 /**
- * Parses a key expression (xpub, xprv, pubkey or wif) into KeyInfo
+ * Parses a key expression (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 its 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.
+ *  }
+ * ```
  */
 export declare function parseKeyExpression({ keyExpression, isSegwit, ECPair, BIP32, network }: {
     keyExpression: string;
+    /** @default networks.bitcoin */
     network?: Network;
     /**
-     * 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;
     ECPair: ECPairAPI;
     BIP32: BIP32API;
 }): KeyInfo;
+/**
+ * Constructs a key expression string for a Ledger device from the provided
+ * components.
+ *
+ * This function assists in crafting key expressions tailored for Ledger
+ * hardware wallets. It fetches the master fingerprint and xpub for a
+ * specified origin path and then combines them with the input parameters.
+ *
+ * For detailed understanding and examples of terms like `originPath`,
+ * `change`, and `keyPath`, refer to the documentation of
+ * {@link _Internal_.ParseKeyExpression | ParseKeyExpression}, which consists
+ * of the reverse procedure.
+ *
+ * @returns {string} - The formed key expression for the Ledger device.
+ */
+export declare function keyExpressionLedger({ ledgerManager, originPath, keyPath, change, index }: {
+    ledgerManager: LedgerManager;
+    originPath: string;
+    change?: number | undefined;
+    index?: number | undefined | '*';
+    keyPath?: string | undefined;
+}): Promise<string>;
+/** @deprecated @hidden */
 export declare function keyExpressionLedger({ ledgerClient, ledgerState, originPath, keyPath, change, index }: {
     ledgerClient: unknown;
     ledgerState: LedgerState;
@@ -26,11 +63,23 @@ export declare function keyExpressionLedger({ ledgerClient, ledgerState, originP
     index?: number | undefined | '*';
     keyPath?: string | undefined;
 }): Promise<string>;
+/**
+ * Constructs a key expression string from its constituent components.
+ *
+ * This function essentially performs the reverse operation of
+ * {@link _Internal_.ParseKeyExpression | ParseKeyExpression}. For detailed
+ * explanations and examples of the terms used here, refer to
+ * {@link _Internal_.ParseKeyExpression | ParseKeyExpression}.
+ */
 export declare function keyExpressionBIP32({ masterNode, originPath, keyPath, change, index, isPublic }: {
     masterNode: BIP32Interface;
     originPath: string;
     change?: number | undefined;
     index?: number | undefined | '*';
     keyPath?: string | undefined;
+    /**
+     * Compute an xpub or xprv
+     * @default true
+     */
     isPublic?: boolean;
 }): string;

package/dist/keyExpressions.js

@@ -44,7 +44,20 @@ const derivePath = (node, path) => {
     return node.derivePath(parsedPath);
 };
 /**
- * Parses a key expression (xpub, xprv, pubkey or wif) into KeyInfo
+ * Parses a key expression (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 its 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.
+ *  }
+ * ```
  */
 function parseKeyExpression({ keyExpression, isSegwit, ECPair, BIP32, network = bitcoinjs_lib_1.networks.bitcoin }) {
     let pubkey; //won't be computed for ranged keyExpressions
@@ -167,7 +180,14 @@ function assertChangeIndexKeyPath({ change, index, keyPath }) {
     if ((change !== undefined) === (keyPath !== undefined))
         throw new Error(`Error: Pass either change and index or a keyPath`);
 }
-async function keyExpressionLedger({ ledgerClient, ledgerState, originPath, keyPath, change, index }) {
+/** @hidden */
+async function keyExpressionLedger({ ledgerClient, ledgerState, ledgerManager, originPath, keyPath, change, index }) {
+    if (ledgerManager && (ledgerClient || ledgerState))
+        throw new Error(`ledgerClient and ledgerState have been deprecated`);
+    if (ledgerManager)
+        ({ ledgerClient, ledgerState } = ledgerManager);
+    if (!ledgerClient || !ledgerState)
+        throw new Error(`Could not retrieve ledgerClient or ledgerState`);
     assertChangeIndexKeyPath({ change, index, keyPath });
     const masterFingerprint = await (0, ledger_1.getLedgerMasterFingerPrint)({
         ledgerClient,
@@ -182,6 +202,14 @@ async function keyExpressionLedger({ ledgerClient, ledgerState, originPath, keyP
         return `${keyRoot}/${change}/${index}`;
 }
 exports.keyExpressionLedger = keyExpressionLedger;
+/**
+ * Constructs a key expression string from its constituent components.
+ *
+ * This function essentially performs the reverse operation of
+ * {@link _Internal_.ParseKeyExpression | ParseKeyExpression}. For detailed
+ * explanations and examples of the terms used here, refer to
+ * {@link _Internal_.ParseKeyExpression | ParseKeyExpression}.
+ */
 function keyExpressionBIP32({ masterNode, originPath, keyPath, change, index, isPublic = true }) {
     assertChangeIndexKeyPath({ change, index, keyPath });
     const masterFingerprint = masterNode.fingerprint;

package/dist/ledger.d.ts

@@ -1,5 +1,7 @@
 /// <reference types="node" />
-import type { DescriptorInstance } from './descriptors';
+import { DescriptorInstance, OutputInstance } from './descriptors';
+import { Network, Psbt } from 'bitcoinjs-lib';
+import type { TinySecp256k1Interface } from './types';
 /**
  * Dynamically imports the 'ledger-bitcoin' module and, if provided, checks if `ledgerClient` is an instance of `AppClient`.
  *
@@ -19,9 +21,28 @@ import type { DescriptorInstance } from './descriptors';
  *   .catch((error) => console.error(error));
  */
 export declare function importAndValidateLedgerBitcoin(ledgerClient?: unknown): Promise<unknown>;
+/**
+ * Verifies if the Ledger device is connected, if the required Bitcoin App is opened,
+ * and if the version of the app meets the minimum requirements.
+ *
+ * @throws Will throw an error if the Ledger device is not connected, the required
+ * Bitcoin App is not opened, or if the version is below the required number.
+ *
+ * @returns Promise<void> - A promise that resolves if all assertions pass, or throws otherwise.
+ */
 export declare function assertLedgerApp({ transport, name, minVersion }: {
+    /**
+     * Connection transport with the Ledger device.
+     * One of these: https://github.com/LedgerHQ/ledger-live#libs---libraries
+     */
     transport: any;
+    /**
+     * The name of the Bitcoin App. "Bitcoin" for mainnet or "Bitcoin Test" for testnet.
+     */
     name: string;
+    /**
+     * The minimum acceptable version of the Bitcoin App in semver format (major.minor.patch).
+     */
     minVersion: string;
 }): Promise<void>;
 export type LedgerPolicy = {
@@ -31,6 +52,11 @@ export type LedgerPolicy = {
     policyId?: Buffer;
     policyHmac?: Buffer;
 };
+/**
+ * Ledger devices operate in a state-less manner. Therefore, policy information
+ * needs to be maintained in a separate data structure, `ledgerState`. For optimization,
+ * `ledgerState` also stores cached xpubs and the masterFingerprint.
+ */
 export type LedgerState = {
     masterFingerprint?: Buffer;
     policies?: LedgerPolicy[];
@@ -38,17 +64,49 @@ export type LedgerState = {
         [key: string]: string;
     };
 };
+export type LedgerManager = {
+    ledgerClient: unknown;
+    ledgerState: LedgerState;
+    ecc: TinySecp256k1Interface;
+    network: Network;
+};
+/** Retrieves the masterFingerPrint of a Ledger device */
+export declare function getLedgerMasterFingerPrint({ ledgerManager }: {
+    ledgerManager: LedgerManager;
+}): Promise<Buffer>;
+/** @deprecated @hidden */
 export declare function getLedgerMasterFingerPrint({ ledgerClient, ledgerState }: {
     ledgerClient: unknown;
     ledgerState: LedgerState;
 }): Promise<Buffer>;
+/** Retrieves the xpub of a certain originPath of a Ledger device */
+export declare function getLedgerXpub({ originPath, ledgerManager }: {
+    originPath: string;
+    ledgerManager: LedgerManager;
+}): Promise<string>;
+/** @deprecated @hidden */
 export declare function getLedgerXpub({ originPath, ledgerClient, ledgerState }: {
     originPath: string;
     ledgerClient: unknown;
     ledgerState: LedgerState;
 }): Promise<string>;
 /**
- * Takes a descriptor and gets its Ledger Wallet Policy, that is, its keyRoots and template.
+ * Checks whether there is a policy in ledgerState that the ledger
+ * could use to sign this psbt input.
+ *
+ * It found return the policy, otherwise, return undefined
+ *
+ * All considerations in the header of this file are applied
+ */
+export declare function ledgerPolicyFromPsbtInput({ ledgerManager, psbt, index }: {
+    ledgerManager: LedgerManager;
+    psbt: Psbt;
+    index: number;
+}): Promise<LedgerPolicy | undefined>;
+/**
+ * Given an output, it extracts its descriptor and converts it to a Ledger
+ * Wallet Policy, that is, its keyRoots and template.
+ *
  * keyRoots and template follow Ledger's specifications:
  * https://github.com/LedgerHQ/app-bitcoin-new/blob/develop/doc/wallet.md
  *
@@ -72,8 +130,8 @@ export declare function getLedgerXpub({ originPath, ledgerClient, ledgerState }:
  * This function takes into account all the considerations regarding Ledger
  * policy implementation details expressed in the header of this file.
  */
-export declare function descriptorToLedgerFormat({ descriptor, ledgerClient, ledgerState }: {
-    descriptor: DescriptorInstance;
+export declare function ledgerPolicyFromOutput({ output, ledgerClient, ledgerState }: {
+    output: OutputInstance;
     ledgerClient: unknown;
     ledgerState: LedgerState;
 }): Promise<{
@@ -81,12 +139,31 @@ export declare function descriptorToLedgerFormat({ descriptor, ledgerClient, led
     keyRoots: string[];
 } | null>;
 /**
- * It registers a policy based on a descriptor. It stores it in ledgerState.
+ * Registers a policy based on a provided descriptor.
  *
- * If the policy was already registered, it does not register it.
- * If the policy is standard, it does not register it.
+ * This function will:
+ * 1. Store the policy in `ledgerState` inside the `ledgerManager`.
+ * 2. Avoid re-registering if the policy was previously registered.
+ * 3. Skip registration if the policy is considered "standard".
  *
- **/
+ * It's important to understand the nature of the Ledger Policy being registered:
+ * - While a descriptor might point to a specific output index of a particular change address,
+ *   the corresponding Ledger Policy abstracts this and represents potential outputs for
+ *   all addresses (both external and internal).
+ * - This means that the registered Ledger Policy is a generalized version of the descriptor,
+ *   not assuming specific values for the keyPath.
+ *
+ */
+export declare function registerLedgerWallet({ descriptor, ledgerManager, policyName }: {
+    descriptor: string;
+    ledgerManager: LedgerManager;
+    /** The Name we want to assign to this specific policy */
+    policyName: string;
+}): Promise<void>;
+/**
+ * @deprecated
+ * @hidden
+ */
 export declare function registerLedgerWallet({ descriptor, ledgerClient, ledgerState, policyName }: {
     descriptor: DescriptorInstance;
     ledgerClient: unknown;
@@ -96,8 +173,8 @@ export declare function registerLedgerWallet({ descriptor, ledgerClient, ledgerS
 /**
  * Retrieve a standard ledger policy or null if it does correspond.
  **/
-export declare function ledgerPolicyFromStandard({ descriptor, ledgerClient, ledgerState }: {
-    descriptor: DescriptorInstance;
+export declare function ledgerPolicyFromStandard({ output, ledgerClient, ledgerState }: {
+    output: OutputInstance;
     ledgerClient: unknown;
     ledgerState: LedgerState;
 }): Promise<LedgerPolicy | null>;
@@ -105,8 +182,8 @@ export declare function comparePolicies(policyA: LedgerPolicy, policyB: LedgerPo
 /**
  * Retrieve a ledger policy from ledgerState or null if it does not exist yet.
  **/
-export declare function ledgerPolicyFromState({ descriptor, ledgerClient, ledgerState }: {
-    descriptor: DescriptorInstance;
+export declare function ledgerPolicyFromState({ output, ledgerClient, ledgerState }: {
+    output: OutputInstance;
     ledgerClient: unknown;
     ledgerState: LedgerState;
 }): Promise<LedgerPolicy | null>;