@bitcoinerlab/descriptors-core 3.1.0

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export type { Expansion, ExpansionMap, KeyExpressionParser, KeyInfo, Preimage, TimeConstraints } from './types';
+export type { TreeNode, TapTreeNode, TapTreeInfoNode, TapLeaf, TapLeafInfo } from './tapTree';
+export { networks, type Network } from './networks';
+export { DescriptorsFactory, OutputInstance, OutputConstructor } from './descriptors';
+export { DescriptorChecksum as checksum } from './checksum';
+import * as signers from './signers';
+export { signers };
+export { keyExpressionBIP32, keyExpressionLedger } from './keyExpressions';
+import * as scriptExpressions from './scriptExpressions';
+export { scriptExpressions };
+import { LedgerState, getLedgerMasterFingerPrint, getLedgerXpub, registerLedgerWallet, assertLedgerApp, LedgerManager } from './ledger';
+/** @namespace */
+export declare const ledger: {
+    /** @function */
+    getLedgerMasterFingerPrint: typeof getLedgerMasterFingerPrint;
+    /** @function */
+    getLedgerXpub: typeof getLedgerXpub;
+    /** @function */
+    registerLedgerWallet: typeof registerLedgerWallet;
+    /** @function */
+    assertLedgerApp: typeof assertLedgerApp;
+};
+export type { LedgerState, LedgerManager };

package/dist/index.js

@@ -0,0 +1,87 @@
+"use strict";
+// Copyright (c) 2023 Jose-Luis Landabaso - https://bitcoinerlab.com
+// Distributed under the MIT software license
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ledger = exports.scriptExpressions = exports.keyExpressionLedger = exports.keyExpressionBIP32 = exports.signers = exports.checksum = exports.DescriptorsFactory = exports.networks = void 0;
+// Some dependencies (like hash-base) assume process.version exists.
+// In React Native / Hermes, process is defined but version is not.
+// Note: we only polyfill if process already exists but is incomplete.
+// The user is responsible for providing the process polyfill; this is just
+// a small patch for environments (like Hermes) with partial implementations.
+//
+// More information: https://github.com/browserify/hash-base/issues/21#issuecomment-3476608003
+const g = typeof globalThis !== 'undefined'
+    ? globalThis
+    : typeof global !== 'undefined'
+        ? global
+        : {};
+if (typeof g.process !== 'undefined' &&
+    typeof g.process.version === 'undefined') {
+    const isDev = g['__DEV__'] === true ||
+        g.process?.env?.['NODE_ENV'] === 'development';
+    if (isDev) {
+        //only WARN while developing
+        console.warn(`[bitcoinerlab/descriptors] Polyfilled process.version (missing in this non-Node environment).
+Learn more: https://github.com/bitcoinerlab/descriptors/blob/main/src/index.ts#L4`);
+    }
+    // @ts-expect-error Polyfill for environments missing process.version
+    global.process.version = '';
+}
+var networks_1 = require("./networks");
+Object.defineProperty(exports, "networks", { enumerable: true, get: function () { return networks_1.networks; } });
+var descriptors_1 = require("./descriptors");
+Object.defineProperty(exports, "DescriptorsFactory", { enumerable: true, get: function () { return descriptors_1.DescriptorsFactory; } });
+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;
+var keyExpressions_1 = require("./keyExpressions");
+Object.defineProperty(exports, "keyExpressionBIP32", { enumerable: true, get: function () { return keyExpressions_1.keyExpressionBIP32; } });
+Object.defineProperty(exports, "keyExpressionLedger", { enumerable: true, get: function () { return keyExpressions_1.keyExpressionLedger; } });
+const scriptExpressions = __importStar(require("./scriptExpressions"));
+exports.scriptExpressions = scriptExpressions;
+const ledger_1 = require("./ledger");
+/** @namespace */
+exports.ledger = {
+    /** @function */
+    getLedgerMasterFingerPrint: ledger_1.getLedgerMasterFingerPrint,
+    /** @function */
+    getLedgerXpub: ledger_1.getLedgerXpub,
+    /** @function */
+    registerLedgerWallet: ledger_1.registerLedgerWallet,
+    /** @function */
+    assertLedgerApp: ledger_1.assertLedgerApp
+};

package/dist/keyExpressions.d.ts

@@ -0,0 +1,124 @@
+import type { ECPairAPILike, BIP32APILike, BIP32InterfaceLike, ScureHDKeyLike } from './bitcoinLib';
+import { type Network } from './networks';
+import type { KeyInfo } from './types';
+import { LedgerManager } from './ledger';
+/**
+ * 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 `KeyInfo`: `pubkey`, `ecpair`, `bip32`,
+ *    // `privkey`, `xPub`, `xPrv`, `masterFingerprint`, etc.
+ *  }
+ * ```
+ */
+export declare function parseKeyExpression({ keyExpression, isSegwit, isTaproot, ECPair, BIP32, network }: {
+    keyExpression: string;
+    /** @default networks.bitcoin */
+    network?: Network;
+    /**
+     * 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;
+    /**
+     * Indicates if this key expression belongs to a Taproot output. For Taproot,
+     * the key must be represented as an x-only public key (32 bytes).
+     * If a 33-byte compressed pubkey is derived, it is converted to its x-only
+     * representation.
+     */
+    isTaproot?: boolean;
+    ECPair: ECPairAPILike;
+    BIP32: BIP32APILike;
+}): 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 KeyExpressionParser}, which consists
+ * of the reverse procedure.
+ *
+ * @returns {Promise<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>;
+/**
+ * Constructs a BIP32 key expression string from its constituent components.
+ *
+ * This function essentially performs the reverse operation of
+ * {@link KeyExpressionParser}. For detailed
+ * explanations and examples of the terms used here, refer to
+ * {@link KeyExpressionParser}.
+ *
+ * @param {Object} params - The parameters object.
+ * @param {BIP32InterfaceLike | ScureHDKeyLike} params.masterNode - Root HD node.
+ * Pass either:
+ * - a bitcoinjs {@link https://github.com/bitcoinjs/bip32 | `BIP32`} node, or
+ * - a scure {@link https://github.com/paulmillr/scure-bip32 | `HDKey`}.
+ * @param {string} params.originPath - Origin path from master, e.g. `"/84'/0'/0'"`.
+ * @param {number} [params.change] - Branch index (`0` receive, `1` change).
+ * @param {number | '*'} [params.index] - Address index or `*` for ranged descriptors.
+ * @param {string} [params.keyPath] - Full suffix path (`/change/index`) alternative to
+ * `change` + `index`.
+ * @returns {string} Descriptor key expression (e.g. `[f23f9fd2/84'/0'/0']xpub.../0/5`).
+ *
+ * @example
+ * ```ts
+ * import * as ecc from '@bitcoinerlab/secp256k1';
+ * import { BIP32Factory } from 'bip32';
+ * import { keyExpressionBIP32 } from '@bitcoinerlab/descriptors';
+ *
+ * const BIP32 = BIP32Factory(ecc);
+ * const masterNode = BIP32.fromSeed(seedBytes);
+ * const keyExp = keyExpressionBIP32({
+ *   masterNode,
+ *   originPath: "/84'/0'/0'",
+ *   change: 0,
+ *   index: 5
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { HDKey } from '@scure/bip32';
+ * import { keyExpressionBIP32 } from '@bitcoinerlab/descriptors';
+ *
+ * const masterNode = HDKey.fromMasterSeed(seedBytes);
+ * const keyExp = keyExpressionBIP32({
+ *   masterNode,
+ *   originPath: "/84'/0'/0'",
+ *   keyPath: '/0/*'
+ * });
+ * ```
+ */
+export declare function keyExpressionBIP32({ masterNode, originPath, keyPath, change, index, isPublic }: {
+    masterNode: BIP32InterfaceLike | ScureHDKeyLike;
+    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

@@ -0,0 +1,310 @@
+"use strict";
+// Copyright (c) 2023 Jose-Luis Landabaso - https://bitcoinerlab.com
+// Distributed under the MIT software license
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseKeyExpression = parseKeyExpression;
+exports.keyExpressionLedger = keyExpressionLedger;
+exports.keyExpressionBIP32 = keyExpressionBIP32;
+const networks_1 = require("./networks");
+const ledger_1 = require("./ledger");
+const keyInterfaces_1 = require("./keyInterfaces");
+const uint8array_tools_1 = require("uint8array-tools");
+const RE = __importStar(require("./re"));
+const derivePath = (node, path) => {
+    if (typeof path !== 'string') {
+        throw new Error(`Error: invalid derivation path ${path}`);
+    }
+    const parsedPath = path.replaceAll('H', "'").replaceAll('h', "'").slice(1);
+    const splitPath = parsedPath.split('/');
+    for (const element of splitPath) {
+        const unhardened = element.endsWith("'") ? element.slice(0, -1) : element;
+        if (!Number.isInteger(Number(unhardened)) ||
+            Number(unhardened) >= 0x80000000)
+            throw new Error(`Error: BIP 32 path element overflow`);
+    }
+    return node.derivePath(parsedPath);
+};
+/**
+ * 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 `KeyInfo`: `pubkey`, `ecpair`, `bip32`,
+ *    // `privkey`, `xPub`, `xPrv`, `masterFingerprint`, etc.
+ *  }
+ * ```
+ */
+function parseKeyExpression({ keyExpression, isSegwit, isTaproot, ECPair, BIP32, network = networks_1.networks.bitcoin }) {
+    if (isTaproot && isSegwit !== true)
+        throw new Error(`Error: taproot key expressions require isSegwit`);
+    let pubkey; //won't be computed for ranged keyExpressions
+    let ecpair;
+    let bip32;
+    let privkey;
+    let xPub;
+    let xPrv;
+    let masterFingerprint;
+    let originPath;
+    let keyPath;
+    let path;
+    const isRanged = keyExpression.indexOf('*') !== -1;
+    const reKeyExp = isTaproot
+        ? RE.reTaprootKeyExp
+        : isSegwit
+            ? RE.reSegwitKeyExp
+            : RE.reNonSegwitKeyExp;
+    const rePubKey = isTaproot
+        ? RE.reTaprootPubKey
+        : isSegwit
+            ? RE.reSegwitPubKey
+            : RE.reNonSegwitPubKey;
+    //Validate the keyExpression:
+    const keyExpressions = keyExpression.match(reKeyExp);
+    if (keyExpressions === null || keyExpressions[0] !== keyExpression) {
+        throw new Error(`Error: expected a keyExpression but got ${keyExpression}`);
+    }
+    const reOriginAnchoredStart = RegExp(String.raw `^(${RE.reOrigin})?`); //starts with ^origin
+    const mOrigin = keyExpression.match(reOriginAnchoredStart);
+    if (mOrigin) {
+        const bareOrigin = mOrigin[0].replace(/[[\]]/g, ''); //strip the "[" and "]" in [origin]
+        const reMasterFingerprintAnchoredStart = String.raw `^(${RE.reMasterFingerprint})`;
+        const mMasterFingerprint = bareOrigin.match(reMasterFingerprintAnchoredStart);
+        const masterFingerprintHex = mMasterFingerprint
+            ? mMasterFingerprint[0]
+            : '';
+        originPath = bareOrigin.replace(masterFingerprintHex, '');
+        if (masterFingerprintHex.length > 0) {
+            if (masterFingerprintHex.length !== 8)
+                throw new Error(`Error: masterFingerprint ${masterFingerprintHex} invalid for keyExpression: ${keyExpression}`);
+            masterFingerprint = (0, uint8array_tools_1.fromHex)(masterFingerprintHex);
+        }
+    }
+    //Remove the origin (if it exists) and store result in actualKey
+    const actualKey = keyExpression.replace(reOriginAnchoredStart, '');
+    let mPubKey, mWIF, mXpubKey, mXprvKey;
+    //match pubkey:
+    if ((mPubKey = actualKey.match(RE.anchorStartAndEnd(rePubKey))) !== null) {
+        pubkey = (0, uint8array_tools_1.fromHex)(mPubKey[0]);
+        if (isTaproot && pubkey.length === 32)
+            //convert the xonly point to a compressed point assuming even parity
+            pubkey = (0, uint8array_tools_1.concat)([Uint8Array.from([0x02]), pubkey]);
+        ecpair = ECPair.fromPublicKey(pubkey, { network });
+        //Validate the pubkey (compressed or uncompressed)
+        if (!ECPair.isPoint(pubkey) ||
+            !(pubkey.length === 33 || pubkey.length === 65)) {
+            throw new Error(`Error: invalid pubkey`);
+        }
+        //Do an extra check in case we know this pubkey refers to a segwit input
+        //Taproot x-only keys are converted to 33-byte compressed form above.
+        if (typeof isSegwit === 'boolean' &&
+            isSegwit &&
+            pubkey.length !== 33 //Inside wpkh and wsh, only compressed public keys are permitted.
+        ) {
+            throw new Error(`Error: invalid pubkey`);
+        }
+        //match WIF:
+    }
+    else if ((mWIF = actualKey.match(RE.anchorStartAndEnd(RE.reWIF))) !== null) {
+        ecpair = ECPair.fromWIF(mWIF[0], network);
+        //fromWIF will throw if the wif is not valid
+        pubkey = ecpair.publicKey;
+        privkey = ecpair.privateKey;
+        //match xpub:
+    }
+    else if ((mXpubKey = actualKey.match(RE.anchorStartAndEnd(RE.reXpubKey))) !== null) {
+        const xPubKey = mXpubKey[0];
+        xPub = xPubKey.match(RE.reXpub)?.[0];
+        if (!xPub)
+            throw new Error(`Error: xpub could not be matched`);
+        bip32 = BIP32.fromBase58(xPub, network);
+        const mPath = xPubKey.match(RE.rePath);
+        if (mPath !== null) {
+            keyPath = xPubKey.match(RE.rePath)?.[0];
+            if (!keyPath)
+                throw new Error(`Error: could not extract a path`);
+            //fromBase58 and derivePath will throw if xPub or path are not valid
+            if (!isRanged)
+                pubkey = derivePath(bip32, keyPath).publicKey;
+        }
+        else {
+            pubkey = bip32.publicKey;
+        }
+        //match xprv:
+    }
+    else if ((mXprvKey = actualKey.match(RE.anchorStartAndEnd(RE.reXprvKey))) !== null) {
+        const xPrvKey = mXprvKey[0];
+        xPrv = xPrvKey.match(RE.reXprv)?.[0];
+        if (!xPrv)
+            throw new Error(`Error: xprv could not be matched`);
+        bip32 = BIP32.fromBase58(xPrv, network);
+        xPub = bip32.neutered().toBase58();
+        const mPath = xPrvKey.match(RE.rePath);
+        if (mPath !== null) {
+            keyPath = xPrvKey.match(RE.rePath)?.[0];
+            if (!keyPath)
+                throw new Error(`Error: could not extract a path`);
+            //fromBase58 and derivePath will throw if xPrv or path are not valid
+            if (!isRanged)
+                pubkey = derivePath(bip32, keyPath).publicKey;
+        }
+        else {
+            pubkey = bip32.publicKey;
+        }
+    }
+    else {
+        throw new Error(`Error: could not get pubkey for keyExpression ${keyExpression}`);
+    }
+    if (originPath || keyPath) {
+        path = `m${originPath ?? ''}${keyPath ?? ''}`;
+    }
+    if (pubkey !== undefined) {
+        if (isTaproot) {
+            if (pubkey.length !== 33)
+                throw new Error(`Error: invalid pubkey`);
+        }
+        else if (typeof isSegwit === 'boolean' &&
+            isSegwit &&
+            pubkey.length !== 33) {
+            throw new Error(`Error: invalid pubkey`);
+        }
+    }
+    if (pubkey !== undefined && isTaproot && pubkey.length === 33)
+        // If we get a 33-byte compressed key, drop the first byte.
+        pubkey = pubkey.slice(1, 33);
+    return {
+        keyExpression,
+        ...(pubkey !== undefined ? { pubkey } : {}),
+        ...(ecpair !== undefined ? { ecpair } : {}),
+        ...(bip32 !== undefined ? { bip32 } : {}),
+        ...(privkey !== undefined ? { privkey } : {}),
+        ...(xPub !== undefined ? { xPub } : {}),
+        ...(xPrv !== undefined ? { xPrv } : {}),
+        ...(masterFingerprint !== undefined ? { masterFingerprint } : {}),
+        ...(originPath !== undefined && originPath !== '' ? { originPath } : {}),
+        ...(keyPath !== undefined && keyPath !== '' ? { keyPath } : {}),
+        ...(path !== undefined ? { path } : {})
+    };
+}
+function assertChangeIndexKeyPath({ change, index, keyPath }) {
+    if (!((change === undefined && index === undefined) ||
+        (change !== undefined && index !== undefined)))
+        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`);
+}
+async function keyExpressionLedger({ ledgerManager, originPath, keyPath, change, index }) {
+    assertChangeIndexKeyPath({ change, index, keyPath });
+    const masterFingerprint = await (0, ledger_1.getLedgerMasterFingerPrint)({
+        ledgerManager
+    });
+    const origin = `[${(0, uint8array_tools_1.toHex)(masterFingerprint)}${originPath}]`;
+    const xpub = await (0, ledger_1.getLedgerXpub)({ originPath, ledgerManager });
+    const keyRoot = `${origin}${xpub}`;
+    if (keyPath !== undefined)
+        return `${keyRoot}${keyPath}`;
+    else
+        return `${keyRoot}/${change}/${index}`;
+}
+/**
+ * Constructs a BIP32 key expression string from its constituent components.
+ *
+ * This function essentially performs the reverse operation of
+ * {@link KeyExpressionParser}. For detailed
+ * explanations and examples of the terms used here, refer to
+ * {@link KeyExpressionParser}.
+ *
+ * @param {Object} params - The parameters object.
+ * @param {BIP32InterfaceLike | ScureHDKeyLike} params.masterNode - Root HD node.
+ * Pass either:
+ * - a bitcoinjs {@link https://github.com/bitcoinjs/bip32 | `BIP32`} node, or
+ * - a scure {@link https://github.com/paulmillr/scure-bip32 | `HDKey`}.
+ * @param {string} params.originPath - Origin path from master, e.g. `"/84'/0'/0'"`.
+ * @param {number} [params.change] - Branch index (`0` receive, `1` change).
+ * @param {number | '*'} [params.index] - Address index or `*` for ranged descriptors.
+ * @param {string} [params.keyPath] - Full suffix path (`/change/index`) alternative to
+ * `change` + `index`.
+ * @returns {string} Descriptor key expression (e.g. `[f23f9fd2/84'/0'/0']xpub.../0/5`).
+ *
+ * @example
+ * ```ts
+ * import * as ecc from '@bitcoinerlab/secp256k1';
+ * import { BIP32Factory } from 'bip32';
+ * import { keyExpressionBIP32 } from '@bitcoinerlab/descriptors';
+ *
+ * const BIP32 = BIP32Factory(ecc);
+ * const masterNode = BIP32.fromSeed(seedBytes);
+ * const keyExp = keyExpressionBIP32({
+ *   masterNode,
+ *   originPath: "/84'/0'/0'",
+ *   change: 0,
+ *   index: 5
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { HDKey } from '@scure/bip32';
+ * import { keyExpressionBIP32 } from '@bitcoinerlab/descriptors';
+ *
+ * const masterNode = HDKey.fromMasterSeed(seedBytes);
+ * const keyExp = keyExpressionBIP32({
+ *   masterNode,
+ *   originPath: "/84'/0'/0'",
+ *   keyPath: '/0/*'
+ * });
+ * ```
+ */
+function keyExpressionBIP32({ masterNode, originPath, keyPath, change, index, isPublic = true }) {
+    masterNode = (0, keyInterfaces_1.toBIP32Interface)(masterNode);
+    assertChangeIndexKeyPath({ change, index, keyPath });
+    const masterFingerprint = masterNode.fingerprint;
+    const origin = `[${(0, uint8array_tools_1.toHex)(masterFingerprint)}${originPath}]`;
+    const xpub = isPublic
+        ? masterNode.derivePath(`m${originPath}`).neutered().toBase58().toString()
+        : masterNode.derivePath(`m${originPath}`).toBase58().toString();
+    const keyRoot = `${origin}${xpub}`;
+    if (keyPath !== undefined)
+        return `${keyRoot}${keyPath}`;
+    else
+        return `${keyRoot}/${change}/${index}`;
+}

package/dist/keyInterfaces.d.ts

@@ -0,0 +1,5 @@
+import { type ECPairInterfaceLike, type BIP32InterfaceLike, type ScureHDKeyLike } from './bitcoinLib';
+/** @internal */
+export declare function toECPairInterface(ecpair: ECPairInterfaceLike | Uint8Array): ECPairInterfaceLike;
+/** @internal */
+export declare function toBIP32Interface(node: BIP32InterfaceLike | ScureHDKeyLike): BIP32InterfaceLike;

package/dist/keyInterfaces.js

@@ -0,0 +1,50 @@
+"use strict";
+// Copyright (c) 2026 Jose-Luis Landabaso - https://bitcoinerlab.com
+// Distributed under the MIT software license
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toECPairInterface = toECPairInterface;
+exports.toBIP32Interface = toBIP32Interface;
+function isScureHDKey(node) {
+    const candidate = node;
+    return (typeof candidate.fingerprint === 'number' &&
+        typeof candidate.derive === 'function' &&
+        typeof candidate.deriveChild === 'function' &&
+        typeof candidate.publicExtendedKey === 'string' &&
+        typeof candidate.privateExtendedKey === 'string');
+}
+/** @internal */
+function toECPairInterface(ecpair) {
+    if (ecpair instanceof Uint8Array) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { wrapScurePrivateKey } = require('./adapters/scureKeys');
+            return wrapScurePrivateKey(ecpair);
+        }
+        catch (error) {
+            throw new Error('Failed to load scure key adapter. ' +
+                'Make sure @noble/curves is installed as a peer dependency. ' +
+                'Original error: ' +
+                (error instanceof Error ? error.message : String(error)));
+        }
+    }
+    // Already a bitcoinjs-lib compatible ECPairInterface
+    return ecpair;
+}
+/** @internal */
+function toBIP32Interface(node) {
+    if (isScureHDKey(node)) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { wrapScureHDKey } = require('./adapters/scureKeys');
+            return wrapScureHDKey(node);
+        }
+        catch (error) {
+            throw new Error('Failed to load scure key adapter. ' +
+                'Make sure @scure/bip32 is installed as a peer dependency. ' +
+                'Original error: ' +
+                (error instanceof Error ? error.message : String(error)));
+        }
+    }
+    // Already a bitcoinjs-lib compatible Bip32Interface
+    return node;
+}