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