_ Git - ldk-java/blob - src/main/java/org/ldk/structs/ProbabilisticScoringParameters.java

   1 package org.ldk.structs;
   2
   3 import org.ldk.impl.bindings;
   4 import org.ldk.enums.*;
   5 import org.ldk.util.*;
   6 import java.util.Arrays;
   7 import java.lang.ref.Reference;
   8 import javax.annotation.Nullable;
   9
  10
  11 /**
  12  * Parameters for configuring [`ProbabilisticScorer`].
  13  *
  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).
  16  *
  17  * The penalty applied to any channel by the [`ProbabilisticScorer`] is the sum of each of the
  18  * parameters here.
  19  */
  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 {
  25                 super.finalize();
  26                 if (ptr != 0) { bindings.ProbabilisticScoringParameters_free(ptr); }
  27         }
  28
  29         /**
  30          * A fixed penalty in msats to apply to each channel.
  31          *
  32          * Default value: 500 msat
  33          */
  34         public long get_base_penalty_msat() {
  35                 long ret = bindings.ProbabilisticScoringParameters_get_base_penalty_msat(this.ptr);
  36                 Reference.reachabilityFence(this);
  37                 return ret;
  38         }
  39
  40         /**
  41          * A fixed penalty in msats to apply to each channel.
  42          *
  43          * Default value: 500 msat
  44          */
  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);
  49         }
  50
  51         /**
  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`].
  54          *
  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.
  58          *
  59          * ie `base_penalty_amount_multiplier_msat * amount_msat / 2^30`
  60          *
  61          * Default value: 8,192 msat
  62          *
  63          * [`base_penalty_msat`]: Self::base_penalty_msat
  64          */
  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);
  68                 return ret;
  69         }
  70
  71         /**
  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`].
  74          *
  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.
  78          *
  79          * ie `base_penalty_amount_multiplier_msat * amount_msat / 2^30`
  80          *
  81          * Default value: 8,192 msat
  82          *
  83          * [`base_penalty_msat`]: Self::base_penalty_msat
  84          */
  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);
  89         }
  90
  91         /**
  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.
  94          *
  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.
 101          *
 102          * Default value: 40,000 msat
 103          *
 104          * [`liquidity_offset_half_life`]: Self::liquidity_offset_half_life
 105          */
 106         public long get_liquidity_penalty_multiplier_msat() {
 107                 long ret = bindings.ProbabilisticScoringParameters_get_liquidity_penalty_multiplier_msat(this.ptr);
 108                 Reference.reachabilityFence(this);
 109                 return ret;
 110         }
 111
 112         /**
 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.
 115          *
 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.
 122          *
 123          * Default value: 40,000 msat
 124          *
 125          * [`liquidity_offset_half_life`]: Self::liquidity_offset_half_life
 126          */
 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);
 131         }
 132
 133         /**
 134          * The time required to elapse before any knowledge learned about channel liquidity balances is
 135          * cut in half.
 136          *
 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.
 140          *
 141          * Default value: 1 hour
 142          *
 143          * # Note
 144          *
 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.
 147          */
 148         public long get_liquidity_offset_half_life() {
 149                 long ret = bindings.ProbabilisticScoringParameters_get_liquidity_offset_half_life(this.ptr);
 150                 Reference.reachabilityFence(this);
 151                 return ret;
 152         }
 153
 154         /**
 155          * The time required to elapse before any knowledge learned about channel liquidity balances is
 156          * cut in half.
 157          *
 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.
 161          *
 162          * Default value: 1 hour
 163          *
 164          * # Note
 165          *
 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.
 168          */
 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);
 173         }
 174
 175         /**
 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.
 178          *
 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.
 183          *
 184          * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
 185          *
 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
 190          * fall below `1`.
 191          *
 192          * Default value: 256 msat
 193          */
 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);
 197                 return ret;
 198         }
 199
 200         /**
 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.
 203          *
 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.
 208          *
 209          * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
 210          *
 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
 215          * fall below `1`.
 216          *
 217          * Default value: 256 msat
 218          */
 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);
 223         }
 224
 225         /**
 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.
 230          *
 231          * Default value: 250 msat
 232          */
 233         public long get_anti_probing_penalty_msat() {
 234                 long ret = bindings.ProbabilisticScoringParameters_get_anti_probing_penalty_msat(this.ptr);
 235                 Reference.reachabilityFence(this);
 236                 return ret;
 237         }
 238
 239         /**
 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.
 244          *
 245          * Default value: 250 msat
 246          */
 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);
 251         }
 252
 253         /**
 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.
 256          *
 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.
 261          *
 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.
 264          *
 265          * Default value: 1_0000_0000_000 msat (1 Bitcoin)
 266          *
 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
 271          */
 272         public long get_considered_impossible_penalty_msat() {
 273                 long ret = bindings.ProbabilisticScoringParameters_get_considered_impossible_penalty_msat(this.ptr);
 274                 Reference.reachabilityFence(this);
 275                 return ret;
 276         }
 277
 278         /**
 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.
 281          *
 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.
 286          *
 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.
 289          *
 290          * Default value: 1_0000_0000_000 msat (1 Bitcoin)
 291          *
 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
 296          */
 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);
 301         }
 302
 303         long clone_ptr() {
 304                 long ret = bindings.ProbabilisticScoringParameters_clone_ptr(this.ptr);
 305                 Reference.reachabilityFence(this);
 306                 return ret;
 307         }
 308
 309         /**
 310          * Creates a copy of the ProbabilisticScoringParameters
 311          */
 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                 ret_hu_conv.ptrs_to.add(this);
 318                 return ret_hu_conv;
 319         }
 320
 321         /**
 322          * Marks all nodes in the given list as banned, i.e.,
 323          * they will be avoided during path finding.
 324          */
 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) { this.ptrs_to.add(node_ids_conv_8); };
 330         }
 331
 332         /**
 333          * Creates a "default" ProbabilisticScoringParameters. See struct and individual field documentaiton for details on which values are used.
 334          */
 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                 ret_hu_conv.ptrs_to.add(ret_hu_conv);
 340                 return ret_hu_conv;
 341         }
 342
 343 }