_ 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, as determined by our latest estimates of the channel's
  94          * liquidity, to determine the liquidity penalty.
  95          *
  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.
 102          *
 103          * `-log10(success_probability) * liquidity_penalty_multiplier_msat`
 104          *
 105          * Default value: 30,000 msat
 106          *
 107          * [`liquidity_offset_half_life`]: Self::liquidity_offset_half_life
 108          */
 109         public long get_liquidity_penalty_multiplier_msat() {
 110                 long ret = bindings.ProbabilisticScoringParameters_get_liquidity_penalty_multiplier_msat(this.ptr);
 111                 Reference.reachabilityFence(this);
 112                 return ret;
 113         }
 114
 115         /**
 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.
 119          *
 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.
 126          *
 127          * `-log10(success_probability) * liquidity_penalty_multiplier_msat`
 128          *
 129          * Default value: 30,000 msat
 130          *
 131          * [`liquidity_offset_half_life`]: Self::liquidity_offset_half_life
 132          */
 133         public void set_liquidity_penalty_multiplier_msat(long val) {
 134                 bindings.ProbabilisticScoringParameters_set_liquidity_penalty_multiplier_msat(this.ptr, val);
 135                 Reference.reachabilityFence(this);
 136                 Reference.reachabilityFence(val);
 137         }
 138
 139         /**
 140          * Whenever this amount of time elapses since the last update to a channel's liquidity bounds,
 141          * the distance from the bounds to \"zero\" is cut in half. In other words, the lower-bound on
 142          * the available liquidity is halved and the upper-bound moves half-way to the channel's total
 143          * capacity.
 144          *
 145          * Because halving the liquidity bounds grows the uncertainty on the channel's liquidity,
 146          * the penalty for an amount within the new bounds may change. See the [`ProbabilisticScorer`]
 147          * struct documentation for more info on the way the liquidity bounds are used.
 148          *
 149          * For example, if the channel's capacity is 1 million sats, and the current upper and lower
 150          * liquidity bounds are 200,000 sats and 600,000 sats, after this amount of time the upper
 151          * and lower liquidity bounds will be decayed to 100,000 and 800,000 sats.
 152          *
 153          * Default value: 6 hours
 154          *
 155          * # Note
 156          *
 157          * When built with the `no-std` feature, time will never elapse. Therefore, the channel
 158          * liquidity knowledge will never decay except when the bounds cross.
 159          */
 160         public long get_liquidity_offset_half_life() {
 161                 long ret = bindings.ProbabilisticScoringParameters_get_liquidity_offset_half_life(this.ptr);
 162                 Reference.reachabilityFence(this);
 163                 return ret;
 164         }
 165
 166         /**
 167          * Whenever this amount of time elapses since the last update to a channel's liquidity bounds,
 168          * the distance from the bounds to \"zero\" is cut in half. In other words, the lower-bound on
 169          * the available liquidity is halved and the upper-bound moves half-way to the channel's total
 170          * capacity.
 171          *
 172          * Because halving the liquidity bounds grows the uncertainty on the channel's liquidity,
 173          * the penalty for an amount within the new bounds may change. See the [`ProbabilisticScorer`]
 174          * struct documentation for more info on the way the liquidity bounds are used.
 175          *
 176          * For example, if the channel's capacity is 1 million sats, and the current upper and lower
 177          * liquidity bounds are 200,000 sats and 600,000 sats, after this amount of time the upper
 178          * and lower liquidity bounds will be decayed to 100,000 and 800,000 sats.
 179          *
 180          * Default value: 6 hours
 181          *
 182          * # Note
 183          *
 184          * When built with the `no-std` feature, time will never elapse. Therefore, the channel
 185          * liquidity knowledge will never decay except when the bounds cross.
 186          */
 187         public void set_liquidity_offset_half_life(long val) {
 188                 bindings.ProbabilisticScoringParameters_set_liquidity_offset_half_life(this.ptr, val);
 189                 Reference.reachabilityFence(this);
 190                 Reference.reachabilityFence(val);
 191         }
 192
 193         /**
 194          * A multiplier used in conjunction with a payment amount and the negative `log10` of the
 195          * channel's success probability for the payment, as determined by our latest estimates of the
 196          * channel's liquidity, to determine the amount penalty.
 197          *
 198          * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
 199          * fees plus penalty) for large payments. The penalty is computed as the product of this
 200          * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the
 201          * success probability.
 202          *
 203          * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
 204          *
 205          * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
 206          * the amount will result in a penalty of the multiplier. And, as the success probability
 207          * decreases, the negative `log10` weighting will increase dramatically. For higher success
 208          * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
 209          * fall below `1`.
 210          *
 211          * Default value: 192 msat
 212          */
 213         public long get_liquidity_penalty_amount_multiplier_msat() {
 214                 long ret = bindings.ProbabilisticScoringParameters_get_liquidity_penalty_amount_multiplier_msat(this.ptr);
 215                 Reference.reachabilityFence(this);
 216                 return ret;
 217         }
 218
 219         /**
 220          * A multiplier used in conjunction with a payment amount and the negative `log10` of the
 221          * channel's success probability for the payment, as determined by our latest estimates of the
 222          * channel's liquidity, to determine the amount penalty.
 223          *
 224          * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
 225          * fees plus penalty) for large payments. The penalty is computed as the product of this
 226          * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the
 227          * success probability.
 228          *
 229          * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
 230          *
 231          * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
 232          * the amount will result in a penalty of the multiplier. And, as the success probability
 233          * decreases, the negative `log10` weighting will increase dramatically. For higher success
 234          * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
 235          * fall below `1`.
 236          *
 237          * Default value: 192 msat
 238          */
 239         public void set_liquidity_penalty_amount_multiplier_msat(long val) {
 240                 bindings.ProbabilisticScoringParameters_set_liquidity_penalty_amount_multiplier_msat(this.ptr, val);
 241                 Reference.reachabilityFence(this);
 242                 Reference.reachabilityFence(val);
 243         }
 244
 245         /**
 246          * A multiplier used in conjunction with the negative `log10` of the channel's success
 247          * probability for the payment, as determined based on the history of our estimates of the
 248          * channel's available liquidity, to determine a penalty.
 249          *
 250          * This penalty is similar to [`liquidity_penalty_multiplier_msat`], however, instead of using
 251          * only our latest estimate for the current liquidity available in the channel, it estimates
 252          * success probability based on the estimated liquidity available in the channel through
 253          * history. Specifically, every time we update our liquidity bounds on a given channel, we
 254          * track which of several buckets those bounds fall into, exponentially decaying the
 255          * probability of each bucket as new samples are added.
 256          *
 257          * Default value: 10,000 msat
 258          *
 259          * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
 260          */
 261         public long get_historical_liquidity_penalty_multiplier_msat() {
 262                 long ret = bindings.ProbabilisticScoringParameters_get_historical_liquidity_penalty_multiplier_msat(this.ptr);
 263                 Reference.reachabilityFence(this);
 264                 return ret;
 265         }
 266
 267         /**
 268          * A multiplier used in conjunction with the negative `log10` of the channel's success
 269          * probability for the payment, as determined based on the history of our estimates of the
 270          * channel's available liquidity, to determine a penalty.
 271          *
 272          * This penalty is similar to [`liquidity_penalty_multiplier_msat`], however, instead of using
 273          * only our latest estimate for the current liquidity available in the channel, it estimates
 274          * success probability based on the estimated liquidity available in the channel through
 275          * history. Specifically, every time we update our liquidity bounds on a given channel, we
 276          * track which of several buckets those bounds fall into, exponentially decaying the
 277          * probability of each bucket as new samples are added.
 278          *
 279          * Default value: 10,000 msat
 280          *
 281          * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
 282          */
 283         public void set_historical_liquidity_penalty_multiplier_msat(long val) {
 284                 bindings.ProbabilisticScoringParameters_set_historical_liquidity_penalty_multiplier_msat(this.ptr, val);
 285                 Reference.reachabilityFence(this);
 286                 Reference.reachabilityFence(val);
 287         }
 288
 289         /**
 290          * A multiplier used in conjunction with the payment amount and the negative `log10` of the
 291          * channel's success probability for the payment, as determined based on the history of our
 292          * estimates of the channel's available liquidity, to determine a penalty.
 293          *
 294          * The purpose of the amount penalty is to avoid having fees dominate the channel cost for
 295          * large payments. The penalty is computed as the product of this multiplier and the `2^20`ths
 296          * of the payment amount, weighted by the negative `log10` of the success probability.
 297          *
 298          * This penalty is similar to [`liquidity_penalty_amount_multiplier_msat`], however, instead
 299          * of using only our latest estimate for the current liquidity available in the channel, it
 300          * estimates success probability based on the estimated liquidity available in the channel
 301          * through history. Specifically, every time we update our liquidity bounds on a given
 302          * channel, we track which of several buckets those bounds fall into, exponentially decaying
 303          * the probability of each bucket as new samples are added.
 304          *
 305          * Default value: 64 msat
 306          *
 307          * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
 308          */
 309         public long get_historical_liquidity_penalty_amount_multiplier_msat() {
 310                 long ret = bindings.ProbabilisticScoringParameters_get_historical_liquidity_penalty_amount_multiplier_msat(this.ptr);
 311                 Reference.reachabilityFence(this);
 312                 return ret;
 313         }
 314
 315         /**
 316          * A multiplier used in conjunction with the payment amount and the negative `log10` of the
 317          * channel's success probability for the payment, as determined based on the history of our
 318          * estimates of the channel's available liquidity, to determine a penalty.
 319          *
 320          * The purpose of the amount penalty is to avoid having fees dominate the channel cost for
 321          * large payments. The penalty is computed as the product of this multiplier and the `2^20`ths
 322          * of the payment amount, weighted by the negative `log10` of the success probability.
 323          *
 324          * This penalty is similar to [`liquidity_penalty_amount_multiplier_msat`], however, instead
 325          * of using only our latest estimate for the current liquidity available in the channel, it
 326          * estimates success probability based on the estimated liquidity available in the channel
 327          * through history. Specifically, every time we update our liquidity bounds on a given
 328          * channel, we track which of several buckets those bounds fall into, exponentially decaying
 329          * the probability of each bucket as new samples are added.
 330          *
 331          * Default value: 64 msat
 332          *
 333          * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
 334          */
 335         public void set_historical_liquidity_penalty_amount_multiplier_msat(long val) {
 336                 bindings.ProbabilisticScoringParameters_set_historical_liquidity_penalty_amount_multiplier_msat(this.ptr, val);
 337                 Reference.reachabilityFence(this);
 338                 Reference.reachabilityFence(val);
 339         }
 340
 341         /**
 342          * If we aren't learning any new datapoints for a channel, the historical liquidity bounds
 343          * tracking can simply live on with increasingly stale data. Instead, when a channel has not
 344          * seen a liquidity estimate update for this amount of time, the historical datapoints are
 345          * decayed by half.
 346          *
 347          * Note that after 16 or more half lives all historical data will be completely gone.
 348          *
 349          * Default value: 14 days
 350          */
 351         public long get_historical_no_updates_half_life() {
 352                 long ret = bindings.ProbabilisticScoringParameters_get_historical_no_updates_half_life(this.ptr);
 353                 Reference.reachabilityFence(this);
 354                 return ret;
 355         }
 356
 357         /**
 358          * If we aren't learning any new datapoints for a channel, the historical liquidity bounds
 359          * tracking can simply live on with increasingly stale data. Instead, when a channel has not
 360          * seen a liquidity estimate update for this amount of time, the historical datapoints are
 361          * decayed by half.
 362          *
 363          * Note that after 16 or more half lives all historical data will be completely gone.
 364          *
 365          * Default value: 14 days
 366          */
 367         public void set_historical_no_updates_half_life(long val) {
 368                 bindings.ProbabilisticScoringParameters_set_historical_no_updates_half_life(this.ptr, val);
 369                 Reference.reachabilityFence(this);
 370                 Reference.reachabilityFence(val);
 371         }
 372
 373         /**
 374          * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
 375          * channel's capacity, which makes us prefer nodes with a smaller `htlc_maximum_msat`. We
 376          * treat such nodes preferentially as this makes balance discovery attacks harder to execute,
 377          * thereby creating an incentive to restrict `htlc_maximum_msat` and improve privacy.
 378          *
 379          * Default value: 250 msat
 380          */
 381         public long get_anti_probing_penalty_msat() {
 382                 long ret = bindings.ProbabilisticScoringParameters_get_anti_probing_penalty_msat(this.ptr);
 383                 Reference.reachabilityFence(this);
 384                 return ret;
 385         }
 386
 387         /**
 388          * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
 389          * channel's capacity, which makes us prefer nodes with a smaller `htlc_maximum_msat`. We
 390          * treat such nodes preferentially as this makes balance discovery attacks harder to execute,
 391          * thereby creating an incentive to restrict `htlc_maximum_msat` and improve privacy.
 392          *
 393          * Default value: 250 msat
 394          */
 395         public void set_anti_probing_penalty_msat(long val) {
 396                 bindings.ProbabilisticScoringParameters_set_anti_probing_penalty_msat(this.ptr, val);
 397                 Reference.reachabilityFence(this);
 398                 Reference.reachabilityFence(val);
 399         }
 400
 401         /**
 402          * This penalty is applied when the amount we're attempting to send over a channel exceeds our
 403          * current estimate of the channel's available liquidity.
 404          *
 405          * Note that in this case all other penalties, including the
 406          * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based
 407          * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if
 408          * applicable, are still included in the overall penalty.
 409          *
 410          * If you wish to avoid creating paths with such channels entirely, setting this to a value of
 411          * `u64::max_value()` will guarantee that.
 412          *
 413          * Default value: 1_0000_0000_000 msat (1 Bitcoin)
 414          *
 415          * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
 416          * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
 417          * [`base_penalty_msat`]: Self::base_penalty_msat
 418          * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat
 419          */
 420         public long get_considered_impossible_penalty_msat() {
 421                 long ret = bindings.ProbabilisticScoringParameters_get_considered_impossible_penalty_msat(this.ptr);
 422                 Reference.reachabilityFence(this);
 423                 return ret;
 424         }
 425
 426         /**
 427          * This penalty is applied when the amount we're attempting to send over a channel exceeds our
 428          * current estimate of the channel's available liquidity.
 429          *
 430          * Note that in this case all other penalties, including the
 431          * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based
 432          * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if
 433          * applicable, are still included in the overall penalty.
 434          *
 435          * If you wish to avoid creating paths with such channels entirely, setting this to a value of
 436          * `u64::max_value()` will guarantee that.
 437          *
 438          * Default value: 1_0000_0000_000 msat (1 Bitcoin)
 439          *
 440          * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
 441          * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
 442          * [`base_penalty_msat`]: Self::base_penalty_msat
 443          * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat
 444          */
 445         public void set_considered_impossible_penalty_msat(long val) {
 446                 bindings.ProbabilisticScoringParameters_set_considered_impossible_penalty_msat(this.ptr, val);
 447                 Reference.reachabilityFence(this);
 448                 Reference.reachabilityFence(val);
 449         }
 450
 451         long clone_ptr() {
 452                 long ret = bindings.ProbabilisticScoringParameters_clone_ptr(this.ptr);
 453                 Reference.reachabilityFence(this);
 454                 return ret;
 455         }
 456
 457         /**
 458          * Creates a copy of the ProbabilisticScoringParameters
 459          */
 460         public ProbabilisticScoringParameters clone() {
 461                 long ret = bindings.ProbabilisticScoringParameters_clone(this.ptr);
 462                 Reference.reachabilityFence(this);
 463                 if (ret >= 0 && ret <= 4096) { return null; }
 464                 org.ldk.structs.ProbabilisticScoringParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringParameters(null, ret); }
 465                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 466                 return ret_hu_conv;
 467         }
 468
 469         /**
 470          * Marks all nodes in the given list as banned, i.e.,
 471          * they will be avoided during path finding.
 472          */
 473         public void add_banned_from_list(NodeId[] node_ids) {
 474                 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);
 475                 Reference.reachabilityFence(this);
 476                 Reference.reachabilityFence(node_ids);
 477                 for (NodeId node_ids_conv_8: node_ids) { if (this != null) { this.ptrs_to.add(node_ids_conv_8); }; };
 478         }
 479
 480         /**
 481          * Creates a "default" ProbabilisticScoringParameters. See struct and individual field documentaiton for details on which values are used.
 482          */
 483         public static ProbabilisticScoringParameters with_default() {
 484                 long ret = bindings.ProbabilisticScoringParameters_default();
 485                 if (ret >= 0 && ret <= 4096) { return null; }
 486                 org.ldk.structs.ProbabilisticScoringParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringParameters(null, ret); }
 487                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); };
 488                 return ret_hu_conv;
 489         }
 490
 491 }