Merge PR 'Retry a single HTLC before abandoning an unfundable batch' (#5406)
What changed, and why it matters
This change fixes a corner case in how the Lightning node tries to claim multiple pending HTLCs (small Bitcoin payments locked in a channel) when the wallet cannot fund a single large batch transaction. Previously, if the multi-HTLC batch was too expensive to fund, the code would shrink the batch and immediately give up when only one HTLC remained, abandoning that last HTLC instead of trying to claim it alone. The patch makes the code retry the final HTLC as a single transaction before giving up, so a user is less likely to lose funds due to an unclaimable HTLC.
Review the change as a defensive hardening fix. Ensure the new `batch_size <= 1` guard and `saturating_sub(...).max(1)` correctly handle all batch sizes and do not introduce an infinite loop or off-by-one behavior. Consider whether the same retry-singleton logic is needed elsewhere in the bump-transaction flow.
Security signals we found
Funds-recovery robustness improvement: prevents premature abandonment of a single unbatched HTLC
Change in error-handling arithmetic from checked_sub/saturating_sub with max(1)
New unit tests covering both failed and successful singleton HTLC funding paths
Evidence from the diff
In lightning/src/events/bump_transaction/mod.rs, the HTLC batching logic reduces batch_size when coin selection fails because the transaction exceeds the user coin weight budget. The old code used checked_sub and returned Err(()) as soon as batch_size reached 0, which could happen after removing HTLCs from a 2-HTLC batch down to 1. The new code checks batch_size <= 1 before subtracting, then uses saturating_sub(...).max(1) so the loop retries with a single HTLC before finally failing. A new test verifies the retry path and the optional successful singleton funding path.
Changed components
lightning/src/events/bump_transaction/mod.rsBumpTransactionEventHandler HTLC resolution batching logicInspect captured patch +119 / −2
### lightning/src/events/bump_transaction/mod.rs
@@ -715,10 +715,10 @@ impl<B: BroadcasterInterface, C: CoinSelectionSource, SP: SignerProvider, L: Log
Err(()) => {
let htlcs_to_remove =
USER_COINS_WEIGHT_BUDGET.div_ceil(htlc_timeout_input_output_pair_weight);
- batch_size = batch_size.checked_sub(htlcs_to_remove as usize).ok_or(())?;
- if batch_size == 0 {
+ if batch_size <= 1 {
return Err(());
}
+ batch_size = batch_size.saturating_sub(htlcs_to_remove as usize).max(1);
continue;
},
};
@@ -1052,6 +1052,123 @@ mod tests {
});
}
+ fn do_test_htlc_batch_retries_singleton(fund_singletons: bool) {
+ struct SingletonCoinSelectionSource {
+ expected_selects: Mutex<Vec<(usize, ClaimId)>>,
+ fund_singletons: bool,
+ funding_tx: Transaction,
+ }
+ impl CoinSelectionSourceSync for SingletonCoinSelectionSource {
+ fn select_confirmed_utxos(
+ &self, claim_id: Option<ClaimId>, must_spend: Vec<Input>, _must_pay_to: &[TxOut],
+ _target_feerate_sat_per_1000_weight: u32, _max_tx_weight: u64,
+ ) -> Result<CoinSelection, ()> {
+ let (batch_size, expected_claim_id) =
+ self.expected_selects.lock().unwrap().remove(0);
+ assert_eq!(must_spend.len(), batch_size);
+ assert_eq!(claim_id, Some(expected_claim_id));
+ if must_spend.len() > 1 || !self.fund_singletons {
+ return Err(());
+ }
+ let vout = must_spend[0].outpoint.vout;
+ Ok(CoinSelection {
+ confirmed_utxos: vec![ConfirmedUtxo {
+ utxo: Utxo {
+ outpoint: OutPoint { txid: self.funding_tx.compute_txid(), vout },
+ output: self.funding_tx.output[vout as usize].clone(),
+ satisfaction_weight: 5, // Empty script_sig and witness lengths.
+ sequence: Sequence::ENABLE_RBF_NO_LOCKTIME,
+ },
+ prevtx: self.funding_tx.clone(),
+ }],
+ change_output: None,
+ })
+ }
+ fn sign_psbt(&self, psbt: Psbt) -> Result<Transaction, ()> {
+ assert!(self.fund_singletons);
+ Ok(psbt.unsigned_tx)
+ }
+ }
+
+ let broadcaster = TestBroadcaster::new(Network::Testnet);
+ let claim_id = ClaimId([42; 32]);
+ let mut expected_selects = vec![(2, claim_id), (1, claim_id)];
+ if fund_singletons {
+ expected_selects.push((1, claim_id.step_with_bytes(&1usize.to_be_bytes())));
+ }
+ let funding_output =
+ TxOut { value: Amount::from_sat(1000), script_pubkey: ScriptBuf::new() };
+ let source = SingletonCoinSelectionSource {
+ expected_selects: Mutex::new(expected_selects),
+ fund_singletons,
+ funding_tx: Transaction {
+ version: Version::TWO,
+ lock_time: LockTime::ZERO,
+ input: vec![],
+ output: vec![funding_output; 2],
+ },
+ };
+ let logger = TestLogger::new();
+ let signer = KeysManager::new(&[42; 32], 42, 42, true, &logger);
+ let handler = BumpTransactionEventHandlerSync::new(&broadcaster, &source, &signer, &logger);
+ let mut transaction_parameters = ChannelTransactionParameters::test_dummy(42_000_000);
+ transaction_parameters.channel_type_features =
+ ChannelTypeFeatures::anchors_zero_htlc_fee_and_dependencies();
+ let htlc_descriptors: Vec<_> = (0..2)
+ .map(|index| HTLCDescriptor {
+ channel_derivation_parameters: ChannelDerivationParameters {
+ value_satoshis: 42_000_000,
+ keys_id: [42; 32],
+ transaction_parameters: transaction_parameters.clone(),
+ },
+ commitment_txid: OutPoint::null().txid,
+ per_commitment_number: 0,
+ per_commitment_point: PublicKey::from_slice(&[2; 33]).unwrap(),
+ feerate_per_kw: 0,
+ htlc: HTLCOutputInCommitment {
+ offered: true,
+ amount_msat: 1_000_000,
+ cltv_expiry: 0,
+ payment_hash: crate::types::payment::PaymentHash([42; 32]),
+ transaction_output_index: Some(index),
+ },
+ preimage: None,
+ counterparty_sig: Signature::from_compact(&[42; 64]).unwrap(),
+ })
+ .collect();
+
+ // A failed two-HTLC batch must retry one HTLC, then either stop or claim both separately.
+ handler.handle_event(&BumpTransactionEvent::HTLCResolution {
+ channel_id: ChannelId([42; 32]),
+ counterparty_node_id: PublicKey::from_slice(&[2; 33]).unwrap(),
+ claim_id,
+ target_feerate_sat_per_1000_weight: 1000,
+ htlc_descriptors: htlc_descriptors.clone(),
+ tx_lock_time: LockTime::ZERO,
+ });
+ assert!(source.expected_selects.lock().unwrap().is_empty());
+ let transactions = broadcaster.txn_broadcast();
+ assert_eq!(transactions.len(), if fund_singletons { 2 } else { 0 });
+ for (tx, descriptor) in transactions.iter().zip(&htlc_descriptors) {
+ assert_eq!(tx.input.len(), 2);
+ assert_eq!(tx.input[0].previous_output, descriptor.outpoint());
+ assert!(!tx.input[0].witness.is_empty());
+ assert_eq!(tx.input[1].previous_output.txid, source.funding_tx.compute_txid());
+ assert_eq!(tx.input[1].previous_output.vout, descriptor.outpoint().vout);
+ assert_eq!(tx.output, vec![descriptor.tx_output(&Secp256k1::new())]);
+ }
+ }
+
+ #[test]
+ fn test_htlc_batch_retries_singleton() {
+ do_test_htlc_batch_retries_singleton(false);
+ }
+
+ #[test]
+ fn test_htlc_batch_broadcasts_singletons() {
+ do_test_htlc_batch_retries_singleton(true);
+ }
+
#[test]
fn test_utxo_new_v1_p2tr() {
// Transaction 33e794d097969002ee05d336686fc03c9e15a597c1b9827669460fac98799036Why this scored 37/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.