Rewrite some documentation on `ProbabilisticScorer` and increase half-life to 6 hours. #1754

TheBlueMatt · 2022-10-05T19:30:15Z

Depends on #1625.

tlulu · 2022-10-05T19:31:13Z

lightning/src/routing/scoring.rs

-/// with high payment volume or that actively probe the [`NetworkGraph`]. Nodes with low payment
-/// volume are more likely to experience failed payment paths, which would need to be retried.
+/// This probability is converted into a linear score by `log10`'ing it and multiplying it with the
+/// [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]


A formula would be easier to read imo
amount = log10(probability) * liquidity_penalty_multiplier_msat * liquidity_penalty_amount_multiplier_msat

Is it okay if we just leave the formulas on the docs for parameters themselves?

Also, should be -log10.

lightning/src/routing/scoring.rs

jkczyz · 2022-10-05T19:57:12Z

lightning/src/routing/scoring.rs

+/// These bounds are then used to determine a success probability using the formula from
+/// *Optimally Reliable & Cheap Payment Flows on the Lightning Network* by Rene Pickhardt
+/// and Stefan Richter [[1]] (i.e. `(payment amount + lower-bound) / (upper-bound - lower-bound)`).


Technically, the numerator and denominator both need + 1 to avoid division by zero.

Yea, I figured skip over that level of detail here.

lightning/src/routing/scoring.rs

jkczyz · 2022-10-05T19:59:08Z

lightning/src/routing/scoring.rs

+/// Channels are tracked with upper- and lower- liquidity bounds - when an HTLC fails at a channel,
+/// we learn that the upper-bound on the available liquidity is lower than the amount of the HTLC.
+/// When a payment is forwarded through a channel (but fails later in the route), we learn the
+/// lower-bound on the channel's available liquidity must be at least the value of the HTLC.


There is a third case where a successful payment lowers the upper bound by the amount.

Yea, I thought about spelling it out, but that just seemed like too much detail. I can add something like "We also learn some information about upper-bounds after a successful payment." or so?

lightning/src/routing/scoring.rs

codecov-commenter · 2022-10-05T22:13:58Z

Codecov Report

Base: 90.79% // Head: 90.80% // Increases project coverage by +0.00% 🎉

Coverage data is based on head (bd6a5f1) compared to base (6738fd5).
Patch coverage: 100.00% of modified lines in pull request are covered.

❗ Current head bd6a5f1 differs from pull request most recent head 9e84966. Consider uploading reports for the commit 9e84966 to get more accurate results

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1754   +/-   ##
=======================================
  Coverage   90.79%   90.80%           
=======================================
  Files          87       87           
  Lines       46969    46969           
  Branches    46969    46969           
=======================================
+ Hits        42646    42648    +2     
+ Misses       4323     4321    -2

Impacted Files	Coverage Δ
lightning/src/routing/scoring.rs	`96.61% <100.00%> (ø)`
lightning/src/chain/onchaintx.rs	`94.71% <0.00%> (-0.92%)`	⬇️
lightning/src/ln/functional_tests.rs	`97.05% <0.00%> (+0.04%)`	⬆️
lightning-net-tokio/src/lib.rs	`77.64% <0.00%> (+0.90%)`	⬆️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

lightning/src/routing/scoring.rs

tnull · 2022-10-06T12:24:29Z

lightning/src/routing/scoring.rs

-	/// gives tighter bounds on the channel liquidity balance. Thus, halving the offsets decreases
-	/// the certainty of the channel liquidity balance.
+	/// For example, if the channel's capacity is 1 million sats, and the current upper- and lower-
+	/// liquidity bounds are 200,000 sats and 600,000 sats, after this amount of time the upper-


nit: Move "after this amount of time" to the end of the sentence. Also, since this is an example it would be nice to make it more concrete, e.g., use the default values or variable name?

Well, the documentation is on the variable itself, so it seems strange to refer to it "in the third person"?

Alright, still think would read better if "after this amount of time" would be at the end of the sentence, but feel to leave as is if you prefer.

tnull

Looks good mod failing CI.

TheBlueMatt · 2022-10-07T17:34:31Z

Rebased after #1625 landed, should pass CI now.

lightning/src/routing/scoring.rs

jkczyz · 2022-10-10T20:14:23Z

lightning/src/routing/scoring.rs

+	/// Because halving the liquidity bounds grows the uncertainty on the channel's liquidity,
+	/// penalties for payments that are within the liquidity bounds will be decreased. See the


I think whether or not penalties are decrease depends on whether the amount lies closer to the upper bound or the lower bound.

Would consider re-wording as:

"Because halving the liquidity bounds increases the uncertainty of the channel's liquidity, the penalty for an amount within the new bounds may increase or decrease depending on whether the new success probability decreased or increased, respectively."

Is it worth specifying the last clause? I just changed it to "it may change", basically.

TheBlueMatt · 2022-10-11T15:28:14Z

Rebased on usptream:

$ git range-diff 7544030bb63fee6484fc178bb2ac8f382fe3b5b1...2e572e8affe4688c84ea15c5d3b836296ee60392 6738fd56cf74227a12ecf6f3934515f42f9f9452...2026634631816b8bfac4e20993fa0814e53dbe00
 1:  56d91c276 =  1:  d7d7c2e61 Rewrite documentation some on `ProbabilisticScorer`
 2:  a7502e09a !  2:  37783f944 f point to params for formulas
    @@ lightning/src/routing/scoring.rs: pub struct ProbabilisticScoringParameters {
        ///
     +  /// `-log10(success_probability) * liquidity_penalty_multiplier_msat`
     +  ///
    -   /// Default value: 40,000 msat
    +   /// Default value: 30,000 msat
        ///
        /// [`liquidity_offset_half_life`]: Self::liquidity_offset_half_life
 3:  db948baf4 =  3:  8c61f751c f add decay example
 4:  ecdcffa3c =  4:  e433f0cad f missing link
 5:  877d9cf5c =  5:  0ab1e4b5f f address docs feedback
 6:  a982b27f7 =  6:  f44f36989 f nits from tnull
 7:  48976ddf2 =  7:  98620f372 f docs
 8:  4fb50c34e =  8:  f5a967c65 f docs
 9:  2e572e8af !  9:  202663463 Increase the default `liquidity_offset_half_life` to six hours
    @@ lightning/src/routing/scoring.rs: impl ProbabilisticScoringParameters {
     -                  liquidity_offset_half_life: Duration::from_secs(3600),
     +                  liquidity_offset_half_life: Duration::from_secs(6 * 60 * 60),
                        liquidity_penalty_amount_multiplier_msat: 0,
    -                   manual_node_penalties: HashMap::new(),
    -                   anti_probing_penalty_msat: 0,
    +                   historical_liquidity_penalty_multiplier_msat: 0,
    +                   historical_liquidity_penalty_amount_multiplier_msat: 0,
     @@ lightning/src/routing/scoring.rs: impl Default for ProbabilisticScoringParameters {
                        base_penalty_msat: 500,
                        base_penalty_amount_multiplier_msat: 8192,
    -                   liquidity_penalty_multiplier_msat: 40_000,
    +                   liquidity_penalty_multiplier_msat: 30_000,
     -                  liquidity_offset_half_life: Duration::from_secs(3600),
     +                  liquidity_offset_half_life: Duration::from_secs(6 * 60 * 60),
    -                   liquidity_penalty_amount_multiplier_msat: 256,
    -                   manual_node_penalties: HashMap::new(),
    -                   anti_probing_penalty_msat: 250,
    +                   liquidity_penalty_amount_multiplier_msat: 192,
    +                   historical_liquidity_penalty_multiplier_msat: 10_000,
    +                   historical_liquidity_penalty_amount_multiplier_msat: 64,

TheBlueMatt · 2022-10-11T15:28:51Z

Then squashed with no further changes:

$ git diff-tree -U1 20266346 bd6a5f17
$

We had some user confusion on how the probabilistic scorer works, especially in reference to the half-life parameter. This attempts to clarify how the bounds work, and how they are decayed.

Even at relatively high payment volumes, decaying knowledge of each individual channel every hour causes aggressive retrying of channels as we quickly forget the state of a channel. Even with the historical tracker, this isn't fully remedied, as we'll track the history bounds with the decayed value. Instead, we decay every six hours here, reducing how often we'll retry a channel due to decay. In addition to this, the decay likely needs to be substantially more linear, as tracked in lightningdevkit#1752.

TheBlueMatt · 2022-10-11T18:26:27Z

Oops, had screwed up the docs, force-pushed:

$ git diff-tree -U1 bd6a5f17b 9e8496659
diff --git a/lightning/src/routing/scoring.rs b/lightning/src/routing/scoring.rs
index f9c188857..fefdebfcc 100644
--- a/lightning/src/routing/scoring.rs
+++ b/lightning/src/routing/scoring.rs
@@ -349,4 +349,4 @@ type ConfiguredTime = Eternity;
 /// [`liquidity_offset_half_life`]: ProbabilisticScoringParameters::liquidity_offset_half_life
-/// [`liquidity_penalty_multiplier_msat`]: ProbabilisticScoringParameters::liquidity_penalty_multiplier_msat
-/// [`liquidity_penalty_amount_multiplier_msat`]: ProbabilisticScoringParameters::liquidity_penalty_amount_multiplier_msat
+/// [`historical_liquidity_penalty_multiplier_msat`]: ProbabilisticScoringParameters::historical_liquidity_penalty_multiplier_msat
+/// [`historical_liquidity_penalty_amount_multiplier_msat`]: ProbabilisticScoringParameters::historical_liquidity_penalty_amount_multiplier_msat

TheBlueMatt added the blocked on dependent pr label Oct 5, 2022

tlulu reviewed Oct 5, 2022

View reviewed changes

lightning/src/routing/scoring.rs Show resolved Hide resolved

TheBlueMatt force-pushed the 2022-10-better-liq-halflife-docs branch from 8702f17 to 14432b8 Compare October 5, 2022 19:40

tlulu previously approved these changes Oct 5, 2022

View reviewed changes

TheBlueMatt dismissed tlulu’s stale review via cb606dd October 5, 2022 19:42

TheBlueMatt force-pushed the 2022-10-better-liq-halflife-docs branch from 14432b8 to cb606dd Compare October 5, 2022 19:42

tlulu previously approved these changes Oct 5, 2022

View reviewed changes

jkczyz reviewed Oct 5, 2022

View reviewed changes

TheBlueMatt dismissed tlulu’s stale review via 25766b1 October 5, 2022 22:12

TheBlueMatt force-pushed the 2022-10-better-liq-halflife-docs branch from cb606dd to 25766b1 Compare October 5, 2022 22:12

tnull self-requested a review October 6, 2022 09:45

tnull reviewed Oct 6, 2022

View reviewed changes

TheBlueMatt force-pushed the 2022-10-better-liq-halflife-docs branch from 25766b1 to e01091c Compare October 6, 2022 17:46

tnull reviewed Oct 7, 2022

View reviewed changes

TheBlueMatt force-pushed the 2022-10-better-liq-halflife-docs branch from e01091c to 3e14f9e Compare October 7, 2022 17:34

TheBlueMatt force-pushed the 2022-10-better-liq-halflife-docs branch from 3e14f9e to 0aec44b Compare October 7, 2022 21:06

tnull previously approved these changes Oct 8, 2022

View reviewed changes

jkczyz reviewed Oct 10, 2022

View reviewed changes

TheBlueMatt removed the blocked on dependent pr label Oct 10, 2022

TheBlueMatt dismissed tnull’s stale review via 2e572e8 October 11, 2022 14:28

TheBlueMatt force-pushed the 2022-10-better-liq-halflife-docs branch from 0aec44b to 2e572e8 Compare October 11, 2022 14:28

jkczyz previously approved these changes Oct 11, 2022

View reviewed changes

TheBlueMatt dismissed jkczyz’s stale review via 2026634 October 11, 2022 15:25

TheBlueMatt force-pushed the 2022-10-better-liq-halflife-docs branch from 2e572e8 to 2026634 Compare October 11, 2022 15:25

TheBlueMatt force-pushed the 2022-10-better-liq-halflife-docs branch from 2026634 to bd6a5f1 Compare October 11, 2022 15:28

tnull previously approved these changes Oct 11, 2022

View reviewed changes

jkczyz previously approved these changes Oct 11, 2022

View reviewed changes

TheBlueMatt added 2 commits October 11, 2022 18:25

Rewrite documentation some on ProbabilisticScorer

fe531c5

We had some user confusion on how the probabilistic scorer works, especially in reference to the half-life parameter. This attempts to clarify how the bounds work, and how they are decayed.

TheBlueMatt dismissed stale reviews from jkczyz and tnull via 9e84966 October 11, 2022 18:25

TheBlueMatt force-pushed the 2022-10-better-liq-halflife-docs branch from bd6a5f1 to 9e84966 Compare October 11, 2022 18:25

jkczyz approved these changes Oct 11, 2022

View reviewed changes

tnull approved these changes Oct 11, 2022

View reviewed changes

TheBlueMatt merged commit fdfd4f0 into lightningdevkit:main Oct 11, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rewrite some documentation on `ProbabilisticScorer` and increase half-life to 6 hours. #1754

Rewrite some documentation on `ProbabilisticScorer` and increase half-life to 6 hours. #1754

TheBlueMatt commented Oct 5, 2022

tlulu Oct 5, 2022 •

edited

Loading

TheBlueMatt Oct 5, 2022

jkczyz Oct 5, 2022

jkczyz Oct 5, 2022

TheBlueMatt Oct 5, 2022

jkczyz Oct 5, 2022

TheBlueMatt Oct 5, 2022

codecov-commenter commented Oct 5, 2022 •

edited

Loading

tnull Oct 6, 2022 •

edited

Loading

TheBlueMatt Oct 6, 2022

tnull Oct 7, 2022

tnull left a comment

TheBlueMatt commented Oct 7, 2022

jkczyz Oct 10, 2022

jkczyz Oct 10, 2022

TheBlueMatt Oct 11, 2022

jkczyz Oct 11, 2022

TheBlueMatt commented Oct 11, 2022

TheBlueMatt commented Oct 11, 2022

TheBlueMatt commented Oct 11, 2022

		/// Because halving the liquidity bounds grows the uncertainty on the channel's liquidity,
		/// penalties for payments that are within the liquidity bounds will be decreased. See the

Rewrite some documentation on ProbabilisticScorer and increase half-life to 6 hours. #1754

Rewrite some documentation on ProbabilisticScorer and increase half-life to 6 hours. #1754

Conversation

TheBlueMatt commented Oct 5, 2022

tlulu Oct 5, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov-commenter commented Oct 5, 2022 • edited Loading

Codecov Report

tnull Oct 6, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tnull left a comment

Choose a reason for hiding this comment

TheBlueMatt commented Oct 7, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TheBlueMatt commented Oct 11, 2022

TheBlueMatt commented Oct 11, 2022

TheBlueMatt commented Oct 11, 2022

Rewrite some documentation on `ProbabilisticScorer` and increase half-life to 6 hours. #1754

Rewrite some documentation on `ProbabilisticScorer` and increase half-life to 6 hours. #1754

tlulu Oct 5, 2022 •

edited

Loading

codecov-commenter commented Oct 5, 2022 •

edited

Loading

tnull Oct 6, 2022 •

edited

Loading