Improve comments in taproot signing logic

Author: sipa

src/key.h

@@ -133,10 +133,15 @@ class CKey
      * optionally tweaked by *merkle_root. Additional nonce entropy can be provided through
      * aux.
      *
-     * When merkle_root is not nullptr, this results in a signature with a modified key as
-     * specified in BIP341:
-     * - If merkle_root->IsNull(): key + H_TapTweak(pubkey)*G
-     * - Otherwise:                key + H_TapTweak(pubkey || *merkle_root)
+     * merkle_root is used to optionally perform tweaking of the private key, as specified
+     * in BIP341:
+     * - If merkle_root == nullptr: no tweaking is done, sign with key directly (this is
+     *                              used for signatures in BIP342 script).
+     * - If merkle_root->IsNull():  sign with key + H_TapTweak(pubkey) (this is used for
+     *                              key path spending when no scripts are present).
+     * - Otherwise:                 sign with key + H_TapTweak(pubkey || *merkle_root)
+     *                              (this is used for key path spending, with specific
+     *                              Merkle root of the script tree).
      */
     bool SignSchnorr(const uint256& hash, Span<unsigned char> sig, const uint256* merkle_root = nullptr, const uint256* aux = nullptr) const;
 

src/script/interpreter.h

@@ -170,6 +170,13 @@ struct PrecomputedTransactionData
 
     PrecomputedTransactionData() = default;
 
+    /** Initialize this PrecomputedTransactionData with transaction data.
+     *
+     * @param[in]   tx             The transaction for which data is being precomputed.
+     * @param[in]   spent_outputs  The CTxOuts being spent, one for each tx.vin, in order.
+     * @param[in]   force          Whether to precompute data for all optional features,
+     *                             regardless of what is in the inputs (used at signing
+     *                             time, when the inputs aren't filled in yet). */
     template <class T>
     void Init(const T& tx, std::vector<CTxOut>&& spent_outputs, bool force = false);
 

src/script/sign.cpp

@@ -61,7 +61,7 @@ bool MutableTransactionSignatureCreator::CreateSchnorrSig(const SigningProvider&
 
     CKey key;
     {
-        // For now, use the old full pubkey-based key derivation logic. As it indexed by
+        // For now, use the old full pubkey-based key derivation logic. As it is indexed by
         // Hash160(full pubkey), we need to try both a version prefixed with 0x02, and one
         // with 0x03.
         unsigned char b[33] = {0x02};

src/script/standard.h

@@ -227,8 +227,11 @@ struct TaprootSpendData
     /** The Merkle root of the script tree (0 if no scripts). */
     uint256 merkle_root;
     /** Map from (script, leaf_version) to (sets of) control blocks.
-     *  The control blocks are sorted by size, so that the signing logic can
-     *  easily prefer the cheapest one. */
+     *  More than one control block for a given script is only possible if it
+     *  appears in multiple branches of the tree. We keep them all so that
+     *  inference can reconstruct the full tree. Within each set, the control
+     *  blocks are sorted by size, so that the signing logic can easily
+     *  prefer the cheapest one. */
     std::map<std::pair<CScript, int>, std::set<std::vector<unsigned char>, ShortestVectorFirstComparator>> scripts;
     /** Merge other TaprootSpendData (for the same scriptPubKey) into this. */
     void Merge(TaprootSpendData other);
@@ -252,7 +255,7 @@ class TaprootBuilder
         /** Merkle hash of this node. */
         uint256 hash;
         /** Tracked leaves underneath this node (either from the node itself, or its children).
-         *  The merkle_branch field for each is the partners to get to *this* node. */
+         *  The merkle_branch field of each is the partners to get to *this* node. */
         std::vector<LeafInfo> leaves;
     };
     /** Whether the builder is in a valid state so far. */