Skip to content

Commit 7615b5a

Browse files
committed
Add further additional documentation to Listen
`Listen` is somewhat quiet on high-level use and even requirements, which we document further here.
1 parent f859a8a commit 7615b5a

File tree

1 file changed

+14
-0
lines changed

1 file changed

+14
-0
lines changed

lightning/src/chain/mod.rs

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,20 @@ impl_writeable_tlv_based!(BestBlock, {
7373
/// By using [`Listen::filtered_block_connected`] this interface supports clients fetching the
7474
/// entire header chain and only blocks with matching transaction data using BIP 157 filters or
7575
/// other similar filtering.
76+
///
77+
/// Each block must be connected in chain order with one call to either
78+
/// [`Listen::block_connected`] or [`Listen::filtered_block_connected`]. If a call to the
79+
/// [`Filter`] interface was made during block processing and further transaction(s) from the same
80+
/// block now match the filter, a second call to [`Listen::filtered_block_connected`] should be
81+
/// made immediately for the same block (prior to any other calls to the [`Listen`] interface).
82+
///
83+
/// In case of a reorg, you must call [`Listen::blocks_disconnected`] once with information on the
84+
/// "fork point" block, i.e. the highest block that is in both forks. For backwards compatibility,
85+
/// you may instead walk the chain backwards, calling `blocks_disconnected` for each block which is
86+
/// disconnected in a reorg.
87+
///
88+
/// Note that most implementations take a [`BestBlock`] on construction and blocks only need to be
89+
/// applied starting from that point.
7690
pub trait Listen {
7791
/// Notifies the listener that a block was added at the given height, with the transaction data
7892
/// possibly filtered.

0 commit comments

Comments
 (0)