X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=c_sharp%2Fsrc%2Forg%2Fldk%2Fstructs%2FProbabilisticScorer.cs;h=2bbdf38ffbdb262cecfed496ded678c010845980;hb=8de7213fbf663ff60322896282dad51e8ab2f001;hp=c14395ee5735e28925a1f5e7dbe15726a59a4762;hpb=afc50e5d491a11364849383b75a8f939df703bac;p=ldk-java diff --git a/c_sharp/src/org/ldk/structs/ProbabilisticScorer.cs b/c_sharp/src/org/ldk/structs/ProbabilisticScorer.cs index c14395ee..2bbdf38f 100644 --- a/c_sharp/src/org/ldk/structs/ProbabilisticScorer.cs +++ b/c_sharp/src/org/ldk/structs/ProbabilisticScorer.cs @@ -7,7 +7,7 @@ namespace org { namespace ldk { namespace structs { /** - * [`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. @@ -17,7 +17,7 @@ namespace org { namespace ldk { namespace structs { * 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 @@ -99,34 +99,89 @@ public class ProbabilisticScorer : CommonBase { * 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 8 buckets. The first set describes the octiles for lower-bound - * liquidity estimates, the second set describes the octiles for upper-bound liquidity - * estimates. Each bucket describes the relative frequency at which we've seen a liquidity - * bound in the octile 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. + * 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 octile - * relative to the channel's total capacity is calculated by dividing that bucket's value with - * the total of all buckets for the given bound. + * 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, a value of `[0, 0, 0, 0, 0, 0, 32]` indicates that we believe the probability - * of a bound being in the top octile to be 100%, and have never (recently) seen it in any - * other octiles. A value of `[31, 0, 0, 0, 0, 0, 0, 32]` indicates we've seen the bound being - * both in the top and bottom octile, and roughly with similar (recent) frequency. + * 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(([0; 8], [0; 8]))`. + * `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 Option_C2Tuple_EightU16sEightU16sZZ historical_estimated_channel_liquidity_probabilities(long scid, org.ldk.structs.NodeId target) { + 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); GC.KeepAlive(this); GC.KeepAlive(scid); GC.KeepAlive(target); if (ret >= 0 && ret <= 4096) { return null; } - org.ldk.structs.Option_C2Tuple_EightU16sEightU16sZZ ret_hu_conv = org.ldk.structs.Option_C2Tuple_EightU16sEightU16sZZ.constr_from_ptr(ret); + 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.AddLast(this); }; + if (this != null) { this.ptrs_to.AddLast(target); }; + return ret_hu_conv; + } + + /** + * 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 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); + GC.KeepAlive(this); + GC.KeepAlive(scid); + GC.KeepAlive(target); + GC.KeepAlive(amount_msat); + GC.KeepAlive(_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.AddLast(this); }; if (this != null) { this.ptrs_to.AddLast(target); }; + if (this != null) { this.ptrs_to.AddLast(_params); }; + return ret_hu_conv; + } + + /** + * 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 ScoreLookUp as_ScoreLookUp() { + long ret = bindings.ProbabilisticScorer_as_ScoreLookUp(this.ptr); + GC.KeepAlive(this); + 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.AddLast(this); }; + return ret_hu_conv; + } + + /** + * 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 ScoreUpdate as_ScoreUpdate() { + long ret = bindings.ProbabilisticScorer_as_ScoreUpdate(this.ptr); + GC.KeepAlive(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.AddLast(this); }; return ret_hu_conv; } @@ -147,16 +202,18 @@ public class ProbabilisticScorer : CommonBase { * Serialize the ProbabilisticScorer object into a byte array which can be read by ProbabilisticScorer_read */ public byte[] write() { - byte[] ret = bindings.ProbabilisticScorer_write(this.ptr); + long ret = bindings.ProbabilisticScorer_write(this.ptr); GC.KeepAlive(this); - return ret; + if (ret >= 0 && ret <= 4096) { return null; } + byte[] ret_conv = InternalUtils.decodeUint8Array(ret); + return ret_conv; } /** * Read a ProbabilisticScorer from a byte array, created by ProbabilisticScorer_write */ 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); + long ret = bindings.ProbabilisticScorer_read(InternalUtils.encodeUint8Array(ser), arg_a == null ? 0 : arg_a.ptr, arg_b == null ? 0 : arg_b.ptr, arg_c.ptr); GC.KeepAlive(ser); GC.KeepAlive(arg_a); GC.KeepAlive(arg_b);