Improve comments and code clarity

Author: reardencode

src/payments/p2tr.js

@@ -163,7 +163,7 @@ function p2tr(a, opts) {
         [
           buffer_1.Buffer.from([o.redeemVersion | outputKey.parity]),
           a.internalPubkey,
-        ].concat(path.reverse()),
+        ].concat(path),
       );
       return [a.redeem.output, controlBock];
     }

src/payments/taprootutils.d.ts

@@ -10,21 +10,25 @@ interface HashBranch {
     left: HashTree;
     right: HashTree;
 }
+/**
+ * Binary tree representing leaf, branch, and root node hashes of a Taptree.
+ * Each node contains a hash, and potentially left and right branch hashes.
+ * This tree is used for 2 purposes: Providing the root hash for tweaking,
+ * and calculating merkle inclusion proofs when constructing a control block.
+ */
 export declare type HashTree = HashLeaf | HashBranch;
 /**
- * Build the hash tree from the scripts binary tree.
- * The binary tree can be balanced or not.
- * @param scriptTree - is a list representing a binary tree where an element can be:
- *  - a taproot leaf [(output, version)], or
- *  - a pair of two taproot leafs [(output, version), (output, version)], or
- *  - one taproot leaf and a list of elements
+ * Build a hash tree of merkle nodes from the scripts binary tree.
+ * @param scriptTree - the tree of scripts to pairwise hash.
  */
 export declare function toHashTree(scriptTree: Taptree): HashTree;
 /**
- * Given a MAST tree, it finds the path of a particular hash.
+ * Given a HashTree, finds the path from a particular hash to the root.
  * @param node - the root of the tree
  * @param hash - the hash to search for
- * @returns - and array of hashes representing the path, undefined if no path is found
+ * @returns - array of sibling hashes, from leaf (inclusive) to root
+ * (exclusive) needed to prove inclusion of the specified hash. undefined if no
+ * path is found
  */
 export declare function findScriptPath(node: HashTree, hash: Buffer): Buffer[] | undefined;
 export declare function tapleafHash(leaf: Tapleaf): Buffer;

src/payments/taprootutils.js

@@ -22,12 +22,8 @@ function rootHashFromPath(controlBlock, leafHash) {
 exports.rootHashFromPath = rootHashFromPath;
 const isHashBranch = ht => 'left' in ht && 'right' in ht;
 /**
- * Build the hash tree from the scripts binary tree.
- * The binary tree can be balanced or not.
- * @param scriptTree - is a list representing a binary tree where an element can be:
- *  - a taproot leaf [(output, version)], or
- *  - a pair of two taproot leafs [(output, version), (output, version)], or
- *  - one taproot leaf and a list of elements
+ * Build a hash tree of merkle nodes from the scripts binary tree.
+ * @param scriptTree - the tree of scripts to pairwise hash.
  */
 function toHashTree(scriptTree) {
   if ((0, types_1.isTapleaf)(scriptTree))
@@ -43,23 +39,22 @@ function toHashTree(scriptTree) {
 }
 exports.toHashTree = toHashTree;
 /**
- * Given a MAST tree, it finds the path of a particular hash.
+ * Given a HashTree, finds the path from a particular hash to the root.
  * @param node - the root of the tree
  * @param hash - the hash to search for
- * @returns - and array of hashes representing the path, undefined if no path is found
+ * @returns - array of sibling hashes, from leaf (inclusive) to root
+ * (exclusive) needed to prove inclusion of the specified hash. undefined if no
+ * path is found
  */
 function findScriptPath(node, hash) {
-  if (!isHashBranch(node)) {
-    if (node.hash.equals(hash)) {
-      return [];
-    } else {
-      return undefined;
-    }
+  if (isHashBranch(node)) {
+    const leftPath = findScriptPath(node.left, hash);
+    if (leftPath !== undefined) return [...leftPath, node.right.hash];
+    const rightPath = findScriptPath(node.right, hash);
+    if (rightPath !== undefined) return [...rightPath, node.left.hash];
+  } else if (node.hash.equals(hash)) {
+    return [];
   }
-  const leftPath = findScriptPath(node.left, hash);
-  if (leftPath !== undefined) return [node.right.hash, ...leftPath];
-  const rightPath = findScriptPath(node.right, hash);
-  if (rightPath !== undefined) return [node.left.hash, ...rightPath];
   return undefined;
 }
 exports.findScriptPath = findScriptPath;

src/types.d.ts

@@ -20,6 +20,11 @@ export interface Tapleaf {
 }
 export declare const TAPLEAF_VERSION_MASK = 254;
 export declare function isTapleaf(o: any): o is Tapleaf;
+/**
+ * Binary tree repsenting script path spends for a Taproot input.
+ * Each node is either a single Tapleaf, or a pair of Tapleaf | Taptree.
+ * The tree has no balancing requirements.
+ */
 export declare type Taptree = [Taptree | Tapleaf, Taptree | Tapleaf] | Tapleaf;
 export declare function isTaptree(scriptTree: any): scriptTree is Taptree;
 export interface TinySecp256k1Interface {

ts_src/payments/p2tr.ts

@@ -181,7 +181,7 @@ export function p2tr(a: Payment, opts?: PaymentOpts): Payment {
         [
           NBuffer.from([o.redeemVersion! | outputKey.parity]),
           a.internalPubkey,
-        ].concat(path.reverse()),
+        ].concat(path),
       );
       return [a.redeem.output, controlBock];
     }

ts_src/payments/taprootutils.ts

@@ -38,15 +38,17 @@ interface HashBranch {
 const isHashBranch = (ht: HashTree): ht is HashBranch =>
   'left' in ht && 'right' in ht;
 
+/**
+ * Binary tree representing leaf, branch, and root node hashes of a Taptree.
+ * Each node contains a hash, and potentially left and right branch hashes.
+ * This tree is used for 2 purposes: Providing the root hash for tweaking,
+ * and calculating merkle inclusion proofs when constructing a control block.
+ */
 export type HashTree = HashLeaf | HashBranch;
 
 /**
- * Build the hash tree from the scripts binary tree.
- * The binary tree can be balanced or not.
- * @param scriptTree - is a list representing a binary tree where an element can be:
- *  - a taproot leaf [(output, version)], or
- *  - a pair of two taproot leafs [(output, version), (output, version)], or
- *  - one taproot leaf and a list of elements
+ * Build a hash tree of merkle nodes from the scripts binary tree.
+ * @param scriptTree - the tree of scripts to pairwise hash.
  */
 export function toHashTree(scriptTree: Taptree): HashTree {
   if (isTapleaf(scriptTree)) return { hash: tapleafHash(scriptTree) };
@@ -63,29 +65,27 @@ export function toHashTree(scriptTree: Taptree): HashTree {
 }
 
 /**
- * Given a MAST tree, it finds the path of a particular hash.
+ * Given a HashTree, finds the path from a particular hash to the root.
  * @param node - the root of the tree
  * @param hash - the hash to search for
- * @returns - and array of hashes representing the path, undefined if no path is found
+ * @returns - array of sibling hashes, from leaf (inclusive) to root
+ * (exclusive) needed to prove inclusion of the specified hash. undefined if no
+ * path is found
  */
 export function findScriptPath(
   node: HashTree,
   hash: Buffer,
 ): Buffer[] | undefined {
-  if (!isHashBranch(node)) {
-    if (node.hash.equals(hash)) {
-      return [];
-    } else {
-      return undefined;
-    }
+  if (isHashBranch(node)) {
+    const leftPath = findScriptPath(node.left, hash);
+    if (leftPath !== undefined) return [...leftPath, node.right.hash];
+
+    const rightPath = findScriptPath(node.right, hash);
+    if (rightPath !== undefined) return [...rightPath, node.left.hash];
+  } else if (node.hash.equals(hash)) {
+    return [];
   }
 
-  const leftPath = findScriptPath(node.left, hash);
-  if (leftPath !== undefined) return [node.right.hash, ...leftPath];
-
-  const rightPath = findScriptPath(node.right, hash);
-  if (rightPath !== undefined) return [node.left.hash, ...rightPath];
-
   return undefined;
 }
 

ts_src/types.ts

@@ -86,6 +86,11 @@ export function isTapleaf(o: any): o is Tapleaf {
   return true;
 }
 
+/**
+ * Binary tree repsenting script path spends for a Taproot input.
+ * Each node is either a single Tapleaf, or a pair of Tapleaf | Taptree.
+ * The tree has no balancing requirements.
+ */
 export type Taptree = [Taptree | Tapleaf, Taptree | Tapleaf] | Tapleaf;
 
 export function isTaptree(scriptTree: any): scriptTree is Taptree {