Skip to content

feat(scoring): add public diagnostics for ChannelLiquidities#2

Draft
ovitrif wants to merge 1 commit intomainfrom
feat/scorer-diagnostics
Draft

feat(scoring): add public diagnostics for ChannelLiquidities#2
ovitrif wants to merge 1 commit intomainfrom
feat/scorer-diagnostics

Conversation

@ovitrif
Copy link
Copy Markdown
Collaborator

@ovitrif ovitrif commented Apr 28, 2026

This PR adds a public read-only diagnostic surface to ChannelLiquidities and ProbabilisticScorer so external tools can inspect serialized scorer files without needing access to the private liquidity_history internals.

Depends on:

Summary

  • New pub struct ChannelLiquidityDiagnostic exposing per-SCID liquidity offsets, last-updated timestamps, and the raw 32-bucket weight arrays from HistoricalLiquidityTracker plus its total_valid_points_tracked summary.
  • New methods ChannelLiquidities::diagnostics() and ProbabilisticScorer::diagnostics() returning Vec<ChannelLiquidityDiagnostic>, sorted by SCID for deterministic output.
  • Two small pub(super) accessors (HistoricalBucketRangeTracker::buckets, HistoricalLiquidityTracker::total_valid_points_tracked) so the diagnostic function can read bucket state without exposing the internal types.
  • No behavior change: the existing scoring path is untouched.

Directional resolution (turning the non-directional offsets into per-direction sat values) is intentionally left out of this surface — that requires a NetworkGraph for capacity and node-id ordering and is best done by the consumer.

The motivation is a separate scorer-inspect CLI (linked above) that reads .bin files served at URLs like scores.zeusln.com/latest.bin or produced locally by Node::export_pathfinding_scores, and emits text/CSV/JSON diagnostics. With these accessors that consumer can be a thin shim instead of duplicating internal types.

Test plan

  • New unit test diagnostics_distinguishes_history_populated_from_empty builds a scorer with one probe-driven entry and one empty entry, calls diagnostics() on both ChannelLiquidities and ProbabilisticScorer, and verifies the populated/empty distinction is preserved through a Writeable -> Readable round-trip on both wire shapes.
  • cargo test -p lightning --lib routing::scoring — all 33 scoring tests pass.

🤖 Generated with Claude Code

Adds a read-only diagnostic surface so external tools can inspect the
contents of a serialized ProbabilisticScorer / ChannelLiquidities file
without needing access to the private liquidity_history internals.

ChannelLiquidities exposes one ChannelLiquidityDiagnostic per stored
SCID, sorted for deterministic output. Each diagnostic surfaces the
non-directional liquidity offsets, last-updated timestamps, and the raw
32-bucket weight arrays from HistoricalLiquidityTracker plus its
total_valid_points_tracked summary - the LDK-internal scalar that
weighs the historical bucket distribution. Directional resolution is
deliberately not part of this surface, since it requires a NetworkGraph
for capacity and node-id ordering.

ProbabilisticScorer::diagnostics() delegates to ChannelLiquidities and
exists as a convenience for callers that hold a live scorer instance.

The accompanying test exercises both the populated and empty-history
paths via a probe-style failure, and confirms that diagnostics survive
a Writeable -> Readable round-trip on both ProbabilisticScorer and the
served ChannelLiquidities wire format.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant