Add probe path selection for background liquidity probing

[151henry151]

PR description updated (2026-06-08) to match review feedback in b17afa6b4.

Issue #2720 originally suggested a wrapper ScoreLookUp around ProbabilisticScorer. #3422 already added probing_diversity_penalty_msat for the same purpose; this PR wires that field into background probe path selection without a redundant wrapper or separate router API.

Background prober loops (random target/amount on a timer) remain userland / separate-crate per maintainer consensus.

This adds RouteParameters::from_probe_target (uncapped routing fees and a runtime-only background_probe flag), ProbabilisticScoringFeeParameters::for_probing(amount_msat) (sets a diversity penalty when none is configured), and ScoreLookUp::params_for_probe (ProbabilisticScorer calls for_probing; DefaultRouter::find_route calls it automatically when background_probe is set). Background probes route through the existing find_route path — there is no separate find_probe_route on Router. ChannelManager::send_probe_to_node is the simple find-and-send entry point. Manual callers using the free find_route should call scorer.params_for_probe(...) themselves. Preflight probe sending shares an internal trim_unannounced_probe_last_hops helper; behavior is unchanged. Router and functional tests verify probe path diversity across repeated probes and end-to-end probe sending.

For ongoing probing, use send_probe_to_node with a DefaultRouter — diversity scoring is applied per call via params_for_probe. Alternatively, set probing_diversity_penalty_msat on the router at construction for fixed probe amounts. This is intentionally different from send_spontaneous_preflight_probes, which probes all MPP paths with payment fee caps and tries to avoid saturating liquidity immediately before the payment is sent.

Fixes #2720

Tested with:
cargo +1.75.0 test -p lightning --lib probing — passed
cargo +1.75.0 test -p lightning --lib find_probe_route — passed
cargo +1.75.0 test -p lightning --lib for_probing — passed
cargo +1.75.0 test -p lightning --lib preflight_probe — passed
cargo +1.75.0 test -p lightning --lib router::tests — passed
cargo +1.75.0 doc -p lightning --no-deps — passed
RUSTFLAGS="--cfg=c_bindings" cargo +1.75.0 check -p lightning — passed
cargo +1.75.0 fmt --all — passed

[ldk-reviews-bot]

👋 Thanks for assigning @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

[ldk-claude-review-bot]

No new issues found in this re-review pass. The previously flagged issues have been addressed in the current commit.

Review Summary

Previously flagged issues — now resolved:

• routing/router.rs:992 — from_probe_target now sets .with_max_path_count(1), so send_probe_to_node probes the full amount_msat on a single deterministic path. The earlier MPP-split concern is fixed.
• The find_probe_route_with_diversity method (and its misleading "prefer send_probe_to_node" doc) has been removed entirely.
• routing/scoring.rs:891 — the historical-amount component now divides by AMOUNT_PENALTY_DIVISOR (1 << 20) with a comment that matches the actual combined_penalty_msat scaling.

Still open (judgment calls, not re-posted):

• for_probing omits the default-dominant liquidity_penalty_multiplier_msat, so the auto-derived diversity penalty can be smaller than the dominant per-channel penalty.
• DefaultRouter's new SP: Clone bound is a minor public API tightening.

I verified the refactored preflight loop and the shared trim_unannounced_probe_last_hops helper preserve the original trimming/fee-accumulation behavior, and that background_probe is correctly treated as a runtime-only (non-serialized) field. No new bugs, security issues, or logic errors identified.

[151henry151]

Addressed the bot feedback in cbd9c04: corrected the find_probe_route_with_diversity docs so pre-computed routes go through send_probe rather than send_probe_to_node, fixed the for_probing historical-amount divisor to AMOUNT_PENALTY_DIVISOR (the earlier 1 << 31 ignored the /2048 cancellation in combined_penalty_msat), and extended send_probe_to_node_happy_path to run the full probe lifecycle.

Is the norm here is to squash this kind of follow-up into one commit or keep the two-commit history?

[151henry151]

Addressed all three comments in the latest commit (b17afa6).

Moved probe score-param tuning to ScoreLookUp::params_for_probe — ProbabilisticScorer overrides it to call the existing for_probing; the Deref blanket impl and ScorerAccountingForInFlightHtlcs forward it; other scorers get the default (clone unchanged). Removed Router::find_probe_route, the free find_probe_route fn, and DefaultRouter::find_probe_route_with_diversity. send_probe_to_node now calls find_route with RouteParameters::from_probe_target (sets a runtime-only background_probe flag); DefaultRouter::find_route calls params_for_probe when that flag is set. Fixed “liquidity guard” wording and removed the new rustfmt::skips.

Squash commits, or keep history?

[ldk-reviews-bot]

🔔 1st Reminder

Hey @wpaulino! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

[ldk-reviews-bot]

🔔 2nd Reminder

Hey @wpaulino! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

[151henry151]

Squashed to one commit — review feedback folded in, instead of added as fix-ups on top.

[151henry151]

Latest squash sets max_path_count = 1 in from_probe_target per bot feedback.

[ldk-reviews-bot]

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.