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 to determine the liquidity penalty.
95 * The penalty is based in part on the knowledge learned from prior successful and unsuccessful
96 * payments. This knowledge is decayed over time based on [`liquidity_offset_half_life`]. The
97 * penalty is effectively limited to `2 * liquidity_penalty_multiplier_msat` (corresponding to
98 * lower bounding the success probability to `0.01`) when the amount falls within the
99 * uncertainty bounds of the channel liquidity balance. Amounts above the upper bound will
100 * result in a `u64::max_value` penalty, however.
102 * Default value: 40,000 msat
104 * [`liquidity_offset_half_life`]: Self::liquidity_offset_half_life
106 public long get_liquidity_penalty_multiplier_msat() {
107 long ret = bindings.ProbabilisticScoringParameters_get_liquidity_penalty_multiplier_msat(this.ptr);
108 Reference.reachabilityFence(this);
113 * A multiplier used in conjunction with the negative `log10` of the channel's success
114 * probability for a payment to determine the liquidity penalty.
116 * The penalty is based in part on the knowledge learned from prior successful and unsuccessful
117 * payments. This knowledge is decayed over time based on [`liquidity_offset_half_life`]. The
118 * penalty is effectively limited to `2 * liquidity_penalty_multiplier_msat` (corresponding to
119 * lower bounding the success probability to `0.01`) when the amount falls within the
120 * uncertainty bounds of the channel liquidity balance. Amounts above the upper bound will
121 * result in a `u64::max_value` penalty, however.
123 * Default value: 40,000 msat
125 * [`liquidity_offset_half_life`]: Self::liquidity_offset_half_life
127 public void set_liquidity_penalty_multiplier_msat(long val) {
128 bindings.ProbabilisticScoringParameters_set_liquidity_penalty_multiplier_msat(this.ptr, val);
129 Reference.reachabilityFence(this);
130 Reference.reachabilityFence(val);
134 * The time required to elapse before any knowledge learned about channel liquidity balances is
137 * The bounds are defined in terms of offsets and are initially zero. Increasing the offsets
138 * gives tighter bounds on the channel liquidity balance. Thus, halving the offsets decreases
139 * the certainty of the channel liquidity balance.
141 * Default value: 1 hour
145 * When built with the `no-std` feature, time will never elapse. Therefore, the channel
146 * liquidity knowledge will never decay except when the bounds cross.
148 public long get_liquidity_offset_half_life() {
149 long ret = bindings.ProbabilisticScoringParameters_get_liquidity_offset_half_life(this.ptr);
150 Reference.reachabilityFence(this);
155 * The time required to elapse before any knowledge learned about channel liquidity balances is
158 * The bounds are defined in terms of offsets and are initially zero. Increasing the offsets
159 * gives tighter bounds on the channel liquidity balance. Thus, halving the offsets decreases
160 * the certainty of the channel liquidity balance.
162 * Default value: 1 hour
166 * When built with the `no-std` feature, time will never elapse. Therefore, the channel
167 * liquidity knowledge will never decay except when the bounds cross.
169 public void set_liquidity_offset_half_life(long val) {
170 bindings.ProbabilisticScoringParameters_set_liquidity_offset_half_life(this.ptr, val);
171 Reference.reachabilityFence(this);
172 Reference.reachabilityFence(val);
176 * A multiplier used in conjunction with a payment amount and the negative `log10` of the
177 * channel's success probability for the payment to determine the amount penalty.
179 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
180 * fees plus penalty) for large payments. The penalty is computed as the product of this
181 * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the
182 * success probability.
184 * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
186 * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
187 * the amount will result in a penalty of the multiplier. And, as the success probability
188 * decreases, the negative `log10` weighting will increase dramatically. For higher success
189 * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
192 * Default value: 256 msat
194 public long get_liquidity_penalty_amount_multiplier_msat() {
195 long ret = bindings.ProbabilisticScoringParameters_get_liquidity_penalty_amount_multiplier_msat(this.ptr);
196 Reference.reachabilityFence(this);
201 * A multiplier used in conjunction with a payment amount and the negative `log10` of the
202 * channel's success probability for the payment to determine the amount penalty.
204 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
205 * fees plus penalty) for large payments. The penalty is computed as the product of this
206 * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the
207 * success probability.
209 * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
211 * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
212 * the amount will result in a penalty of the multiplier. And, as the success probability
213 * decreases, the negative `log10` weighting will increase dramatically. For higher success
214 * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
217 * Default value: 256 msat
219 public void set_liquidity_penalty_amount_multiplier_msat(long val) {
220 bindings.ProbabilisticScoringParameters_set_liquidity_penalty_amount_multiplier_msat(this.ptr, val);
221 Reference.reachabilityFence(this);
222 Reference.reachabilityFence(val);
226 * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
227 * channel's capacity, which makes us prefer nodes with a smaller `htlc_maximum_msat`. We
228 * treat such nodes preferentially as this makes balance discovery attacks harder to execute,
229 * thereby creating an incentive to restrict `htlc_maximum_msat` and improve privacy.
231 * Default value: 250 msat
233 public long get_anti_probing_penalty_msat() {
234 long ret = bindings.ProbabilisticScoringParameters_get_anti_probing_penalty_msat(this.ptr);
235 Reference.reachabilityFence(this);
240 * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
241 * channel's capacity, which makes us prefer nodes with a smaller `htlc_maximum_msat`. We
242 * treat such nodes preferentially as this makes balance discovery attacks harder to execute,
243 * thereby creating an incentive to restrict `htlc_maximum_msat` and improve privacy.
245 * Default value: 250 msat
247 public void set_anti_probing_penalty_msat(long val) {
248 bindings.ProbabilisticScoringParameters_set_anti_probing_penalty_msat(this.ptr, val);
249 Reference.reachabilityFence(this);
250 Reference.reachabilityFence(val);
254 * This penalty is applied when the amount we're attempting to send over a channel exceeds our
255 * current estimate of the channel's available liquidity.
257 * Note that in this case all other penalties, including the
258 * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based
259 * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if
260 * applicable, are still included in the overall penalty.
262 * If you wish to avoid creating paths with such channels entirely, setting this to a value of
263 * `u64::max_value()` will guarantee that.
265 * Default value: 1_0000_0000_000 msat (1 Bitcoin)
267 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
268 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
269 * [`base_penalty_msat`]: Self::base_penalty_msat
270 * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat
272 public long get_considered_impossible_penalty_msat() {
273 long ret = bindings.ProbabilisticScoringParameters_get_considered_impossible_penalty_msat(this.ptr);
274 Reference.reachabilityFence(this);
279 * This penalty is applied when the amount we're attempting to send over a channel exceeds our
280 * current estimate of the channel's available liquidity.
282 * Note that in this case all other penalties, including the
283 * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based
284 * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if
285 * applicable, are still included in the overall penalty.
287 * If you wish to avoid creating paths with such channels entirely, setting this to a value of
288 * `u64::max_value()` will guarantee that.
290 * Default value: 1_0000_0000_000 msat (1 Bitcoin)
292 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
293 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
294 * [`base_penalty_msat`]: Self::base_penalty_msat
295 * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat
297 public void set_considered_impossible_penalty_msat(long val) {
298 bindings.ProbabilisticScoringParameters_set_considered_impossible_penalty_msat(this.ptr, val);
299 Reference.reachabilityFence(this);
300 Reference.reachabilityFence(val);
304 long ret = bindings.ProbabilisticScoringParameters_clone_ptr(this.ptr);
305 Reference.reachabilityFence(this);
310 * Creates a copy of the ProbabilisticScoringParameters
312 public ProbabilisticScoringParameters clone() {
313 long ret = bindings.ProbabilisticScoringParameters_clone(this.ptr);
314 Reference.reachabilityFence(this);
315 if (ret >= 0 && ret <= 4096) { return null; }
316 org.ldk.structs.ProbabilisticScoringParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringParameters(null, ret); }
317 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
322 * Marks all nodes in the given list as banned, i.e.,
323 * they will be avoided during path finding.
325 public void add_banned_from_list(NodeId[] node_ids) {
326 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);
327 Reference.reachabilityFence(this);
328 Reference.reachabilityFence(node_ids);
329 for (NodeId node_ids_conv_8: node_ids) { if (this != null) { this.ptrs_to.add(node_ids_conv_8); }; };
333 * Creates a "default" ProbabilisticScoringParameters. See struct and individual field documentaiton for details on which values are used.
335 public static ProbabilisticScoringParameters with_default() {
336 long ret = bindings.ProbabilisticScoringParameters_default();
337 if (ret >= 0 && ret <= 4096) { return null; }
338 org.ldk.structs.ProbabilisticScoringParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringParameters(null, ret); }
339 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); };