@bitcoinerlab/descriptors 0.3.0 → 0.3.1

package/README.md

@@ -79,8 +79,8 @@ constructor({
               // to denote an arbitrary index.
   index,      // The descriptor's index in the case of a range descriptor
               // (must be an integer >= 0).
-  checksumRequired = false, // Flag indicating if the descriptor is required
-                            // to include a checksum.
+  checksumRequired = false // Optional flag indicating if the descriptor is
+                           // required to include a checksum. Defaults to false.
   allowMiniscriptInP2SH = false, // Flag indicating if this instance can parse
                                  // and generate script satisfactions for
                                  // sh(miniscript) top-level expressions of
@@ -142,7 +142,15 @@ const result = expand({
   network: networks.testnet, // One of bitcoinjs-lib `networks`
                              // (https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/src/networks.js)
                              // or another one with the same interface.
-  allowMiniscriptInP2SH: true // Optional flag to allow miniscript in P2SH
+                             // Optional (defaults to bitcoin mainnet). 
+  allowMiniscriptInP2SH: true, // Optional flag to allow miniscript in P2SH.
+                              // Defaults to false.
+  index, // Optional. The descriptor's index in the case of a range descriptor
+         // (must be an integer >= 0). If not set for ranged descriptors, then 
+         // the function will return an expansionMap with ranged keyPaths and
+         // won't compute Payment or scripts.
+  checksumRequired = false // Optional flag indicating if the descriptor is
+                           // required to include a checksum. Defaults to false.
 });
 ```
 
@@ -156,6 +164,8 @@ The `expand()` function returns an object with the following properties:
 - `expandedMiniscript: string | undefined`: The expanded miniscript, if any.
 - `redeemScript: Buffer | undefined`: The redeem script for the descriptor, if applicable.
 - `witnessScript: Buffer | undefined`: The witness script for the descriptor, if applicable.
+- `isRanged: boolean` : Whether the expression represents a ranged descriptor.
+- `canonicalExpression` : This is the preferred or authoritative representation of the descriptor expression. It standardizes the descriptor by replacing indexes on wildcards and eliminating checksums.
 
 For the example expression provided, the `expandedExpression` and a portion of the `expansionMap` would be as follows:
 

package/dist/descriptors.js

@@ -55,7 +55,7 @@ function countNonPushOnlyOPs(script) {
     const decompile = bitcoinjs_lib_1.script.decompile(script);
     if (!decompile)
         throw new Error(`Error: cound not decompile ${script}`);
-    return decompile.filter(op => op > bitcoinjs_lib_1.script.OPS['OP_16']).length;
+    return decompile.filter(op => typeof op === 'number' && op > bitcoinjs_lib_1.script.OPS['OP_16']).length;
 }
 /*
  * Returns a bare descriptor without checksum and particularized for a certain
@@ -75,20 +75,20 @@ function evaluate({ expression, checksumRequired, index }) {
             throw new Error(`Error: invalid descriptor checksum for ${expression}`);
         }
     }
-    const mWildcard = evaluatedExpression.match(/\*/g);
-    if (mWildcard && mWildcard.length > 0) {
-        if (index === undefined)
-            throw new Error(`Error: index was not provided for ranged descriptor`);
-        if (!Number.isInteger(index) || index < 0)
-            throw new Error(`Error: invalid index ${index}`);
-        //From  https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md
-        //To prevent a combinatorial explosion of the search space, if more than
-        //one of the multi() key arguments is a BIP32 wildcard path ending in /* or
-        //*', the multi() expression only matches multisig scripts with the ith
-        //child key from each wildcard path in lockstep, rather than scripts with
-        //any combination of child keys from each wildcard path.
-        //We extend this reasoning for musig for all cases
-        evaluatedExpression = evaluatedExpression.replaceAll('*', index.toString());
+    if (index !== undefined) {
+        const mWildcard = evaluatedExpression.match(/\*/g);
+        if (mWildcard && mWildcard.length > 0) {
+            //From  https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md
+            //To prevent a combinatorial explosion of the search space, if more than
+            //one of the multi() key arguments is a BIP32 wildcard path ending in /* or
+            //*', the multi() expression only matches multisig scripts with the ith
+            //child key from each wildcard path in lockstep, rather than scripts with
+            //any combination of child keys from each wildcard path.
+            //We extend this reasoning for musig for all cases
+            evaluatedExpression = evaluatedExpression.replaceAll('*', index.toString());
+        }
+        else
+            throw new Error(`Error: index passed for non-ranged descriptor: ${expression}`);
     }
     return evaluatedExpression;
 }
@@ -132,13 +132,15 @@ function DescriptorsFactory(ecc) {
      *     - expandedMiniscript: The expanded miniscript, if any.
      *     - redeemScript: The redeem script for the descriptor, if applicable.
      *     - witnessScript: The witness script for the descriptor, if applicable.
+     *     - isRanged: Whether this expression representas a ranged-descriptor
+     *     - canonicalExpression: This is the preferred or authoritative
+     *     representation of the descriptor expression. It standardizes the
+     *     descriptor by replacing indexes on wildcards and eliminating checksums.
+     *     This helps ensure consistency and facilitates efficient interpretation and handling by systems or software.
      *
      * @throws {Error} Throws an error if the descriptor cannot be parsed or does not conform to the expected format.
      */
-    const expand = ({ expression, loggedExpression, //this is the expression that will be used for logging error messages
-    network = bitcoinjs_lib_1.networks.bitcoin, allowMiniscriptInP2SH = false }) => {
-        //remove the checksum before proceeding:
-        expression = expression.replace(new RegExp(RE.reChecksum + '$'), '');
+    const expand = ({ expression, index, checksumRequired = false, network = bitcoinjs_lib_1.networks.bitcoin, allowMiniscriptInP2SH = false }) => {
         let expandedExpression;
         let miniscript;
         let expansionMap;
@@ -148,15 +150,24 @@ function DescriptorsFactory(ecc) {
         let witnessScript;
         let redeemScript;
         const isRanged = expression.indexOf('*') !== -1;
-        if (!loggedExpression)
-            loggedExpression = expression;
+        if (index !== undefined)
+            if (!Number.isInteger(index) || index < 0)
+                throw new Error(`Error: invalid index ${index}`);
+        //Verify and remove checksum (if exists) and
+        //particularize range descriptor for index (if desc is range descriptor)
+        const canonicalExpression = evaluate({
+            expression,
+            ...(index !== undefined ? { index } : {}),
+            checksumRequired
+        });
+        const isCanonicalRanged = canonicalExpression.indexOf('*') !== -1;
         //addr(ADDR)
-        if (expression.match(RE.reAddrAnchored)) {
+        if (canonicalExpression.match(RE.reAddrAnchored)) {
             if (isRanged)
                 throw new Error(`Error: addr() cannot be ranged`);
-            const matchedAddress = expression.match(RE.reAddrAnchored)?.[1]; //[1]-> whatever is found addr(->HERE<-)
+            const matchedAddress = canonicalExpression.match(RE.reAddrAnchored)?.[1]; //[1]-> whatever is found addr(->HERE<-)
             if (!matchedAddress)
-                throw new Error(`Error: could not get an address in ${loggedExpression}`);
+                throw new Error(`Error: could not get an address in ${expression}`);
             let output;
             try {
                 output = bitcoinjs_lib_1.address.toOutputScript(matchedAddress, network);
@@ -189,98 +200,94 @@ function DescriptorsFactory(ecc) {
             }
         }
         //pk(KEY)
-        else if (expression.match(RE.rePkAnchored)) {
+        else if (canonicalExpression.match(RE.rePkAnchored)) {
             isSegwit = false;
-            const keyExpression = expression.match(RE.reKeyExp)?.[0];
+            const keyExpression = canonicalExpression.match(RE.reKeyExp)?.[0];
             if (!keyExpression)
                 throw new Error(`Error: keyExpression could not me extracted`);
-            if (expression !== `pk(${keyExpression})`)
-                throw new Error(`Error: invalid expression ${loggedExpression}`);
+            if (canonicalExpression !== `pk(${keyExpression})`)
+                throw new Error(`Error: invalid expression ${expression}`);
             expandedExpression = 'pk(@0)';
-            expansionMap = {
-                '@0': parseKeyExpression({ keyExpression, network, isSegwit })
-            };
-            if (!isRanged) {
-                const pubkey = expansionMap['@0'].pubkey;
+            const pKE = parseKeyExpression({ keyExpression, network, isSegwit });
+            expansionMap = { '@0': pKE };
+            if (!isCanonicalRanged) {
+                const pubkey = pKE.pubkey;
                 //Note there exists no address for p2pk, but we can still use the script
                 if (!pubkey)
-                    throw new Error(`Error: could not extract a pubkey from ${loggedExpression}`);
+                    throw new Error(`Error: could not extract a pubkey from ${expression}`);
                 payment = p2pk({ pubkey, network });
             }
         }
         //pkh(KEY) - legacy
-        else if (expression.match(RE.rePkhAnchored)) {
+        else if (canonicalExpression.match(RE.rePkhAnchored)) {
             isSegwit = false;
-            const keyExpression = expression.match(RE.reKeyExp)?.[0];
+            const keyExpression = canonicalExpression.match(RE.reKeyExp)?.[0];
             if (!keyExpression)
                 throw new Error(`Error: keyExpression could not me extracted`);
-            if (expression !== `pkh(${keyExpression})`)
-                throw new Error(`Error: invalid expression ${loggedExpression}`);
+            if (canonicalExpression !== `pkh(${keyExpression})`)
+                throw new Error(`Error: invalid expression ${expression}`);
             expandedExpression = 'pkh(@0)';
-            expansionMap = {
-                '@0': parseKeyExpression({ keyExpression, network, isSegwit })
-            };
-            if (!isRanged) {
-                const pubkey = expansionMap['@0'].pubkey;
+            const pKE = parseKeyExpression({ keyExpression, network, isSegwit });
+            expansionMap = { '@0': pKE };
+            if (!isCanonicalRanged) {
+                const pubkey = pKE.pubkey;
                 if (!pubkey)
-                    throw new Error(`Error: could not extract a pubkey from ${loggedExpression}`);
+                    throw new Error(`Error: could not extract a pubkey from ${expression}`);
                 payment = p2pkh({ pubkey, network });
             }
         }
         //sh(wpkh(KEY)) - nested segwit
-        else if (expression.match(RE.reShWpkhAnchored)) {
+        else if (canonicalExpression.match(RE.reShWpkhAnchored)) {
             isSegwit = true;
-            const keyExpression = expression.match(RE.reKeyExp)?.[0];
+            const keyExpression = canonicalExpression.match(RE.reKeyExp)?.[0];
             if (!keyExpression)
                 throw new Error(`Error: keyExpression could not me extracted`);
-            if (expression !== `sh(wpkh(${keyExpression}))`)
-                throw new Error(`Error: invalid expression ${loggedExpression}`);
+            if (canonicalExpression !== `sh(wpkh(${keyExpression}))`)
+                throw new Error(`Error: invalid expression ${expression}`);
             expandedExpression = 'sh(wpkh(@0))';
-            expansionMap = {
-                '@0': parseKeyExpression({ keyExpression, network, isSegwit })
-            };
-            if (!isRanged) {
-                const pubkey = expansionMap['@0'].pubkey;
+            const pKE = parseKeyExpression({ keyExpression, network, isSegwit });
+            expansionMap = { '@0': pKE };
+            if (!isCanonicalRanged) {
+                const pubkey = pKE.pubkey;
                 if (!pubkey)
-                    throw new Error(`Error: could not extract a pubkey from ${loggedExpression}`);
+                    throw new Error(`Error: could not extract a pubkey from ${expression}`);
                 payment = p2sh({ redeem: p2wpkh({ pubkey, network }), network });
                 redeemScript = payment.redeem?.output;
                 if (!redeemScript)
-                    throw new Error(`Error: could not calculate redeemScript for ${loggedExpression}`);
+                    throw new Error(`Error: could not calculate redeemScript for ${expression}`);
             }
         }
         //wpkh(KEY) - native segwit
-        else if (expression.match(RE.reWpkhAnchored)) {
+        else if (canonicalExpression.match(RE.reWpkhAnchored)) {
             isSegwit = true;
-            const keyExpression = expression.match(RE.reKeyExp)?.[0];
+            const keyExpression = canonicalExpression.match(RE.reKeyExp)?.[0];
             if (!keyExpression)
                 throw new Error(`Error: keyExpression could not me extracted`);
-            if (expression !== `wpkh(${keyExpression})`)
-                throw new Error(`Error: invalid expression ${loggedExpression}`);
+            if (canonicalExpression !== `wpkh(${keyExpression})`)
+                throw new Error(`Error: invalid expression ${expression}`);
             expandedExpression = 'wpkh(@0)';
-            expansionMap = {
-                '@0': parseKeyExpression({ keyExpression, network, isSegwit })
-            };
-            if (!isRanged) {
-                const pubkey = expansionMap['@0'].pubkey;
+            const pKE = parseKeyExpression({ keyExpression, network, isSegwit });
+            expansionMap = { '@0': pKE };
+            if (!isCanonicalRanged) {
+                const pubkey = pKE.pubkey;
                 if (!pubkey)
-                    throw new Error(`Error: could not extract a pubkey from ${loggedExpression}`);
+                    throw new Error(`Error: could not extract a pubkey from ${expression}`);
                 payment = p2wpkh({ pubkey, network });
             }
         }
         //sh(wsh(miniscript))
-        else if (expression.match(RE.reShWshMiniscriptAnchored)) {
+        else if (canonicalExpression.match(RE.reShWshMiniscriptAnchored)) {
             isSegwit = true;
-            miniscript = expression.match(RE.reShWshMiniscriptAnchored)?.[1]; //[1]-> whatever is found sh(wsh(->HERE<-))
+            miniscript = canonicalExpression.match(RE.reShWshMiniscriptAnchored)?.[1]; //[1]-> whatever is found sh(wsh(->HERE<-))
             if (!miniscript)
-                throw new Error(`Error: could not get miniscript in ${loggedExpression}`);
+                throw new Error(`Error: could not get miniscript in ${expression}`);
             ({ expandedMiniscript, expansionMap } = expandMiniscript({
                 miniscript,
                 isSegwit,
                 network
             }));
             expandedExpression = `sh(wsh(${expandedMiniscript}))`;
-            if (!isRanged) {
+            if (!isCanonicalRanged) {
                 const script = (0, miniscript_1.miniscript2Script)({ expandedMiniscript, expansionMap });
                 witnessScript = script;
                 if (script.byteLength > MAX_STANDARD_P2WSH_SCRIPT_SIZE) {
@@ -296,17 +303,17 @@ function DescriptorsFactory(ecc) {
                 });
                 redeemScript = payment.redeem?.output;
                 if (!redeemScript)
-                    throw new Error(`Error: could not calculate redeemScript for ${loggedExpression}`);
+                    throw new Error(`Error: could not calculate redeemScript for ${expression}`);
             }
         }
         //sh(miniscript)
-        else if (expression.match(RE.reShMiniscriptAnchored)) {
+        else if (canonicalExpression.match(RE.reShMiniscriptAnchored)) {
             //isSegwit false because we know it's a P2SH of a miniscript and not a
             //P2SH that embeds a witness payment.
             isSegwit = false;
-            miniscript = expression.match(RE.reShMiniscriptAnchored)?.[1]; //[1]-> whatever is found sh(->HERE<-)
+            miniscript = canonicalExpression.match(RE.reShMiniscriptAnchored)?.[1]; //[1]-> whatever is found sh(->HERE<-)
             if (!miniscript)
-                throw new Error(`Error: could not get miniscript in ${loggedExpression}`);
+                throw new Error(`Error: could not get miniscript in ${expression}`);
             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
@@ -320,7 +327,7 @@ function DescriptorsFactory(ecc) {
                 network
             }));
             expandedExpression = `sh(${expandedMiniscript})`;
-            if (!isRanged) {
+            if (!isCanonicalRanged) {
                 const script = (0, miniscript_1.miniscript2Script)({ expandedMiniscript, expansionMap });
                 redeemScript = script;
                 if (script.byteLength > MAX_SCRIPT_ELEMENT_SIZE) {
@@ -334,18 +341,18 @@ function DescriptorsFactory(ecc) {
             }
         }
         //wsh(miniscript)
-        else if (expression.match(RE.reWshMiniscriptAnchored)) {
+        else if (canonicalExpression.match(RE.reWshMiniscriptAnchored)) {
             isSegwit = true;
-            miniscript = expression.match(RE.reWshMiniscriptAnchored)?.[1]; //[1]-> whatever is found wsh(->HERE<-)
+            miniscript = canonicalExpression.match(RE.reWshMiniscriptAnchored)?.[1]; //[1]-> whatever is found wsh(->HERE<-)
             if (!miniscript)
-                throw new Error(`Error: could not get miniscript in ${loggedExpression}`);
+                throw new Error(`Error: could not get miniscript in ${expression}`);
             ({ expandedMiniscript, expansionMap } = expandMiniscript({
                 miniscript,
                 isSegwit,
                 network
             }));
             expandedExpression = `wsh(${expandedMiniscript})`;
-            if (!isRanged) {
+            if (!isCanonicalRanged) {
                 const script = (0, miniscript_1.miniscript2Script)({ expandedMiniscript, expansionMap });
                 witnessScript = script;
                 if (script.byteLength > MAX_STANDARD_P2WSH_SCRIPT_SIZE) {
@@ -359,7 +366,7 @@ function DescriptorsFactory(ecc) {
             }
         }
         else {
-            throw new Error(`Error: Could not parse descriptor ${loggedExpression}`);
+            throw new Error(`Error: Could not parse descriptor ${expression}`);
         }
         return {
             ...(payment !== undefined ? { payment } : {}),
@@ -369,7 +376,9 @@ function DescriptorsFactory(ecc) {
             ...(isSegwit !== undefined ? { isSegwit } : {}),
             ...(expandedMiniscript !== undefined ? { expandedMiniscript } : {}),
             ...(redeemScript !== undefined ? { redeemScript } : {}),
-            ...(witnessScript !== undefined ? { witnessScript } : {})
+            ...(witnessScript !== undefined ? { witnessScript } : {}),
+            isRanged,
+            canonicalExpression
         };
     };
     /**
@@ -420,19 +429,15 @@ function DescriptorsFactory(ecc) {
             __classPrivateFieldSet(this, _Descriptor_preimages, preimages, "f");
             if (typeof expression !== 'string')
                 throw new Error(`Error: invalid descriptor type`);
-            //Verify and remove checksum (if exists) and
-            //particularize range descriptor for index (if desc is range descriptor)
-            const evaluatedExpression = evaluate({
+            const expandedResult = expand({
                 expression,
                 ...(index !== undefined ? { index } : {}),
-                checksumRequired
-            });
-            const expandedResult = expand({
-                expression: evaluatedExpression,
-                loggedExpression: expression,
+                checksumRequired,
                 network,
                 allowMiniscriptInP2SH
             });
+            if (expandedResult.isRanged && index === undefined)
+                throw new Error(`Error: index was not provided for ranged descriptor`);
             if (!expandedResult.payment)
                 throw new Error(`Error: could not extract a payment from ${expression}`);
             __classPrivateFieldSet(this, _Descriptor_payment, expandedResult.payment, "f");
@@ -464,7 +469,7 @@ function DescriptorsFactory(ecc) {
                 }
                 else {
                     //We should only miss expansionMap in addr() expressions:
-                    if (!evaluatedExpression.match(RE.reAddrAnchored)) {
+                    if (!expandedResult.canonicalExpression.match(RE.reAddrAnchored)) {
                         throw new Error(`Error: expansionMap not available for expression ${expression} that is not an address`);
                     }
                     __classPrivateFieldSet(this, _Descriptor_signersPubKeys, [this.getScriptPubKey()], "f");

package/dist/types.d.ts

@@ -47,7 +47,8 @@ export interface ParseKeyExpression {
 export interface Expand {
     (params: {
         expression: string;
-        loggedExpression?: string;
+        index?: number;
+        checksumRequired?: boolean;
         network?: Network;
         allowMiniscriptInP2SH?: boolean;
     }): {
@@ -59,6 +60,8 @@ export interface Expand {
         expandedMiniscript?: string;
         redeemScript?: Buffer;
         witnessScript?: Buffer;
+        isRanged: boolean;
+        canonicalExpression: string;
     };
 }
 interface XOnlyPointAddTweakResult {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bitcoinerlab/descriptors",
   "homepage": "https://github.com/bitcoinerlab/descriptors",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -64,8 +64,8 @@
   "devDependencies": {
     "@babel/plugin-transform-modules-commonjs": "^7.20.11",
     "@ledgerhq/hw-transport-node-hid": "^6.27.12",
-    "@typescript-eslint/eslint-plugin": "^5.53.0",
-    "@typescript-eslint/parser": "^5.53.0",
+    "@typescript-eslint/eslint-plugin": "^5.60.1",
+    "@typescript-eslint/parser": "^5.60.1",
     "babel-plugin-transform-import-meta": "^2.2.0",
     "better-docs": "^2.7.2",
     "bip39": "^3.0.4",
@@ -80,6 +80,7 @@
     "path": "^0.12.7",
     "prettier": "^2.8.8",
     "regtest-client": "^0.2.0",
-    "ts-node-dev": "^2.0.0"
+    "ts-node-dev": "^2.0.0",
+    "typescript": "5.0"
   }
 }