X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=src%2Fmain%2Fjava%2Forg%2Fldk%2Fstructs%2FProbabilisticScorer.java;h=b317cd238390736d48a81c284551e8443fa8201e;hb=07d5d868dfe064aadb28a7f7ca6002c16be9723d;hp=71658b3f3f14e3c00957d7710f6b58c717a9ceb7;hpb=5e9de82b3a7712a41189756d9d16d946142b2ac5;p=ldk-java diff --git a/src/main/java/org/ldk/structs/ProbabilisticScorer.java b/src/main/java/org/ldk/structs/ProbabilisticScorer.java index 71658b3f..b317cd23 100644 --- a/src/main/java/org/ldk/structs/ProbabilisticScorer.java +++ b/src/main/java/org/ldk/structs/ProbabilisticScorer.java @@ -9,7 +9,7 @@ import javax.annotation.Nullable; /** - * [`Score`] implementation using channel success probability distributions. + * [`ScoreLookUp`] implementation using channel success probability distributions. * * Channels are tracked with upper and lower liquidity bounds - when an HTLC fails at a channel, * we learn that the upper-bound on the available liquidity is lower than the amount of the HTLC. @@ -19,7 +19,7 @@ import javax.annotation.Nullable; * These bounds are then used to determine a success probability using the formula from * Optimally Reliable & Cheap Payment Flows on the Lightning Network* by Rene Pickhardt * and Stefan Richter [[1]] (i.e. `(upper_bound - payment_amount) / (upper_bound - lower_bound)`). - * + * 6762, 1070 * This probability is combined with the [`liquidity_penalty_multiplier_msat`] and * [`liquidity_penalty_amount_multiplier_msat`] parameters to calculate a concrete penalty in * milli-satoshis. The penalties, when added across all hops, have the property of being linear in @@ -40,11 +40,11 @@ import javax.annotation.Nullable; * behavior. * * [1]: https://arxiv.org/abs/2107.05322 - * [`liquidity_penalty_multiplier_msat`]: ProbabilisticScoringParameters::liquidity_penalty_multiplier_msat - * [`liquidity_penalty_amount_multiplier_msat`]: ProbabilisticScoringParameters::liquidity_penalty_amount_multiplier_msat - * [`liquidity_offset_half_life`]: ProbabilisticScoringParameters::liquidity_offset_half_life - * [`historical_liquidity_penalty_multiplier_msat`]: ProbabilisticScoringParameters::historical_liquidity_penalty_multiplier_msat - * [`historical_liquidity_penalty_amount_multiplier_msat`]: ProbabilisticScoringParameters::historical_liquidity_penalty_amount_multiplier_msat + * [`liquidity_penalty_multiplier_msat`]: ProbabilisticScoringFeeParameters::liquidity_penalty_multiplier_msat + * [`liquidity_penalty_amount_multiplier_msat`]: ProbabilisticScoringFeeParameters::liquidity_penalty_amount_multiplier_msat + * [`liquidity_offset_half_life`]: ProbabilisticScoringDecayParameters::liquidity_offset_half_life + * [`historical_liquidity_penalty_multiplier_msat`]: ProbabilisticScoringFeeParameters::historical_liquidity_penalty_multiplier_msat + * [`historical_liquidity_penalty_amount_multiplier_msat`]: ProbabilisticScoringFeeParameters::historical_liquidity_penalty_amount_multiplier_msat */ @SuppressWarnings("unchecked") // We correctly assign various generic arrays public class ProbabilisticScorer extends CommonBase { @@ -59,15 +59,15 @@ public class ProbabilisticScorer extends CommonBase { * Creates a new scorer using the given scoring parameters for sending payments from a node * through a network graph. */ - public static ProbabilisticScorer of(ProbabilisticScoringParameters params, NetworkGraph network_graph, Logger logger) { - long ret = bindings.ProbabilisticScorer_new(params == null ? 0 : params.ptr, network_graph == null ? 0 : network_graph.ptr, logger == null ? 0 : logger.ptr); - Reference.reachabilityFence(params); + public static ProbabilisticScorer of(org.ldk.structs.ProbabilisticScoringDecayParameters decay_params, org.ldk.structs.NetworkGraph network_graph, org.ldk.structs.Logger logger) { + long ret = bindings.ProbabilisticScorer_new(decay_params == null ? 0 : decay_params.ptr, network_graph == null ? 0 : network_graph.ptr, logger.ptr); + Reference.reachabilityFence(decay_params); Reference.reachabilityFence(network_graph); Reference.reachabilityFence(logger); if (ret >= 0 && ret <= 4096) { return null; } org.ldk.structs.ProbabilisticScorer ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.ProbabilisticScorer(null, ret); } if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); }; - if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(params); }; + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(decay_params); }; if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(network_graph); }; if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(logger); }; return ret_hu_conv; @@ -88,7 +88,7 @@ public class ProbabilisticScorer extends CommonBase { * Query the estimated minimum and maximum liquidity available for sending a payment over the * channel with `scid` towards the given `target` node. */ - public Option_C2Tuple_u64u64ZZ estimated_channel_liquidity_range(long scid, NodeId target) { + public Option_C2Tuple_u64u64ZZ estimated_channel_liquidity_range(long scid, org.ldk.structs.NodeId target) { long ret = bindings.ProbabilisticScorer_estimated_channel_liquidity_range(this.ptr, scid, target == null ? 0 : target.ptr); Reference.reachabilityFence(this); Reference.reachabilityFence(scid); @@ -101,53 +101,93 @@ public class ProbabilisticScorer extends CommonBase { } /** - * Marks the node with the given `node_id` as banned, i.e., - * it will be avoided during path finding. - */ - public void add_banned(NodeId node_id) { - bindings.ProbabilisticScorer_add_banned(this.ptr, node_id == null ? 0 : node_id.ptr); - Reference.reachabilityFence(this); - Reference.reachabilityFence(node_id); - if (this != null) { this.ptrs_to.add(node_id); }; - } - - /** - * Removes the node with the given `node_id` from the list of nodes to avoid. + * Query the historical estimated minimum and maximum liquidity available for sending a + * payment over the channel with `scid` towards the given `target` node. + * + * Returns two sets of 32 buckets. The first set describes the lower-bound liquidity history, + * the second set describes the upper-bound liquidity history. Each bucket describes the + * relative frequency at which we've seen a liquidity bound in the bucket's range relative to + * the channel's total capacity, on an arbitrary scale. Because the values are slowly decayed, + * more recent data points are weighted more heavily than older datapoints. + * + * Note that the range of each bucket varies by its location to provide more granular results + * at the edges of a channel's capacity, where it is more likely to sit. + * + * When scoring, the estimated probability that an upper-/lower-bound lies in a given bucket + * is calculated by dividing that bucket's value with the total value of all buckets. + * + * For example, using a lower bucket count for illustrative purposes, a value of + * `[0, 0, 0, ..., 0, 32]` indicates that we believe the probability of a bound being very + * close to the channel's capacity to be 100%, and have never (recently) seen it in any other + * bucket. A value of `[31, 0, 0, ..., 0, 0, 32]` indicates we've seen the bound being both + * in the top and bottom bucket, and roughly with similar (recent) frequency. + * + * Because the datapoints are decayed slowly over time, values will eventually return to + * `Some(([1; 32], [1; 32]))` and then to `None` once no datapoints remain. + * + * In order to fetch a single success probability from the buckets provided here, as used in + * the scoring model, see [`Self::historical_estimated_payment_success_probability`]. */ - public void remove_banned(NodeId node_id) { - bindings.ProbabilisticScorer_remove_banned(this.ptr, node_id == null ? 0 : node_id.ptr); + public Option_C2Tuple_ThirtyTwoU16sThirtyTwoU16sZZ historical_estimated_channel_liquidity_probabilities(long scid, org.ldk.structs.NodeId target) { + long ret = bindings.ProbabilisticScorer_historical_estimated_channel_liquidity_probabilities(this.ptr, scid, target == null ? 0 : target.ptr); Reference.reachabilityFence(this); - Reference.reachabilityFence(node_id); - if (this != null) { this.ptrs_to.add(node_id); }; + Reference.reachabilityFence(scid); + Reference.reachabilityFence(target); + if (ret >= 0 && ret <= 4096) { return null; } + org.ldk.structs.Option_C2Tuple_ThirtyTwoU16sThirtyTwoU16sZZ ret_hu_conv = org.ldk.structs.Option_C2Tuple_ThirtyTwoU16sThirtyTwoU16sZZ.constr_from_ptr(ret); + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); }; + if (this != null) { this.ptrs_to.add(target); }; + return ret_hu_conv; } /** - * Sets a manual penalty for the given node. + * Query the probability of payment success sending the given `amount_msat` over the channel + * with `scid` towards the given `target` node, based on the historical estimated liquidity + * bounds. + * + * These are the same bounds as returned by + * [`Self::historical_estimated_channel_liquidity_probabilities`] (but not those returned by + * [`Self::estimated_channel_liquidity_range`]). */ - public void set_manual_penalty(NodeId node_id, long penalty) { - bindings.ProbabilisticScorer_set_manual_penalty(this.ptr, node_id == null ? 0 : node_id.ptr, penalty); + public Option_f64Z historical_estimated_payment_success_probability(long scid, org.ldk.structs.NodeId target, long amount_msat, org.ldk.structs.ProbabilisticScoringFeeParameters params) { + long ret = bindings.ProbabilisticScorer_historical_estimated_payment_success_probability(this.ptr, scid, target == null ? 0 : target.ptr, amount_msat, params == null ? 0 : params.ptr); Reference.reachabilityFence(this); - Reference.reachabilityFence(node_id); - Reference.reachabilityFence(penalty); - if (this != null) { this.ptrs_to.add(node_id); }; + Reference.reachabilityFence(scid); + Reference.reachabilityFence(target); + Reference.reachabilityFence(amount_msat); + Reference.reachabilityFence(params); + if (ret >= 0 && ret <= 4096) { return null; } + org.ldk.structs.Option_f64Z ret_hu_conv = org.ldk.structs.Option_f64Z.constr_from_ptr(ret); + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); }; + if (this != null) { this.ptrs_to.add(target); }; + if (this != null) { this.ptrs_to.add(params); }; + return ret_hu_conv; } /** - * Removes the node with the given `node_id` from the list of manual penalties. + * Constructs a new ScoreLookUp which calls the relevant methods on this_arg. + * This copies the `inner` pointer in this_arg and thus the returned ScoreLookUp must be freed before this_arg is */ - public void remove_manual_penalty(NodeId node_id) { - bindings.ProbabilisticScorer_remove_manual_penalty(this.ptr, node_id == null ? 0 : node_id.ptr); + public ScoreLookUp as_ScoreLookUp() { + long ret = bindings.ProbabilisticScorer_as_ScoreLookUp(this.ptr); Reference.reachabilityFence(this); - Reference.reachabilityFence(node_id); - if (this != null) { this.ptrs_to.add(node_id); }; + if (ret >= 0 && ret <= 4096) { return null; } + ScoreLookUp ret_hu_conv = new ScoreLookUp(null, ret); + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); }; + return ret_hu_conv; } /** - * Clears the list of manual penalties that are applied during path finding. + * Constructs a new ScoreUpdate which calls the relevant methods on this_arg. + * This copies the `inner` pointer in this_arg and thus the returned ScoreUpdate must be freed before this_arg is */ - public void clear_manual_penalties() { - bindings.ProbabilisticScorer_clear_manual_penalties(this.ptr); + public ScoreUpdate as_ScoreUpdate() { + long ret = bindings.ProbabilisticScorer_as_ScoreUpdate(this.ptr); Reference.reachabilityFence(this); + if (ret >= 0 && ret <= 4096) { return null; } + ScoreUpdate ret_hu_conv = new ScoreUpdate(null, ret); + if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); }; + return ret_hu_conv; } /** @@ -175,8 +215,8 @@ public class ProbabilisticScorer extends CommonBase { /** * Read a ProbabilisticScorer from a byte array, created by ProbabilisticScorer_write */ - public static Result_ProbabilisticScorerDecodeErrorZ read(byte[] ser, ProbabilisticScoringParameters arg_a, NetworkGraph arg_b, Logger arg_c) { - long ret = bindings.ProbabilisticScorer_read(ser, arg_a == null ? 0 : arg_a.ptr, arg_b == null ? 0 : arg_b.ptr, arg_c == null ? 0 : arg_c.ptr); + public static Result_ProbabilisticScorerDecodeErrorZ read(byte[] ser, org.ldk.structs.ProbabilisticScoringDecayParameters arg_a, org.ldk.structs.NetworkGraph arg_b, org.ldk.structs.Logger arg_c) { + long ret = bindings.ProbabilisticScorer_read(ser, arg_a == null ? 0 : arg_a.ptr, arg_b == null ? 0 : arg_b.ptr, arg_c.ptr); Reference.reachabilityFence(ser); Reference.reachabilityFence(arg_a); Reference.reachabilityFence(arg_b);