Document exactly our CLTV sanitization policy for final incoming HTLCs

We want to avoid a third-party channel closure, where a random node
by sending us a payment expiring at current height, would trigger our
onchain logic to close the channel due to a near-expiration.

diff --git a/lightning/src/ln/channel.rs b/lightning/src/ln/channel.rs
index f44109432a581c2f28a7b3797cc187d24546ed31..efc3a151c50fa898f03a2420844661fd204806a6 100644 (file)
--- a/lightning/src/ln/channel.rs
+++ b/lightning/src/ln/channel.rs
@@ -1727,8 +1727,6 @@ impl<ChanSigner: ChannelKeys> Channel<ChanSigner> {
                        return Err(ChannelError::Close("Remote provided CLTV expiry in seconds instead of block height"));
                }
 
-               //TODO: Check msg.cltv_expiry further? Do this in channel manager?
-
                if self.channel_state & ChannelState::LocalShutdownSent as u32 != 0 {
                        if let PendingHTLCStatus::Forward(_) = pending_forward_state {
                                panic!("ChannelManager shouldn't be trying to add a forwardable HTLC after we've started closing");

diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs
index 8086fe3a9601b01d74ee36829fd1c13af659ec40..939b61e4d178ff9bde50b080203acec091c16636 100644 (file)
--- a/lightning/src/ln/channelmanager.rs
+++ b/lightning/src/ln/channelmanager.rs
@@ -1039,7 +1039,11 @@ impl<ChanSigner: ChannelKeys, M: Deref, T: Deref, K: Deref, F: Deref> ChannelMan
 
                                // OUR PAYMENT!
                                // final_expiry_too_soon
-                               if (msg.cltv_expiry as u64) < self.latest_block_height.load(Ordering::Acquire) as u64 + (CLTV_CLAIM_BUFFER + LATENCY_GRACE_PERIOD_BLOCKS) as u64 {
+                               // We have to have some headroom to broadcast on chain if we have the preimage, so make sure we have at least
+                               // HTLC_FAIL_BACK_BUFFER blocks to go.
+                               // Also, ensure that, in the case of an unknown payment hash, our payment logic has enough time to fail the HTLC backward
+                               // before our onchain logic triggers a channel closure (see HTLC_FAIL_BACK_BUFFER rational).
+                               if (msg.cltv_expiry as u64) <= self.latest_block_height.load(Ordering::Acquire) as u64 + HTLC_FAIL_BACK_BUFFER as u64 + 1 {
                                        return_err!("The final CLTV expiry is too soon to handle", 17, &[0;0]);
                                }
                                // final_incorrect_htlc_amount

diff --git a/lightning/src/util/events.rs b/lightning/src/util/events.rs
index ca6355af001e5eb7d05a96a7ffa22548c9340d87..43a2dc3bd6f881ab4ec69241f30f5a2b37651a8e 100644 (file)
--- a/lightning/src/util/events.rs
+++ b/lightning/src/util/events.rs
@@ -51,8 +51,9 @@ pub enum Event {
        },
        /// Indicates we've received money! Just gotta dig out that payment preimage and feed it to
        /// ChannelManager::claim_funds to get it....
-       /// Note that if the preimage is not known or the amount paid is incorrect, you must call
-       /// ChannelManager::fail_htlc_backwards to free up resources for this HTLC.
+       /// Note that if the preimage is not known or the amount paid is incorrect, you should call
+       /// ChannelManager::fail_htlc_backwards to free up resources for this HTLC and avoid
+       /// network congestion.
        /// The amount paid should be considered 'incorrect' when it is less than or more than twice
        /// the amount expected.
        /// If you fail to call either ChannelManager::claim_funds or