Skip to content

Deprecate pay, keysend, renepay and getroute#9110

Merged
rustyrussell merged 43 commits into
ElementsProject:masterfrom
rustyrussell:guilt/deprecate-pay
May 11, 2026
Merged

Deprecate pay, keysend, renepay and getroute#9110
rustyrussell merged 43 commits into
ElementsProject:masterfrom
rustyrussell:guilt/deprecate-pay

Conversation

@rustyrussell

@rustyrussell rustyrussell commented May 5, 2026

Copy link
Copy Markdown
Contributor
  1. Complete the xpay feature set:
    1. Add xkeysend variant for "keysend using xpay",
    2. Add label and localinvreqid parameter support,
    3. Implement CLTV shadow routing in xpay.
    4. Handle channel_updates in errors in xpay.
    5. Improve compat handling for xpay-handle-pay: "succeed" like pay did if we're already paid.
  2. Enhance getroutes and sendpay: getroutes gets clearer and more complete fields, and sendpay understands them so the two easily work together
  3. Deprecate pay, paystatus, keysend, getroute, and renepay/renepaystatus (all with removal window v26.06–v27.03), and make xpay-handle-pay the default.

@rustyrussell rustyrussell added this to the v26.06 milestone May 5, 2026
@rustyrussell rustyrussell requested a review from Lagrang3 May 5, 2026 02:24
@rustyrussell rustyrussell requested a review from cdecker as a code owner May 5, 2026 02:24
@madelinevibes madelinevibes added Status::Ready for Review The work has been completed and is now awaiting evaluation or approval. PLEASE clear CI 🫠 labels May 5, 2026
Lagrang3
Lagrang3 reviewed May 5, 2026
View reviewed changes
Comment thread plugins/xpay/xpay.c
Lagrang3
Lagrang3 approved these changes May 5, 2026
View reviewed changes

@Lagrang3 Lagrang3 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This has been a lot of effort.
Nice work on building xkeysend and making getroutes compatible with sendpay.

@Lagrang3

Lagrang3 commented May 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

@rustyrussell, I think we could keep the old json rpc names keysend and pay to be presented as a legacy API and under the surface be calling xkeysend and xpay. We wouldn't need to deprecate them, or break existing software relying on that API and in any case the names suit for their purposes. Someone coming into core lightning one year from now will be asking "why is that command called xpay instead of simply pay".

I know there is a little bit of work to be done to digest the parameters in pay to the almost equivalent xpay call, in particular with the exclude option, but it is workable.

@rustyrussell

rustyrussell commented May 7, 2026

Copy link
Copy Markdown
Contributor Author

@rustyrussell, I think we could keep the old json rpc names keysend and pay to be presented as a legacy API and under the surface be calling xkeysend and xpay. We wouldn't need to deprecate them, or break existing software relying on that API and in any case the names suit for their purposes. Someone coming into core lightning one year from now will be asking "why is that command called xpay instead of simply pay".

I know there is a little bit of work to be done to digest the parameters in pay to the almost equivalent xpay call, in particular with the exclude option, but it is workable.

Instead of removing pay, we can just make it an alias for xpay when pay is fully deprecated? We could allow "invstring" as a parameter to pay: that covers 99% of the transition already (amount_msat and label are already the same).

Similarly, keysend just becomes an alias for xkeysend.

@rustyrussell rustyrussell force-pushed the guilt/deprecate-pay branch from 5a447d1 to c2ca227 Compare May 7, 2026 06:44
@rustyrussell

rustyrussell commented May 7, 2026

Copy link
Copy Markdown
Contributor Author

@rustyrussell, I think we could keep the old json rpc names keysend and pay to be presented as a legacy API and under the surface be calling xkeysend and xpay. We wouldn't need to deprecate them, or break existing software relying on that API and in any case the names suit for their purposes. Someone coming into core lightning one year from now will be asking "why is that command called xpay instead of simply pay".
I know there is a little bit of work to be done to digest the parameters in pay to the almost equivalent xpay call, in particular with the exclude option, but it is workable.

Instead of removing pay, we can just make it an alias for xpay when pay is fully deprecated? We could allow "invstring" as a parameter to pay: that covers 99% of the transition already (amount_msat and label are already the same).

Similarly, keysend just becomes an alias for xkeysend.

I've add this change: pay now accepts invstring so people can use it today.

@rustyrussell rustyrussell force-pushed the guilt/deprecate-pay branch 2 times, most recently from 58e1b79 to 26827eb Compare May 7, 2026 23:58
@rustyrussell rustyrussell enabled auto-merge (rebase) May 7, 2026 23:59
@rustyrussell rustyrussell force-pushed the guilt/deprecate-pay branch 8 times, most recently from c56d5fd to 119d29b Compare May 11, 2026 01:15
@rustyrussell
update-mocks: make handling of mocks in nested files deterministic.
4258cd0 
update-mocks searches for prototypes, looking first in the local
directory, then in */*.h, and takes the first.  In the case of
plugins/bkpr/test/run-currencyrate_str.c referring to
jsonrpc_request_start_, this means it could get either the one in
libplugin (correct) or the one in lightningd (wrong!), depending on
directory order randomness.

Hack it a bit harder, to look one up from the local dir before */*.h.
This is redundant in most cases, but not for three-deep-nested dirs
like this.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
common: implement tal_arr_append and tal_arr_appendn, and use them.
b502ca3 
These are useful for the common pattern of "append these bytes to this tal array".

As a bonus, we do memcheck() on all these callers, for extra checking
under valgrind.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
CCAN: update to get json_escape_dup helper.
304d33e 
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
pytest: cleanup test_pay_avoid_low_fee_chan flake.
15c5a43 
Use standard names, and don't wait for each channel: wait for the final result.

In particular, make sure l1 sees *all* the gossip!

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
askrene: all remove_small_channel_layer when maxparts=1.
9c9078c 
We were doing it for "auto.no_mpp_support", but not maxparts=1.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
askrene: improve errors we return.
c3d983f 
In particular, we can return PAY_ROUTE_TOO_EXPENSIVE.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
askrene: make failure messages clearer:
51718b8 
If all channels are disabled, say so clearly.  Also reword: it's not
the source or destination which have disabled the channels.  While
we're here, remove the double space, lest people think I'm Satoshi.

Before:
	Failed after 1 attempts.
	Unexpected error (invalid_onion_payload) from final node: disabling 103x1x0/1 for this payment.
	Then routing failed: We could not find a usable set of paths.  The source has disabled 1 of 1 channels, leaving capacity only 0msat of 1000000000msat.

After:
	Failed after 1 attempts.
	Unexpected error (invalid_onion_payload) from final node: disabling 103x1x0/1 for this payment.
	Then routing failed: We could not find a usable set of paths. All 1 channels to the source are disabled.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
pytest: use maxparts=1 not the soon-to-be-deprecated "auto.no_mpp_sup…
a6b8251 
…port" layer.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
xpay: ensure unique_id is always valid.
2b50033 
In implementing shadow, I added a call to payment_log in xpay_core,
which caused a valgrind error because we set unique_id later.  This
was a premature optimization, so we didn't assign unique_id for
payments which didn't even start, but it's a footgun, and there are
other (less common) calls to payment_log too early which make the same
mistake.

Simplify: unique_id is assigned at creation.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
askrene: populate struct route with more complete information.
9e7ad05 
Much of this is redundant, but now it's better labeleled and stands alone.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
getroutes: return more detailed fields in routes[].
acedb59 
This reflects a long-standing complaint from @Lagrang3 when the API
was first implemented, and I should have listened.  In particular, the
impedance mismatch with the sendpay API is annoying.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
Changelog-Added: JSON-RPC: `getroutes` `route` explicit fields `node_id_in`, `node_id_out`, `amount_in_msat`, `amount_out_msat`, `cltv_in`, `cltv_out`.
@rustyrussell
getroutes: deprecate old vaguely named fields.
35f2469 
Changelog-Deprecated: JSON-RPC: `getroutes` `route` fields `next_node_id`, `amount_msat` and `delay` (use `node_id_out`, `amount_in_msat` and `cltv_in`).
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell rustyrussell force-pushed the guilt/deprecate-pay branch from 119d29b to fce4055 Compare May 11, 2026 04:05
rustyrussell added 19 commits May 11, 2026 13:50
@rustyrussell
sendpay: ignore unknown route fields, but take the getroutes-styl…
afec304 
…e ones.

Changelog-Added: JSON-RPC: `sendpay` now accepts one of the `paths` returned from `getroutes` as its `route` parameter.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
pyln: add getroutes wrapper to pyln-client, add single_route helper t…
6931040 
…o pyln-testing.

And remove the two getroute() calls inside pyln-testing.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
tests: use getroutes, not getroute (simple cases)
2a81897 
We add a nice getroutes wrapper and use it to replace the simple
getroute() calls which simply hand the result to sendpay().

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
pytest: convert remaining getroute cases.
b52faf5 
Excluding explicit getroute tests.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
xpay: add xkeysend support.
d8af31d 
This uses askrene, so it benefits from previous payment experience.

Changelog-Added: JSON-RPC: `xkeysend` command for keysend with modern routing support.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
pytest: speed up test_keysend_description_size_limit
ed29120 
Starting up two nodes for each variant is slow, so do this internally.
Also check that the descriptions are correct, not just that there is
some invoice!

Before:
================================ 7 passed in 75.63s (0:01:15) ================================

After:
===================================== 1 passed in 12.62s =====================================

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
pytest: test xkeysend as thoroughly as keysend.
bfa74a7 
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
offers: use xpay.
f2a7d54 
Changelog-Changed: offers: we now use `xpay` not `pay` for paying invoices made with invoicerequest().
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
pytest: make pay tests more robust.
b10fe00 
1. Don't assume they send group 0 (thus waitsendpay works).  waitsendpay should be unnecessary
   after pay anyway.
2. Don't use pay for test_multichan_stress, since it relies on pay not learning that
   the channel is unreliable.
3. Use xpay for test_listhtlcs_wait, since we want no shadow.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
pyln-testing: allow bitcoind mocks to return None to mean "don't mock".
0552ef2 
Good for conditional mocks, like in next patch.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
pytest: use xpay, not pay in misc tests.
8db4766 
This usually means changing the error strings, where we test them, and
avoiding `paystatus`.

Other changes:
1. Completely get rid of `test_custom_notification_topics`: xpay tests do this
   already.
2. Add xpay wrapper to pyln-client so we can mix named and unnamed args.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
xpay: take over pay invocations by default.
4ac80c1 
The main change here is the error messages got better.  Where that was
the case, and the test was not completely redundant with existing xpay
tests, I explicitly converted to calls to xpay (meaning the tests
will be kept when `pay` is finally removed).

Test changes:
1. deschash checking is old-pay only, keep that there.
2. Add debug logs for checks for using forwarding via scid in injectpaymentonion.
3. Don't assert that not all sendpays should have the invoice string: xpay does not try to be clever there.
4. We no longer check if invoices are already paid before routing, since injectpaymentonion will catch that for us.
5. Removed `test_pay_get_error_with_update` which has xpay equiv.

Changelog-Changed: JSON-RPC: `xpay` now handles `pay` command by default (use `xpay-handle-pay=false` to prevent this)
Changelog-Removed: JSON-RPC: `exclude` parameter to `pay` (when `xpay-handle-pay` is True): craft a layer with desired modifications and pass it to `xpay` `layers`.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
pay: accept invstring as first parameter name.
d28ad2b 
If you don't use complex pay options, you can use `invstring` now and when xpay
becomes pay, there's no transition.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
Changelog-Changed: JSON-RPC: `pay` now accepts `invstring` as a parameter name for `bolt11`, to ease transition when xpay takes over in v27.03.
@rustyrussell
pay: deprecate pay and paystatus.
766082e 
Use xpay and listpays.

Some tests which are pay/paystatus specific simply enabled deprecations.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
Changelog-Deprecated: JSON-RPC: `pay` and `paystatus`: use `xpay`, `listpays` (or `xpay`'s notifications for details of attempts).  `pay` will be replaced by `xpay` in v27.03.
@rustyrussell
getroute: deprecate in favor of getroutes
ff4b71e 
Changelog-Deprecated: JSON-RPC: `getroute` (use `getroutes` with layers `["auto.localchans","auto.sourcefree"]` and `maxparts=1`) (since v25.09).

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
keysend: deprecate in favor of xkeysend.
9941d46 
Changelog-Deprecated: JSON-RPC: `keysend` (use `xkeysend`).  `xkeysend` will take over `keysend` in v27.03.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
xpay: keep track of ongoing payments, to implement attempt_ongoing()
d655892 
This will help when we implement listpays (next) to be xpay-aware.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
plugins: move listpays from pay plugin to xpay plugin.
5c59925 
This will make life easier when we remove the pay plugin, but also fixes
an issue where `listpays` can indicate ongoing payments are failed,
even though xpay is still working on it.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell
renepay: deprecate.
a9241d8 
I think Eduardo and I stole all the best bits to make xpay and askrene.

I simply enabled deprecations on all the renepay tests.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
@rustyrussell rustyrussell force-pushed the guilt/deprecate-pay branch from fce4055 to a9241d8 Compare May 11, 2026 04:20
@rustyrussell rustyrussell disabled auto-merge May 11, 2026 04:20
@rustyrussell rustyrussell merged commit 6eb7dc0 into ElementsProject:master May 11, 2026
3 checks passed
@Lagrang3 Lagrang3 mentioned this pull request Jun 10, 2026
Closed
This was referenced Jun 24, 2026
Closed
Draft
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Lagrang3 Lagrang3 Lagrang3 approved these changes
@cdecker cdecker Awaiting requested review from cdecker cdecker is a code owner

Assignees

No one assigned

Labels

PLEASE clear CI 🫠 Status::Ready for Review The work has been completed and is now awaiting evaluation or approval.

Projects

None yet

Milestone

v26.06

Development

Successfully merging this pull request may close these issues.

3 participants

@rustyrussell @Lagrang3 @madelinevibes