+/// Updates channel state to take note of transactions which were confirmed in the given block
+/// at the given height.
+///
+/// Note that you must still call (or have called) [`update_best_block`] with the block
+/// information which is included here.
+///
+/// This method may be called before or after [`update_best_block`] for a given block's
+/// transaction data and may be called multiple times with additional transaction data for a
+/// given block.
+///
+/// This method may be called for a previous block after an [`update_best_block`] call has
+/// been made for a later block, however it must *not* be called with transaction data from a
+/// block which is no longer in the best chain (ie where [`update_best_block`] has already
+/// been informed about a blockchain reorganization which no longer includes the block which
+/// corresponds to `header`).
+///
+/// [`update_best_block`]: `Self::update_best_block`