1 package org.ldk.structs;
3 import org.ldk.impl.bindings;
4 import org.ldk.enums.*;
6 import java.util.Arrays;
7 import java.lang.ref.Reference;
8 import javax.annotation.Nullable;
12 * Parameters for configuring [`ProbabilisticScorer`].
14 * Used to configure base, liquidity, and amount penalties, the sum of which comprises the channel
15 * penalty (i.e., the amount in msats willing to be paid to avoid routing through the channel).
17 * The penalty applied to any channel by the [`ProbabilisticScorer`] is the sum of each of the
20 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
21 public class ProbabilisticScoringFeeParameters extends CommonBase {
22 ProbabilisticScoringFeeParameters(Object _dummy, long ptr) { super(ptr); }
23 @Override @SuppressWarnings("deprecation")
24 protected void finalize() throws Throwable {
26 if (ptr != 0) { bindings.ProbabilisticScoringFeeParameters_free(ptr); }
30 * A fixed penalty in msats to apply to each channel.
32 * Default value: 500 msat
34 public long get_base_penalty_msat() {
35 long ret = bindings.ProbabilisticScoringFeeParameters_get_base_penalty_msat(this.ptr);
36 Reference.reachabilityFence(this);
41 * A fixed penalty in msats to apply to each channel.
43 * Default value: 500 msat
45 public void set_base_penalty_msat(long val) {
46 bindings.ProbabilisticScoringFeeParameters_set_base_penalty_msat(this.ptr, val);
47 Reference.reachabilityFence(this);
48 Reference.reachabilityFence(val);
52 * A multiplier used with the total amount flowing over a channel to calculate a fixed penalty
53 * applied to each channel, in excess of the [`base_penalty_msat`].
55 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
56 * fees plus penalty) for large payments. The penalty is computed as the product of this
57 * multiplier and `2^30`ths of the total amount flowing over a channel (i.e. the payment
58 * amount plus the amount of any other HTLCs flowing we sent over the same channel).
60 * ie `base_penalty_amount_multiplier_msat * amount_msat / 2^30`
62 * Default value: 8,192 msat
64 * [`base_penalty_msat`]: Self::base_penalty_msat
66 public long get_base_penalty_amount_multiplier_msat() {
67 long ret = bindings.ProbabilisticScoringFeeParameters_get_base_penalty_amount_multiplier_msat(this.ptr);
68 Reference.reachabilityFence(this);
73 * A multiplier used with the total amount flowing over a channel to calculate a fixed penalty
74 * applied to each channel, in excess of the [`base_penalty_msat`].
76 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
77 * fees plus penalty) for large payments. The penalty is computed as the product of this
78 * multiplier and `2^30`ths of the total amount flowing over a channel (i.e. the payment
79 * amount plus the amount of any other HTLCs flowing we sent over the same channel).
81 * ie `base_penalty_amount_multiplier_msat * amount_msat / 2^30`
83 * Default value: 8,192 msat
85 * [`base_penalty_msat`]: Self::base_penalty_msat
87 public void set_base_penalty_amount_multiplier_msat(long val) {
88 bindings.ProbabilisticScoringFeeParameters_set_base_penalty_amount_multiplier_msat(this.ptr, val);
89 Reference.reachabilityFence(this);
90 Reference.reachabilityFence(val);
94 * A multiplier used in conjunction with the negative `log10` of the channel's success
95 * probability for a payment, as determined by our latest estimates of the channel's
96 * liquidity, to determine the liquidity penalty.
98 * The penalty is based in part on the knowledge learned from prior successful and unsuccessful
99 * payments. This knowledge is decayed over time based on [`liquidity_offset_half_life`]. The
100 * penalty is effectively limited to `2 * liquidity_penalty_multiplier_msat` (corresponding to
101 * lower bounding the success probability to `0.01`) when the amount falls within the
102 * uncertainty bounds of the channel liquidity balance. Amounts above the upper bound will
103 * result in a `u64::max_value` penalty, however.
105 * `-log10(success_probability) * liquidity_penalty_multiplier_msat`
107 * Default value: 30,000 msat
109 * [`liquidity_offset_half_life`]: ProbabilisticScoringDecayParameters::liquidity_offset_half_life
111 public long get_liquidity_penalty_multiplier_msat() {
112 long ret = bindings.ProbabilisticScoringFeeParameters_get_liquidity_penalty_multiplier_msat(this.ptr);
113 Reference.reachabilityFence(this);
118 * A multiplier used in conjunction with the negative `log10` of the channel's success
119 * probability for a payment, as determined by our latest estimates of the channel's
120 * liquidity, to determine the liquidity penalty.
122 * The penalty is based in part on the knowledge learned from prior successful and unsuccessful
123 * payments. This knowledge is decayed over time based on [`liquidity_offset_half_life`]. The
124 * penalty is effectively limited to `2 * liquidity_penalty_multiplier_msat` (corresponding to
125 * lower bounding the success probability to `0.01`) when the amount falls within the
126 * uncertainty bounds of the channel liquidity balance. Amounts above the upper bound will
127 * result in a `u64::max_value` penalty, however.
129 * `-log10(success_probability) * liquidity_penalty_multiplier_msat`
131 * Default value: 30,000 msat
133 * [`liquidity_offset_half_life`]: ProbabilisticScoringDecayParameters::liquidity_offset_half_life
135 public void set_liquidity_penalty_multiplier_msat(long val) {
136 bindings.ProbabilisticScoringFeeParameters_set_liquidity_penalty_multiplier_msat(this.ptr, val);
137 Reference.reachabilityFence(this);
138 Reference.reachabilityFence(val);
142 * A multiplier used in conjunction with the total amount flowing over a channel and the
143 * negative `log10` of the channel's success probability for the payment, as determined by our
144 * latest estimates of the channel's liquidity, to determine the amount penalty.
146 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
147 * fees plus penalty) for large payments. The penalty is computed as the product of this
148 * multiplier and `2^20`ths of the amount flowing over this channel, weighted by the negative
149 * `log10` of the success probability.
151 * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
153 * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
154 * the amount will result in a penalty of the multiplier. And, as the success probability
155 * decreases, the negative `log10` weighting will increase dramatically. For higher success
156 * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
159 * Default value: 192 msat
161 public long get_liquidity_penalty_amount_multiplier_msat() {
162 long ret = bindings.ProbabilisticScoringFeeParameters_get_liquidity_penalty_amount_multiplier_msat(this.ptr);
163 Reference.reachabilityFence(this);
168 * A multiplier used in conjunction with the total amount flowing over a channel and the
169 * negative `log10` of the channel's success probability for the payment, as determined by our
170 * latest estimates of the channel's liquidity, to determine the amount penalty.
172 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
173 * fees plus penalty) for large payments. The penalty is computed as the product of this
174 * multiplier and `2^20`ths of the amount flowing over this channel, weighted by the negative
175 * `log10` of the success probability.
177 * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
179 * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
180 * the amount will result in a penalty of the multiplier. And, as the success probability
181 * decreases, the negative `log10` weighting will increase dramatically. For higher success
182 * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
185 * Default value: 192 msat
187 public void set_liquidity_penalty_amount_multiplier_msat(long val) {
188 bindings.ProbabilisticScoringFeeParameters_set_liquidity_penalty_amount_multiplier_msat(this.ptr, val);
189 Reference.reachabilityFence(this);
190 Reference.reachabilityFence(val);
194 * A multiplier used in conjunction with the negative `log10` of the channel's success
195 * probability for the payment, as determined based on the history of our estimates of the
196 * channel's available liquidity, to determine a penalty.
198 * This penalty is similar to [`liquidity_penalty_multiplier_msat`], however, instead of using
199 * only our latest estimate for the current liquidity available in the channel, it estimates
200 * success probability based on the estimated liquidity available in the channel through
201 * history. Specifically, every time we update our liquidity bounds on a given channel, we
202 * track which of several buckets those bounds fall into, exponentially decaying the
203 * probability of each bucket as new samples are added.
205 * Default value: 10,000 msat
207 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
209 public long get_historical_liquidity_penalty_multiplier_msat() {
210 long ret = bindings.ProbabilisticScoringFeeParameters_get_historical_liquidity_penalty_multiplier_msat(this.ptr);
211 Reference.reachabilityFence(this);
216 * A multiplier used in conjunction with the negative `log10` of the channel's success
217 * probability for the payment, as determined based on the history of our estimates of the
218 * channel's available liquidity, to determine a penalty.
220 * This penalty is similar to [`liquidity_penalty_multiplier_msat`], however, instead of using
221 * only our latest estimate for the current liquidity available in the channel, it estimates
222 * success probability based on the estimated liquidity available in the channel through
223 * history. Specifically, every time we update our liquidity bounds on a given channel, we
224 * track which of several buckets those bounds fall into, exponentially decaying the
225 * probability of each bucket as new samples are added.
227 * Default value: 10,000 msat
229 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
231 public void set_historical_liquidity_penalty_multiplier_msat(long val) {
232 bindings.ProbabilisticScoringFeeParameters_set_historical_liquidity_penalty_multiplier_msat(this.ptr, val);
233 Reference.reachabilityFence(this);
234 Reference.reachabilityFence(val);
238 * A multiplier used in conjunction with the total amount flowing over a channel and the
239 * negative `log10` of the channel's success probability for the payment, as determined based
240 * on the history of our estimates of the channel's available liquidity, to determine a
243 * The purpose of the amount penalty is to avoid having fees dominate the channel cost for
244 * large payments. The penalty is computed as the product of this multiplier and `2^20`ths
245 * of the amount flowing over this channel, weighted by the negative `log10` of the success
248 * This penalty is similar to [`liquidity_penalty_amount_multiplier_msat`], however, instead
249 * of using only our latest estimate for the current liquidity available in the channel, it
250 * estimates success probability based on the estimated liquidity available in the channel
251 * through history. Specifically, every time we update our liquidity bounds on a given
252 * channel, we track which of several buckets those bounds fall into, exponentially decaying
253 * the probability of each bucket as new samples are added.
255 * Default value: 64 msat
257 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
259 public long get_historical_liquidity_penalty_amount_multiplier_msat() {
260 long ret = bindings.ProbabilisticScoringFeeParameters_get_historical_liquidity_penalty_amount_multiplier_msat(this.ptr);
261 Reference.reachabilityFence(this);
266 * A multiplier used in conjunction with the total amount flowing over a channel and the
267 * negative `log10` of the channel's success probability for the payment, as determined based
268 * on the history of our estimates of the channel's available liquidity, to determine a
271 * The purpose of the amount penalty is to avoid having fees dominate the channel cost for
272 * large payments. The penalty is computed as the product of this multiplier and `2^20`ths
273 * of the amount flowing over this channel, weighted by the negative `log10` of the success
276 * This penalty is similar to [`liquidity_penalty_amount_multiplier_msat`], however, instead
277 * of using only our latest estimate for the current liquidity available in the channel, it
278 * estimates success probability based on the estimated liquidity available in the channel
279 * through history. Specifically, every time we update our liquidity bounds on a given
280 * channel, we track which of several buckets those bounds fall into, exponentially decaying
281 * the probability of each bucket as new samples are added.
283 * Default value: 64 msat
285 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
287 public void set_historical_liquidity_penalty_amount_multiplier_msat(long val) {
288 bindings.ProbabilisticScoringFeeParameters_set_historical_liquidity_penalty_amount_multiplier_msat(this.ptr, val);
289 Reference.reachabilityFence(this);
290 Reference.reachabilityFence(val);
294 * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
295 * channel's capacity, (ie. htlc_maximum_msat >= 0.5 * channel_capacity) which makes us
296 * prefer nodes with a smaller `htlc_maximum_msat`. We treat such nodes preferentially
297 * as this makes balance discovery attacks harder to execute, thereby creating an incentive
298 * to restrict `htlc_maximum_msat` and improve privacy.
300 * Default value: 250 msat
302 public long get_anti_probing_penalty_msat() {
303 long ret = bindings.ProbabilisticScoringFeeParameters_get_anti_probing_penalty_msat(this.ptr);
304 Reference.reachabilityFence(this);
309 * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
310 * channel's capacity, (ie. htlc_maximum_msat >= 0.5 * channel_capacity) which makes us
311 * prefer nodes with a smaller `htlc_maximum_msat`. We treat such nodes preferentially
312 * as this makes balance discovery attacks harder to execute, thereby creating an incentive
313 * to restrict `htlc_maximum_msat` and improve privacy.
315 * Default value: 250 msat
317 public void set_anti_probing_penalty_msat(long val) {
318 bindings.ProbabilisticScoringFeeParameters_set_anti_probing_penalty_msat(this.ptr, val);
319 Reference.reachabilityFence(this);
320 Reference.reachabilityFence(val);
324 * This penalty is applied when the total amount flowing over a channel exceeds our current
325 * estimate of the channel's available liquidity. The total amount is the amount of the
326 * current HTLC plus any HTLCs which we've sent over the same channel.
328 * Note that in this case all other penalties, including the
329 * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based
330 * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if
331 * applicable, are still included in the overall penalty.
333 * If you wish to avoid creating paths with such channels entirely, setting this to a value of
334 * `u64::max_value()` will guarantee that.
336 * Default value: 1_0000_0000_000 msat (1 Bitcoin)
338 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
339 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
340 * [`base_penalty_msat`]: Self::base_penalty_msat
341 * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat
343 public long get_considered_impossible_penalty_msat() {
344 long ret = bindings.ProbabilisticScoringFeeParameters_get_considered_impossible_penalty_msat(this.ptr);
345 Reference.reachabilityFence(this);
350 * This penalty is applied when the total amount flowing over a channel exceeds our current
351 * estimate of the channel's available liquidity. The total amount is the amount of the
352 * current HTLC plus any HTLCs which we've sent over the same channel.
354 * Note that in this case all other penalties, including the
355 * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based
356 * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if
357 * applicable, are still included in the overall penalty.
359 * If you wish to avoid creating paths with such channels entirely, setting this to a value of
360 * `u64::max_value()` will guarantee that.
362 * Default value: 1_0000_0000_000 msat (1 Bitcoin)
364 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
365 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
366 * [`base_penalty_msat`]: Self::base_penalty_msat
367 * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat
369 public void set_considered_impossible_penalty_msat(long val) {
370 bindings.ProbabilisticScoringFeeParameters_set_considered_impossible_penalty_msat(this.ptr, val);
371 Reference.reachabilityFence(this);
372 Reference.reachabilityFence(val);
376 * In order to calculate most of the scores above, we must first convert a lower and upper
377 * bound on the available liquidity in a channel into the probability that we think a payment
378 * will succeed. That probability is derived from a Probability Density Function for where we
379 * think the liquidity in a channel likely lies, given such bounds.
381 * If this flag is set, that PDF is simply a constant - we assume that the actual available
382 * liquidity in a channel is just as likely to be at any point between our lower and upper
385 * If this flag is *not* set, that PDF is `(x - 0.5*capacity) ^ 2`. That is, we use an
386 * exponential curve which expects the liquidity of a channel to lie \"at the edges\". This
387 * matches experimental results - most routing nodes do not aggressively rebalance their
388 * channels and flows in the network are often unbalanced, leaving liquidity usually
391 * Thus, for the \"best\" routes, leave this flag `false`. However, the flag does imply a number
392 * of floating-point multiplications in the hottest routing code, which may lead to routing
393 * performance degradation on some machines.
395 * Default value: false
397 public boolean get_linear_success_probability() {
398 boolean ret = bindings.ProbabilisticScoringFeeParameters_get_linear_success_probability(this.ptr);
399 Reference.reachabilityFence(this);
404 * In order to calculate most of the scores above, we must first convert a lower and upper
405 * bound on the available liquidity in a channel into the probability that we think a payment
406 * will succeed. That probability is derived from a Probability Density Function for where we
407 * think the liquidity in a channel likely lies, given such bounds.
409 * If this flag is set, that PDF is simply a constant - we assume that the actual available
410 * liquidity in a channel is just as likely to be at any point between our lower and upper
413 * If this flag is *not* set, that PDF is `(x - 0.5*capacity) ^ 2`. That is, we use an
414 * exponential curve which expects the liquidity of a channel to lie \"at the edges\". This
415 * matches experimental results - most routing nodes do not aggressively rebalance their
416 * channels and flows in the network are often unbalanced, leaving liquidity usually
419 * Thus, for the \"best\" routes, leave this flag `false`. However, the flag does imply a number
420 * of floating-point multiplications in the hottest routing code, which may lead to routing
421 * performance degradation on some machines.
423 * Default value: false
425 public void set_linear_success_probability(boolean val) {
426 bindings.ProbabilisticScoringFeeParameters_set_linear_success_probability(this.ptr, val);
427 Reference.reachabilityFence(this);
428 Reference.reachabilityFence(val);
432 long ret = bindings.ProbabilisticScoringFeeParameters_clone_ptr(this.ptr);
433 Reference.reachabilityFence(this);
438 * Creates a copy of the ProbabilisticScoringFeeParameters
440 public ProbabilisticScoringFeeParameters clone() {
441 long ret = bindings.ProbabilisticScoringFeeParameters_clone(this.ptr);
442 Reference.reachabilityFence(this);
443 if (ret >= 0 && ret <= 4096) { return null; }
444 org.ldk.structs.ProbabilisticScoringFeeParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringFeeParameters(null, ret); }
445 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
450 * Creates a "default" ProbabilisticScoringFeeParameters. See struct and individual field documentaiton for details on which values are used.
452 public static ProbabilisticScoringFeeParameters with_default() {
453 long ret = bindings.ProbabilisticScoringFeeParameters_default();
454 if (ret >= 0 && ret <= 4096) { return null; }
455 org.ldk.structs.ProbabilisticScoringFeeParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringFeeParameters(null, ret); }
456 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); };
461 * Marks the node with the given `node_id` as banned,
462 * i.e it will be avoided during path finding.
464 public void add_banned(org.ldk.structs.NodeId node_id) {
465 bindings.ProbabilisticScoringFeeParameters_add_banned(this.ptr, node_id == null ? 0 : node_id.ptr);
466 Reference.reachabilityFence(this);
467 Reference.reachabilityFence(node_id);
468 if (this != null) { this.ptrs_to.add(node_id); };
472 * Marks all nodes in the given list as banned, i.e.,
473 * they will be avoided during path finding.
475 public void add_banned_from_list(NodeId[] node_ids) {
476 bindings.ProbabilisticScoringFeeParameters_add_banned_from_list(this.ptr, node_ids != null ? Arrays.stream(node_ids).mapToLong(node_ids_conv_8 -> node_ids_conv_8 == null ? 0 : node_ids_conv_8.ptr).toArray() : null);
477 Reference.reachabilityFence(this);
478 Reference.reachabilityFence(node_ids);
479 for (NodeId node_ids_conv_8: node_ids) { if (this != null) { this.ptrs_to.add(node_ids_conv_8); }; };
483 * Removes the node with the given `node_id` from the list of nodes to avoid.
485 public void remove_banned(org.ldk.structs.NodeId node_id) {
486 bindings.ProbabilisticScoringFeeParameters_remove_banned(this.ptr, node_id == null ? 0 : node_id.ptr);
487 Reference.reachabilityFence(this);
488 Reference.reachabilityFence(node_id);
489 if (this != null) { this.ptrs_to.add(node_id); };
493 * Sets a manual penalty for the given node.
495 public void set_manual_penalty(org.ldk.structs.NodeId node_id, long penalty) {
496 bindings.ProbabilisticScoringFeeParameters_set_manual_penalty(this.ptr, node_id == null ? 0 : node_id.ptr, penalty);
497 Reference.reachabilityFence(this);
498 Reference.reachabilityFence(node_id);
499 Reference.reachabilityFence(penalty);
500 if (this != null) { this.ptrs_to.add(node_id); };
504 * Removes the node with the given `node_id` from the list of manual penalties.
506 public void remove_manual_penalty(org.ldk.structs.NodeId node_id) {
507 bindings.ProbabilisticScoringFeeParameters_remove_manual_penalty(this.ptr, node_id == null ? 0 : node_id.ptr);
508 Reference.reachabilityFence(this);
509 Reference.reachabilityFence(node_id);
510 if (this != null) { this.ptrs_to.add(node_id); };
514 * Clears the list of manual penalties that are applied during path finding.
516 public void clear_manual_penalties() {
517 bindings.ProbabilisticScoringFeeParameters_clear_manual_penalties(this.ptr);
518 Reference.reachabilityFence(this);