@kukks/bitcoin-descriptors 3.0.2 → 3.2.1

package/README.md

@@ -6,12 +6,13 @@ This library parses and creates Bitcoin Miniscript Descriptors and generates Par
 
 ## Differences from upstream
 
-This fork migrates the entire library from `bitcoinjs-lib` to the [`@scure/btc-signer`](https://github.com/nicolo-ribaudo/scure-btc-signer) and [`@noble`](https://github.com/nicolo-ribaudo/noble-curves) ecosystem. Key differences:
+This fork migrates the entire library from `bitcoinjs-lib` to the [`@scure/btc-signer`](https://github.com/paulmillr/scure-btc-signer) and [`@noble`](https://github.com/paulmillr/noble-curves) ecosystem. Key differences:
 
 - **`Buffer` replaced with `Uint8Array`** across the entire public API. All methods that previously returned or accepted `Buffer` now use `Uint8Array`. This is a **breaking change**.
-- **Dependencies replaced**: `bitcoinjs-lib`, `ecpair`, `bip32`, `tiny-secp256k1` are no longer used. The library now depends on `@scure/btc-signer`, `@scure/bip32`, `@noble/curves`, `@noble/hashes`, and `@scure/base`.
+- **Dependencies replaced**: `bitcoinjs-lib`, `ecpair`, `bip32`, `tiny-secp256k1` are no longer used. The library now depends on [`@scure/btc-signer`](https://github.com/paulmillr/scure-btc-signer), [`@scure/bip32`](https://github.com/paulmillr/scure-bip32), [`@noble/curves`](https://github.com/paulmillr/noble-curves), [`@noble/hashes`](https://github.com/paulmillr/noble-hashes), and [`@scure/base`](https://github.com/paulmillr/scure-base).
+- **Built-in adapters**: Ships `nobleECPair` and `scureBIP32` adapters — no more boilerplate. `DescriptorsFactory()` works with zero arguments.
 - **PSBT class**: Uses `Transaction` from `@scure/btc-signer` instead of `Psbt` from `bitcoinjs-lib`.
-- **Ledger support removed**: The `ledger` module and all Ledger-related functions (`signLedger`, `keyExpressionLedger`, `pkhLedger`, `shWpkhLedger`, `wpkhLedger`, etc.) have been removed.
+- **Ledger support removed**: The `ledger` module and all Ledger-related functions have been removed.
 - **`lodash.memoize` removed**: Replaced with an inline memoize helper.
 - **Package renamed** from `@bitcoinerlab/descriptors` to `@kukks/bitcoin-descriptors`.
 
@@ -19,18 +20,62 @@ This fork migrates the entire library from `bitcoinjs-lib` to the [`@scure/btc-s
 
 ```bash
 npm install @kukks/bitcoin-descriptors
+```
+
+If you use **miniscript-based descriptors** (`sh(wsh(...))`, `sh(...)`, `wsh(...)` with miniscript expressions), install the optional peer dependency:
+
+```bash
 npm install @bitcoinerlab/miniscript
 ```
 
+Standard descriptors (`pkh`, `wpkh`, `sh(wpkh(...))`, `tr`, `multi`, `sortedmulti`, `addr`) work without it.
+
+## Quick Start
+
+```typescript
+import { DescriptorsFactory } from '@kukks/bitcoin-descriptors';
+
+// Zero-config — uses built-in @noble/curves + @scure/bip32 adapters
+const { Output, expand } = DescriptorsFactory();
+
+const output = new Output({
+  descriptor: 'wpkh(02f9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9)'
+});
+
+console.log(output.getAddress());
+```
+
+Or use the pre-built default factory:
+
+```typescript
+import { defaultFactory } from '@kukks/bitcoin-descriptors';
+
+const { Output } = defaultFactory;
+```
+
+### Bring your own adapters
+
+If you need custom `ECPairAPI` or `BIP32API` implementations, you can still pass them explicitly:
+
+```typescript
+import { DescriptorsFactory } from '@kukks/bitcoin-descriptors';
+import type { ECPairAPI, BIP32API } from '@kukks/bitcoin-descriptors';
+
+const { Output } = DescriptorsFactory({ ECPair: myECPair, BIP32: myBIP32 });
+```
+
+The built-in adapters are also available as standalone exports:
+
+```typescript
+import { nobleECPair, scureBIP32 } from '@kukks/bitcoin-descriptors';
+```
+
 ## Features
 
 - Parses and creates [Bitcoin Descriptors](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md) (including those based on the [Miniscript language](https://bitcoinerlab.com/modules/miniscript)).
 - Generates Partially Signed Bitcoin Transactions (PSBTs).
 - Provides PSBT finalizers and signers for single-signature and BIP32 wallets.
-
-## Concepts
-
-This library has two main capabilities related to Bitcoin descriptors. Firstly, it can generate `addresses` and `scriptPubKeys` from descriptors. These `addresses` and `scriptPubKeys` can be used to receive funds from other parties. Secondly, the library is able to sign transactions and spend unspent outputs described by those same descriptors. In order to do this, the descriptors must first be set into a PSBT.
+- Ships built-in adapters for `@noble/curves` and `@scure/bip32` — zero boilerplate needed.
 
 <details>
   <summary>Concepts</summary>
@@ -61,21 +106,15 @@ The library can be split into three main parts:
 
 ### Output class
 
-The `Output` class is dynamically created by providing `ECPair` and `BIP32` factory APIs:
-
-```javascript
-import * as descriptors from '@kukks/bitcoin-descriptors';
-const { Output } = descriptors.DescriptorsFactory({ ECPair, BIP32 });
-```
+The `Output` class is created via `DescriptorsFactory`:
 
-Here, `ECPair` and `BIP32` are implementations of the `ECPairAPI` and `BIP32API` interfaces. These interfaces now use `Uint8Array` instead of `Buffer` for all binary data (public keys, private keys, signatures, etc.).
+```typescript
+import { DescriptorsFactory } from '@kukks/bitcoin-descriptors';
 
-Once set up, you can obtain an instance for an output:
+const { Output } = DescriptorsFactory();
 
-```javascript
 const wpkhOutput = new Output({
-  descriptor:
-    'wpkh(02f9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9)'
+  descriptor: 'wpkh(02f9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9)'
 });
 ```
 
@@ -83,33 +122,35 @@ For miniscript-based descriptors, the `signersPubKeys` parameter in the construc
 
 The `Output` class offers various helpful methods, including `getAddress()`, `getScriptPubKey()` (returns `Uint8Array`), `expand()`, `updatePsbtAsInput()` and `updatePsbtAsOutput()`.
 
- The library supports a wide range of descriptor types, including:
- - Pay-to-Public-Key-Hash (P2PKH): `pkh(KEY)`
- - Pay-to-Witness-Public-Key-Hash (P2WPKH): `wpkh(KEY)`
- - Pay-to-Script-Hash (P2SH): `sh(SCRIPT)`
- - Pay-to-Witness-Script-Hash (P2WSH): `wsh(SCRIPT)`
- - Pay-to-Taproot (P2TR) with single key: `tr(KEY)`
- - Address-based descriptors: `addr(ADDRESS)`, including Taproot addresses
+The library supports a wide range of descriptor types, including:
+- Pay-to-Public-Key-Hash (P2PKH): `pkh(KEY)`
+- Pay-to-Witness-Public-Key-Hash (P2WPKH): `wpkh(KEY)`
+- Pay-to-Script-Hash (P2SH): `sh(SCRIPT)`
+- Pay-to-Witness-Script-Hash (P2WSH): `wsh(SCRIPT)`
+- Pay-to-Taproot (P2TR) with single key: `tr(KEY)`
+- Address-based descriptors: `addr(ADDRESS)`, including Taproot addresses
 
 #### Working with PSBTs
 
 This library uses `Transaction` from `@scure/btc-signer` as the PSBT class:
 
-```javascript
+```typescript
 import { Transaction } from '@scure/btc-signer';
+
 const psbt = new Transaction({ allowUnknownOutputs: true, disableScriptCheck: true });
 const inputFinalizer = output.updatePsbtAsInput({ psbt, txHex, vout });
 ```
 
-Here, `psbt` refers to an instance of the [`@scure/btc-signer` Transaction class](https://github.com/nicolo-ribaudo/scure-btc-signer). The parameter `txHex` denotes a hex string that serializes the previous transaction containing this output. Meanwhile, `vout` is an integer that marks the position of the output within that transaction.
+Here, `psbt` refers to an instance of the [`@scure/btc-signer` Transaction class](https://github.com/paulmillr/scure-btc-signer). The parameter `txHex` denotes a hex string that serializes the previous transaction containing this output. Meanwhile, `vout` is an integer that marks the position of the output within that transaction.
 
 The method returns the `inputFinalizer()` function. This finalizer function completes a PSBT input by adding the unlocking script (`scriptWitness` or `scriptSig`) that satisfies the previous output's spending conditions. Complete all necessary signing operations before calling `inputFinalizer()`.
 
 To add an output:
 
-```javascript
-const recipientOutput =
- new Output({ descriptor: `addr(bc1qgw6xanldsz959z45y4dszehx4xkuzf7nfhya8x)` });
+```typescript
+const recipientOutput = new Output({
+  descriptor: 'addr(bc1qgw6xanldsz959z45y4dszehx4xkuzf7nfhya8x)'
+});
 recipientOutput.updatePsbtAsOutput({ psbt, value: 10000 });
 ```
 
@@ -117,15 +158,15 @@ recipientOutput.updatePsbtAsOutput({ psbt, value: 10000 });
 
 The `expand()` function parses Bitcoin descriptors into their component parts:
 
-```javascript
+```typescript
 const output = new Output({ descriptor: "your-descriptor-here" });
 const result = output.expand();
 ```
 
 Or through the factory:
 
-```javascript
-const { expand } = descriptors.DescriptorsFactory({ ECPair, BIP32 });
+```typescript
+const { expand } = DescriptorsFactory();
 const result = expand({
   descriptor: "sh(wsh(andor(pk(0252972572d465d016d4c501887b8df303eee3ed602c056b1eb09260dfa0da0ab2),older(8640),pk([d34db33f/49'/0'/0']tpubDCdxmvzJ5QBjTN8oCjjyT2V58AyZvA1fkmCeZRC75QMoaHcVP2m45Bv3hmnR7ttAwkb2UNYyoXdHVt4gwBqRrJqLUU2JrM43HippxiWpHra/1/2/3/4/*))))"
 });
@@ -135,7 +176,7 @@ const result = expand({
 
 This library includes two signers: ECPair (single-signature) and BIP32.
 
-```javascript
+```typescript
 import { signers } from '@kukks/bitcoin-descriptors';
 
 // For BIP32
@@ -149,13 +190,13 @@ signers.signECPair({ psbt, ecpair });
 
 1. For each unspent output, call `updatePsbtAsInput`:
 
-   ```javascript
+   ```typescript
    const inputFinalizer = output.updatePsbtAsInput({ psbt, txHex, vout });
    ```
 
 2. After signing, finalize each input:
 
-   ```javascript
+   ```typescript
    inputFinalizer({ psbt });
    ```
 
@@ -163,7 +204,7 @@ signers.signECPair({ psbt, ecpair });
 
 Helper functions for generating descriptor strings:
 
-```javascript
+```typescript
 import { scriptExpressions, keyExpressionBIP32 } from '@kukks/bitcoin-descriptors';
 ```
 
@@ -171,7 +212,7 @@ The `scriptExpressions` module includes functions like `pkhBIP32()`, `shWpkhBIP3
 
 The `keyExpressionBIP32` function generates BIP32 key expression strings:
 
-```javascript
+```typescript
 keyExpressionBIP32({
   masterNode,     // BIP32Interface
   originPath,     // e.g. "/44'/0'/0'"
@@ -181,6 +222,36 @@ keyExpressionBIP32({
 });
 ```
 
+## API Reference
+
+### Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `DescriptorsFactory` | function | Creates `Output`, `expand`, `parseKeyExpression` — params optional (defaults to built-in adapters) |
+| `defaultFactory` | object | Pre-built factory using built-in adapters |
+| `nobleECPair` | `ECPairAPI` | Built-in ECPair adapter using `@noble/curves` secp256k1 |
+| `scureBIP32` | `BIP32API` | Built-in BIP32 adapter using `@scure/bip32` |
+| `signers` | namespace | `signECPair`, `signBIP32` and related signing functions |
+| `scriptExpressions` | namespace | `pkhBIP32`, `shWpkhBIP32`, `wpkhBIP32`, etc. |
+| `keyExpressionBIP32` | function | Generate BIP32 key expression strings |
+| `networks` | object | `bitcoin`, `testnet`, `regtest` network definitions |
+| `checksum` | function | Compute/validate descriptor checksums |
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `ECPairAPI` | Factory interface for creating key pairs |
+| `ECPairInterface` | Key pair instance with `sign`, `verify`, `publicKey`, etc. |
+| `BIP32API` | Factory interface for creating HD keys (`fromSeed`, `fromBase58`, etc.) |
+| `BIP32Interface` | HD key instance with `derivePath`, `derive`, `sign`, etc. |
+| `OutputInstance` | Instance returned by `new Output(...)` |
+| `Network` | Network configuration (`bitcoin`, `testnet`, `regtest`) |
+| `PsbtLike` | PSBT interface (compatible with `@scure/btc-signer` Transaction) |
+| `KeyInfo` | Parsed key expression data |
+| `Expansion` | Parsed descriptor expansion data |
+
 ## Building from source
 
 ```bash

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/dist/miniscript.js

@@ -6,7 +6,23 @@ import { hash160 } from '@scure/btc-signer/utils.js';
 import { hex } from '@scure/base';
 import { parseKeyExpression } from './keyExpressions.js';
 import * as RE from './re.js';
-import { compileMiniscript, satisfier } from '@bitcoinerlab/miniscript';
+import { createRequire } from 'module';
+// Lazy-load @bitcoinerlab/miniscript (optional peer dependency).
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _miniscriptLib;
+function getMiniscriptLib() {
+    if (!_miniscriptLib) {
+        try {
+            const require = createRequire(import.meta.url);
+            _miniscriptLib = require('@bitcoinerlab/miniscript');
+        }
+        catch {
+            throw new Error('@bitcoinerlab/miniscript is required for miniscript descriptors. ' +
+                'Install it: npm install @bitcoinerlab/miniscript');
+        }
+    }
+    return _miniscriptLib;
+}
 /**
  * Expand a miniscript to a generalized form using variables instead of key
  * expressions. Variables will be of this form: @0, @1, ...
@@ -84,7 +100,7 @@ function substituteAsm({ expandedAsm, expansionMap }) {
     return asm;
 }
 export function miniscript2Script({ expandedMiniscript, expansionMap }) {
-    const compiled = compileMiniscript(expandedMiniscript);
+    const compiled = getMiniscriptLib().compileMiniscript(expandedMiniscript);
     if (compiled.issane !== true) {
         throw new Error(`Error: Miniscript ${expandedMiniscript} is not sane`);
     }
@@ -128,7 +144,7 @@ export function satisfyMiniscript({ expandedMiniscript, expansionMap, signatures
     const expandedKnownsMap = { ...preimageMap, ...expandedSignatureMap };
     const knowns = Object.keys(expandedKnownsMap);
     //satisfier verifies again internally whether expandedKnownsMap with given knowns is sane
-    const { nonMalleableSats } = satisfier(expandedMiniscript, { knowns });
+    const { nonMalleableSats } = getMiniscriptLib().satisfier(expandedMiniscript, { knowns });
     if (!Array.isArray(nonMalleableSats) || !nonMalleableSats[0])
         throw new Error(`Error: unresolvable miniscript ${expandedMiniscript}`);
     let sat;

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.2.1",
   "author": "Jose-Luis Landabaso",
   "license": "MIT",
   "repository": {
@@ -51,14 +51,22 @@
   ],
   "devDependencies": {
     "@bitcoinerlab/configs": "^2.0.0",
+    "@bitcoinerlab/miniscript": "^1.4.3",
     "bip39": "^3.0.4",
     "bip65": "^1.0.3",
     "bip68": "^1.0.4",
     "regtest-client": "^0.2.1",
     "yargs": "^17.7.2"
   },
+  "peerDependencies": {
+    "@bitcoinerlab/miniscript": "^1.4.3"
+  },
+  "peerDependenciesMeta": {
+    "@bitcoinerlab/miniscript": {
+      "optional": true
+    }
+  },
   "dependencies": {
-    "@bitcoinerlab/miniscript": "^1.4.3",
     "@noble/curves": "^2.0.1",
     "@noble/hashes": "^2.0.1",
     "@scure/base": "^2.0.0",