Merge bitcoin/bitcoin#31596: doc: Clarify comments about endianness after #30526

3e0a992 doc: Clarify comments about endianness after #30526 (Ryan Ofsky)

Pull request description:

  This is a documentation-only change following up on suggestions made in the #30526 review.

  Motivation for this change is that I was recently reviewing #31583, which reminded me how confusing the arithmetic blob code was and made me want to write better comments.

ACKs for top commit:
  achow101:
    ACK 3e0a992
  TheCharlatan:
    ACK 3e0a992
  Sjors:
    ACK 3e0a992
  BrandonOdiwuor:
    LGTM ACK 3e0a992

Tree-SHA512: 90d5582a25a51fc406d83ca6b8c4e5e4d3aee828a0497f4b226b2024ff89e29b9b50d0ae8ddeac6abf2757fe78548d58cf3dd54df4b6d623f634a2106048091d

Author: achow101

src/arith_uint256.h

@@ -26,6 +26,7 @@ class base_uint
 protected:
     static_assert(BITS / 32 > 0 && BITS % 32 == 0, "Template parameter BITS must be a positive multiple of 32.");
     static constexpr int WIDTH = BITS / 32;
+    /** Big integer represented with 32-bit digits, least-significant first. */
     uint32_t pn[WIDTH];
 public:
 

src/policy/packages.h

@@ -89,8 +89,9 @@ bool IsChildWithParents(const Package& package);
  */
 bool IsChildWithParentsTree(const Package& package);
 
-/** Get the hash of these transactions' wtxids, concatenated in lexicographical order (treating the
- * wtxids as little endian encoded uint256, smallest to largest). */
+/** Get the hash of the concatenated wtxids of transactions, with wtxids
+ * treated as a little-endian numbers and sorted in ascending numeric order.
+ */
 uint256 GetPackageHash(const std::vector<CTransactionRef>& transactions);
 
 #endif // BITCOIN_POLICY_PACKAGES_H

src/rpc/mining.cpp

@@ -633,8 +633,8 @@ static RPCHelpMan getblocktemplate()
                     {RPCResult::Type::OBJ, "", "",
                     {
                         {RPCResult::Type::STR_HEX, "data", "transaction data encoded in hexadecimal (byte-for-byte)"},
-                        {RPCResult::Type::STR_HEX, "txid", "transaction id encoded in little-endian hexadecimal"},
-                        {RPCResult::Type::STR_HEX, "hash", "hash encoded in little-endian hexadecimal (including witness data)"},
+                        {RPCResult::Type::STR_HEX, "txid", "transaction hash excluding witness data, shown in byte-reversed hex"},
+                        {RPCResult::Type::STR_HEX, "hash", "transaction hash including witness data, shown in byte-reversed hex"},
                         {RPCResult::Type::ARR, "depends", "array of numbers",
                         {
                             {RPCResult::Type::NUM, "", "transactions before this one (by 1-based index in 'transactions' list) that must be present in the final block if this one is"},

src/uint256.h

@@ -69,16 +69,27 @@ class base_blob
 
     /** @name Hex representation
      *
-     * The reverse-byte hex representation is a convenient way to view the blob
-     * as a number, because it is consistent with the way the base_uint class
-     * converts blobs to numbers.
+     * The hex representation used by GetHex(), ToString(), FromHex() and
+     * SetHexDeprecated() is unusual, since it shows bytes of the base_blob in
+     * reverse order. For example, a 4-byte blob {0x12, 0x34, 0x56, 0x78} is
+     * represented as "78563412" instead of the more typical "12345678"
+     * representation that would be shown in a hex editor or used by typical
+     * byte-array / hex conversion functions like python's bytes.hex() and
+     * bytes.fromhex().
+     *
+     * The nice thing about the reverse-byte representation, even though it is
+     * unusual, is that if a blob contains an arithmetic number in little endian
+     * format (with least significant bytes first, and most significant bytes
+     * last), the GetHex() output will match the way the number would normally
+     * be written in base-16 (with most significant digits first and least
+     * significant digits last).
+     *
+     * This means, for example, that ArithToUint256(num).GetHex() can be used to
+     * display an arith_uint256 num value as a number, because
+     * ArithToUint256() converts the number to a blob in little-endian format,
+     * so the arith_uint256 class doesn't need to have its own number parsing
+     * and formatting functions.
      *
-     * @note base_uint treats the blob as an array of bytes with the numerically
-     * least significant byte first and the most significant byte last. Because
-     * numbers are typically written with the most significant digit first and
-     * the least significant digit last, the reverse hex display of the blob
-     * corresponds to the same numeric value that base_uint interprets from the
-     * blob.
      * @{*/
     std::string GetHex() const;
     /** Unlike FromHex this accepts any invalid input, thus it is fragile and deprecated!