From 684ebf33e0cb563f6fe9f2844a25d72239c95648 Mon Sep 17 00:00:00 2001 From: okekefrancis112 Date: Mon, 9 Feb 2026 12:11:39 +0100 Subject: [PATCH] feat: added retry payment feature --- lightning/src/ln/channelmanager.rs | 10 ++ lightning/src/ln/functional_tests.rs | 30 +++- lightning/src/ln/htlc_reserve_unit_tests.rs | 84 +++++++++-- lightning/src/ln/payment_tests.rs | 151 +++++++++++++++++--- lightning/src/util/errors.rs | 12 ++ 5 files changed, 249 insertions(+), 38 deletions(-) diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs index 8a84de69cfc..363d7945beb 100644 --- a/lightning/src/ln/channelmanager.rs +++ b/lightning/src/ln/channelmanager.rs @@ -5239,6 +5239,16 @@ impl< &self.fee_estimator, &&logger, ); + // Intercept temporary local failures (e.g., HTLC slots full, + // balance constraint) before they go through break_channel_entry! + // which would convert them to ChannelUnavailable. Return + // ChannelBusy instead so the payment can be retried later. + let send_res = match send_res { + Err(ChannelError::Ignore(msg)) => { + return Err(APIError::ChannelBusy { err: msg }); + }, + other => other, + }; match break_channel_entry!(self, peer_state, send_res, chan_entry) { Some(monitor_update) => { let (update_completed, completion_data) = self diff --git a/lightning/src/ln/functional_tests.rs b/lightning/src/ln/functional_tests.rs index a7a062add11..1877171b136 100644 --- a/lightning/src/ln/functional_tests.rs +++ b/lightning/src/ln/functional_tests.rs @@ -8742,12 +8742,24 @@ fn do_test_max_dust_htlc_exposure( let onion = RecipientOnionFields::secret_only(payment_secret); let id = PaymentId(payment_hash.0); let res = nodes[0].node.send_payment_with_route(route, payment_hash, onion, id); - unwrap_send_err!(nodes[0], res, true, APIError::ChannelUnavailable { .. }, {}); + unwrap_send_err!( + nodes[0], + res, + true, + APIError::ChannelUnavailable { .. } | APIError::ChannelBusy { .. }, + {} + ); } else { let onion = RecipientOnionFields::secret_only(payment_secret); let id = PaymentId(payment_hash.0); let res = nodes[0].node.send_payment_with_route(route, payment_hash, onion, id); - unwrap_send_err!(nodes[0], res, true, APIError::ChannelUnavailable { .. }, {}); + unwrap_send_err!( + nodes[0], + res, + true, + APIError::ChannelUnavailable { .. } | APIError::ChannelBusy { .. }, + {} + ); } } else if exposure_breach_event == ExposureEvent::AtHTLCReception { let amount_msats = if on_holder_tx { @@ -9066,9 +9078,9 @@ pub fn test_nondust_htlc_excess_fees_are_dust() { let onion = RecipientOnionFields::secret_only(payment_secret_0_1); let id = PaymentId(payment_hash_0_1.0); let res = nodes[0].node.send_payment_with_route(route_0_1, payment_hash_0_1, onion, id); - unwrap_send_err!(nodes[0], res, true, APIError::ChannelUnavailable { .. }, {}); + unwrap_send_err!(nodes[0], res, true, APIError::ChannelBusy { .. }, {}); nodes[0].logger.assert_log("lightning::ln::outbound_payment", - format!("Failed to send along path due to error: Channel unavailable: Cannot send more than our next-HTLC maximum - {} msat", 2325000), 1); + format!("Failed to send along path due to error: Channel busy: Cannot send more than our next-HTLC maximum - {} msat", 2325000), 1); assert!(nodes[0].node.get_and_clear_pending_msg_events().is_empty()); assert_eq!(nodes[0].node.list_channels().len(), 1); @@ -9288,7 +9300,13 @@ fn do_test_nondust_htlc_fees_dust_exposure_delta(features: ChannelTypeFeatures) let onion = RecipientOnionFields::secret_only(payment_secret_1_0); let id = PaymentId(payment_hash_1_0.0); let res = nodes[1].node.send_payment_with_route(route_1_0, payment_hash_1_0, onion, id); - unwrap_send_err!(nodes[1], res, true, APIError::ChannelUnavailable { .. }, {}); + unwrap_send_err!( + nodes[1], + res, + true, + APIError::ChannelUnavailable { .. } | APIError::ChannelBusy { .. }, + {} + ); let (htlc_success_tx_fee_sat, _) = second_stage_tx_fees_sat(&features, node_1_dust_buffer_feerate as u32); @@ -9298,7 +9316,7 @@ fn do_test_nondust_htlc_fees_dust_exposure_delta(features: ChannelTypeFeatures) MIN_CHAN_DUST_LIMIT_SATOSHIS * 1000 }; nodes[1].logger.assert_log("lightning::ln::outbound_payment", - format!("Failed to send along path due to error: Channel unavailable: Cannot send more than our next-HTLC maximum - {} msat", dust_limit), 1); + format!("Failed to send along path due to error: Channel busy: Cannot send more than our next-HTLC maximum - {} msat", dust_limit), 1); assert!(nodes[1].node.get_and_clear_pending_msg_events().is_empty()); assert_eq!(nodes[0].node.list_channels().len(), 1); diff --git a/lightning/src/ln/htlc_reserve_unit_tests.rs b/lightning/src/ln/htlc_reserve_unit_tests.rs index 4c4fbada7dd..0e7fbf6dd4c 100644 --- a/lightning/src/ln/htlc_reserve_unit_tests.rs +++ b/lightning/src/ln/htlc_reserve_unit_tests.rs @@ -173,7 +173,13 @@ pub fn test_channel_reserve_holding_cell_htlcs() { let onion = RecipientOnionFields::secret_only(our_payment_secret); let id = PaymentId(our_payment_hash.0); let res = nodes[0].node.send_payment_with_route(route, our_payment_hash, onion, id); - unwrap_send_err!(nodes[0], res, true, APIError::ChannelUnavailable { .. }, {}); + unwrap_send_err!( + nodes[0], + res, + true, + APIError::ChannelUnavailable { .. } | APIError::ChannelBusy { .. }, + {} + ); assert!(nodes[0].node.get_and_clear_pending_msg_events().is_empty()); } @@ -270,7 +276,13 @@ pub fn test_channel_reserve_holding_cell_htlcs() { let onion = RecipientOnionFields::secret_only(our_payment_secret); let id = PaymentId(our_payment_hash.0); let res = nodes[0].node.send_payment_with_route(route, our_payment_hash, onion, id); - unwrap_send_err!(nodes[0], res, true, APIError::ChannelUnavailable { .. }, {}); + unwrap_send_err!( + nodes[0], + res, + true, + APIError::ChannelUnavailable { .. } | APIError::ChannelBusy { .. }, + {} + ); assert!(nodes[0].node.get_and_clear_pending_msg_events().is_empty()); } @@ -310,7 +322,13 @@ pub fn test_channel_reserve_holding_cell_htlcs() { let onion = RecipientOnionFields::secret_only(our_payment_secret); let id = PaymentId(our_payment_hash.0); let res = nodes[0].node.send_payment_with_route(route, our_payment_hash, onion, id); - unwrap_send_err!(nodes[0], res, true, APIError::ChannelUnavailable { .. }, {}); + unwrap_send_err!( + nodes[0], + res, + true, + APIError::ChannelUnavailable { .. } | APIError::ChannelBusy { .. }, + {} + ); assert!(nodes[0].node.get_and_clear_pending_msg_events().is_empty()); } @@ -656,7 +674,13 @@ pub fn holding_cell_htlc_counting() { let onion = RecipientOnionFields::secret_only(payment_secret_1); let id = PaymentId(payment_hash_1.0); let res = nodes[1].node.send_payment_with_route(route, payment_hash_1, onion, id); - unwrap_send_err!(nodes[1], res, true, APIError::ChannelUnavailable { .. }, {}); + unwrap_send_err!( + nodes[1], + res, + true, + APIError::ChannelUnavailable { .. } | APIError::ChannelBusy { .. }, + {} + ); assert!(nodes[1].node.get_and_clear_pending_msg_events().is_empty()); } @@ -770,7 +794,13 @@ pub fn test_basic_channel_reserve() { let onion = RecipientOnionFields::secret_only(our_payment_secret); let id = PaymentId(our_payment_hash.0); let err = nodes[0].node.send_payment_with_route(route, our_payment_hash, onion, id); - unwrap_send_err!(nodes[0], err, true, APIError::ChannelUnavailable { .. }, {}); + unwrap_send_err!( + nodes[0], + err, + true, + APIError::ChannelUnavailable { .. } | APIError::ChannelBusy { .. }, + {} + ); assert!(nodes[0].node.get_and_clear_pending_msg_events().is_empty()); send_payment(&nodes[0], &[&nodes[1]], max_can_send); @@ -1017,7 +1047,13 @@ pub fn test_chan_reserve_violation_outbound_htlc_inbound_chan() { let onion = RecipientOnionFields::secret_only(our_payment_secret); let id = PaymentId(our_payment_hash.0); let res = nodes[1].node.send_payment_with_route(route, our_payment_hash, onion, id); - unwrap_send_err!(nodes[1], res, true, APIError::ChannelUnavailable { .. }, {}); + unwrap_send_err!( + nodes[1], + res, + true, + APIError::ChannelUnavailable { .. } | APIError::ChannelBusy { .. }, + {} + ); assert!(nodes[1].node.get_and_clear_pending_msg_events().is_empty()); } @@ -1145,7 +1181,13 @@ pub fn test_chan_reserve_dust_inbound_htlcs_outbound_chan() { let onion = RecipientOnionFields::secret_only(our_payment_secret); let id = PaymentId(our_payment_hash.0); let res = nodes[1].node.send_payment_with_route(route, our_payment_hash, onion, id); - unwrap_send_err!(nodes[1], res, true, APIError::ChannelUnavailable { .. }, {}); + unwrap_send_err!( + nodes[1], + res, + true, + APIError::ChannelUnavailable { .. } | APIError::ChannelBusy { .. }, + {} + ); } #[xtest(feature = "_externalize_tests")] @@ -1337,7 +1379,13 @@ pub fn test_update_add_htlc_bolt2_sender_value_below_minimum_msat() { let onion = RecipientOnionFields::secret_only(our_payment_secret); let id = PaymentId(our_payment_hash.0); let res = nodes[0].node.send_payment_with_route(route, our_payment_hash, onion, id); - unwrap_send_err!(nodes[0], res, true, APIError::ChannelUnavailable { .. }, {}); + unwrap_send_err!( + nodes[0], + res, + true, + APIError::ChannelUnavailable { .. } | APIError::ChannelBusy { .. }, + {} + ); assert!(nodes[0].node.get_and_clear_pending_msg_events().is_empty()); } @@ -1358,12 +1406,12 @@ pub fn test_update_add_htlc_bolt2_sender_zero_value_msat() { let id = PaymentId(our_payment_hash.0); let res = nodes[0].node.send_payment_with_route(route, our_payment_hash, onion, id); unwrap_send_err!(nodes[0], res, - true, APIError::ChannelUnavailable { ref err }, + true, APIError::ChannelBusy { ref err }, assert_eq!(err, "Cannot send 0-msat HTLC")); assert!(nodes[0].node.get_and_clear_pending_msg_events().is_empty()); nodes[0].logger.assert_log_contains( - "lightning::ln::channelmanager", + "lightning::ln::outbound_payment", "Cannot send 0-msat HTLC", 2, ); @@ -1489,7 +1537,13 @@ pub fn test_update_add_htlc_bolt2_sender_exceed_max_htlc_num_and_htlc_id_increme let onion = RecipientOnionFields::secret_only(our_payment_secret); let id = PaymentId(our_payment_hash.0); let res = nodes[0].node.send_payment_with_route(route, our_payment_hash, onion, id); - unwrap_send_err!(nodes[0], res, true, APIError::ChannelUnavailable { .. }, {}); + unwrap_send_err!( + nodes[0], + res, + true, + APIError::ChannelUnavailable { .. } | APIError::ChannelBusy { .. }, + {} + ); assert!(nodes[0].node.get_and_clear_pending_msg_events().is_empty()); } @@ -1517,7 +1571,13 @@ pub fn test_update_add_htlc_bolt2_sender_exceed_max_htlc_value_in_flight() { let onion = RecipientOnionFields::secret_only(our_payment_secret); let id = PaymentId(our_payment_hash.0); let res = nodes[0].node.send_payment_with_route(route, our_payment_hash, onion, id); - unwrap_send_err!(nodes[0], res, true, APIError::ChannelUnavailable { .. }, {}); + unwrap_send_err!( + nodes[0], + res, + true, + APIError::ChannelUnavailable { .. } | APIError::ChannelBusy { .. }, + {} + ); assert!(nodes[0].node.get_and_clear_pending_msg_events().is_empty()); send_payment(&nodes[0], &[&nodes[1]], max_in_flight); diff --git a/lightning/src/ln/payment_tests.rs b/lightning/src/ln/payment_tests.rs index 2b3a2633205..2a09d5fd8f2 100644 --- a/lightning/src/ln/payment_tests.rs +++ b/lightning/src/ln/payment_tests.rs @@ -2938,10 +2938,11 @@ fn auto_retry_partial_failure() { nodes[0].router.expect_find_route(route_params.clone(), Ok(send_route)); // Configure the retry1 paths - let mut payment_params = route_params.payment_params.clone(); - payment_params.previously_failed_channels.push(chan_2_id); - let mut retry_1_params = - RouteParameters::from_payment_params_and_value(payment_params, amt_msat / 2); + // ChannelBusy errors don't blacklist channels, so previously_failed_channels stays empty. + let mut retry_1_params = RouteParameters::from_payment_params_and_value( + route_params.payment_params.clone(), + amt_msat / 2, + ); retry_1_params.max_total_routing_fee_msat = None; let retry_1_route = Route { @@ -2976,10 +2977,11 @@ fn auto_retry_partial_failure() { nodes[0].router.expect_find_route(retry_1_params.clone(), Ok(retry_1_route)); // Configure the retry2 path - let mut payment_params = retry_1_params.payment_params.clone(); - payment_params.previously_failed_channels.push(chan_3_id); - let mut retry_2_params = - RouteParameters::from_payment_params_and_value(payment_params, amt_msat / 4); + // ChannelBusy errors don't blacklist channels, so previously_failed_channels stays empty. + let mut retry_2_params = RouteParameters::from_payment_params_and_value( + retry_1_params.payment_params.clone(), + amt_msat / 4, + ); retry_2_params.max_total_routing_fee_msat = None; let retry_2_route = Route { @@ -3293,12 +3295,14 @@ fn retry_multi_path_single_failed_payment() { }; nodes[0].router.expect_find_route(route_params.clone(), Ok(route.clone())); // On retry, split the payment across both channels. + // ChannelBusy errors don't blacklist channels, so previously_failed_channels stays empty. route.paths[0].hops[0].fee_msat = 50_000_001; route.paths[1].hops[0].fee_msat = 50_000_000; - let mut pay_params = route.route_params.clone().unwrap().payment_params; - pay_params.previously_failed_channels.push(chans[1].short_channel_id.unwrap()); - let mut retry_params = RouteParameters::from_payment_params_and_value(pay_params, 100_000_000); + let mut retry_params = RouteParameters::from_payment_params_and_value( + route_params.payment_params.clone(), + 100_000_000, + ); retry_params.max_total_routing_fee_msat = None; route.route_params = Some(retry_params.clone()); nodes[0].router.expect_find_route(retry_params, Ok(route.clone())); @@ -3333,12 +3337,11 @@ fn retry_multi_path_single_failed_payment() { Event::PaymentPathFailed { payment_hash: ev_payment_hash, payment_failed_permanently: false, - failure: PathFailure::InitialSend { err: APIError::ChannelUnavailable { .. } }, - short_channel_id: Some(expected_scid), + failure: PathFailure::InitialSend { err: APIError::ChannelBusy { .. } }, + short_channel_id: None, .. } => { assert_eq!(payment_hash, ev_payment_hash); - assert_eq!(expected_scid, route.paths[1].hops[0].short_channel_id); }, _ => panic!("Unexpected event"), } @@ -3395,13 +3398,12 @@ fn immediate_retry_on_failure() { }; nodes[0].router.expect_find_route(route_params.clone(), Ok(route.clone())); // On retry, split the payment across both channels. + // ChannelBusy errors don't blacklist the channel, so the retry uses original route_params. route.paths.push(route.paths[0].clone()); route.paths[0].hops[0].short_channel_id = chans[1].short_channel_id.unwrap(); route.paths[0].hops[0].fee_msat = 50_000_000; route.paths[1].hops[0].fee_msat = 50_000_001; - let mut pay_params = route_params.payment_params.clone(); - pay_params.previously_failed_channels.push(chans[0].short_channel_id.unwrap()); - let retry_params = RouteParameters::from_payment_params_and_value(pay_params, amt_msat); + let retry_params = route_params.clone(); route.route_params = Some(retry_params.clone()); nodes[0].router.expect_find_route(retry_params, Ok(route.clone())); @@ -3414,12 +3416,11 @@ fn immediate_retry_on_failure() { Event::PaymentPathFailed { payment_hash: ev_payment_hash, payment_failed_permanently: false, - failure: PathFailure::InitialSend { err: APIError::ChannelUnavailable { .. } }, - short_channel_id: Some(expected_scid), + failure: PathFailure::InitialSend { err: APIError::ChannelBusy { .. } }, + short_channel_id: None, .. } => { assert_eq!(payment_hash, ev_payment_hash); - assert_eq!(expected_scid, route.paths[1].hops[0].short_channel_id); }, _ => panic!("Unexpected event"), } @@ -5413,3 +5414,113 @@ fn max_out_mpp_path() { check_added_monitors(&nodes[0], 2); // one monitor update per MPP part nodes[0].node.get_and_clear_pending_msg_events(); } + +#[test] +fn channel_busy_does_not_blacklist_channel() { + // Test that when a payment fails with ChannelBusy (e.g., exceeds max HTLC value), the + // channel is not added to previously_failed_channels, allowing the retry to use the same + // channel. This is the core behavior from issue #4161. + let chanmon_cfgs = create_chanmon_cfgs(2); + let node_cfgs = create_node_cfgs(2, &chanmon_cfgs); + let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, None]); + let nodes = create_network(2, &node_cfgs, &node_chanmgrs); + + let node_b_id = nodes[1].node.get_our_node_id(); + + create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 1_000_000, 0); + create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 1_000_000, 0); + + // Amount exceeds max HTLC value for a single channel (10% of 1M sats = 100K sats) + let amt_msat = 100_000_001; + let (_, payment_hash, _, payment_secret) = + get_route_and_payment_hash!(&nodes[0], nodes[1], amt_msat); + #[cfg(feature = "std")] + let payment_expiry_secs = SystemTime::UNIX_EPOCH.elapsed().unwrap().as_secs() + 60 * 60; + #[cfg(not(feature = "std"))] + let payment_expiry_secs = 60 * 60; + let mut invoice_features = Bolt11InvoiceFeatures::empty(); + invoice_features.set_variable_length_onion_required(); + invoice_features.set_payment_secret_required(); + invoice_features.set_basic_mpp_optional(); + let payment_params = PaymentParameters::from_node_id(node_b_id, TEST_FINAL_CLTV) + .with_expiry_time(payment_expiry_secs as u64) + .with_bolt11_features(invoice_features) + .unwrap(); + let route_params = RouteParameters::from_payment_params_and_value(payment_params, amt_msat); + + let chans = nodes[0].node.list_usable_channels(); + + // First attempt: single path with too-large value -> ChannelBusy + let route = Route { + paths: vec![Path { + hops: vec![RouteHop { + pubkey: node_b_id, + node_features: nodes[1].node.node_features(), + short_channel_id: chans[0].short_channel_id.unwrap(), + channel_features: nodes[1].node.channel_features(), + fee_msat: amt_msat, + cltv_expiry_delta: 100, + maybe_announced_channel: true, + }], + blinded_tail: None, + }], + route_params: Some(route_params.clone()), + }; + nodes[0].router.expect_find_route(route_params.clone(), Ok(route)); + + // On retry, the route_params should NOT have previously_failed_channels set because + // ChannelBusy does not blacklist the channel. The retry splits across both channels. + let retry_route = Route { + paths: vec![ + Path { + hops: vec![RouteHop { + pubkey: node_b_id, + node_features: nodes[1].node.node_features(), + short_channel_id: chans[0].short_channel_id.unwrap(), + channel_features: nodes[1].node.channel_features(), + fee_msat: 50_000_000, + cltv_expiry_delta: 100, + maybe_announced_channel: true, + }], + blinded_tail: None, + }, + Path { + hops: vec![RouteHop { + pubkey: node_b_id, + node_features: nodes[1].node.node_features(), + short_channel_id: chans[1].short_channel_id.unwrap(), + channel_features: nodes[1].node.channel_features(), + fee_msat: 50_000_001, + cltv_expiry_delta: 100, + maybe_announced_channel: true, + }], + blinded_tail: None, + }, + ], + route_params: Some(route_params.clone()), + }; + // Key assertion: the retry uses route_params WITHOUT previously_failed_channels + nodes[0].router.expect_find_route(route_params.clone(), Ok(retry_route)); + + let onion = RecipientOnionFields::secret_only(payment_secret); + let id = PaymentId(payment_hash.0); + nodes[0].node.send_payment(payment_hash, onion, id, route_params, Retry::Attempts(1)).unwrap(); + + let events = nodes[0].node.get_and_clear_pending_events(); + assert_eq!(events.len(), 1); + // Verify ChannelBusy error with no short_channel_id blame (channel not blacklisted) + match &events[0] { + Event::PaymentPathFailed { + payment_failed_permanently: false, + failure: PathFailure::InitialSend { err: APIError::ChannelBusy { .. } }, + short_channel_id: None, + .. + } => {}, + _ => panic!("Expected PaymentPathFailed with ChannelBusy, got: {:?}", events[0]), + } + + // The retry should have succeeded (split across both channels) + let htlc_msgs = nodes[0].node.get_and_clear_pending_msg_events(); + assert_eq!(htlc_msgs.len(), 2); + check_added_monitors(&nodes[0], 2); +} diff --git a/lightning/src/util/errors.rs b/lightning/src/util/errors.rs index eaaf0130ca2..cd0222f3f23 100644 --- a/lightning/src/util/errors.rs +++ b/lightning/src/util/errors.rs @@ -57,6 +57,14 @@ pub enum APIError { /// [`chain::Watch::update_channel`]: crate::chain::Watch::update_channel /// [`ChannelMonitorUpdateStatus::InProgress`]: crate::chain::ChannelMonitorUpdateStatus::InProgress MonitorUpdateInProgress, + /// The channel is temporarily busy and cannot process the request right now (e.g., all HTLC + /// slots are full, or a temporary balance constraint prevents forwarding). The condition is + /// expected to resolve on its own and the payment will be retried automatically if a retry + /// strategy is set. + ChannelBusy { + /// A human-readable error message + err: String, + }, /// [`SignerProvider::get_shutdown_scriptpubkey`] returned a shutdown scriptpubkey incompatible /// with the channel counterparty as negotiated in [`InitFeatures`]. /// @@ -80,6 +88,9 @@ impl fmt::Debug for APIError { }, APIError::InvalidRoute { ref err } => write!(f, "Invalid route provided: {}", err), APIError::ChannelUnavailable { ref err } => write!(f, "Channel unavailable: {}", err), + APIError::ChannelBusy { ref err } => { + write!(f, "Channel busy: {}", err) + }, APIError::MonitorUpdateInProgress => f.write_str( "Client indicated a channel monitor update is in progress but not yet complete", ), @@ -100,4 +111,5 @@ impl_writeable_tlv_based_enum_upgradable!(APIError, (6, ChannelUnavailable) => { (0, err, required), }, (8, MonitorUpdateInProgress) => {}, (10, IncompatibleShutdownScript) => { (0, script, required), }, + (12, ChannelBusy) => { (0, err, required), }, );