_ Git - ldk-java/blob - src/main/java/org/ldk/structs/ProbabilisticScoringFeeParameters.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 ProbabilisticScoringFeeParameters extends CommonBase {
  22         ProbabilisticScoringFeeParameters(Object _dummy, long ptr) { super(ptr); }
  23         @Override @SuppressWarnings("deprecation")
  24         protected void finalize() throws Throwable {
  25                 super.finalize();
  26                 if (ptr != 0) { bindings.ProbabilisticScoringFeeParameters_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.ProbabilisticScoringFeeParameters_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.ProbabilisticScoringFeeParameters_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.ProbabilisticScoringFeeParameters_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.ProbabilisticScoringFeeParameters_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`]: ProbabilisticScoringDecayParameters::liquidity_offset_half_life
 108          */
 109         public long get_liquidity_penalty_multiplier_msat() {
 110                 long ret = bindings.ProbabilisticScoringFeeParameters_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`]: ProbabilisticScoringDecayParameters::liquidity_offset_half_life
 132          */
 133         public void set_liquidity_penalty_multiplier_msat(long val) {
 134                 bindings.ProbabilisticScoringFeeParameters_set_liquidity_penalty_multiplier_msat(this.ptr, val);
 135                 Reference.reachabilityFence(this);
 136                 Reference.reachabilityFence(val);
 137         }
 138
 139         /**
 140          * A multiplier used in conjunction with a payment amount and the negative `log10` of the
 141          * channel's success probability for the payment, as determined by our latest estimates of the
 142          * channel's liquidity, to determine the amount penalty.
 143          *
 144          * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
 145          * fees plus penalty) for large payments. The penalty is computed as the product of this
 146          * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the
 147          * success probability.
 148          *
 149          * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
 150          *
 151          * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
 152          * the amount will result in a penalty of the multiplier. And, as the success probability
 153          * decreases, the negative `log10` weighting will increase dramatically. For higher success
 154          * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
 155          * fall below `1`.
 156          *
 157          * Default value: 192 msat
 158          */
 159         public long get_liquidity_penalty_amount_multiplier_msat() {
 160                 long ret = bindings.ProbabilisticScoringFeeParameters_get_liquidity_penalty_amount_multiplier_msat(this.ptr);
 161                 Reference.reachabilityFence(this);
 162                 return ret;
 163         }
 164
 165         /**
 166          * A multiplier used in conjunction with a payment amount and the negative `log10` of the
 167          * channel's success probability for the payment, as determined by our latest estimates of the
 168          * channel's liquidity, to determine the amount penalty.
 169          *
 170          * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
 171          * fees plus penalty) for large payments. The penalty is computed as the product of this
 172          * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the
 173          * success probability.
 174          *
 175          * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20`
 176          *
 177          * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
 178          * the amount will result in a penalty of the multiplier. And, as the success probability
 179          * decreases, the negative `log10` weighting will increase dramatically. For higher success
 180          * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
 181          * fall below `1`.
 182          *
 183          * Default value: 192 msat
 184          */
 185         public void set_liquidity_penalty_amount_multiplier_msat(long val) {
 186                 bindings.ProbabilisticScoringFeeParameters_set_liquidity_penalty_amount_multiplier_msat(this.ptr, val);
 187                 Reference.reachabilityFence(this);
 188                 Reference.reachabilityFence(val);
 189         }
 190
 191         /**
 192          * A multiplier used in conjunction with the negative `log10` of the channel's success
 193          * probability for the payment, as determined based on the history of our estimates of the
 194          * channel's available liquidity, to determine a penalty.
 195          *
 196          * This penalty is similar to [`liquidity_penalty_multiplier_msat`], however, instead of using
 197          * only our latest estimate for the current liquidity available in the channel, it estimates
 198          * success probability based on the estimated liquidity available in the channel through
 199          * history. Specifically, every time we update our liquidity bounds on a given channel, we
 200          * track which of several buckets those bounds fall into, exponentially decaying the
 201          * probability of each bucket as new samples are added.
 202          *
 203          * Default value: 10,000 msat
 204          *
 205          * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
 206          */
 207         public long get_historical_liquidity_penalty_multiplier_msat() {
 208                 long ret = bindings.ProbabilisticScoringFeeParameters_get_historical_liquidity_penalty_multiplier_msat(this.ptr);
 209                 Reference.reachabilityFence(this);
 210                 return ret;
 211         }
 212
 213         /**
 214          * A multiplier used in conjunction with the negative `log10` of the channel's success
 215          * probability for the payment, as determined based on the history of our estimates of the
 216          * channel's available liquidity, to determine a penalty.
 217          *
 218          * This penalty is similar to [`liquidity_penalty_multiplier_msat`], however, instead of using
 219          * only our latest estimate for the current liquidity available in the channel, it estimates
 220          * success probability based on the estimated liquidity available in the channel through
 221          * history. Specifically, every time we update our liquidity bounds on a given channel, we
 222          * track which of several buckets those bounds fall into, exponentially decaying the
 223          * probability of each bucket as new samples are added.
 224          *
 225          * Default value: 10,000 msat
 226          *
 227          * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
 228          */
 229         public void set_historical_liquidity_penalty_multiplier_msat(long val) {
 230                 bindings.ProbabilisticScoringFeeParameters_set_historical_liquidity_penalty_multiplier_msat(this.ptr, val);
 231                 Reference.reachabilityFence(this);
 232                 Reference.reachabilityFence(val);
 233         }
 234
 235         /**
 236          * A multiplier used in conjunction with the payment amount and the negative `log10` of the
 237          * channel's success probability for the payment, as determined based on the history of our
 238          * estimates of the channel's available liquidity, to determine a penalty.
 239          *
 240          * The purpose of the amount penalty is to avoid having fees dominate the channel cost for
 241          * large payments. The penalty is computed as the product of this multiplier and the `2^20`ths
 242          * of the payment amount, weighted by the negative `log10` of the success probability.
 243          *
 244          * This penalty is similar to [`liquidity_penalty_amount_multiplier_msat`], however, instead
 245          * of using only our latest estimate for the current liquidity available in the channel, it
 246          * estimates success probability based on the estimated liquidity available in the channel
 247          * through history. Specifically, every time we update our liquidity bounds on a given
 248          * channel, we track which of several buckets those bounds fall into, exponentially decaying
 249          * the probability of each bucket as new samples are added.
 250          *
 251          * Default value: 64 msat
 252          *
 253          * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
 254          */
 255         public long get_historical_liquidity_penalty_amount_multiplier_msat() {
 256                 long ret = bindings.ProbabilisticScoringFeeParameters_get_historical_liquidity_penalty_amount_multiplier_msat(this.ptr);
 257                 Reference.reachabilityFence(this);
 258                 return ret;
 259         }
 260
 261         /**
 262          * A multiplier used in conjunction with the payment amount and the negative `log10` of the
 263          * channel's success probability for the payment, as determined based on the history of our
 264          * estimates of the channel's available liquidity, to determine a penalty.
 265          *
 266          * The purpose of the amount penalty is to avoid having fees dominate the channel cost for
 267          * large payments. The penalty is computed as the product of this multiplier and the `2^20`ths
 268          * of the payment amount, weighted by the negative `log10` of the success probability.
 269          *
 270          * This penalty is similar to [`liquidity_penalty_amount_multiplier_msat`], however, instead
 271          * of using only our latest estimate for the current liquidity available in the channel, it
 272          * estimates success probability based on the estimated liquidity available in the channel
 273          * through history. Specifically, every time we update our liquidity bounds on a given
 274          * channel, we track which of several buckets those bounds fall into, exponentially decaying
 275          * the probability of each bucket as new samples are added.
 276          *
 277          * Default value: 64 msat
 278          *
 279          * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
 280          */
 281         public void set_historical_liquidity_penalty_amount_multiplier_msat(long val) {
 282                 bindings.ProbabilisticScoringFeeParameters_set_historical_liquidity_penalty_amount_multiplier_msat(this.ptr, val);
 283                 Reference.reachabilityFence(this);
 284                 Reference.reachabilityFence(val);
 285         }
 286
 287         /**
 288          * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
 289          * channel's capacity, (ie. htlc_maximum_msat >= 0.5 * channel_capacity) which makes us
 290          * prefer nodes with a smaller `htlc_maximum_msat`. We treat such nodes preferentially
 291          * as this makes balance discovery attacks harder to execute, thereby creating an incentive
 292          * to restrict `htlc_maximum_msat` and improve privacy.
 293          *
 294          * Default value: 250 msat
 295          */
 296         public long get_anti_probing_penalty_msat() {
 297                 long ret = bindings.ProbabilisticScoringFeeParameters_get_anti_probing_penalty_msat(this.ptr);
 298                 Reference.reachabilityFence(this);
 299                 return ret;
 300         }
 301
 302         /**
 303          * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
 304          * channel's capacity, (ie. htlc_maximum_msat >= 0.5 * channel_capacity) which makes us
 305          * prefer nodes with a smaller `htlc_maximum_msat`. We treat such nodes preferentially
 306          * as this makes balance discovery attacks harder to execute, thereby creating an incentive
 307          * to restrict `htlc_maximum_msat` and improve privacy.
 308          *
 309          * Default value: 250 msat
 310          */
 311         public void set_anti_probing_penalty_msat(long val) {
 312                 bindings.ProbabilisticScoringFeeParameters_set_anti_probing_penalty_msat(this.ptr, val);
 313                 Reference.reachabilityFence(this);
 314                 Reference.reachabilityFence(val);
 315         }
 316
 317         /**
 318          * This penalty is applied when the amount we're attempting to send over a channel exceeds our
 319          * current estimate of the channel's available liquidity.
 320          *
 321          * Note that in this case all other penalties, including the
 322          * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based
 323          * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if
 324          * applicable, are still included in the overall penalty.
 325          *
 326          * If you wish to avoid creating paths with such channels entirely, setting this to a value of
 327          * `u64::max_value()` will guarantee that.
 328          *
 329          * Default value: 1_0000_0000_000 msat (1 Bitcoin)
 330          *
 331          * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
 332          * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
 333          * [`base_penalty_msat`]: Self::base_penalty_msat
 334          * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat
 335          */
 336         public long get_considered_impossible_penalty_msat() {
 337                 long ret = bindings.ProbabilisticScoringFeeParameters_get_considered_impossible_penalty_msat(this.ptr);
 338                 Reference.reachabilityFence(this);
 339                 return ret;
 340         }
 341
 342         /**
 343          * This penalty is applied when the amount we're attempting to send over a channel exceeds our
 344          * current estimate of the channel's available liquidity.
 345          *
 346          * Note that in this case all other penalties, including the
 347          * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based
 348          * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if
 349          * applicable, are still included in the overall penalty.
 350          *
 351          * If you wish to avoid creating paths with such channels entirely, setting this to a value of
 352          * `u64::max_value()` will guarantee that.
 353          *
 354          * Default value: 1_0000_0000_000 msat (1 Bitcoin)
 355          *
 356          * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
 357          * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat
 358          * [`base_penalty_msat`]: Self::base_penalty_msat
 359          * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat
 360          */
 361         public void set_considered_impossible_penalty_msat(long val) {
 362                 bindings.ProbabilisticScoringFeeParameters_set_considered_impossible_penalty_msat(this.ptr, val);
 363                 Reference.reachabilityFence(this);
 364                 Reference.reachabilityFence(val);
 365         }
 366
 367         long clone_ptr() {
 368                 long ret = bindings.ProbabilisticScoringFeeParameters_clone_ptr(this.ptr);
 369                 Reference.reachabilityFence(this);
 370                 return ret;
 371         }
 372
 373         /**
 374          * Creates a copy of the ProbabilisticScoringFeeParameters
 375          */
 376         public ProbabilisticScoringFeeParameters clone() {
 377                 long ret = bindings.ProbabilisticScoringFeeParameters_clone(this.ptr);
 378                 Reference.reachabilityFence(this);
 379                 if (ret >= 0 && ret <= 4096) { return null; }
 380                 org.ldk.structs.ProbabilisticScoringFeeParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringFeeParameters(null, ret); }
 381                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 382                 return ret_hu_conv;
 383         }
 384
 385         /**
 386          * Creates a "default" ProbabilisticScoringFeeParameters. See struct and individual field documentaiton for details on which values are used.
 387          */
 388         public static ProbabilisticScoringFeeParameters with_default() {
 389                 long ret = bindings.ProbabilisticScoringFeeParameters_default();
 390                 if (ret >= 0 && ret <= 4096) { return null; }
 391                 org.ldk.structs.ProbabilisticScoringFeeParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringFeeParameters(null, ret); }
 392                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); };
 393                 return ret_hu_conv;
 394         }
 395
 396         /**
 397          * Marks the node with the given `node_id` as banned,
 398          * i.e it will be avoided during path finding.
 399          */
 400         public void add_banned(org.ldk.structs.NodeId node_id) {
 401                 bindings.ProbabilisticScoringFeeParameters_add_banned(this.ptr, node_id == null ? 0 : node_id.ptr);
 402                 Reference.reachabilityFence(this);
 403                 Reference.reachabilityFence(node_id);
 404                 if (this != null) { this.ptrs_to.add(node_id); };
 405         }
 406
 407         /**
 408          * Marks all nodes in the given list as banned, i.e.,
 409          * they will be avoided during path finding.
 410          */
 411         public void add_banned_from_list(NodeId[] node_ids) {
 412                 bindings.ProbabilisticScoringFeeParameters_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);
 413                 Reference.reachabilityFence(this);
 414                 Reference.reachabilityFence(node_ids);
 415                 for (NodeId node_ids_conv_8: node_ids) { if (this != null) { this.ptrs_to.add(node_ids_conv_8); }; };
 416         }
 417
 418         /**
 419          * Removes the node with the given `node_id` from the list of nodes to avoid.
 420          */
 421         public void remove_banned(org.ldk.structs.NodeId node_id) {
 422                 bindings.ProbabilisticScoringFeeParameters_remove_banned(this.ptr, node_id == null ? 0 : node_id.ptr);
 423                 Reference.reachabilityFence(this);
 424                 Reference.reachabilityFence(node_id);
 425                 if (this != null) { this.ptrs_to.add(node_id); };
 426         }
 427
 428         /**
 429          * Sets a manual penalty for the given node.
 430          */
 431         public void set_manual_penalty(org.ldk.structs.NodeId node_id, long penalty) {
 432                 bindings.ProbabilisticScoringFeeParameters_set_manual_penalty(this.ptr, node_id == null ? 0 : node_id.ptr, penalty);
 433                 Reference.reachabilityFence(this);
 434                 Reference.reachabilityFence(node_id);
 435                 Reference.reachabilityFence(penalty);
 436                 if (this != null) { this.ptrs_to.add(node_id); };
 437         }
 438
 439         /**
 440          * Removes the node with the given `node_id` from the list of manual penalties.
 441          */
 442         public void remove_manual_penalty(org.ldk.structs.NodeId node_id) {
 443                 bindings.ProbabilisticScoringFeeParameters_remove_manual_penalty(this.ptr, node_id == null ? 0 : node_id.ptr);
 444                 Reference.reachabilityFence(this);
 445                 Reference.reachabilityFence(node_id);
 446                 if (this != null) { this.ptrs_to.add(node_id); };
 447         }
 448
 449         /**
 450          * Clears the list of manual penalties that are applied during path finding.
 451          */
 452         public void clear_manual_penalties() {
 453                 bindings.ProbabilisticScoringFeeParameters_clear_manual_penalties(this.ptr);
 454                 Reference.reachabilityFence(this);
 455         }
 456
 457 }