Repository navigation
Add non-paying circular route quotes constrained to exact local channels - #1220
hudhaifahz wants to merge 3 commits into
Conversation
Extract non-paying route quotation from getAlby#115 and adapt it to current upstream. Pin both local endpoints, preserve fee limits, and expose estimates through Rust and UniFFI without payment-store or execution changes. Test parallel channels, aliases, and multipart routes. AI disclosure: prepared with OpenAI Codex; CodeRabbit CLI assisted review.
|
I've assigned @tnull as a reviewer! |
Resolve the payment-module import conflict against upstream 4a8fb7f. Use upstream apply_route_parameters_config for circular quotes instead of retaining a separate fee/config implementation. AI disclosure: prepared and validated with OpenAI Codex.
SpendableOutputs registration can follow sync_wallets sweep generation, leaving a valid PendingBroadcast state. Poll with the existing bounded helper, then observe the exact spending transaction before mining. Keep the terminal balance and confirmation assertions intact. AI disclosure: prepared and validated with OpenAI Codex; CodeRabbit CLI assisted review.
tnull
left a comment
There was a problem hiding this comment.
Hmm, this seems like a rather hacky workaround (IIUC?). I think as discussed in https://git.rust-bitcoin.org/lightningdevkit/rust-lightning/issues/3791 we should rather probably add a helper for circular route finding upstream and then make use of it here.
|
Thanks @tnull — agreed that LDK Node should consume an upstream helper rather than own this routing workaround. I read #3791 and found the existing #4616. I'd like to coordinate with that work and reuse its route-construction pieces rather than start a competing implementation. For agreement before more code, my proposed first slice is a non-paying circular-route helper in rust-lightning, tentatively
I can adapt the existing tests here for exact parallel-channel selection, aliases, endpoint validation, zero/default/explicit fee caps and unchanged payment state. The MPP fixture is also reusable: if multipath is included, every path must use the same selected endpoints and respect aggregate limits. That is route-finding coverage, not a claim that the keysend flow in #4616 supports MPP. Two design choices I'd appreciate your direction on:
Once that boundary is agreed, the plan is to contribute the reusable tests/helper upstream and reduce #1220 to the LDK Node adapter. I'll hold off on further implementation until then. AI assistance: Codex helped review the linked discussion/code and prepare this proposal. |
Applications planning a channel rebalance need to choose the outgoing and returning channels, including when several channels connect to the same peer. This adds
Bolt11Payment::quote_circular_routeand Rust/UniFFI quote records exposing the estimated paths and fees for that exact pair. Quoting creates no invoice, probe, HTLC, or payment-store entry.Approach
The router receives only the selected outgoing channel as a first hop and a route hint for the selected incoming channel. Since ordinary LDK pathfinding rejects payer == payee, the search targets a fresh synthetic recipient behind the incoming peer. Before returning a quote, every path is checked against both endpoint channel IDs and peer identities; only the terminal synthetic identity is then replaced with the local node. Synthetic payment parameters are discarded.
Routing configuration is applied through upstream's shared
apply_route_parameters_confighelper. The search uses the local node's BOLT11 feature support, current in-flight HTLCs, channel capacities, incoming forwarding policy, and routing configuration. This permits multipart estimates while keeping the same selected first and last channel on every path. An unset fee cap preserves LDK's default; an explicit zero cap stays zero. Ambiguous user channel IDs are rejected. A quote is an estimate, not a liquidity reservation or a guarantee of payment success.Scope and provenance
This extracts the route-quotation work from getAlby/ldk-node#115, source commit
70965f2e58936c0893c48ee0cc1788b84164a4e2, and adapts it to upstream main4a8fb7f39d0fe75e9ad863ec038a9571f464587d.There are no payment-storage changes, new dependencies, swaps, UI changes, or automatic rebalancing in this PR. It does not enable circular sending. The older fork's durable preparation, exact receiving-channel enforcement, and restart recovery are deferred for a separate design review. Opaque serialized routes are deliberately absent from the public quote API so this PR does not establish an execution or durable serialization contract.
Validation
cargo +1.91.1 test --lib: 393 passed (with CI cycle-test configuration).cargo +1.91.1 test --no-default-features --features uniffi-default --lib: 392 passed.RUSTDOCFLAGS=-D warningson the original contribution.Checks ran on macOS ARM64. Formatting used the repository-pinned
nightly-2026-09-22.The new pathfinding tests use LDK's in-process functional network. They do not send real payments. The full cross-platform CI matrix is also exercised by upstream CI.
CI repair after updating from main
The import conflict is resolved against current upstream, reusing its routing-configuration helper. The original macOS beta failure was in the existing force-close settlement helper, which immediately rejected the valid intermediate
PendingBroadcaststate. The quote API is not called by that test. The helper now uses the existing bounded polling utility to wait for sweep generation, then observes the exact spending transaction in the backend before mining its confirmation. Terminal balance assertions remain unchanged. No production force-close or wallet behavior is changed.The original failure was intermittent: an isolated current-main run passed. The diagnosis follows the failed CI location, the pending-sweep enum variants, and the asynchronous event/broadcast ordering; it does not claim a deterministic local reproduction.
CI status after repair
At 2026-11-12 22:30:29 UTC on head
c7c35bd1db2a6486f9621e50ee9712d50312f6e0:Review focus
Is
Bolt11Paymentthe preferred location for this quote-only API, and is the synthetic-destination route-hint approach acceptable as an initial circular-routing primitive? The intent is to contribute this functionality to shared upstream ownership before proposing the larger payment lifecycle.AI disclosure: implementation, adaptation, tests, and this description were prepared with OpenAI Codex. CodeRabbit CLI was used for automated review; its findings are assessed rather than treated as a security audit.