Improve router logging and update documentation#2436

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

Merged
jkczyz merged 2 commits into from
Jul 21, 2023
Merged

Improve router logging and update documentation #2436

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
543c5bf
Update outdated `router.rs` docs
tnull Jul 18, 2023
1db53a9
Improve logging for ignored candiate hops
tnull Jul 18, 2023
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
91 changes: 67 additions & 24 deletions lightning/src/routing/router.rs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -82,13 +82,21 @@ impl< G: Deref<Target = NetworkGraph<L>>, L: Deref, S: Deref, SP: Sized, Sc: Sco

/// A trait defining behavior for routing a payment.
pub trait Router {
/// Finds a [`Route`] between `payer` and `payee` for a payment with the given values.
/// Finds a [`Route`] for a payment between the given `payer` and a payee.
///
/// The `payee` and the payment's value are given in [`RouteParameters::payment_params`]
/// and [`RouteParameters::final_value_msat`], respectively.
fn find_route(
&self, payer: &PublicKey, route_params: &RouteParameters,
first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InFlightHtlcs
) -> Result<Route, LightningError>;
/// Finds a [`Route`] between `payer` and `payee` for a payment with the given values. Includes
/// `PaymentHash` and `PaymentId` to be able to correlate the request with a specific payment.
/// Finds a [`Route`] for a payment between the given `payer` and a payee.
///
/// The `payee` and the payment's value are given in [`RouteParameters::payment_params`]
/// and [`RouteParameters::final_value_msat`], respectively.
///
/// Includes a [`PaymentHash`] and a [`PaymentId`] to be able to correlate the request with a specific
/// payment.
fn find_route_with_id(
&self, payer: &PublicKey, route_params: &RouteParameters,
first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InFlightHtlcs,
Expand DownExpand Up@@ -346,19 +354,17 @@ pub struct Route {
/// [`BlindedTail`]s are present, then the pubkey of the last [`RouteHop`] in each path must be
/// the same.
pub paths: Vec<Path>,
/// The `payment_params` parameter passed to [`find_route`].
/// This is used by `ChannelManager` to track information which may be required for retries,
/// provided back to you via [`Event::PaymentPathFailed`].
/// The `payment_params` parameter passed via [`RouteParameters`] to [`find_route`].
///
/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
/// This is used by `ChannelManager` to track information which may be required for retries.
pub payment_params: Option<PaymentParameters>,
}

impl Route {
/// Returns the total amount of fees paid on this [`Route`].
///
/// This doesn't include any extra payment made to the recipient, which can happen in excess of
/// the amount passed to [`find_route`]'s `params.final_value_msat`.
/// the amount passed to [`find_route`]'s `route_params.final_value_msat`.
pub fn get_total_fees(&self) -> u64 {
self.paths.iter().map(|path| path.fee_msat()).sum()
}
Expand DownExpand Up@@ -436,10 +442,7 @@ impl Readable for Route {

/// Parameters needed to find a [`Route`].
///
/// Passed to [`find_route`] and [`build_route_from_hops`], but also provided in
/// [`Event::PaymentPathFailed`].
///
/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
/// Passed to [`find_route`] and [`build_route_from_hops`].
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RouteParameters {
/// The parameters of the failed payment path.
Expand DownExpand Up@@ -1330,6 +1333,14 @@ impl<'a> fmt::Display for LoggedCandidateHop<'a> {
" and blinding point ".fmt(f)?;
hint.1.blinding_point.fmt(f)
},
CandidateRouteHop::FirstHop { .. } => {
"first hop with SCID ".fmt(f)?;
self.0.short_channel_id().unwrap().fmt(f)
},
CandidateRouteHop::PrivateHop { .. } => {
"route hint with SCID ".fmt(f)?;
self.0.short_channel_id().unwrap().fmt(f)
},
_ => {
"SCID ".fmt(f)?;
self.0.short_channel_id().unwrap().fmt(f)
Expand DownExpand Up@@ -1375,10 +1386,12 @@ fn sort_first_hop_channels(

/// Finds a route from us (payer) to the given target node (payee).
///
/// If the payee provided features in their invoice, they should be provided via `params.payee`.
/// If the payee provided features in their invoice, they should be provided via the `payee` field
/// in the given [`RouteParameters::payment_params`].
/// Without this, MPP will only be used if the payee's features are available in the network graph.
///
/// Private routing paths between a public node and the target may be included in `params.payee`.
/// Private routing paths between a public node and the target may be included in the `payee` field
/// of [`RouteParameters::payment_params`].
///
/// If some channels aren't announced, it may be useful to fill in `first_hops` with the results
/// from [`ChannelManager::list_usable_channels`]. If it is filled in, the view of these channels
Expand All@@ -1388,15 +1401,9 @@ fn sort_first_hop_channels(
/// However, the enabled/disabled bit on such channels as well as the `htlc_minimum_msat` /
/// `htlc_maximum_msat` *are* checked as they may change based on the receiving node.
///
/// # Note
///
/// May be used to re-compute a [`Route`] when handling a [`Event::PaymentPathFailed`]. Any
/// adjustments to the [`NetworkGraph`] and channel scores should be made prior to calling this
/// function.
///
/// # Panics
///
/// Panics if first_hops contains channels without short_channel_ids;
/// Panics if first_hops contains channels without `short_channel_id`s;
/// [`ChannelManager::list_usable_channels`] will never include such channels.
///
/// [`ChannelManager::list_usable_channels`]: crate::ln::channelmanager::ChannelManager::list_usable_channels
Expand DownExpand Up@@ -1641,6 +1648,12 @@ where L::Target: Logger {
log_trace!(logger, "Building path from {} to payer {} for value {} msat.",
LoggedPayeePubkey(payment_params.payee.node_id()), our_node_pubkey, final_value_msat);

// Remember how many candidates we ignored to allow for some logging afterwards.
let mut num_ignored_value_contribution = 0;
let mut num_ignored_path_length_limit = 0;
let mut num_ignored_cltv_delta_limit = 0;
let mut num_ignored_previously_failed = 0;

macro_rules! add_entry {
// Adds entry which goes from $src_node_id to $dest_node_id over the $candidate hop.
// $next_hops_fee_msat represents the fees paid for using all the channels *after* this one,
Expand DownExpand Up@@ -1715,13 +1728,37 @@ where L::Target: Logger {
let payment_failed_on_this_channel = scid_opt.map_or(false,
|scid| payment_params.previously_failed_channels.contains(&scid));

let should_log_candidate = match $candidate {
CandidateRouteHop::FirstHop { .. } => true,
CandidateRouteHop::PrivateHop { .. } => true,
CandidateRouteHop::Blinded { .. } => true,
_ => false,
};

// If HTLC minimum is larger than the amount we're going to transfer, we shouldn't
// bother considering this channel. If retrying with recommended_value_msat may
// allow us to hit the HTLC minimum limit, set htlc_minimum_limit so that we go
// around again with a higher amount.
if !contributes_sufficient_value || exceeds_max_path_length ||
exceeds_cltv_delta_limit || payment_failed_on_this_channel {
// Path isn't useful, ignore it and move on.
if !contributes_sufficient_value {
if should_log_candidate {
log_trace!(logger, "Ignoring {} due to insufficient value contribution.", LoggedCandidateHop(&$candidate));
}
num_ignored_value_contribution += 1;
} else if exceeds_max_path_length {
if should_log_candidate {
log_trace!(logger, "Ignoring {} due to exceeding maximum path length limit.", LoggedCandidateHop(&$candidate));
}
num_ignored_path_length_limit += 1;
} else if exceeds_cltv_delta_limit {
if should_log_candidate {
log_trace!(logger, "Ignoring {} due to exceeding CLTV delta limit.", LoggedCandidateHop(&$candidate));
}
num_ignored_cltv_delta_limit += 1;
} else if payment_failed_on_this_channel {
if should_log_candidate {
log_trace!(logger, "Ignoring {} due to a failed previous payment attempt.", LoggedCandidateHop(&$candidate));
}
num_ignored_previously_failed += 1;
} else if may_overpay_to_meet_path_minimum_msat {
hit_minimum_limit = true;
} else if over_path_minimum_msat {
Expand DownExpand Up@@ -2323,6 +2360,12 @@ where L::Target: Logger {
}
}

let num_ignored_total = num_ignored_value_contribution + num_ignored_path_length_limit +
num_ignored_cltv_delta_limit + num_ignored_previously_failed;
if num_ignored_total > 0 {
log_trace!(logger, "Ignored {} candidate hops due to insufficient value contribution, {} due to path length limit, {} due to CLTV delta limit, {} due to previous payment failure. Total: {} ignored candidates.", num_ignored_value_contribution, num_ignored_path_length_limit, num_ignored_cltv_delta_limit, num_ignored_previously_failed, num_ignored_total);
}

// Step (5).
if payment_paths.len() == 0 {
return Err(LightningError{err: "Failed to find a path to the given destination".to_owned(), action: ErrorAction::IgnoreError});
Expand Down
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
Improve router logging and update documentation#2436

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

 Merged

jkczyz
merged 2 commits into

from

Jul 21, 2023
 Merged


Improve router logging and update documentation
#2436
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
543c5bf

Update outdated `router.rs` docs


tnull Jul 18, 2023
1db53a9

Improve logging for ignored candiate hops


tnull Jul 18, 2023

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


91 changes: 67 additions & 24 deletions
lightning/src/routing/router.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -82,13 +82,21 @@ impl< G: Deref<Target = NetworkGraph<L>>, L: Deref, S: Deref, SP: Sized, Sc: Sco

/// A trait defining behavior for routing a payment.
pub trait Router {
	/// Finds a [`Route`] between `payer` and `payee` for a payment with the given values.
	/// Finds a [`Route`] for a payment between the given `payer` and a payee.
	///
	/// The `payee` and the payment's value are given in [`RouteParameters::payment_params`]
	/// and [`RouteParameters::final_value_msat`], respectively.
	fn find_route(
 &self, payer: &PublicKey, route_params: &RouteParameters,
 first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InFlightHtlcs
	) -> Result<Route, LightningError>;
	/// Finds a [`Route`] between `payer` and `payee` for a payment with the given values. Includes
	/// `PaymentHash` and `PaymentId` to be able to correlate the request with a specific payment.
	/// Finds a [`Route`] for a payment between the given `payer` and a payee.
	///
	/// The `payee` and the payment's value are given in [`RouteParameters::payment_params`]
	/// and [`RouteParameters::final_value_msat`], respectively.
	///
	/// Includes a [`PaymentHash`] and a [`PaymentId`] to be able to correlate the request with a specific
	/// payment.
	fn find_route_with_id(
 &self, payer: &PublicKey, route_params: &RouteParameters,
 first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InFlightHtlcs,
Expand DownExpand Up@@ -346,19 +354,17 @@ pub struct Route {
	/// [`BlindedTail`]s are present, then the pubkey of the last [`RouteHop`] in each path must be
	/// the same.
	pub paths: Vec<Path>,
	/// The `payment_params` parameter passed to [`find_route`].
	/// This is used by `ChannelManager` to track information which may be required for retries,
	/// provided back to you via [`Event::PaymentPathFailed`].
	/// The `payment_params` parameter passed via [`RouteParameters`] to [`find_route`].
	///
	/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
	/// This is used by `ChannelManager` to track information which may be required for retries.
	pub payment_params: Option<PaymentParameters>,
}

impl Route {
	/// Returns the total amount of fees paid on this [`Route`].
	///
	/// This doesn't include any extra payment made to the recipient, which can happen in excess of
	/// the amount passed to [`find_route`]'s `params.final_value_msat`.
	/// the amount passed to [`find_route`]'s `route_params.final_value_msat`.
	pub fn get_total_fees(&self) -> u64 {
 self.paths.iter().map(|path| path.fee_msat()).sum()
	}
Expand DownExpand Up@@ -436,10 +442,7 @@ impl Readable for Route {

/// Parameters needed to find a [`Route`].
///
/// Passed to [`find_route`] and [`build_route_from_hops`], but also provided in
/// [`Event::PaymentPathFailed`].
///
/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
/// Passed to [`find_route`] and [`build_route_from_hops`].
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RouteParameters {
	/// The parameters of the failed payment path.
Expand DownExpand Up@@ -1330,6 +1333,14 @@ impl<'a> fmt::Display for LoggedCandidateHop<'a> {
 " and blinding point ".fmt(f)?;
 hint.1.blinding_point.fmt(f)
 },
 CandidateRouteHop::FirstHop { .. } => {
 "first hop with SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
 },
 CandidateRouteHop::PrivateHop { .. } => {
 "route hint with SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
 },
 _ => {
 "SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
Expand DownExpand Up@@ -1375,10 +1386,12 @@ fn sort_first_hop_channels(

/// Finds a route from us (payer) to the given target node (payee).
///
/// If the payee provided features in their invoice, they should be provided via `params.payee`.
/// If the payee provided features in their invoice, they should be provided via the `payee` field
/// in the given [`RouteParameters::payment_params`].
/// Without this, MPP will only be used if the payee's features are available in the network graph.
///
/// Private routing paths between a public node and the target may be included in `params.payee`.
/// Private routing paths between a public node and the target may be included in the `payee` field
/// of [`RouteParameters::payment_params`].
///
/// If some channels aren't announced, it may be useful to fill in `first_hops` with the results
/// from [`ChannelManager::list_usable_channels`]. If it is filled in, the view of these channels
Expand All@@ -1388,15 +1401,9 @@ fn sort_first_hop_channels(
/// However, the enabled/disabled bit on such channels as well as the `htlc_minimum_msat` /
/// `htlc_maximum_msat` *are* checked as they may change based on the receiving node.
///
/// # Note
///
/// May be used to re-compute a [`Route`] when handling a [`Event::PaymentPathFailed`]. Any
/// adjustments to the [`NetworkGraph`] and channel scores should be made prior to calling this
/// function.
///
/// # Panics
///
/// Panics if first_hops contains channels without short_channel_ids;
/// Panics if first_hops contains channels without `short_channel_id`s;
/// [`ChannelManager::list_usable_channels`] will never include such channels.
///
/// [`ChannelManager::list_usable_channels`]: crate::ln::channelmanager::ChannelManager::list_usable_channels
Expand DownExpand Up@@ -1641,6 +1648,12 @@ where L::Target: Logger {
	log_trace!(logger, "Building path from {} to payer {} for value {} msat.",
 LoggedPayeePubkey(payment_params.payee.node_id()), our_node_pubkey, final_value_msat);

	// Remember how many candidates we ignored to allow for some logging afterwards.
	let mut num_ignored_value_contribution = 0;
	let mut num_ignored_path_length_limit = 0;
	let mut num_ignored_cltv_delta_limit = 0;
	let mut num_ignored_previously_failed = 0;

	macro_rules! add_entry {
 // Adds entry which goes from $src_node_id to $dest_node_id over the $candidate hop.
 // $next_hops_fee_msat represents the fees paid for using all the channels *after* this one,
Expand DownExpand Up@@ -1715,13 +1728,37 @@ where L::Target: Logger {
 let payment_failed_on_this_channel = scid_opt.map_or(false,
 |scid| payment_params.previously_failed_channels.contains(&scid));

 let should_log_candidate = match $candidate {
 CandidateRouteHop::FirstHop { .. } => true,
 CandidateRouteHop::PrivateHop { .. } => true,
 CandidateRouteHop::Blinded { .. } => true,
 _ => false,
 };

 // If HTLC minimum is larger than the amount we're going to transfer, we shouldn't
 // bother considering this channel. If retrying with recommended_value_msat may
 // allow us to hit the HTLC minimum limit, set htlc_minimum_limit so that we go
 // around again with a higher amount.
 if !contributes_sufficient_value || exceeds_max_path_length ||
 exceeds_cltv_delta_limit || payment_failed_on_this_channel {
 // Path isn't useful, ignore it and move on.
 if !contributes_sufficient_value {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to insufficient value contribution.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_value_contribution += 1;
 } else if exceeds_max_path_length {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to exceeding maximum path length limit.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_path_length_limit += 1;
 } else if exceeds_cltv_delta_limit {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to exceeding CLTV delta limit.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_cltv_delta_limit += 1;
 } else if payment_failed_on_this_channel {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to a failed previous payment attempt.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_previously_failed += 1;
 } else if may_overpay_to_meet_path_minimum_msat {
 hit_minimum_limit = true;
 } else if over_path_minimum_msat {
Expand DownExpand Up@@ -2323,6 +2360,12 @@ where L::Target: Logger {
 }
	}

	let num_ignored_total = num_ignored_value_contribution + num_ignored_path_length_limit +
 num_ignored_cltv_delta_limit + num_ignored_previously_failed;
	if num_ignored_total > 0 {
 log_trace!(logger, "Ignored {} candidate hops due to insufficient value contribution, {} due to path length limit, {} due to CLTV delta limit, {} due to previous payment failure. Total: {} ignored candidates.", num_ignored_value_contribution, num_ignored_path_length_limit, num_ignored_cltv_delta_limit, num_ignored_previously_failed, num_ignored_total);
	}

	// Step (5).
	if payment_paths.len() == 0 {
 return Err(LightningError{err: "Failed to find a path to the given destination".to_owned(), action: ErrorAction::IgnoreError});
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Improve router logging and update documentation#2436

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

 Merged

jkczyz
merged 2 commits into

from

Jul 21, 2023
 Merged


Improve router logging and update documentation
#2436
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
543c5bf

Update outdated `router.rs` docs


tnull Jul 18, 2023
1db53a9

Improve logging for ignored candiate hops


tnull Jul 18, 2023

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


91 changes: 67 additions & 24 deletions
lightning/src/routing/router.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -82,13 +82,21 @@ impl< G: Deref<Target = NetworkGraph<L>>, L: Deref, S: Deref, SP: Sized, Sc: Sco

/// A trait defining behavior for routing a payment.
pub trait Router {
	/// Finds a [`Route`] between `payer` and `payee` for a payment with the given values.
	/// Finds a [`Route`] for a payment between the given `payer` and a payee.
	///
	/// The `payee` and the payment's value are given in [`RouteParameters::payment_params`]
	/// and [`RouteParameters::final_value_msat`], respectively.
	fn find_route(
 &self, payer: &PublicKey, route_params: &RouteParameters,
 first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InFlightHtlcs
	) -> Result<Route, LightningError>;
	/// Finds a [`Route`] between `payer` and `payee` for a payment with the given values. Includes
	/// `PaymentHash` and `PaymentId` to be able to correlate the request with a specific payment.
	/// Finds a [`Route`] for a payment between the given `payer` and a payee.
	///
	/// The `payee` and the payment's value are given in [`RouteParameters::payment_params`]
	/// and [`RouteParameters::final_value_msat`], respectively.
	///
	/// Includes a [`PaymentHash`] and a [`PaymentId`] to be able to correlate the request with a specific
	/// payment.
	fn find_route_with_id(
 &self, payer: &PublicKey, route_params: &RouteParameters,
 first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InFlightHtlcs,
Expand DownExpand Up@@ -346,19 +354,17 @@ pub struct Route {
	/// [`BlindedTail`]s are present, then the pubkey of the last [`RouteHop`] in each path must be
	/// the same.
	pub paths: Vec<Path>,
	/// The `payment_params` parameter passed to [`find_route`].
	/// This is used by `ChannelManager` to track information which may be required for retries,
	/// provided back to you via [`Event::PaymentPathFailed`].
	/// The `payment_params` parameter passed via [`RouteParameters`] to [`find_route`].
	///
	/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
	/// This is used by `ChannelManager` to track information which may be required for retries.
	pub payment_params: Option<PaymentParameters>,
}

impl Route {
	/// Returns the total amount of fees paid on this [`Route`].
	///
	/// This doesn't include any extra payment made to the recipient, which can happen in excess of
	/// the amount passed to [`find_route`]'s `params.final_value_msat`.
	/// the amount passed to [`find_route`]'s `route_params.final_value_msat`.
	pub fn get_total_fees(&self) -> u64 {
 self.paths.iter().map(|path| path.fee_msat()).sum()
	}
Expand DownExpand Up@@ -436,10 +442,7 @@ impl Readable for Route {

/// Parameters needed to find a [`Route`].
///
/// Passed to [`find_route`] and [`build_route_from_hops`], but also provided in
/// [`Event::PaymentPathFailed`].
///
/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
/// Passed to [`find_route`] and [`build_route_from_hops`].
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RouteParameters {
	/// The parameters of the failed payment path.
Expand DownExpand Up@@ -1330,6 +1333,14 @@ impl<'a> fmt::Display for LoggedCandidateHop<'a> {
 " and blinding point ".fmt(f)?;
 hint.1.blinding_point.fmt(f)
 },
 CandidateRouteHop::FirstHop { .. } => {
 "first hop with SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
 },
 CandidateRouteHop::PrivateHop { .. } => {
 "route hint with SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
 },
 _ => {
 "SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
Expand DownExpand Up@@ -1375,10 +1386,12 @@ fn sort_first_hop_channels(

/// Finds a route from us (payer) to the given target node (payee).
///
/// If the payee provided features in their invoice, they should be provided via `params.payee`.
/// If the payee provided features in their invoice, they should be provided via the `payee` field
/// in the given [`RouteParameters::payment_params`].
/// Without this, MPP will only be used if the payee's features are available in the network graph.
///
/// Private routing paths between a public node and the target may be included in `params.payee`.
/// Private routing paths between a public node and the target may be included in the `payee` field
/// of [`RouteParameters::payment_params`].
///
/// If some channels aren't announced, it may be useful to fill in `first_hops` with the results
/// from [`ChannelManager::list_usable_channels`]. If it is filled in, the view of these channels
Expand All@@ -1388,15 +1401,9 @@ fn sort_first_hop_channels(
/// However, the enabled/disabled bit on such channels as well as the `htlc_minimum_msat` /
/// `htlc_maximum_msat` *are* checked as they may change based on the receiving node.
///
/// # Note
///
/// May be used to re-compute a [`Route`] when handling a [`Event::PaymentPathFailed`]. Any
/// adjustments to the [`NetworkGraph`] and channel scores should be made prior to calling this
/// function.
///
/// # Panics
///
/// Panics if first_hops contains channels without short_channel_ids;
/// Panics if first_hops contains channels without `short_channel_id`s;
/// [`ChannelManager::list_usable_channels`] will never include such channels.
///
/// [`ChannelManager::list_usable_channels`]: crate::ln::channelmanager::ChannelManager::list_usable_channels
Expand DownExpand Up@@ -1641,6 +1648,12 @@ where L::Target: Logger {
	log_trace!(logger, "Building path from {} to payer {} for value {} msat.",
 LoggedPayeePubkey(payment_params.payee.node_id()), our_node_pubkey, final_value_msat);

	// Remember how many candidates we ignored to allow for some logging afterwards.
	let mut num_ignored_value_contribution = 0;
	let mut num_ignored_path_length_limit = 0;
	let mut num_ignored_cltv_delta_limit = 0;
	let mut num_ignored_previously_failed = 0;

	macro_rules! add_entry {
 // Adds entry which goes from $src_node_id to $dest_node_id over the $candidate hop.
 // $next_hops_fee_msat represents the fees paid for using all the channels *after* this one,
Expand DownExpand Up@@ -1715,13 +1728,37 @@ where L::Target: Logger {
 let payment_failed_on_this_channel = scid_opt.map_or(false,
 |scid| payment_params.previously_failed_channels.contains(&scid));

 let should_log_candidate = match $candidate {
 CandidateRouteHop::FirstHop { .. } => true,
 CandidateRouteHop::PrivateHop { .. } => true,
 CandidateRouteHop::Blinded { .. } => true,
 _ => false,
 };

 // If HTLC minimum is larger than the amount we're going to transfer, we shouldn't
 // bother considering this channel. If retrying with recommended_value_msat may
 // allow us to hit the HTLC minimum limit, set htlc_minimum_limit so that we go
 // around again with a higher amount.
 if !contributes_sufficient_value || exceeds_max_path_length ||
 exceeds_cltv_delta_limit || payment_failed_on_this_channel {
 // Path isn't useful, ignore it and move on.
 if !contributes_sufficient_value {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to insufficient value contribution.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_value_contribution += 1;
 } else if exceeds_max_path_length {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to exceeding maximum path length limit.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_path_length_limit += 1;
 } else if exceeds_cltv_delta_limit {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to exceeding CLTV delta limit.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_cltv_delta_limit += 1;
 } else if payment_failed_on_this_channel {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to a failed previous payment attempt.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_previously_failed += 1;
 } else if may_overpay_to_meet_path_minimum_msat {
 hit_minimum_limit = true;
 } else if over_path_minimum_msat {
Expand DownExpand Up@@ -2323,6 +2360,12 @@ where L::Target: Logger {
 }
	}

	let num_ignored_total = num_ignored_value_contribution + num_ignored_path_length_limit +
 num_ignored_cltv_delta_limit + num_ignored_previously_failed;
	if num_ignored_total > 0 {
 log_trace!(logger, "Ignored {} candidate hops due to insufficient value contribution, {} due to path length limit, {} due to CLTV delta limit, {} due to previous payment failure. Total: {} ignored candidates.", num_ignored_value_contribution, num_ignored_path_length_limit, num_ignored_cltv_delta_limit, num_ignored_previously_failed, num_ignored_total);
	}

	// Step (5).
	if payment_paths.len() == 0 {
 return Err(LightningError{err: "Failed to find a path to the given destination".to_owned(), action: ErrorAction::IgnoreError});
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Improve router logging and update documentation#2436

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

 Merged

jkczyz
merged 2 commits into

from

Jul 21, 2023
 Merged


Improve router logging and update documentation
#2436
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
543c5bf

Update outdated `router.rs` docs


tnull Jul 18, 2023
1db53a9

Improve logging for ignored candiate hops


tnull Jul 18, 2023

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


91 changes: 67 additions & 24 deletions
lightning/src/routing/router.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -82,13 +82,21 @@ impl< G: Deref<Target = NetworkGraph<L>>, L: Deref, S: Deref, SP: Sized, Sc: Sco

/// A trait defining behavior for routing a payment.
pub trait Router {
	/// Finds a [`Route`] between `payer` and `payee` for a payment with the given values.
	/// Finds a [`Route`] for a payment between the given `payer` and a payee.
	///
	/// The `payee` and the payment's value are given in [`RouteParameters::payment_params`]
	/// and [`RouteParameters::final_value_msat`], respectively.
	fn find_route(
 &self, payer: &PublicKey, route_params: &RouteParameters,
 first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InFlightHtlcs
	) -> Result<Route, LightningError>;
	/// Finds a [`Route`] between `payer` and `payee` for a payment with the given values. Includes
	/// `PaymentHash` and `PaymentId` to be able to correlate the request with a specific payment.
	/// Finds a [`Route`] for a payment between the given `payer` and a payee.
	///
	/// The `payee` and the payment's value are given in [`RouteParameters::payment_params`]
	/// and [`RouteParameters::final_value_msat`], respectively.
	///
	/// Includes a [`PaymentHash`] and a [`PaymentId`] to be able to correlate the request with a specific
	/// payment.
	fn find_route_with_id(
 &self, payer: &PublicKey, route_params: &RouteParameters,
 first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InFlightHtlcs,
Expand DownExpand Up@@ -346,19 +354,17 @@ pub struct Route {
	/// [`BlindedTail`]s are present, then the pubkey of the last [`RouteHop`] in each path must be
	/// the same.
	pub paths: Vec<Path>,
	/// The `payment_params` parameter passed to [`find_route`].
	/// This is used by `ChannelManager` to track information which may be required for retries,
	/// provided back to you via [`Event::PaymentPathFailed`].
	/// The `payment_params` parameter passed via [`RouteParameters`] to [`find_route`].
	///
	/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
	/// This is used by `ChannelManager` to track information which may be required for retries.
	pub payment_params: Option<PaymentParameters>,
}

impl Route {
	/// Returns the total amount of fees paid on this [`Route`].
	///
	/// This doesn't include any extra payment made to the recipient, which can happen in excess of
	/// the amount passed to [`find_route`]'s `params.final_value_msat`.
	/// the amount passed to [`find_route`]'s `route_params.final_value_msat`.
	pub fn get_total_fees(&self) -> u64 {
 self.paths.iter().map(|path| path.fee_msat()).sum()
	}
Expand DownExpand Up@@ -436,10 +442,7 @@ impl Readable for Route {

/// Parameters needed to find a [`Route`].
///
/// Passed to [`find_route`] and [`build_route_from_hops`], but also provided in
/// [`Event::PaymentPathFailed`].
///
/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
/// Passed to [`find_route`] and [`build_route_from_hops`].
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RouteParameters {
	/// The parameters of the failed payment path.
Expand DownExpand Up@@ -1330,6 +1333,14 @@ impl<'a> fmt::Display for LoggedCandidateHop<'a> {
 " and blinding point ".fmt(f)?;
 hint.1.blinding_point.fmt(f)
 },
 CandidateRouteHop::FirstHop { .. } => {
 "first hop with SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
 },
 CandidateRouteHop::PrivateHop { .. } => {
 "route hint with SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
 },
 _ => {
 "SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
Expand DownExpand Up@@ -1375,10 +1386,12 @@ fn sort_first_hop_channels(

/// Finds a route from us (payer) to the given target node (payee).
///
/// If the payee provided features in their invoice, they should be provided via `params.payee`.
/// If the payee provided features in their invoice, they should be provided via the `payee` field
/// in the given [`RouteParameters::payment_params`].
/// Without this, MPP will only be used if the payee's features are available in the network graph.
///
/// Private routing paths between a public node and the target may be included in `params.payee`.
/// Private routing paths between a public node and the target may be included in the `payee` field
/// of [`RouteParameters::payment_params`].
///
/// If some channels aren't announced, it may be useful to fill in `first_hops` with the results
/// from [`ChannelManager::list_usable_channels`]. If it is filled in, the view of these channels
Expand All@@ -1388,15 +1401,9 @@ fn sort_first_hop_channels(
/// However, the enabled/disabled bit on such channels as well as the `htlc_minimum_msat` /
/// `htlc_maximum_msat` *are* checked as they may change based on the receiving node.
///
/// # Note
///
/// May be used to re-compute a [`Route`] when handling a [`Event::PaymentPathFailed`]. Any
/// adjustments to the [`NetworkGraph`] and channel scores should be made prior to calling this
/// function.
///
/// # Panics
///
/// Panics if first_hops contains channels without short_channel_ids;
/// Panics if first_hops contains channels without `short_channel_id`s;
/// [`ChannelManager::list_usable_channels`] will never include such channels.
///
/// [`ChannelManager::list_usable_channels`]: crate::ln::channelmanager::ChannelManager::list_usable_channels
Expand DownExpand Up@@ -1641,6 +1648,12 @@ where L::Target: Logger {
	log_trace!(logger, "Building path from {} to payer {} for value {} msat.",
 LoggedPayeePubkey(payment_params.payee.node_id()), our_node_pubkey, final_value_msat);

	// Remember how many candidates we ignored to allow for some logging afterwards.
	let mut num_ignored_value_contribution = 0;
	let mut num_ignored_path_length_limit = 0;
	let mut num_ignored_cltv_delta_limit = 0;
	let mut num_ignored_previously_failed = 0;

	macro_rules! add_entry {
 // Adds entry which goes from $src_node_id to $dest_node_id over the $candidate hop.
 // $next_hops_fee_msat represents the fees paid for using all the channels *after* this one,
Expand DownExpand Up@@ -1715,13 +1728,37 @@ where L::Target: Logger {
 let payment_failed_on_this_channel = scid_opt.map_or(false,
 |scid| payment_params.previously_failed_channels.contains(&scid));

 let should_log_candidate = match $candidate {
 CandidateRouteHop::FirstHop { .. } => true,
 CandidateRouteHop::PrivateHop { .. } => true,
 CandidateRouteHop::Blinded { .. } => true,
 _ => false,
 };

 // If HTLC minimum is larger than the amount we're going to transfer, we shouldn't
 // bother considering this channel. If retrying with recommended_value_msat may
 // allow us to hit the HTLC minimum limit, set htlc_minimum_limit so that we go
 // around again with a higher amount.
 if !contributes_sufficient_value || exceeds_max_path_length ||
 exceeds_cltv_delta_limit || payment_failed_on_this_channel {
 // Path isn't useful, ignore it and move on.
 if !contributes_sufficient_value {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to insufficient value contribution.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_value_contribution += 1;
 } else if exceeds_max_path_length {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to exceeding maximum path length limit.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_path_length_limit += 1;
 } else if exceeds_cltv_delta_limit {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to exceeding CLTV delta limit.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_cltv_delta_limit += 1;
 } else if payment_failed_on_this_channel {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to a failed previous payment attempt.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_previously_failed += 1;
 } else if may_overpay_to_meet_path_minimum_msat {
 hit_minimum_limit = true;
 } else if over_path_minimum_msat {
Expand DownExpand Up@@ -2323,6 +2360,12 @@ where L::Target: Logger {
 }
	}

	let num_ignored_total = num_ignored_value_contribution + num_ignored_path_length_limit +
 num_ignored_cltv_delta_limit + num_ignored_previously_failed;
	if num_ignored_total > 0 {
 log_trace!(logger, "Ignored {} candidate hops due to insufficient value contribution, {} due to path length limit, {} due to CLTV delta limit, {} due to previous payment failure. Total: {} ignored candidates.", num_ignored_value_contribution, num_ignored_path_length_limit, num_ignored_cltv_delta_limit, num_ignored_previously_failed, num_ignored_total);
	}

	// Step (5).
	if payment_paths.len() == 0 {
 return Err(LightningError{err: "Failed to find a path to the given destination".to_owned(), action: ErrorAction::IgnoreError});
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
Improve router logging and update documentation#2436

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

 Merged

jkczyz
merged 2 commits into

from

Jul 21, 2023
 Merged


Improve router logging and update documentation
#2436
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
543c5bf

Update outdated `router.rs` docs


tnull Jul 18, 2023
1db53a9

Improve logging for ignored candiate hops


tnull Jul 18, 2023

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


91 changes: 67 additions & 24 deletions
lightning/src/routing/router.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -82,13 +82,21 @@ impl< G: Deref<Target = NetworkGraph<L>>, L: Deref, S: Deref, SP: Sized, Sc: Sco

/// A trait defining behavior for routing a payment.
pub trait Router {
	/// Finds a [`Route`] between `payer` and `payee` for a payment with the given values.
	/// Finds a [`Route`] for a payment between the given `payer` and a payee.
	///
	/// The `payee` and the payment's value are given in [`RouteParameters::payment_params`]
	/// and [`RouteParameters::final_value_msat`], respectively.
	fn find_route(
 &self, payer: &PublicKey, route_params: &RouteParameters,
 first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InFlightHtlcs
	) -> Result<Route, LightningError>;
	/// Finds a [`Route`] between `payer` and `payee` for a payment with the given values. Includes
	/// `PaymentHash` and `PaymentId` to be able to correlate the request with a specific payment.
	/// Finds a [`Route`] for a payment between the given `payer` and a payee.
	///
	/// The `payee` and the payment's value are given in [`RouteParameters::payment_params`]
	/// and [`RouteParameters::final_value_msat`], respectively.
	///
	/// Includes a [`PaymentHash`] and a [`PaymentId`] to be able to correlate the request with a specific
	/// payment.
	fn find_route_with_id(
 &self, payer: &PublicKey, route_params: &RouteParameters,
 first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InFlightHtlcs,
Expand DownExpand Up@@ -346,19 +354,17 @@ pub struct Route {
	/// [`BlindedTail`]s are present, then the pubkey of the last [`RouteHop`] in each path must be
	/// the same.
	pub paths: Vec<Path>,
	/// The `payment_params` parameter passed to [`find_route`].
	/// This is used by `ChannelManager` to track information which may be required for retries,
	/// provided back to you via [`Event::PaymentPathFailed`].
	/// The `payment_params` parameter passed via [`RouteParameters`] to [`find_route`].
	///
	/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
	/// This is used by `ChannelManager` to track information which may be required for retries.
	pub payment_params: Option<PaymentParameters>,
}

impl Route {
	/// Returns the total amount of fees paid on this [`Route`].
	///
	/// This doesn't include any extra payment made to the recipient, which can happen in excess of
	/// the amount passed to [`find_route`]'s `params.final_value_msat`.
	/// the amount passed to [`find_route`]'s `route_params.final_value_msat`.
	pub fn get_total_fees(&self) -> u64 {
 self.paths.iter().map(|path| path.fee_msat()).sum()
	}
Expand DownExpand Up@@ -436,10 +442,7 @@ impl Readable for Route {

/// Parameters needed to find a [`Route`].
///
/// Passed to [`find_route`] and [`build_route_from_hops`], but also provided in
/// [`Event::PaymentPathFailed`].
///
/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
/// Passed to [`find_route`] and [`build_route_from_hops`].
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RouteParameters {
	/// The parameters of the failed payment path.
Expand DownExpand Up@@ -1330,6 +1333,14 @@ impl<'a> fmt::Display for LoggedCandidateHop<'a> {
 " and blinding point ".fmt(f)?;
 hint.1.blinding_point.fmt(f)
 },
 CandidateRouteHop::FirstHop { .. } => {
 "first hop with SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
 },
 CandidateRouteHop::PrivateHop { .. } => {
 "route hint with SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
 },
 _ => {
 "SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
Expand DownExpand Up@@ -1375,10 +1386,12 @@ fn sort_first_hop_channels(

/// Finds a route from us (payer) to the given target node (payee).
///
/// If the payee provided features in their invoice, they should be provided via `params.payee`.
/// If the payee provided features in their invoice, they should be provided via the `payee` field
/// in the given [`RouteParameters::payment_params`].
/// Without this, MPP will only be used if the payee's features are available in the network graph.
///
/// Private routing paths between a public node and the target may be included in `params.payee`.
/// Private routing paths between a public node and the target may be included in the `payee` field
/// of [`RouteParameters::payment_params`].
///
/// If some channels aren't announced, it may be useful to fill in `first_hops` with the results
/// from [`ChannelManager::list_usable_channels`]. If it is filled in, the view of these channels
Expand All@@ -1388,15 +1401,9 @@ fn sort_first_hop_channels(
/// However, the enabled/disabled bit on such channels as well as the `htlc_minimum_msat` /
/// `htlc_maximum_msat` *are* checked as they may change based on the receiving node.
///
/// # Note
///
/// May be used to re-compute a [`Route`] when handling a [`Event::PaymentPathFailed`]. Any
/// adjustments to the [`NetworkGraph`] and channel scores should be made prior to calling this
/// function.
///
/// # Panics
///
/// Panics if first_hops contains channels without short_channel_ids;
/// Panics if first_hops contains channels without `short_channel_id`s;
/// [`ChannelManager::list_usable_channels`] will never include such channels.
///
/// [`ChannelManager::list_usable_channels`]: crate::ln::channelmanager::ChannelManager::list_usable_channels
Expand DownExpand Up@@ -1641,6 +1648,12 @@ where L::Target: Logger {
	log_trace!(logger, "Building path from {} to payer {} for value {} msat.",
 LoggedPayeePubkey(payment_params.payee.node_id()), our_node_pubkey, final_value_msat);

	// Remember how many candidates we ignored to allow for some logging afterwards.
	let mut num_ignored_value_contribution = 0;
	let mut num_ignored_path_length_limit = 0;
	let mut num_ignored_cltv_delta_limit = 0;
	let mut num_ignored_previously_failed = 0;

	macro_rules! add_entry {
 // Adds entry which goes from $src_node_id to $dest_node_id over the $candidate hop.
 // $next_hops_fee_msat represents the fees paid for using all the channels *after* this one,
Expand DownExpand Up@@ -1715,13 +1728,37 @@ where L::Target: Logger {
 let payment_failed_on_this_channel = scid_opt.map_or(false,
 |scid| payment_params.previously_failed_channels.contains(&scid));

 let should_log_candidate = match $candidate {
 CandidateRouteHop::FirstHop { .. } => true,
 CandidateRouteHop::PrivateHop { .. } => true,
 CandidateRouteHop::Blinded { .. } => true,
 _ => false,
 };

 // If HTLC minimum is larger than the amount we're going to transfer, we shouldn't
 // bother considering this channel. If retrying with recommended_value_msat may
 // allow us to hit the HTLC minimum limit, set htlc_minimum_limit so that we go
 // around again with a higher amount.
 if !contributes_sufficient_value || exceeds_max_path_length ||
 exceeds_cltv_delta_limit || payment_failed_on_this_channel {
 // Path isn't useful, ignore it and move on.
 if !contributes_sufficient_value {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to insufficient value contribution.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_value_contribution += 1;
 } else if exceeds_max_path_length {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to exceeding maximum path length limit.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_path_length_limit += 1;
 } else if exceeds_cltv_delta_limit {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to exceeding CLTV delta limit.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_cltv_delta_limit += 1;
 } else if payment_failed_on_this_channel {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to a failed previous payment attempt.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_previously_failed += 1;
 } else if may_overpay_to_meet_path_minimum_msat {
 hit_minimum_limit = true;
 } else if over_path_minimum_msat {
Expand DownExpand Up@@ -2323,6 +2360,12 @@ where L::Target: Logger {
 }
	}

	let num_ignored_total = num_ignored_value_contribution + num_ignored_path_length_limit +
 num_ignored_cltv_delta_limit + num_ignored_previously_failed;
	if num_ignored_total > 0 {
 log_trace!(logger, "Ignored {} candidate hops due to insufficient value contribution, {} due to path length limit, {} due to CLTV delta limit, {} due to previous payment failure. Total: {} ignored candidates.", num_ignored_value_contribution, num_ignored_path_length_limit, num_ignored_cltv_delta_limit, num_ignored_previously_failed, num_ignored_total);
	}

	// Step (5).
	if payment_paths.len() == 0 {
 return Err(LightningError{err: "Failed to find a path to the given destination".to_owned(), action: ErrorAction::IgnoreError});
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Improve router logging and update documentation#2436

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

 Merged

jkczyz
merged 2 commits into

from

Jul 21, 2023
 Merged


Improve router logging and update documentation
#2436
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
543c5bf

Update outdated `router.rs` docs


tnull Jul 18, 2023
1db53a9

Improve logging for ignored candiate hops


tnull Jul 18, 2023

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


91 changes: 67 additions & 24 deletions
lightning/src/routing/router.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -82,13 +82,21 @@ impl< G: Deref<Target = NetworkGraph<L>>, L: Deref, S: Deref, SP: Sized, Sc: Sco

/// A trait defining behavior for routing a payment.
pub trait Router {
	/// Finds a [`Route`] between `payer` and `payee` for a payment with the given values.
	/// Finds a [`Route`] for a payment between the given `payer` and a payee.
	///
	/// The `payee` and the payment's value are given in [`RouteParameters::payment_params`]
	/// and [`RouteParameters::final_value_msat`], respectively.
	fn find_route(
 &self, payer: &PublicKey, route_params: &RouteParameters,
 first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InFlightHtlcs
	) -> Result<Route, LightningError>;
	/// Finds a [`Route`] between `payer` and `payee` for a payment with the given values. Includes
	/// `PaymentHash` and `PaymentId` to be able to correlate the request with a specific payment.
	/// Finds a [`Route`] for a payment between the given `payer` and a payee.
	///
	/// The `payee` and the payment's value are given in [`RouteParameters::payment_params`]
	/// and [`RouteParameters::final_value_msat`], respectively.
	///
	/// Includes a [`PaymentHash`] and a [`PaymentId`] to be able to correlate the request with a specific
	/// payment.
	fn find_route_with_id(
 &self, payer: &PublicKey, route_params: &RouteParameters,
 first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InFlightHtlcs,
Expand DownExpand Up@@ -346,19 +354,17 @@ pub struct Route {
	/// [`BlindedTail`]s are present, then the pubkey of the last [`RouteHop`] in each path must be
	/// the same.
	pub paths: Vec<Path>,
	/// The `payment_params` parameter passed to [`find_route`].
	/// This is used by `ChannelManager` to track information which may be required for retries,
	/// provided back to you via [`Event::PaymentPathFailed`].
	/// The `payment_params` parameter passed via [`RouteParameters`] to [`find_route`].
	///
	/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
	/// This is used by `ChannelManager` to track information which may be required for retries.
	pub payment_params: Option<PaymentParameters>,
}

impl Route {
	/// Returns the total amount of fees paid on this [`Route`].
	///
	/// This doesn't include any extra payment made to the recipient, which can happen in excess of
	/// the amount passed to [`find_route`]'s `params.final_value_msat`.
	/// the amount passed to [`find_route`]'s `route_params.final_value_msat`.
	pub fn get_total_fees(&self) -> u64 {
 self.paths.iter().map(|path| path.fee_msat()).sum()
	}
Expand DownExpand Up@@ -436,10 +442,7 @@ impl Readable for Route {

/// Parameters needed to find a [`Route`].
///
/// Passed to [`find_route`] and [`build_route_from_hops`], but also provided in
/// [`Event::PaymentPathFailed`].
///
/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
/// Passed to [`find_route`] and [`build_route_from_hops`].
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RouteParameters {
	/// The parameters of the failed payment path.
Expand DownExpand Up@@ -1330,6 +1333,14 @@ impl<'a> fmt::Display for LoggedCandidateHop<'a> {
 " and blinding point ".fmt(f)?;
 hint.1.blinding_point.fmt(f)
 },
 CandidateRouteHop::FirstHop { .. } => {
 "first hop with SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
 },
 CandidateRouteHop::PrivateHop { .. } => {
 "route hint with SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
 },
 _ => {
 "SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
Expand DownExpand Up@@ -1375,10 +1386,12 @@ fn sort_first_hop_channels(

/// Finds a route from us (payer) to the given target node (payee).
///
/// If the payee provided features in their invoice, they should be provided via `params.payee`.
/// If the payee provided features in their invoice, they should be provided via the `payee` field
/// in the given [`RouteParameters::payment_params`].
/// Without this, MPP will only be used if the payee's features are available in the network graph.
///
/// Private routing paths between a public node and the target may be included in `params.payee`.
/// Private routing paths between a public node and the target may be included in the `payee` field
/// of [`RouteParameters::payment_params`].
///
/// If some channels aren't announced, it may be useful to fill in `first_hops` with the results
/// from [`ChannelManager::list_usable_channels`]. If it is filled in, the view of these channels
Expand All@@ -1388,15 +1401,9 @@ fn sort_first_hop_channels(
/// However, the enabled/disabled bit on such channels as well as the `htlc_minimum_msat` /
/// `htlc_maximum_msat` *are* checked as they may change based on the receiving node.
///
/// # Note
///
/// May be used to re-compute a [`Route`] when handling a [`Event::PaymentPathFailed`]. Any
/// adjustments to the [`NetworkGraph`] and channel scores should be made prior to calling this
/// function.
///
/// # Panics
///
/// Panics if first_hops contains channels without short_channel_ids;
/// Panics if first_hops contains channels without `short_channel_id`s;
/// [`ChannelManager::list_usable_channels`] will never include such channels.
///
/// [`ChannelManager::list_usable_channels`]: crate::ln::channelmanager::ChannelManager::list_usable_channels
Expand DownExpand Up@@ -1641,6 +1648,12 @@ where L::Target: Logger {
	log_trace!(logger, "Building path from {} to payer {} for value {} msat.",
 LoggedPayeePubkey(payment_params.payee.node_id()), our_node_pubkey, final_value_msat);

	// Remember how many candidates we ignored to allow for some logging afterwards.
	let mut num_ignored_value_contribution = 0;
	let mut num_ignored_path_length_limit = 0;
	let mut num_ignored_cltv_delta_limit = 0;
	let mut num_ignored_previously_failed = 0;

	macro_rules! add_entry {
 // Adds entry which goes from $src_node_id to $dest_node_id over the $candidate hop.
 // $next_hops_fee_msat represents the fees paid for using all the channels *after* this one,
Expand DownExpand Up@@ -1715,13 +1728,37 @@ where L::Target: Logger {
 let payment_failed_on_this_channel = scid_opt.map_or(false,
 |scid| payment_params.previously_failed_channels.contains(&scid));

 let should_log_candidate = match $candidate {
 CandidateRouteHop::FirstHop { .. } => true,
 CandidateRouteHop::PrivateHop { .. } => true,
 CandidateRouteHop::Blinded { .. } => true,
 _ => false,
 };

 // If HTLC minimum is larger than the amount we're going to transfer, we shouldn't
 // bother considering this channel. If retrying with recommended_value_msat may
 // allow us to hit the HTLC minimum limit, set htlc_minimum_limit so that we go
 // around again with a higher amount.
 if !contributes_sufficient_value || exceeds_max_path_length ||
 exceeds_cltv_delta_limit || payment_failed_on_this_channel {
 // Path isn't useful, ignore it and move on.
 if !contributes_sufficient_value {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to insufficient value contribution.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_value_contribution += 1;
 } else if exceeds_max_path_length {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to exceeding maximum path length limit.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_path_length_limit += 1;
 } else if exceeds_cltv_delta_limit {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to exceeding CLTV delta limit.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_cltv_delta_limit += 1;
 } else if payment_failed_on_this_channel {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to a failed previous payment attempt.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_previously_failed += 1;
 } else if may_overpay_to_meet_path_minimum_msat {
 hit_minimum_limit = true;
 } else if over_path_minimum_msat {
Expand DownExpand Up@@ -2323,6 +2360,12 @@ where L::Target: Logger {
 }
	}

	let num_ignored_total = num_ignored_value_contribution + num_ignored_path_length_limit +
 num_ignored_cltv_delta_limit + num_ignored_previously_failed;
	if num_ignored_total > 0 {
 log_trace!(logger, "Ignored {} candidate hops due to insufficient value contribution, {} due to path length limit, {} due to CLTV delta limit, {} due to previous payment failure. Total: {} ignored candidates.", num_ignored_value_contribution, num_ignored_path_length_limit, num_ignored_cltv_delta_limit, num_ignored_previously_failed, num_ignored_total);
	}

	// Step (5).
	if payment_paths.len() == 0 {
 return Err(LightningError{err: "Failed to find a path to the given destination".to_owned(), action: ErrorAction::IgnoreError});
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Improve router logging and update documentation#2436

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

 Merged

jkczyz
merged 2 commits into

from

Jul 21, 2023
 Merged


Improve router logging and update documentation
#2436
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
543c5bf

Update outdated `router.rs` docs


tnull Jul 18, 2023
1db53a9

Improve logging for ignored candiate hops


tnull Jul 18, 2023

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


91 changes: 67 additions & 24 deletions
lightning/src/routing/router.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -82,13 +82,21 @@ impl< G: Deref<Target = NetworkGraph<L>>, L: Deref, S: Deref, SP: Sized, Sc: Sco

/// A trait defining behavior for routing a payment.
pub trait Router {
	/// Finds a [`Route`] between `payer` and `payee` for a payment with the given values.
	/// Finds a [`Route`] for a payment between the given `payer` and a payee.
	///
	/// The `payee` and the payment's value are given in [`RouteParameters::payment_params`]
	/// and [`RouteParameters::final_value_msat`], respectively.
	fn find_route(
 &self, payer: &PublicKey, route_params: &RouteParameters,
 first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InFlightHtlcs
	) -> Result<Route, LightningError>;
	/// Finds a [`Route`] between `payer` and `payee` for a payment with the given values. Includes
	/// `PaymentHash` and `PaymentId` to be able to correlate the request with a specific payment.
	/// Finds a [`Route`] for a payment between the given `payer` and a payee.
	///
	/// The `payee` and the payment's value are given in [`RouteParameters::payment_params`]
	/// and [`RouteParameters::final_value_msat`], respectively.
	///
	/// Includes a [`PaymentHash`] and a [`PaymentId`] to be able to correlate the request with a specific
	/// payment.
	fn find_route_with_id(
 &self, payer: &PublicKey, route_params: &RouteParameters,
 first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InFlightHtlcs,
Expand DownExpand Up@@ -346,19 +354,17 @@ pub struct Route {
	/// [`BlindedTail`]s are present, then the pubkey of the last [`RouteHop`] in each path must be
	/// the same.
	pub paths: Vec<Path>,
	/// The `payment_params` parameter passed to [`find_route`].
	/// This is used by `ChannelManager` to track information which may be required for retries,
	/// provided back to you via [`Event::PaymentPathFailed`].
	/// The `payment_params` parameter passed via [`RouteParameters`] to [`find_route`].
	///
	/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
	/// This is used by `ChannelManager` to track information which may be required for retries.
	pub payment_params: Option<PaymentParameters>,
}

impl Route {
	/// Returns the total amount of fees paid on this [`Route`].
	///
	/// This doesn't include any extra payment made to the recipient, which can happen in excess of
	/// the amount passed to [`find_route`]'s `params.final_value_msat`.
	/// the amount passed to [`find_route`]'s `route_params.final_value_msat`.
	pub fn get_total_fees(&self) -> u64 {
 self.paths.iter().map(|path| path.fee_msat()).sum()
	}
Expand DownExpand Up@@ -436,10 +442,7 @@ impl Readable for Route {

/// Parameters needed to find a [`Route`].
///
/// Passed to [`find_route`] and [`build_route_from_hops`], but also provided in
/// [`Event::PaymentPathFailed`].
///
/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
/// Passed to [`find_route`] and [`build_route_from_hops`].
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RouteParameters {
	/// The parameters of the failed payment path.
Expand DownExpand Up@@ -1330,6 +1333,14 @@ impl<'a> fmt::Display for LoggedCandidateHop<'a> {
 " and blinding point ".fmt(f)?;
 hint.1.blinding_point.fmt(f)
 },
 CandidateRouteHop::FirstHop { .. } => {
 "first hop with SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
 },
 CandidateRouteHop::PrivateHop { .. } => {
 "route hint with SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
 },
 _ => {
 "SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
Expand DownExpand Up@@ -1375,10 +1386,12 @@ fn sort_first_hop_channels(

/// Finds a route from us (payer) to the given target node (payee).
///
/// If the payee provided features in their invoice, they should be provided via `params.payee`.
/// If the payee provided features in their invoice, they should be provided via the `payee` field
/// in the given [`RouteParameters::payment_params`].
/// Without this, MPP will only be used if the payee's features are available in the network graph.
///
/// Private routing paths between a public node and the target may be included in `params.payee`.
/// Private routing paths between a public node and the target may be included in the `payee` field
/// of [`RouteParameters::payment_params`].
///
/// If some channels aren't announced, it may be useful to fill in `first_hops` with the results
/// from [`ChannelManager::list_usable_channels`]. If it is filled in, the view of these channels
Expand All@@ -1388,15 +1401,9 @@ fn sort_first_hop_channels(
/// However, the enabled/disabled bit on such channels as well as the `htlc_minimum_msat` /
/// `htlc_maximum_msat` *are* checked as they may change based on the receiving node.
///
/// # Note
///
/// May be used to re-compute a [`Route`] when handling a [`Event::PaymentPathFailed`]. Any
/// adjustments to the [`NetworkGraph`] and channel scores should be made prior to calling this
/// function.
///
/// # Panics
///
/// Panics if first_hops contains channels without short_channel_ids;
/// Panics if first_hops contains channels without `short_channel_id`s;
/// [`ChannelManager::list_usable_channels`] will never include such channels.
///
/// [`ChannelManager::list_usable_channels`]: crate::ln::channelmanager::ChannelManager::list_usable_channels
Expand DownExpand Up@@ -1641,6 +1648,12 @@ where L::Target: Logger {
	log_trace!(logger, "Building path from {} to payer {} for value {} msat.",
 LoggedPayeePubkey(payment_params.payee.node_id()), our_node_pubkey, final_value_msat);

	// Remember how many candidates we ignored to allow for some logging afterwards.
	let mut num_ignored_value_contribution = 0;
	let mut num_ignored_path_length_limit = 0;
	let mut num_ignored_cltv_delta_limit = 0;
	let mut num_ignored_previously_failed = 0;

	macro_rules! add_entry {
 // Adds entry which goes from $src_node_id to $dest_node_id over the $candidate hop.
 // $next_hops_fee_msat represents the fees paid for using all the channels *after* this one,
Expand DownExpand Up@@ -1715,13 +1728,37 @@ where L::Target: Logger {
 let payment_failed_on_this_channel = scid_opt.map_or(false,
 |scid| payment_params.previously_failed_channels.contains(&scid));

 let should_log_candidate = match $candidate {
 CandidateRouteHop::FirstHop { .. } => true,
 CandidateRouteHop::PrivateHop { .. } => true,
 CandidateRouteHop::Blinded { .. } => true,
 _ => false,
 };

 // If HTLC minimum is larger than the amount we're going to transfer, we shouldn't
 // bother considering this channel. If retrying with recommended_value_msat may
 // allow us to hit the HTLC minimum limit, set htlc_minimum_limit so that we go
 // around again with a higher amount.
 if !contributes_sufficient_value || exceeds_max_path_length ||
 exceeds_cltv_delta_limit || payment_failed_on_this_channel {
 // Path isn't useful, ignore it and move on.
 if !contributes_sufficient_value {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to insufficient value contribution.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_value_contribution += 1;
 } else if exceeds_max_path_length {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to exceeding maximum path length limit.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_path_length_limit += 1;
 } else if exceeds_cltv_delta_limit {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to exceeding CLTV delta limit.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_cltv_delta_limit += 1;
 } else if payment_failed_on_this_channel {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to a failed previous payment attempt.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_previously_failed += 1;
 } else if may_overpay_to_meet_path_minimum_msat {
 hit_minimum_limit = true;
 } else if over_path_minimum_msat {
Expand DownExpand Up@@ -2323,6 +2360,12 @@ where L::Target: Logger {
 }
	}

	let num_ignored_total = num_ignored_value_contribution + num_ignored_path_length_limit +
 num_ignored_cltv_delta_limit + num_ignored_previously_failed;
	if num_ignored_total > 0 {
 log_trace!(logger, "Ignored {} candidate hops due to insufficient value contribution, {} due to path length limit, {} due to CLTV delta limit, {} due to previous payment failure. Total: {} ignored candidates.", num_ignored_value_contribution, num_ignored_path_length_limit, num_ignored_cltv_delta_limit, num_ignored_previously_failed, num_ignored_total);
	}

	// Step (5).
	if payment_paths.len() == 0 {
 return Err(LightningError{err: "Failed to find a path to the given destination".to_owned(), action: ErrorAction::IgnoreError});
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
Improve router logging and update documentation#2436

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

 Merged

jkczyz
merged 2 commits into

from

Jul 21, 2023
 Merged


Improve router logging and update documentation
#2436
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
543c5bf

Update outdated `router.rs` docs


tnull Jul 18, 2023
1db53a9

Improve logging for ignored candiate hops


tnull Jul 18, 2023

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


91 changes: 67 additions & 24 deletions
lightning/src/routing/router.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -82,13 +82,21 @@ impl< G: Deref<Target = NetworkGraph<L>>, L: Deref, S: Deref, SP: Sized, Sc: Sco

/// A trait defining behavior for routing a payment.
pub trait Router {
	/// Finds a [`Route`] between `payer` and `payee` for a payment with the given values.
	/// Finds a [`Route`] for a payment between the given `payer` and a payee.
	///
	/// The `payee` and the payment's value are given in [`RouteParameters::payment_params`]
	/// and [`RouteParameters::final_value_msat`], respectively.
	fn find_route(
 &self, payer: &PublicKey, route_params: &RouteParameters,
 first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InFlightHtlcs
	) -> Result<Route, LightningError>;
	/// Finds a [`Route`] between `payer` and `payee` for a payment with the given values. Includes
	/// `PaymentHash` and `PaymentId` to be able to correlate the request with a specific payment.
	/// Finds a [`Route`] for a payment between the given `payer` and a payee.
	///
	/// The `payee` and the payment's value are given in [`RouteParameters::payment_params`]
	/// and [`RouteParameters::final_value_msat`], respectively.
	///
	/// Includes a [`PaymentHash`] and a [`PaymentId`] to be able to correlate the request with a specific
	/// payment.
	fn find_route_with_id(
 &self, payer: &PublicKey, route_params: &RouteParameters,
 first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InFlightHtlcs,
Expand DownExpand Up@@ -346,19 +354,17 @@ pub struct Route {
	/// [`BlindedTail`]s are present, then the pubkey of the last [`RouteHop`] in each path must be
	/// the same.
	pub paths: Vec<Path>,
	/// The `payment_params` parameter passed to [`find_route`].
	/// This is used by `ChannelManager` to track information which may be required for retries,
	/// provided back to you via [`Event::PaymentPathFailed`].
	/// The `payment_params` parameter passed via [`RouteParameters`] to [`find_route`].
	///
	/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
	/// This is used by `ChannelManager` to track information which may be required for retries.
	pub payment_params: Option<PaymentParameters>,
}

impl Route {
	/// Returns the total amount of fees paid on this [`Route`].
	///
	/// This doesn't include any extra payment made to the recipient, which can happen in excess of
	/// the amount passed to [`find_route`]'s `params.final_value_msat`.
	/// the amount passed to [`find_route`]'s `route_params.final_value_msat`.
	pub fn get_total_fees(&self) -> u64 {
 self.paths.iter().map(|path| path.fee_msat()).sum()
	}
Expand DownExpand Up@@ -436,10 +442,7 @@ impl Readable for Route {

/// Parameters needed to find a [`Route`].
///
/// Passed to [`find_route`] and [`build_route_from_hops`], but also provided in
/// [`Event::PaymentPathFailed`].
///
/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
/// Passed to [`find_route`] and [`build_route_from_hops`].
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RouteParameters {
	/// The parameters of the failed payment path.
Expand DownExpand Up@@ -1330,6 +1333,14 @@ impl<'a> fmt::Display for LoggedCandidateHop<'a> {
 " and blinding point ".fmt(f)?;
 hint.1.blinding_point.fmt(f)
 },
 CandidateRouteHop::FirstHop { .. } => {
 "first hop with SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
 },
 CandidateRouteHop::PrivateHop { .. } => {
 "route hint with SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
 },
 _ => {
 "SCID ".fmt(f)?;
 self.0.short_channel_id().unwrap().fmt(f)
Expand DownExpand Up@@ -1375,10 +1386,12 @@ fn sort_first_hop_channels(

/// Finds a route from us (payer) to the given target node (payee).
///
/// If the payee provided features in their invoice, they should be provided via `params.payee`.
/// If the payee provided features in their invoice, they should be provided via the `payee` field
/// in the given [`RouteParameters::payment_params`].
/// Without this, MPP will only be used if the payee's features are available in the network graph.
///
/// Private routing paths between a public node and the target may be included in `params.payee`.
/// Private routing paths between a public node and the target may be included in the `payee` field
/// of [`RouteParameters::payment_params`].
///
/// If some channels aren't announced, it may be useful to fill in `first_hops` with the results
/// from [`ChannelManager::list_usable_channels`]. If it is filled in, the view of these channels
Expand All@@ -1388,15 +1401,9 @@ fn sort_first_hop_channels(
/// However, the enabled/disabled bit on such channels as well as the `htlc_minimum_msat` /
/// `htlc_maximum_msat` *are* checked as they may change based on the receiving node.
///
/// # Note
///
/// May be used to re-compute a [`Route`] when handling a [`Event::PaymentPathFailed`]. Any
/// adjustments to the [`NetworkGraph`] and channel scores should be made prior to calling this
/// function.
///
/// # Panics
///
/// Panics if first_hops contains channels without short_channel_ids;
/// Panics if first_hops contains channels without `short_channel_id`s;
/// [`ChannelManager::list_usable_channels`] will never include such channels.
///
/// [`ChannelManager::list_usable_channels`]: crate::ln::channelmanager::ChannelManager::list_usable_channels
Expand DownExpand Up@@ -1641,6 +1648,12 @@ where L::Target: Logger {
	log_trace!(logger, "Building path from {} to payer {} for value {} msat.",
 LoggedPayeePubkey(payment_params.payee.node_id()), our_node_pubkey, final_value_msat);

	// Remember how many candidates we ignored to allow for some logging afterwards.
	let mut num_ignored_value_contribution = 0;
	let mut num_ignored_path_length_limit = 0;
	let mut num_ignored_cltv_delta_limit = 0;
	let mut num_ignored_previously_failed = 0;

	macro_rules! add_entry {
 // Adds entry which goes from $src_node_id to $dest_node_id over the $candidate hop.
 // $next_hops_fee_msat represents the fees paid for using all the channels *after* this one,
Expand DownExpand Up@@ -1715,13 +1728,37 @@ where L::Target: Logger {
 let payment_failed_on_this_channel = scid_opt.map_or(false,
 |scid| payment_params.previously_failed_channels.contains(&scid));

 let should_log_candidate = match $candidate {
 CandidateRouteHop::FirstHop { .. } => true,
 CandidateRouteHop::PrivateHop { .. } => true,
 CandidateRouteHop::Blinded { .. } => true,
 _ => false,
 };

 // If HTLC minimum is larger than the amount we're going to transfer, we shouldn't
 // bother considering this channel. If retrying with recommended_value_msat may
 // allow us to hit the HTLC minimum limit, set htlc_minimum_limit so that we go
 // around again with a higher amount.
 if !contributes_sufficient_value || exceeds_max_path_length ||
 exceeds_cltv_delta_limit || payment_failed_on_this_channel {
 // Path isn't useful, ignore it and move on.
 if !contributes_sufficient_value {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to insufficient value contribution.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_value_contribution += 1;
 } else if exceeds_max_path_length {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to exceeding maximum path length limit.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_path_length_limit += 1;
 } else if exceeds_cltv_delta_limit {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to exceeding CLTV delta limit.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_cltv_delta_limit += 1;
 } else if payment_failed_on_this_channel {
 if should_log_candidate {
 log_trace!(logger, "Ignoring {} due to a failed previous payment attempt.", LoggedCandidateHop(&$candidate));
 }
 num_ignored_previously_failed += 1;
 } else if may_overpay_to_meet_path_minimum_msat {
 hit_minimum_limit = true;
 } else if over_path_minimum_msat {
Expand DownExpand Up@@ -2323,6 +2360,12 @@ where L::Target: Logger {
 }
	}

	let num_ignored_total = num_ignored_value_contribution + num_ignored_path_length_limit +
 num_ignored_cltv_delta_limit + num_ignored_previously_failed;
	if num_ignored_total > 0 {
 log_trace!(logger, "Ignored {} candidate hops due to insufficient value contribution, {} due to path length limit, {} due to CLTV delta limit, {} due to previous payment failure. Total: {} ignored candidates.", num_ignored_value_contribution, num_ignored_path_length_limit, num_ignored_cltv_delta_limit, num_ignored_previously_failed, num_ignored_total);
	}

	// Step (5).
	if payment_paths.len() == 0 {
 return Err(LightningError{err: "Failed to find a path to the given destination".to_owned(), action: ErrorAction::IgnoreError});
Expand Down