message: Update docs on `hash_merkle_root`
diff: @@ -114,9 +114,19 @@ impl Digest {
  Digest(result)
  }
  - /// Hashes a Merkle root and leaf count.
  + /// Hashes a raw Merkle root and leaf count to firm the final Merkle hash.
  ///
  - /// TODO: Document this function and its role in pre-image attacks.
  + /// To avoid pre-image attacks, the final hash that is based upon the number of leaves in the
  + /// merkle tree and the root hash is prepended with a padding to ensure it is longer than the
  + /// actual chunk size.
  + ///
  + /// Without this feature, an attacker could construct an item that is only a few bytes long but
  + /// hashes to the same value as a much longer, chunked item by hashing `(len || root hash of
  + /// longer items Merkle tree root)`.
  + ///
  + /// This function computes the correct final hash by ensuring the hasher used has been
  + /// initialized with padding before. For efficiency reasons it uses a memoized hasher state
  + /// computed on first run and cloned afterwards.
  fn hash_merkle_root(leaf_count: u64, root: Digest) -> Digest {
  static PAIR_PREFIX_HASHER: OnceCell<VarBlake2b> = OnceCell::new();
  