Consider channels "live" even if they are awaiting a monitor update

[TheBlueMatt]

We use Channel::is_live() to gate inclusion of a channel in
ChannelManager::list_usable_channels() and when sending an
HTLC to select whether a channel is available for
forwarding through/sending to.

In both of these cases, we almost certainly want
Channel::is_live() to include channels which are simply pending a
monitor update, as some clients may update monitors asynchronously,
thus any rejection of HTLCs based on a monitor update still pending
causing a race condition.

After #851, we always ensure any holding cells are free'd when
sending P2P messages, making this much more trivially correct -
instead of having to ensure that we always have a matching holding
cell free any time we add something to the holding cell, we can
simply rely on the fact that it always happens.

Fixes#661.

This should make #949's tests a bit easier to implement.

[codecov]

Codecov Report

Merging #954 (0534e8b) into main (2940099) will increase coverage by 1.47%.
The diff coverage is 91.30%.

❗ Current head 0534e8b differs from pull request most recent head b58c884. Consider uploading reports for the commit b58c884 to get more accurate results

@@ Coverage Diff @@## main #954 +/- ##
==========================================
+ Coverage 90.59% 92.06% +1.47% 
==========================================
Files 60 60 Lines 30423 39444 +9021 ==========================================
+ Hits 27561 36314 +8753 - Misses 2862 3130 +268 

Impacted Files	Coverage Δ
lightning/src/ln/channelmanager.rs	87.18% <ø> (+3.27%)	⬆️
lightning/src/ln/channel.rs	92.86% <87.50%> (+4.57%)	⬆️
lightning/src/ln/chanmon_update_fail_tests.rs	97.60% <91.58%> (-0.19%)	⬇️
lightning/src/ln/wire.rs	60.52% <0.00%> (-3.58%)	⬇️
lightning/src/util/macro_logger.rs	87.87% <0.00%> (-1.19%)	⬇️
lightning/src/ln/functional_test_utils.rs	94.79% <0.00%> (-0.03%)	⬇️
lightning/src/ln/reorg_tests.rs	100.00% <0.00%> (+0.37%)	⬆️
lightning/src/chain/chainmonitor.rs	96.21% <0.00%> (+0.41%)	⬆️
lightning/src/util/ser.rs	91.70% <0.00%> (+0.43%)	⬆️
... and 20 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2940099...b58c884. Read the comment docs.

[TheBlueMatt]

Addressed a few comments left on other PRs, including #949 (comment)

[ariard]

Just need to fix send_htlc doc I believe, otherwise good to me

[ariard]

This comment sounds weird, I still think we should be able to receive a HTLC even if the forwarding channel is knock-out, though we don't currently in decode_update_add_htlc_onion. Maybe possible after #680.

[TheBlueMatt]

Right, I suppose its reasonable to accept an HTLC for forwarding to a channel which is disconnected currently if you're a special type of node that can make the channel become connected soon (of course for a general purpose node we should definitely fail). There isn't a lot of harm in waiting to fail until the payment gets to the send_htlc call (instead of doing it immediately upon receipt), so I think I agree we should just drop it (but keep this return).

All that to say, I don't think anything needs to change in this PR, correct? The comment is still true today, though I agree we could change it in a followup and should change it after #680.

[ariard]

Yeah I just believe this forwarding policy makes really sense if the next hop is owned by a mobile client, with a clear agreement "I'm going to be offline 99% of my time, please cache my HTLC" ? Or at least it would be worthy as an experimentation.

Right, it's more a good-place-to-clean-once-we-have-680.

[ariard]

Code Review ACK 8671aca

[TheBlueMatt]

Tagging as 0.0.99 as #949 depends on this and because this would be critical for any async-monitor-update routing node.

[TheBlueMatt]

Squashed with no changes:

$ git diff-tree 8671aca5 eab577c0
$

[jkczyz]

Somethings aren't clear to me when reading the commit message / PR description:

In both of these cases, we almost certainly want
Channel::is_live() to include channels which are simply pending a
monitor update, as some clients may update monitors asynchronously,

Either drop "almost certainly" or explain when this is not the case.

thus any rejection of HTLCs based on a monitor update still pending
causing a race condition.

Reads strange. Start new sentence here and replace "causing" with "causes"?

After #851, we always ensure any holding cells are free'd when
sending P2P messages, making this much more trivially correct -

What is "this" referring to? "this change"?

instead of having to ensure that we always have a matching holding
cell free any time we add something to the holding cell, we can
simply rely on the fact that it always happens.

Unclear to me what is meant by a "matching holding cell" (matching what?) and what "it always happens" is referring to.

[jkczyz]

Is there a TL;DR to summarize the changes to this test to help in review?

[TheBlueMatt]

Because it is no longer the case that receiving an HTLC while we're pending a monitor update restoration causes the HTLC to fail, code which relied on that behavior broke. eg the first code hunk which was removed explicitly delivered an HTLC and expected it to fail, which no longer happens.

The big if-block diff hunk is because the two cases have converged somewhat - we now always have a payment in node[1]'s outbound holding cell.

[jkczyz]

Is there any way to assert the state of the channel rather than examining the log?

[TheBlueMatt]

This line was only moved, not created. the log assert is nice IMO as it checks the specific error, not just that one happened, though the observable state is still checked in that no new message was generated.

[TheBlueMatt]

I rewrote the commit message in the main commit (without changing its contents), let me know what you think.

[jkczyz]

I rewrote the commit message in the main commit (without changing its contents), let me know what you think.

Looks good. Thanks for doing it!

[TheBlueMatt]

Squashed with no changes:

$ git diff-tree -U1 0534e8b9 b58c8843
$

The full diff from the previous ack is still trivial, so will merge after CI:

$ git diff-tree -U1 -b eab577c0 b58c8843
diff --git a/lightning/src/ln/chanmon_update_fail_tests.rs b/lightning/src/ln/chanmon_update_fail_tests.rs
index ac293cc1..73fc5315 100644
--- a/lightning/src/ln/chanmon_update_fail_tests.rs
+++ b/lightning/src/ln/chanmon_update_fail_tests.rs
@@ -908,4 +908,4 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-	// Attempt to forward a third payment but fail due to the second channel being unavailable
-	// for forwarding.
+	// Forward a third payment which will also be added to the holding cell, despite the channel
+	// being paused waiting a monitor update.
let (_, payment_hash_3, payment_secret_3) = get_payment_preimage_hash!(nodes[2]);
@@ -924,2 +924,8 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
+	// Call forward_pending_htlcs and check that the new HTLC was simply added to the holding cell
+	// and not forwarded.
+	expect_pending_htlcs_forwardable!(nodes[1]);
+	check_added_monitors!(nodes[1], 0);
+	assert!(nodes[1].node.get_and_clear_pending_events().is_empty());
+
let (payment_preimage_4, payment_hash_4) = if test_ignore_second_cs {
@@ -942,8 +948,2 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-	// Call forward_pending_htlcs first to make sure we don't have any issues attempting (and
-	// failing) to forward an HTLC while a channel is still awaiting monitor update restoration.
-	expect_pending_htlcs_forwardable!(nodes[1]);
-	check_added_monitors!(nodes[1], 0);
-	assert!(nodes[1].node.get_and_clear_pending_events().is_empty());
-
// Restore monitor updating, ensuring we immediately get a fail-back update and a
@@ -1048,2 +1048,3 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
}
+
assert_eq!(as_cs.update_add_htlcs.len(), 1);
@@ -1077,3 +1078,2 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-
expect_pending_htlcs_forwardable!(nodes[2]);
diff --git a/lightning/src/ln/channel.rs b/lightning/src/ln/channel.rs
index 19e28d4a..26725111 100644
--- a/lightning/src/ln/channel.rs
+++ b/lightning/src/ln/channel.rs
@@ -3976,10 +3976,14 @@ impl<Signer: Sign> Channel<Signer> {
/// send_htlc_and_commit instead cause you'll want both messages at once.
-	/// This returns an option instead of a pure UpdateAddHTLC as we may be in a state where we
-	/// cannot add HTLCs on the wire.
-	/// In cases where we're waiting on the remote peer to send us a revoke_and_ack, if we did, we
-	/// wouldn't be able to determine what they actually ACK'ed when we do receive the
-	/// revoke_and_ack.
-	/// In cases where we're marked MonitorUpdateFailed, we cannot commit to a new state as we may
-	/// not yet have sent the previous commitment update messages and will need to regenerate them.
-	/// You MUST call send_commitment prior to any other calls on this Channel
+	///
+	/// This returns an optional UpdateAddHTLC as we may be in a state where we cannot add HTLCs on
+	/// the wire:
+	/// * In cases where we're waiting on the remote peer to send us a revoke_and_ack, we
+	/// wouldn't be able to determine what they actually ACK'ed if we have two sets of updates
+	/// awaiting ACK.
+	/// * In cases where we're marked MonitorUpdateFailed, we cannot commit to a new state as we
+	/// may not yet have sent the previous commitment update messages and will need to regenerate
+	/// them.
+	///
+	/// You MUST call send_commitment prior to calling any other methods on this Channel!
+	///
/// If an Err is returned, it's a ChannelError::Ignore!
$

[TheBlueMatt]

We use Channel::is_live() to gate inclusion of a channel in
ChannelManager::list_usable_channels() and when sending an
HTLC to select whether a channel is available for
forwarding through/sending to.

In both of these cases, we almost certainly want
Channel::is_live() to include channels which are simply pending a
monitor update, as some clients may update monitors asynchronously,
thus any rejection of HTLCs based on a monitor update still pending
causing a race condition.

After #851, we always ensure any holding cells are free'd when
sending P2P messages, making this much more trivially correct -
instead of having to ensure that we always have a matching holding
cell free any time we add something to the holding cell, we can
simply rely on the fact that it always happens.

Fixes#661.

This should make #949's tests a bit easier to implement.

[codecov]

Codecov Report

Merging #954 (0534e8b) into main (2940099) will increase coverage by 1.47%.
The diff coverage is 91.30%.

❗ Current head 0534e8b differs from pull request most recent head b58c884. Consider uploading reports for the commit b58c884 to get more accurate results

@@ Coverage Diff @@## main #954 +/- ##
==========================================
+ Coverage 90.59% 92.06% +1.47% 
==========================================
Files 60 60 Lines 30423 39444 +9021 ==========================================
+ Hits 27561 36314 +8753 - Misses 2862 3130 +268 

Impacted Files	Coverage Δ
lightning/src/ln/channelmanager.rs	87.18% <ø> (+3.27%)	⬆️
lightning/src/ln/channel.rs	92.86% <87.50%> (+4.57%)	⬆️
lightning/src/ln/chanmon_update_fail_tests.rs	97.60% <91.58%> (-0.19%)	⬇️
lightning/src/ln/wire.rs	60.52% <0.00%> (-3.58%)	⬇️
lightning/src/util/macro_logger.rs	87.87% <0.00%> (-1.19%)	⬇️
lightning/src/ln/functional_test_utils.rs	94.79% <0.00%> (-0.03%)	⬇️
lightning/src/ln/reorg_tests.rs	100.00% <0.00%> (+0.37%)	⬆️
lightning/src/chain/chainmonitor.rs	96.21% <0.00%> (+0.41%)	⬆️
lightning/src/util/ser.rs	91.70% <0.00%> (+0.43%)	⬆️
... and 20 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2940099...b58c884. Read the comment docs.

[TheBlueMatt]

Addressed a few comments left on other PRs, including #949 (comment)

[ariard]

Just need to fix send_htlc doc I believe, otherwise good to me

[ariard]

This comment sounds weird, I still think we should be able to receive a HTLC even if the forwarding channel is knock-out, though we don't currently in decode_update_add_htlc_onion. Maybe possible after #680.

[TheBlueMatt]

Right, I suppose its reasonable to accept an HTLC for forwarding to a channel which is disconnected currently if you're a special type of node that can make the channel become connected soon (of course for a general purpose node we should definitely fail). There isn't a lot of harm in waiting to fail until the payment gets to the send_htlc call (instead of doing it immediately upon receipt), so I think I agree we should just drop it (but keep this return).

All that to say, I don't think anything needs to change in this PR, correct? The comment is still true today, though I agree we could change it in a followup and should change it after #680.

[ariard]

Yeah I just believe this forwarding policy makes really sense if the next hop is owned by a mobile client, with a clear agreement "I'm going to be offline 99% of my time, please cache my HTLC" ? Or at least it would be worthy as an experimentation.

Right, it's more a good-place-to-clean-once-we-have-680.

[ariard]

Code Review ACK 8671aca

[TheBlueMatt]

Tagging as 0.0.99 as #949 depends on this and because this would be critical for any async-monitor-update routing node.

[TheBlueMatt]

Squashed with no changes:

$ git diff-tree 8671aca5 eab577c0
$

[jkczyz]

Somethings aren't clear to me when reading the commit message / PR description:

In both of these cases, we almost certainly want
Channel::is_live() to include channels which are simply pending a
monitor update, as some clients may update monitors asynchronously,

Either drop "almost certainly" or explain when this is not the case.

thus any rejection of HTLCs based on a monitor update still pending
causing a race condition.

Reads strange. Start new sentence here and replace "causing" with "causes"?

After #851, we always ensure any holding cells are free'd when
sending P2P messages, making this much more trivially correct -

What is "this" referring to? "this change"?

instead of having to ensure that we always have a matching holding
cell free any time we add something to the holding cell, we can
simply rely on the fact that it always happens.

Unclear to me what is meant by a "matching holding cell" (matching what?) and what "it always happens" is referring to.

[jkczyz]

Is there a TL;DR to summarize the changes to this test to help in review?

[TheBlueMatt]

Because it is no longer the case that receiving an HTLC while we're pending a monitor update restoration causes the HTLC to fail, code which relied on that behavior broke. eg the first code hunk which was removed explicitly delivered an HTLC and expected it to fail, which no longer happens.

The big if-block diff hunk is because the two cases have converged somewhat - we now always have a payment in node[1]'s outbound holding cell.

[jkczyz]

Is there any way to assert the state of the channel rather than examining the log?

[TheBlueMatt]

This line was only moved, not created. the log assert is nice IMO as it checks the specific error, not just that one happened, though the observable state is still checked in that no new message was generated.

[TheBlueMatt]

I rewrote the commit message in the main commit (without changing its contents), let me know what you think.

[jkczyz]

I rewrote the commit message in the main commit (without changing its contents), let me know what you think.

Looks good. Thanks for doing it!

[TheBlueMatt]

Squashed with no changes:

$ git diff-tree -U1 0534e8b9 b58c8843
$

The full diff from the previous ack is still trivial, so will merge after CI:

$ git diff-tree -U1 -b eab577c0 b58c8843
diff --git a/lightning/src/ln/chanmon_update_fail_tests.rs b/lightning/src/ln/chanmon_update_fail_tests.rs
index ac293cc1..73fc5315 100644
--- a/lightning/src/ln/chanmon_update_fail_tests.rs
+++ b/lightning/src/ln/chanmon_update_fail_tests.rs
@@ -908,4 +908,4 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-	// Attempt to forward a third payment but fail due to the second channel being unavailable
-	// for forwarding.
+	// Forward a third payment which will also be added to the holding cell, despite the channel
+	// being paused waiting a monitor update.
let (_, payment_hash_3, payment_secret_3) = get_payment_preimage_hash!(nodes[2]);
@@ -924,2 +924,8 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
+	// Call forward_pending_htlcs and check that the new HTLC was simply added to the holding cell
+	// and not forwarded.
+	expect_pending_htlcs_forwardable!(nodes[1]);
+	check_added_monitors!(nodes[1], 0);
+	assert!(nodes[1].node.get_and_clear_pending_events().is_empty());
+
let (payment_preimage_4, payment_hash_4) = if test_ignore_second_cs {
@@ -942,8 +948,2 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-	// Call forward_pending_htlcs first to make sure we don't have any issues attempting (and
-	// failing) to forward an HTLC while a channel is still awaiting monitor update restoration.
-	expect_pending_htlcs_forwardable!(nodes[1]);
-	check_added_monitors!(nodes[1], 0);
-	assert!(nodes[1].node.get_and_clear_pending_events().is_empty());
-
// Restore monitor updating, ensuring we immediately get a fail-back update and a
@@ -1048,2 +1048,3 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
}
+
assert_eq!(as_cs.update_add_htlcs.len(), 1);
@@ -1077,3 +1078,2 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-
expect_pending_htlcs_forwardable!(nodes[2]);
diff --git a/lightning/src/ln/channel.rs b/lightning/src/ln/channel.rs
index 19e28d4a..26725111 100644
--- a/lightning/src/ln/channel.rs
+++ b/lightning/src/ln/channel.rs
@@ -3976,10 +3976,14 @@ impl<Signer: Sign> Channel<Signer> {
/// send_htlc_and_commit instead cause you'll want both messages at once.
-	/// This returns an option instead of a pure UpdateAddHTLC as we may be in a state where we
-	/// cannot add HTLCs on the wire.
-	/// In cases where we're waiting on the remote peer to send us a revoke_and_ack, if we did, we
-	/// wouldn't be able to determine what they actually ACK'ed when we do receive the
-	/// revoke_and_ack.
-	/// In cases where we're marked MonitorUpdateFailed, we cannot commit to a new state as we may
-	/// not yet have sent the previous commitment update messages and will need to regenerate them.
-	/// You MUST call send_commitment prior to any other calls on this Channel
+	///
+	/// This returns an optional UpdateAddHTLC as we may be in a state where we cannot add HTLCs on
+	/// the wire:
+	/// * In cases where we're waiting on the remote peer to send us a revoke_and_ack, we
+	/// wouldn't be able to determine what they actually ACK'ed if we have two sets of updates
+	/// awaiting ACK.
+	/// * In cases where we're marked MonitorUpdateFailed, we cannot commit to a new state as we
+	/// may not yet have sent the previous commitment update messages and will need to regenerate
+	/// them.
+	///
+	/// You MUST call send_commitment prior to calling any other methods on this Channel!
+	///
/// If an Err is returned, it's a ChannelError::Ignore!
$

[TheBlueMatt]

We use Channel::is_live() to gate inclusion of a channel in
ChannelManager::list_usable_channels() and when sending an
HTLC to select whether a channel is available for
forwarding through/sending to.

In both of these cases, we almost certainly want
Channel::is_live() to include channels which are simply pending a
monitor update, as some clients may update monitors asynchronously,
thus any rejection of HTLCs based on a monitor update still pending
causing a race condition.

After #851, we always ensure any holding cells are free'd when
sending P2P messages, making this much more trivially correct -
instead of having to ensure that we always have a matching holding
cell free any time we add something to the holding cell, we can
simply rely on the fact that it always happens.

Fixes#661.

This should make #949's tests a bit easier to implement.

[codecov]

Codecov Report

Merging #954 (0534e8b) into main (2940099) will increase coverage by 1.47%.
The diff coverage is 91.30%.

❗ Current head 0534e8b differs from pull request most recent head b58c884. Consider uploading reports for the commit b58c884 to get more accurate results

@@ Coverage Diff @@## main #954 +/- ##
==========================================
+ Coverage 90.59% 92.06% +1.47% 
==========================================
Files 60 60 Lines 30423 39444 +9021 ==========================================
+ Hits 27561 36314 +8753 - Misses 2862 3130 +268 

Impacted Files	Coverage Δ
lightning/src/ln/channelmanager.rs	87.18% <ø> (+3.27%)	⬆️
lightning/src/ln/channel.rs	92.86% <87.50%> (+4.57%)	⬆️
lightning/src/ln/chanmon_update_fail_tests.rs	97.60% <91.58%> (-0.19%)	⬇️
lightning/src/ln/wire.rs	60.52% <0.00%> (-3.58%)	⬇️
lightning/src/util/macro_logger.rs	87.87% <0.00%> (-1.19%)	⬇️
lightning/src/ln/functional_test_utils.rs	94.79% <0.00%> (-0.03%)	⬇️
lightning/src/ln/reorg_tests.rs	100.00% <0.00%> (+0.37%)	⬆️
lightning/src/chain/chainmonitor.rs	96.21% <0.00%> (+0.41%)	⬆️
lightning/src/util/ser.rs	91.70% <0.00%> (+0.43%)	⬆️
... and 20 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2940099...b58c884. Read the comment docs.

[TheBlueMatt]

Addressed a few comments left on other PRs, including #949 (comment)

[ariard]

Just need to fix send_htlc doc I believe, otherwise good to me

[ariard]

This comment sounds weird, I still think we should be able to receive a HTLC even if the forwarding channel is knock-out, though we don't currently in decode_update_add_htlc_onion. Maybe possible after #680.

[TheBlueMatt]

Right, I suppose its reasonable to accept an HTLC for forwarding to a channel which is disconnected currently if you're a special type of node that can make the channel become connected soon (of course for a general purpose node we should definitely fail). There isn't a lot of harm in waiting to fail until the payment gets to the send_htlc call (instead of doing it immediately upon receipt), so I think I agree we should just drop it (but keep this return).

All that to say, I don't think anything needs to change in this PR, correct? The comment is still true today, though I agree we could change it in a followup and should change it after #680.

[ariard]

Yeah I just believe this forwarding policy makes really sense if the next hop is owned by a mobile client, with a clear agreement "I'm going to be offline 99% of my time, please cache my HTLC" ? Or at least it would be worthy as an experimentation.

Right, it's more a good-place-to-clean-once-we-have-680.

[ariard]

Code Review ACK 8671aca

[TheBlueMatt]

Tagging as 0.0.99 as #949 depends on this and because this would be critical for any async-monitor-update routing node.

[TheBlueMatt]

Squashed with no changes:

$ git diff-tree 8671aca5 eab577c0
$

[jkczyz]

Somethings aren't clear to me when reading the commit message / PR description:

In both of these cases, we almost certainly want
Channel::is_live() to include channels which are simply pending a
monitor update, as some clients may update monitors asynchronously,

Either drop "almost certainly" or explain when this is not the case.

thus any rejection of HTLCs based on a monitor update still pending
causing a race condition.

Reads strange. Start new sentence here and replace "causing" with "causes"?

After #851, we always ensure any holding cells are free'd when
sending P2P messages, making this much more trivially correct -

What is "this" referring to? "this change"?

instead of having to ensure that we always have a matching holding
cell free any time we add something to the holding cell, we can
simply rely on the fact that it always happens.

Unclear to me what is meant by a "matching holding cell" (matching what?) and what "it always happens" is referring to.

[jkczyz]

Is there a TL;DR to summarize the changes to this test to help in review?

[TheBlueMatt]

Because it is no longer the case that receiving an HTLC while we're pending a monitor update restoration causes the HTLC to fail, code which relied on that behavior broke. eg the first code hunk which was removed explicitly delivered an HTLC and expected it to fail, which no longer happens.

The big if-block diff hunk is because the two cases have converged somewhat - we now always have a payment in node[1]'s outbound holding cell.

[jkczyz]

Is there any way to assert the state of the channel rather than examining the log?

[TheBlueMatt]

This line was only moved, not created. the log assert is nice IMO as it checks the specific error, not just that one happened, though the observable state is still checked in that no new message was generated.

[TheBlueMatt]

I rewrote the commit message in the main commit (without changing its contents), let me know what you think.

[jkczyz]

I rewrote the commit message in the main commit (without changing its contents), let me know what you think.

Looks good. Thanks for doing it!

[TheBlueMatt]

Squashed with no changes:

$ git diff-tree -U1 0534e8b9 b58c8843
$

The full diff from the previous ack is still trivial, so will merge after CI:

$ git diff-tree -U1 -b eab577c0 b58c8843
diff --git a/lightning/src/ln/chanmon_update_fail_tests.rs b/lightning/src/ln/chanmon_update_fail_tests.rs
index ac293cc1..73fc5315 100644
--- a/lightning/src/ln/chanmon_update_fail_tests.rs
+++ b/lightning/src/ln/chanmon_update_fail_tests.rs
@@ -908,4 +908,4 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-	// Attempt to forward a third payment but fail due to the second channel being unavailable
-	// for forwarding.
+	// Forward a third payment which will also be added to the holding cell, despite the channel
+	// being paused waiting a monitor update.
let (_, payment_hash_3, payment_secret_3) = get_payment_preimage_hash!(nodes[2]);
@@ -924,2 +924,8 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
+	// Call forward_pending_htlcs and check that the new HTLC was simply added to the holding cell
+	// and not forwarded.
+	expect_pending_htlcs_forwardable!(nodes[1]);
+	check_added_monitors!(nodes[1], 0);
+	assert!(nodes[1].node.get_and_clear_pending_events().is_empty());
+
let (payment_preimage_4, payment_hash_4) = if test_ignore_second_cs {
@@ -942,8 +948,2 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-	// Call forward_pending_htlcs first to make sure we don't have any issues attempting (and
-	// failing) to forward an HTLC while a channel is still awaiting monitor update restoration.
-	expect_pending_htlcs_forwardable!(nodes[1]);
-	check_added_monitors!(nodes[1], 0);
-	assert!(nodes[1].node.get_and_clear_pending_events().is_empty());
-
// Restore monitor updating, ensuring we immediately get a fail-back update and a
@@ -1048,2 +1048,3 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
}
+
assert_eq!(as_cs.update_add_htlcs.len(), 1);
@@ -1077,3 +1078,2 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-
expect_pending_htlcs_forwardable!(nodes[2]);
diff --git a/lightning/src/ln/channel.rs b/lightning/src/ln/channel.rs
index 19e28d4a..26725111 100644
--- a/lightning/src/ln/channel.rs
+++ b/lightning/src/ln/channel.rs
@@ -3976,10 +3976,14 @@ impl<Signer: Sign> Channel<Signer> {
/// send_htlc_and_commit instead cause you'll want both messages at once.
-	/// This returns an option instead of a pure UpdateAddHTLC as we may be in a state where we
-	/// cannot add HTLCs on the wire.
-	/// In cases where we're waiting on the remote peer to send us a revoke_and_ack, if we did, we
-	/// wouldn't be able to determine what they actually ACK'ed when we do receive the
-	/// revoke_and_ack.
-	/// In cases where we're marked MonitorUpdateFailed, we cannot commit to a new state as we may
-	/// not yet have sent the previous commitment update messages and will need to regenerate them.
-	/// You MUST call send_commitment prior to any other calls on this Channel
+	///
+	/// This returns an optional UpdateAddHTLC as we may be in a state where we cannot add HTLCs on
+	/// the wire:
+	/// * In cases where we're waiting on the remote peer to send us a revoke_and_ack, we
+	/// wouldn't be able to determine what they actually ACK'ed if we have two sets of updates
+	/// awaiting ACK.
+	/// * In cases where we're marked MonitorUpdateFailed, we cannot commit to a new state as we
+	/// may not yet have sent the previous commitment update messages and will need to regenerate
+	/// them.
+	///
+	/// You MUST call send_commitment prior to calling any other methods on this Channel!
+	///
/// If an Err is returned, it's a ChannelError::Ignore!
$

[TheBlueMatt]

We use Channel::is_live() to gate inclusion of a channel in
ChannelManager::list_usable_channels() and when sending an
HTLC to select whether a channel is available for
forwarding through/sending to.

In both of these cases, we almost certainly want
Channel::is_live() to include channels which are simply pending a
monitor update, as some clients may update monitors asynchronously,
thus any rejection of HTLCs based on a monitor update still pending
causing a race condition.

After #851, we always ensure any holding cells are free'd when
sending P2P messages, making this much more trivially correct -
instead of having to ensure that we always have a matching holding
cell free any time we add something to the holding cell, we can
simply rely on the fact that it always happens.

Fixes#661.

This should make #949's tests a bit easier to implement.

[codecov]

Codecov Report

Merging #954 (0534e8b) into main (2940099) will increase coverage by 1.47%.
The diff coverage is 91.30%.

❗ Current head 0534e8b differs from pull request most recent head b58c884. Consider uploading reports for the commit b58c884 to get more accurate results

@@ Coverage Diff @@## main #954 +/- ##
==========================================
+ Coverage 90.59% 92.06% +1.47% 
==========================================
Files 60 60 Lines 30423 39444 +9021 ==========================================
+ Hits 27561 36314 +8753 - Misses 2862 3130 +268 

Impacted Files	Coverage Δ
lightning/src/ln/channelmanager.rs	87.18% <ø> (+3.27%)	⬆️
lightning/src/ln/channel.rs	92.86% <87.50%> (+4.57%)	⬆️
lightning/src/ln/chanmon_update_fail_tests.rs	97.60% <91.58%> (-0.19%)	⬇️
lightning/src/ln/wire.rs	60.52% <0.00%> (-3.58%)	⬇️
lightning/src/util/macro_logger.rs	87.87% <0.00%> (-1.19%)	⬇️
lightning/src/ln/functional_test_utils.rs	94.79% <0.00%> (-0.03%)	⬇️
lightning/src/ln/reorg_tests.rs	100.00% <0.00%> (+0.37%)	⬆️
lightning/src/chain/chainmonitor.rs	96.21% <0.00%> (+0.41%)	⬆️
lightning/src/util/ser.rs	91.70% <0.00%> (+0.43%)	⬆️
... and 20 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2940099...b58c884. Read the comment docs.

[TheBlueMatt]

Addressed a few comments left on other PRs, including #949 (comment)

[ariard]

Just need to fix send_htlc doc I believe, otherwise good to me

[ariard]

This comment sounds weird, I still think we should be able to receive a HTLC even if the forwarding channel is knock-out, though we don't currently in decode_update_add_htlc_onion. Maybe possible after #680.

[TheBlueMatt]

Right, I suppose its reasonable to accept an HTLC for forwarding to a channel which is disconnected currently if you're a special type of node that can make the channel become connected soon (of course for a general purpose node we should definitely fail). There isn't a lot of harm in waiting to fail until the payment gets to the send_htlc call (instead of doing it immediately upon receipt), so I think I agree we should just drop it (but keep this return).

All that to say, I don't think anything needs to change in this PR, correct? The comment is still true today, though I agree we could change it in a followup and should change it after #680.

[ariard]

Yeah I just believe this forwarding policy makes really sense if the next hop is owned by a mobile client, with a clear agreement "I'm going to be offline 99% of my time, please cache my HTLC" ? Or at least it would be worthy as an experimentation.

Right, it's more a good-place-to-clean-once-we-have-680.

[ariard]

Code Review ACK 8671aca

[TheBlueMatt]

Tagging as 0.0.99 as #949 depends on this and because this would be critical for any async-monitor-update routing node.

[TheBlueMatt]

Squashed with no changes:

$ git diff-tree 8671aca5 eab577c0
$

[jkczyz]

Somethings aren't clear to me when reading the commit message / PR description:

In both of these cases, we almost certainly want
Channel::is_live() to include channels which are simply pending a
monitor update, as some clients may update monitors asynchronously,

Either drop "almost certainly" or explain when this is not the case.

thus any rejection of HTLCs based on a monitor update still pending
causing a race condition.

Reads strange. Start new sentence here and replace "causing" with "causes"?

After #851, we always ensure any holding cells are free'd when
sending P2P messages, making this much more trivially correct -

What is "this" referring to? "this change"?

instead of having to ensure that we always have a matching holding
cell free any time we add something to the holding cell, we can
simply rely on the fact that it always happens.

Unclear to me what is meant by a "matching holding cell" (matching what?) and what "it always happens" is referring to.

[jkczyz]

Is there a TL;DR to summarize the changes to this test to help in review?

[TheBlueMatt]

Because it is no longer the case that receiving an HTLC while we're pending a monitor update restoration causes the HTLC to fail, code which relied on that behavior broke. eg the first code hunk which was removed explicitly delivered an HTLC and expected it to fail, which no longer happens.

The big if-block diff hunk is because the two cases have converged somewhat - we now always have a payment in node[1]'s outbound holding cell.

[jkczyz]

Is there any way to assert the state of the channel rather than examining the log?

[TheBlueMatt]

This line was only moved, not created. the log assert is nice IMO as it checks the specific error, not just that one happened, though the observable state is still checked in that no new message was generated.

[TheBlueMatt]

I rewrote the commit message in the main commit (without changing its contents), let me know what you think.

[jkczyz]

I rewrote the commit message in the main commit (without changing its contents), let me know what you think.

Looks good. Thanks for doing it!

[TheBlueMatt]

Squashed with no changes:

$ git diff-tree -U1 0534e8b9 b58c8843
$

The full diff from the previous ack is still trivial, so will merge after CI:

$ git diff-tree -U1 -b eab577c0 b58c8843
diff --git a/lightning/src/ln/chanmon_update_fail_tests.rs b/lightning/src/ln/chanmon_update_fail_tests.rs
index ac293cc1..73fc5315 100644
--- a/lightning/src/ln/chanmon_update_fail_tests.rs
+++ b/lightning/src/ln/chanmon_update_fail_tests.rs
@@ -908,4 +908,4 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-	// Attempt to forward a third payment but fail due to the second channel being unavailable
-	// for forwarding.
+	// Forward a third payment which will also be added to the holding cell, despite the channel
+	// being paused waiting a monitor update.
let (_, payment_hash_3, payment_secret_3) = get_payment_preimage_hash!(nodes[2]);
@@ -924,2 +924,8 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
+	// Call forward_pending_htlcs and check that the new HTLC was simply added to the holding cell
+	// and not forwarded.
+	expect_pending_htlcs_forwardable!(nodes[1]);
+	check_added_monitors!(nodes[1], 0);
+	assert!(nodes[1].node.get_and_clear_pending_events().is_empty());
+
let (payment_preimage_4, payment_hash_4) = if test_ignore_second_cs {
@@ -942,8 +948,2 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-	// Call forward_pending_htlcs first to make sure we don't have any issues attempting (and
-	// failing) to forward an HTLC while a channel is still awaiting monitor update restoration.
-	expect_pending_htlcs_forwardable!(nodes[1]);
-	check_added_monitors!(nodes[1], 0);
-	assert!(nodes[1].node.get_and_clear_pending_events().is_empty());
-
// Restore monitor updating, ensuring we immediately get a fail-back update and a
@@ -1048,2 +1048,3 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
}
+
assert_eq!(as_cs.update_add_htlcs.len(), 1);
@@ -1077,3 +1078,2 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-
expect_pending_htlcs_forwardable!(nodes[2]);
diff --git a/lightning/src/ln/channel.rs b/lightning/src/ln/channel.rs
index 19e28d4a..26725111 100644
--- a/lightning/src/ln/channel.rs
+++ b/lightning/src/ln/channel.rs
@@ -3976,10 +3976,14 @@ impl<Signer: Sign> Channel<Signer> {
/// send_htlc_and_commit instead cause you'll want both messages at once.
-	/// This returns an option instead of a pure UpdateAddHTLC as we may be in a state where we
-	/// cannot add HTLCs on the wire.
-	/// In cases where we're waiting on the remote peer to send us a revoke_and_ack, if we did, we
-	/// wouldn't be able to determine what they actually ACK'ed when we do receive the
-	/// revoke_and_ack.
-	/// In cases where we're marked MonitorUpdateFailed, we cannot commit to a new state as we may
-	/// not yet have sent the previous commitment update messages and will need to regenerate them.
-	/// You MUST call send_commitment prior to any other calls on this Channel
+	///
+	/// This returns an optional UpdateAddHTLC as we may be in a state where we cannot add HTLCs on
+	/// the wire:
+	/// * In cases where we're waiting on the remote peer to send us a revoke_and_ack, we
+	/// wouldn't be able to determine what they actually ACK'ed if we have two sets of updates
+	/// awaiting ACK.
+	/// * In cases where we're marked MonitorUpdateFailed, we cannot commit to a new state as we
+	/// may not yet have sent the previous commitment update messages and will need to regenerate
+	/// them.
+	///
+	/// You MUST call send_commitment prior to calling any other methods on this Channel!
+	///
/// If an Err is returned, it's a ChannelError::Ignore!
$

[TheBlueMatt]

We use Channel::is_live() to gate inclusion of a channel in
ChannelManager::list_usable_channels() and when sending an
HTLC to select whether a channel is available for
forwarding through/sending to.

In both of these cases, we almost certainly want
Channel::is_live() to include channels which are simply pending a
monitor update, as some clients may update monitors asynchronously,
thus any rejection of HTLCs based on a monitor update still pending
causing a race condition.

After #851, we always ensure any holding cells are free'd when
sending P2P messages, making this much more trivially correct -
instead of having to ensure that we always have a matching holding
cell free any time we add something to the holding cell, we can
simply rely on the fact that it always happens.

Fixes#661.

This should make #949's tests a bit easier to implement.

[codecov]

Codecov Report

Merging #954 (0534e8b) into main (2940099) will increase coverage by 1.47%.
The diff coverage is 91.30%.

❗ Current head 0534e8b differs from pull request most recent head b58c884. Consider uploading reports for the commit b58c884 to get more accurate results

@@ Coverage Diff @@## main #954 +/- ##
==========================================
+ Coverage 90.59% 92.06% +1.47% 
==========================================
Files 60 60 Lines 30423 39444 +9021 ==========================================
+ Hits 27561 36314 +8753 - Misses 2862 3130 +268 

Impacted Files	Coverage Δ
lightning/src/ln/channelmanager.rs	87.18% <ø> (+3.27%)	⬆️
lightning/src/ln/channel.rs	92.86% <87.50%> (+4.57%)	⬆️
lightning/src/ln/chanmon_update_fail_tests.rs	97.60% <91.58%> (-0.19%)	⬇️
lightning/src/ln/wire.rs	60.52% <0.00%> (-3.58%)	⬇️
lightning/src/util/macro_logger.rs	87.87% <0.00%> (-1.19%)	⬇️
lightning/src/ln/functional_test_utils.rs	94.79% <0.00%> (-0.03%)	⬇️
lightning/src/ln/reorg_tests.rs	100.00% <0.00%> (+0.37%)	⬆️
lightning/src/chain/chainmonitor.rs	96.21% <0.00%> (+0.41%)	⬆️
lightning/src/util/ser.rs	91.70% <0.00%> (+0.43%)	⬆️
... and 20 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2940099...b58c884. Read the comment docs.

[TheBlueMatt]

Addressed a few comments left on other PRs, including #949 (comment)

[ariard]

Just need to fix send_htlc doc I believe, otherwise good to me

[ariard]

This comment sounds weird, I still think we should be able to receive a HTLC even if the forwarding channel is knock-out, though we don't currently in decode_update_add_htlc_onion. Maybe possible after #680.

[TheBlueMatt]

Right, I suppose its reasonable to accept an HTLC for forwarding to a channel which is disconnected currently if you're a special type of node that can make the channel become connected soon (of course for a general purpose node we should definitely fail). There isn't a lot of harm in waiting to fail until the payment gets to the send_htlc call (instead of doing it immediately upon receipt), so I think I agree we should just drop it (but keep this return).

All that to say, I don't think anything needs to change in this PR, correct? The comment is still true today, though I agree we could change it in a followup and should change it after #680.

[ariard]

Yeah I just believe this forwarding policy makes really sense if the next hop is owned by a mobile client, with a clear agreement "I'm going to be offline 99% of my time, please cache my HTLC" ? Or at least it would be worthy as an experimentation.

Right, it's more a good-place-to-clean-once-we-have-680.

[ariard]

Code Review ACK 8671aca

[TheBlueMatt]

Tagging as 0.0.99 as #949 depends on this and because this would be critical for any async-monitor-update routing node.

[TheBlueMatt]

Squashed with no changes:

$ git diff-tree 8671aca5 eab577c0
$

[jkczyz]

Somethings aren't clear to me when reading the commit message / PR description:

In both of these cases, we almost certainly want
Channel::is_live() to include channels which are simply pending a
monitor update, as some clients may update monitors asynchronously,

Either drop "almost certainly" or explain when this is not the case.

thus any rejection of HTLCs based on a monitor update still pending
causing a race condition.

Reads strange. Start new sentence here and replace "causing" with "causes"?

After #851, we always ensure any holding cells are free'd when
sending P2P messages, making this much more trivially correct -

What is "this" referring to? "this change"?

instead of having to ensure that we always have a matching holding
cell free any time we add something to the holding cell, we can
simply rely on the fact that it always happens.

Unclear to me what is meant by a "matching holding cell" (matching what?) and what "it always happens" is referring to.

[jkczyz]

Is there a TL;DR to summarize the changes to this test to help in review?

[TheBlueMatt]

Because it is no longer the case that receiving an HTLC while we're pending a monitor update restoration causes the HTLC to fail, code which relied on that behavior broke. eg the first code hunk which was removed explicitly delivered an HTLC and expected it to fail, which no longer happens.

The big if-block diff hunk is because the two cases have converged somewhat - we now always have a payment in node[1]'s outbound holding cell.

[jkczyz]

Is there any way to assert the state of the channel rather than examining the log?

[TheBlueMatt]

This line was only moved, not created. the log assert is nice IMO as it checks the specific error, not just that one happened, though the observable state is still checked in that no new message was generated.

[TheBlueMatt]

I rewrote the commit message in the main commit (without changing its contents), let me know what you think.

[jkczyz]

I rewrote the commit message in the main commit (without changing its contents), let me know what you think.

Looks good. Thanks for doing it!

[TheBlueMatt]

Squashed with no changes:

$ git diff-tree -U1 0534e8b9 b58c8843
$

The full diff from the previous ack is still trivial, so will merge after CI:

$ git diff-tree -U1 -b eab577c0 b58c8843
diff --git a/lightning/src/ln/chanmon_update_fail_tests.rs b/lightning/src/ln/chanmon_update_fail_tests.rs
index ac293cc1..73fc5315 100644
--- a/lightning/src/ln/chanmon_update_fail_tests.rs
+++ b/lightning/src/ln/chanmon_update_fail_tests.rs
@@ -908,4 +908,4 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-	// Attempt to forward a third payment but fail due to the second channel being unavailable
-	// for forwarding.
+	// Forward a third payment which will also be added to the holding cell, despite the channel
+	// being paused waiting a monitor update.
let (_, payment_hash_3, payment_secret_3) = get_payment_preimage_hash!(nodes[2]);
@@ -924,2 +924,8 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
+	// Call forward_pending_htlcs and check that the new HTLC was simply added to the holding cell
+	// and not forwarded.
+	expect_pending_htlcs_forwardable!(nodes[1]);
+	check_added_monitors!(nodes[1], 0);
+	assert!(nodes[1].node.get_and_clear_pending_events().is_empty());
+
let (payment_preimage_4, payment_hash_4) = if test_ignore_second_cs {
@@ -942,8 +948,2 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-	// Call forward_pending_htlcs first to make sure we don't have any issues attempting (and
-	// failing) to forward an HTLC while a channel is still awaiting monitor update restoration.
-	expect_pending_htlcs_forwardable!(nodes[1]);
-	check_added_monitors!(nodes[1], 0);
-	assert!(nodes[1].node.get_and_clear_pending_events().is_empty());
-
// Restore monitor updating, ensuring we immediately get a fail-back update and a
@@ -1048,2 +1048,3 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
}
+
assert_eq!(as_cs.update_add_htlcs.len(), 1);
@@ -1077,3 +1078,2 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-
expect_pending_htlcs_forwardable!(nodes[2]);
diff --git a/lightning/src/ln/channel.rs b/lightning/src/ln/channel.rs
index 19e28d4a..26725111 100644
--- a/lightning/src/ln/channel.rs
+++ b/lightning/src/ln/channel.rs
@@ -3976,10 +3976,14 @@ impl<Signer: Sign> Channel<Signer> {
/// send_htlc_and_commit instead cause you'll want both messages at once.
-	/// This returns an option instead of a pure UpdateAddHTLC as we may be in a state where we
-	/// cannot add HTLCs on the wire.
-	/// In cases where we're waiting on the remote peer to send us a revoke_and_ack, if we did, we
-	/// wouldn't be able to determine what they actually ACK'ed when we do receive the
-	/// revoke_and_ack.
-	/// In cases where we're marked MonitorUpdateFailed, we cannot commit to a new state as we may
-	/// not yet have sent the previous commitment update messages and will need to regenerate them.
-	/// You MUST call send_commitment prior to any other calls on this Channel
+	///
+	/// This returns an optional UpdateAddHTLC as we may be in a state where we cannot add HTLCs on
+	/// the wire:
+	/// * In cases where we're waiting on the remote peer to send us a revoke_and_ack, we
+	/// wouldn't be able to determine what they actually ACK'ed if we have two sets of updates
+	/// awaiting ACK.
+	/// * In cases where we're marked MonitorUpdateFailed, we cannot commit to a new state as we
+	/// may not yet have sent the previous commitment update messages and will need to regenerate
+	/// them.
+	///
+	/// You MUST call send_commitment prior to calling any other methods on this Channel!
+	///
/// If an Err is returned, it's a ChannelError::Ignore!
$

[TheBlueMatt]

We use Channel::is_live() to gate inclusion of a channel in
ChannelManager::list_usable_channels() and when sending an
HTLC to select whether a channel is available for
forwarding through/sending to.

In both of these cases, we almost certainly want
Channel::is_live() to include channels which are simply pending a
monitor update, as some clients may update monitors asynchronously,
thus any rejection of HTLCs based on a monitor update still pending
causing a race condition.

After #851, we always ensure any holding cells are free'd when
sending P2P messages, making this much more trivially correct -
instead of having to ensure that we always have a matching holding
cell free any time we add something to the holding cell, we can
simply rely on the fact that it always happens.

Fixes#661.

This should make #949's tests a bit easier to implement.

[codecov]

Codecov Report

Merging #954 (0534e8b) into main (2940099) will increase coverage by 1.47%.
The diff coverage is 91.30%.

❗ Current head 0534e8b differs from pull request most recent head b58c884. Consider uploading reports for the commit b58c884 to get more accurate results

@@ Coverage Diff @@## main #954 +/- ##
==========================================
+ Coverage 90.59% 92.06% +1.47% 
==========================================
Files 60 60 Lines 30423 39444 +9021 ==========================================
+ Hits 27561 36314 +8753 - Misses 2862 3130 +268 

Impacted Files	Coverage Δ
lightning/src/ln/channelmanager.rs	87.18% <ø> (+3.27%)	⬆️
lightning/src/ln/channel.rs	92.86% <87.50%> (+4.57%)	⬆️
lightning/src/ln/chanmon_update_fail_tests.rs	97.60% <91.58%> (-0.19%)	⬇️
lightning/src/ln/wire.rs	60.52% <0.00%> (-3.58%)	⬇️
lightning/src/util/macro_logger.rs	87.87% <0.00%> (-1.19%)	⬇️
lightning/src/ln/functional_test_utils.rs	94.79% <0.00%> (-0.03%)	⬇️
lightning/src/ln/reorg_tests.rs	100.00% <0.00%> (+0.37%)	⬆️
lightning/src/chain/chainmonitor.rs	96.21% <0.00%> (+0.41%)	⬆️
lightning/src/util/ser.rs	91.70% <0.00%> (+0.43%)	⬆️
... and 20 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2940099...b58c884. Read the comment docs.

[TheBlueMatt]

Addressed a few comments left on other PRs, including #949 (comment)

[ariard]

Just need to fix send_htlc doc I believe, otherwise good to me

[ariard]

This comment sounds weird, I still think we should be able to receive a HTLC even if the forwarding channel is knock-out, though we don't currently in decode_update_add_htlc_onion. Maybe possible after #680.

[TheBlueMatt]

Right, I suppose its reasonable to accept an HTLC for forwarding to a channel which is disconnected currently if you're a special type of node that can make the channel become connected soon (of course for a general purpose node we should definitely fail). There isn't a lot of harm in waiting to fail until the payment gets to the send_htlc call (instead of doing it immediately upon receipt), so I think I agree we should just drop it (but keep this return).

All that to say, I don't think anything needs to change in this PR, correct? The comment is still true today, though I agree we could change it in a followup and should change it after #680.

[ariard]

Yeah I just believe this forwarding policy makes really sense if the next hop is owned by a mobile client, with a clear agreement "I'm going to be offline 99% of my time, please cache my HTLC" ? Or at least it would be worthy as an experimentation.

Right, it's more a good-place-to-clean-once-we-have-680.

[ariard]

Code Review ACK 8671aca

[TheBlueMatt]

Tagging as 0.0.99 as #949 depends on this and because this would be critical for any async-monitor-update routing node.

[TheBlueMatt]

Squashed with no changes:

$ git diff-tree 8671aca5 eab577c0
$

[jkczyz]

Somethings aren't clear to me when reading the commit message / PR description:

In both of these cases, we almost certainly want
Channel::is_live() to include channels which are simply pending a
monitor update, as some clients may update monitors asynchronously,

Either drop "almost certainly" or explain when this is not the case.

thus any rejection of HTLCs based on a monitor update still pending
causing a race condition.

Reads strange. Start new sentence here and replace "causing" with "causes"?

After #851, we always ensure any holding cells are free'd when
sending P2P messages, making this much more trivially correct -

What is "this" referring to? "this change"?

instead of having to ensure that we always have a matching holding
cell free any time we add something to the holding cell, we can
simply rely on the fact that it always happens.

Unclear to me what is meant by a "matching holding cell" (matching what?) and what "it always happens" is referring to.

[jkczyz]

Is there a TL;DR to summarize the changes to this test to help in review?

[TheBlueMatt]

Because it is no longer the case that receiving an HTLC while we're pending a monitor update restoration causes the HTLC to fail, code which relied on that behavior broke. eg the first code hunk which was removed explicitly delivered an HTLC and expected it to fail, which no longer happens.

The big if-block diff hunk is because the two cases have converged somewhat - we now always have a payment in node[1]'s outbound holding cell.

[jkczyz]

Is there any way to assert the state of the channel rather than examining the log?

[TheBlueMatt]

This line was only moved, not created. the log assert is nice IMO as it checks the specific error, not just that one happened, though the observable state is still checked in that no new message was generated.

[TheBlueMatt]

I rewrote the commit message in the main commit (without changing its contents), let me know what you think.

[jkczyz]

I rewrote the commit message in the main commit (without changing its contents), let me know what you think.

Looks good. Thanks for doing it!

[TheBlueMatt]

Squashed with no changes:

$ git diff-tree -U1 0534e8b9 b58c8843
$

The full diff from the previous ack is still trivial, so will merge after CI:

$ git diff-tree -U1 -b eab577c0 b58c8843
diff --git a/lightning/src/ln/chanmon_update_fail_tests.rs b/lightning/src/ln/chanmon_update_fail_tests.rs
index ac293cc1..73fc5315 100644
--- a/lightning/src/ln/chanmon_update_fail_tests.rs
+++ b/lightning/src/ln/chanmon_update_fail_tests.rs
@@ -908,4 +908,4 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-	// Attempt to forward a third payment but fail due to the second channel being unavailable
-	// for forwarding.
+	// Forward a third payment which will also be added to the holding cell, despite the channel
+	// being paused waiting a monitor update.
let (_, payment_hash_3, payment_secret_3) = get_payment_preimage_hash!(nodes[2]);
@@ -924,2 +924,8 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
+	// Call forward_pending_htlcs and check that the new HTLC was simply added to the holding cell
+	// and not forwarded.
+	expect_pending_htlcs_forwardable!(nodes[1]);
+	check_added_monitors!(nodes[1], 0);
+	assert!(nodes[1].node.get_and_clear_pending_events().is_empty());
+
let (payment_preimage_4, payment_hash_4) = if test_ignore_second_cs {
@@ -942,8 +948,2 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-	// Call forward_pending_htlcs first to make sure we don't have any issues attempting (and
-	// failing) to forward an HTLC while a channel is still awaiting monitor update restoration.
-	expect_pending_htlcs_forwardable!(nodes[1]);
-	check_added_monitors!(nodes[1], 0);
-	assert!(nodes[1].node.get_and_clear_pending_events().is_empty());
-
// Restore monitor updating, ensuring we immediately get a fail-back update and a
@@ -1048,2 +1048,3 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
}
+
assert_eq!(as_cs.update_add_htlcs.len(), 1);
@@ -1077,3 +1078,2 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-
expect_pending_htlcs_forwardable!(nodes[2]);
diff --git a/lightning/src/ln/channel.rs b/lightning/src/ln/channel.rs
index 19e28d4a..26725111 100644
--- a/lightning/src/ln/channel.rs
+++ b/lightning/src/ln/channel.rs
@@ -3976,10 +3976,14 @@ impl<Signer: Sign> Channel<Signer> {
/// send_htlc_and_commit instead cause you'll want both messages at once.
-	/// This returns an option instead of a pure UpdateAddHTLC as we may be in a state where we
-	/// cannot add HTLCs on the wire.
-	/// In cases where we're waiting on the remote peer to send us a revoke_and_ack, if we did, we
-	/// wouldn't be able to determine what they actually ACK'ed when we do receive the
-	/// revoke_and_ack.
-	/// In cases where we're marked MonitorUpdateFailed, we cannot commit to a new state as we may
-	/// not yet have sent the previous commitment update messages and will need to regenerate them.
-	/// You MUST call send_commitment prior to any other calls on this Channel
+	///
+	/// This returns an optional UpdateAddHTLC as we may be in a state where we cannot add HTLCs on
+	/// the wire:
+	/// * In cases where we're waiting on the remote peer to send us a revoke_and_ack, we
+	/// wouldn't be able to determine what they actually ACK'ed if we have two sets of updates
+	/// awaiting ACK.
+	/// * In cases where we're marked MonitorUpdateFailed, we cannot commit to a new state as we
+	/// may not yet have sent the previous commitment update messages and will need to regenerate
+	/// them.
+	///
+	/// You MUST call send_commitment prior to calling any other methods on this Channel!
+	///
/// If an Err is returned, it's a ChannelError::Ignore!
$

[TheBlueMatt]

We use Channel::is_live() to gate inclusion of a channel in
ChannelManager::list_usable_channels() and when sending an
HTLC to select whether a channel is available for
forwarding through/sending to.

In both of these cases, we almost certainly want
Channel::is_live() to include channels which are simply pending a
monitor update, as some clients may update monitors asynchronously,
thus any rejection of HTLCs based on a monitor update still pending
causing a race condition.

After #851, we always ensure any holding cells are free'd when
sending P2P messages, making this much more trivially correct -
instead of having to ensure that we always have a matching holding
cell free any time we add something to the holding cell, we can
simply rely on the fact that it always happens.

Fixes#661.

This should make #949's tests a bit easier to implement.

[codecov]

Codecov Report

Merging #954 (0534e8b) into main (2940099) will increase coverage by 1.47%.
The diff coverage is 91.30%.

❗ Current head 0534e8b differs from pull request most recent head b58c884. Consider uploading reports for the commit b58c884 to get more accurate results

@@ Coverage Diff @@## main #954 +/- ##
==========================================
+ Coverage 90.59% 92.06% +1.47% 
==========================================
Files 60 60 Lines 30423 39444 +9021 ==========================================
+ Hits 27561 36314 +8753 - Misses 2862 3130 +268 

Impacted Files	Coverage Δ
lightning/src/ln/channelmanager.rs	87.18% <ø> (+3.27%)	⬆️
lightning/src/ln/channel.rs	92.86% <87.50%> (+4.57%)	⬆️
lightning/src/ln/chanmon_update_fail_tests.rs	97.60% <91.58%> (-0.19%)	⬇️
lightning/src/ln/wire.rs	60.52% <0.00%> (-3.58%)	⬇️
lightning/src/util/macro_logger.rs	87.87% <0.00%> (-1.19%)	⬇️
lightning/src/ln/functional_test_utils.rs	94.79% <0.00%> (-0.03%)	⬇️
lightning/src/ln/reorg_tests.rs	100.00% <0.00%> (+0.37%)	⬆️
lightning/src/chain/chainmonitor.rs	96.21% <0.00%> (+0.41%)	⬆️
lightning/src/util/ser.rs	91.70% <0.00%> (+0.43%)	⬆️
... and 20 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2940099...b58c884. Read the comment docs.

[TheBlueMatt]

Addressed a few comments left on other PRs, including #949 (comment)

[ariard]

Just need to fix send_htlc doc I believe, otherwise good to me

[ariard]

This comment sounds weird, I still think we should be able to receive a HTLC even if the forwarding channel is knock-out, though we don't currently in decode_update_add_htlc_onion. Maybe possible after #680.

[TheBlueMatt]

Right, I suppose its reasonable to accept an HTLC for forwarding to a channel which is disconnected currently if you're a special type of node that can make the channel become connected soon (of course for a general purpose node we should definitely fail). There isn't a lot of harm in waiting to fail until the payment gets to the send_htlc call (instead of doing it immediately upon receipt), so I think I agree we should just drop it (but keep this return).

All that to say, I don't think anything needs to change in this PR, correct? The comment is still true today, though I agree we could change it in a followup and should change it after #680.

[ariard]

Yeah I just believe this forwarding policy makes really sense if the next hop is owned by a mobile client, with a clear agreement "I'm going to be offline 99% of my time, please cache my HTLC" ? Or at least it would be worthy as an experimentation.

Right, it's more a good-place-to-clean-once-we-have-680.

[ariard]

Code Review ACK 8671aca

[TheBlueMatt]

Tagging as 0.0.99 as #949 depends on this and because this would be critical for any async-monitor-update routing node.

[TheBlueMatt]

Squashed with no changes:

$ git diff-tree 8671aca5 eab577c0
$

[jkczyz]

Somethings aren't clear to me when reading the commit message / PR description:

In both of these cases, we almost certainly want
Channel::is_live() to include channels which are simply pending a
monitor update, as some clients may update monitors asynchronously,

Either drop "almost certainly" or explain when this is not the case.

thus any rejection of HTLCs based on a monitor update still pending
causing a race condition.

Reads strange. Start new sentence here and replace "causing" with "causes"?

After #851, we always ensure any holding cells are free'd when
sending P2P messages, making this much more trivially correct -

What is "this" referring to? "this change"?

instead of having to ensure that we always have a matching holding
cell free any time we add something to the holding cell, we can
simply rely on the fact that it always happens.

Unclear to me what is meant by a "matching holding cell" (matching what?) and what "it always happens" is referring to.

[jkczyz]

Is there a TL;DR to summarize the changes to this test to help in review?

[TheBlueMatt]

Because it is no longer the case that receiving an HTLC while we're pending a monitor update restoration causes the HTLC to fail, code which relied on that behavior broke. eg the first code hunk which was removed explicitly delivered an HTLC and expected it to fail, which no longer happens.

The big if-block diff hunk is because the two cases have converged somewhat - we now always have a payment in node[1]'s outbound holding cell.

[jkczyz]

Is there any way to assert the state of the channel rather than examining the log?

[TheBlueMatt]

This line was only moved, not created. the log assert is nice IMO as it checks the specific error, not just that one happened, though the observable state is still checked in that no new message was generated.

[TheBlueMatt]

I rewrote the commit message in the main commit (without changing its contents), let me know what you think.

[jkczyz]

I rewrote the commit message in the main commit (without changing its contents), let me know what you think.

Looks good. Thanks for doing it!

[TheBlueMatt]

Squashed with no changes:

$ git diff-tree -U1 0534e8b9 b58c8843
$

The full diff from the previous ack is still trivial, so will merge after CI:

$ git diff-tree -U1 -b eab577c0 b58c8843
diff --git a/lightning/src/ln/chanmon_update_fail_tests.rs b/lightning/src/ln/chanmon_update_fail_tests.rs
index ac293cc1..73fc5315 100644
--- a/lightning/src/ln/chanmon_update_fail_tests.rs
+++ b/lightning/src/ln/chanmon_update_fail_tests.rs
@@ -908,4 +908,4 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-	// Attempt to forward a third payment but fail due to the second channel being unavailable
-	// for forwarding.
+	// Forward a third payment which will also be added to the holding cell, despite the channel
+	// being paused waiting a monitor update.
let (_, payment_hash_3, payment_secret_3) = get_payment_preimage_hash!(nodes[2]);
@@ -924,2 +924,8 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
+	// Call forward_pending_htlcs and check that the new HTLC was simply added to the holding cell
+	// and not forwarded.
+	expect_pending_htlcs_forwardable!(nodes[1]);
+	check_added_monitors!(nodes[1], 0);
+	assert!(nodes[1].node.get_and_clear_pending_events().is_empty());
+
let (payment_preimage_4, payment_hash_4) = if test_ignore_second_cs {
@@ -942,8 +948,2 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-	// Call forward_pending_htlcs first to make sure we don't have any issues attempting (and
-	// failing) to forward an HTLC while a channel is still awaiting monitor update restoration.
-	expect_pending_htlcs_forwardable!(nodes[1]);
-	check_added_monitors!(nodes[1], 0);
-	assert!(nodes[1].node.get_and_clear_pending_events().is_empty());
-
// Restore monitor updating, ensuring we immediately get a fail-back update and a
@@ -1048,2 +1048,3 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
}
+
assert_eq!(as_cs.update_add_htlcs.len(), 1);
@@ -1077,3 +1078,2 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-
expect_pending_htlcs_forwardable!(nodes[2]);
diff --git a/lightning/src/ln/channel.rs b/lightning/src/ln/channel.rs
index 19e28d4a..26725111 100644
--- a/lightning/src/ln/channel.rs
+++ b/lightning/src/ln/channel.rs
@@ -3976,10 +3976,14 @@ impl<Signer: Sign> Channel<Signer> {
/// send_htlc_and_commit instead cause you'll want both messages at once.
-	/// This returns an option instead of a pure UpdateAddHTLC as we may be in a state where we
-	/// cannot add HTLCs on the wire.
-	/// In cases where we're waiting on the remote peer to send us a revoke_and_ack, if we did, we
-	/// wouldn't be able to determine what they actually ACK'ed when we do receive the
-	/// revoke_and_ack.
-	/// In cases where we're marked MonitorUpdateFailed, we cannot commit to a new state as we may
-	/// not yet have sent the previous commitment update messages and will need to regenerate them.
-	/// You MUST call send_commitment prior to any other calls on this Channel
+	///
+	/// This returns an optional UpdateAddHTLC as we may be in a state where we cannot add HTLCs on
+	/// the wire:
+	/// * In cases where we're waiting on the remote peer to send us a revoke_and_ack, we
+	/// wouldn't be able to determine what they actually ACK'ed if we have two sets of updates
+	/// awaiting ACK.
+	/// * In cases where we're marked MonitorUpdateFailed, we cannot commit to a new state as we
+	/// may not yet have sent the previous commitment update messages and will need to regenerate
+	/// them.
+	///
+	/// You MUST call send_commitment prior to calling any other methods on this Channel!
+	///
/// If an Err is returned, it's a ChannelError::Ignore!
$

[TheBlueMatt]

We use Channel::is_live() to gate inclusion of a channel in
ChannelManager::list_usable_channels() and when sending an
HTLC to select whether a channel is available for
forwarding through/sending to.

In both of these cases, we almost certainly want
Channel::is_live() to include channels which are simply pending a
monitor update, as some clients may update monitors asynchronously,
thus any rejection of HTLCs based on a monitor update still pending
causing a race condition.

After #851, we always ensure any holding cells are free'd when
sending P2P messages, making this much more trivially correct -
instead of having to ensure that we always have a matching holding
cell free any time we add something to the holding cell, we can
simply rely on the fact that it always happens.

Fixes#661.

This should make #949's tests a bit easier to implement.

[codecov]

Codecov Report

Merging #954 (0534e8b) into main (2940099) will increase coverage by 1.47%.
The diff coverage is 91.30%.

❗ Current head 0534e8b differs from pull request most recent head b58c884. Consider uploading reports for the commit b58c884 to get more accurate results

@@ Coverage Diff @@## main #954 +/- ##
==========================================
+ Coverage 90.59% 92.06% +1.47% 
==========================================
Files 60 60 Lines 30423 39444 +9021 ==========================================
+ Hits 27561 36314 +8753 - Misses 2862 3130 +268 

Impacted Files	Coverage Δ
lightning/src/ln/channelmanager.rs	87.18% <ø> (+3.27%)	⬆️
lightning/src/ln/channel.rs	92.86% <87.50%> (+4.57%)	⬆️
lightning/src/ln/chanmon_update_fail_tests.rs	97.60% <91.58%> (-0.19%)	⬇️
lightning/src/ln/wire.rs	60.52% <0.00%> (-3.58%)	⬇️
lightning/src/util/macro_logger.rs	87.87% <0.00%> (-1.19%)	⬇️
lightning/src/ln/functional_test_utils.rs	94.79% <0.00%> (-0.03%)	⬇️
lightning/src/ln/reorg_tests.rs	100.00% <0.00%> (+0.37%)	⬆️
lightning/src/chain/chainmonitor.rs	96.21% <0.00%> (+0.41%)	⬆️
lightning/src/util/ser.rs	91.70% <0.00%> (+0.43%)	⬆️
... and 20 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2940099...b58c884. Read the comment docs.

[TheBlueMatt]

Addressed a few comments left on other PRs, including #949 (comment)

[ariard]

Just need to fix send_htlc doc I believe, otherwise good to me

[ariard]

This comment sounds weird, I still think we should be able to receive a HTLC even if the forwarding channel is knock-out, though we don't currently in decode_update_add_htlc_onion. Maybe possible after #680.

[TheBlueMatt]

Right, I suppose its reasonable to accept an HTLC for forwarding to a channel which is disconnected currently if you're a special type of node that can make the channel become connected soon (of course for a general purpose node we should definitely fail). There isn't a lot of harm in waiting to fail until the payment gets to the send_htlc call (instead of doing it immediately upon receipt), so I think I agree we should just drop it (but keep this return).

All that to say, I don't think anything needs to change in this PR, correct? The comment is still true today, though I agree we could change it in a followup and should change it after #680.

[ariard]

Yeah I just believe this forwarding policy makes really sense if the next hop is owned by a mobile client, with a clear agreement "I'm going to be offline 99% of my time, please cache my HTLC" ? Or at least it would be worthy as an experimentation.

Right, it's more a good-place-to-clean-once-we-have-680.

[ariard]

Code Review ACK 8671aca

[TheBlueMatt]

Tagging as 0.0.99 as #949 depends on this and because this would be critical for any async-monitor-update routing node.

[TheBlueMatt]

Squashed with no changes:

$ git diff-tree 8671aca5 eab577c0
$

[jkczyz]

Somethings aren't clear to me when reading the commit message / PR description:

In both of these cases, we almost certainly want
Channel::is_live() to include channels which are simply pending a
monitor update, as some clients may update monitors asynchronously,

Either drop "almost certainly" or explain when this is not the case.

thus any rejection of HTLCs based on a monitor update still pending
causing a race condition.

Reads strange. Start new sentence here and replace "causing" with "causes"?

After #851, we always ensure any holding cells are free'd when
sending P2P messages, making this much more trivially correct -

What is "this" referring to? "this change"?

instead of having to ensure that we always have a matching holding
cell free any time we add something to the holding cell, we can
simply rely on the fact that it always happens.

Unclear to me what is meant by a "matching holding cell" (matching what?) and what "it always happens" is referring to.

[jkczyz]

Is there a TL;DR to summarize the changes to this test to help in review?

[TheBlueMatt]

Because it is no longer the case that receiving an HTLC while we're pending a monitor update restoration causes the HTLC to fail, code which relied on that behavior broke. eg the first code hunk which was removed explicitly delivered an HTLC and expected it to fail, which no longer happens.

The big if-block diff hunk is because the two cases have converged somewhat - we now always have a payment in node[1]'s outbound holding cell.

[jkczyz]

Is there any way to assert the state of the channel rather than examining the log?

[TheBlueMatt]

This line was only moved, not created. the log assert is nice IMO as it checks the specific error, not just that one happened, though the observable state is still checked in that no new message was generated.

[TheBlueMatt]

I rewrote the commit message in the main commit (without changing its contents), let me know what you think.

[jkczyz]

I rewrote the commit message in the main commit (without changing its contents), let me know what you think.

Looks good. Thanks for doing it!

[TheBlueMatt]

Squashed with no changes:

$ git diff-tree -U1 0534e8b9 b58c8843
$

The full diff from the previous ack is still trivial, so will merge after CI:

$ git diff-tree -U1 -b eab577c0 b58c8843
diff --git a/lightning/src/ln/chanmon_update_fail_tests.rs b/lightning/src/ln/chanmon_update_fail_tests.rs
index ac293cc1..73fc5315 100644
--- a/lightning/src/ln/chanmon_update_fail_tests.rs
+++ b/lightning/src/ln/chanmon_update_fail_tests.rs
@@ -908,4 +908,4 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-	// Attempt to forward a third payment but fail due to the second channel being unavailable
-	// for forwarding.
+	// Forward a third payment which will also be added to the holding cell, despite the channel
+	// being paused waiting a monitor update.
let (_, payment_hash_3, payment_secret_3) = get_payment_preimage_hash!(nodes[2]);
@@ -924,2 +924,8 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
+	// Call forward_pending_htlcs and check that the new HTLC was simply added to the holding cell
+	// and not forwarded.
+	expect_pending_htlcs_forwardable!(nodes[1]);
+	check_added_monitors!(nodes[1], 0);
+	assert!(nodes[1].node.get_and_clear_pending_events().is_empty());
+
let (payment_preimage_4, payment_hash_4) = if test_ignore_second_cs {
@@ -942,8 +948,2 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-	// Call forward_pending_htlcs first to make sure we don't have any issues attempting (and
-	// failing) to forward an HTLC while a channel is still awaiting monitor update restoration.
-	expect_pending_htlcs_forwardable!(nodes[1]);
-	check_added_monitors!(nodes[1], 0);
-	assert!(nodes[1].node.get_and_clear_pending_events().is_empty());
-
// Restore monitor updating, ensuring we immediately get a fail-back update and a
@@ -1048,2 +1048,3 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
}
+
assert_eq!(as_cs.update_add_htlcs.len(), 1);
@@ -1077,3 +1078,2 @@ fn do_test_monitor_update_fail_raa(test_ignore_second_cs: bool) {
-
expect_pending_htlcs_forwardable!(nodes[2]);
diff --git a/lightning/src/ln/channel.rs b/lightning/src/ln/channel.rs
index 19e28d4a..26725111 100644
--- a/lightning/src/ln/channel.rs
+++ b/lightning/src/ln/channel.rs
@@ -3976,10 +3976,14 @@ impl<Signer: Sign> Channel<Signer> {
/// send_htlc_and_commit instead cause you'll want both messages at once.
-	/// This returns an option instead of a pure UpdateAddHTLC as we may be in a state where we
-	/// cannot add HTLCs on the wire.
-	/// In cases where we're waiting on the remote peer to send us a revoke_and_ack, if we did, we
-	/// wouldn't be able to determine what they actually ACK'ed when we do receive the
-	/// revoke_and_ack.
-	/// In cases where we're marked MonitorUpdateFailed, we cannot commit to a new state as we may
-	/// not yet have sent the previous commitment update messages and will need to regenerate them.
-	/// You MUST call send_commitment prior to any other calls on this Channel
+	///
+	/// This returns an optional UpdateAddHTLC as we may be in a state where we cannot add HTLCs on
+	/// the wire:
+	/// * In cases where we're waiting on the remote peer to send us a revoke_and_ack, we
+	/// wouldn't be able to determine what they actually ACK'ed if we have two sets of updates
+	/// awaiting ACK.
+	/// * In cases where we're marked MonitorUpdateFailed, we cannot commit to a new state as we
+	/// may not yet have sent the previous commitment update messages and will need to regenerate
+	/// them.
+	///
+	/// You MUST call send_commitment prior to calling any other methods on this Channel!
+	///
/// If an Err is returned, it's a ChannelError::Ignore!
$