X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=src%2Fmain%2Fjava%2Forg%2Fldk%2Fstructs%2FProbabilisticScoringParameters.java;h=3617ce0d6f63406d14e1a6ce25f693c9c3562051;hb=3c60e0fd0da579be9932801c1be2b32014c944a5;hp=96e66ac929b3c9062441c962483271a0aab5ff81;hpb=2a8741cb87eb2b82381a6220a98f80f741147837;p=ldk-java diff --git a/src/main/java/org/ldk/structs/ProbabilisticScoringParameters.java b/src/main/java/org/ldk/structs/ProbabilisticScoringParameters.java index 96e66ac9..3617ce0d 100644 --- a/src/main/java/org/ldk/structs/ProbabilisticScoringParameters.java +++ b/src/main/java/org/ldk/structs/ProbabilisticScoringParameters.java @@ -13,6 +13,9 @@ import javax.annotation.Nullable; * * Used to configure base, liquidity, and amount penalties, the sum of which comprises the channel * penalty (i.e., the amount in msats willing to be paid to avoid routing through the channel). + * + * The penalty applied to any channel by the [`ProbabilisticScorer`] is the sum of each of the + * parameters here. */ @SuppressWarnings("unchecked") // We correctly assign various generic arrays public class ProbabilisticScoringParameters extends CommonBase { @@ -45,6 +48,46 @@ public class ProbabilisticScoringParameters extends CommonBase { Reference.reachabilityFence(val); } + /** + * A multiplier used with the payment amount to calculate a fixed penalty applied to each + * channel, in excess of the [`base_penalty_msat`]. + * + * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e., + * fees plus penalty) for large payments. The penalty is computed as the product of this + * multiplier and `2^30`ths of the payment amount. + * + * ie `base_penalty_amount_multiplier_msat * amount_msat / 2^30` + * + * Default value: 8,192 msat + * + * [`base_penalty_msat`]: Self::base_penalty_msat + */ + public long get_base_penalty_amount_multiplier_msat() { + long ret = bindings.ProbabilisticScoringParameters_get_base_penalty_amount_multiplier_msat(this.ptr); + Reference.reachabilityFence(this); + return ret; + } + + /** + * A multiplier used with the payment amount to calculate a fixed penalty applied to each + * channel, in excess of the [`base_penalty_msat`]. + * + * The purpose of the amount penalty is to avoid having fees dominate the channel cost (i.e., + * fees plus penalty) for large payments. The penalty is computed as the product of this + * multiplier and `2^30`ths of the payment amount. + * + * ie `base_penalty_amount_multiplier_msat * amount_msat / 2^30` + * + * Default value: 8,192 msat + * + * [`base_penalty_msat`]: Self::base_penalty_msat + */ + public void set_base_penalty_amount_multiplier_msat(long val) { + bindings.ProbabilisticScoringParameters_set_base_penalty_amount_multiplier_msat(this.ptr, val); + Reference.reachabilityFence(this); + Reference.reachabilityFence(val); + } + /** * A multiplier used in conjunction with the negative `log10` of the channel's success * probability for a payment to determine the liquidity penalty. @@ -138,7 +181,7 @@ public class ProbabilisticScoringParameters extends CommonBase { * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the * success probability. * - * `-log10(success_probability) * amount_penalty_multiplier_msat * amount_msat / 2^20` + * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20` * * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of * the amount will result in a penalty of the multiplier. And, as the success probability @@ -148,8 +191,8 @@ public class ProbabilisticScoringParameters extends CommonBase { * * Default value: 256 msat */ - public long get_amount_penalty_multiplier_msat() { - long ret = bindings.ProbabilisticScoringParameters_get_amount_penalty_multiplier_msat(this.ptr); + public long get_liquidity_penalty_amount_multiplier_msat() { + long ret = bindings.ProbabilisticScoringParameters_get_liquidity_penalty_amount_multiplier_msat(this.ptr); Reference.reachabilityFence(this); return ret; } @@ -163,7 +206,7 @@ public class ProbabilisticScoringParameters extends CommonBase { * multiplier and `2^20`ths of the payment amount, weighted by the negative `log10` of the * success probability. * - * `-log10(success_probability) * amount_penalty_multiplier_msat * amount_msat / 2^20` + * `-log10(success_probability) * liquidity_penalty_amount_multiplier_msat * amount_msat / 2^20` * * In practice, this means for 0.1 success probability (`-log10(0.1) == 1`) each `2^20`th of * the amount will result in a penalty of the multiplier. And, as the success probability @@ -173,25 +216,88 @@ public class ProbabilisticScoringParameters extends CommonBase { * * Default value: 256 msat */ - public void set_amount_penalty_multiplier_msat(long val) { - bindings.ProbabilisticScoringParameters_set_amount_penalty_multiplier_msat(this.ptr, val); + public void set_liquidity_penalty_amount_multiplier_msat(long val) { + bindings.ProbabilisticScoringParameters_set_liquidity_penalty_amount_multiplier_msat(this.ptr, val); Reference.reachabilityFence(this); Reference.reachabilityFence(val); } /** - * Constructs a new ProbabilisticScoringParameters given each field + * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the + * channel's capacity, which makes us prefer nodes with a smaller `htlc_maximum_msat`. We + * treat such nodes preferentially as this makes balance discovery attacks harder to execute, + * thereby creating an incentive to restrict `htlc_maximum_msat` and improve privacy. + * + * Default value: 250 msat */ - 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) { - long ret = bindings.ProbabilisticScoringParameters_new(base_penalty_msat_arg, liquidity_penalty_multiplier_msat_arg, liquidity_offset_half_life_arg, amount_penalty_multiplier_msat_arg); - Reference.reachabilityFence(base_penalty_msat_arg); - Reference.reachabilityFence(liquidity_penalty_multiplier_msat_arg); - Reference.reachabilityFence(liquidity_offset_half_life_arg); - Reference.reachabilityFence(amount_penalty_multiplier_msat_arg); - if (ret >= 0 && ret <= 4096) { return null; } - org.ldk.structs.ProbabilisticScoringParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringParameters(null, ret); } - ret_hu_conv.ptrs_to.add(ret_hu_conv); - return ret_hu_conv; + public long get_anti_probing_penalty_msat() { + long ret = bindings.ProbabilisticScoringParameters_get_anti_probing_penalty_msat(this.ptr); + Reference.reachabilityFence(this); + return ret; + } + + /** + * This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the + * channel's capacity, which makes us prefer nodes with a smaller `htlc_maximum_msat`. We + * treat such nodes preferentially as this makes balance discovery attacks harder to execute, + * thereby creating an incentive to restrict `htlc_maximum_msat` and improve privacy. + * + * Default value: 250 msat + */ + public void set_anti_probing_penalty_msat(long val) { + bindings.ProbabilisticScoringParameters_set_anti_probing_penalty_msat(this.ptr, val); + Reference.reachabilityFence(this); + Reference.reachabilityFence(val); + } + + /** + * This penalty is applied when the amount we're attempting to send over a channel exceeds our + * current estimate of the channel's available liquidity. + * + * Note that in this case all other penalties, including the + * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based + * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if + * applicable, are still included in the overall penalty. + * + * If you wish to avoid creating paths with such channels entirely, setting this to a value of + * `u64::max_value()` will guarantee that. + * + * Default value: 1_0000_0000_000 msat (1 Bitcoin) + * + * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat + * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat + * [`base_penalty_msat`]: Self::base_penalty_msat + * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat + */ + public long get_considered_impossible_penalty_msat() { + long ret = bindings.ProbabilisticScoringParameters_get_considered_impossible_penalty_msat(this.ptr); + Reference.reachabilityFence(this); + return ret; + } + + /** + * This penalty is applied when the amount we're attempting to send over a channel exceeds our + * current estimate of the channel's available liquidity. + * + * Note that in this case all other penalties, including the + * [`liquidity_penalty_multiplier_msat`] and [`liquidity_penalty_amount_multiplier_msat`]-based + * penalties, as well as the [`base_penalty_msat`] and the [`anti_probing_penalty_msat`], if + * applicable, are still included in the overall penalty. + * + * If you wish to avoid creating paths with such channels entirely, setting this to a value of + * `u64::max_value()` will guarantee that. + * + * Default value: 1_0000_0000_000 msat (1 Bitcoin) + * + * [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat + * [`liquidity_penalty_amount_multiplier_msat`]: Self::liquidity_penalty_amount_multiplier_msat + * [`base_penalty_msat`]: Self::base_penalty_msat + * [`anti_probing_penalty_msat`]: Self::anti_probing_penalty_msat + */ + public void set_considered_impossible_penalty_msat(long val) { + bindings.ProbabilisticScoringParameters_set_considered_impossible_penalty_msat(this.ptr, val); + Reference.reachabilityFence(this); + Reference.reachabilityFence(val); } long clone_ptr() { @@ -208,10 +314,21 @@ public class ProbabilisticScoringParameters extends CommonBase { Reference.reachabilityFence(this); if (ret >= 0 && ret <= 4096) { return null; } org.ldk.structs.ProbabilisticScoringParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringParameters(null, ret); } - ret_hu_conv.ptrs_to.add(this); + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); }; return ret_hu_conv; } + /** + * Marks all nodes in the given list as banned, i.e., + * they will be avoided during path finding. + */ + public void add_banned_from_list(NodeId[] node_ids) { + bindings.ProbabilisticScoringParameters_add_banned_from_list(this.ptr, node_ids != null ? Arrays.stream(node_ids).mapToLong(node_ids_conv_8 -> node_ids_conv_8 == null ? 0 : node_ids_conv_8.ptr).toArray() : null); + Reference.reachabilityFence(this); + Reference.reachabilityFence(node_ids); + for (NodeId node_ids_conv_8: node_ids) { if (this != null) { this.ptrs_to.add(node_ids_conv_8); }; }; + } + /** * Creates a "default" ProbabilisticScoringParameters. See struct and individual field documentaiton for details on which values are used. */ @@ -219,7 +336,7 @@ public class ProbabilisticScoringParameters extends CommonBase { long ret = bindings.ProbabilisticScoringParameters_default(); if (ret >= 0 && ret <= 4096) { return null; } org.ldk.structs.ProbabilisticScoringParameters ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScoringParameters(null, ret); } - ret_hu_conv.ptrs_to.add(ret_hu_conv); + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); }; return ret_hu_conv; }