Struct ProbabilisticScoringFeeParameters

pub struct ProbabilisticScoringFeeParameters {
    pub base_penalty_msat: u64,
    pub base_penalty_amount_multiplier_msat: u64,
    pub liquidity_penalty_multiplier_msat: u64,
    pub liquidity_penalty_amount_multiplier_msat: u64,
    pub historical_liquidity_penalty_multiplier_msat: u64,
    pub historical_liquidity_penalty_amount_multiplier_msat: u64,
    pub manual_node_penalties: HashMap<NodeId, u64>,
    pub anti_probing_penalty_msat: u64,
    pub considered_impossible_penalty_msat: u64,
    pub linear_success_probability: bool,
}

Parameters for configuring ProbabilisticScorer.

Used to configure base, liquidity, and amount penalties, the sum of which comprises the channel penalty (i.e., the amount in msats willing to be paid to avoid routing through the channel).

The penalty applied to any channel by the ProbabilisticScorer is the sum of each of the parameters here.

Fields

base_penalty_msat: u64

A fixed penalty in msats to apply to each channel.

In testing, a value of roughly 1/10th of historical_liquidity_penalty_multiplier_msat (implying scaling all estimated probabilities down by a factor of ~79%) resulted in the most accurate total success probabilities.

Default value: 1,024 msat (i.e. we’re willing to pay 1 sat to avoid each additional hop).

base_penalty_amount_multiplier_msat: u64

A multiplier used with the payment amount to calculate a fixed penalty applied to each channel, in excess of the base_penalty_msat.

The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e., fees plus penalty) for large payments. The penalty is computed as the product of this multiplier and 2^30ths of the payment amount.

ie base_penalty_amount_multiplier_msat * amount_msat / 2^30

In testing, a value of roughly ~100x (1/10th * 2^10) of historical_liquidity_penalty_amount_multiplier_msat (implying scaling all estimated probabilities down by a factor of ~79%) resulted in the most accurate total success probabilities.

Default value: 131,072 msat (i.e. we’re willing to pay 0.125bps to avoid each additional hop).

liquidity_penalty_multiplier_msat: u64

A multiplier used in conjunction with the negative log10 of the channel’s success probability for a payment, as determined by our latest estimates of the channel’s liquidity, to determine the liquidity penalty.

The penalty is based in part on the knowledge learned from prior successful and unsuccessful payments. This knowledge is decayed over time based on liquidity_offset_half_life. The penalty is effectively limited to 2 * liquidity_penalty_multiplier_msat (corresponding to lower bounding the success probability to 0.01) when the amount falls within the uncertainty bounds of the channel liquidity balance. Amounts above the upper bound will result in a u64::max_value penalty, however.

-log10(success_probability) * liquidity_penalty_multiplier_msat

In testing, this scoring model performs much worse than the historical scoring model configured with the historical_liquidity_penalty_multiplier_msat and thus is disabled by default.

Default value: 0 msat

liquidity_penalty_amount_multiplier_msat: u64

A multiplier used in conjunction with the payment amount and the negative log10 of the channel’s success probability for the total amount flowing over a channel, as determined by our latest estimates of the channel’s liquidity, to determine the amount penalty.

The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e., fees plus penalty) for large payments. The penalty is computed as the product of this multiplier and 2^20ths of the payment amount, weighted by the negative log10 of the success probability.

-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20

In practice, this means for 0.1 success probability (-log10(0.1) == 1) each 2^20th of the amount will result in a penalty of the multiplier. And, as the success probability decreases, the negative log10 weighting will increase dramatically. For higher success probabilities, the multiplier will have a decreasing effect as the negative log10 will fall below 1.

In testing, this scoring model performs much worse than the historical scoring model configured with the historical_liquidity_penalty_amount_multiplier_msat and thus is disabled by default.

Default value: 0 msat

historical_liquidity_penalty_multiplier_msat: u64

A multiplier used in conjunction with the negative log10 of the channel’s success probability for the payment, as determined based on the history of our estimates of the channel’s available liquidity, to determine a penalty.

This penalty is similar to liquidity_penalty_multiplier_msat, however, instead of using only our latest estimate for the current liquidity available in the channel, it estimates success probability based on the estimated liquidity available in the channel through history. Specifically, every time we update our liquidity bounds on a given channel, we track which of several buckets those bounds fall into, exponentially decaying the probability of each bucket as new samples are added.

Default value: 10,000 msat (i.e. willing to pay 1 sat to avoid an 80% probability channel, or 6 sats to avoid a 25% probability channel).

historical_liquidity_penalty_amount_multiplier_msat: u64

A multiplier used in conjunction with the payment amount and the negative log10 of the channel’s success probability for the total amount flowing over a channel, as determined based on the history of our estimates of the channel’s available liquidity, to determine a penalty.

The purpose of the amount penalty is to avoid having fees dominate the channel cost for large payments. The penalty is computed as the product of this multiplier and 2^20ths of the payment amount, weighted by the negative log10 of the success probability.

This penalty is similar to liquidity_penalty_amount_multiplier_msat, however, instead of using only our latest estimate for the current liquidity available in the channel, it estimates success probability based on the estimated liquidity available in the channel through history. Specifically, every time we update our liquidity bounds on a given channel, we track which of several buckets those bounds fall into, exponentially decaying the probability of each bucket as new samples are added.

Default value: 1,250 msat (i.e. willing to pay about 0.125 bps per hop to avoid 78% probability channels, or 0.5bps to avoid a 38% probability channel).

manual_node_penalties: HashMap<NodeId, u64>

Manual penalties used for the given nodes. Allows to set a particular penalty for a given node. Note that a manual penalty of u64::max_value() means the node would not ever be considered during path finding.

This is not exported to bindings users

anti_probing_penalty_msat: u64

This penalty is applied when htlc_maximum_msat is equal to or larger than half of the channel’s capacity, (ie. htlc_maximum_msat >= 0.5 * channel_capacity) which makes us prefer nodes with a smaller htlc_maximum_msat. We treat such nodes preferentially as this makes balance discovery attacks harder to execute, thereby creating an incentive to restrict htlc_maximum_msat and improve privacy.

Default value: 250 msat

considered_impossible_penalty_msat: u64

This penalty is applied when the total amount flowing over a channel exceeds our current estimate of the channel’s available liquidity. The total amount is the amount of the current HTLC plus any HTLCs which we’ve sent over the same channel.

Note that in this case all other penalties, including the liquidity_penalty_multiplier_msat and liquidity_penalty_amount_multiplier_msat-based penalties, as well as the base_penalty_msat and the anti_probing_penalty_msat, if applicable, are still included in the overall penalty.

If you wish to avoid creating paths with such channels entirely, setting this to a value of u64::max_value() will guarantee that.

Default value: 1_0000_0000_000 msat (1 Bitcoin)

linear_success_probability: bool

In order to calculate most of the scores above, we must first convert a lower and upper bound on the available liquidity in a channel into the probability that we think a payment will succeed. That probability is derived from a Probability Density Function for where we think the liquidity in a channel likely lies, given such bounds.

If this flag is set, that PDF is simply a constant - we assume that the actual available liquidity in a channel is just as likely to be at any point between our lower and upper bounds.

If this flag is not set, that PDF is (x - 0.5*capacity) ^ 2. That is, we use an exponential curve which expects the liquidity of a channel to lie “at the edges”. This matches experimental results - most routing nodes do not aggressively rebalance their channels and flows in the network are often unbalanced, leaving liquidity usually unavailable.

Thus, for the “best” routes, leave this flag false. However, the flag does imply a number of floating-point multiplications in the hottest routing code, which may lead to routing performance degradation on some machines.

Default value: false

Implementations

impl ProbabilisticScoringFeeParameters

pub fn add_banned(&mut self, node_id: &NodeId)

Marks the node with the given node_id as banned, i.e it will be avoided during path finding.

pub fn add_banned_from_list(&mut self, node_ids: Vec<NodeId>)

Marks all nodes in the given list as banned, i.e., they will be avoided during path finding.

pub fn remove_banned(&mut self, node_id: &NodeId)

Removes the node with the given node_id from the list of nodes to avoid.

pub fn set_manual_penalty(&mut self, node_id: &NodeId, penalty: u64)

Sets a manual penalty for the given node.

pub fn remove_manual_penalty(&mut self, node_id: &NodeId)

Removes the node with the given node_id from the list of manual penalties.

pub fn clear_manual_penalties(&mut self)

Clears the list of manual penalties that are applied during path finding.

Trait Implementations

impl Clone for ProbabilisticScoringFeeParameters

fn clone(&self) -> ProbabilisticScoringFeeParameters

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for ProbabilisticScoringFeeParameters

fn default() -> Self

Returns the “default value” for a type.