6 namespace org { namespace ldk { namespace structs {
10 * Parameters for configuring [`ProbabilisticScorer`].
12 * Used to configure base, liquidity, and amount penalties, the sum of which comprises the channel
13 * penalty (i.e., the amount in msats willing to be paid to avoid routing through the channel).
15 * The penalty applied to any channel by the [`ProbabilisticScorer`] is the sum of each of the
18 public class ProbabilisticScoringFeeParameters : CommonBase {
19 internal ProbabilisticScoringFeeParameters(object _dummy, long ptr) : base(ptr) { }
20 ~ProbabilisticScoringFeeParameters() {
21 if (ptr != 0) { bindings.ProbabilisticScoringFeeParameters_free(ptr); }
25 * A fixed penalty in msats to apply to each channel.
27 * Default value: 500 msat
29 public long get_base_penalty_msat() {
30 long ret = bindings.ProbabilisticScoringFeeParameters_get_base_penalty_msat(this.ptr);
36 * A fixed penalty in msats to apply to each channel.
38 * Default value: 500 msat
40 public void set_base_penalty_msat(long val) {
41 bindings.ProbabilisticScoringFeeParameters_set_base_penalty_msat(this.ptr, val);
47 * A multiplier used with the total amount flowing over a channel to calculate a fixed penalty
48 * applied to each channel, in excess of the [`base_penalty_msat`].
50 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
51 * fees plus penalty) for large payments. The penalty is computed as the product of this
52 * multiplier and `2^30`ths of the total amount flowing over a channel (i.e. the payment
53 * amount plus the amount of any other HTLCs flowing we sent over the same channel).
55 * ie `base_penalty_amount_multiplier_msat * amount_msat / 2^30`
57 * Default value: 8,192 msat
59 * [`base_penalty_msat`]: Self::base_penalty_msat
61 public long get_base_penalty_amount_multiplier_msat() {
62 long ret = bindings.ProbabilisticScoringFeeParameters_get_base_penalty_amount_multiplier_msat(this.ptr);
68 * A multiplier used with the total amount flowing over a channel to calculate a fixed penalty
69 * applied to each channel, in excess of the [`base_penalty_msat`].
71 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
72 * fees plus penalty) for large payments. The penalty is computed as the product of this
73 * multiplier and `2^30`ths of the total amount flowing over a channel (i.e. the payment
74 * amount plus the amount of any other HTLCs flowing we sent over the same channel).
76 * ie `base_penalty_amount_multiplier_msat * amount_msat / 2^30`
78 * Default value: 8,192 msat
80 * [`base_penalty_msat`]: Self::base_penalty_msat
82 public void set_base_penalty_amount_multiplier_msat(long val) {
83 bindings.ProbabilisticScoringFeeParameters_set_base_penalty_amount_multiplier_msat(this.ptr, val);
89 * A multiplier used in conjunction with the negative `log10` of the channel's success
90 * probability for a payment, as determined by our latest estimates of the channel's
91 * liquidity, to determine the liquidity penalty.
93 * The penalty is based in part on the knowledge learned from prior successful and unsuccessful
94 * payments. This knowledge is decayed over time based on [`liquidity_offset_half_life`]. The
95 * penalty is effectively limited to `2 * liquidity_penalty_multiplier_msat` (corresponding to
96 * lower bounding the success probability to `0.01`) when the amount falls within the
97 * uncertainty bounds of the channel liquidity balance. Amounts above the upper bound will
98 * result in a `u64::max_value` penalty, however.
100 * `-log10(success_probability) * liquidity_penalty_multiplier_msat`
102 * Default value: 30,000 msat
104 * [`liquidity_offset_half_life`]: ProbabilisticScoringDecayParameters::liquidity_offset_half_life
106 public long get_liquidity_penalty_multiplier_msat() {
107 long ret = bindings.ProbabilisticScoringFeeParameters_get_liquidity_penalty_multiplier_msat(this.ptr);
113 * A multiplier used in conjunction with the negative `log10` of the channel's success
114 * probability for a payment, as determined by our latest estimates of the channel's
115 * liquidity, to determine the liquidity penalty.
117 * The penalty is based in part on the knowledge learned from prior successful and unsuccessful
118 * payments. This knowledge is decayed over time based on [`liquidity_offset_half_life`]. The
119 * penalty is effectively limited to `2 * liquidity_penalty_multiplier_msat` (corresponding to
120 * lower bounding the success probability to `0.01`) when the amount falls within the
121 * uncertainty bounds of the channel liquidity balance. Amounts above the upper bound will
122 * result in a `u64::max_value` penalty, however.
124 * `-log10(success_probability) * liquidity_penalty_multiplier_msat`
126 * Default value: 30,000 msat
128 * [`liquidity_offset_half_life`]: ProbabilisticScoringDecayParameters::liquidity_offset_half_life
130 public void set_liquidity_penalty_multiplier_msat(long val) {
131 bindings.ProbabilisticScoringFeeParameters_set_liquidity_penalty_multiplier_msat(this.ptr, val);
137 * A multiplier used in conjunction with the total amount flowing over a channel and the
138 * negative `log10` of the channel's success probability for the payment, as determined by our
139 * latest estimates of the channel's liquidity, to determine the amount penalty.
141 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
142 * fees plus penalty) for large payments. The penalty is computed as the product of this
143 * multiplier and `2^20`ths of the amount flowing over this channel, weighted by the negative
144 * `log10` of the success probability.
146 * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
148 * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
149 * the amount will result in a penalty of the multiplier. And, as the success probability
150 * decreases, the negative `log10` weighting will increase dramatically. For higher success
151 * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
154 * Default value: 192 msat
156 public long get_liquidity_penalty_amount_multiplier_msat() {
157 long ret = bindings.ProbabilisticScoringFeeParameters_get_liquidity_penalty_amount_multiplier_msat(this.ptr);
163 * A multiplier used in conjunction with the total amount flowing over a channel and the
164 * negative `log10` of the channel's success probability for the payment, as determined by our
165 * latest estimates of the channel's liquidity, to determine the amount penalty.
167 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
168 * fees plus penalty) for large payments. The penalty is computed as the product of this
169 * multiplier and `2^20`ths of the amount flowing over this channel, weighted by the negative
170 * `log10` of the success probability.
172 * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
174 * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
175 * the amount will result in a penalty of the multiplier. And, as the success probability
176 * decreases, the negative `log10` weighting will increase dramatically. For higher success
177 * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
180 * Default value: 192 msat
182 public void set_liquidity_penalty_amount_multiplier_msat(long val) {
183 bindings.ProbabilisticScoringFeeParameters_set_liquidity_penalty_amount_multiplier_msat(this.ptr, val);
189 * A multiplier used in conjunction with the negative `log10` of the channel's success
190 * probability for the payment, as determined based on the history of our estimates of the
191 * channel's available liquidity, to determine a penalty.
193 * This penalty is similar to [`liquidity_penalty_multiplier_msat`], however, instead of using
194 * only our latest estimate for the current liquidity available in the channel, it estimates
195 * success probability based on the estimated liquidity available in the channel through
196 * history. Specifically, every time we update our liquidity bounds on a given channel, we
197 * track which of several buckets those bounds fall into, exponentially decaying the
198 * probability of each bucket as new samples are added.
200 * Default value: 10,000 msat
202 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
204 public long get_historical_liquidity_penalty_multiplier_msat() {
205 long ret = bindings.ProbabilisticScoringFeeParameters_get_historical_liquidity_penalty_multiplier_msat(this.ptr);
211 * A multiplier used in conjunction with the negative `log10` of the channel's success
212 * probability for the payment, as determined based on the history of our estimates of the
213 * channel's available liquidity, to determine a penalty.
215 * This penalty is similar to [`liquidity_penalty_multiplier_msat`], however, instead of using
216 * only our latest estimate for the current liquidity available in the channel, it estimates
217 * success probability based on the estimated liquidity available in the channel through
218 * history. Specifically, every time we update our liquidity bounds on a given channel, we
219 * track which of several buckets those bounds fall into, exponentially decaying the
220 * probability of each bucket as new samples are added.
222 * Default value: 10,000 msat
224 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
226 public void set_historical_liquidity_penalty_multiplier_msat(long val) {
227 bindings.ProbabilisticScoringFeeParameters_set_historical_liquidity_penalty_multiplier_msat(this.ptr, val);
233 * A multiplier used in conjunction with the total amount flowing over a channel and the
234 * negative `log10` of the channel's success probability for the payment, as determined based
235 * on the history of our estimates of the channel's available liquidity, to determine a
238 * The purpose of the amount penalty is to avoid having fees dominate the channel cost for
239 * large payments. The penalty is computed as the product of this multiplier and `2^20`ths
240 * of the amount flowing over this channel, weighted by the negative `log10` of the success
243 * This penalty is similar to [`liquidity_penalty_amount_multiplier_msat`], however, instead
244 * of using only our latest estimate for the current liquidity available in the channel, it
245 * estimates success probability based on the estimated liquidity available in the channel
246 * through history. Specifically, every time we update our liquidity bounds on a given
247 * channel, we track which of several buckets those bounds fall into, exponentially decaying
248 * the probability of each bucket as new samples are added.
250 * Default value: 64 msat
252 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
254 public long get_historical_liquidity_penalty_amount_multiplier_msat() {
255 long ret = bindings.ProbabilisticScoringFeeParameters_get_historical_liquidity_penalty_amount_multiplier_msat(this.ptr);
261 * A multiplier used in conjunction with the total amount flowing over a channel and the
262 * negative `log10` of the channel's success probability for the payment, as determined based
263 * on the history of our estimates of the channel's available liquidity, to determine a
266 * The purpose of the amount penalty is to avoid having fees dominate the channel cost for
267 * large payments. The penalty is computed as the product of this multiplier and `2^20`ths
268 * of the amount flowing over this channel, weighted by the negative `log10` of the success
271 * This penalty is similar to [`liquidity_penalty_amount_multiplier_msat`], however, instead
272 * of using only our latest estimate for the current liquidity available in the channel, it
273 * estimates success probability based on the estimated liquidity available in the channel
274 * through history. Specifically, every time we update our liquidity bounds on a given
275 * channel, we track which of several buckets those bounds fall into, exponentially decaying
276 * the probability of each bucket as new samples are added.
278 * Default value: 64 msat
280 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
282 public void set_historical_liquidity_penalty_amount_multiplier_msat(long val) {
283 bindings.ProbabilisticScoringFeeParameters_set_historical_liquidity_penalty_amount_multiplier_msat(this.ptr, val);
289 * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
290 * channel's capacity, (ie. htlc_maximum_msat >= 0.5 * channel_capacity) which makes us
291 * prefer nodes with a smaller `htlc_maximum_msat`. We treat such nodes preferentially
292 * as this makes balance discovery attacks harder to execute, thereby creating an incentive
293 * to restrict `htlc_maximum_msat` and improve privacy.
295 * Default value: 250 msat
297 public long get_anti_probing_penalty_msat() {
298 long ret = bindings.ProbabilisticScoringFeeParameters_get_anti_probing_penalty_msat(this.ptr);
304 * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
305 * channel's capacity, (ie. htlc_maximum_msat >= 0.5 * channel_capacity) which makes us
306 * prefer nodes with a smaller `htlc_maximum_msat`. We treat such nodes preferentially
307 * as this makes balance discovery attacks harder to execute, thereby creating an incentive
308 * to restrict `htlc_maximum_msat` and improve privacy.
310 * Default value: 250 msat
312 public void set_anti_probing_penalty_msat(long val) {
313 bindings.ProbabilisticScoringFeeParameters_set_anti_probing_penalty_msat(this.ptr, val);
319 * This penalty is applied when the total amount flowing over a channel exceeds our current
320 * estimate of the channel's available liquidity. The total amount is the amount of the
321 * current HTLC plus any HTLCs which we've sent over the same channel.
323 * Note that in this case all other penalties, including the
324 * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based
325 * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if
326 * applicable, are still included in the overall penalty.
328 * If you wish to avoid creating paths with such channels entirely, setting this to a value of
329 * `u64::max_value()` will guarantee that.
331 * Default value: 1_0000_0000_000 msat (1 Bitcoin)
333 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
334 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
335 * [`base_penalty_msat`]: Self::base_penalty_msat
336 * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat
338 public long get_considered_impossible_penalty_msat() {
339 long ret = bindings.ProbabilisticScoringFeeParameters_get_considered_impossible_penalty_msat(this.ptr);
345 * This penalty is applied when the total amount flowing over a channel exceeds our current
346 * estimate of the channel's available liquidity. The total amount is the amount of the
347 * current HTLC plus any HTLCs which we've sent over the same channel.
349 * Note that in this case all other penalties, including the
350 * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based
351 * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if
352 * applicable, are still included in the overall penalty.
354 * If you wish to avoid creating paths with such channels entirely, setting this to a value of
355 * `u64::max_value()` will guarantee that.
357 * Default value: 1_0000_0000_000 msat (1 Bitcoin)
359 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
360 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
361 * [`base_penalty_msat`]: Self::base_penalty_msat
362 * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat
364 public void set_considered_impossible_penalty_msat(long val) {
365 bindings.ProbabilisticScoringFeeParameters_set_considered_impossible_penalty_msat(this.ptr, val);
371 * In order to calculate most of the scores above, we must first convert a lower and upper
372 * bound on the available liquidity in a channel into the probability that we think a payment
373 * will succeed. That probability is derived from a Probability Density Function for where we
374 * think the liquidity in a channel likely lies, given such bounds.
376 * If this flag is set, that PDF is simply a constant - we assume that the actual available
377 * liquidity in a channel is just as likely to be at any point between our lower and upper
380 * If this flag is *not* set, that PDF is `(x - 0.5*capacity) ^ 2`. That is, we use an
381 * exponential curve which expects the liquidity of a channel to lie \"at the edges\". This
382 * matches experimental results - most routing nodes do not aggressively rebalance their
383 * channels and flows in the network are often unbalanced, leaving liquidity usually
386 * Thus, for the \"best\" routes, leave this flag `false`. However, the flag does imply a number
387 * of floating-point multiplications in the hottest routing code, which may lead to routing
388 * performance degradation on some machines.
390 * Default value: false
392 public bool get_linear_success_probability() {
393 bool ret = bindings.ProbabilisticScoringFeeParameters_get_linear_success_probability(this.ptr);
399 * In order to calculate most of the scores above, we must first convert a lower and upper
400 * bound on the available liquidity in a channel into the probability that we think a payment
401 * will succeed. That probability is derived from a Probability Density Function for where we
402 * think the liquidity in a channel likely lies, given such bounds.
404 * If this flag is set, that PDF is simply a constant - we assume that the actual available
405 * liquidity in a channel is just as likely to be at any point between our lower and upper
408 * If this flag is *not* set, that PDF is `(x - 0.5*capacity) ^ 2`. That is, we use an
409 * exponential curve which expects the liquidity of a channel to lie \"at the edges\". This
410 * matches experimental results - most routing nodes do not aggressively rebalance their
411 * channels and flows in the network are often unbalanced, leaving liquidity usually
414 * Thus, for the \"best\" routes, leave this flag `false`. However, the flag does imply a number
415 * of floating-point multiplications in the hottest routing code, which may lead to routing
416 * performance degradation on some machines.
418 * Default value: false
420 public void set_linear_success_probability(bool val) {
421 bindings.ProbabilisticScoringFeeParameters_set_linear_success_probability(this.ptr, val);
426 internal long clone_ptr() {
427 long ret = bindings.ProbabilisticScoringFeeParameters_clone_ptr(this.ptr);
433 * Creates a copy of the ProbabilisticScoringFeeParameters
435 public ProbabilisticScoringFeeParameters clone() {
436 long ret = bindings.ProbabilisticScoringFeeParameters_clone(this.ptr);
438 if (ret >= 0 && ret <= 4096) { return null; }
439 org.ldk.structs.ProbabilisticScoringFeeParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringFeeParameters(null, ret); }
440 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.AddLast(this); };
445 * Creates a "default" ProbabilisticScoringFeeParameters. See struct and individual field documentaiton for details on which values are used.
447 public static ProbabilisticScoringFeeParameters with_default() {
448 long ret = bindings.ProbabilisticScoringFeeParameters_default();
449 if (ret >= 0 && ret <= 4096) { return null; }
450 org.ldk.structs.ProbabilisticScoringFeeParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringFeeParameters(null, ret); }
451 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.AddLast(ret_hu_conv); };
456 * Marks the node with the given `node_id` as banned,
457 * i.e it will be avoided during path finding.
459 public void add_banned(org.ldk.structs.NodeId node_id) {
460 bindings.ProbabilisticScoringFeeParameters_add_banned(this.ptr, node_id == null ? 0 : node_id.ptr);
462 GC.KeepAlive(node_id);
463 if (this != null) { this.ptrs_to.AddLast(node_id); };
467 * Marks all nodes in the given list as banned, i.e.,
468 * they will be avoided during path finding.
470 public void add_banned_from_list(NodeId[] node_ids) {
471 bindings.ProbabilisticScoringFeeParameters_add_banned_from_list(this.ptr, InternalUtils.encodeUint64Array(InternalUtils.mapArray(node_ids, node_ids_conv_8 => node_ids_conv_8 == null ? 0 : node_ids_conv_8.ptr)));
473 GC.KeepAlive(node_ids);
474 foreach (NodeId node_ids_conv_8 in node_ids) { if (this != null) { this.ptrs_to.AddLast(node_ids_conv_8); }; };
478 * Removes the node with the given `node_id` from the list of nodes to avoid.
480 public void remove_banned(org.ldk.structs.NodeId node_id) {
481 bindings.ProbabilisticScoringFeeParameters_remove_banned(this.ptr, node_id == null ? 0 : node_id.ptr);
483 GC.KeepAlive(node_id);
484 if (this != null) { this.ptrs_to.AddLast(node_id); };
488 * Sets a manual penalty for the given node.
490 public void set_manual_penalty(org.ldk.structs.NodeId node_id, long penalty) {
491 bindings.ProbabilisticScoringFeeParameters_set_manual_penalty(this.ptr, node_id == null ? 0 : node_id.ptr, penalty);
493 GC.KeepAlive(node_id);
494 GC.KeepAlive(penalty);
495 if (this != null) { this.ptrs_to.AddLast(node_id); };
499 * Removes the node with the given `node_id` from the list of manual penalties.
501 public void remove_manual_penalty(org.ldk.structs.NodeId node_id) {
502 bindings.ProbabilisticScoringFeeParameters_remove_manual_penalty(this.ptr, node_id == null ? 0 : node_id.ptr);
504 GC.KeepAlive(node_id);
505 if (this != null) { this.ptrs_to.AddLast(node_id); };
509 * Clears the list of manual penalties that are applied during path finding.
511 public void clear_manual_penalties() {
512 bindings.ProbabilisticScoringFeeParameters_clear_manual_penalties(this.ptr);