@kukks/bitcoin-descriptors 3.0.2 → 3.1.0

package/dist/adapters.d.ts

@@ -0,0 +1,23 @@
+import { HDKey } from '@scure/bip32';
+import type { ECPairInterface, ECPairAPI, BIP32Interface, BIP32API } from './types.js';
+import { type Network } from './networks.js';
+/**
+ * Create an ECPairInterface from a private key and/or public key.
+ * Exported for advanced use cases where consumers need to construct
+ * key pairs directly.
+ */
+export declare function createECPair(privKey: Uint8Array | undefined, pubKeyInput: Uint8Array | undefined, compressed: boolean, network: Network): ECPairInterface;
+/**
+ * Built-in ECPairAPI implementation using @noble/curves secp256k1.
+ */
+export declare const nobleECPair: ECPairAPI;
+/**
+ * Wrap a @scure/bip32 HDKey in a BIP32Interface.
+ * Exported for advanced use cases where consumers need to wrap
+ * HDKey instances directly.
+ */
+export declare function wrapHDKey(hdkey: HDKey, network: Network): BIP32Interface;
+/**
+ * Built-in BIP32API implementation using @scure/bip32.
+ */
+export declare const scureBIP32: BIP32API;

package/dist/adapters.js

@@ -0,0 +1,321 @@
+// Copyright (c) 2025 Jose-Luis Landabaso - https://bitcoinerlab.com
+// Distributed under the MIT software license
+// Built-in adapters for ECPairAPI and BIP32API using
+// @noble/curves, @scure/bip32, @noble/hashes, and @scure/base.
+// These conform to the interfaces defined in ./types.ts.
+import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { HDKey } from '@scure/bip32';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { base58check, hex } from '@scure/base';
+import { concatBytes } from '@scure/btc-signer/utils.js';
+import { networks } from './networks.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const bs58check = base58check(sha256);
+const DEFAULT_NETWORK = networks.bitcoin;
+/** Convert a bigint to a 32-byte big-endian Uint8Array. */
+function bigintTo32Bytes(n) {
+    const hexStr = n.toString(16).padStart(64, '0');
+    return hex.decode(hexStr);
+}
+/** Write a 32-bit unsigned integer in big-endian format into buf at offset. */
+function writeUInt32BE(buf, value, offset) {
+    buf[offset] = (value >>> 24) & 0xff;
+    buf[offset + 1] = (value >>> 16) & 0xff;
+    buf[offset + 2] = (value >>> 8) & 0xff;
+    buf[offset + 3] = value & 0xff;
+}
+// ---------------------------------------------------------------------------
+// WIF encode / decode
+// ---------------------------------------------------------------------------
+function encodeWIF(privateKey, compressed, network) {
+    const prefix = Uint8Array.from([network.wif]);
+    const payload = compressed
+        ? concatBytes(prefix, privateKey, Uint8Array.from([0x01]))
+        : concatBytes(prefix, privateKey);
+    return bs58check.encode(payload);
+}
+function decodeWIF(wif, network) {
+    const decoded = bs58check.decode(wif);
+    const version = decoded[0];
+    // Determine matching network(s)
+    const candidateNetworks = network
+        ? Array.isArray(network)
+            ? network
+            : [network]
+        : [networks.bitcoin, networks.testnet, networks.regtest];
+    const matchedNetwork = candidateNetworks.find(n => n.wif === version);
+    if (!matchedNetwork) {
+        throw new Error(`Invalid network version`);
+    }
+    // Determine if compressed
+    if (decoded.length === 34 && decoded[33] === 0x01) {
+        return {
+            privateKey: decoded.subarray(1, 33),
+            compressed: true,
+            network: matchedNetwork
+        };
+    }
+    else if (decoded.length === 33) {
+        return {
+            privateKey: decoded.subarray(1, 33),
+            compressed: false,
+            network: matchedNetwork
+        };
+    }
+    else {
+        throw new Error('Invalid WIF payload length');
+    }
+}
+// ---------------------------------------------------------------------------
+// ECPair implementation
+// ---------------------------------------------------------------------------
+/**
+ * Create an ECPairInterface from a private key and/or public key.
+ * Exported for advanced use cases where consumers need to construct
+ * key pairs directly.
+ */
+export function createECPair(privKey, pubKeyInput, compressed, network) {
+    let pubKey;
+    if (privKey) {
+        pubKey = secp256k1.getPublicKey(privKey, compressed);
+    }
+    else if (pubKeyInput) {
+        // Normalise to the requested compression
+        const point = secp256k1.Point.fromHex(hex.encode(pubKeyInput));
+        pubKey = point.toBytes(compressed);
+    }
+    else {
+        throw new Error('Either privateKey or publicKey must be provided');
+    }
+    // Build the object conditionally so that `privateKey` is only present
+    // when defined (satisfies exactOptionalPropertyTypes).
+    const base = {
+        publicKey: pubKey,
+        compressed,
+        network,
+        sign(hash) {
+            if (!privKey)
+                throw new Error('Missing private key');
+            return secp256k1.sign(hash, privKey);
+        },
+        verify(hash, signature) {
+            return secp256k1.verify(signature, hash, pubKey);
+        },
+        toWIF() {
+            if (!privKey)
+                throw new Error('Missing private key');
+            return encodeWIF(privKey, compressed, network);
+        },
+        tweak(t) {
+            const tweakBigint = BigInt('0x' + hex.encode(t));
+            const n = secp256k1.Point.CURVE().n;
+            if (privKey) {
+                const privBigint = BigInt('0x' + hex.encode(privKey));
+                const newPrivBigint = (privBigint + tweakBigint) % n;
+                if (newPrivBigint === 0n) {
+                    throw new Error('Tweaked private key is zero');
+                }
+                const newPrivKey = bigintTo32Bytes(newPrivBigint);
+                return createECPair(newPrivKey, undefined, compressed, network);
+            }
+            else {
+                // Public-key-only tweak: P' = P + t*G
+                const G = secp256k1.Point.BASE;
+                const tweakPoint = G.multiply(tweakBigint);
+                const pubPoint = secp256k1.Point.fromHex(hex.encode(pubKey));
+                const tweakedPoint = pubPoint.add(tweakPoint);
+                return createECPair(undefined, tweakedPoint.toBytes(compressed), compressed, network);
+            }
+        }
+    };
+    if (privKey) {
+        return Object.assign(base, { privateKey: privKey });
+    }
+    return base;
+}
+/**
+ * Built-in ECPairAPI implementation using @noble/curves secp256k1.
+ */
+export const nobleECPair = {
+    fromPublicKey(publicKey, options) {
+        const compressed = options?.compressed !== false;
+        const network = options?.network ?? DEFAULT_NETWORK;
+        return createECPair(undefined, publicKey, compressed, network);
+    },
+    fromPrivateKey(privateKey, options) {
+        const compressed = options?.compressed !== false;
+        const network = options?.network ?? DEFAULT_NETWORK;
+        return createECPair(privateKey, undefined, compressed, network);
+    },
+    fromWIF(wif, network) {
+        const { privateKey, compressed, network: net } = decodeWIF(wif, network);
+        return createECPair(privateKey, undefined, compressed, net);
+    },
+    makeRandom(options) {
+        const privKey = secp256k1.utils.randomSecretKey();
+        const compressed = options?.compressed !== false;
+        const network = options?.network ?? DEFAULT_NETWORK;
+        return createECPair(privKey, undefined, compressed, network);
+    },
+    isPoint(p) {
+        try {
+            secp256k1.Point.fromHex(hex.encode(p));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+};
+// ---------------------------------------------------------------------------
+// BIP32 implementation
+// ---------------------------------------------------------------------------
+/** Map a Network to the versions object expected by @scure/bip32's HDKey. */
+function networkToVersions(network) {
+    return { public: network.bip32.public, private: network.bip32.private };
+}
+/**
+ * Wrap a @scure/bip32 HDKey in a BIP32Interface.
+ * Exported for advanced use cases where consumers need to wrap
+ * HDKey instances directly.
+ */
+export function wrapHDKey(hdkey, network) {
+    const versions = networkToVersions(network);
+    // Build the base object without privateKey, then conditionally add it.
+    // This satisfies exactOptionalPropertyTypes.
+    const base = {
+        get publicKey() {
+            if (!hdkey.publicKey)
+                throw new Error('Missing public key');
+            return hdkey.publicKey;
+        },
+        get chainCode() {
+            if (!hdkey.chainCode)
+                throw new Error('Missing chain code');
+            return hdkey.chainCode;
+        },
+        get fingerprint() {
+            // HDKey.fingerprint is a number (4-byte big-endian unsigned int)
+            const buf = new Uint8Array(4);
+            writeUInt32BE(buf, hdkey.fingerprint >>> 0, 0);
+            return buf;
+        },
+        get depth() {
+            return hdkey.depth;
+        },
+        get index() {
+            return hdkey.index;
+        },
+        get parentFingerprint() {
+            return hdkey.parentFingerprint;
+        },
+        network,
+        derivePath(path) {
+            // @scure/bip32 requires paths to start with "m" or "M"
+            // Old bip32 package accepted relative paths like "0'/1'/0'"
+            const normalizedPath = path.startsWith('m') || path.startsWith('M') ? path : `m/${path}`;
+            return wrapHDKey(hdkey.derive(normalizedPath), network);
+        },
+        derive(index) {
+            return wrapHDKey(hdkey.deriveChild(index), network);
+        },
+        deriveHardened(index) {
+            return wrapHDKey(hdkey.deriveChild(index + 0x80000000), network);
+        },
+        neutered() {
+            // Create a public-only HDKey via the public extended key
+            const xpub = hdkey.publicExtendedKey;
+            const neuteredKey = HDKey.fromExtendedKey(xpub, versions);
+            return wrapHDKey(neuteredKey, network);
+        },
+        toBase58() {
+            if (hdkey.privateKey) {
+                return hdkey.privateExtendedKey;
+            }
+            return hdkey.publicExtendedKey;
+        },
+        sign(hash) {
+            if (!hdkey.privateKey)
+                throw new Error('Missing private key');
+            return hdkey.sign(hash);
+        },
+        verify(hash, signature) {
+            return hdkey.verify(hash, signature);
+        },
+        isNeutered() {
+            return !hdkey.privateKey;
+        },
+        toWIF() {
+            if (!hdkey.privateKey) {
+                throw new Error('Missing private key');
+            }
+            return encodeWIF(hdkey.privateKey, true, network);
+        }
+    };
+    if (hdkey.privateKey) {
+        return Object.defineProperty(base, 'privateKey', {
+            get() {
+                return hdkey.privateKey;
+            },
+            enumerable: true,
+            configurable: true
+        });
+    }
+    return base;
+}
+/**
+ * Built-in BIP32API implementation using @scure/bip32.
+ */
+export const scureBIP32 = {
+    fromBase58(base58, network) {
+        const net = network ?? DEFAULT_NETWORK;
+        const versions = networkToVersions(net);
+        const hdkey = HDKey.fromExtendedKey(base58, versions);
+        return wrapHDKey(hdkey, net);
+    },
+    fromPublicKey(publicKey, chainCode, network) {
+        const net = network ?? DEFAULT_NETWORK;
+        const versions = networkToVersions(net);
+        // Manually serialise the public extended key in base58check format.
+        //
+        // xpub format (78 bytes):
+        //   version (4) + depth (1) + parentFingerprint (4) + index (4) +
+        //   chainCode (32) + publicKey (33)
+        const buf = new Uint8Array(78);
+        writeUInt32BE(buf, versions.public, 0); // version
+        buf[4] = 0; // depth
+        writeUInt32BE(buf, 0, 5); // parent fingerprint
+        writeUInt32BE(buf, 0, 9); // index
+        buf.set(chainCode, 13);
+        buf.set(publicKey, 45);
+        const xpub = bs58check.encode(buf);
+        const hdkey = HDKey.fromExtendedKey(xpub, versions);
+        return wrapHDKey(hdkey, net);
+    },
+    fromPrivateKey(privateKey, chainCode, network) {
+        const net = network ?? DEFAULT_NETWORK;
+        const versions = networkToVersions(net);
+        // xprv format (78 bytes):
+        //   version (4) + depth (1) + parentFingerprint (4) + index (4) +
+        //   chainCode (32) + 0x00 (1) + privateKey (32)
+        const buf = new Uint8Array(78);
+        writeUInt32BE(buf, versions.private, 0); // version
+        buf[4] = 0; // depth
+        writeUInt32BE(buf, 0, 5); // parent fingerprint
+        writeUInt32BE(buf, 0, 9); // index
+        buf.set(chainCode, 13);
+        buf[45] = 0x00; // padding byte before private key
+        buf.set(privateKey, 46);
+        const xprv = bs58check.encode(buf);
+        const hdkey = HDKey.fromExtendedKey(xprv, versions);
+        return wrapHDKey(hdkey, net);
+    },
+    fromSeed(seed, network) {
+        const net = network ?? DEFAULT_NETWORK;
+        const versions = networkToVersions(net);
+        const hdkey = HDKey.fromMasterSeed(seed, versions);
+        return wrapHDKey(hdkey, net);
+    }
+};

package/dist/descriptors.d.ts

@@ -16,11 +16,12 @@ import type { PsbtLike } from './psbt.js';
  * These are compatible interfaces for managing BIP32 keys and
  * public/private key pairs respectively.
  *
- * @param {Object} params - An object with `ECPair` and `BIP32` factories.
+ * @param {Object} params - An object with optional `ECPair` and `BIP32` factories.
+ * When omitted, built-in adapters using @noble/curves and @scure/bip32 are used.
  */
-export declare function DescriptorsFactory({ ECPair, BIP32 }: {
-    ECPair: ECPairAPI;
-    BIP32: BIP32API;
+export declare function DescriptorsFactory({ ECPair, BIP32 }?: {
+    ECPair?: ECPairAPI;
+    BIP32?: BIP32API;
 }): {
     Output: {
         new ({ descriptor, index, checksumRequired, allowMiniscriptInP2SH, network, preimages, signersPubKeys }: {

package/dist/descriptors.js

@@ -30,6 +30,7 @@ import { varintEncodingLength, decompileScript } from './scriptUtils.js';
 import { hash160, compareBytes, equalBytes, concatBytes } from '@scure/btc-signer/utils.js';
 import { hex } from '@scure/base';
 import { sha256 } from '@noble/hashes/sha2.js';
+import { nobleECPair, scureBIP32 } from './adapters.js';
 import { computeFinalScripts, updatePsbt } from './psbt.js';
 import { DescriptorChecksum } from './checksum.js';
 import { parseKeyExpression as globalParseKeyExpression } from './keyExpressions.js';
@@ -178,9 +179,10 @@ function parseSortedMulti(inner) {
  * These are compatible interfaces for managing BIP32 keys and
  * public/private key pairs respectively.
  *
- * @param {Object} params - An object with `ECPair` and `BIP32` factories.
+ * @param {Object} params - An object with optional `ECPair` and `BIP32` factories.
+ * When omitted, built-in adapters using @noble/curves and @scure/bip32 are used.
  */
-export function DescriptorsFactory({ ECPair, BIP32 }) {
+export function DescriptorsFactory({ ECPair = nobleECPair, BIP32 = scureBIP32 } = {}) {
     var _Output_instances, _Output_payment, _Output_preimages, _Output_signersPubKeys, _Output_miniscript, _Output_witnessScript, _Output_redeemScript, _Output_isSegwit, _Output_isTaproot, _Output_expandedExpression, _Output_expandedMiniscript, _Output_expansionMap, _Output_network, _Output_getTimeConstraints, _Output_assertPsbtInput;
     /**
      * Takes a string key expression (xpub, xprv, pubkey or wif) and parses it

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export type { KeyInfo, Expansion } from './types.js';
+export type { ECPairAPI, ECPairInterface, BIP32API, BIP32Interface } from './types.js';
 export type { OutputInstance } from './descriptors.js';
 export { DescriptorsFactory, OutputConstructor } from './descriptors.js';
 export { DescriptorChecksum as checksum } from './checksum.js';
@@ -10,3 +11,91 @@ export { scriptExpressions };
 export type { PsbtLike } from './psbt.js';
 export { networks } from './networks.js';
 export type { Network } from './networks.js';
+export { nobleECPair, scureBIP32 } from './adapters.js';
+export declare const defaultFactory: {
+    Output: {
+        new ({ descriptor, index, checksumRequired, allowMiniscriptInP2SH, network, preimages, signersPubKeys }: {
+            descriptor: string;
+            index?: number;
+            checksumRequired?: boolean;
+            allowMiniscriptInP2SH?: boolean;
+            network?: import("./networks.js").Network;
+            preimages?: import("./types.js").Preimage[];
+            signersPubKeys?: Uint8Array[];
+        }): {
+            readonly "__#private@#payment": import("@scure/btc-signer/payment.js").P2Ret;
+            readonly "__#private@#preimages": import("./types.js").Preimage[];
+            readonly "__#private@#signersPubKeys": Uint8Array[];
+            readonly "__#private@#miniscript"?: string;
+            readonly "__#private@#witnessScript"?: Uint8Array;
+            readonly "__#private@#redeemScript"?: Uint8Array;
+            readonly "__#private@#isSegwit"?: boolean;
+            readonly "__#private@#isTaproot"?: boolean;
+            readonly "__#private@#expandedExpression"?: string;
+            readonly "__#private@#expandedMiniscript"?: string;
+            readonly "__#private@#expansionMap"?: import("./types.js").ExpansionMap;
+            readonly "__#private@#network": import("./networks.js").Network;
+            "__#private@#getTimeConstraints"(): import("./types.js").TimeConstraints | undefined;
+            getPayment(): import("@scure/btc-signer/payment.js").P2Ret;
+            getAddress(): string;
+            getScriptPubKey(): Uint8Array;
+            getScriptSatisfaction(signatures: import("./types.js").PartialSig[] | "DANGEROUSLY_USE_FAKE_SIGNATURES"): Uint8Array;
+            getSequence(): number | undefined;
+            getLockTime(): number | undefined;
+            getWitnessScript(): Uint8Array | undefined;
+            getRedeemScript(): Uint8Array | undefined;
+            getNetwork(): import("./networks.js").Network;
+            isSegwit(): boolean | undefined;
+            isTaproot(): boolean | undefined;
+            guessOutput(): {
+                isPKH: boolean;
+                isWPKH: boolean;
+                isSH: boolean;
+                isWSH: boolean;
+                isTR: boolean;
+            };
+            inputWeight(isSegwitTx: boolean, signatures: import("./types.js").PartialSig[] | "DANGEROUSLY_USE_FAKE_SIGNATURES"): number;
+            outputWeight(): number;
+            updatePsbtAsInput({ psbt, txHex, txId, value, vout, rbf }: {
+                psbt: import("./psbt.js").PsbtLike;
+                txHex?: string;
+                txId?: string;
+                value?: number;
+                vout: number;
+                rbf?: boolean;
+            }): ({ psbt, validate }: {
+                psbt: import("./psbt.js").PsbtLike;
+                validate?: boolean | undefined;
+            }) => void;
+            updatePsbtAsOutput({ psbt, value }: {
+                psbt: import("./psbt.js").PsbtLike;
+                value: number | bigint;
+            }): void;
+            "__#private@#assertPsbtInput"({ psbt, index }: {
+                psbt: import("./psbt.js").PsbtLike;
+                index: number;
+            }): void;
+            finalizePsbtInput({ index, psbt, validate }: {
+                index: number;
+                psbt: import("./psbt.js").PsbtLike;
+                validate?: boolean | undefined;
+            }): void;
+            expand(): {
+                expansionMap?: import("./types.js").ExpansionMap;
+                expandedMiniscript?: string;
+                miniscript?: string;
+                expandedExpression?: string;
+            };
+        };
+    };
+    parseKeyExpression: import("./types.js").ParseKeyExpression;
+    expand: ({ descriptor, index, checksumRequired, network, allowMiniscriptInP2SH }: {
+        descriptor: string;
+        index?: number;
+        checksumRequired?: boolean;
+        network?: import("./networks.js").Network;
+        allowMiniscriptInP2SH?: boolean;
+    }) => import("./types.js").Expansion;
+    ECPair: import("./types.js").ECPairAPI;
+    BIP32: import("./types.js").BIP32API;
+};

package/dist/index.js

@@ -8,3 +8,8 @@ export { keyExpressionBIP32 } from './keyExpressions.js';
 import * as scriptExpressions from './scriptExpressions.js';
 export { scriptExpressions };
 export { networks } from './networks.js';
+// Built-in adapters using @noble/curves and @scure/bip32
+export { nobleECPair, scureBIP32 } from './adapters.js';
+// Pre-built factory using built-in adapters (zero-config convenience)
+import { DescriptorsFactory } from './descriptors.js';
+export const defaultFactory = DescriptorsFactory();

package/package.json

@@ -2,7 +2,7 @@
   "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",
+  "version": "3.1.0",
   "author": "Jose-Luis Landabaso",
   "license": "MIT",
   "repository": {