Doc and comment followups to #2562

lightning-persister/src/fs_store.rs

@@ -436,7 +436,7 @@ mod tests {
 	}
 
 	// Test that if the store's path to channel data is read-only, writing a
-	// monitor to it results in the store returning an InProgress.
+	// monitor to it results in the store returning an UnrecoverableError.
 	// Windows ignores the read-only flag for folders, so this test is Unix-only.
 	#[cfg(not(target_os = "windows"))]
 	#[test]
@@ -458,7 +458,7 @@ mod tests {
  let update_id = update_map.get(&added_monitors[0].0.to_channel_id()).unwrap();
 
  // Set the store's directory to read-only, which should result in
- // returning a permanent failure when we then attempt to persist a
+ // returning an unrecoverable failure when we then attempt to persist a
  // channel update.
  let path = &store.get_data_dir();
  let mut perms = fs::metadata(path).unwrap().permissions();

lightning/src/chain/chainmonitor.rs

@@ -98,7 +98,7 @@ impl MonitorUpdateId {
 /// If at some point no further progress can be made towards persisting the pending updates, the
 /// node should simply shut down.
 ///
-/// * If the persistence has failed and cannot be retried further (e.g. because of some timeout),
+/// * If the persistence has failed and cannot be retried further (e.g. because of an outage),
 /// [`ChannelMonitorUpdateStatus::UnrecoverableError`] can be used, though this will result in
 /// an immediate panic and future operations in LDK generally failing.
 ///
@@ -113,7 +113,10 @@ impl MonitorUpdateId {
 /// [`ChainMonitor::channel_monitor_updated`] must be called once for *each* update which occurs.
 ///
 /// If at some point no further progress can be made towards persisting a pending update, the node
-/// should simply shut down.
+/// should simply shut down. Until then, the background task should either loop indefinitely, or
+/// persistence should be regularly retried with [`ChainMonitor::list_pending_monitor_updates`]
+/// and [`ChainMonitor::get_monitor`] (note that if a full monitor is persisted all pending
+/// monitor updates may be marked completed).
 ///
 /// # Using remote watchtowers
 ///

lightning/src/ln/channelmanager.rs

@@ -3388,9 +3388,8 @@ where
 	/// In general, a path may raise:
 	/// * [`APIError::InvalidRoute`] when an invalid route or forwarding parameter (cltv_delta, fee,
 	/// node public key) is specified.
-	/// * [`APIError::ChannelUnavailable`] if the next-hop channel is not available for updates
-	/// (including due to previous monitor update failure or new permanent monitor update
-	/// failure).
+	/// * [`APIError::ChannelUnavailable`] if the next-hop channel is not available as it has been
+	/// closed, doesn't exist, or the peer is currently disconnected.
 	/// * [`APIError::MonitorUpdateInProgress`] if a new monitor update failure prevented sending the
 	/// relevant updates.
 	///

lightning/src/ln/shutdown_tests.rs

@@ -264,7 +264,7 @@ fn shutdown_on_unfunded_channel() {
 	nodes[0].node.create_channel(nodes[1].node.get_our_node_id(), 1_000_000, 100_000, 0, None).unwrap();
 	let open_chan = get_event_msg!(nodes[0], MessageSendEvent::SendOpenChannel, nodes[1].node.get_our_node_id());
 
-	// P2WSH
+	// Create a dummy P2WPKH script
 	let script = Builder::new().push_int(0)
  .push_slice(&[0; 20])
  .into_script();

lightning-persister/src/fs_store.rs

@@ -436,7 +436,7 @@ mod tests {
 	}
 
 	// Test that if the store's path to channel data is read-only, writing a
-	// monitor to it results in the store returning an InProgress.
+	// monitor to it results in the store returning an UnrecoverableError.
 	// Windows ignores the read-only flag for folders, so this test is Unix-only.
 	#[cfg(not(target_os = "windows"))]
 	#[test]
@@ -458,7 +458,7 @@ mod tests {
  let update_id = update_map.get(&added_monitors[0].0.to_channel_id()).unwrap();
 
  // Set the store's directory to read-only, which should result in
- // returning a permanent failure when we then attempt to persist a
+ // returning an unrecoverable failure when we then attempt to persist a
  // channel update.
  let path = &store.get_data_dir();
  let mut perms = fs::metadata(path).unwrap().permissions();

lightning/src/chain/chainmonitor.rs

@@ -98,7 +98,7 @@ impl MonitorUpdateId {
 /// If at some point no further progress can be made towards persisting the pending updates, the
 /// node should simply shut down.
 ///
-/// * If the persistence has failed and cannot be retried further (e.g. because of some timeout),
+/// * If the persistence has failed and cannot be retried further (e.g. because of an outage),
 /// [`ChannelMonitorUpdateStatus::UnrecoverableError`] can be used, though this will result in
 /// an immediate panic and future operations in LDK generally failing.
 ///
@@ -113,7 +113,10 @@ impl MonitorUpdateId {
 /// [`ChainMonitor::channel_monitor_updated`] must be called once for *each* update which occurs.
 ///
 /// If at some point no further progress can be made towards persisting a pending update, the node
-/// should simply shut down.
+/// should simply shut down. Until then, the background task should either loop indefinitely, or
+/// persistence should be regularly retried with [`ChainMonitor::list_pending_monitor_updates`]
+/// and [`ChainMonitor::get_monitor`] (note that if a full monitor is persisted all pending
+/// monitor updates may be marked completed).
 ///
 /// # Using remote watchtowers
 ///

lightning/src/ln/channelmanager.rs

@@ -3388,9 +3388,8 @@ where
 	/// In general, a path may raise:
 	/// * [`APIError::InvalidRoute`] when an invalid route or forwarding parameter (cltv_delta, fee,
 	/// node public key) is specified.
-	/// * [`APIError::ChannelUnavailable`] if the next-hop channel is not available for updates
-	/// (including due to previous monitor update failure or new permanent monitor update
-	/// failure).
+	/// * [`APIError::ChannelUnavailable`] if the next-hop channel is not available as it has been
+	/// closed, doesn't exist, or the peer is currently disconnected.
 	/// * [`APIError::MonitorUpdateInProgress`] if a new monitor update failure prevented sending the
 	/// relevant updates.
 	///

lightning/src/ln/shutdown_tests.rs

@@ -264,7 +264,7 @@ fn shutdown_on_unfunded_channel() {
 	nodes[0].node.create_channel(nodes[1].node.get_our_node_id(), 1_000_000, 100_000, 0, None).unwrap();
 	let open_chan = get_event_msg!(nodes[0], MessageSendEvent::SendOpenChannel, nodes[1].node.get_our_node_id());
 
-	// P2WSH
+	// Create a dummy P2WPKH script
 	let script = Builder::new().push_int(0)
  .push_slice(&[0; 20])
  .into_script();

lightning-persister/src/fs_store.rs

@@ -436,7 +436,7 @@ mod tests {
 	}
 
 	// Test that if the store's path to channel data is read-only, writing a
-	// monitor to it results in the store returning an InProgress.
+	// monitor to it results in the store returning an UnrecoverableError.
 	// Windows ignores the read-only flag for folders, so this test is Unix-only.
 	#[cfg(not(target_os = "windows"))]
 	#[test]
@@ -458,7 +458,7 @@ mod tests {
  let update_id = update_map.get(&added_monitors[0].0.to_channel_id()).unwrap();
 
  // Set the store's directory to read-only, which should result in
- // returning a permanent failure when we then attempt to persist a
+ // returning an unrecoverable failure when we then attempt to persist a
  // channel update.
  let path = &store.get_data_dir();
  let mut perms = fs::metadata(path).unwrap().permissions();

lightning/src/chain/chainmonitor.rs

@@ -98,7 +98,7 @@ impl MonitorUpdateId {
 /// If at some point no further progress can be made towards persisting the pending updates, the
 /// node should simply shut down.
 ///
-/// * If the persistence has failed and cannot be retried further (e.g. because of some timeout),
+/// * If the persistence has failed and cannot be retried further (e.g. because of an outage),
 /// [`ChannelMonitorUpdateStatus::UnrecoverableError`] can be used, though this will result in
 /// an immediate panic and future operations in LDK generally failing.
 ///
@@ -113,7 +113,10 @@ impl MonitorUpdateId {
 /// [`ChainMonitor::channel_monitor_updated`] must be called once for *each* update which occurs.
 ///
 /// If at some point no further progress can be made towards persisting a pending update, the node
-/// should simply shut down.
+/// should simply shut down. Until then, the background task should either loop indefinitely, or
+/// persistence should be regularly retried with [`ChainMonitor::list_pending_monitor_updates`]
+/// and [`ChainMonitor::get_monitor`] (note that if a full monitor is persisted all pending
+/// monitor updates may be marked completed).
 ///
 /// # Using remote watchtowers
 ///

lightning/src/ln/channelmanager.rs

@@ -3388,9 +3388,8 @@ where
 	/// In general, a path may raise:
 	/// * [`APIError::InvalidRoute`] when an invalid route or forwarding parameter (cltv_delta, fee,
 	/// node public key) is specified.
-	/// * [`APIError::ChannelUnavailable`] if the next-hop channel is not available for updates
-	/// (including due to previous monitor update failure or new permanent monitor update
-	/// failure).
+	/// * [`APIError::ChannelUnavailable`] if the next-hop channel is not available as it has been
+	/// closed, doesn't exist, or the peer is currently disconnected.
 	/// * [`APIError::MonitorUpdateInProgress`] if a new monitor update failure prevented sending the
 	/// relevant updates.
 	///

lightning/src/ln/shutdown_tests.rs

@@ -264,7 +264,7 @@ fn shutdown_on_unfunded_channel() {
 	nodes[0].node.create_channel(nodes[1].node.get_our_node_id(), 1_000_000, 100_000, 0, None).unwrap();
 	let open_chan = get_event_msg!(nodes[0], MessageSendEvent::SendOpenChannel, nodes[1].node.get_our_node_id());
 
-	// P2WSH
+	// Create a dummy P2WPKH script
 	let script = Builder::new().push_int(0)
  .push_slice(&[0; 20])
  .into_script();

lightning-persister/src/fs_store.rs

@@ -436,7 +436,7 @@ mod tests {
 	}
 
 	// Test that if the store's path to channel data is read-only, writing a
-	// monitor to it results in the store returning an InProgress.
+	// monitor to it results in the store returning an UnrecoverableError.
 	// Windows ignores the read-only flag for folders, so this test is Unix-only.
 	#[cfg(not(target_os = "windows"))]
 	#[test]
@@ -458,7 +458,7 @@ mod tests {
  let update_id = update_map.get(&added_monitors[0].0.to_channel_id()).unwrap();
 
  // Set the store's directory to read-only, which should result in
- // returning a permanent failure when we then attempt to persist a
+ // returning an unrecoverable failure when we then attempt to persist a
  // channel update.
  let path = &store.get_data_dir();
  let mut perms = fs::metadata(path).unwrap().permissions();

lightning/src/chain/chainmonitor.rs

@@ -98,7 +98,7 @@ impl MonitorUpdateId {
 /// If at some point no further progress can be made towards persisting the pending updates, the
 /// node should simply shut down.
 ///
-/// * If the persistence has failed and cannot be retried further (e.g. because of some timeout),
+/// * If the persistence has failed and cannot be retried further (e.g. because of an outage),
 /// [`ChannelMonitorUpdateStatus::UnrecoverableError`] can be used, though this will result in
 /// an immediate panic and future operations in LDK generally failing.
 ///
@@ -113,7 +113,10 @@ impl MonitorUpdateId {
 /// [`ChainMonitor::channel_monitor_updated`] must be called once for *each* update which occurs.
 ///
 /// If at some point no further progress can be made towards persisting a pending update, the node
-/// should simply shut down.
+/// should simply shut down. Until then, the background task should either loop indefinitely, or
+/// persistence should be regularly retried with [`ChainMonitor::list_pending_monitor_updates`]
+/// and [`ChainMonitor::get_monitor`] (note that if a full monitor is persisted all pending
+/// monitor updates may be marked completed).
 ///
 /// # Using remote watchtowers
 ///

lightning/src/ln/channelmanager.rs

@@ -3388,9 +3388,8 @@ where
 	/// In general, a path may raise:
 	/// * [`APIError::InvalidRoute`] when an invalid route or forwarding parameter (cltv_delta, fee,
 	/// node public key) is specified.
-	/// * [`APIError::ChannelUnavailable`] if the next-hop channel is not available for updates
-	/// (including due to previous monitor update failure or new permanent monitor update
-	/// failure).
+	/// * [`APIError::ChannelUnavailable`] if the next-hop channel is not available as it has been
+	/// closed, doesn't exist, or the peer is currently disconnected.
 	/// * [`APIError::MonitorUpdateInProgress`] if a new monitor update failure prevented sending the
 	/// relevant updates.
 	///

lightning/src/ln/shutdown_tests.rs

@@ -264,7 +264,7 @@ fn shutdown_on_unfunded_channel() {
 	nodes[0].node.create_channel(nodes[1].node.get_our_node_id(), 1_000_000, 100_000, 0, None).unwrap();
 	let open_chan = get_event_msg!(nodes[0], MessageSendEvent::SendOpenChannel, nodes[1].node.get_our_node_id());
 
-	// P2WSH
+	// Create a dummy P2WPKH script
 	let script = Builder::new().push_int(0)
  .push_slice(&[0; 20])
  .into_script();

lightning-persister/src/fs_store.rs

@@ -436,7 +436,7 @@ mod tests {
 	}
 
 	// Test that if the store's path to channel data is read-only, writing a
-	// monitor to it results in the store returning an InProgress.
+	// monitor to it results in the store returning an UnrecoverableError.
 	// Windows ignores the read-only flag for folders, so this test is Unix-only.
 	#[cfg(not(target_os = "windows"))]
 	#[test]
@@ -458,7 +458,7 @@ mod tests {
  let update_id = update_map.get(&added_monitors[0].0.to_channel_id()).unwrap();
 
  // Set the store's directory to read-only, which should result in
- // returning a permanent failure when we then attempt to persist a
+ // returning an unrecoverable failure when we then attempt to persist a
  // channel update.
  let path = &store.get_data_dir();
  let mut perms = fs::metadata(path).unwrap().permissions();

lightning/src/chain/chainmonitor.rs

@@ -98,7 +98,7 @@ impl MonitorUpdateId {
 /// If at some point no further progress can be made towards persisting the pending updates, the
 /// node should simply shut down.
 ///
-/// * If the persistence has failed and cannot be retried further (e.g. because of some timeout),
+/// * If the persistence has failed and cannot be retried further (e.g. because of an outage),
 /// [`ChannelMonitorUpdateStatus::UnrecoverableError`] can be used, though this will result in
 /// an immediate panic and future operations in LDK generally failing.
 ///
@@ -113,7 +113,10 @@ impl MonitorUpdateId {
 /// [`ChainMonitor::channel_monitor_updated`] must be called once for *each* update which occurs.
 ///
 /// If at some point no further progress can be made towards persisting a pending update, the node
-/// should simply shut down.
+/// should simply shut down. Until then, the background task should either loop indefinitely, or
+/// persistence should be regularly retried with [`ChainMonitor::list_pending_monitor_updates`]
+/// and [`ChainMonitor::get_monitor`] (note that if a full monitor is persisted all pending
+/// monitor updates may be marked completed).
 ///
 /// # Using remote watchtowers
 ///

lightning/src/ln/channelmanager.rs

@@ -3388,9 +3388,8 @@ where
 	/// In general, a path may raise:
 	/// * [`APIError::InvalidRoute`] when an invalid route or forwarding parameter (cltv_delta, fee,
 	/// node public key) is specified.
-	/// * [`APIError::ChannelUnavailable`] if the next-hop channel is not available for updates
-	/// (including due to previous monitor update failure or new permanent monitor update
-	/// failure).
+	/// * [`APIError::ChannelUnavailable`] if the next-hop channel is not available as it has been
+	/// closed, doesn't exist, or the peer is currently disconnected.
 	/// * [`APIError::MonitorUpdateInProgress`] if a new monitor update failure prevented sending the
 	/// relevant updates.
 	///

lightning/src/ln/shutdown_tests.rs

@@ -264,7 +264,7 @@ fn shutdown_on_unfunded_channel() {
 	nodes[0].node.create_channel(nodes[1].node.get_our_node_id(), 1_000_000, 100_000, 0, None).unwrap();
 	let open_chan = get_event_msg!(nodes[0], MessageSendEvent::SendOpenChannel, nodes[1].node.get_our_node_id());
 
-	// P2WSH
+	// Create a dummy P2WPKH script
 	let script = Builder::new().push_int(0)
  .push_slice(&[0; 20])
  .into_script();

lightning-persister/src/fs_store.rs

@@ -436,7 +436,7 @@ mod tests {
 	}
 
 	// Test that if the store's path to channel data is read-only, writing a
-	// monitor to it results in the store returning an InProgress.
+	// monitor to it results in the store returning an UnrecoverableError.
 	// Windows ignores the read-only flag for folders, so this test is Unix-only.
 	#[cfg(not(target_os = "windows"))]
 	#[test]
@@ -458,7 +458,7 @@ mod tests {
  let update_id = update_map.get(&added_monitors[0].0.to_channel_id()).unwrap();
 
  // Set the store's directory to read-only, which should result in
- // returning a permanent failure when we then attempt to persist a
+ // returning an unrecoverable failure when we then attempt to persist a
  // channel update.
  let path = &store.get_data_dir();
  let mut perms = fs::metadata(path).unwrap().permissions();

lightning/src/chain/chainmonitor.rs

@@ -98,7 +98,7 @@ impl MonitorUpdateId {
 /// If at some point no further progress can be made towards persisting the pending updates, the
 /// node should simply shut down.
 ///
-/// * If the persistence has failed and cannot be retried further (e.g. because of some timeout),
+/// * If the persistence has failed and cannot be retried further (e.g. because of an outage),
 /// [`ChannelMonitorUpdateStatus::UnrecoverableError`] can be used, though this will result in
 /// an immediate panic and future operations in LDK generally failing.
 ///
@@ -113,7 +113,10 @@ impl MonitorUpdateId {
 /// [`ChainMonitor::channel_monitor_updated`] must be called once for *each* update which occurs.
 ///
 /// If at some point no further progress can be made towards persisting a pending update, the node
-/// should simply shut down.
+/// should simply shut down. Until then, the background task should either loop indefinitely, or
+/// persistence should be regularly retried with [`ChainMonitor::list_pending_monitor_updates`]
+/// and [`ChainMonitor::get_monitor`] (note that if a full monitor is persisted all pending
+/// monitor updates may be marked completed).
 ///
 /// # Using remote watchtowers
 ///

lightning/src/ln/channelmanager.rs

@@ -3388,9 +3388,8 @@ where
 	/// In general, a path may raise:
 	/// * [`APIError::InvalidRoute`] when an invalid route or forwarding parameter (cltv_delta, fee,
 	/// node public key) is specified.
-	/// * [`APIError::ChannelUnavailable`] if the next-hop channel is not available for updates
-	/// (including due to previous monitor update failure or new permanent monitor update
-	/// failure).
+	/// * [`APIError::ChannelUnavailable`] if the next-hop channel is not available as it has been
+	/// closed, doesn't exist, or the peer is currently disconnected.
 	/// * [`APIError::MonitorUpdateInProgress`] if a new monitor update failure prevented sending the
 	/// relevant updates.
 	///

lightning/src/ln/shutdown_tests.rs

@@ -264,7 +264,7 @@ fn shutdown_on_unfunded_channel() {
 	nodes[0].node.create_channel(nodes[1].node.get_our_node_id(), 1_000_000, 100_000, 0, None).unwrap();
 	let open_chan = get_event_msg!(nodes[0], MessageSendEvent::SendOpenChannel, nodes[1].node.get_our_node_id());
 
-	// P2WSH
+	// Create a dummy P2WPKH script
 	let script = Builder::new().push_int(0)
  .push_slice(&[0; 20])
  .into_script();

lightning-persister/src/fs_store.rs

@@ -436,7 +436,7 @@ mod tests {
 	}
 
 	// Test that if the store's path to channel data is read-only, writing a
-	// monitor to it results in the store returning an InProgress.
+	// monitor to it results in the store returning an UnrecoverableError.
 	// Windows ignores the read-only flag for folders, so this test is Unix-only.
 	#[cfg(not(target_os = "windows"))]
 	#[test]
@@ -458,7 +458,7 @@ mod tests {
  let update_id = update_map.get(&added_monitors[0].0.to_channel_id()).unwrap();
 
  // Set the store's directory to read-only, which should result in
- // returning a permanent failure when we then attempt to persist a
+ // returning an unrecoverable failure when we then attempt to persist a
  // channel update.
  let path = &store.get_data_dir();
  let mut perms = fs::metadata(path).unwrap().permissions();

lightning/src/chain/chainmonitor.rs

@@ -98,7 +98,7 @@ impl MonitorUpdateId {
 /// If at some point no further progress can be made towards persisting the pending updates, the
 /// node should simply shut down.
 ///
-/// * If the persistence has failed and cannot be retried further (e.g. because of some timeout),
+/// * If the persistence has failed and cannot be retried further (e.g. because of an outage),
 /// [`ChannelMonitorUpdateStatus::UnrecoverableError`] can be used, though this will result in
 /// an immediate panic and future operations in LDK generally failing.
 ///
@@ -113,7 +113,10 @@ impl MonitorUpdateId {
 /// [`ChainMonitor::channel_monitor_updated`] must be called once for *each* update which occurs.
 ///
 /// If at some point no further progress can be made towards persisting a pending update, the node
-/// should simply shut down.
+/// should simply shut down. Until then, the background task should either loop indefinitely, or
+/// persistence should be regularly retried with [`ChainMonitor::list_pending_monitor_updates`]
+/// and [`ChainMonitor::get_monitor`] (note that if a full monitor is persisted all pending
+/// monitor updates may be marked completed).
 ///
 /// # Using remote watchtowers
 ///

lightning/src/ln/channelmanager.rs

@@ -3388,9 +3388,8 @@ where
 	/// In general, a path may raise:
 	/// * [`APIError::InvalidRoute`] when an invalid route or forwarding parameter (cltv_delta, fee,
 	/// node public key) is specified.
-	/// * [`APIError::ChannelUnavailable`] if the next-hop channel is not available for updates
-	/// (including due to previous monitor update failure or new permanent monitor update
-	/// failure).
+	/// * [`APIError::ChannelUnavailable`] if the next-hop channel is not available as it has been
+	/// closed, doesn't exist, or the peer is currently disconnected.
 	/// * [`APIError::MonitorUpdateInProgress`] if a new monitor update failure prevented sending the
 	/// relevant updates.
 	///

lightning/src/ln/shutdown_tests.rs

@@ -264,7 +264,7 @@ fn shutdown_on_unfunded_channel() {
 	nodes[0].node.create_channel(nodes[1].node.get_our_node_id(), 1_000_000, 100_000, 0, None).unwrap();
 	let open_chan = get_event_msg!(nodes[0], MessageSendEvent::SendOpenChannel, nodes[1].node.get_our_node_id());
 
-	// P2WSH
+	// Create a dummy P2WPKH script
 	let script = Builder::new().push_int(0)
  .push_slice(&[0; 20])
  .into_script();

lightning-persister/src/fs_store.rs

@@ -436,7 +436,7 @@ mod tests {
 	}
 
 	// Test that if the store's path to channel data is read-only, writing a
-	// monitor to it results in the store returning an InProgress.
+	// monitor to it results in the store returning an UnrecoverableError.
 	// Windows ignores the read-only flag for folders, so this test is Unix-only.
 	#[cfg(not(target_os = "windows"))]
 	#[test]
@@ -458,7 +458,7 @@ mod tests {
  let update_id = update_map.get(&added_monitors[0].0.to_channel_id()).unwrap();
 
  // Set the store's directory to read-only, which should result in
- // returning a permanent failure when we then attempt to persist a
+ // returning an unrecoverable failure when we then attempt to persist a
  // channel update.
  let path = &store.get_data_dir();
  let mut perms = fs::metadata(path).unwrap().permissions();

lightning/src/chain/chainmonitor.rs

@@ -98,7 +98,7 @@ impl MonitorUpdateId {
 /// If at some point no further progress can be made towards persisting the pending updates, the
 /// node should simply shut down.
 ///
-/// * If the persistence has failed and cannot be retried further (e.g. because of some timeout),
+/// * If the persistence has failed and cannot be retried further (e.g. because of an outage),
 /// [`ChannelMonitorUpdateStatus::UnrecoverableError`] can be used, though this will result in
 /// an immediate panic and future operations in LDK generally failing.
 ///
@@ -113,7 +113,10 @@ impl MonitorUpdateId {
 /// [`ChainMonitor::channel_monitor_updated`] must be called once for *each* update which occurs.
 ///
 /// If at some point no further progress can be made towards persisting a pending update, the node
-/// should simply shut down.
+/// should simply shut down. Until then, the background task should either loop indefinitely, or
+/// persistence should be regularly retried with [`ChainMonitor::list_pending_monitor_updates`]
+/// and [`ChainMonitor::get_monitor`] (note that if a full monitor is persisted all pending
+/// monitor updates may be marked completed).
 ///
 /// # Using remote watchtowers
 ///

lightning/src/ln/channelmanager.rs

@@ -3388,9 +3388,8 @@ where
 	/// In general, a path may raise:
 	/// * [`APIError::InvalidRoute`] when an invalid route or forwarding parameter (cltv_delta, fee,
 	/// node public key) is specified.
-	/// * [`APIError::ChannelUnavailable`] if the next-hop channel is not available for updates
-	/// (including due to previous monitor update failure or new permanent monitor update
-	/// failure).
+	/// * [`APIError::ChannelUnavailable`] if the next-hop channel is not available as it has been
+	/// closed, doesn't exist, or the peer is currently disconnected.
 	/// * [`APIError::MonitorUpdateInProgress`] if a new monitor update failure prevented sending the
 	/// relevant updates.
 	///

lightning/src/ln/shutdown_tests.rs

@@ -264,7 +264,7 @@ fn shutdown_on_unfunded_channel() {
 	nodes[0].node.create_channel(nodes[1].node.get_our_node_id(), 1_000_000, 100_000, 0, None).unwrap();
 	let open_chan = get_event_msg!(nodes[0], MessageSendEvent::SendOpenChannel, nodes[1].node.get_our_node_id());
 
-	// P2WSH
+	// Create a dummy P2WPKH script
 	let script = Builder::new().push_int(0)
  .push_slice(&[0; 20])
  .into_script();