@bitcoinerlab/descriptors 2.3.6 → 3.0.1

package/dist/tapTree.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TAPTREE_DEPTH = void 0;
+exports.assertTapTreeDepth = assertTapTreeDepth;
+exports.collectTapTreeLeaves = collectTapTreeLeaves;
+exports.selectTapLeafCandidates = selectTapLeafCandidates;
+exports.parseTapTreeExpression = parseTapTreeExpression;
+// NOTE: This uses an internal bitcoinjs-lib module. Consider adding a local wrapper.
+const bitcoinjs_lib_internals_1 = require("./bitcoinjs-lib-internals");
+const uint8array_tools_1 = require("uint8array-tools");
+const parseUtils_1 = require("./parseUtils");
+// See BIP341 control block limits and Sipa's Miniscript "Resource limitations":
+// https://bitcoin.sipa.be/miniscript/
+// Taproot script path depth is encoded in the control block as 32-byte hashes,
+// with consensus max depth 128.
+exports.MAX_TAPTREE_DEPTH = 128;
+function tapTreeMaxDepth(tapTree, depth = 0) {
+    if ('expression' in tapTree)
+        return depth;
+    return Math.max(tapTreeMaxDepth(tapTree.left, depth + 1), tapTreeMaxDepth(tapTree.right, depth + 1));
+}
+function assertTapTreeDepth(tapTree) {
+    const maxDepth = tapTreeMaxDepth(tapTree);
+    if (maxDepth > exports.MAX_TAPTREE_DEPTH)
+        throw new Error(`Error: taproot tree depth is too large, ${maxDepth} is larger than ${exports.MAX_TAPTREE_DEPTH}`);
+}
+/**
+ * Collects taproot leaf metadata with depth from a tree.
+ * Traversal is left-first, following the order of `{left,right}` in the
+ * expression so tie-breaks are deterministic.
+ *
+ * Example tree:
+ * ```
+ * {pk(A),{pk(B),pk(C)}}
+ * ```
+ * Visual shape:
+ * ```
+ *         root
+ *        /    \
+ *     pk(A)  branch
+ *            /   \
+ *         pk(B) pk(C)
+ * ```
+ * Collected leaves with depth:
+ * ```
+ * [
+ *   { leaf: pk(A), depth: 1 },
+ *   { leaf: pk(B), depth: 2 },
+ *   { leaf: pk(C), depth: 2 }
+ * ]
+ * ```
+ */
+function collectTapTreeLeaves(tapTreeInfo) {
+    const leaves = [];
+    const walk = (node, depth) => {
+        if ('expression' in node) {
+            leaves.push({ leaf: node, depth });
+            return;
+        }
+        walk(node.left, depth + 1);
+        walk(node.right, depth + 1);
+    };
+    walk(tapTreeInfo, 0);
+    return leaves;
+}
+function computeTapLeafHash(leaf) {
+    return (0, bitcoinjs_lib_internals_1.tapleafHash)({ output: leaf.tapScript, version: leaf.version });
+}
+function normalizeExpressionForMatch(expression) {
+    return expression.replace(/\s+/g, '');
+}
+/**
+ * Resolves taproot leaf candidates based on an optional selector.
+ *
+ * If `tapLeaf` is undefined, all leaves are returned for auto-selection.
+ * If `tapLeaf` is bytes, it is treated as a tapleaf hash and must match
+ * exactly one leaf.
+ * If `tapLeaf` is a string, it is treated as a raw taproot leaf expression
+ * (not expanded). Matching is whitespace-insensitive. If the expression appears
+ * more than once, this function throws an error.
+ *
+ * Example:
+ * ```
+ * const candidates = selectTapLeafCandidates({ tapTreeInfo, tapLeaf });
+ * // tapLeaf can be undefined, bytes (tapleaf hash) or a leaf expression:
+ * // f.ex.: 'pk(03bb...)'
+ * ```
+ */
+function selectTapLeafCandidates({ tapTreeInfo, tapLeaf }) {
+    const leaves = collectTapTreeLeaves(tapTreeInfo).map(({ leaf, depth }) => ({
+        leaf,
+        depth,
+        tapLeafHash: computeTapLeafHash(leaf)
+    }));
+    if (tapLeaf === undefined)
+        return leaves;
+    if (tapLeaf instanceof Uint8Array) {
+        const match = leaves.find(entry => (0, uint8array_tools_1.compare)(entry.tapLeafHash, tapLeaf) === 0);
+        if (!match)
+            throw new Error(`Error: tapleaf hash not found in tapTreeInfo`);
+        return [match];
+    }
+    const normalizedSelector = normalizeExpressionForMatch(tapLeaf);
+    const matches = leaves.filter(entry => normalizeExpressionForMatch(entry.leaf.expression) === normalizedSelector);
+    if (matches.length === 0)
+        throw new Error(`Error: taproot leaf expression not found in tapTreeInfo: ${tapLeaf}`);
+    if (matches.length > 1)
+        throw new Error(`Error: taproot leaf expression is ambiguous in tapTreeInfo: ${tapLeaf}`);
+    return matches;
+}
+function tapTreeError(expression) {
+    return new Error(`Error: invalid taproot tree expression: ${expression}`);
+}
+/**
+ * Splits the inner tree expression of a branch into left/right parts.
+ * The input must be the contents inside `{}` (no outer braces).
+ * Example: `pk(@0),{pk(@1),pk(@2)}` => left: `pk(@0)`, right: `{pk(@1),pk(@2)}`.
+ */
+function splitTapTreeExpression(expression) {
+    const result = (0, parseUtils_1.splitTopLevelComma)({ expression, onError: tapTreeError });
+    if (!result)
+        throw tapTreeError(expression);
+    return result;
+}
+/**
+ * Parses a single taproot tree node expression.
+ *
+ * Note: the field name is intentionally generic (`expression`) because taproot
+ * leaves can contain either miniscript fragments (e.g. `pk(...)`) or
+ * descriptor-level script expressions (e.g. `sortedmulti_a(...)`).
+ * Examples:
+ * - `pk(@0)` => { expression: 'pk(@0)' }
+ * - `{pk(@0),pk(@1)}` => { left: { expression: 'pk(@0)' }, right: { expression: 'pk(@1)' } }
+ * - `{pk(@0),{pk(@1),pk(@2)}}` =>
+ *   {
+ *     left: { expression: 'pk(@0)' },
+ *     right: { left: { expression: 'pk(@1)' }, right: { expression: 'pk(@2)' } }
+ *   }
+ */
+function parseTapTreeNode(expression) {
+    const trimmedExpression = expression.trim();
+    if (!trimmedExpression)
+        throw tapTreeError(expression);
+    if (trimmedExpression.startsWith('{')) {
+        if (!trimmedExpression.endsWith('}'))
+            throw tapTreeError(expression);
+        const inner = trimmedExpression.slice(1, -1).trim();
+        if (!inner)
+            throw tapTreeError(expression);
+        const { left, right } = splitTapTreeExpression(inner);
+        return {
+            left: parseTapTreeNode(left),
+            right: parseTapTreeNode(right)
+        };
+    }
+    if (trimmedExpression.includes('{') || trimmedExpression.includes('}'))
+        throw tapTreeError(expression);
+    return { expression: trimmedExpression };
+}
+function parseTapTreeExpression(expression) {
+    const trimmed = expression.trim();
+    if (!trimmed)
+        throw tapTreeError(expression);
+    const tapTree = parseTapTreeNode(trimmed);
+    assertTapTreeDepth(tapTree);
+    return tapTree;
+}

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 import type { ECPairInterface } from 'ecpair';
 import type { BIP32Interface } from 'bip32';
 import type { Payment, Network } from 'bitcoinjs-lib';
+import type { TapTreeNode, TapTreeInfoNode } from './tapTree';
 /**
  * Preimage
  * See {@link Output}
@@ -24,14 +25,14 @@ export type TimeConstraints = {
     nSequence: number | undefined;
 };
 /**
- * See {@link _Internal_.ParseKeyExpression | ParseKeyExpression}.
+ * See {@link _Internal_.KeyExpressionParser | KeyExpressionParser}.
  */
 export type KeyInfo = {
     keyExpression: string;
-    pubkey?: Buffer;
+    pubkey?: Uint8Array;
     ecpair?: ECPairInterface;
     bip32?: BIP32Interface;
-    masterFingerprint?: Buffer;
+    masterFingerprint?: Uint8Array;
     originPath?: string;
     keyPath?: string;
     path?: string;
@@ -127,14 +128,59 @@ export type Expansion = {
      * expression.
      */
     expandedMiniscript?: string;
+    /**
+     * The taproot tree expression, if any. Only defined for `tr(KEY, TREE)`.
+     * Example: `{pk(02aa...),{pk(03bb...),pk(02cc...)}}`.
+     */
+    tapTreeExpression?: string;
+    /**
+     * The parsed taproot tree, if any. Only defined for `tr(KEY, TREE)`.
+     * Example:
+     * ```
+     * {
+     *   left: { expression: 'pk(02aa...)' },
+     *   right: {
+     *     left: { expression: 'pk(03bb...)' },
+     *     right: { expression: 'pk(02cc...)' }
+     *   }
+     * }
+     * ```
+     */
+    tapTree?: TapTreeNode;
+    /**
+     * The compiled taproot tree metadata, if any. Only defined for `tr(KEY, TREE)`.
+     * Same as tapTree, but each leaf includes:
+     * - `expandedExpression`: descriptor-level expanded leaf expression
+     * - optional `expandedMiniscript`: miniscript-expanded leaf (when applicable)
+     * - key expansion map
+     * - compiled tapscript (`tapScript`)
+     * - leaf version.
+     *
+     * Note: `@i` placeholders are scoped per leaf, since each leaf is expanded
+     * and satisfied independently.
+     *
+     * Example:
+     * ```
+     * {
+     *   left: {
+     *     expression: 'pk(02aa...)',
+     *     expandedExpression: 'pk(@0)',
+     *     expandedMiniscript: 'pk(@0)',
+     *     expansionMap: ExpansionMap;
+     *     tapScript: Uint8Array;
+     *     version: number;
+     *   },
+     *   right: ....
+     */
+    tapTreeInfo?: TapTreeInfoNode;
     /**
      * The redeem script for the descriptor, if applicable.
      */
-    redeemScript?: Buffer;
+    redeemScript?: Uint8Array;
     /**
      * The witness script for the descriptor, if applicable.
      */
-    witnessScript?: Buffer;
+    witnessScript?: Uint8Array;
     /**
      * Whether the descriptor is a ranged-descriptor.
      */
@@ -170,7 +216,7 @@ export type Expansion = {
  *
  * See {@link KeyInfo} for the complete list of elements retrieved by this function.
  */
-export interface ParseKeyExpression {
+export interface KeyExpressionParser {
     (params: {
         keyExpression: string;
         /**

package/package.json

@@ -2,7 +2,7 @@
   "name": "@bitcoinerlab/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/bitcoinerlab/descriptors",
-  "version": "2.3.6",
+  "version": "3.0.1",
   "author": "Jose-Luis Landabaso",
   "license": "MIT",
   "repository": {
@@ -36,43 +36,43 @@
     "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:integration:ledger": "npm run ensureTester && node test/integration/ledger.js",
-    "test:integration:deprecated": "npm run ensureTester && node test/integration/standardOutputs-deprecated.js && echo \"\n\n\" && node test/integration/miniscript-deprecated.js && echo \"\n\n\" && node test/integration/ledger-deprecated.js",
+    "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 && echo \"\n\n\" && node test/integration/taproot.js",
+    "test:integration:ledger": "npm run ensureTester && node test/integration/ledgerTaproot.js && echo \"\n\n\" && node test/integration/ledger.js",
     "test:unit": "jest",
     "test": "npm run lint && npm run build && npm run test:unit && npm run test:integration:soft",
     "testledger": "npm run lint && npm run build && npm run test:integration:ledger",
-    "prepublishOnly": "npm run test && echo \"\n\n\" && npm run test:integration:deprecated && npm run test:integration:ledger"
+    "prepublishOnly": "npm run test && echo \"\n\n\" && npm run test:integration:ledger"
   },
   "files": [
     "dist"
   ],
   "peerDependencies": {
-    "ledger-bitcoin": "^0.2.2"
+    "@ledgerhq/ledger-bitcoin": "^0.3.0"
   },
   "peerDependenciesMeta": {
-    "ledger-bitcoin": {
+    "@ledgerhq/ledger-bitcoin": {
       "optional": true
     }
   },
   "devDependencies": {
     "@bitcoinerlab/configs": "^2.0.0",
-    "@ledgerhq/hw-transport-node-hid": "^6.27.12",
+    "@bitcoinerlab/miniscript-policies": "^1.0.0",
+    "@ledgerhq/hw-transport-node-hid": "^6.30.0",
+    "@ledgerhq/ledger-bitcoin": "^0.3.0",
     "@types/lodash.memoize": "^4.1.9",
     "bip39": "^3.0.4",
     "bip65": "^1.0.3",
     "bip68": "^1.0.4",
-    "ledger-bitcoin": "^0.2.2",
     "regtest-client": "^0.2.1",
     "yargs": "^17.7.2"
   },
   "dependencies": {
-    "@bitcoinerlab/miniscript": "^1.4.3",
+    "@bitcoinerlab/miniscript": "^2.0.0",
     "@bitcoinerlab/secp256k1": "^1.2.0",
     "bip32": "^4.0.0",
-    "bitcoinjs-lib": "^6.1.7",
-    "ecpair": "^2.1.0",
+    "bitcoinjs-lib": "^7.0.1",
+    "ecpair": "^3.0.1",
     "lodash.memoize": "^4.1.2",
-    "varuint-bitcoin": "^1.1.2"
+    "varuint-bitcoin": "^2.0.0"
   }
 }