Skip to content

Use HTLC CLTV instead of onion CLTV values for payment claim timer #4402

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
TheBlueMatt wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Use HTLC CLTV instead of onion CLTV values for payment claim timer #4402

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
37e75e7
Use HTLC CLTV instead of onion CLTV values for payment claim timer
TheBlueMatt Feb 8, 2026
4867c30
Fix trampoline onion encoding to match doc-declared CLTV rules
TheBlueMatt Feb 8, 2026
ec8580b
Clarify CLTV value selection in the first blinded hop marginally
TheBlueMatt Feb 9, 2026
5ce6e42
Add a `Path::total_cltv_expiry_delta` accessor
TheBlueMatt Feb 9, 2026
54be6ef
Validate CLTV somewhat in `Route::debug_assert_route_meets_params`
TheBlueMatt Feb 9, 2026
e39437d
Rename `starting_htlc_offset` `cur_block_height` in onion building
TheBlueMatt Feb 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 46 additions & 43 deletions lightning/src/ln/blinded_payment_tests.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -981,23 +981,19 @@ fn do_multi_hop_receiver_fail(check: ReceiveCheckFail) {
};

let amt_msat = 5000;
let excess_final_cltv_delta_opt = if check == ReceiveCheckFail::ProcessPendingHTLCsCheck {
// Set the final CLTV expiry too low to trigger the failure in process_pending_htlc_forwards.
Some(TEST_FINAL_CLTV as u16 - 2)
let required_final_cltv = if check == ReceiveCheckFail::ProcessPendingHTLCsCheck {
// Set the final CLTV required much too high to trigger the failure in process_pending_htlc_forwards.
Some((TEST_FINAL_CLTV as u16) * 10)
} else { None };
let (_, payment_hash, payment_secret) = get_payment_preimage_hash(&nodes[2], Some(amt_msat), excess_final_cltv_delta_opt);
let (_, payment_hash, payment_secret) = get_payment_preimage_hash(&nodes[2], Some(amt_msat), required_final_cltv);
let mut route_params = get_blinded_route_parameters(amt_msat, payment_secret, 1, 1_0000_0000,
nodes.iter().skip(1).map(|n| n.node.get_our_node_id()).collect(), &[&chan_upd_1_2],
&chanmon_cfgs[2].keys_manager);

route_params.payment_params.max_path_length = 17;

let route = if check == ReceiveCheckFail::ProcessPendingHTLCsCheck {
let mut route = get_route(&nodes[0], &route_params).unwrap();
// Set the final CLTV expiry too low to trigger the failure in process_pending_htlc_forwards.
route.paths[0].hops.last_mut().map(|h| h.cltv_expiry_delta += excess_final_cltv_delta_opt.unwrap() as u32);
route.paths[0].blinded_tail.as_mut().map(|bt| bt.excess_final_cltv_expiry_delta = excess_final_cltv_delta_opt.unwrap() as u32);
route
get_route(&nodes[0], &route_params).unwrap()
} else if check == ReceiveCheckFail::PaymentConstraints {
// Create a blinded path where the receiver's encrypted payload has an htlc_minimum_msat that is
// violated by `amt_msat`, and stick it in the route_params without changing the corresponding
Expand Down Expand Up @@ -1115,7 +1111,6 @@ fn do_multi_hop_receiver_fail(check: ReceiveCheckFail) {
check_added_monitors(&nodes[2], 1);
},
ReceiveCheckFail::ProcessPendingHTLCsCheck => {
assert_eq!(payment_event_1_2.msgs[0].cltv_expiry, nodes[0].best_block_info().1 + 1 + excess_final_cltv_delta_opt.unwrap() as u32 + TEST_FINAL_CLTV);
nodes[2].node.handle_update_add_htlc(nodes[1].node.get_our_node_id(), &payment_event_1_2.msgs[0]);
check_added_monitors(&nodes[2], 0);
do_commitment_signed_dance(&nodes[2], &nodes[1], &payment_event_1_2.commitment_msg, true, true);
Expand Down Expand Up @@ -1857,7 +1852,7 @@ fn test_combined_trampoline_onion_creation_vectors() {
short_channel_id: (572330 << 40) + (42 << 16) + 2821,
channel_features: ChannelFeatures::empty(),
fee_msat: 153_000,
cltv_expiry_delta: 0,
cltv_expiry_delta: 24 + 36,
maybe_announced_channel: false,
},
],
Expand Down Expand Up @@ -1952,7 +1947,7 @@ fn test_trampoline_inbound_payment_decoding() {
short_channel_id: (572330 << 40) + (42 << 16) + 2821,
channel_features: ChannelFeatures::empty(),
fee_msat: 150_153_000,
cltv_expiry_delta: 0,
cltv_expiry_delta: 24 + 36,
maybe_announced_channel: false,
},
],
Expand Down Expand Up @@ -2120,7 +2115,7 @@ fn test_trampoline_forward_payload_encoded_as_receive() {
blinded_path::utils::construct_blinded_hops(
&secp_ctx, path.into_iter(), &trampoline_session_priv,
)
};
};

let route = Route {
paths: vec![Path {
Expand All @@ -2143,7 +2138,7 @@ fn test_trampoline_forward_payload_encoded_as_receive() {
short_channel_id: bob_carol_scid,
channel_features: ChannelFeatures::empty(),
fee_msat: 0,
cltv_expiry_delta: 48,
cltv_expiry_delta: 24 + 39,
maybe_announced_channel: false,
}
],
Expand All @@ -2154,7 +2149,7 @@ fn test_trampoline_forward_payload_encoded_as_receive() {
pubkey: carol_node_id,
node_features: Features::empty(),
fee_msat: amt_msat,
cltv_expiry_delta: 24,
cltv_expiry_delta: 24 + 39,
},
],
hops: carol_blinded_hops,
Expand All @@ -2181,7 +2176,7 @@ fn test_trampoline_forward_payload_encoded_as_receive() {
});

let recipient_onion_fields = RecipientOnionFields::spontaneous_empty(amt_msat);
let (mut trampoline_payloads, outer_total_msat, outer_starting_htlc_offset) = onion_utils::build_trampoline_onion_payloads(&blinded_tail, &recipient_onion_fields, 32, &None).unwrap();
let (mut trampoline_payloads, outer_total_msat) = onion_utils::build_trampoline_onion_payloads(&blinded_tail, &recipient_onion_fields, 32, &None).unwrap();

// pop the last dummy hop
trampoline_payloads.pop();
Expand All @@ -2196,7 +2191,7 @@ fn test_trampoline_forward_payload_encoded_as_receive() {
).unwrap();

let recipient_onion_fields = RecipientOnionFields::spontaneous_empty(outer_total_msat);
let (outer_payloads, _, _) = onion_utils::test_build_onion_payloads(&route.paths[0], &recipient_onion_fields, outer_starting_htlc_offset, &None, None, Some(trampoline_packet)).unwrap();
let (outer_payloads, _, _) = onion_utils::test_build_onion_payloads(&route.paths[0], &recipient_onion_fields, 32, &None, None, Some(trampoline_packet)).unwrap();
let outer_onion_keys = onion_utils::construct_onion_keys(&secp_ctx, &route.clone().paths[0], &outer_session_priv);
let outer_packet = onion_utils::construct_onion_packet(
outer_payloads,
Expand Down Expand Up @@ -2309,7 +2304,7 @@ fn do_test_trampoline_single_hop_receive(success: bool) {
short_channel_id: bob_carol_scid,
channel_features: ChannelFeatures::empty(),
fee_msat: 0,
cltv_expiry_delta: 48,
cltv_expiry_delta: 104 + 39,
maybe_announced_channel: false,
}
],
Expand All @@ -2320,7 +2315,7 @@ fn do_test_trampoline_single_hop_receive(success: bool) {
pubkey: carol_node_id,
node_features: Features::empty(),
fee_msat: amt_msat,
cltv_expiry_delta: 104,
cltv_expiry_delta: 104 + 39,
},
],
hops: blinded_path.blinded_hops().to_vec(),
Expand Down Expand Up @@ -2428,8 +2423,8 @@ fn test_trampoline_blinded_receive() {
/// Creates a blinded tail where Carol receives via a blinded path.
fn create_blinded_tail(
secp_ctx: &Secp256k1<All>, override_random_bytes: [u8; 32], carol_node_id: PublicKey,
carol_auth_key: ReceiveAuthKey, trampoline_cltv_expiry_delta: u32, final_value_msat: u64,
payment_secret: PaymentSecret,
carol_auth_key: ReceiveAuthKey, trampoline_cltv_expiry_delta: u32,
excess_final_cltv_delta: u32, final_value_msat: u64, payment_secret: PaymentSecret,
) -> BlindedTail {
let outer_session_priv = SecretKey::from_slice(&override_random_bytes).unwrap();
let trampoline_session_priv = onion_utils::compute_trampoline_session_priv(&outer_session_priv);
Expand Down Expand Up @@ -2460,11 +2455,11 @@ fn create_blinded_tail(
pubkey: carol_node_id,
node_features: Features::empty(),
fee_msat: final_value_msat,
cltv_expiry_delta: trampoline_cltv_expiry_delta,
cltv_expiry_delta: trampoline_cltv_expiry_delta + excess_final_cltv_delta,
}],
hops: carol_blinded_hops,
blinding_point: carol_blinding_point,
excess_final_cltv_expiry_delta: 39,
excess_final_cltv_expiry_delta: excess_final_cltv_delta,
final_value_msat,
}
}
Expand All @@ -2473,8 +2468,9 @@ fn create_blinded_tail(
// payloads that send to unblinded receives and invalid payloads.
fn replacement_onion(
test_case: TrampolineTestCase, secp_ctx: &Secp256k1<All>, override_random_bytes: [u8; 32],
route: Route, original_amt_msat: u64, starting_htlc_offset: u32, original_trampoline_cltv: u32,
payment_hash: PaymentHash, payment_secret: PaymentSecret, blinded: bool,
route: Route, original_amt_msat: u64, starting_htlc_offset: u32, excess_final_cltv: u32,
original_trampoline_cltv: u32, payment_hash: PaymentHash, payment_secret: PaymentSecret,
blinded: bool,
) -> msgs::OnionPacket {
let outer_session_priv = SecretKey::from_slice(&override_random_bytes[..]).unwrap();
let trampoline_session_priv = onion_utils::compute_trampoline_session_priv(&outer_session_priv);
Expand All @@ -2485,8 +2481,8 @@ fn replacement_onion(
// Rebuild our trampoline packet from the original route. If we want to test Carol receiving
// as an unblinded trampoline hop, we switch out her inner trampoline onion with a direct
// receive payload because LDK doesn't support unblinded trampoline receives.
let (trampoline_packet, outer_total_msat, outer_starting_htlc_offset) = {
let (mut trampoline_payloads, outer_total_msat, outer_starting_htlc_offset) =
let (trampoline_packet, outer_total_msat) = {
let (mut trampoline_payloads, outer_total_msat) =
onion_utils::build_trampoline_onion_payloads(
&blinded_tail,
&recipient_onion_fields,
Expand All @@ -2502,7 +2498,9 @@ fn replacement_onion(
total_msat: original_amt_msat,
}),
sender_intended_htlc_amt_msat: original_amt_msat,
cltv_expiry_height: original_trampoline_cltv + starting_htlc_offset,
cltv_expiry_height: original_trampoline_cltv
+ starting_htlc_offset
+ excess_final_cltv,
}];
}

Expand All @@ -2520,7 +2518,7 @@ fn replacement_onion(
)
.unwrap();

(trampoline_packet, outer_total_msat, outer_starting_htlc_offset)
(trampoline_packet, outer_total_msat)
};

// Use a different session key to construct the replacement onion packet. Note that the
Expand All @@ -2529,7 +2527,7 @@ fn replacement_onion(
let (mut outer_payloads, _, _) = onion_utils::test_build_onion_payloads(
&route.paths[0],
&recipient_onion_fields,
outer_starting_htlc_offset,
starting_htlc_offset,
&None,
None,
Some(trampoline_packet),
Expand All @@ -2547,7 +2545,7 @@ fn replacement_onion(
..
} => {
*amt_to_forward = test_case.outer_onion_amt(original_amt_msat);
let outer_cltv = original_trampoline_cltv + starting_htlc_offset;
let outer_cltv = original_trampoline_cltv + starting_htlc_offset + excess_final_cltv;
*outgoing_cltv_value = test_case.outer_onion_cltv(outer_cltv);
},
_ => panic!("final payload is not trampoline entrypoint"),
Expand Down Expand Up @@ -2582,11 +2580,9 @@ fn do_test_trampoline_relay(blinded: bool, test_case: TrampolineTestCase) {
let alice_bob_chan = create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 1_000_000, 0);
let bob_carol_chan = create_announced_chan_between_nodes_with_value(&nodes, 1, 2, 1_000_000, 0);

let starting_htlc_offset = (TOTAL_NODE_COUNT as u32) * CHAN_CONFIRM_DEPTH + 1;
for i in 0..TOTAL_NODE_COUNT {
connect_blocks(
&nodes[i],
(TOTAL_NODE_COUNT as u32) * CHAN_CONFIRM_DEPTH + 1 - nodes[i].best_block_info().1,
);
connect_blocks(&nodes[i], starting_htlc_offset - nodes[i].best_block_info().1);
}

let alice_node_id = nodes[0].node.get_our_node_id();
Expand All @@ -2597,8 +2593,11 @@ fn do_test_trampoline_relay(blinded: bool, test_case: TrampolineTestCase) {
let bob_carol_scid = get_scid_from_channel_id(&nodes[1], bob_carol_chan.2);

let original_amt_msat = 1000;
let original_trampoline_cltv = 72;
let starting_htlc_offset = 32;
// Note that for TrampolineTestCase::OuterCLTVLessThanTrampoline to work properly,
// (starting_htlc_offset + excess_final_cltv) / 2 < (starting_htlc_offset + excess_final_cltv + original_trampoline_cltv)
// otherwise dividing the CLTV value by 2 won't kick us under the outer trampoline CLTV.
let original_trampoline_cltv = 42;
let excess_final_cltv = 70;

let (payment_preimage, payment_hash, payment_secret) =
get_payment_preimage_hash(&nodes[2], Some(original_amt_msat), None);
Expand All @@ -2625,7 +2624,7 @@ fn do_test_trampoline_relay(blinded: bool, test_case: TrampolineTestCase) {
short_channel_id: bob_carol_scid,
channel_features: ChannelFeatures::empty(),
fee_msat: 0,
cltv_expiry_delta: 48,
cltv_expiry_delta: original_trampoline_cltv + excess_final_cltv,
maybe_announced_channel: false,
},
],
Expand All @@ -2638,6 +2637,7 @@ fn do_test_trampoline_relay(blinded: bool, test_case: TrampolineTestCase) {
carol_node_id,
nodes[2].keys_manager.get_receive_auth_key(),
original_trampoline_cltv,
excess_final_cltv,
original_amt_msat,
payment_secret,
)),
Expand Down Expand Up @@ -2680,6 +2680,7 @@ fn do_test_trampoline_relay(blinded: bool, test_case: TrampolineTestCase) {
original_amt_msat,
starting_htlc_offset,
original_trampoline_cltv,
excess_final_cltv,
payment_hash,
payment_secret,
blinded,
Expand All @@ -2696,8 +2697,9 @@ fn do_test_trampoline_relay(blinded: bool, test_case: TrampolineTestCase) {
);

let amt_bytes = test_case.outer_onion_amt(original_amt_msat).to_be_bytes();
let cltv_bytes =
test_case.outer_onion_cltv(original_trampoline_cltv + starting_htlc_offset).to_be_bytes();
let cltv_bytes = test_case
.outer_onion_cltv(original_trampoline_cltv + starting_htlc_offset + excess_final_cltv)
.to_be_bytes();
let payment_failure = test_case.payment_failed_conditions(&amt_bytes, &cltv_bytes).map(|p| {
if blinded {
PaymentFailedConditions::new()
Expand All @@ -2711,7 +2713,8 @@ fn do_test_trampoline_relay(blinded: bool, test_case: TrampolineTestCase) {
.without_claimable_event()
.expect_failure(HTLCHandlingFailureType::Receive { payment_hash })
} else {
args.with_payment_secret(payment_secret)
let htlc_cltv = starting_htlc_offset + original_trampoline_cltv + excess_final_cltv;
args.with_payment_secret(payment_secret).with_payment_claimable_cltv(htlc_cltv)
};

do_pass_along_path(args);
Expand Down Expand Up @@ -2797,7 +2800,7 @@ fn test_trampoline_forward_rejection() {
short_channel_id: bob_carol_scid,
channel_features: ChannelFeatures::empty(),
fee_msat: 0,
cltv_expiry_delta: 48,
cltv_expiry_delta: 24 + 24 + 39,
maybe_announced_channel: false,
}
],
Expand All @@ -2816,7 +2819,7 @@ fn test_trampoline_forward_rejection() {
pubkey: alice_node_id,
node_features: Features::empty(),
fee_msat: amt_msat,
cltv_expiry_delta: 24,
cltv_expiry_delta: 24 + 39,
},
],
hops: vec![BlindedHop{
Expand Down
15 changes: 14 additions & 1 deletion lightning/src/ln/functional_test_utils.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
//! nodes for functional tests.

use crate::blinded_path::payment::DummyTlvs;
use crate::chain::channelmonitor::ChannelMonitor;
use crate::chain::channelmonitor::{ChannelMonitor, HTLC_FAIL_BACK_BUFFER};
use crate::chain::transaction::OutPoint;
use crate::chain::{BestBlock, ChannelMonitorUpdateStatus, Confirm, Listen, Watch};
use crate::events::bump_transaction::sync::BumpTransactionEventHandlerSync;
Expand Down Expand Up @@ -3490,6 +3490,7 @@ pub struct PassAlongPathArgs<'a, 'b, 'c, 'd> {
pub custom_tlvs: Vec<(u64, Vec<u8>)>,
pub payment_metadata: Option<Vec<u8>>,
pub expected_failure: Option<HTLCHandlingFailureType>,
pub payment_claimable_cltv: Option<u32>,
}

impl<'a, 'b, 'c, 'd> PassAlongPathArgs<'a, 'b, 'c, 'd> {
Expand All @@ -3512,6 +3513,7 @@ impl<'a, 'b, 'c, 'd> PassAlongPathArgs<'a, 'b, 'c, 'd> {
custom_tlvs: Vec::new(),
payment_metadata: None,
expected_failure: None,
payment_claimable_cltv: None,
}
}
pub fn without_clearing_recipient_events(mut self) -> Self {
Expand Down Expand Up @@ -3552,6 +3554,10 @@ impl<'a, 'b, 'c, 'd> PassAlongPathArgs<'a, 'b, 'c, 'd> {
self.dummy_tlvs = dummy_tlvs.to_vec();
self
}
pub fn with_payment_claimable_cltv(mut self, cltv: u32) -> Self {
self.payment_claimable_cltv = Some(cltv);
self
}
}

pub fn do_pass_along_path<'a, 'b, 'c>(args: PassAlongPathArgs) -> Option<Event> {
Expand All @@ -3570,6 +3576,7 @@ pub fn do_pass_along_path<'a, 'b, 'c>(args: PassAlongPathArgs) -> Option<Event>
custom_tlvs,
payment_metadata,
expected_failure,
payment_claimable_cltv,
} = args;

let mut payment_event = SendEvent::from_event(ev);
Expand Down Expand Up @@ -3685,6 +3692,12 @@ pub fn do_pass_along_path<'a, 'b, 'c>(args: PassAlongPathArgs) -> Option<Event>
assert_eq!(*user_chan_id, Some(chan.user_channel_id));
}
assert!(claim_deadline.unwrap() > node.best_block_info().1);
if let Some(expected_cltv) = payment_claimable_cltv {
assert_eq!(
claim_deadline.unwrap(),
expected_cltv - HTLC_FAIL_BACK_BUFFER,
);
}
},
_ => panic!("Unexpected event"),
}
Expand Down
3 changes: 2 additions & 1 deletion lightning/src/ln/htlc_reserve_unit_tests.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1429,9 +1429,10 @@ pub fn test_update_add_htlc_bolt2_sender_cltv_expiry_too_high() {

let _chan = create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 1000000, 0);

let payment_params = PaymentParameters::from_node_id(node_b_id, 0)
let mut payment_params = PaymentParameters::from_node_id(node_b_id, 0)
.with_bolt11_features(nodes[1].node.bolt11_invoice_features())
.unwrap();
payment_params.max_total_cltv_expiry_delta = 500000001;
let (mut route, our_payment_hash, _, our_payment_secret) =
get_route_and_payment_hash!(nodes[0], nodes[1], payment_params, 100000000);
route.paths[0].hops.last_mut().unwrap().cltv_expiry_delta = 500000001;
Expand Down
6 changes: 3 additions & 3 deletions lightning/src/ln/onion_payment.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -438,7 +438,7 @@ pub(super) fn create_recv_pending_htlc_info(
payment_data,
payment_preimage,
payment_metadata,
incoming_cltv_expiry: onion_cltv_expiry,
incoming_cltv_expiry: cltv_expiry,
custom_tlvs,
requires_blinded_error,
has_recipient_created_payment_secret,
Expand All @@ -450,7 +450,7 @@ pub(super) fn create_recv_pending_htlc_info(
payment_data: data,
payment_metadata,
payment_context,
incoming_cltv_expiry: onion_cltv_expiry,
incoming_cltv_expiry: cltv_expiry,
phantom_shared_secret,
trampoline_shared_secret,
custom_tlvs,
Expand Down Expand Up @@ -842,7 +842,7 @@ mod tests {
PendingHTLCRouting::ReceiveKeysend { payment_preimage, payment_data, incoming_cltv_expiry, .. } => {
assert_eq!(payment_preimage, preimage);
assert_eq!(peeled2.outgoing_amt_msat, recipient_amount);
assert_eq!(incoming_cltv_expiry, peeled2.outgoing_cltv_value);
assert_eq!(incoming_cltv_expiry, msg.cltv_expiry);
let msgs::FinalOnionHopData{total_msat, payment_secret} = payment_data.unwrap();
assert_eq!(total_msat, total_amt_msat);
assert_eq!(payment_secret, pay_secret);
Expand Down
Loading
Loading