Skip to content

Introduce Realistic constraints for Dummy Hops #4501

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
shaavan wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Introduce Realistic constraints for Dummy Hops #4501

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
d14446b
Return dummy-hop-specific error on blinded-forward underflow
shaavan Mar 12, 2026
125c69e
Track dummy-hop skimmed fees through receive handling
shaavan Mar 12, 2026
0c0f741
Account for dummy-hop fees in payment test helpers
shaavan Mar 12, 2026
9c0de90
Use realistic dummy-hop defaults in blinded path admission
shaavan Mar 12, 2026
3372b44
Test payinfo handling for dummy-hop blinded paths
shaavan Mar 21, 2026
942e455
Make `BlindedPaymentPath::new_with_dummy_hops` public
shaavan Mar 21, 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
98 changes: 75 additions & 23 deletions lightning/src/blinded_path/payment.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,6 @@ impl BlindedPaymentPath {
/// Errors if:
/// * [`BlindedPayInfo`] calculation results in an integer overflow
/// * any unknown features are required in the provided [`ForwardTlvs`]
// TODO: make all payloads the same size with padding + add dummy hops
pub fn new<ES: EntropySource, T: secp256k1::Signing + secp256k1::Verification>(
intermediate_nodes: &[PaymentForwardNode], payee_node_id: PublicKey,
local_node_receive_key: ReceiveAuthKey, payee_tlvs: ReceiveTlvs, htlc_maximum_msat: u64,
Expand All @@ -136,10 +135,7 @@ impl BlindedPaymentPath {
///
/// This improves privacy by making path-length analysis based on fee and CLTV delta
/// values less reliable.
///
/// TODO: Add end-to-end tests validating fee aggregation, CLTV deltas, and
/// HTLC bounds when dummy hops are present, before exposing this API publicly.
pub(crate) fn new_with_dummy_hops<
pub fn new_with_dummy_hops<
ES: EntropySource,
T: secp256k1::Signing + secp256k1::Verification,
>(
Expand Down Expand Up @@ -392,15 +388,57 @@ pub struct DummyTlvs {
pub payment_constraints: PaymentConstraints,
}

impl Default for DummyTlvs {
fn default() -> Self {
let payment_relay =
PaymentRelay { cltv_expiry_delta: 0, fee_proportional_millionths: 0, fee_base_msat: 0 };
// Default parameters used for dummy hops in blinded paths.
//
// These values are chosen to resemble typical forwarding hops while remaining
// stable and predictable for tests.

/// Adds a realistic but stable CLTV cost per dummy hop.
///
/// The router folds this into the blinded path's advertised CLTV delta, so it must
/// be non-trivial enough to model hidden relay latency while remaining predictable
/// for tests and callers reasoning about timeout budgets.
pub(crate) const DEFAULT_DUMMY_HOP_CLTV_EXPIRY_DELTA: u16 = 80;
Copy link
Copy Markdown
Collaborator

@TheBlueMatt TheBlueMatt Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm, yea, I don't think this is quite sufficient sadly. I think what we should do is actually round up fees for normal hops within some threshold buckets (like we do for CLTVs already) and then pick constants from there. Right now nodes are likely to have relatively precise fee amounts and we'll set those explicitly on the path and then pick these constants for the dummy hops, revealing that they're dummy. I feel like we should use the previous hop's feerate if its "low" and otherwise pick the most common on the network today, which are:

 fee_base_msat | fee_proportional_millionths | channel_count
---------------+-----------------------------+---------------
          1000 |                           1 |        151157
             0 |                           0 |         55688
             0 |                         500 |         50607
    2147483647 |                  2147483647 |         45806
             0 |                           1 |         23804
             0 |                         100 |         20417
          1000 |                           0 |         18224
          1000 |                          10 |         16224
          1000 |                         499 |         14838
             0 |                        1000 |         14703
             0 |                          10 |         12683
          1000 |                        1000 |         12060
          1000 |                         100 |         10609
          1000 |                        2500 |          9680
             0 |                          50 |          7898
             0 |                           5 |          6254
          1000 |                         200 |          6113
          1000 |                         500 |          6101
             0 |                         200 |          5522
             0 |                          20 |          4658
(20 rows)


/// Keeps dummy-hop fee aggregation linear and deterministic.
///
/// A non-zero proportional fee would compound across dummy hops and introduce rounding
/// effects into blinded payinfo. The base fee still makes dummy hops look like plausible relays.
pub(crate) const DEFAULT_DUMMY_HOP_FEE_PROPORTIONAL_MILLIONTHS: u32 = 0;

/// Matches the default relay base fee used by the standard test channel configuration.
///
/// This keeps dummy hops aligned with typical forwarding hops in tests rather than
/// making them appear unrealistically cheap or expensive.
pub(crate) const DEFAULT_DUMMY_HOP_FEE_BASE_MSAT: u32 = 1000;

/// Leaves the dummy hop's absolute CLTV ceiling effectively unbounded by default.
///
/// `PaymentConstraints::max_cltv_expiry` is interpreted as an absolute block height, so using a
/// fixed low value here would cause dummy hops to reject otherwise-valid payments on live chains.
pub(crate) const DEFAULT_DUMMY_HOP_MAX_CLTV_EXPIRY: u32 = u32::MAX;

let payment_constraints =
PaymentConstraints { max_cltv_expiry: u32::MAX, htlc_minimum_msat: 0 };
/// Matches the default test channel HTLC minimum.
///
/// The router takes the max of the introduction node's inbound HTLC minimum and this value,
/// so keeping them aligned prevents dummy hops from unexpectedly tightening or loosening
/// admission.
pub(crate) const DEFAULT_DUMMY_HOP_HTLC_MINIMUM_MSAT: u64 = 1000;

Self { payment_relay, payment_constraints }
impl Default for DummyTlvs {
/// Returns the documented default relay requirements and constraints for synthetic hops.
fn default() -> Self {
Self {
payment_relay: PaymentRelay {
cltv_expiry_delta: DEFAULT_DUMMY_HOP_CLTV_EXPIRY_DELTA,
fee_proportional_millionths: DEFAULT_DUMMY_HOP_FEE_PROPORTIONAL_MILLIONTHS,
fee_base_msat: DEFAULT_DUMMY_HOP_FEE_BASE_MSAT,
},
payment_constraints: PaymentConstraints {
max_cltv_expiry: DEFAULT_DUMMY_HOP_MAX_CLTV_EXPIRY,
htlc_minimum_msat: DEFAULT_DUMMY_HOP_HTLC_MINIMUM_MSAT,
},
}
}
}

Expand Down Expand Up @@ -791,6 +829,20 @@ pub(crate) fn amt_to_forward_msat(
u64::try_from(amt_to_forward).ok()
}

pub(crate) fn compute_next_htlc_minimum_msat(
htlc_minimum_msat: u64, payment_constraints: &PaymentConstraints, payment_relay: &PaymentRelay,
) -> u64 {
// Fold the next hop's minimum backwards through its relay fees to recover the minimum amount the
// previous hop must receive.
amt_to_forward_msat(
core::cmp::max(payment_constraints.htlc_minimum_msat, htlc_minimum_msat),
payment_relay,
)
// If reversing the fee calculation would require less than 1 msat, clamp to 1 since any
// positive incoming amount already satisfies the next hop's minimum once fees are accounted for.
.unwrap_or(1)
}

// Returns (aggregated_base_fee, aggregated_proportional_fee)
pub(crate) fn compute_aggregated_base_prop_fee<I>(hops_fees: I) -> Result<(u64, u64), ()>
where
Expand Down Expand Up @@ -854,14 +906,14 @@ pub(super) fn compute_payinfo(
cltv_expiry_delta =
cltv_expiry_delta.checked_add(node.tlvs.payment_relay.cltv_expiry_delta).ok_or(())?;

// The min htlc for an intermediate node is that node's min minus the fees charged by all of the
// following hops for forwarding that min, since that fee amount will automatically be included
// in the amount that this node receives and contribute towards reaching its min.
htlc_minimum_msat = amt_to_forward_msat(
core::cmp::max(node.tlvs.payment_constraints.htlc_minimum_msat, htlc_minimum_msat),
// The min htlc for an intermediate node is that node's min minus the fees charged by all of
// the following hops for forwarding that min, since that fee amount will automatically be
// included in the amount that this node receives and contribute towards reaching its min.
htlc_minimum_msat = compute_next_htlc_minimum_msat(
htlc_minimum_msat,
&node.tlvs.payment_constraints,
&node.tlvs.payment_relay,
)
.unwrap_or(1); // If underflow occurs, we definitely reached this node's min
);
htlc_maximum_msat = amt_to_forward_msat(
core::cmp::min(node.htlc_maximum_msat, htlc_maximum_msat),
&node.tlvs.payment_relay,
Expand All @@ -872,11 +924,11 @@ pub(super) fn compute_payinfo(
cltv_expiry_delta =
cltv_expiry_delta.checked_add(dummy_tlvs.payment_relay.cltv_expiry_delta).ok_or(())?;

htlc_minimum_msat = amt_to_forward_msat(
core::cmp::max(dummy_tlvs.payment_constraints.htlc_minimum_msat, htlc_minimum_msat),
htlc_minimum_msat = compute_next_htlc_minimum_msat(
htlc_minimum_msat,
&dummy_tlvs.payment_constraints,
&dummy_tlvs.payment_relay,
)
.unwrap_or(1); // If underflow occurs, we definitely reached this node's min
);
}
htlc_minimum_msat =
core::cmp::max(payee_tlvs.payment_constraints.htlc_minimum_msat, htlc_minimum_msat);
Expand Down
32 changes: 32 additions & 0 deletions lightning/src/events/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -902,6 +902,12 @@ pub enum Event {
///
/// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs
amount_msat: u64,
/// The additional skimmed fee, in thousandths of a satoshi, that the receiver earns from
/// dummy hops preceding the final receipt, in addition to the `amount_msat`.
///
/// For backwards compatibility with older LDK versions where this TLV was not serialized,
/// this defaults to 0 when absent.
dummy_hops_skimmed_fee_msat: u64,
/// The value, in thousands of a satoshi, that was skimmed off of this payment as an extra fee
/// taken by our channel counterparty.
///
Expand Down Expand Up @@ -965,6 +971,12 @@ pub enum Event {
/// The value, in thousandths of a satoshi, that this payment is for. May be greater than the
/// invoice amount.
amount_msat: u64,
/// The additional skimmed fee, in thousandths of a satoshi, that the receiver earns from
/// dummy hops preceding the final receipt, in addition to the `amount_msat`.
///
/// For backwards compatibility with older LDK versions where this TLV was not serialized,
/// this defaults to 0 when absent.
dummy_hops_skimmed_fee_msat: u64,
/// The purpose of the claimed payment, i.e. whether the payment was for an invoice or a
/// spontaneous payment.
purpose: PaymentPurpose,
Expand Down Expand Up @@ -1891,6 +1903,7 @@ impl Writeable for Event {
&Event::PaymentClaimable {
ref payment_hash,
ref amount_msat,
dummy_hops_skimmed_fee_msat,
counterparty_skimmed_fee_msat,
ref purpose,
ref receiver_node_id,
Expand Down Expand Up @@ -1938,6 +1951,11 @@ impl Writeable for Event {
} else {
Some(counterparty_skimmed_fee_msat)
};
let dummy_skimmed_fee_opt = if dummy_hops_skimmed_fee_msat == 0 {
None
} else {
Some(dummy_hops_skimmed_fee_msat)
};

let (receiving_channel_id_legacy, receiving_user_channel_id_legacy) =
match receiving_channel_ids.last() {
Expand All @@ -1964,6 +1982,7 @@ impl Writeable for Event {
(11, payment_context, option),
(13, payment_id, option),
(15, *receiving_channel_ids, optional_vec),
(17, dummy_skimmed_fee_opt, option),
});
},
&Event::PaymentSent {
Expand Down Expand Up @@ -2189,6 +2208,7 @@ impl Writeable for Event {
&Event::PaymentClaimed {
ref payment_hash,
ref amount_msat,
dummy_hops_skimmed_fee_msat,
ref purpose,
ref receiver_node_id,
ref htlcs,
Expand All @@ -2197,6 +2217,11 @@ impl Writeable for Event {
ref payment_id,
} => {
19u8.write(writer)?;
let dummy_skimmed_fee_opt = if dummy_hops_skimmed_fee_msat == 0 {
None
} else {
Some(dummy_hops_skimmed_fee_msat)
};
write_tlv_fields!(writer, {
(0, payment_hash, required),
(1, receiver_node_id, option),
Expand All @@ -2206,6 +2231,7 @@ impl Writeable for Event {
(7, sender_intended_total_msat, option),
(9, onion_fields, option),
(11, payment_id, option),
(13, dummy_skimmed_fee_opt, option),
});
},
&Event::ProbeSuccessful { ref payment_id, ref payment_hash, ref path } => {
Expand Down Expand Up @@ -2407,6 +2433,7 @@ impl MaybeReadable for Event {
let mut payment_preimage = None;
let mut payment_secret = None;
let mut amount_msat = 0;
let mut dummy_skimmed_fee_msat_opt = None;
let mut counterparty_skimmed_fee_msat_opt = None;
let mut receiver_node_id = None;
let mut _user_payment_id = None::<u64>; // Used in 0.0.103 and earlier, no longer written in 0.0.116+.
Expand All @@ -2432,6 +2459,7 @@ impl MaybeReadable for Event {
(11, payment_context, option),
(13, payment_id, option),
(15, receiving_channel_ids_opt, optional_vec),
(17, dummy_skimmed_fee_msat_opt, option),
});
let purpose = match payment_secret {
Some(secret) => {
Expand All @@ -2455,6 +2483,7 @@ impl MaybeReadable for Event {
receiver_node_id,
payment_hash,
amount_msat,
dummy_hops_skimmed_fee_msat: dummy_skimmed_fee_msat_opt.unwrap_or(0),
counterparty_skimmed_fee_msat: counterparty_skimmed_fee_msat_opt
.unwrap_or(0),
purpose,
Expand Down Expand Up @@ -2760,6 +2789,7 @@ impl MaybeReadable for Event {
let mut payment_hash = PaymentHash([0; 32]);
let mut purpose = UpgradableRequired(None);
let mut amount_msat = 0;
let mut dummy_hops_skimmed_fee_msat_opt = None;
let mut receiver_node_id = None;
let mut htlcs: Option<Vec<ClaimedHTLC>> = Some(vec![]);
let mut sender_intended_total_msat: Option<u64> = None;
Expand All @@ -2775,12 +2805,14 @@ impl MaybeReadable for Event {
(9, onion_fields, (option: ReadableArgs,
sender_intended_total_msat.unwrap_or(amount_msat))),
(11, payment_id, option),
(13, dummy_hops_skimmed_fee_msat_opt, option),
});
Ok(Some(Event::PaymentClaimed {
receiver_node_id,
payment_hash,
purpose: _init_tlv_based_struct_field!(purpose, upgradable_required),
amount_msat,
dummy_hops_skimmed_fee_msat: dummy_hops_skimmed_fee_msat_opt.unwrap_or(0),
htlcs: htlcs.unwrap_or_default(),
sender_intended_total_msat,
onion_fields,
Expand Down
Loading
Loading