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

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