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 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.ProbabilisticScoringFeeParameters_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.ProbabilisticScoringFeeParameters_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`]: ProbabilisticScoringDecayParameters::liquidity_offset_half_life
109 public long get_liquidity_penalty_multiplier_msat() {
110 long ret = bindings.ProbabilisticScoringFeeParameters_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`]: ProbabilisticScoringDecayParameters::liquidity_offset_half_life
133 public void set_liquidity_penalty_multiplier_msat(long val) {
134 bindings.ProbabilisticScoringFeeParameters_set_liquidity_penalty_multiplier_msat(this.ptr, val);
135 Reference.reachabilityFence(this);
136 Reference.reachabilityFence(val);
140 * A multiplier used in conjunction with a payment amount and the negative `log10` of the
141 * channel's success probability for the payment, as determined by our latest estimates of the
142 * channel's liquidity, to determine the amount penalty.
144 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
145 * fees plus penalty) for large payments. The penalty is computed as the product of this
146 * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the
147 * success probability.
149 * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
151 * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
152 * the amount will result in a penalty of the multiplier. And, as the success probability
153 * decreases, the negative `log10` weighting will increase dramatically. For higher success
154 * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
157 * Default value: 192 msat
159 public long get_liquidity_penalty_amount_multiplier_msat() {
160 long ret = bindings.ProbabilisticScoringFeeParameters_get_liquidity_penalty_amount_multiplier_msat(this.ptr);
161 Reference.reachabilityFence(this);
166 * A multiplier used in conjunction with a payment amount and the negative `log10` of the
167 * channel's success probability for the payment, as determined by our latest estimates of the
168 * channel's liquidity, to determine the amount penalty.
170 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
171 * fees plus penalty) for large payments. The penalty is computed as the product of this
172 * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the
173 * success probability.
175 * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
177 * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
178 * the amount will result in a penalty of the multiplier. And, as the success probability
179 * decreases, the negative `log10` weighting will increase dramatically. For higher success
180 * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
183 * Default value: 192 msat
185 public void set_liquidity_penalty_amount_multiplier_msat(long val) {
186 bindings.ProbabilisticScoringFeeParameters_set_liquidity_penalty_amount_multiplier_msat(this.ptr, val);
187 Reference.reachabilityFence(this);
188 Reference.reachabilityFence(val);
192 * A multiplier used in conjunction with the negative `log10` of the channel's success
193 * probability for the payment, as determined based on the history of our estimates of the
194 * channel's available liquidity, to determine a penalty.
196 * This penalty is similar to [`liquidity_penalty_multiplier_msat`], however, instead of using
197 * only our latest estimate for the current liquidity available in the channel, it estimates
198 * success probability based on the estimated liquidity available in the channel through
199 * history. Specifically, every time we update our liquidity bounds on a given channel, we
200 * track which of several buckets those bounds fall into, exponentially decaying the
201 * probability of each bucket as new samples are added.
203 * Default value: 10,000 msat
205 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
207 public long get_historical_liquidity_penalty_multiplier_msat() {
208 long ret = bindings.ProbabilisticScoringFeeParameters_get_historical_liquidity_penalty_multiplier_msat(this.ptr);
209 Reference.reachabilityFence(this);
214 * A multiplier used in conjunction with the negative `log10` of the channel's success
215 * probability for the payment, as determined based on the history of our estimates of the
216 * channel's available liquidity, to determine a penalty.
218 * This penalty is similar to [`liquidity_penalty_multiplier_msat`], however, instead of using
219 * only our latest estimate for the current liquidity available in the channel, it estimates
220 * success probability based on the estimated liquidity available in the channel through
221 * history. Specifically, every time we update our liquidity bounds on a given channel, we
222 * track which of several buckets those bounds fall into, exponentially decaying the
223 * probability of each bucket as new samples are added.
225 * Default value: 10,000 msat
227 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
229 public void set_historical_liquidity_penalty_multiplier_msat(long val) {
230 bindings.ProbabilisticScoringFeeParameters_set_historical_liquidity_penalty_multiplier_msat(this.ptr, val);
231 Reference.reachabilityFence(this);
232 Reference.reachabilityFence(val);
236 * A multiplier used in conjunction with the payment amount and the negative `log10` of the
237 * channel's success probability for the payment, as determined based on the history of our
238 * estimates of the channel's available liquidity, to determine a penalty.
240 * The purpose of the amount penalty is to avoid having fees dominate the channel cost for
241 * large payments. The penalty is computed as the product of this multiplier and the `2^20`ths
242 * of the payment amount, weighted by the negative `log10` of the success probability.
244 * This penalty is similar to [`liquidity_penalty_amount_multiplier_msat`], however, instead
245 * of using only our latest estimate for the current liquidity available in the channel, it
246 * estimates success probability based on the estimated liquidity available in the channel
247 * through history. Specifically, every time we update our liquidity bounds on a given
248 * channel, we track which of several buckets those bounds fall into, exponentially decaying
249 * the probability of each bucket as new samples are added.
251 * Default value: 64 msat
253 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
255 public long get_historical_liquidity_penalty_amount_multiplier_msat() {
256 long ret = bindings.ProbabilisticScoringFeeParameters_get_historical_liquidity_penalty_amount_multiplier_msat(this.ptr);
257 Reference.reachabilityFence(this);
262 * A multiplier used in conjunction with the payment amount and the negative `log10` of the
263 * channel's success probability for the payment, as determined based on the history of our
264 * estimates of the channel's available liquidity, to determine a penalty.
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 the `2^20`ths
268 * of the payment amount, weighted by the negative `log10` of the success probability.
270 * This penalty is similar to [`liquidity_penalty_amount_multiplier_msat`], however, instead
271 * of using only our latest estimate for the current liquidity available in the channel, it
272 * estimates success probability based on the estimated liquidity available in the channel
273 * through history. Specifically, every time we update our liquidity bounds on a given
274 * channel, we track which of several buckets those bounds fall into, exponentially decaying
275 * the probability of each bucket as new samples are added.
277 * Default value: 64 msat
279 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
281 public void set_historical_liquidity_penalty_amount_multiplier_msat(long val) {
282 bindings.ProbabilisticScoringFeeParameters_set_historical_liquidity_penalty_amount_multiplier_msat(this.ptr, val);
283 Reference.reachabilityFence(this);
284 Reference.reachabilityFence(val);
288 * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
289 * channel's capacity, (ie. htlc_maximum_msat >= 0.5 * channel_capacity) which makes us
290 * prefer nodes with a smaller `htlc_maximum_msat`. We treat such nodes preferentially
291 * as this makes balance discovery attacks harder to execute, thereby creating an incentive
292 * to restrict `htlc_maximum_msat` and improve privacy.
294 * Default value: 250 msat
296 public long get_anti_probing_penalty_msat() {
297 long ret = bindings.ProbabilisticScoringFeeParameters_get_anti_probing_penalty_msat(this.ptr);
298 Reference.reachabilityFence(this);
303 * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
304 * channel's capacity, (ie. htlc_maximum_msat >= 0.5 * channel_capacity) which makes us
305 * prefer nodes with a smaller `htlc_maximum_msat`. We treat such nodes preferentially
306 * as this makes balance discovery attacks harder to execute, thereby creating an incentive
307 * to restrict `htlc_maximum_msat` and improve privacy.
309 * Default value: 250 msat
311 public void set_anti_probing_penalty_msat(long val) {
312 bindings.ProbabilisticScoringFeeParameters_set_anti_probing_penalty_msat(this.ptr, val);
313 Reference.reachabilityFence(this);
314 Reference.reachabilityFence(val);
318 * This penalty is applied when the amount we're attempting to send over a channel exceeds our
319 * current estimate of the channel's available liquidity.
321 * Note that in this case all other penalties, including the
322 * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based
323 * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if
324 * applicable, are still included in the overall penalty.
326 * If you wish to avoid creating paths with such channels entirely, setting this to a value of
327 * `u64::max_value()` will guarantee that.
329 * Default value: 1_0000_0000_000 msat (1 Bitcoin)
331 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
332 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
333 * [`base_penalty_msat`]: Self::base_penalty_msat
334 * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat
336 public long get_considered_impossible_penalty_msat() {
337 long ret = bindings.ProbabilisticScoringFeeParameters_get_considered_impossible_penalty_msat(this.ptr);
338 Reference.reachabilityFence(this);
343 * This penalty is applied when the amount we're attempting to send over a channel exceeds our
344 * current estimate of the channel's available liquidity.
346 * Note that in this case all other penalties, including the
347 * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based
348 * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if
349 * applicable, are still included in the overall penalty.
351 * If you wish to avoid creating paths with such channels entirely, setting this to a value of
352 * `u64::max_value()` will guarantee that.
354 * Default value: 1_0000_0000_000 msat (1 Bitcoin)
356 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
357 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
358 * [`base_penalty_msat`]: Self::base_penalty_msat
359 * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat
361 public void set_considered_impossible_penalty_msat(long val) {
362 bindings.ProbabilisticScoringFeeParameters_set_considered_impossible_penalty_msat(this.ptr, val);
363 Reference.reachabilityFence(this);
364 Reference.reachabilityFence(val);
368 long ret = bindings.ProbabilisticScoringFeeParameters_clone_ptr(this.ptr);
369 Reference.reachabilityFence(this);
374 * Creates a copy of the ProbabilisticScoringFeeParameters
376 public ProbabilisticScoringFeeParameters clone() {
377 long ret = bindings.ProbabilisticScoringFeeParameters_clone(this.ptr);
378 Reference.reachabilityFence(this);
379 if (ret >= 0 && ret <= 4096) { return null; }
380 org.ldk.structs.ProbabilisticScoringFeeParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringFeeParameters(null, ret); }
381 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
386 * Creates a "default" ProbabilisticScoringFeeParameters. See struct and individual field documentaiton for details on which values are used.
388 public static ProbabilisticScoringFeeParameters with_default() {
389 long ret = bindings.ProbabilisticScoringFeeParameters_default();
390 if (ret >= 0 && ret <= 4096) { return null; }
391 org.ldk.structs.ProbabilisticScoringFeeParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringFeeParameters(null, ret); }
392 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); };
397 * Marks the node with the given `node_id` as banned,
398 * i.e it will be avoided during path finding.
400 public void add_banned(org.ldk.structs.NodeId node_id) {
401 bindings.ProbabilisticScoringFeeParameters_add_banned(this.ptr, node_id == null ? 0 : node_id.ptr);
402 Reference.reachabilityFence(this);
403 Reference.reachabilityFence(node_id);
404 if (this != null) { this.ptrs_to.add(node_id); };
408 * Marks all nodes in the given list as banned, i.e.,
409 * they will be avoided during path finding.
411 public void add_banned_from_list(NodeId[] node_ids) {
412 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);
413 Reference.reachabilityFence(this);
414 Reference.reachabilityFence(node_ids);
415 for (NodeId node_ids_conv_8: node_ids) { if (this != null) { this.ptrs_to.add(node_ids_conv_8); }; };
419 * Removes the node with the given `node_id` from the list of nodes to avoid.
421 public void remove_banned(org.ldk.structs.NodeId node_id) {
422 bindings.ProbabilisticScoringFeeParameters_remove_banned(this.ptr, node_id == null ? 0 : node_id.ptr);
423 Reference.reachabilityFence(this);
424 Reference.reachabilityFence(node_id);
425 if (this != null) { this.ptrs_to.add(node_id); };
429 * Sets a manual penalty for the given node.
431 public void set_manual_penalty(org.ldk.structs.NodeId node_id, long penalty) {
432 bindings.ProbabilisticScoringFeeParameters_set_manual_penalty(this.ptr, node_id == null ? 0 : node_id.ptr, penalty);
433 Reference.reachabilityFence(this);
434 Reference.reachabilityFence(node_id);
435 Reference.reachabilityFence(penalty);
436 if (this != null) { this.ptrs_to.add(node_id); };
440 * Removes the node with the given `node_id` from the list of manual penalties.
442 public void remove_manual_penalty(org.ldk.structs.NodeId node_id) {
443 bindings.ProbabilisticScoringFeeParameters_remove_manual_penalty(this.ptr, node_id == null ? 0 : node_id.ptr);
444 Reference.reachabilityFence(this);
445 Reference.reachabilityFence(node_id);
446 if (this != null) { this.ptrs_to.add(node_id); };
450 * Clears the list of manual penalties that are applied during path finding.
452 public void clear_manual_penalties() {
453 bindings.ProbabilisticScoringFeeParameters_clear_manual_penalties(this.ptr);
454 Reference.reachabilityFence(this);