Add 'send_circular_payment' helper and 'send_spontaneous_payment_with…

[Ferryx349]

Fixes- #3791
This PR adds two new methods to ChannelManager:

send_circular_payment

A helper for circular channel rebalancing. It:

1. Validates that two provided channel IDs are distinct and usable.
2. Calls find_route targeting the inbound channel's counterparty, with first_hops restricted to only the outbound channel to force the router to use it as the first hop.
3. Manually appends a final RouteHop back to our own node over the inbound channel's SCID, with fee_msat set to the full payment amount as required for the last hop and the preceding hop's fee_msat adjusted to counterparty's forwarding fee.
4. Sends result as a spontaneous payment via send_spontaneous_payment_with_route.

The existing guard in pay_route_internal already permits our node as the last hop in a path ("simple rebalance loop to us"), so no changes to the payment sending internals were needed.

Tests

1. test_circular_payment_rebalance: covers the happy path (0→1→2→0), same-channel error, and channel-not-found error.
2. test_circular_payment_no_route: verifies RouteNotFound is returned when no path exists between the two counterparties.

This is my first contribution to LDK. I tried to follow the patterns established by send_payment_with_route and send_spontaneous_preflight_probes as closely as possible. Happy to revise anything that doesn't match project conventions.

CC: @tnull

[ldk-reviews-bot]

I've assigned @wpaulino 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]

Review Summary

Issues Found

Inline comments posted:

1. lightning/src/ln/channelmanager.rs:5594 — [2; 32] should be [2; 33]: latent panic in route_params_for_fixed_route fallback. Every other usage in the codebase uses 33 bytes for compressed public keys. Pre-existing bug preserved during refactoring.

2. lightning/src/ln/channelmanager.rs:5631 — send_spontaneous_payment_with_route is a new public API with insufficient documentation. Should mention no auto-retry and reference send_spontaneous_payment.

Prior comments status

The four issues from the previous review pass appear to have been addressed in the current code:

• cltv_expiry_delta is now updated on prev_last (line 6233)
• forwarding_info None case returns early with an error (lines 6199-6203)
• forwarding_info.cltv_expiry_delta is used in PaymentParameters (lines 6206, 6209)
• DRY issue resolved via route_params_for_fixed_route helper

Cross-cutting notes

• The diff includes unrelated whitespace reformatting of ComplFunc closure type signatures around lines 9898/9937. These should ideally be in a separate commit to keep the diff focused.

[codecov]

Codecov Report

❌ Patch coverage is 93.87755% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.39%. Comparing base (946ee09) to head (844dae6).
⚠️ Report is 22 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/ln/channelmanager.rs	93.87%	2 Missing and 4 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4616      +/-   ##
==========================================
+ Coverage   86.11%   86.39%   +0.28%     
==========================================
  Files         157      158       +1     
  Lines      108841   109382     +541     
  Branches   108841   109382     +541     
==========================================
+ Hits        93725    94504     +779     
+ Misses      12497    12325     -172     
+ Partials     2619     2553      -66     

Flag	Coverage Δ
fuzzing-fake-hashes	5.07% <0.00%> (?)
fuzzing-real-hashes	22.74% <16.32%> (?)
tests	86.12% <93.87%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ldk-claude-review-bot]

Bug (pre-existing, preserved during refactor): [2; 32] produces a 32-byte array, but secp256k1::PublicKey::from_slice expects 33 bytes for a compressed key. This unwrap() will always panic if reached.

Every other usage in the codebase uses [2; 33]. This code path is only hit when the route has zero paths (so it's currently unreachable in practice), but it's still a latent panic that should be fixed while this code is being moved:

Suggested change

	(PublicKey::from_slice(&[2; 32]).unwrap(), MIN_FINAL_CLTV_EXPIRY_DELTA as u32)
	(PublicKey::from_slice(&[2; 33]).unwrap(), MIN_FINAL_CLTV_EXPIRY_DELTA as u32)

[ldk-claude-review-bot]

This is a new public API method but the documentation is very sparse. At minimum it should mention no auto-retry behavior and reference send_spontaneous_payment for more context, similar to how send_payment_with_route references send_payment:

Suggested change

	#[rustfmt::skip]
	/// Sends a spontaneous payment along a given route. See
	/// [`Self::send_spontaneous_payment`] for more info.
	///
	/// LDK will not automatically retry this payment, though it may be manually re-sent after an
	/// [`Event::PaymentFailed`] is generated.

[Ferryx349]

got these after doing fmt in channelmanager...