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.

[ldk-reviews-bot]

🔔 2nd 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.

[tnull]

Hmm, we discussed before where background probing related logic should live and decided against expanding the logic in rust-lightning. Rather, background probing capabilities are now being added in lightningdevkit/ldk-node#815, so I'm not sure if we should go down the road of additional background-probing specific API changes in LDK?

[TheBlueMatt]

Ah, I hadn't seen that PR. Not sure what the right answer is regarding the right background probing API - my understanding previously was that we'd not want to add stuff in the lightning crate which handles tracking in-flight probes and manages liquidity and runs on some timer to constantly run background probes. I still don't think we should add that kind of logic.

However, lightningdevkit/ldk-node#815 is a lot more than that. Its also adding new logic for how to build paths for probes beyond our existing logic. If it were as trivial as "pick a random node and send a random amount" I'd think it probably isn't worth upstreaming but its more than that - its both some code to select nodes based on various heuristics as well as a whole new router that does a random walk rather than selecting a path based on our existing scoring heuristics. If we want to go that direction and have a lot of additional logic that we think is important for doing good probing, IMO that should go in lightning, not LDK Node, so that others can use it.

That said, I'm not really sure that we want that much additional logic? Do we really think LDK Node users are going to be configuring their probing heuristics with a custom pathfinder? Or even tuning much beyond selecting which nodes to probe based on their historical payment targets?