@kukks/bitcoin-descriptors 3.0.2

package/dist/signers.js

@@ -0,0 +1,129 @@
+// Copyright (c) 2025 Jose-Luis Landabaso - https://bitcoinerlab.com
+// Distributed under the MIT software license
+import { readUInt32BE } from './scriptUtils.js';
+/**
+ * Adapts a BIP32Interface node to the HDKey interface expected by @scure/btc-signer.
+ * scure's Transaction.sign/signIdx auto-handle Taproot tweaking when given an HDKey.
+ */
+function toScureHDKey(node) {
+    if (!node.privateKey)
+        throw new Error('Cannot create HDKey signer from neutered node');
+    return {
+        publicKey: node.publicKey,
+        privateKey: node.privateKey,
+        fingerprint: readUInt32BE(node.fingerprint),
+        derive(path) {
+            return toScureHDKey(node.derivePath(path));
+        },
+        deriveChild(index) {
+            return toScureHDKey(node.derive(index));
+        },
+        sign(hash) {
+            return node.sign(hash);
+        }
+    };
+}
+/**
+ * Derives the private key from a BIP32 node using tapBip32Derivation info
+ * and signs the Taproot input directly with the raw private key.
+ * This is needed because @scure/btc-signer's signIdx HDKey path only checks
+ * bip32Derivation, not tapBip32Derivation.
+ */
+function signTapBip32(psbt, index, masterNode) {
+    const input = psbt.getInput(index);
+    const tapBip32 = input.tapBip32Derivation;
+    if (!tapBip32 || !tapBip32.length)
+        return false;
+    const fp = readUInt32BE(masterNode.fingerprint);
+    let signed = false;
+    for (const [, { der }] of tapBip32) {
+        if (der.fingerprint !== fp)
+            continue;
+        let node = masterNode;
+        for (const childIdx of der.path) {
+            node = node.derive(childIdx);
+        }
+        if (!node.privateKey)
+            throw new Error('Cannot sign: derived node has no private key');
+        psbt.signIdx(node.privateKey, index);
+        signed = true;
+    }
+    return signed;
+}
+/**
+ * Signs a specific input of a PSBT with an ECPair.
+ *
+ * Uses @scure/btc-signer's signIdx which automatically handles
+ * Taproot key tweaking internally.
+ *
+ * @param {Object} params - The parameters object
+ * @param {PsbtLike} params.psbt - The PSBT to sign
+ * @param {number} params.index - The input index to sign
+ * @param {ECPairInterface} params.ecpair - The ECPair to sign with
+ */
+export function signInputECPair({ psbt, index, ecpair }) {
+    if (!ecpair.privateKey)
+        throw new Error('Missing private key');
+    psbt.signIdx(ecpair.privateKey, index);
+}
+/**
+ * Signs all inputs of a PSBT with an ECPair.
+ *
+ * Uses @scure/btc-signer's sign which automatically handles
+ * Taproot key tweaking internally.
+ *
+ * @param {Object} params - The parameters object
+ * @param {PsbtLike} params.psbt - The PSBT to sign
+ * @param {ECPairInterface} params.ecpair - The ECPair to sign with
+ */
+export function signECPair({ psbt, ecpair }) {
+    if (!ecpair.privateKey)
+        throw new Error('Missing private key');
+    const signed = psbt.sign(ecpair.privateKey);
+    if (signed === 0) {
+        throw new Error('No inputs were signed');
+    }
+}
+/**
+ * Signs a specific input of a PSBT with a BIP32 node.
+ *
+ * Handles Taproot inputs via tapBip32Derivation, and non-Taproot via
+ * @scure/btc-signer's signIdx with an HDKey adapter.
+ *
+ * @param {Object} params - The parameters object
+ * @param {PsbtLike} params.psbt - The PSBT to sign
+ * @param {number} params.index - The input index to sign
+ * @param {BIP32Interface} params.node - The BIP32 node to sign with
+ */
+export function signInputBIP32({ psbt, index, node }) {
+    if (!signTapBip32(psbt, index, node)) {
+        psbt.signIdx(toScureHDKey(node), index);
+    }
+}
+/**
+ * Signs all inputs of a PSBT with a BIP32 master node.
+ *
+ * First signs any Taproot inputs via tapBip32Derivation, then uses
+ * @scure/btc-signer's sign for remaining non-Taproot inputs.
+ *
+ * @param {Object} params - The parameters object
+ * @param {PsbtLike} params.psbt - The PSBT to sign
+ * @param {BIP32Interface} params.masterNode - The BIP32 master node to sign with
+ */
+export function signBIP32({ psbt, masterNode }) {
+    let tapSigned = 0;
+    for (let i = 0; i < psbt.inputsLength; i++) {
+        if (signTapBip32(psbt, i, masterNode))
+            tapSigned++;
+    }
+    let nonTapSigned = 0;
+    try {
+        nonTapSigned = psbt.sign(toScureHDKey(masterNode));
+    }
+    catch {
+        // sign() throws 'No inputs signed' when no bip32Derivation matches
+    }
+    if (tapSigned + nonTapSigned === 0) {
+        throw new Error('No inputs were signed');
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,263 @@
+import type { Network } from './networks.js';
+import type { P2Ret } from '@scure/btc-signer/payment.js';
+/**
+ * Interface for an EC key pair (replaces ecpair's ECPairInterface).
+ * Only the fields used by this library are included.
+ */
+export interface ECPairInterface {
+    publicKey: Uint8Array;
+    privateKey?: Uint8Array;
+    compressed: boolean;
+    network?: Network;
+    sign(hash: Uint8Array): Uint8Array;
+    verify(hash: Uint8Array, signature: Uint8Array): boolean;
+    toWIF(): string;
+    tweak(t: Uint8Array): ECPairInterface;
+}
+/**
+ * API for creating EC key pairs (replaces ecpair's ECPairAPI).
+ */
+export interface ECPairAPI {
+    fromPublicKey(publicKey: Uint8Array, options?: {
+        network?: Network;
+        compressed?: boolean;
+    }): ECPairInterface;
+    fromPrivateKey(privateKey: Uint8Array, options?: {
+        network?: Network;
+        compressed?: boolean;
+    }): ECPairInterface;
+    fromWIF(wif: string, network?: Network | Network[]): ECPairInterface;
+    makeRandom(options?: {
+        network?: Network;
+        compressed?: boolean;
+    }): ECPairInterface;
+    isPoint(p: Uint8Array): boolean;
+}
+/**
+ * Interface for a BIP32 HD key (replaces bip32's BIP32Interface).
+ * Only the fields used by this library are included.
+ */
+export interface BIP32Interface {
+    publicKey: Uint8Array;
+    privateKey?: Uint8Array;
+    chainCode: Uint8Array;
+    fingerprint: Uint8Array;
+    depth: number;
+    index: number;
+    parentFingerprint: number;
+    network: Network;
+    derivePath(path: string): BIP32Interface;
+    derive(index: number): BIP32Interface;
+    deriveHardened(index: number): BIP32Interface;
+    neutered(): BIP32Interface;
+    toBase58(): string;
+    sign(hash: Uint8Array): Uint8Array;
+    verify(hash: Uint8Array, signature: Uint8Array): boolean;
+    isNeutered(): boolean;
+    toWIF(): string;
+}
+/**
+ * API for creating BIP32 keys (replaces bip32's BIP32API).
+ */
+export interface BIP32API {
+    fromBase58(base58: string, network?: Network): BIP32Interface;
+    fromPublicKey(publicKey: Uint8Array, chainCode: Uint8Array, network?: Network): BIP32Interface;
+    fromPrivateKey(privateKey: Uint8Array, chainCode: Uint8Array, network?: Network): BIP32Interface;
+    fromSeed(seed: Uint8Array, network?: Network): BIP32Interface;
+}
+/**
+ * PartialSig (replaces bip174's PartialSig)
+ */
+export interface PartialSig {
+    pubkey: Uint8Array;
+    signature: Uint8Array;
+}
+/**
+ * Preimage
+ * See {@link Output}
+ */
+export type Preimage = {
+    /**
+     * Use same string 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 preimage. Preimages are always 32 bytes (so, 64 character in hex).
+     */
+    preimage: string;
+};
+export type TimeConstraints = {
+    nLockTime: number | undefined;
+    nSequence: number | undefined;
+};
+/**
+ * See {@link _Internal_.ParseKeyExpression | ParseKeyExpression}.
+ */
+export type KeyInfo = {
+    keyExpression: string;
+    pubkey?: Uint8Array;
+    ecpair?: ECPairInterface;
+    bip32?: BIP32Interface;
+    masterFingerprint?: Uint8Array;
+    originPath?: string;
+    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;
+};
+/** @ignore */
+interface XOnlyPointAddTweakResult {
+    parity: 1 | 0;
+    xOnlyPubkey: Uint8Array;
+}
+/** @ignore */
+export interface TinySecp256k1Interface {
+    isPoint(p: Uint8Array): boolean;
+    pointCompress(p: Uint8Array, compressed?: boolean): Uint8Array;
+    isPrivate(d: Uint8Array): boolean;
+    pointFromScalar(d: Uint8Array, compressed?: boolean): Uint8Array | null;
+    pointAddScalar(p: Uint8Array, tweak: Uint8Array, compressed?: boolean): Uint8Array | null;
+    privateAdd(d: Uint8Array, tweak: Uint8Array): Uint8Array | null;
+    sign(h: Uint8Array, d: Uint8Array, e?: Uint8Array): Uint8Array;
+    signSchnorr?(h: Uint8Array, d: Uint8Array, e?: Uint8Array): Uint8Array;
+    verify(h: Uint8Array, Q: Uint8Array, signature: Uint8Array, strict?: boolean): boolean;
+    verifySchnorr?(h: Uint8Array, Q: Uint8Array, signature: Uint8Array): boolean;
+    xOnlyPointAddTweak(p: Uint8Array, tweak: Uint8Array): XOnlyPointAddTweakResult | null;
+    isXOnlyPoint(p: Uint8Array): boolean;
+    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 Payment for the provided expression, if applicable.
+     */
+    payment?: P2Ret;
+    /**
+     * 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;
+    /**
+     * A boolean indicating whether the descriptor uses Taproot.
+     */
+    isTaproot?: 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?: Uint8Array;
+    /**
+     * The witness script for the descriptor, if applicable.
+     */
+    witnessScript?: Uint8Array;
+    /**
+     * 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;
+};
+/**
+ * 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;
+        /**
+         * 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;
+        network?: Network;
+    }): KeyInfo;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,3 @@
+// Copyright (c) 2023 Jose-Luis Landabaso - https://bitcoinerlab.com
+// Distributed under the MIT software license
+export {};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@kukks/bitcoin-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/Kukks/descriptors",
+  "version": "3.0.2",
+  "author": "Jose-Luis Landabaso",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Kukks/descriptors.git"
+  },
+  "keywords": [
+    "bitcoin",
+    "descriptors",
+    "miniscript",
+    "scure",
+    "noble"
+  ],
+  "bugs": {
+    "url": "https://github.com/Kukks/descriptors/issues"
+  },
+  "type": "module",
+  "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",
+    "extensionsToTreatAsEsm": [],
+    "transform": {}
+  },
+  "scripts": {
+    "webdocs": "typedoc --options ./node_modules/@bitcoinerlab/configs/webtypedoc.json",
+    "docs": "typedoc --options ./node_modules/@bitcoinerlab/configs/typedoc.json",
+    "build:src": "tsc --project tsconfig.src.json",
+    "build:fixtures": "node test/tools/generateBitcoinCoreFixtures.cjs -i test/fixtures/descriptor_tests.cpp | npx prettier --parser typescript > test/fixtures/bitcoinCore.ts",
+    "build:test": "npm run build:fixtures && tsc --project tsconfig.test.json --resolveJsonModule",
+    "build": "npm run build:src && npm run build:test",
+    "lint": "./node_modules/@bitcoinerlab/configs/scripts/lint.sh",
+    "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 && echo \"\n\n\" && node test/integration/sortedmulti.js",
+
+    "test:unit": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test": "npm run lint && npm run build && npm run test:unit && npm run test:integration:soft",
+    "prepublishOnly": "npm run test"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@bitcoinerlab/configs": "^2.0.0",
+    "bip39": "^3.0.4",
+    "bip65": "^1.0.3",
+    "bip68": "^1.0.4",
+    "regtest-client": "^0.2.1",
+    "yargs": "^17.7.2"
+  },
+  "dependencies": {
+    "@bitcoinerlab/miniscript": "^1.4.3",
+    "@noble/curves": "^2.0.1",
+    "@noble/hashes": "^2.0.1",
+    "@scure/base": "^2.0.0",
+    "@scure/bip32": "^2.0.1",
+    "@scure/btc-signer": "^2.0.1"
+  }
+}