_ 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 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
  18 public class ProbabilisticScoringParameters extends CommonBase {
  19         ProbabilisticScoringParameters(Object _dummy, long ptr) { super(ptr); }
  20         @Override @SuppressWarnings("deprecation")
  21         protected void finalize() throws Throwable {
  22                 super.finalize();
  23                 if (ptr != 0) { bindings.ProbabilisticScoringParameters_free(ptr); }
  24         }
  25
  26         /**
  27          * A fixed penalty in msats to apply to each channel.
  28          *
  29          * Default value: 500 msat
  30          */
  31         public long get_base_penalty_msat() {
  32                 long ret = bindings.ProbabilisticScoringParameters_get_base_penalty_msat(this.ptr);
  33                 Reference.reachabilityFence(this);
  34                 return ret;
  35         }
  36
  37         /**
  38          * A fixed penalty in msats to apply to each channel.
  39          *
  40          * Default value: 500 msat
  41          */
  42         public void set_base_penalty_msat(long val) {
  43                 bindings.ProbabilisticScoringParameters_set_base_penalty_msat(this.ptr, val);
  44                 Reference.reachabilityFence(this);
  45                 Reference.reachabilityFence(val);
  46         }
  47
  48         /**
  49          * A multiplier used in conjunction with the negative `log10` of the channel's success
  50          * probability for a payment to determine the liquidity penalty.
  51          *
  52          * The penalty is based in part on the knowledge learned from prior successful and unsuccessful
  53          * payments. This knowledge is decayed over time based on [`liquidity_offset_half_life`]. The
  54          * penalty is effectively limited to `2 * liquidity_penalty_multiplier_msat` (corresponding to
  55          * lower bounding the success probability to `0.01`) when the amount falls within the
  56          * uncertainty bounds of the channel liquidity balance. Amounts above the upper bound will
  57          * result in a `u64::max_value` penalty, however.
  58          *
  59          * Default value: 40,000 msat
  60          *
  61          * [`liquidity_offset_half_life`]: Self::liquidity_offset_half_life
  62          */
  63         public long get_liquidity_penalty_multiplier_msat() {
  64                 long ret = bindings.ProbabilisticScoringParameters_get_liquidity_penalty_multiplier_msat(this.ptr);
  65                 Reference.reachabilityFence(this);
  66                 return ret;
  67         }
  68
  69         /**
  70          * A multiplier used in conjunction with the negative `log10` of the channel's success
  71          * probability for a payment to determine the liquidity penalty.
  72          *
  73          * The penalty is based in part on the knowledge learned from prior successful and unsuccessful
  74          * payments. This knowledge is decayed over time based on [`liquidity_offset_half_life`]. The
  75          * penalty is effectively limited to `2 * liquidity_penalty_multiplier_msat` (corresponding to
  76          * lower bounding the success probability to `0.01`) when the amount falls within the
  77          * uncertainty bounds of the channel liquidity balance. Amounts above the upper bound will
  78          * result in a `u64::max_value` penalty, however.
  79          *
  80          * Default value: 40,000 msat
  81          *
  82          * [`liquidity_offset_half_life`]: Self::liquidity_offset_half_life
  83          */
  84         public void set_liquidity_penalty_multiplier_msat(long val) {
  85                 bindings.ProbabilisticScoringParameters_set_liquidity_penalty_multiplier_msat(this.ptr, val);
  86                 Reference.reachabilityFence(this);
  87                 Reference.reachabilityFence(val);
  88         }
  89
  90         /**
  91          * The time required to elapse before any knowledge learned about channel liquidity balances is
  92          * cut in half.
  93          *
  94          * The bounds are defined in terms of offsets and are initially zero. Increasing the offsets
  95          * gives tighter bounds on the channel liquidity balance. Thus, halving the offsets decreases
  96          * the certainty of the channel liquidity balance.
  97          *
  98          * Default value: 1 hour
  99          *
 100          * # Note
 101          *
 102          * When built with the `no-std` feature, time will never elapse. Therefore, the channel
 103          * liquidity knowledge will never decay except when the bounds cross.
 104          */
 105         public long get_liquidity_offset_half_life() {
 106                 long ret = bindings.ProbabilisticScoringParameters_get_liquidity_offset_half_life(this.ptr);
 107                 Reference.reachabilityFence(this);
 108                 return ret;
 109         }
 110
 111         /**
 112          * The time required to elapse before any knowledge learned about channel liquidity balances is
 113          * cut in half.
 114          *
 115          * The bounds are defined in terms of offsets and are initially zero. Increasing the offsets
 116          * gives tighter bounds on the channel liquidity balance. Thus, halving the offsets decreases
 117          * the certainty of the channel liquidity balance.
 118          *
 119          * Default value: 1 hour
 120          *
 121          * # Note
 122          *
 123          * When built with the `no-std` feature, time will never elapse. Therefore, the channel
 124          * liquidity knowledge will never decay except when the bounds cross.
 125          */
 126         public void set_liquidity_offset_half_life(long val) {
 127                 bindings.ProbabilisticScoringParameters_set_liquidity_offset_half_life(this.ptr, val);
 128                 Reference.reachabilityFence(this);
 129                 Reference.reachabilityFence(val);
 130         }
 131
 132         /**
 133          * A multiplier used in conjunction with a payment amount and the negative `log10` of the
 134          * channel's success probability for the payment to determine the amount penalty.
 135          *
 136          * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
 137          * fees plus penalty) for large payments. The penalty is computed as the product of this
 138          * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the
 139          * success probability.
 140          *
 141          * `-log10(success_probability) * amount_penalty_multiplier_msat * amount_msat / 2^20`
 142          *
 143          * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
 144          * the amount will result in a penalty of the multiplier. And, as the success probability
 145          * decreases, the negative `log10` weighting will increase dramatically. For higher success
 146          * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
 147          * fall below `1`.
 148          *
 149          * Default value: 256 msat
 150          */
 151         public long get_amount_penalty_multiplier_msat() {
 152                 long ret = bindings.ProbabilisticScoringParameters_get_amount_penalty_multiplier_msat(this.ptr);
 153                 Reference.reachabilityFence(this);
 154                 return ret;
 155         }
 156
 157         /**
 158          * A multiplier used in conjunction with a payment amount and the negative `log10` of the
 159          * channel's success probability for the payment to determine the amount penalty.
 160          *
 161          * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e.,
 162          * fees plus penalty) for large payments. The penalty is computed as the product of this
 163          * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the
 164          * success probability.
 165          *
 166          * `-log10(success_probability) * amount_penalty_multiplier_msat * amount_msat / 2^20`
 167          *
 168          * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of
 169          * the amount will result in a penalty of the multiplier. And, as the success probability
 170          * decreases, the negative `log10` weighting will increase dramatically. For higher success
 171          * probabilities, the multiplier will have a decreasing effect as the negative `log10` will
 172          * fall below `1`.
 173          *
 174          * Default value: 256 msat
 175          */
 176         public void set_amount_penalty_multiplier_msat(long val) {
 177                 bindings.ProbabilisticScoringParameters_set_amount_penalty_multiplier_msat(this.ptr, val);
 178                 Reference.reachabilityFence(this);
 179                 Reference.reachabilityFence(val);
 180         }
 181
 182         /**
 183          * Constructs a new ProbabilisticScoringParameters given each field
 184          */
 185         public static ProbabilisticScoringParameters of(long base_penalty_msat_arg, long liquidity_penalty_multiplier_msat_arg, long liquidity_offset_half_life_arg, long amount_penalty_multiplier_msat_arg) {
 186                 long ret = bindings.ProbabilisticScoringParameters_new(base_penalty_msat_arg, liquidity_penalty_multiplier_msat_arg, liquidity_offset_half_life_arg, amount_penalty_multiplier_msat_arg);
 187                 Reference.reachabilityFence(base_penalty_msat_arg);
 188                 Reference.reachabilityFence(liquidity_penalty_multiplier_msat_arg);
 189                 Reference.reachabilityFence(liquidity_offset_half_life_arg);
 190                 Reference.reachabilityFence(amount_penalty_multiplier_msat_arg);
 191                 if (ret >= 0 && ret <= 4096) { return null; }
 192                 ProbabilisticScoringParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new ProbabilisticScoringParameters(null, ret); }
 193                 ret_hu_conv.ptrs_to.add(ret_hu_conv);
 194                 return ret_hu_conv;
 195         }
 196
 197         long clone_ptr() {
 198                 long ret = bindings.ProbabilisticScoringParameters_clone_ptr(this.ptr);
 199                 Reference.reachabilityFence(this);
 200                 return ret;
 201         }
 202
 203         /**
 204          * Creates a copy of the ProbabilisticScoringParameters
 205          */
 206         public ProbabilisticScoringParameters clone() {
 207                 long ret = bindings.ProbabilisticScoringParameters_clone(this.ptr);
 208                 Reference.reachabilityFence(this);
 209                 if (ret >= 0 && ret <= 4096) { return null; }
 210                 ProbabilisticScoringParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new ProbabilisticScoringParameters(null, ret); }
 211                 ret_hu_conv.ptrs_to.add(this);
 212                 return ret_hu_conv;
 213         }
 214
 215         /**
 216          * Creates a "default" ProbabilisticScoringParameters. See struct and individual field documentaiton for details on which values are used.
 217          */
 218         public static ProbabilisticScoringParameters with_default() {
 219                 long ret = bindings.ProbabilisticScoringParameters_default();
 220                 if (ret >= 0 && ret <= 4096) { return null; }
 221                 ProbabilisticScoringParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new ProbabilisticScoringParameters(null, ret); }
 222                 ret_hu_conv.ptrs_to.add(ret_hu_conv);
 223                 return ret_hu_conv;
 224         }
 225
 226 }