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 ProbabilisticScoringParameters : CommonBase {
19 internal ProbabilisticScoringParameters(object _dummy, long ptr) : base(ptr) { }
20 ~ProbabilisticScoringParameters() {
21 if (ptr != 0) { bindings.ProbabilisticScoringParameters_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.ProbabilisticScoringParameters_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.ProbabilisticScoringParameters_set_base_penalty_msat(this.ptr, val);
47 * A multiplier used with the payment amount to calculate a fixed penalty applied to each
48 * 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 payment amount.
54 * ie `base_penalty_amount_multiplier_msat * amount_msat / 2^30`
56 * Default value: 8,192 msat
58 * [`base_penalty_msat`]: Self::base_penalty_msat
60 public long get_base_penalty_amount_multiplier_msat() {
61 long ret = bindings.ProbabilisticScoringParameters_get_base_penalty_amount_multiplier_msat(this.ptr);
67 * A multiplier used with the payment amount to calculate a fixed penalty applied to each
68 * channel, in excess of the [`base_penalty_msat`].
70 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
71 * fees plus penalty) for large payments. The penalty is computed as the product of this
72 * multiplier and `2^30`ths of the payment amount.
74 * ie `base_penalty_amount_multiplier_msat * amount_msat / 2^30`
76 * Default value: 8,192 msat
78 * [`base_penalty_msat`]: Self::base_penalty_msat
80 public void set_base_penalty_amount_multiplier_msat(long val) {
81 bindings.ProbabilisticScoringParameters_set_base_penalty_amount_multiplier_msat(this.ptr, val);
87 * A multiplier used in conjunction with the negative `log10` of the channel's success
88 * probability for a payment, as determined by our latest estimates of the channel's
89 * liquidity, to determine the liquidity penalty.
91 * The penalty is based in part on the knowledge learned from prior successful and unsuccessful
92 * payments. This knowledge is decayed over time based on [`liquidity_offset_half_life`]. The
93 * penalty is effectively limited to `2 * liquidity_penalty_multiplier_msat` (corresponding to
94 * lower bounding the success probability to `0.01`) when the amount falls within the
95 * uncertainty bounds of the channel liquidity balance. Amounts above the upper bound will
96 * result in a `u64::max_value` penalty, however.
98 * `-log10(success_probability) * liquidity_penalty_multiplier_msat`
100 * Default value: 30,000 msat
102 * [`liquidity_offset_half_life`]: Self::liquidity_offset_half_life
104 public long get_liquidity_penalty_multiplier_msat() {
105 long ret = bindings.ProbabilisticScoringParameters_get_liquidity_penalty_multiplier_msat(this.ptr);
111 * A multiplier used in conjunction with the negative `log10` of the channel's success
112 * probability for a payment, as determined by our latest estimates of the channel's
113 * liquidity, to determine the liquidity penalty.
115 * The penalty is based in part on the knowledge learned from prior successful and unsuccessful
116 * payments. This knowledge is decayed over time based on [`liquidity_offset_half_life`]. The
117 * penalty is effectively limited to `2 * liquidity_penalty_multiplier_msat` (corresponding to
118 * lower bounding the success probability to `0.01`) when the amount falls within the
119 * uncertainty bounds of the channel liquidity balance. Amounts above the upper bound will
120 * result in a `u64::max_value` penalty, however.
122 * `-log10(success_probability) * liquidity_penalty_multiplier_msat`
124 * Default value: 30,000 msat
126 * [`liquidity_offset_half_life`]: Self::liquidity_offset_half_life
128 public void set_liquidity_penalty_multiplier_msat(long val) {
129 bindings.ProbabilisticScoringParameters_set_liquidity_penalty_multiplier_msat(this.ptr, val);
135 * Whenever this amount of time elapses since the last update to a channel's liquidity bounds,
136 * the distance from the bounds to \"zero\" is cut in half. In other words, the lower-bound on
137 * the available liquidity is halved and the upper-bound moves half-way to the channel's total
140 * Because halving the liquidity bounds grows the uncertainty on the channel's liquidity,
141 * the penalty for an amount within the new bounds may change. See the [`ProbabilisticScorer`]
142 * struct documentation for more info on the way the liquidity bounds are used.
144 * For example, if the channel's capacity is 1 million sats, and the current upper and lower
145 * liquidity bounds are 200,000 sats and 600,000 sats, after this amount of time the upper
146 * and lower liquidity bounds will be decayed to 100,000 and 800,000 sats.
148 * Default value: 6 hours
152 * When built with the `no-std` feature, time will never elapse. Therefore, the channel
153 * liquidity knowledge will never decay except when the bounds cross.
155 public long get_liquidity_offset_half_life() {
156 long ret = bindings.ProbabilisticScoringParameters_get_liquidity_offset_half_life(this.ptr);
162 * Whenever this amount of time elapses since the last update to a channel's liquidity bounds,
163 * the distance from the bounds to \"zero\" is cut in half. In other words, the lower-bound on
164 * the available liquidity is halved and the upper-bound moves half-way to the channel's total
167 * Because halving the liquidity bounds grows the uncertainty on the channel's liquidity,
168 * the penalty for an amount within the new bounds may change. See the [`ProbabilisticScorer`]
169 * struct documentation for more info on the way the liquidity bounds are used.
171 * For example, if the channel's capacity is 1 million sats, and the current upper and lower
172 * liquidity bounds are 200,000 sats and 600,000 sats, after this amount of time the upper
173 * and lower liquidity bounds will be decayed to 100,000 and 800,000 sats.
175 * Default value: 6 hours
179 * When built with the `no-std` feature, time will never elapse. Therefore, the channel
180 * liquidity knowledge will never decay except when the bounds cross.
182 public void set_liquidity_offset_half_life(long val) {
183 bindings.ProbabilisticScoringParameters_set_liquidity_offset_half_life(this.ptr, val);
189 * A multiplier used in conjunction with a payment amount and the negative `log10` of the
190 * channel's success probability for the payment, as determined by our latest estimates of the
191 * channel's liquidity, to determine the amount penalty.
193 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
194 * fees plus penalty) for large payments. The penalty is computed as the product of this
195 * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the
196 * success probability.
198 * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
200 * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
201 * the amount will result in a penalty of the multiplier. And, as the success probability
202 * decreases, the negative `log10` weighting will increase dramatically. For higher success
203 * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
206 * Default value: 192 msat
208 public long get_liquidity_penalty_amount_multiplier_msat() {
209 long ret = bindings.ProbabilisticScoringParameters_get_liquidity_penalty_amount_multiplier_msat(this.ptr);
215 * A multiplier used in conjunction with a payment amount and the negative `log10` of the
216 * channel's success probability for the payment, as determined by our latest estimates of the
217 * channel's liquidity, to determine the amount penalty.
219 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
220 * fees plus penalty) for large payments. The penalty is computed as the product of this
221 * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the
222 * success probability.
224 * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
226 * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
227 * the amount will result in a penalty of the multiplier. And, as the success probability
228 * decreases, the negative `log10` weighting will increase dramatically. For higher success
229 * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
232 * Default value: 192 msat
234 public void set_liquidity_penalty_amount_multiplier_msat(long val) {
235 bindings.ProbabilisticScoringParameters_set_liquidity_penalty_amount_multiplier_msat(this.ptr, val);
241 * A multiplier used in conjunction with the negative `log10` of the channel's success
242 * probability for the payment, as determined based on the history of our estimates of the
243 * channel's available liquidity, to determine a penalty.
245 * This penalty is similar to [`liquidity_penalty_multiplier_msat`], however, instead of using
246 * only our latest estimate for the current liquidity available in the channel, it estimates
247 * success probability based on the estimated liquidity available in the channel through
248 * history. Specifically, every time we update our liquidity bounds on a given channel, we
249 * track which of several buckets those bounds fall into, exponentially decaying the
250 * probability of each bucket as new samples are added.
252 * Default value: 10,000 msat
254 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
256 public long get_historical_liquidity_penalty_multiplier_msat() {
257 long ret = bindings.ProbabilisticScoringParameters_get_historical_liquidity_penalty_multiplier_msat(this.ptr);
263 * A multiplier used in conjunction with the negative `log10` of the channel's success
264 * probability for the payment, as determined based on the history of our estimates of the
265 * channel's available liquidity, to determine a penalty.
267 * This penalty is similar to [`liquidity_penalty_multiplier_msat`], however, instead of using
268 * only our latest estimate for the current liquidity available in the channel, it estimates
269 * success probability based on the estimated liquidity available in the channel through
270 * history. Specifically, every time we update our liquidity bounds on a given channel, we
271 * track which of several buckets those bounds fall into, exponentially decaying the
272 * probability of each bucket as new samples are added.
274 * Default value: 10,000 msat
276 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
278 public void set_historical_liquidity_penalty_multiplier_msat(long val) {
279 bindings.ProbabilisticScoringParameters_set_historical_liquidity_penalty_multiplier_msat(this.ptr, val);
285 * A multiplier used in conjunction with the payment amount and the negative `log10` of the
286 * channel's success probability for the payment, as determined based on the history of our
287 * estimates of the channel's available liquidity, to determine a penalty.
289 * The purpose of the amount penalty is to avoid having fees dominate the channel cost for
290 * large payments. The penalty is computed as the product of this multiplier and the `2^20`ths
291 * of the payment amount, weighted by the negative `log10` of the success probability.
293 * This penalty is similar to [`liquidity_penalty_amount_multiplier_msat`], however, instead
294 * of using only our latest estimate for the current liquidity available in the channel, it
295 * estimates success probability based on the estimated liquidity available in the channel
296 * through history. Specifically, every time we update our liquidity bounds on a given
297 * channel, we track which of several buckets those bounds fall into, exponentially decaying
298 * the probability of each bucket as new samples are added.
300 * Default value: 64 msat
302 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
304 public long get_historical_liquidity_penalty_amount_multiplier_msat() {
305 long ret = bindings.ProbabilisticScoringParameters_get_historical_liquidity_penalty_amount_multiplier_msat(this.ptr);
311 * A multiplier used in conjunction with the payment amount and the negative `log10` of the
312 * channel's success probability for the payment, as determined based on the history of our
313 * estimates of the channel's available liquidity, to determine a penalty.
315 * The purpose of the amount penalty is to avoid having fees dominate the channel cost for
316 * large payments. The penalty is computed as the product of this multiplier and the `2^20`ths
317 * of the payment amount, weighted by the negative `log10` of the success probability.
319 * This penalty is similar to [`liquidity_penalty_amount_multiplier_msat`], however, instead
320 * of using only our latest estimate for the current liquidity available in the channel, it
321 * estimates success probability based on the estimated liquidity available in the channel
322 * through history. Specifically, every time we update our liquidity bounds on a given
323 * channel, we track which of several buckets those bounds fall into, exponentially decaying
324 * the probability of each bucket as new samples are added.
326 * Default value: 64 msat
328 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
330 public void set_historical_liquidity_penalty_amount_multiplier_msat(long val) {
331 bindings.ProbabilisticScoringParameters_set_historical_liquidity_penalty_amount_multiplier_msat(this.ptr, val);
337 * If we aren't learning any new datapoints for a channel, the historical liquidity bounds
338 * tracking can simply live on with increasingly stale data. Instead, when a channel has not
339 * seen a liquidity estimate update for this amount of time, the historical datapoints are
342 * Note that after 16 or more half lives all historical data will be completely gone.
344 * Default value: 14 days
346 public long get_historical_no_updates_half_life() {
347 long ret = bindings.ProbabilisticScoringParameters_get_historical_no_updates_half_life(this.ptr);
353 * If we aren't learning any new datapoints for a channel, the historical liquidity bounds
354 * tracking can simply live on with increasingly stale data. Instead, when a channel has not
355 * seen a liquidity estimate update for this amount of time, the historical datapoints are
358 * Note that after 16 or more half lives all historical data will be completely gone.
360 * Default value: 14 days
362 public void set_historical_no_updates_half_life(long val) {
363 bindings.ProbabilisticScoringParameters_set_historical_no_updates_half_life(this.ptr, val);
369 * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
370 * channel's capacity, which makes us prefer nodes with a smaller `htlc_maximum_msat`. We
371 * treat such nodes preferentially as this makes balance discovery attacks harder to execute,
372 * thereby creating an incentive to restrict `htlc_maximum_msat` and improve privacy.
374 * Default value: 250 msat
376 public long get_anti_probing_penalty_msat() {
377 long ret = bindings.ProbabilisticScoringParameters_get_anti_probing_penalty_msat(this.ptr);
383 * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
384 * channel's capacity, which makes us prefer nodes with a smaller `htlc_maximum_msat`. We
385 * treat such nodes preferentially as this makes balance discovery attacks harder to execute,
386 * thereby creating an incentive to restrict `htlc_maximum_msat` and improve privacy.
388 * Default value: 250 msat
390 public void set_anti_probing_penalty_msat(long val) {
391 bindings.ProbabilisticScoringParameters_set_anti_probing_penalty_msat(this.ptr, val);
397 * This penalty is applied when the amount we're attempting to send over a channel exceeds our
398 * current estimate of the channel's available liquidity.
400 * Note that in this case all other penalties, including the
401 * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based
402 * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if
403 * applicable, are still included in the overall penalty.
405 * If you wish to avoid creating paths with such channels entirely, setting this to a value of
406 * `u64::max_value()` will guarantee that.
408 * Default value: 1_0000_0000_000 msat (1 Bitcoin)
410 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
411 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
412 * [`base_penalty_msat`]: Self::base_penalty_msat
413 * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat
415 public long get_considered_impossible_penalty_msat() {
416 long ret = bindings.ProbabilisticScoringParameters_get_considered_impossible_penalty_msat(this.ptr);
422 * This penalty is applied when the amount we're attempting to send over a channel exceeds our
423 * current estimate of the channel's available liquidity.
425 * Note that in this case all other penalties, including the
426 * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based
427 * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if
428 * applicable, are still included in the overall penalty.
430 * If you wish to avoid creating paths with such channels entirely, setting this to a value of
431 * `u64::max_value()` will guarantee that.
433 * Default value: 1_0000_0000_000 msat (1 Bitcoin)
435 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
436 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
437 * [`base_penalty_msat`]: Self::base_penalty_msat
438 * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat
440 public void set_considered_impossible_penalty_msat(long val) {
441 bindings.ProbabilisticScoringParameters_set_considered_impossible_penalty_msat(this.ptr, val);
446 internal long clone_ptr() {
447 long ret = bindings.ProbabilisticScoringParameters_clone_ptr(this.ptr);
453 * Creates a copy of the ProbabilisticScoringParameters
455 public ProbabilisticScoringParameters clone() {
456 long ret = bindings.ProbabilisticScoringParameters_clone(this.ptr);
458 if (ret >= 0 && ret <= 4096) { return null; }
459 org.ldk.structs.ProbabilisticScoringParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringParameters(null, ret); }
460 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.AddLast(this); };
465 * Marks all nodes in the given list as banned, i.e.,
466 * they will be avoided during path finding.
468 public void add_banned_from_list(NodeId[] node_ids) {
469 bindings.ProbabilisticScoringParameters_add_banned_from_list(this.ptr, node_ids != null ? InternalUtils.mapArray(node_ids, node_ids_conv_8 => node_ids_conv_8 == null ? 0 : node_ids_conv_8.ptr) : null);
471 GC.KeepAlive(node_ids);
472 foreach (NodeId node_ids_conv_8 in node_ids) { if (this != null) { this.ptrs_to.AddLast(node_ids_conv_8); }; };
476 * Creates a "default" ProbabilisticScoringParameters. See struct and individual field documentaiton for details on which values are used.
478 public static ProbabilisticScoringParameters with_default() {
479 long ret = bindings.ProbabilisticScoringParameters_default();
480 if (ret >= 0 && ret <= 4096) { return null; }
481 org.ldk.structs.ProbabilisticScoringParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringParameters(null, ret); }
482 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.AddLast(ret_hu_conv); };