Merge PR 'Account for current HTLC fees in dust exposure' (#5690)
What changed, and why it matters
This change fixes how Lightning nodes calculate the financial risk from tiny ('dust') HTLCs when the current on-chain fee rate is higher than the node's own local fee estimate. Previously, the code only considered a buffered fee rate when deciding which HTLCs count as dust and how much extra fee exposure they create. The patch now checks both the actual current fee rate and the buffered fee rate, and uses the worse of the two when limiting how much can be sent. This prevents a node from accepting or sending HTLCs that look safe under a buffered estimate but are actually dust at the current fee rate, which could leave the node paying unexpectedly high commitment transaction fees relative to the HTLC value.
Review and merge if not already merged; ensure downstream users update to include this fix. Operators should monitor `max_dust_htlc_exposure` settings and fee estimator behavior. No immediate emergency response is indicated, but the fix should be included in the next release.
Security signals we found
Incorrect fee exposure accounting for dust HTLCs
Potential to accept HTLCs whose commitment/HTLC-success fees exceed their value under current feerate
Economic griefing / forced-channel-closure cost manipulation
Regression test added for the fixed scenario
Evidence from the diff
The patch modifies commit_plus_htlc_tx_fees_msat and get_dust_exposure_stats in lightning/src/sign/tx_builder.rs. Previously, dust exposure and excess fee calculations used a single dust_buffer_feerate for determining which HTLCs are dust and a separate excess_feerate for fee calculations. The fix introduces a loop over both feerate_per_kw (current) and dust_buffer_feerate (buffered), computing dust exposure and excess commitment/second-stage fees for each, and taking the maximum. This ensures that HTLCs which are non-dust at the buffered rate but dust at the current rate are accounted for. Additionally, adjust_min_max_htlc_for_dust_exposure now uses the current feerate’s dust limit rather than the buffered one when capping available capacity after an extra HTLC would exceed the dust exposure limit. A new regression test test_buffered_dust_htlc_excess_fees demonstrates the scenario.
Changed components
lightning/src/sign/tx_builder.rslightning/src/ln/functional_tests.rsInspect captured patch +108 / −38
### lightning/src/ln/functional_tests.rs
@@ -9686,6 +9686,48 @@ fn do_test_nondust_htlc_fees_dust_exposure_delta(features: ChannelTypeFeatures)
assert_eq!(nodes[1].node.list_channels()[0].pending_inbound_htlcs.len(), DUST_HTLC_COUNT);
}
+#[test]
+fn test_buffered_dust_htlc_excess_fees() {
+ let chanmon_cfgs = create_chanmon_cfgs(2);
+ for cfg in &chanmon_cfgs {
+ *cfg.fee_estimator.sat_per_kw.lock().unwrap() = 18_500;
+ }
+ let node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
+ let mut config = test_legacy_channel_config();
+ config.channel_config.max_dust_htlc_exposure = MaxDustHTLCExposure::FeeRateMultiplier(10_000);
+ let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[Some(config.clone()), Some(config)]);
+ let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
+ create_chan_between_nodes_with_value(&nodes[0], &nodes[1], 1_000_000, 200_000_000);
+
+ // This HTLC is untrimmed on the counterparty commitment at 18,500 sat/kw, but dust at
+ // the buffered 23,125 sat/kw. Cache a route before lowering the estimate to test send admission.
+ const HTLC_MSAT: u64 = 13_359_000;
+ let (route, payment_hash, _, payment_secret) =
+ get_route_and_payment_hash!(nodes[0], nodes[1], HTLC_MSAT);
+ let (preimage, _, _, _) = route_payment(&nodes[0], &[&nodes[1]], HTLC_MSAT);
+
+ // The negotiated feerate remains high while the local estimate and exposure limit fall.
+ *chanmon_cfgs[0].fee_estimator.sat_per_kw.lock().unwrap() = 2_500;
+ // Excess commitment and HTLC-success fees: (724 + 172 + 703) * (18,500 - 2,500) msat.
+ assert_eq!(nodes[0].node.list_channels()[0].current_dust_exposure_msat, Some(25_584_000));
+ claim_payment(&nodes[0], &[&nodes[1]], preimage);
+
+ // A new untrimmed HTLC would exceed the 25,000,000-msat exposure limit.
+ assert_eq!(nodes[0].node.list_channels()[0].next_outbound_htlc_limit_msat, HTLC_MSAT - 1);
+ let onion = RecipientOnionFields::secret_only(payment_secret, route.get_total_amount());
+ let res = nodes[0].node.send_payment_with_route(
+ route,
+ payment_hash,
+ onion,
+ PaymentId(payment_hash.0),
+ );
+ unwrap_send_err!(nodes[0], res, true, APIError::ChannelUnavailable { err }, {
+ assert_eq!(err, "Cannot send more than our next-HTLC maximum - 13358999 msat");
+ });
+ check_added_monitors(&nodes[0], 0);
+ send_payment(&nodes[0], &[&nodes[1]], HTLC_MSAT - 1);
+}
+
#[test]
fn test_nondust_htlc_fees_dust_exposure_delta() {
do_test_nondust_htlc_fees_dust_exposure_delta(ChannelTypeFeatures::only_static_remote_key());
### lightning/src/sign/tx_builder.rs
@@ -51,16 +51,17 @@ pub(crate) struct ChannelStats {
}
fn commit_plus_htlc_tx_fees_msat(
- local: bool, next_commitment_htlcs: &[HTLCAmountDirection], dust_buffer_feerate: u32,
- feerate: u32, broadcaster_dust_limit_satoshis: u64, channel_type: &ChannelTypeFeatures,
+ local: bool, next_commitment_htlcs: &[HTLCAmountDirection],
+ current_or_buffered_feerate_per_kw: u32, excess_feerate_over_local_estimate_per_kw: u32,
+ broadcaster_dust_limit_satoshis: u64, channel_type: &ChannelTypeFeatures,
) -> (u64, u64) {
let accepted_nondust_htlcs = next_commitment_htlcs
.iter()
.filter(|htlc| {
htlc.outbound != local
&& !htlc.is_dust(
local,
- dust_buffer_feerate,
+ current_or_buffered_feerate_per_kw,
broadcaster_dust_limit_satoshis,
channel_type,
)
@@ -72,26 +73,37 @@ fn commit_plus_htlc_tx_fees_msat(
htlc.outbound == local
&& !htlc.is_dust(
local,
- dust_buffer_feerate,
+ current_or_buffered_feerate_per_kw,
broadcaster_dust_limit_satoshis,
channel_type,
)
})
.count();
- let commitment_fee_sat =
- commit_tx_fee_sat(feerate, accepted_nondust_htlcs + offered_nondust_htlcs, channel_type);
- let second_stage_fees_sat =
- htlc_tx_fees_sat(feerate, accepted_nondust_htlcs, offered_nondust_htlcs, channel_type);
+ let commitment_fee_sat = commit_tx_fee_sat(
+ excess_feerate_over_local_estimate_per_kw,
+ accepted_nondust_htlcs + offered_nondust_htlcs,
+ channel_type,
+ );
+ let second_stage_fees_sat = htlc_tx_fees_sat(
+ excess_feerate_over_local_estimate_per_kw,
+ accepted_nondust_htlcs,
+ offered_nondust_htlcs,
+ channel_type,
+ );
let total_fees_msat = (commitment_fee_sat + second_stage_fees_sat) * 1000;
let extra_accepted_htlc_commitment_fee_sat = commit_tx_fee_sat(
- feerate,
+ excess_feerate_over_local_estimate_per_kw,
accepted_nondust_htlcs + 1 + offered_nondust_htlcs,
channel_type,
);
- let extra_accepted_htlc_second_stage_fees_sat =
- htlc_tx_fees_sat(feerate, accepted_nondust_htlcs + 1, offered_nondust_htlcs, channel_type);
+ let extra_accepted_htlc_second_stage_fees_sat = htlc_tx_fees_sat(
+ excess_feerate_over_local_estimate_per_kw,
+ accepted_nondust_htlcs + 1,
+ offered_nondust_htlcs,
+ channel_type,
+ );
let extra_accepted_htlc_total_fees_msat =
(extra_accepted_htlc_commitment_fee_sat + extra_accepted_htlc_second_stage_fees_sat) * 1000;
@@ -154,42 +166,56 @@ fn get_dust_exposure_stats(
dust_exposure_limiting_feerate: Option<u32>, broadcaster_dust_limit_satoshis: u64,
channel_type: &ChannelTypeFeatures,
) -> (u64, Option<u64>) {
- let excess_feerate =
+ let excess_feerate_over_local_estimate_per_kw =
feerate_per_kw.saturating_sub(dust_exposure_limiting_feerate.unwrap_or(feerate_per_kw));
if channel_type.supports_anchor_zero_fee_commitments() {
debug_assert_eq!(feerate_per_kw, 0);
- debug_assert_eq!(excess_feerate, 0);
+ debug_assert_eq!(excess_feerate_over_local_estimate_per_kw, 0);
}
// Increment the feerate by a buffer to calculate dust exposure
let dust_buffer_feerate = get_dust_buffer_feerate(feerate_per_kw);
- // Calculate dust exposure on commitment transaction
- let dust_exposure_msat = commitment_htlcs
- .iter()
- .filter_map(|htlc| {
- htlc.is_dust(local, dust_buffer_feerate, broadcaster_dust_limit_satoshis, channel_type)
+ let dust_exposure_at_feerate = |current_or_buffered_feerate_per_kw| {
+ commitment_htlcs
+ .iter()
+ .filter_map(|htlc| {
+ htlc.is_dust(
+ local,
+ current_or_buffered_feerate_per_kw,
+ broadcaster_dust_limit_satoshis,
+ channel_type,
+ )
.then_some(htlc.amount_msat)
- })
- .sum();
+ })
+ .sum::<u64>()
+ };
- if local || excess_feerate == 0 {
- (dust_exposure_msat, None)
+ if local || excess_feerate_over_local_estimate_per_kw == 0 {
+ (dust_exposure_at_feerate(dust_buffer_feerate), None)
} else {
- // Add any excess fees to dust exposure on counterparty transactions
- let (excess_fees_msat, extra_accepted_htlc_excess_fees_msat) =
- commit_plus_htlc_tx_fees_msat(
- local,
- &commitment_htlcs,
- dust_buffer_feerate,
- excess_feerate,
- broadcaster_dust_limit_satoshis,
- channel_type,
+ // An HTLC trimmed only at the buffered feerate may incur excess commitment and
+ // second-stage fees exceeding its amount at the current feerate. Bound both scenarios.
+ let mut exposure_msat = 0;
+ let mut extra_htlc_exposure_msat = 0;
+ for current_or_buffered_feerate_per_kw in [feerate_per_kw, dust_buffer_feerate] {
+ let dust_exposure_msat = dust_exposure_at_feerate(current_or_buffered_feerate_per_kw);
+ let (excess_fees_msat, extra_accepted_htlc_excess_fees_msat) =
+ commit_plus_htlc_tx_fees_msat(
+ local,
+ commitment_htlcs,
+ current_or_buffered_feerate_per_kw,
+ excess_feerate_over_local_estimate_per_kw,
+ broadcaster_dust_limit_satoshis,
+ channel_type,
+ );
+ exposure_msat = cmp::max(exposure_msat, dust_exposure_msat + excess_fees_msat);
+ extra_htlc_exposure_msat = cmp::max(
+ extra_htlc_exposure_msat,
+ dust_exposure_msat + extra_accepted_htlc_excess_fees_msat,
);
- (
- dust_exposure_msat + excess_fees_msat,
- Some(dust_exposure_msat + extra_accepted_htlc_excess_fees_msat),
- )
+ }
+ (exposure_msat, Some(extra_htlc_exposure_msat))
}
}
@@ -607,11 +633,13 @@ fn adjust_min_max_htlc_for_dust_exposure(
if let Some(extra_htlc_remote_dust_exposure) = extra_htlc_remote_dust_exposure_msat {
if extra_htlc_remote_dust_exposure > max_dust_htlc_exposure_msat {
- // If adding an extra HTLC would put us over the dust limit in total fees, we cannot
- // send any non-dust HTLCs.
+ // Only HTLCs trimmed at the current feerate avoid the additional output fees.
+ let current_dust_limit_success_sat =
+ second_stage_tx_fees_sat(channel_type, feerate_per_kw).0
+ + channel_constraints.counterparty_dust_limit_satoshis;
available_capacity_msat = cmp::min(
available_capacity_msat,
- buffer_dust_limit_success_sat.saturating_mul(1000).saturating_sub(1),
+ current_dust_limit_success_sat.saturating_mul(1000).saturating_sub(1),
);
}
}Why this scored 63/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.