From: Wei Chen <wzc110@gmail.com>
Date: Mon, 18 Aug 2025 06:57:53 +0000 (+0000)
Subject: docs(chain): update docs for `CheckPoint` and `SyncRequest`
X-Git-Url: http://internal-gitweb-vhost/?a=commitdiff_plain;h=8bc239168a2d81430244ee7633723f7eefe0d0f4;p=bdk

docs(chain): update docs for `CheckPoint` and `SyncRequest`
---

diff --git a/crates/core/src/checkpoint.rs b/crates/core/src/checkpoint.rs
index a3041296..d0a9bacd 100644
--- a/crates/core/src/checkpoint.rs
+++ b/crates/core/src/checkpoint.rs
@@ -2,7 +2,7 @@ use core::fmt;
 use core::ops::RangeBounds;
 
 use alloc::sync::Arc;
-use bitcoin::{block::Header, Block, BlockHash};
+use bitcoin::{block::Header, BlockHash};
 
 use crate::BlockId;
 
@@ -60,8 +60,11 @@ impl<D> Drop for CPInner<D> {
 
 /// Trait that converts [`CheckPoint`] `data` to [`BlockHash`].
 ///
-/// Implementations of [`ToBlockHash`] must consist exclusively of the data to be hashed — do not
-/// include any extraneous fields.
+/// Implementations of [`ToBlockHash`] must always return the block’s consensus-defined hash. If
+/// your type contains extra fields (timestamps, metadata, etc.), these must be ignored. For
+/// example, [`BlockHash`] trivially returns itself, [`Header`] calls its `block_hash()`, and a
+/// wrapper type around a [`Header`] should delegate to the header’s hash rather than derive one
+/// from other fields.
 pub trait ToBlockHash {
     /// Returns the [`BlockHash`] for the associated [`CheckPoint`] `data` type.
     fn to_blockhash(&self) -> BlockHash;
@@ -79,12 +82,6 @@ impl ToBlockHash for Header {
     }
 }
 
-impl ToBlockHash for Block {
-    fn to_blockhash(&self) -> BlockHash {
-        self.block_hash()
-    }
-}
-
 impl<D> PartialEq for CheckPoint<D> {
     fn eq(&self, other: &Self) -> bool {
         let self_cps = self.iter().map(|cp| cp.block_id());
@@ -239,11 +236,11 @@ where
 
     /// Inserts `data` at its `height` within the chain.
     ///
-    /// The effect of `insert` depends on whether a height already exists. If it doesn't the
-    /// `block_id` we inserted and all pre-existing blocks higher than it will be re-inserted after
-    /// it. If the height already existed and has a conflicting block hash then it will be purged
-    /// along with all block following it. The returned chain will have a tip of the `block_id`
-    /// passed in. Of course, if the `block_id` was already present then this just returns `self`.
+    /// The effect of `insert` depends on whether a height already exists. If it doesn't, the data
+    /// we inserted and all pre-existing entries higher than it will be re-inserted after it. If the
+    /// height already existed and has a conflicting block hash then it will be purged along with
+    /// all entries following it. The returned chain will have a tip of the data passed in. Of
+    /// course, if the data was already present then this just returns `self`.
     ///
     /// # Panics
     ///
@@ -258,7 +255,7 @@ where
                     return self;
                 }
                 assert_ne!(cp.height(), 0, "cannot replace genesis block");
-                // if we have a conflict we just return the inserted block because the tail is by
+                // If we have a conflict we just return the inserted data because the tail is by
                 // implication invalid.
                 tail = vec![];
                 break cp.prev().expect("can't be called on genesis block");
diff --git a/crates/core/src/spk_client.rs b/crates/core/src/spk_client.rs
index 12bbba56..2c80e70a 100644
--- a/crates/core/src/spk_client.rs
+++ b/crates/core/src/spk_client.rs
@@ -164,8 +164,8 @@ impl<I, D> SyncRequestBuilder<I, D> {
     ///     .build();
     ///
     /// // Sync all revealed spks in the indexer. This time, spks may be derived from different
-    /// // keychains. Each spk will be indexed with `(&'static str, u32)` where `&'static str` is
-    /// // the keychain identifier and `u32` is the derivation index.
+    /// // keychains. Each spk will be indexed with `(&str, u32)` where `&str` is the keychain
+    /// // identifier and `u32` is the derivation index.
     /// let all_revealed_spks = indexer.revealed_spks(..);
     /// let _request: SyncRequest<(&str, u32), BlockHash> = SyncRequest::builder()
     ///     .spks_with_indexes(all_revealed_spks)