feat: allow configurable force-close buffer for claimable HTLCs

Add a `force_close_claimable_htlc_cltv_buffer` field to `ChannelConfig`
that allows users to configure how many blocks before an inbound HTLC's
CLTV expiry the channel will be force-closed to claim it on-chain.

This gives users more tolerance for their own downtime at the expense of
being less tolerant of counterparty unresponsiveness (more force-closes).

Default value remains `CLTV_CLAIM_BUFFER` (36 blocks). Values below the
minimum are rejected via `update_partial_channel_config`.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: okekefrancis112

lightning/src/chain/channelmonitor.rs

@@ -278,9 +278,9 @@ pub(crate) const MAX_BLOCKS_FOR_CONF: u32 = 18;
 /// If an HTLC expires within this many blocks, force-close the channel to broadcast the
 /// HTLC-Success transaction.
 ///
-/// This is two times [`MAX_BLOCKS_FOR_CONF`] as we need to first get the commitment transaction
-/// confirmed, then get an HTLC transaction confirmed.
-pub(crate) const CLTV_CLAIM_BUFFER: u32 = MAX_BLOCKS_FOR_CONF * 2;
+/// This accounts for the time needed to first get the commitment transaction confirmed, then get
+/// an HTLC transaction confirmed.
+pub const CLTV_CLAIM_BUFFER: u32 = MAX_BLOCKS_FOR_CONF * 2;
 /// Number of blocks by which point we expect our counterparty to have seen new blocks on the
 /// network and done a full update_fail_htlc/commitment_signed dance (+ we've updated all our
 /// copies of ChannelMonitors, including watchtowers). We could enforce the contract by failing
@@ -706,6 +706,10 @@ pub(crate) enum ChannelMonitorUpdateStep {
 	ReleasePaymentComplete {
 		htlc: SentHTLCId,
 	},
+	/// Used to update the configurable force-close CLTV buffer for claimable HTLCs.
+	ChannelConfigUpdated {
+		force_close_claimable_htlc_cltv_buffer: u32,
+	},
 }
 
 impl ChannelMonitorUpdateStep {
@@ -723,6 +727,7 @@ impl ChannelMonitorUpdateStep {
 			ChannelMonitorUpdateStep::RenegotiatedFunding { .. } => "RenegotiatedFunding",
 			ChannelMonitorUpdateStep::RenegotiatedFundingLocked { .. } => "RenegotiatedFundingLocked",
 			ChannelMonitorUpdateStep::ReleasePaymentComplete { .. } => "ReleasePaymentComplete",
+			ChannelMonitorUpdateStep::ChannelConfigUpdated { .. } => "ChannelConfigUpdated",
 		}
 	}
 }
@@ -777,6 +782,9 @@ impl_writeable_tlv_based_enum_upgradable!(ChannelMonitorUpdateStep,
 	(12, RenegotiatedFundingLocked) => {
 		(1, funding_txid, required),
 	},
+	(14, ChannelConfigUpdated) => {
+		(1, force_close_claimable_htlc_cltv_buffer, required),
+	},
 );
 
 /// Indicates whether the balance is derived from a cooperative close, a force-close
@@ -1234,6 +1242,10 @@ pub(crate) struct ChannelMonitorImpl<Signer: EcdsaChannelSigner> {
 
 	on_holder_tx_csv: u16,
 
+	/// The configurable number of blocks before an inbound HTLC's CLTV expiry at which we will
+	/// force-close the channel to claim it on-chain. Defaults to [`CLTV_CLAIM_BUFFER`].
+	force_close_claimable_htlc_cltv_buffer: u32,
+
 	commitment_secrets: CounterpartyCommitmentSecrets,
 	/// We cannot identify HTLC-Success or HTLC-Timeout transactions by themselves on the chain.
 	/// Nor can we figure out their commitment numbers without the commitment transaction they are
@@ -1754,6 +1766,7 @@ pub(crate) fn write_chanmon_internal<Signer: EcdsaChannelSigner, W: Writer>(
 		(34, channel_monitor.alternative_funding_confirmed, option),
 		(35, channel_monitor.is_manual_broadcast, required),
 		(37, channel_monitor.funding_seen_onchain, required),
+		(39, channel_monitor.force_close_claimable_htlc_cltv_buffer, (default_value, CLTV_CLAIM_BUFFER)),
 	});
 
 	Ok(())
@@ -1859,6 +1872,7 @@ impl<Signer: EcdsaChannelSigner> ChannelMonitor<Signer> {
 		initial_holder_commitment_tx: HolderCommitmentTransaction, best_block: BestBlock,
 		counterparty_node_id: PublicKey, channel_id: ChannelId,
 		is_manual_broadcast: bool,
+		force_close_claimable_htlc_cltv_buffer: u32,
 	) -> ChannelMonitor<Signer> {
 
 		assert!(commitment_transaction_number_obscure_factor <= (1 << 48));
@@ -1927,6 +1941,11 @@ impl<Signer: EcdsaChannelSigner> ChannelMonitor<Signer> {
 
 			on_holder_tx_csv: counterparty_channel_parameters.selected_contest_delay,
 
+			force_close_claimable_htlc_cltv_buffer: core::cmp::max(
+				force_close_claimable_htlc_cltv_buffer,
+				CLTV_CLAIM_BUFFER,
+			),
+
 			commitment_secrets: CounterpartyCommitmentSecrets::new(),
 			counterparty_commitment_txn_on_chain: new_hash_map(),
 			counterparty_hash_commitment_number: new_hash_map(),
@@ -4280,6 +4299,13 @@ impl<Signer: EcdsaChannelSigner> ChannelMonitorImpl<Signer> {
 					log_trace!(logger, "HTLC {htlc:?} permanently and fully resolved");
 					self.htlcs_resolved_to_user.insert(*htlc);
 				},
+				ChannelMonitorUpdateStep::ChannelConfigUpdated { force_close_claimable_htlc_cltv_buffer } => {
+					log_trace!(logger, "Updating ChannelMonitor force_close_claimable_htlc_cltv_buffer to {}", force_close_claimable_htlc_cltv_buffer);
+					self.force_close_claimable_htlc_cltv_buffer = core::cmp::max(
+						*force_close_claimable_htlc_cltv_buffer,
+						CLTV_CLAIM_BUFFER,
+					);
+				},
 			}
 		}
 
@@ -4312,6 +4338,8 @@ impl<Signer: EcdsaChannelSigner> ChannelMonitorImpl<Signer> {
 				ChannelMonitorUpdateStep::PaymentPreimage { .. } => {},
 				ChannelMonitorUpdateStep::ChannelForceClosed { .. } => {},
 				ChannelMonitorUpdateStep::ReleasePaymentComplete { .. } => {},
+				ChannelMonitorUpdateStep::ChannelConfigUpdated { .. } =>
+					is_pre_close_update = true,
 			}
 		}
 
@@ -5952,7 +5980,7 @@ impl<Signer: EcdsaChannelSigner> ChannelMonitorImpl<Signer> {
 					// on-chain for an expired HTLC.
 					let htlc_outbound = $holder_tx == htlc.offered;
 					if ( htlc_outbound && htlc.cltv_expiry + LATENCY_GRACE_PERIOD_BLOCKS <= height) ||
-					   (!htlc_outbound && htlc.cltv_expiry <= height + CLTV_CLAIM_BUFFER && self.payment_preimages.contains_key(&htlc.payment_hash)) {
+					   (!htlc_outbound && htlc.cltv_expiry <= height + self.force_close_claimable_htlc_cltv_buffer && self.payment_preimages.contains_key(&htlc.payment_hash)) {
 						log_info!(logger, "Force-closing channel due to {} HTLC timeout - HTLC with payment hash {} expires at {}", if htlc_outbound { "outbound" } else { "inbound"}, htlc.payment_hash, htlc.cltv_expiry);
 						return Some(htlc.payment_hash);
 					}
@@ -6520,6 +6548,7 @@ impl<'a, 'b, ES: EntropySource, SP: SignerProvider> ReadableArgs<(&'a ES, &'b SP
 		let mut alternative_funding_confirmed = None;
 		let mut is_manual_broadcast = RequiredWrapper(None);
 		let mut funding_seen_onchain = RequiredWrapper(None);
+		let mut force_close_claimable_htlc_cltv_buffer = CLTV_CLAIM_BUFFER;
 		read_tlv_fields!(reader, {
 			(1, funding_spend_confirmed, option),
 			(3, htlcs_resolved_on_chain, optional_vec),
@@ -6542,6 +6571,7 @@ impl<'a, 'b, ES: EntropySource, SP: SignerProvider> ReadableArgs<(&'a ES, &'b SP
 			(34, alternative_funding_confirmed, option),
 			(35, is_manual_broadcast, (default_value, false)),
 			(37, funding_seen_onchain, (default_value, true)),
+			(39, force_close_claimable_htlc_cltv_buffer, (default_value, CLTV_CLAIM_BUFFER)),
 		});
 		// Note that `payment_preimages_with_info` was added (and is always written) in LDK 0.1, so
 		// we can use it to determine if this monitor was last written by LDK 0.1 or later.
@@ -6681,6 +6711,8 @@ impl<'a, 'b, ES: EntropySource, SP: SignerProvider> ReadableArgs<(&'a ES, &'b SP
 
 			on_holder_tx_csv,
 
+			force_close_claimable_htlc_cltv_buffer,
+
 			commitment_secrets,
 			counterparty_commitment_txn_on_chain,
 			counterparty_hash_commitment_number,
@@ -6761,7 +6793,7 @@ mod tests {
 	use crate::chain::chaininterface::LowerBoundedFeeEstimator;
 	use crate::events::ClosureReason;
 
-	use super::ChannelMonitorUpdateStep;
+	use super::{ChannelMonitorUpdateStep, CLTV_CLAIM_BUFFER};
 	use crate::chain::channelmonitor::{ChannelMonitor, WithChannelMonitor};
 	use crate::chain::package::{
 		weight_offered_htlc, weight_received_htlc, weight_revoked_offered_htlc,
@@ -6996,7 +7028,7 @@ mod tests {
 		let monitor = ChannelMonitor::new(
 			Secp256k1::new(), keys, Some(shutdown_script.into_inner()), 0, &ScriptBuf::new(),
 			&channel_parameters, true, 0, HolderCommitmentTransaction::dummy(0, funding_outpoint, Vec::new()),
-			best_block, dummy_key, channel_id, false,
+			best_block, dummy_key, channel_id, false, CLTV_CLAIM_BUFFER,
 		);
 
 		let nondust_htlcs = preimages_slice_to_htlcs!(preimages[0..10]);
@@ -7257,7 +7289,7 @@ mod tests {
 		let monitor = ChannelMonitor::new(
 			Secp256k1::new(), keys, Some(shutdown_script.into_inner()), 0, &ScriptBuf::new(),
 			&channel_parameters, true, 0, HolderCommitmentTransaction::dummy(0, funding_outpoint, Vec::new()),
-			best_block, dummy_key, channel_id, false,
+			best_block, dummy_key, channel_id, false, CLTV_CLAIM_BUFFER,
 		);
 
 		let chan_id = monitor.inner.lock().unwrap().channel_id();

lightning/src/ln/channel.rs

@@ -3381,6 +3381,7 @@ trait InitialRemoteCommitmentReceiver<SP: SignerProvider> {
 			&funding.channel_transaction_parameters, funding.is_outbound(), obscure_factor,
 			holder_commitment_tx, best_block, context.counterparty_node_id, context.channel_id(),
 			context.is_manual_broadcast,
+			context.config.options.force_close_claimable_htlc_cltv_buffer,
 		);
 		channel_monitor.provide_initial_counterparty_commitment_tx(
 			counterparty_initial_commitment_tx.clone(),

lightning/src/ln/channel_open_tests.rs

@@ -1119,6 +1119,7 @@ pub fn test_manually_accept_inbound_channel_request() {
 			cltv_expiry_delta: None,
 			max_dust_htlc_exposure_msat: None,
 			force_close_avoidance_max_fee_satoshis: None,
+			force_close_claimable_htlc_cltv_buffer: None,
 			accept_underpaying_htlcs: None,
 		}),
 	};

lightning/src/ln/channelmanager.rs

@@ -6619,6 +6619,13 @@ impl<
 				err: format!("The chosen CLTV expiry delta is below the minimum of {}", MIN_CLTV_EXPIRY_DELTA),
 			});
 		}
+		if config_update.force_close_claimable_htlc_cltv_buffer
+			.map(|buf| buf < CLTV_CLAIM_BUFFER).unwrap_or(false)
+		{
+			return Err(APIError::APIMisuseError {
+				err: format!("The chosen force-close CLTV buffer is below the minimum of {}", CLTV_CLAIM_BUFFER),
+			});
+		}
 
 		let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(self);
 		let per_peer_state = self.per_peer_state.read().unwrap();

lightning/src/util/config.rs

@@ -10,6 +10,7 @@
 //! Various user-configurable channel limits and settings which ChannelManager
 //! applies for you.
 
+use crate::chain::channelmonitor::CLTV_CLAIM_BUFFER;
 use crate::ln::channel::MAX_FUNDING_SATOSHIS_NO_WUMBO;
 use crate::ln::channelmanager::{BREAKDOWN_TIMEOUT, MAX_LOCAL_BREAKDOWN_TIMEOUT};
 
@@ -593,6 +594,26 @@ pub struct ChannelConfig {
 	/// [`NonAnchorChannelFee`]: crate::chain::chaininterface::ConfirmationTarget::NonAnchorChannelFee
 	/// [`ChannelCloseMinimum`]: crate::chain::chaininterface::ConfirmationTarget::ChannelCloseMinimum
 	pub force_close_avoidance_max_fee_satoshis: u64,
+	/// The number of blocks before an inbound HTLC's CLTV expiry at which we will force-close the
+	/// channel in order to claim it on-chain with an HTLC-Success transaction. This applies when
+	/// we have the preimage for the HTLC (i.e., it is a claimable HTLC that we forwarded).
+	///
+	/// Increasing this value gives you more tolerance for your own downtime at the expense of
+	/// being less tolerant of counterparty unresponsiveness (more force-closes). When set higher,
+	/// you force-close earlier, leaving more blocks to get the commitment transaction and
+	/// HTLC-Success transaction confirmed on-chain.
+	///
+	/// Note that when changing this value, you should also ensure that
+	/// [`cltv_expiry_delta`] is large enough to accommodate the new buffer.
+	///
+	/// Default value: [`CLTV_CLAIM_BUFFER`] (36 blocks)
+	///
+	/// Minimum value: [`CLTV_CLAIM_BUFFER`] (Any values less than this will be treated as
+	///                [`CLTV_CLAIM_BUFFER`] instead.)
+	///
+	/// [`cltv_expiry_delta`]: ChannelConfig::cltv_expiry_delta
+	/// [`CLTV_CLAIM_BUFFER`]: crate::chain::channelmonitor::CLTV_CLAIM_BUFFER
+	pub force_close_claimable_htlc_cltv_buffer: u32,
 	/// If set, allows this channel's counterparty to skim an additional fee off this node's inbound
 	/// HTLCs. Useful for liquidity providers to offload on-chain channel costs to end users.
 	///
@@ -650,6 +671,11 @@ impl ChannelConfig {
 		{
 			self.force_close_avoidance_max_fee_satoshis = force_close_avoidance_max_fee_satoshis;
 		}
+		if let Some(force_close_claimable_htlc_cltv_buffer) =
+			update.force_close_claimable_htlc_cltv_buffer
+		{
+			self.force_close_claimable_htlc_cltv_buffer = force_close_claimable_htlc_cltv_buffer;
+		}
 		if let Some(accept_underpaying_htlcs) = update.accept_underpaying_htlcs {
 			self.accept_underpaying_htlcs = accept_underpaying_htlcs;
 		}
@@ -665,6 +691,7 @@ impl Default for ChannelConfig {
 			cltv_expiry_delta: 6 * 12, // 6 blocks/hour * 12 hours
 			max_dust_htlc_exposure: MaxDustHTLCExposure::FeeRateMultiplier(10000),
 			force_close_avoidance_max_fee_satoshis: 1000,
+			force_close_claimable_htlc_cltv_buffer: CLTV_CLAIM_BUFFER,
 			accept_underpaying_htlcs: false,
 		}
 	}
@@ -687,6 +714,7 @@ impl crate::util::ser::Writeable for ChannelConfig {
 			// LegacyChannelConfig. To make sure that serialization is not compatible with this one, we use
 			// the next required type of 10, which if seen by the old serialization will always fail.
 			(10, self.force_close_avoidance_max_fee_satoshis, required),
+			(11, self.force_close_claimable_htlc_cltv_buffer, (default_value, CLTV_CLAIM_BUFFER)),
 		});
 		Ok(())
 	}
@@ -701,6 +729,7 @@ impl crate::util::ser::Readable for ChannelConfig {
 		let mut max_dust_htlc_exposure_msat = None;
 		let mut max_dust_htlc_exposure_enum = None;
 		let mut force_close_avoidance_max_fee_satoshis = 1000;
+		let mut force_close_claimable_htlc_cltv_buffer = CLTV_CLAIM_BUFFER;
 		read_tlv_fields!(reader, {
 			(0, forwarding_fee_proportional_millionths, required),
 			(1, accept_underpaying_htlcs, (default_value, false)),
@@ -710,6 +739,7 @@ impl crate::util::ser::Readable for ChannelConfig {
 			// Has always been written, but became optionally read in 0.0.116
 			(6, max_dust_htlc_exposure_msat, option),
 			(10, force_close_avoidance_max_fee_satoshis, required),
+			(11, force_close_claimable_htlc_cltv_buffer, (default_value, CLTV_CLAIM_BUFFER)),
 		});
 		let max_dust_htlc_fixed_limit = max_dust_htlc_exposure_msat.unwrap_or(5_000_000);
 		let max_dust_htlc_exposure_msat = max_dust_htlc_exposure_enum
@@ -721,6 +751,7 @@ impl crate::util::ser::Readable for ChannelConfig {
 			cltv_expiry_delta,
 			max_dust_htlc_exposure: max_dust_htlc_exposure_msat,
 			force_close_avoidance_max_fee_satoshis,
+			force_close_claimable_htlc_cltv_buffer,
 		})
 	}
 }
@@ -747,6 +778,10 @@ pub struct ChannelConfigUpdate {
 	/// funds. See [`ChannelConfig::force_close_avoidance_max_fee_satoshis`].
 	pub force_close_avoidance_max_fee_satoshis: Option<u64>,
 
+	/// The number of blocks before an inbound HTLC's CLTV expiry at which we will force-close to claim it
+	/// on-chain. See [`ChannelConfig::force_close_claimable_htlc_cltv_buffer`].
+	pub force_close_claimable_htlc_cltv_buffer: Option<u32>,
+
 	/// If set, allows this channel's counterparty to skim an additional fee off this node's inbound HTLCs. See
 	/// [`ChannelConfig::accept_underpaying_htlcs`].
 	pub accept_underpaying_htlcs: Option<bool>,
@@ -764,6 +799,9 @@ impl From<ChannelConfig> for ChannelConfigUpdate {
 			force_close_avoidance_max_fee_satoshis: Some(
 				config.force_close_avoidance_max_fee_satoshis,
 			),
+			force_close_claimable_htlc_cltv_buffer: Some(
+				config.force_close_claimable_htlc_cltv_buffer,
+			),
 			accept_underpaying_htlcs: Some(config.accept_underpaying_htlcs),
 		}
 	}
@@ -846,6 +884,7 @@ impl crate::util::ser::Readable for LegacyChannelConfig {
 				max_dust_htlc_exposure: max_dust_htlc_exposure_msat,
 				cltv_expiry_delta,
 				force_close_avoidance_max_fee_satoshis,
+				force_close_claimable_htlc_cltv_buffer: CLTV_CLAIM_BUFFER,
 				forwarding_fee_base_msat,
 				accept_underpaying_htlcs: false,
 			},