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 ProbabilisticScoringParameters extends CommonBase {
22 ProbabilisticScoringParameters(Object _dummy, long ptr) { super(ptr); }
23 @Override @SuppressWarnings("deprecation")
24 protected void finalize() throws Throwable {
26 if (ptr != 0) { bindings.ProbabilisticScoringParameters_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.ProbabilisticScoringParameters_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.ProbabilisticScoringParameters_set_base_penalty_msat(this.ptr, val);
47 Reference.reachabilityFence(this);
48 Reference.reachabilityFence(val);
52 * A multiplier used with the payment amount to calculate a fixed penalty applied to each
53 * 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 payment amount.
59 * ie `base_penalty_amount_multiplier_msat * amount_msat / 2^30`
61 * Default value: 8,192 msat
63 * [`base_penalty_msat`]: Self::base_penalty_msat
65 public long get_base_penalty_amount_multiplier_msat() {
66 long ret = bindings.ProbabilisticScoringParameters_get_base_penalty_amount_multiplier_msat(this.ptr);
67 Reference.reachabilityFence(this);
72 * A multiplier used with the payment amount to calculate a fixed penalty applied to each
73 * channel, in excess of the [`base_penalty_msat`].
75 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
76 * fees plus penalty) for large payments. The penalty is computed as the product of this
77 * multiplier and `2^30`ths of the payment amount.
79 * ie `base_penalty_amount_multiplier_msat * amount_msat / 2^30`
81 * Default value: 8,192 msat
83 * [`base_penalty_msat`]: Self::base_penalty_msat
85 public void set_base_penalty_amount_multiplier_msat(long val) {
86 bindings.ProbabilisticScoringParameters_set_base_penalty_amount_multiplier_msat(this.ptr, val);
87 Reference.reachabilityFence(this);
88 Reference.reachabilityFence(val);
92 * A multiplier used in conjunction with the negative `log10` of the channel's success
93 * probability for a payment, as determined by our latest estimates of the channel's
94 * liquidity, to determine the liquidity penalty.
96 * The penalty is based in part on the knowledge learned from prior successful and unsuccessful
97 * payments. This knowledge is decayed over time based on [`liquidity_offset_half_life`]. The
98 * penalty is effectively limited to `2 * liquidity_penalty_multiplier_msat` (corresponding to
99 * lower bounding the success probability to `0.01`) when the amount falls within the
100 * uncertainty bounds of the channel liquidity balance. Amounts above the upper bound will
101 * result in a `u64::max_value` penalty, however.
103 * `-log10(success_probability) * liquidity_penalty_multiplier_msat`
105 * Default value: 30,000 msat
107 * [`liquidity_offset_half_life`]: Self::liquidity_offset_half_life
109 public long get_liquidity_penalty_multiplier_msat() {
110 long ret = bindings.ProbabilisticScoringParameters_get_liquidity_penalty_multiplier_msat(this.ptr);
111 Reference.reachabilityFence(this);
116 * A multiplier used in conjunction with the negative `log10` of the channel's success
117 * probability for a payment, as determined by our latest estimates of the channel's
118 * liquidity, to determine the liquidity penalty.
120 * The penalty is based in part on the knowledge learned from prior successful and unsuccessful
121 * payments. This knowledge is decayed over time based on [`liquidity_offset_half_life`]. The
122 * penalty is effectively limited to `2 * liquidity_penalty_multiplier_msat` (corresponding to
123 * lower bounding the success probability to `0.01`) when the amount falls within the
124 * uncertainty bounds of the channel liquidity balance. Amounts above the upper bound will
125 * result in a `u64::max_value` penalty, however.
127 * `-log10(success_probability) * liquidity_penalty_multiplier_msat`
129 * Default value: 30,000 msat
131 * [`liquidity_offset_half_life`]: Self::liquidity_offset_half_life
133 public void set_liquidity_penalty_multiplier_msat(long val) {
134 bindings.ProbabilisticScoringParameters_set_liquidity_penalty_multiplier_msat(this.ptr, val);
135 Reference.reachabilityFence(this);
136 Reference.reachabilityFence(val);
140 * Whenever this amount of time elapses since the last update to a channel's liquidity bounds,
141 * the distance from the bounds to \"zero\" is cut in half. In other words, the lower-bound on
142 * the available liquidity is halved and the upper-bound moves half-way to the channel's total
145 * Because halving the liquidity bounds grows the uncertainty on the channel's liquidity,
146 * the penalty for an amount within the new bounds may change. See the [`ProbabilisticScorer`]
147 * struct documentation for more info on the way the liquidity bounds are used.
149 * For example, if the channel's capacity is 1 million sats, and the current upper and lower
150 * liquidity bounds are 200,000 sats and 600,000 sats, after this amount of time the upper
151 * and lower liquidity bounds will be decayed to 100,000 and 800,000 sats.
153 * Default value: 6 hours
157 * When built with the `no-std` feature, time will never elapse. Therefore, the channel
158 * liquidity knowledge will never decay except when the bounds cross.
160 public long get_liquidity_offset_half_life() {
161 long ret = bindings.ProbabilisticScoringParameters_get_liquidity_offset_half_life(this.ptr);
162 Reference.reachabilityFence(this);
167 * Whenever this amount of time elapses since the last update to a channel's liquidity bounds,
168 * the distance from the bounds to \"zero\" is cut in half. In other words, the lower-bound on
169 * the available liquidity is halved and the upper-bound moves half-way to the channel's total
172 * Because halving the liquidity bounds grows the uncertainty on the channel's liquidity,
173 * the penalty for an amount within the new bounds may change. See the [`ProbabilisticScorer`]
174 * struct documentation for more info on the way the liquidity bounds are used.
176 * For example, if the channel's capacity is 1 million sats, and the current upper and lower
177 * liquidity bounds are 200,000 sats and 600,000 sats, after this amount of time the upper
178 * and lower liquidity bounds will be decayed to 100,000 and 800,000 sats.
180 * Default value: 6 hours
184 * When built with the `no-std` feature, time will never elapse. Therefore, the channel
185 * liquidity knowledge will never decay except when the bounds cross.
187 public void set_liquidity_offset_half_life(long val) {
188 bindings.ProbabilisticScoringParameters_set_liquidity_offset_half_life(this.ptr, val);
189 Reference.reachabilityFence(this);
190 Reference.reachabilityFence(val);
194 * A multiplier used in conjunction with a payment amount and the negative `log10` of the
195 * channel's success probability for the payment, as determined by our latest estimates of the
196 * channel's liquidity, to determine the amount penalty.
198 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
199 * fees plus penalty) for large payments. The penalty is computed as the product of this
200 * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the
201 * success probability.
203 * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
205 * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
206 * the amount will result in a penalty of the multiplier. And, as the success probability
207 * decreases, the negative `log10` weighting will increase dramatically. For higher success
208 * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
211 * Default value: 192 msat
213 public long get_liquidity_penalty_amount_multiplier_msat() {
214 long ret = bindings.ProbabilisticScoringParameters_get_liquidity_penalty_amount_multiplier_msat(this.ptr);
215 Reference.reachabilityFence(this);
220 * A multiplier used in conjunction with a payment amount and the negative `log10` of the
221 * channel's success probability for the payment, as determined by our latest estimates of the
222 * channel's liquidity, to determine the amount penalty.
224 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
225 * fees plus penalty) for large payments. The penalty is computed as the product of this
226 * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the
227 * success probability.
229 * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
231 * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
232 * the amount will result in a penalty of the multiplier. And, as the success probability
233 * decreases, the negative `log10` weighting will increase dramatically. For higher success
234 * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
237 * Default value: 192 msat
239 public void set_liquidity_penalty_amount_multiplier_msat(long val) {
240 bindings.ProbabilisticScoringParameters_set_liquidity_penalty_amount_multiplier_msat(this.ptr, val);
241 Reference.reachabilityFence(this);
242 Reference.reachabilityFence(val);
246 * A multiplier used in conjunction with the negative `log10` of the channel's success
247 * probability for the payment, as determined based on the history of our estimates of the
248 * channel's available liquidity, to determine a penalty.
250 * This penalty is similar to [`liquidity_penalty_multiplier_msat`], however, instead of using
251 * only our latest estimate for the current liquidity available in the channel, it estimates
252 * success probability based on the estimated liquidity available in the channel through
253 * history. Specifically, every time we update our liquidity bounds on a given channel, we
254 * track which of several buckets those bounds fall into, exponentially decaying the
255 * probability of each bucket as new samples are added.
257 * Default value: 10,000 msat
259 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
261 public long get_historical_liquidity_penalty_multiplier_msat() {
262 long ret = bindings.ProbabilisticScoringParameters_get_historical_liquidity_penalty_multiplier_msat(this.ptr);
263 Reference.reachabilityFence(this);
268 * A multiplier used in conjunction with the negative `log10` of the channel's success
269 * probability for the payment, as determined based on the history of our estimates of the
270 * channel's available liquidity, to determine a penalty.
272 * This penalty is similar to [`liquidity_penalty_multiplier_msat`], however, instead of using
273 * only our latest estimate for the current liquidity available in the channel, it estimates
274 * success probability based on the estimated liquidity available in the channel through
275 * history. Specifically, every time we update our liquidity bounds on a given channel, we
276 * track which of several buckets those bounds fall into, exponentially decaying the
277 * probability of each bucket as new samples are added.
279 * Default value: 10,000 msat
281 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
283 public void set_historical_liquidity_penalty_multiplier_msat(long val) {
284 bindings.ProbabilisticScoringParameters_set_historical_liquidity_penalty_multiplier_msat(this.ptr, val);
285 Reference.reachabilityFence(this);
286 Reference.reachabilityFence(val);
290 * A multiplier used in conjunction with the payment amount and the negative `log10` of the
291 * channel's success probability for the payment, as determined based on the history of our
292 * estimates of the channel's available liquidity, to determine a penalty.
294 * The purpose of the amount penalty is to avoid having fees dominate the channel cost for
295 * large payments. The penalty is computed as the product of this multiplier and the `2^20`ths
296 * of the payment amount, weighted by the negative `log10` of the success probability.
298 * This penalty is similar to [`liquidity_penalty_amount_multiplier_msat`], however, instead
299 * of using only our latest estimate for the current liquidity available in the channel, it
300 * estimates success probability based on the estimated liquidity available in the channel
301 * through history. Specifically, every time we update our liquidity bounds on a given
302 * channel, we track which of several buckets those bounds fall into, exponentially decaying
303 * the probability of each bucket as new samples are added.
305 * Default value: 64 msat
307 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
309 public long get_historical_liquidity_penalty_amount_multiplier_msat() {
310 long ret = bindings.ProbabilisticScoringParameters_get_historical_liquidity_penalty_amount_multiplier_msat(this.ptr);
311 Reference.reachabilityFence(this);
316 * A multiplier used in conjunction with the payment amount and the negative `log10` of the
317 * channel's success probability for the payment, as determined based on the history of our
318 * estimates of the channel's available liquidity, to determine a penalty.
320 * The purpose of the amount penalty is to avoid having fees dominate the channel cost for
321 * large payments. The penalty is computed as the product of this multiplier and the `2^20`ths
322 * of the payment amount, weighted by the negative `log10` of the success probability.
324 * This penalty is similar to [`liquidity_penalty_amount_multiplier_msat`], however, instead
325 * of using only our latest estimate for the current liquidity available in the channel, it
326 * estimates success probability based on the estimated liquidity available in the channel
327 * through history. Specifically, every time we update our liquidity bounds on a given
328 * channel, we track which of several buckets those bounds fall into, exponentially decaying
329 * the probability of each bucket as new samples are added.
331 * Default value: 64 msat
333 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
335 public void set_historical_liquidity_penalty_amount_multiplier_msat(long val) {
336 bindings.ProbabilisticScoringParameters_set_historical_liquidity_penalty_amount_multiplier_msat(this.ptr, val);
337 Reference.reachabilityFence(this);
338 Reference.reachabilityFence(val);
342 * If we aren't learning any new datapoints for a channel, the historical liquidity bounds
343 * tracking can simply live on with increasingly stale data. Instead, when a channel has not
344 * seen a liquidity estimate update for this amount of time, the historical datapoints are
347 * Note that after 16 or more half lives all historical data will be completely gone.
349 * Default value: 14 days
351 public long get_historical_no_updates_half_life() {
352 long ret = bindings.ProbabilisticScoringParameters_get_historical_no_updates_half_life(this.ptr);
353 Reference.reachabilityFence(this);
358 * If we aren't learning any new datapoints for a channel, the historical liquidity bounds
359 * tracking can simply live on with increasingly stale data. Instead, when a channel has not
360 * seen a liquidity estimate update for this amount of time, the historical datapoints are
363 * Note that after 16 or more half lives all historical data will be completely gone.
365 * Default value: 14 days
367 public void set_historical_no_updates_half_life(long val) {
368 bindings.ProbabilisticScoringParameters_set_historical_no_updates_half_life(this.ptr, val);
369 Reference.reachabilityFence(this);
370 Reference.reachabilityFence(val);
374 * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
375 * channel's capacity, which makes us prefer nodes with a smaller `htlc_maximum_msat`. We
376 * treat such nodes preferentially as this makes balance discovery attacks harder to execute,
377 * thereby creating an incentive to restrict `htlc_maximum_msat` and improve privacy.
379 * Default value: 250 msat
381 public long get_anti_probing_penalty_msat() {
382 long ret = bindings.ProbabilisticScoringParameters_get_anti_probing_penalty_msat(this.ptr);
383 Reference.reachabilityFence(this);
388 * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
389 * channel's capacity, which makes us prefer nodes with a smaller `htlc_maximum_msat`. We
390 * treat such nodes preferentially as this makes balance discovery attacks harder to execute,
391 * thereby creating an incentive to restrict `htlc_maximum_msat` and improve privacy.
393 * Default value: 250 msat
395 public void set_anti_probing_penalty_msat(long val) {
396 bindings.ProbabilisticScoringParameters_set_anti_probing_penalty_msat(this.ptr, val);
397 Reference.reachabilityFence(this);
398 Reference.reachabilityFence(val);
402 * This penalty is applied when the amount we're attempting to send over a channel exceeds our
403 * current estimate of the channel's available liquidity.
405 * Note that in this case all other penalties, including the
406 * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based
407 * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if
408 * applicable, are still included in the overall penalty.
410 * If you wish to avoid creating paths with such channels entirely, setting this to a value of
411 * `u64::max_value()` will guarantee that.
413 * Default value: 1_0000_0000_000 msat (1 Bitcoin)
415 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
416 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
417 * [`base_penalty_msat`]: Self::base_penalty_msat
418 * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat
420 public long get_considered_impossible_penalty_msat() {
421 long ret = bindings.ProbabilisticScoringParameters_get_considered_impossible_penalty_msat(this.ptr);
422 Reference.reachabilityFence(this);
427 * This penalty is applied when the amount we're attempting to send over a channel exceeds our
428 * current estimate of the channel's available liquidity.
430 * Note that in this case all other penalties, including the
431 * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based
432 * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if
433 * applicable, are still included in the overall penalty.
435 * If you wish to avoid creating paths with such channels entirely, setting this to a value of
436 * `u64::max_value()` will guarantee that.
438 * Default value: 1_0000_0000_000 msat (1 Bitcoin)
440 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
441 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
442 * [`base_penalty_msat`]: Self::base_penalty_msat
443 * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat
445 public void set_considered_impossible_penalty_msat(long val) {
446 bindings.ProbabilisticScoringParameters_set_considered_impossible_penalty_msat(this.ptr, val);
447 Reference.reachabilityFence(this);
448 Reference.reachabilityFence(val);
452 long ret = bindings.ProbabilisticScoringParameters_clone_ptr(this.ptr);
453 Reference.reachabilityFence(this);
458 * Creates a copy of the ProbabilisticScoringParameters
460 public ProbabilisticScoringParameters clone() {
461 long ret = bindings.ProbabilisticScoringParameters_clone(this.ptr);
462 Reference.reachabilityFence(this);
463 if (ret >= 0 && ret <= 4096) { return null; }
464 org.ldk.structs.ProbabilisticScoringParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringParameters(null, ret); }
465 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
470 * Marks all nodes in the given list as banned, i.e.,
471 * they will be avoided during path finding.
473 public void add_banned_from_list(NodeId[] node_ids) {
474 bindings.ProbabilisticScoringParameters_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);
475 Reference.reachabilityFence(this);
476 Reference.reachabilityFence(node_ids);
477 for (NodeId node_ids_conv_8: node_ids) { if (this != null) { this.ptrs_to.add(node_ids_conv_8); }; };
481 * Creates a "default" ProbabilisticScoringParameters. See struct and individual field documentaiton for details on which values are used.
483 public static ProbabilisticScoringParameters with_default() {
484 long ret = bindings.ProbabilisticScoringParameters_default();
485 if (ret >= 0 && ret <= 4096) { return null; }
486 org.ldk.structs.ProbabilisticScoringParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringParameters(null, ret); }
487 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); };