@bitcoinerlab/descriptors 3.0.0 → 3.0.1

package/dist/descriptors.js

@@ -139,6 +139,22 @@ function parseSortedMulti(inner) {
         throw new Error(`sortedmulti(): descriptors support up to 20 keys (per BIP 380/383).`);
     return { m, keyExpressions };
 }
+const MAX_PUBKEYS_PER_MULTI_A = 999;
+// Helper: parse sortedmulti_a(M, k1, k2,...)
+function parseSortedMultiA(inner) {
+    const parts = inner.split(',').map(p => p.trim());
+    if (parts.length < 2)
+        throw new Error(`sortedmulti_a(): must contain M and at least one key: ${inner}`);
+    const m = Number(parts[0]);
+    if (!Number.isInteger(m) || m < 1)
+        throw new Error(`sortedmulti_a(): invalid M=${parts[0]}`);
+    const keyExpressions = parts.slice(1);
+    if (keyExpressions.length < m)
+        throw new Error(`sortedmulti_a(): M cannot exceed number of keys: ${inner}`);
+    if (keyExpressions.length > MAX_PUBKEYS_PER_MULTI_A)
+        throw new Error(`sortedmulti_a(): descriptors support up to ${MAX_PUBKEYS_PER_MULTI_A} keys.`);
+    return { m, keyExpressions };
+}
 function parseTrExpression(expression) {
     if (!expression.startsWith('tr(') || !expression.endsWith(')'))
         throw new Error(`Error: invalid descriptor ${expression}`);
@@ -205,6 +221,69 @@ function DescriptorsFactory(ecc) {
             BIP32
         });
     };
+    /**
+     * Builds a taproot leaf expansion override for descriptor-level
+     * `sortedmulti_a(...)`.
+     *
+     * Why this exists:
+     * - `sortedmulti_a` is a descriptor script expression (not a Miniscript
+     *   fragment).
+     *
+     * What this does:
+     * - Resolves each key expression to a concrete pubkey and builds a leaf-local
+     *   placeholder map (`@0`, `@1`, ... in input order).
+     * - Derives the internal compilation form by sorting placeholders by pubkey
+     *   bytes and lowering to `multi_a(...)`.
+     * - Compiles tapscript from that lowered form and returns it as override
+     *   data.
+     *
+     * Returns `undefined` for non-`sortedmulti_a` leaves so normal taproot miniscript
+     * expansion/compilation is used.
+     */
+    function buildTapLeafSortedMultiAOverride({ expression, network = bitcoinjs_lib_1.networks.bitcoin }) {
+        if (!/\bsortedmulti_a\(/.test(expression))
+            return undefined;
+        const trimmed = expression.trim();
+        const match = trimmed.match(/^sortedmulti_a\((.*)\)$/);
+        if (!match)
+            throw new Error(`Error: sortedmulti_a() must be a standalone taproot leaf expression`);
+        const inner = match[1];
+        if (!inner)
+            throw new Error(`Error: invalid sortedmulti_a() expression: ${expression}`);
+        const { m, keyExpressions } = parseSortedMultiA(inner);
+        const keyInfos = keyExpressions.map(keyExpression => {
+            const keyInfo = parseKeyExpression({
+                keyExpression,
+                isSegwit: true,
+                isTaproot: true,
+                network
+            });
+            if (!keyInfo.pubkey)
+                throw new Error(`Error: sortedmulti_a() key must resolve to a concrete pubkey: ${keyExpression}`);
+            return keyInfo;
+        });
+        const expansionMap = {};
+        keyInfos.forEach((keyInfo, index) => {
+            expansionMap[`@${index}`] = keyInfo;
+        });
+        // sortedmulti_a is descriptor-level sugar. We preserve it in
+        // expandedExpression, but compile tapscript from its internal multi_a
+        // lowering with sorted placeholders.
+        const expandedExpression = `sortedmulti_a(${[
+            m,
+            ...Object.keys(expansionMap)
+        ].join(',')})`;
+        const compileExpandedMiniscript = (0, tapMiniscript_1.compileSortedMultiAExpandedExpression)({
+            expandedExpression,
+            expansionMap
+        });
+        const tapScript = (0, miniscript_1.miniscript2Script)({
+            expandedMiniscript: compileExpandedMiniscript,
+            expansionMap,
+            tapscript: true
+        });
+        return { expandedExpression, expansionMap, tapScript };
+    }
     function expand({ descriptor, index, change, checksumRequired = false, network = bitcoinjs_lib_1.networks.bitcoin, allowMiniscriptInP2SH = false }) {
         if (!descriptor)
             throw new Error(`descriptor not provided`);
@@ -503,10 +582,14 @@ function DescriptorsFactory(ecc) {
             if (!miniscript)
                 throw new Error(`Error: could not get miniscript in ${descriptor}`);
             if (allowMiniscriptInP2SH === false &&
-                //These top-level expressions within sh are allowed within sh.
-                //They can be parsed with miniscript2Script, but first we must make sure
-                //that other expressions are not accepted (unless forced with allowMiniscriptInP2SH).
-                miniscript.search(/^(pk\(|pkh\(|wpkh\(|combo\(|multi\(|sortedmulti\(|multi_a\(|sortedmulti_a\()/) !== 0) {
+                // These top-level script expressions are allowed inside sh(...).
+                // The sorted script expressions (`sortedmulti`, `sortedmulti_a`) are
+                // handled in dedicated descriptor/taproot branches and are intentionally
+                // not part of this miniscript gate.
+                // Here we only keep legacy top-level forms to avoid accepting arbitrary
+                // miniscript in P2SH unless explicitly enabled.
+                miniscript.search(/^(pk\(|pkh\(|wpkh\(|combo\(|multi\(|multi_a\()/) !==
+                    0) {
                 throw new Error(`Error: Miniscript expressions can only be used in wsh`);
             }
             ({ expandedMiniscript, expansionMap } = expandMiniscript({
@@ -567,7 +650,18 @@ function DescriptorsFactory(ecc) {
                 tapTreeExpression = treeExpression;
                 tapTree = (0, tapTree_1.parseTapTreeExpression)(treeExpression);
                 if (!isCanonicalRanged) {
-                    tapTreeInfo = (0, tapMiniscript_1.buildTapTreeInfo)({ tapTree, network, BIP32, ECPair });
+                    tapTreeInfo = (0, tapMiniscript_1.buildTapTreeInfo)({
+                        tapTree,
+                        network,
+                        BIP32,
+                        ECPair,
+                        // `leafExpansionOverride` runs per leaf expression.
+                        // For non-matching leaves it returns undefined and
+                        // normal miniscript expansion is used;
+                        // for sortedmulti_a leaves it returns descriptor-level
+                        // metadata plus precompiled tapscript bytes.
+                        leafExpansionOverride: (expression) => buildTapLeafSortedMultiAOverride({ expression, network })
+                    });
                 }
             }
             if (!isCanonicalRanged) {

package/dist/ledger.js

@@ -268,18 +268,16 @@ async function ledgerPolicyFromPsbtInput({ ledgerManager, psbt, index }) {
                     // Replace change (making sure the value in the change level for the
                     // template of the policy meets the change in bip32Derivation):
                     descriptor = descriptor.replace(/\/\*\*/g, `/<0;1>/*`);
-                    const regExpMN = new RegExp(`/<(\\d+);(\\d+)>`, 'g');
-                    let matchMN;
-                    while (descriptor && (matchMN = regExpMN.exec(descriptor)) !== null) {
-                        const [M, N] = [
-                            parseInt(matchMN[1], 10),
-                            parseInt(matchMN[2], 10)
-                        ];
+                    let tupleMismatch = false;
+                    descriptor = descriptor.replace(/\/<(\d+);(\d+)>/g, (token, strM, strN) => {
+                        const [M, N] = [parseInt(strM, 10), parseInt(strN, 10)];
                         if (M === change || N === change)
-                            descriptor = descriptor.replace(`/<${M};${N}>`, `/${change}`);
-                        else
-                            descriptor = undefined;
-                    }
+                            return `/${change}`;
+                        tupleMismatch = true;
+                        return token;
+                    });
+                    if (tupleMismatch)
+                        descriptor = undefined;
                     if (descriptor) {
                         // Replace index:
                         descriptor = descriptor.replace(/\/\*/g, `/${index}`);
@@ -382,13 +380,20 @@ async function ledgerPolicyFromOutput({ output, ledgerManager }) {
             return placeholder;
         };
         const remapTapTree = (node) => {
-            if ('miniscript' in node) {
-                let remappedMiniscript = node.expandedMiniscript;
-                const localEntries = Object.entries(node.expansionMap).sort(([placeholderA], [placeholderB]) => placeholderB.length - placeholderA.length);
+            if ('expression' in node) {
+                // Prefer descriptor-level expanded expression for policy templates so
+                // script expressions (e.g. sortedmulti_a) are preserved. Fall back to
+                // expandedMiniscript for older metadata.
+                let remappedMiniscript = node.expandedExpression ?? node.expandedMiniscript;
+                if (!remappedMiniscript)
+                    throw new Error(`Error: taproot leaf expansion not available`);
+                const localEntries = Object.entries(node.expansionMap);
+                const localToGlobalPlaceholder = new Map();
                 for (const [localPlaceholder, keyInfo] of localEntries) {
                     const globalPlaceholder = globalPlaceholderFor(keyInfo);
-                    remappedMiniscript = remappedMiniscript.replaceAll(localPlaceholder, globalPlaceholder);
+                    localToGlobalPlaceholder.set(localPlaceholder, globalPlaceholder);
                 }
+                remappedMiniscript = remappedMiniscript.replace(/@\d+/g, placeholder => localToGlobalPlaceholder.get(placeholder) ?? placeholder);
                 return remappedMiniscript;
             }
             return `{${remapTapTree(node.left)},${remapTapTree(node.right)}}`;
@@ -400,11 +405,15 @@ async function ledgerPolicyFromOutput({ output, ledgerManager }) {
     const ledgerMasterFingerprint = await getLedgerMasterFingerPrint({
         ledgerManager
     });
-    //It's important to have keys sorted in ascii order. keys
-    //are of this type: @0, @1, @2, ....  and they also appear in the expandedExpression
-    //in ascending ascii order. Note that Object.keys(expansionMap ) does not ensure
-    //that the order is respected and so we force it.
-    const allKeys = Object.keys(expansionMap).sort();
+    // Keep placeholders in numeric order (@0, @1, @2, ...). This avoids
+    // lexicographic pitfalls like @10 being ordered before @2.
+    const allKeys = Object.keys(expansionMap).sort((a, b) => {
+        const aIndex = Number(a.slice(1));
+        const bIndex = Number(b.slice(1));
+        if (Number.isNaN(aIndex) || Number.isNaN(bIndex))
+            return a.localeCompare(b);
+        return aIndex - bIndex;
+    });
     const ledgerKeys = allKeys.filter(key => {
         const masterFingerprint = expansionMap[key]?.masterFingerprint;
         return (masterFingerprint &&
@@ -425,8 +434,8 @@ async function ledgerPolicyFromOutput({ output, ledgerManager }) {
     if (!/^\/[01]\/\d+$/.test(keyPath))
         throw new Error(`Error: key paths must be /<1;0>/index, where change is 1 or 0 and index >= 0`);
     const keyRoots = [];
-    let ledgerTemplate = expandedExpression;
-    allKeys.forEach(key => {
+    const placeholderToLedgerPlaceholder = new Map();
+    allKeys.forEach((key, index) => {
         if (key !== ledgerKey) {
             //This block here only does data integrity assertions:
             const otherKeyInfo = expansionMap[key];
@@ -442,13 +451,14 @@ async function ledgerPolicyFromOutput({ output, ledgerManager }) {
                 throw new Error(`Error: all keyPaths must be the same for Ledger being able to sign: ${otherKeyInfo.keyPath} !== ${keyPath}`);
             }
         }
-        ledgerTemplate = ledgerTemplate.replaceAll(key, `@${keyRoots.length}/**`);
+        placeholderToLedgerPlaceholder.set(key, `@${index}/**`);
         const keyInfo = expansionMap[key];
         if (keyInfo.masterFingerprint && keyInfo.originPath)
             keyRoots.push(`[${(0, uint8array_tools_1.toHex)(keyInfo.masterFingerprint)}${keyInfo.originPath}]${keyInfo?.bip32?.neutered().toBase58()}`);
         else
             keyRoots.push(`${keyInfo?.bip32?.neutered().toBase58()}`);
     });
+    const ledgerTemplate = expandedExpression.replace(/@\d+/g, placeholder => placeholderToLedgerPlaceholder.get(placeholder) ?? placeholder);
     return { ledgerTemplate, keyRoots };
 }
 /**

package/dist/miniscript.js

@@ -78,11 +78,16 @@ function expandMiniscript({ miniscript, isSegwit, isTaproot, network = bitcoinjs
         });
         return key;
     };
-    //These are the fragments where keys are allowed. Note that we only look
-    //inside these fragments to avoid problems in pregimages like sha256 which can
-    //contain hex values which could be confussed with a key
-    const keyFragmentRegex = /\b(pk|pkh|sortedmulti_a|sortedmulti|multi_a|multi)\(([^()]*)\)/g;
-    const expandedMiniscript = miniscript.replace(keyFragmentRegex, (_, name, inner) => {
+    // These are the Miniscript fragments where key arguments are expected.
+    // We only replace key expressions inside these fragments to avoid confusing
+    // hash preimages (e.g. sha256(03...)) with keys.
+    //
+    // Note: sorted script expressions (`sortedmulti`, `sortedmulti_a`) are
+    // intentionally excluded here. They are descriptor-level expressions (not
+    // Miniscript fragments) and are handled in descriptor/tap-tree code paths
+    // before Miniscript compilation.
+    const keyBearingFragmentRegex = /\b(pk|pkh|multi_a|multi)\(([^()]*)\)/g;
+    const expandedMiniscript = miniscript.replace(keyBearingFragmentRegex, (_, name, inner) => {
         if (name === 'pk' || name === 'pkh')
             return `${name}(${replaceKeyExpression(inner)})`;
         //now do *multi* which has arguments:

package/dist/tapMiniscript.d.ts

@@ -3,8 +3,13 @@ import type { BIP32API } from 'bip32';
 import type { ECPairAPI } from 'ecpair';
 import type { PartialSig, TapBip32Derivation } from 'bip174';
 import type { Taptree } from 'bitcoinjs-lib/src/cjs/types';
-import type { KeyInfo, Preimage, TimeConstraints } from './types';
+import type { ExpansionMap, KeyInfo, Preimage, TimeConstraints } from './types';
 import type { TapLeafInfo, TapTreeInfoNode, TapTreeNode } from './tapTree';
+export type TapLeafExpansionOverride = {
+    expandedExpression: string;
+    expansionMap: ExpansionMap;
+    tapScript: Uint8Array;
+};
 export type TaprootLeafSatisfaction = {
     leaf: TapLeafInfo;
     depth: number;
@@ -23,15 +28,23 @@ export type TaprootPsbtLeafMetadata = {
 };
 /**
  * Compiles a taproot miniscript tree into per-leaf metadata.
- * Each leaf contains its expanded miniscript, expansion map, compiled tapscript
- * and leaf version. This keeps the taproot script-path data ready for
- * satisfactions and witness building.
+ * Each leaf contains expanded expression metadata, key expansion map,
+ * compiled tapscript and leaf version. This keeps the taproot script-path data
+ * ready for satisfactions and witness building.
+ *
+ * `leafExpansionOverride` allows descriptor-level script expressions to provide:
+ * - user-facing expanded expression metadata (for selector/template use), and
+ * - custom expansion map and tapscript bytes for compilation.
+ *
+ * Example: sortedmulti_a can expose `expandedExpression=sortedmulti_a(...)`
+ * while providing a tapscript already compiled.
  */
-export declare function buildTapTreeInfo({ tapTree, network, BIP32, ECPair }: {
+export declare function buildTapTreeInfo({ tapTree, network, BIP32, ECPair, leafExpansionOverride }: {
     tapTree: TapTreeNode;
     network?: Network;
     BIP32: BIP32API;
     ECPair: ECPairAPI;
+    leafExpansionOverride: (expression: string) => TapLeafExpansionOverride | undefined;
 }): TapTreeInfoNode;
 export declare function tapTreeInfoToScriptTree(tapTreeInfo: TapTreeInfoNode): Taptree;
 /**
@@ -142,6 +155,15 @@ export declare function buildTaprootBip32Derivations({ tapTreeInfo, internalKeyI
     internalKeyInfo?: KeyInfo;
 }): TapBip32Derivation[];
 export declare function normalizeTaprootPubkey(pubkey: Uint8Array): Uint8Array;
+/**
+ * Compiles an expanded `sortedmulti_a(...)` leaf expression to its internal
+ * `multi_a(...)` form by sorting placeholders using the resolved pubkeys from
+ * `expansionMap`.
+ */
+export declare function compileSortedMultiAExpandedExpression({ expandedExpression, expansionMap }: {
+    expandedExpression: string;
+    expansionMap: ExpansionMap;
+}): string;
 /**
  * Computes satisfactions for taproot script-path leaves.
  *
@@ -174,8 +196,8 @@ export declare function collectTapTreePubkeys(tapTreeInfo: TapTreeInfoNode): Uin
  *
  * If `tapLeaf` is provided, only that leaf is considered. If `tapLeaf` is a
  * bytes, it is treated as a tapLeafHash and must match exactly one leaf. If
- * `tapLeaf` is a string, it is treated as a miniscript leaf and must match
- * exactly one leaf (whitespace-insensitive).
+ * `tapLeaf` is a string, it is treated as a raw leaf expression and must
+ * match exactly one leaf (whitespace-insensitive).
  *
  * This function is typically called twice:
  * 1) Planning pass: call it with fake signatures (built by the caller) to

package/dist/tapMiniscript.js

@@ -6,6 +6,7 @@ exports.tapTreeInfoToScriptTree = tapTreeInfoToScriptTree;
 exports.buildTaprootLeafPsbtMetadata = buildTaprootLeafPsbtMetadata;
 exports.buildTaprootBip32Derivations = buildTaprootBip32Derivations;
 exports.normalizeTaprootPubkey = normalizeTaprootPubkey;
+exports.compileSortedMultiAExpandedExpression = compileSortedMultiAExpandedExpression;
 exports.collectTaprootLeafSatisfactions = collectTaprootLeafSatisfactions;
 exports.selectBestTaprootLeafSatisfaction = selectBestTaprootLeafSatisfaction;
 exports.collectTapTreePubkeys = collectTapTreePubkeys;
@@ -30,42 +31,83 @@ function expandTaprootMiniscript({ miniscript, network = bitcoinjs_lib_1.network
 }
 /**
  * Compiles a taproot miniscript tree into per-leaf metadata.
- * Each leaf contains its expanded miniscript, expansion map, compiled tapscript
- * and leaf version. This keeps the taproot script-path data ready for
- * satisfactions and witness building.
+ * Each leaf contains expanded expression metadata, key expansion map,
+ * compiled tapscript and leaf version. This keeps the taproot script-path data
+ * ready for satisfactions and witness building.
+ *
+ * `leafExpansionOverride` allows descriptor-level script expressions to provide:
+ * - user-facing expanded expression metadata (for selector/template use), and
+ * - custom expansion map and tapscript bytes for compilation.
+ *
+ * Example: sortedmulti_a can expose `expandedExpression=sortedmulti_a(...)`
+ * while providing a tapscript already compiled.
  */
-function buildTapTreeInfo({ tapTree, network = bitcoinjs_lib_1.networks.bitcoin, BIP32, ECPair }) {
+function buildTapTreeInfo({ tapTree, network = bitcoinjs_lib_1.networks.bitcoin, BIP32, ECPair, leafExpansionOverride }) {
     // Defensive: parseTapTreeExpression() already enforces this for descriptor
     // strings, but buildTapTreeInfo is exported and can be called directly.
     (0, tapTree_1.assertTapTreeDepth)(tapTree);
-    if ('miniscript' in tapTree) {
-        const miniscript = tapTree.miniscript;
-        const { expandedMiniscript, expansionMap } = expandTaprootMiniscript({
-            miniscript,
-            network,
-            BIP32,
-            ECPair
-        });
-        const tapScript = (0, miniscript_1.miniscript2Script)({
-            expandedMiniscript,
-            expansionMap,
-            tapscript: true
-        });
+    if ('expression' in tapTree) {
+        // Tap-tree leaves store generic descriptor expressions. Most leaves are
+        // miniscript fragments, but descriptor-level script expressions (such as
+        // sortedmulti_a) can also appear and be normalized through
+        // `leafExpansionOverride`.
+        const expression = tapTree.expression;
+        const override = leafExpansionOverride(expression);
+        let expandedExpression;
+        let expandedMiniscript;
+        let expansionMap;
+        let tapScript;
+        if (override) {
+            // Descriptor-level expression overrides (e.g. sortedmulti_a) preserve a
+            // user-facing expanded expression while allowing custom compilation.
+            expandedExpression = override.expandedExpression;
+            expansionMap = override.expansionMap;
+            tapScript = override.tapScript;
+        }
+        else {
+            const expanded = expandTaprootMiniscript({
+                miniscript: expression,
+                network,
+                BIP32,
+                ECPair
+            });
+            expandedExpression = expanded.expandedMiniscript;
+            expandedMiniscript = expanded.expandedMiniscript;
+            expansionMap = expanded.expansionMap;
+            tapScript = (0, miniscript_1.miniscript2Script)({
+                expandedMiniscript: expanded.expandedMiniscript,
+                expansionMap,
+                tapscript: true
+            });
+        }
         return {
-            miniscript,
-            expandedMiniscript,
+            expression,
+            expandedExpression,
+            ...(expandedMiniscript !== undefined ? { expandedMiniscript } : {}),
             expansionMap,
             tapScript,
             version: TAPROOT_LEAF_VERSION_TAPSCRIPT
         };
     }
     return {
-        left: buildTapTreeInfo({ tapTree: tapTree.left, network, BIP32, ECPair }),
-        right: buildTapTreeInfo({ tapTree: tapTree.right, network, BIP32, ECPair })
+        left: buildTapTreeInfo({
+            tapTree: tapTree.left,
+            network,
+            BIP32,
+            ECPair,
+            leafExpansionOverride
+        }),
+        right: buildTapTreeInfo({
+            tapTree: tapTree.right,
+            network,
+            BIP32,
+            ECPair,
+            leafExpansionOverride
+        })
     };
 }
 function tapTreeInfoToScriptTree(tapTreeInfo) {
-    if ('miniscript' in tapTreeInfo) {
+    if ('expression' in tapTreeInfo) {
         return {
             output: tapTreeInfo.tapScript,
             version: tapTreeInfo.version
@@ -153,7 +195,7 @@ function buildTaprootLeafPsbtMetadata({ tapTreeInfo, internalPubkey }) {
         });
         const merklePath = (0, bitcoinjs_lib_internals_1.findScriptPath)(hashTree, tapLeafHash);
         if (!merklePath)
-            throw new Error(`Error: could not build controlBlock for taproot leaf ${leaf.miniscript}`);
+            throw new Error(`Error: could not build controlBlock for taproot leaf ${leaf.expression}`);
         // controlBlock[0] packs:
         // - leaf version (high bits), and
         // - parity of the tweaked output key Q = P + t*G (low bit).
@@ -292,6 +334,37 @@ function normalizeTaprootPubkey(pubkey) {
         return pubkey.slice(1, 33);
     throw new Error(`Error: invalid taproot pubkey length`);
 }
+/**
+ * Compiles an expanded `sortedmulti_a(...)` leaf expression to its internal
+ * `multi_a(...)` form by sorting placeholders using the resolved pubkeys from
+ * `expansionMap`.
+ */
+function compileSortedMultiAExpandedExpression({ expandedExpression, expansionMap }) {
+    const trimmed = expandedExpression.trim();
+    const match = trimmed.match(/^sortedmulti_a\((.*)\)$/);
+    if (!match)
+        throw new Error(`Error: invalid sortedmulti_a() expression: ${trimmed}`);
+    const inner = match[1];
+    if (!inner)
+        throw new Error(`Error: invalid sortedmulti_a() expression: ${trimmed}`);
+    const parts = inner.split(',').map(part => part.trim());
+    if (parts.length < 2)
+        throw new Error(`Error: invalid sortedmulti_a() expression: ${trimmed}`);
+    const threshold = parts[0];
+    if (!threshold)
+        throw new Error(`Error: invalid sortedmulti_a() threshold: ${trimmed}`);
+    const placeholders = parts.slice(1);
+    const sortedPlaceholders = placeholders
+        .map(placeholder => {
+        const keyInfo = expansionMap[placeholder];
+        if (!keyInfo?.pubkey)
+            throw new Error(`Error: sortedmulti_a() placeholder ${placeholder} not found in expansionMap`);
+        return { placeholder, pubkey: keyInfo.pubkey };
+    })
+        .sort((a, b) => (0, uint8array_tools_1.compare)(a.pubkey, b.pubkey))
+        .map(({ placeholder }) => placeholder);
+    return `multi_a(${[threshold, ...sortedPlaceholders].join(',')})`;
+}
 /**
  * Computes satisfactions for taproot script-path leaves.
  *
@@ -329,8 +402,22 @@ function collectTaprootLeafSatisfactions({ tapTreeInfo, preimages, signatures, t
         const { leaf } = candidate;
         const leafSignatures = resolveLeafSignatures(leaf);
         try {
+            let satisfierMiniscript = leaf.expandedMiniscript;
+            // Most taproot leaves are Miniscript fragments, so `expandedMiniscript`
+            // is available (and currently matches `expandedExpression`).
+            // Descriptor-level leaf expressions (currently `sortedmulti_a`)
+            // expose only `expandedExpression`, so we derive an internal
+            // Miniscript-equivalent form here before calling `satisfyMiniscript(...)`
+            if (!satisfierMiniscript) {
+                if (!/^sortedmulti_a\(/.test(leaf.expandedExpression.trim()))
+                    throw new Error(`Error: taproot leaf does not provide a satisfier miniscript`);
+                satisfierMiniscript = compileSortedMultiAExpandedExpression({
+                    expandedExpression: leaf.expandedExpression,
+                    expansionMap: leaf.expansionMap
+                });
+            }
             const { scriptSatisfaction, nLockTime, nSequence } = (0, miniscript_1.satisfyMiniscript)({
-                expandedMiniscript: leaf.expandedMiniscript,
+                expandedMiniscript: satisfierMiniscript,
                 expansionMap: leaf.expansionMap,
                 signatures: leafSignatures,
                 preimages,
@@ -406,8 +493,8 @@ function collectTapTreePubkeys(tapTreeInfo) {
  *
  * If `tapLeaf` is provided, only that leaf is considered. If `tapLeaf` is a
  * bytes, it is treated as a tapLeafHash and must match exactly one leaf. If
- * `tapLeaf` is a string, it is treated as a miniscript leaf and must match
- * exactly one leaf (whitespace-insensitive).
+ * `tapLeaf` is a string, it is treated as a raw leaf expression and must
+ * match exactly one leaf (whitespace-insensitive).
  *
  * This function is typically called twice:
  * 1) Planning pass: call it with fake signatures (built by the caller) to

package/dist/tapTree.d.ts

@@ -4,12 +4,22 @@ export type TreeNode<TLeaf> = TLeaf | {
     right: TreeNode<TLeaf>;
 };
 export type TapLeaf = {
-    miniscript: string;
+    /** Raw leaf expression as written in tr(KEY,TREE). */
+    expression: string;
 };
 export type TapTreeNode = TreeNode<TapLeaf>;
 export type TapLeafInfo = {
-    miniscript: string;
-    expandedMiniscript: string;
+    /** Raw leaf expression as written in tr(KEY,TREE). */
+    expression: string;
+    /** Expanded descriptor-level expression for this leaf. */
+    expandedExpression: string;
+    /**
+     * Expanded miniscript form when the leaf expression is a miniscript fragment.
+     *
+     * For descriptor-level script expressions (e.g. sortedmulti_a), this can be
+     * undefined even though `tapScript` is available.
+     */
+    expandedMiniscript?: string;
     expansionMap: ExpansionMap;
     tapScript: Uint8Array;
     version: number;
@@ -58,14 +68,14 @@ export declare function collectTapTreeLeaves(tapTreeInfo: TapTreeInfoNode): Arra
  * 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 miniscript leaf (raw, not
- * expanded). Matching is whitespace-insensitive. If the miniscript appears
+ * 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 miniscript string:
+ * // tapLeaf can be undefined, bytes (tapleaf hash) or a leaf expression:
  * // f.ex.: 'pk(03bb...)'
  * ```
  */

package/dist/tapTree.js

@@ -15,7 +15,7 @@ const parseUtils_1 = require("./parseUtils");
 // with consensus max depth 128.
 exports.MAX_TAPTREE_DEPTH = 128;
 function tapTreeMaxDepth(tapTree, depth = 0) {
-    if ('miniscript' in tapTree)
+    if ('expression' in tapTree)
         return depth;
     return Math.max(tapTreeMaxDepth(tapTree.left, depth + 1), tapTreeMaxDepth(tapTree.right, depth + 1));
 }
@@ -53,7 +53,7 @@ function assertTapTreeDepth(tapTree) {
 function collectTapTreeLeaves(tapTreeInfo) {
     const leaves = [];
     const walk = (node, depth) => {
-        if ('miniscript' in node) {
+        if ('expression' in node) {
             leaves.push({ leaf: node, depth });
             return;
         }
@@ -66,8 +66,8 @@ function collectTapTreeLeaves(tapTreeInfo) {
 function computeTapLeafHash(leaf) {
     return (0, bitcoinjs_lib_internals_1.tapleafHash)({ output: leaf.tapScript, version: leaf.version });
 }
-function normalizeMiniscriptForMatch(miniscript) {
-    return miniscript.replace(/\s+/g, '');
+function normalizeExpressionForMatch(expression) {
+    return expression.replace(/\s+/g, '');
 }
 /**
  * Resolves taproot leaf candidates based on an optional selector.
@@ -75,14 +75,14 @@ function normalizeMiniscriptForMatch(miniscript) {
  * 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 miniscript leaf (raw, not
- * expanded). Matching is whitespace-insensitive. If the miniscript appears
+ * 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 miniscript string:
+ * // tapLeaf can be undefined, bytes (tapleaf hash) or a leaf expression:
  * // f.ex.: 'pk(03bb...)'
  * ```
  */
@@ -100,12 +100,12 @@ function selectTapLeafCandidates({ tapTreeInfo, tapLeaf }) {
             throw new Error(`Error: tapleaf hash not found in tapTreeInfo`);
         return [match];
     }
-    const normalizedSelector = normalizeMiniscriptForMatch(tapLeaf);
-    const matches = leaves.filter(entry => normalizeMiniscriptForMatch(entry.leaf.miniscript) === normalizedSelector);
+    const normalizedSelector = normalizeExpressionForMatch(tapLeaf);
+    const matches = leaves.filter(entry => normalizeExpressionForMatch(entry.leaf.expression) === normalizedSelector);
     if (matches.length === 0)
-        throw new Error(`Error: miniscript leaf not found in tapTreeInfo: ${tapLeaf}`);
+        throw new Error(`Error: taproot leaf expression not found in tapTreeInfo: ${tapLeaf}`);
     if (matches.length > 1)
-        throw new Error(`Error: miniscript leaf is ambiguous in tapTreeInfo: ${tapLeaf}`);
+        throw new Error(`Error: taproot leaf expression is ambiguous in tapTreeInfo: ${tapLeaf}`);
     return matches;
 }
 function tapTreeError(expression) {
@@ -124,13 +124,17 @@ function splitTapTreeExpression(expression) {
 }
 /**
  * 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)` => { miniscript: 'pk(@0)' }
- * - `{pk(@0),pk(@1)}` => { left: { miniscript: 'pk(@0)' }, right: { miniscript: 'pk(@1)' } }
+ * - `pk(@0)` => { expression: 'pk(@0)' }
+ * - `{pk(@0),pk(@1)}` => { left: { expression: 'pk(@0)' }, right: { expression: 'pk(@1)' } }
  * - `{pk(@0),{pk(@1),pk(@2)}}` =>
  *   {
- *     left: { miniscript: 'pk(@0)' },
- *     right: { left: { miniscript: 'pk(@1)' }, right: { miniscript: 'pk(@2)' } }
+ *     left: { expression: 'pk(@0)' },
+ *     right: { left: { expression: 'pk(@1)' }, right: { expression: 'pk(@2)' } }
  *   }
  */
 function parseTapTreeNode(expression) {
@@ -151,7 +155,7 @@ function parseTapTreeNode(expression) {
     }
     if (trimmedExpression.includes('{') || trimmedExpression.includes('}'))
         throw tapTreeError(expression);
-    return { miniscript: trimmedExpression };
+    return { expression: trimmedExpression };
 }
 function parseTapTreeExpression(expression) {
     const trimmed = expression.trim();

package/dist/types.d.ts

@@ -138,10 +138,10 @@ export type Expansion = {
      * Example:
      * ```
      * {
-     *   left: { miniscript: 'pk(02aa...)' },
+     *   left: { expression: 'pk(02aa...)' },
      *   right: {
-     *     left: { miniscript: 'pk(03bb...)' },
-     *     right: { miniscript: 'pk(02cc...)' }
+     *     left: { expression: 'pk(03bb...)' },
+     *     right: { expression: 'pk(02cc...)' }
      *   }
      * }
      * ```
@@ -149,16 +149,22 @@ export type Expansion = {
     tapTree?: TapTreeNode;
     /**
      * The compiled taproot tree metadata, if any. Only defined for `tr(KEY, TREE)`.
-     * Same as tapTree, but each leaf includes the expanded miniscript, key
-     * expansion map, compiled tapscript (`tapScript`), and leaf version.
-     * Note: `@i` placeholders in `expandedMiniscript` are scoped per leaf, since
-     * each leaf is expanded and satisfied independently.
+     * 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: {
-     *     miniscript: 'pk(02aa...)',
+     *     expression: 'pk(02aa...)',
+     *     expandedExpression: 'pk(@0)',
      *     expandedMiniscript: 'pk(@0)',
      *     expansionMap: ExpansionMap;
      *     tapScript: Uint8Array;

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

package/dist/stackResourceLimits.d.ts

@@ -1,17 +0,0 @@
-export declare const MAX_STACK_SIZE = 1000;
-export declare const MAX_SCRIPT_ELEMENT_SIZE = 520;
-export declare function assertConsensusStackResourceLimits({ stackItems, stackLabel, stackItemLabel }: {
-    stackItems: Uint8Array[];
-    stackLabel?: string;
-    stackItemLabel?: string;
-}): void;
-export declare function assertStandardPolicyStackItemCountLimit({ stackItems, maxStackItems, stackLabel }: {
-    stackItems: Uint8Array[];
-    maxStackItems: number;
-    stackLabel: string;
-}): void;
-export declare function assertStandardPolicyStackItemSizeLimit({ stackItems, maxStackItemSize, stackItemLabel }: {
-    stackItems: Uint8Array[];
-    maxStackItemSize: number;
-    stackItemLabel: string;
-}): void;

package/dist/stackResourceLimits.js

@@ -1,35 +0,0 @@
-"use strict";
-// Copyright (c) 2026 Jose-Luis Landabaso
-// Distributed under the MIT software license
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_SCRIPT_ELEMENT_SIZE = exports.MAX_STACK_SIZE = void 0;
-exports.assertConsensusStackResourceLimits = assertConsensusStackResourceLimits;
-exports.assertStandardPolicyStackItemCountLimit = assertStandardPolicyStackItemCountLimit;
-exports.assertStandardPolicyStackItemSizeLimit = assertStandardPolicyStackItemSizeLimit;
-// See Sipa's Miniscript "Resource limitations":
-// https://bitcoin.sipa.be/miniscript/
-// and Bitcoin Core policy/consensus constants.
-// Consensus: max number of elements in initial stack (and stack+altstack after
-// each opcode execution).
-exports.MAX_STACK_SIZE = 1000;
-// Consensus: max size for any pushed stack element. This is an element limit,
-// not a full script-size limit.
-exports.MAX_SCRIPT_ELEMENT_SIZE = 520;
-function assertConsensusStackResourceLimits({ stackItems, stackLabel = 'stack', stackItemLabel = 'stack item' }) {
-    if (stackItems.length > exports.MAX_STACK_SIZE)
-        throw new Error(`Error: ${stackLabel} has too many items, ${stackItems.length} is larger than ${exports.MAX_STACK_SIZE}`);
-    for (const stackItem of stackItems) {
-        if (stackItem.length > exports.MAX_SCRIPT_ELEMENT_SIZE)
-            throw new Error(`Error: ${stackItemLabel} is too large, ${stackItem.length} bytes is larger than ${exports.MAX_SCRIPT_ELEMENT_SIZE} bytes`);
-    }
-}
-function assertStandardPolicyStackItemCountLimit({ stackItems, maxStackItems, stackLabel }) {
-    if (stackItems.length > maxStackItems)
-        throw new Error(`Error: ${stackLabel} has too many items, ${stackItems.length} is larger than ${maxStackItems}`);
-}
-function assertStandardPolicyStackItemSizeLimit({ stackItems, maxStackItemSize, stackItemLabel }) {
-    for (const stackItem of stackItems) {
-        if (stackItem.length > maxStackItemSize)
-            throw new Error(`Error: ${stackItemLabel} exceeds standard policy, ${stackItem.length} bytes is larger than ${maxStackItemSize} bytes`);
-    }
-}