Merge rust-bitcoin/rust-bitcoin#7117: primitives: Document omitted return conditions
What changed, and why it matters
This commit only updates documentation comments in the rust-bitcoin library. It adds notes explaining when two Merkle-root calculation functions can return None (specifically when a no-memory-allocation build mode is used with very large transaction lists) and clarifies what the two parts of a witness-commitment check result mean. No code behavior was changed.
No security action needed; this is a documentation-only change. Reviewers may verify that the added docs accurately reflect the existing implementation.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The patch is a docs-only change across three files in the primitives crate. It copies an existing no-alloc transaction-count limit note from a private trait into the public docs for TxMerkleNode::calculate_root and WitnessMerkleNode::calculate_root, and expands the Returns section of Block::check_witness_commitment to describe both the boolean validity result and the optional witness Merkle root. No logic, signatures, or APIs were modified.
Changed components
primitives/src/block.rsprimitives/src/hash_types/transaction_merkle_node.rsprimitives/src/hash_types/witness_merkle_node.rsInspect captured patch +10 / −2
### primitives/src/block.rs
@@ -344,8 +344,10 @@ impl Block<Unchecked> {
///
/// # Returns
///
- /// Returns the witness Merkle root if it was computed. This can then be passed into
- /// [`assume_checked`] to save re-calculating it.
+ /// Whether the witness commitment is valid, and the witness Merkle root if it was computed.
+ /// The commitment is valid if it matches the transaction list, or if it is absent and no
+ /// transaction has witness data. The root can then be passed into [`assume_checked`] to save
+ /// re-calculating it.
///
/// [`assume_checked`]: Block<Unchecked>::assume_checked
///
### primitives/src/hash_types/transaction_merkle_node.rs
@@ -47,6 +47,9 @@ impl TxMerkleNode {
/// transactions will always be invalid, so there is no harm in us refusing to
/// compute their Merkle roots.
///
+ /// Also returns [`None`] if the `alloc` feature is disabled and `iter` has more than
+ /// 32,767 transactions.
+ ///
/// Unless you are certain your transaction list is nonempty and has no duplicates,
/// you should not unwrap the [`Option`] returned by this method!
pub fn calculate_root<I: IntoIterator<Item = Txid>>(iter: I) -> Option<Self> {
### primitives/src/hash_types/witness_merkle_node.rs
@@ -47,6 +47,9 @@ impl WitnessMerkleNode {
/// transactions will always be invalid, so there is no harm in us refusing to
/// compute their Merkle roots.
///
+ /// Also returns [`None`] if the `alloc` feature is disabled and `iter` has more than
+ /// 32,767 transactions.
+ ///
/// Unless you are certain your transaction list is nonempty and has no duplicates,
/// you should not unwrap the [`Option`] returned by this method!
pub fn calculate_root<I: IntoIterator<Item = Wtxid>>(iter: I) -> Option<Self> {Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.