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 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
18 public class ProbabilisticScoringParameters extends CommonBase {
19 ProbabilisticScoringParameters(Object _dummy, long ptr) { super(ptr); }
20 @Override @SuppressWarnings("deprecation")
21 protected void finalize() throws Throwable {
23 if (ptr != 0) { bindings.ProbabilisticScoringParameters_free(ptr); }
27 * A fixed penalty in msats to apply to each channel.
29 * Default value: 500 msat
31 public long get_base_penalty_msat() {
32 long ret = bindings.ProbabilisticScoringParameters_get_base_penalty_msat(this.ptr);
33 Reference.reachabilityFence(this);
38 * A fixed penalty in msats to apply to each channel.
40 * Default value: 500 msat
42 public void set_base_penalty_msat(long val) {
43 bindings.ProbabilisticScoringParameters_set_base_penalty_msat(this.ptr, val);
44 Reference.reachabilityFence(this);
45 Reference.reachabilityFence(val);
49 * A multiplier used in conjunction with the negative `log10` of the channel's success
50 * probability for a payment to determine the liquidity penalty.
52 * The penalty is based in part on the knowledge learned from prior successful and unsuccessful
53 * payments. This knowledge is decayed over time based on [`liquidity_offset_half_life`]. The
54 * penalty is effectively limited to `2 * liquidity_penalty_multiplier_msat` (corresponding to
55 * lower bounding the success probability to `0.01`) when the amount falls within the
56 * uncertainty bounds of the channel liquidity balance. Amounts above the upper bound will
57 * result in a `u64::max_value` penalty, however.
59 * Default value: 40,000 msat
61 * [`liquidity_offset_half_life`]: Self::liquidity_offset_half_life
63 public long get_liquidity_penalty_multiplier_msat() {
64 long ret = bindings.ProbabilisticScoringParameters_get_liquidity_penalty_multiplier_msat(this.ptr);
65 Reference.reachabilityFence(this);
70 * A multiplier used in conjunction with the negative `log10` of the channel's success
71 * probability for a payment to determine the liquidity penalty.
73 * The penalty is based in part on the knowledge learned from prior successful and unsuccessful
74 * payments. This knowledge is decayed over time based on [`liquidity_offset_half_life`]. The
75 * penalty is effectively limited to `2 * liquidity_penalty_multiplier_msat` (corresponding to
76 * lower bounding the success probability to `0.01`) when the amount falls within the
77 * uncertainty bounds of the channel liquidity balance. Amounts above the upper bound will
78 * result in a `u64::max_value` penalty, however.
80 * Default value: 40,000 msat
82 * [`liquidity_offset_half_life`]: Self::liquidity_offset_half_life
84 public void set_liquidity_penalty_multiplier_msat(long val) {
85 bindings.ProbabilisticScoringParameters_set_liquidity_penalty_multiplier_msat(this.ptr, val);
86 Reference.reachabilityFence(this);
87 Reference.reachabilityFence(val);
91 * The time required to elapse before any knowledge learned about channel liquidity balances is
94 * The bounds are defined in terms of offsets and are initially zero. Increasing the offsets
95 * gives tighter bounds on the channel liquidity balance. Thus, halving the offsets decreases
96 * the certainty of the channel liquidity balance.
98 * Default value: 1 hour
102 * When built with the `no-std` feature, time will never elapse. Therefore, the channel
103 * liquidity knowledge will never decay except when the bounds cross.
105 public long get_liquidity_offset_half_life() {
106 long ret = bindings.ProbabilisticScoringParameters_get_liquidity_offset_half_life(this.ptr);
107 Reference.reachabilityFence(this);
112 * The time required to elapse before any knowledge learned about channel liquidity balances is
115 * The bounds are defined in terms of offsets and are initially zero. Increasing the offsets
116 * gives tighter bounds on the channel liquidity balance. Thus, halving the offsets decreases
117 * the certainty of the channel liquidity balance.
119 * Default value: 1 hour
123 * When built with the `no-std` feature, time will never elapse. Therefore, the channel
124 * liquidity knowledge will never decay except when the bounds cross.
126 public void set_liquidity_offset_half_life(long val) {
127 bindings.ProbabilisticScoringParameters_set_liquidity_offset_half_life(this.ptr, val);
128 Reference.reachabilityFence(this);
129 Reference.reachabilityFence(val);
133 * A multiplier used in conjunction with a payment amount and the negative `log10` of the
134 * channel's success probability for the payment to determine the amount penalty.
136 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
137 * fees plus penalty) for large payments. The penalty is computed as the product of this
138 * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the
139 * success probability.
141 * `-log10(success_probability) * amount_penalty_multiplier_msat * amount_msat / 2^20`
143 * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
144 * the amount will result in a penalty of the multiplier. And, as the success probability
145 * decreases, the negative `log10` weighting will increase dramatically. For higher success
146 * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
149 * Default value: 256 msat
151 public long get_amount_penalty_multiplier_msat() {
152 long ret = bindings.ProbabilisticScoringParameters_get_amount_penalty_multiplier_msat(this.ptr);
153 Reference.reachabilityFence(this);
158 * A multiplier used in conjunction with a payment amount and the negative `log10` of the
159 * channel's success probability for the payment to determine the amount penalty.
161 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
162 * fees plus penalty) for large payments. The penalty is computed as the product of this
163 * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the
164 * success probability.
166 * `-log10(success_probability) * amount_penalty_multiplier_msat * amount_msat / 2^20`
168 * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
169 * the amount will result in a penalty of the multiplier. And, as the success probability
170 * decreases, the negative `log10` weighting will increase dramatically. For higher success
171 * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
174 * Default value: 256 msat
176 public void set_amount_penalty_multiplier_msat(long val) {
177 bindings.ProbabilisticScoringParameters_set_amount_penalty_multiplier_msat(this.ptr, val);
178 Reference.reachabilityFence(this);
179 Reference.reachabilityFence(val);
183 * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
184 * channel's capacity, which makes us prefer nodes with a smaller `htlc_maximum_msat`. We
185 * treat such nodes preferentially as this makes balance discovery attacks harder to execute,
186 * thereby creating an incentive to restrict `htlc_maximum_msat` and improve privacy.
188 * Default value: 250 msat
190 public long get_anti_probing_penalty_msat() {
191 long ret = bindings.ProbabilisticScoringParameters_get_anti_probing_penalty_msat(this.ptr);
192 Reference.reachabilityFence(this);
197 * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
198 * channel's capacity, which makes us prefer nodes with a smaller `htlc_maximum_msat`. We
199 * treat such nodes preferentially as this makes balance discovery attacks harder to execute,
200 * thereby creating an incentive to restrict `htlc_maximum_msat` and improve privacy.
202 * Default value: 250 msat
204 public void set_anti_probing_penalty_msat(long val) {
205 bindings.ProbabilisticScoringParameters_set_anti_probing_penalty_msat(this.ptr, val);
206 Reference.reachabilityFence(this);
207 Reference.reachabilityFence(val);
211 long ret = bindings.ProbabilisticScoringParameters_clone_ptr(this.ptr);
212 Reference.reachabilityFence(this);
217 * Creates a copy of the ProbabilisticScoringParameters
219 public ProbabilisticScoringParameters clone() {
220 long ret = bindings.ProbabilisticScoringParameters_clone(this.ptr);
221 Reference.reachabilityFence(this);
222 if (ret >= 0 && ret <= 4096) { return null; }
223 org.ldk.structs.ProbabilisticScoringParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringParameters(null, ret); }
224 ret_hu_conv.ptrs_to.add(this);
229 * Marks all nodes in the given list as banned, i.e.,
230 * they will be avoided during path finding.
232 public void add_banned_from_list(NodeId[] node_ids) {
233 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 & ~1).toArray() : null);
234 Reference.reachabilityFence(this);
235 Reference.reachabilityFence(node_ids);
239 * Creates a "default" ProbabilisticScoringParameters. See struct and individual field documentaiton for details on which values are used.
241 public static ProbabilisticScoringParameters with_default() {
242 long ret = bindings.ProbabilisticScoringParameters_default();
243 if (ret >= 0 && ret <= 4096) { return null; }
244 org.ldk.structs.ProbabilisticScoringParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringParameters(null, ret); }
245 ret_hu_conv.ptrs_to.add(ret_hu_conv);