6 namespace org { namespace ldk { namespace structs {
10 * Parameters for configuring [`ProbabilisticScorer`].
12 * Used to configure base, liquidity, and amount penalties, the sum of which comprises the channel
13 * penalty (i.e., the amount in msats willing to be paid to avoid routing through the channel).
15 * The penalty applied to any channel by the [`ProbabilisticScorer`] is the sum of each of the
18 public class ProbabilisticScoringFeeParameters : CommonBase {
19 internal ProbabilisticScoringFeeParameters(object _dummy, long ptr) : base(ptr) { }
20 ~ProbabilisticScoringFeeParameters() {
21 if (ptr != 0) { bindings.ProbabilisticScoringFeeParameters_free(ptr); }
25 * A fixed penalty in msats to apply to each channel.
27 * Default value: 500 msat
29 public long get_base_penalty_msat() {
30 long ret = bindings.ProbabilisticScoringFeeParameters_get_base_penalty_msat(this.ptr);
36 * A fixed penalty in msats to apply to each channel.
38 * Default value: 500 msat
40 public void set_base_penalty_msat(long val) {
41 bindings.ProbabilisticScoringFeeParameters_set_base_penalty_msat(this.ptr, val);
47 * A multiplier used with the payment amount to calculate a fixed penalty applied to each
48 * channel, in excess of the [`base_penalty_msat`].
50 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
51 * fees plus penalty) for large payments. The penalty is computed as the product of this
52 * multiplier and `2^30`ths of the payment amount.
54 * ie `base_penalty_amount_multiplier_msat * amount_msat / 2^30`
56 * Default value: 8,192 msat
58 * [`base_penalty_msat`]: Self::base_penalty_msat
60 public long get_base_penalty_amount_multiplier_msat() {
61 long ret = bindings.ProbabilisticScoringFeeParameters_get_base_penalty_amount_multiplier_msat(this.ptr);
67 * A multiplier used with the payment amount to calculate a fixed penalty applied to each
68 * channel, in excess of the [`base_penalty_msat`].
70 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
71 * fees plus penalty) for large payments. The penalty is computed as the product of this
72 * multiplier and `2^30`ths of the payment amount.
74 * ie `base_penalty_amount_multiplier_msat * amount_msat / 2^30`
76 * Default value: 8,192 msat
78 * [`base_penalty_msat`]: Self::base_penalty_msat
80 public void set_base_penalty_amount_multiplier_msat(long val) {
81 bindings.ProbabilisticScoringFeeParameters_set_base_penalty_amount_multiplier_msat(this.ptr, val);
87 * A multiplier used in conjunction with the negative `log10` of the channel's success
88 * probability for a payment, as determined by our latest estimates of the channel's
89 * liquidity, to determine the liquidity penalty.
91 * The penalty is based in part on the knowledge learned from prior successful and unsuccessful
92 * payments. This knowledge is decayed over time based on [`liquidity_offset_half_life`]. The
93 * penalty is effectively limited to `2 * liquidity_penalty_multiplier_msat` (corresponding to
94 * lower bounding the success probability to `0.01`) when the amount falls within the
95 * uncertainty bounds of the channel liquidity balance. Amounts above the upper bound will
96 * result in a `u64::max_value` penalty, however.
98 * `-log10(success_probability) * liquidity_penalty_multiplier_msat`
100 * Default value: 30,000 msat
102 * [`liquidity_offset_half_life`]: ProbabilisticScoringDecayParameters::liquidity_offset_half_life
104 public long get_liquidity_penalty_multiplier_msat() {
105 long ret = bindings.ProbabilisticScoringFeeParameters_get_liquidity_penalty_multiplier_msat(this.ptr);
111 * A multiplier used in conjunction with the negative `log10` of the channel's success
112 * probability for a payment, as determined by our latest estimates of the channel's
113 * liquidity, to determine the liquidity penalty.
115 * The penalty is based in part on the knowledge learned from prior successful and unsuccessful
116 * payments. This knowledge is decayed over time based on [`liquidity_offset_half_life`]. The
117 * penalty is effectively limited to `2 * liquidity_penalty_multiplier_msat` (corresponding to
118 * lower bounding the success probability to `0.01`) when the amount falls within the
119 * uncertainty bounds of the channel liquidity balance. Amounts above the upper bound will
120 * result in a `u64::max_value` penalty, however.
122 * `-log10(success_probability) * liquidity_penalty_multiplier_msat`
124 * Default value: 30,000 msat
126 * [`liquidity_offset_half_life`]: ProbabilisticScoringDecayParameters::liquidity_offset_half_life
128 public void set_liquidity_penalty_multiplier_msat(long val) {
129 bindings.ProbabilisticScoringFeeParameters_set_liquidity_penalty_multiplier_msat(this.ptr, val);
135 * A multiplier used in conjunction with a payment amount and the negative `log10` of the
136 * channel's success probability for the payment, as determined by our latest estimates of the
137 * channel's liquidity, to determine the amount penalty.
139 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
140 * fees plus penalty) for large payments. The penalty is computed as the product of this
141 * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the
142 * success probability.
144 * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
146 * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
147 * the amount will result in a penalty of the multiplier. And, as the success probability
148 * decreases, the negative `log10` weighting will increase dramatically. For higher success
149 * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
152 * Default value: 192 msat
154 public long get_liquidity_penalty_amount_multiplier_msat() {
155 long ret = bindings.ProbabilisticScoringFeeParameters_get_liquidity_penalty_amount_multiplier_msat(this.ptr);
161 * A multiplier used in conjunction with a payment amount and the negative `log10` of the
162 * channel's success probability for the payment, as determined by our latest estimates of the
163 * channel's liquidity, to determine the amount penalty.
165 * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
166 * fees plus penalty) for large payments. The penalty is computed as the product of this
167 * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the
168 * success probability.
170 * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
172 * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
173 * the amount will result in a penalty of the multiplier. And, as the success probability
174 * decreases, the negative `log10` weighting will increase dramatically. For higher success
175 * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
178 * Default value: 192 msat
180 public void set_liquidity_penalty_amount_multiplier_msat(long val) {
181 bindings.ProbabilisticScoringFeeParameters_set_liquidity_penalty_amount_multiplier_msat(this.ptr, val);
187 * A multiplier used in conjunction with the negative `log10` of the channel's success
188 * probability for the payment, as determined based on the history of our estimates of the
189 * channel's available liquidity, to determine a penalty.
191 * This penalty is similar to [`liquidity_penalty_multiplier_msat`], however, instead of using
192 * only our latest estimate for the current liquidity available in the channel, it estimates
193 * success probability based on the estimated liquidity available in the channel through
194 * history. Specifically, every time we update our liquidity bounds on a given channel, we
195 * track which of several buckets those bounds fall into, exponentially decaying the
196 * probability of each bucket as new samples are added.
198 * Default value: 10,000 msat
200 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
202 public long get_historical_liquidity_penalty_multiplier_msat() {
203 long ret = bindings.ProbabilisticScoringFeeParameters_get_historical_liquidity_penalty_multiplier_msat(this.ptr);
209 * A multiplier used in conjunction with the negative `log10` of the channel's success
210 * probability for the payment, as determined based on the history of our estimates of the
211 * channel's available liquidity, to determine a penalty.
213 * This penalty is similar to [`liquidity_penalty_multiplier_msat`], however, instead of using
214 * only our latest estimate for the current liquidity available in the channel, it estimates
215 * success probability based on the estimated liquidity available in the channel through
216 * history. Specifically, every time we update our liquidity bounds on a given channel, we
217 * track which of several buckets those bounds fall into, exponentially decaying the
218 * probability of each bucket as new samples are added.
220 * Default value: 10,000 msat
222 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
224 public void set_historical_liquidity_penalty_multiplier_msat(long val) {
225 bindings.ProbabilisticScoringFeeParameters_set_historical_liquidity_penalty_multiplier_msat(this.ptr, val);
231 * A multiplier used in conjunction with the payment amount and the negative `log10` of the
232 * channel's success probability for the payment, as determined based on the history of our
233 * estimates of the channel's available liquidity, to determine a penalty.
235 * The purpose of the amount penalty is to avoid having fees dominate the channel cost for
236 * large payments. The penalty is computed as the product of this multiplier and the `2^20`ths
237 * of the payment amount, weighted by the negative `log10` of the success probability.
239 * This penalty is similar to [`liquidity_penalty_amount_multiplier_msat`], however, instead
240 * of using only our latest estimate for the current liquidity available in the channel, it
241 * estimates success probability based on the estimated liquidity available in the channel
242 * through history. Specifically, every time we update our liquidity bounds on a given
243 * channel, we track which of several buckets those bounds fall into, exponentially decaying
244 * the probability of each bucket as new samples are added.
246 * Default value: 64 msat
248 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
250 public long get_historical_liquidity_penalty_amount_multiplier_msat() {
251 long ret = bindings.ProbabilisticScoringFeeParameters_get_historical_liquidity_penalty_amount_multiplier_msat(this.ptr);
257 * A multiplier used in conjunction with the payment amount and the negative `log10` of the
258 * channel's success probability for the payment, as determined based on the history of our
259 * estimates of the channel's available liquidity, to determine a penalty.
261 * The purpose of the amount penalty is to avoid having fees dominate the channel cost for
262 * large payments. The penalty is computed as the product of this multiplier and the `2^20`ths
263 * of the payment amount, weighted by the negative `log10` of the success probability.
265 * This penalty is similar to [`liquidity_penalty_amount_multiplier_msat`], however, instead
266 * of using only our latest estimate for the current liquidity available in the channel, it
267 * estimates success probability based on the estimated liquidity available in the channel
268 * through history. Specifically, every time we update our liquidity bounds on a given
269 * channel, we track which of several buckets those bounds fall into, exponentially decaying
270 * the probability of each bucket as new samples are added.
272 * Default value: 64 msat
274 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
276 public void set_historical_liquidity_penalty_amount_multiplier_msat(long val) {
277 bindings.ProbabilisticScoringFeeParameters_set_historical_liquidity_penalty_amount_multiplier_msat(this.ptr, val);
283 * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
284 * channel's capacity, (ie. htlc_maximum_msat >= 0.5 * channel_capacity) which makes us
285 * prefer nodes with a smaller `htlc_maximum_msat`. We treat such nodes preferentially
286 * as this makes balance discovery attacks harder to execute, thereby creating an incentive
287 * to restrict `htlc_maximum_msat` and improve privacy.
289 * Default value: 250 msat
291 public long get_anti_probing_penalty_msat() {
292 long ret = bindings.ProbabilisticScoringFeeParameters_get_anti_probing_penalty_msat(this.ptr);
298 * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
299 * channel's capacity, (ie. htlc_maximum_msat >= 0.5 * channel_capacity) which makes us
300 * prefer nodes with a smaller `htlc_maximum_msat`. We treat such nodes preferentially
301 * as this makes balance discovery attacks harder to execute, thereby creating an incentive
302 * to restrict `htlc_maximum_msat` and improve privacy.
304 * Default value: 250 msat
306 public void set_anti_probing_penalty_msat(long val) {
307 bindings.ProbabilisticScoringFeeParameters_set_anti_probing_penalty_msat(this.ptr, val);
313 * This penalty is applied when the amount we're attempting to send over a channel exceeds our
314 * current estimate of the channel's available liquidity.
316 * Note that in this case all other penalties, including the
317 * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based
318 * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if
319 * applicable, are still included in the overall penalty.
321 * If you wish to avoid creating paths with such channels entirely, setting this to a value of
322 * `u64::max_value()` will guarantee that.
324 * Default value: 1_0000_0000_000 msat (1 Bitcoin)
326 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
327 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
328 * [`base_penalty_msat`]: Self::base_penalty_msat
329 * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat
331 public long get_considered_impossible_penalty_msat() {
332 long ret = bindings.ProbabilisticScoringFeeParameters_get_considered_impossible_penalty_msat(this.ptr);
338 * This penalty is applied when the amount we're attempting to send over a channel exceeds our
339 * current estimate of the channel's available liquidity.
341 * Note that in this case all other penalties, including the
342 * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based
343 * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if
344 * applicable, are still included in the overall penalty.
346 * If you wish to avoid creating paths with such channels entirely, setting this to a value of
347 * `u64::max_value()` will guarantee that.
349 * Default value: 1_0000_0000_000 msat (1 Bitcoin)
351 * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
352 * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
353 * [`base_penalty_msat`]: Self::base_penalty_msat
354 * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat
356 public void set_considered_impossible_penalty_msat(long val) {
357 bindings.ProbabilisticScoringFeeParameters_set_considered_impossible_penalty_msat(this.ptr, val);
362 internal long clone_ptr() {
363 long ret = bindings.ProbabilisticScoringFeeParameters_clone_ptr(this.ptr);
369 * Creates a copy of the ProbabilisticScoringFeeParameters
371 public ProbabilisticScoringFeeParameters clone() {
372 long ret = bindings.ProbabilisticScoringFeeParameters_clone(this.ptr);
374 if (ret >= 0 && ret <= 4096) { return null; }
375 org.ldk.structs.ProbabilisticScoringFeeParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringFeeParameters(null, ret); }
376 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.AddLast(this); };
381 * Creates a "default" ProbabilisticScoringFeeParameters. See struct and individual field documentaiton for details on which values are used.
383 public static ProbabilisticScoringFeeParameters with_default() {
384 long ret = bindings.ProbabilisticScoringFeeParameters_default();
385 if (ret >= 0 && ret <= 4096) { return null; }
386 org.ldk.structs.ProbabilisticScoringFeeParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringFeeParameters(null, ret); }
387 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.AddLast(ret_hu_conv); };
392 * Marks the node with the given `node_id` as banned,
393 * i.e it will be avoided during path finding.
395 public void add_banned(org.ldk.structs.NodeId node_id) {
396 bindings.ProbabilisticScoringFeeParameters_add_banned(this.ptr, node_id == null ? 0 : node_id.ptr);
398 GC.KeepAlive(node_id);
399 if (this != null) { this.ptrs_to.AddLast(node_id); };
403 * Marks all nodes in the given list as banned, i.e.,
404 * they will be avoided during path finding.
406 public void add_banned_from_list(NodeId[] node_ids) {
407 bindings.ProbabilisticScoringFeeParameters_add_banned_from_list(this.ptr, node_ids != null ? InternalUtils.mapArray(node_ids, node_ids_conv_8 => node_ids_conv_8 == null ? 0 : node_ids_conv_8.ptr) : null);
409 GC.KeepAlive(node_ids);
410 foreach (NodeId node_ids_conv_8 in node_ids) { if (this != null) { this.ptrs_to.AddLast(node_ids_conv_8); }; };
414 * Removes the node with the given `node_id` from the list of nodes to avoid.
416 public void remove_banned(org.ldk.structs.NodeId node_id) {
417 bindings.ProbabilisticScoringFeeParameters_remove_banned(this.ptr, node_id == null ? 0 : node_id.ptr);
419 GC.KeepAlive(node_id);
420 if (this != null) { this.ptrs_to.AddLast(node_id); };
424 * Sets a manual penalty for the given node.
426 public void set_manual_penalty(org.ldk.structs.NodeId node_id, long penalty) {
427 bindings.ProbabilisticScoringFeeParameters_set_manual_penalty(this.ptr, node_id == null ? 0 : node_id.ptr, penalty);
429 GC.KeepAlive(node_id);
430 GC.KeepAlive(penalty);
431 if (this != null) { this.ptrs_to.AddLast(node_id); };
435 * Removes the node with the given `node_id` from the list of manual penalties.
437 public void remove_manual_penalty(org.ldk.structs.NodeId node_id) {
438 bindings.ProbabilisticScoringFeeParameters_remove_manual_penalty(this.ptr, node_id == null ? 0 : node_id.ptr);
440 GC.KeepAlive(node_id);
441 if (this != null) { this.ptrs_to.AddLast(node_id); };
445 * Clears the list of manual penalties that are applied during path finding.
447 public void clear_manual_penalties() {
448 bindings.ProbabilisticScoringFeeParameters_clear_manual_penalties(this.ptr);