Add further additional documentation to `Listen`
What changed, and why it matters
This commit only adds documentation comments to a Rust programming interface called `Listen`. It explains how callers should connect blocks, handle blockchain reorganizations, and what 'birthday' means for implementations. No code behavior was changed.
No action required; this is a documentation-only change.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff adds 18 lines of rustdoc to the Listen trait in lightning/src/chain/mod.rs. It documents requirements for block_connected/filtered_block_connected ordering, reorg handling via blocks_disconnected, and the BestBlock construction birthday. No trait methods, signatures, or logic were modified.
Changed components
lightning/src/chain/mod.rs documentationInspect captured patch +18 / −0
diff --git a/lightning/src/chain/mod.rs b/lightning/src/chain/mod.rs
index 35a01d7..2a6d3d2 100644
--- a/lightning/src/chain/mod.rs
+++ b/lightning/src/chain/mod.rs
@@ -73,6 +73,24 @@ impl_writeable_tlv_based!(BestBlock, {
/// By using [`Listen::filtered_block_connected`] this interface supports clients fetching the
/// entire header chain and only blocks with matching transaction data using BIP 157 filters or
/// other similar filtering.
+///
+/// # Requirements
+///
+/// Each block must be connected in chain order with one call to either
+/// [`Listen::block_connected`] or [`Listen::filtered_block_connected`]. If a call to the
+/// [`Filter`] interface was made during block processing and further transaction(s) from the same
+/// block now match the filter, a second call to [`Listen::filtered_block_connected`] should be
+/// made immediately for the same block (prior to any other calls to the [`Listen`] interface).
+///
+/// In case of a reorg, you must call [`Listen::blocks_disconnected`] once with information on the
+/// "fork point" block, i.e. the highest block that is in both forks. You may call
+/// [`Listen::blocks_disconnected`] multiple times as you walk the chain backwards, but each must
+/// include a fork point block that is before the last.
+///
+/// # Object Birthday
+///
+/// Note that most implementations take a [`BestBlock`] on construction and blocks only need to be
+/// applied starting from that point.
pub trait Listen {
/// Notifies the listener that a block was added at the given height, with the transaction data
/// possibly filtered.
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.