- * 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`].