getroute: deprecate in favor of `getroutes`
What changed, and why it matters
This commit simply marks an older command, getroute, as deprecated and tells users to switch to a newer command, getroutes. It does not fix a bug or change security behavior. The old command still works for now, but tests that use it must explicitly allow deprecated APIs. There is no security issue here.
No security action needed. Developers relying on getroute should plan migration to getroutes with layers ["auto.localchans","auto.sourcefree"] and maxparts=1 before v27.03.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The patch deprecates the JSON-RPC command getroute in favor of getroutes. It updates schema documentation, the deprecated-features list, and the plugin command registration to include deprecation version windows (v26.06 to v27.03). Existing tests that call getroute are updated to enable allow-deprecated-apis, and one test assertion using getroute is removed. No code logic affecting routing, payment safety, or access control is changed.
Changed components
JSON-RPC command getrouteplugins/topology.cdoc/schemas/getroute.jsondoc/developers-guide/deprecated-features.mdtests/test_gossip.pytests/test_pay.pyInspect captured patch +10 / −5
diff --git a/contrib/msggen/msggen/schema.json b/contrib/msggen/msggen/schema.json
index 270dfa88..8c86eeba 100644
--- a/contrib/msggen/msggen/schema.json
+++ b/contrib/msggen/msggen/schema.json
@@ -16297,6 +16297,8 @@
"rpc": "getroute",
"title": "Command for routing a payment (low-level)",
"description": [
+ "NOTE: As of v26.06, getroute is deprecated in favor of **getroutes**. The usual equivalent is to use getroutes with `layers` including `auto.localchans`, `auto.sourcefree` and `maxparts` set to 1.",
+ "",
"The **getroute** RPC command attempts to find the best route for the payment of *amount_msat* to lightning node *id*, such that the payment will arrive at *id* with *cltv*.",
"",
"There are two considerations for how good a route is: how low the fees are, and how long your payment will get stuck in a delayed output if a node goes down during the process. ."
diff --git a/doc/developers-guide/deprecated-features.md b/doc/developers-guide/deprecated-features.md
index 298e2bb4..89f75a4c 100644
--- a/doc/developers-guide/deprecated-features.md
+++ b/doc/developers-guide/deprecated-features.md
@@ -29,6 +29,7 @@ privacy:
| getroutes.delay | Field | v26.06 | v27.06 | Use `cltv_in` instead (since v26.06) |
| pay | Command | v26.06 | v27.03 | Use the more sophisticated and effective "xpay" command instead (since v24.11). |
| paystatus | Command | v26.06 | v27.03 | Uses internal pay structures, doesn't work with xpay, doesn't work across restarts. |
+| getroute | Command | v26.06 | v27.03 | Less flexible than `getroutes` which takes an actual fee budget and can do multiple paths at once. |
Inevitably there are features which need to change: either to be generalized, or removed when they can no longer be supported.
diff --git a/doc/schemas/getroute.json b/doc/schemas/getroute.json
index 404d5390..b6bdd2c4 100644
--- a/doc/schemas/getroute.json
+++ b/doc/schemas/getroute.json
@@ -4,6 +4,8 @@
"rpc": "getroute",
"title": "Command for routing a payment (low-level)",
"description": [
+ "NOTE: As of v26.06, getroute is deprecated in favor of **getroutes**. The usual equivalent is to use getroutes with `layers` including `auto.localchans`, `auto.sourcefree` and `maxparts` set to 1.",
+ "",
"The **getroute** RPC command attempts to find the best route for the payment of *amount_msat* to lightning node *id*, such that the payment will arrive at *id* with *cltv*.",
"",
"There are two considerations for how good a route is: how low the fees are, and how long your payment will get stuck in a delayed output if a node goes down during the process. ."
diff --git a/plugins/topology.c b/plugins/topology.c
index 5990bbe7..8c1ba598 100644
--- a/plugins/topology.c
+++ b/plugins/topology.c
@@ -616,6 +616,7 @@ static const struct plugin_command commands[] = {
{
"getroute",
json_getroute,
+ "v26.06", "v27.03",
},
{
"listchannels",
diff --git a/tests/test_gossip.py b/tests/test_gossip.py
index 7a037f20..326a4391 100644
--- a/tests/test_gossip.py
+++ b/tests/test_gossip.py
@@ -1474,7 +1474,8 @@ def test_getroute_exclude_duplicate(node_factory):
in the exclude list will not have permanent effects.
"""
- l1, l2 = node_factory.line_graph(2, wait_for_announce=True)
+ l1, l2 = node_factory.line_graph(2, wait_for_announce=True,
+ opts={'allow-deprecated-apis': True})
# Starting route
route = l1.rpc.getroute(l2.info['id'], 1, 1)['route']
@@ -1506,7 +1507,8 @@ def test_getroute_exclude_duplicate(node_factory):
def test_getroute_exclude(node_factory, bitcoind):
"""Test getroute's exclude argument"""
- l1, l2, l3, l4, l5 = node_factory.get_nodes(5)
+ l1, l2, l3, l4, l5 = node_factory.get_nodes(5,
+ opts={'allow-deprecated-apis': True})
node_factory.join_nodes([l1, l2, l3, l4], wait_for_announce=True)
# This should work
diff --git a/tests/test_pay.py b/tests/test_pay.py
index c8a557e0..5059b0d0 100644
--- a/tests/test_pay.py
+++ b/tests/test_pay.py
@@ -5738,9 +5738,6 @@ def test_pay_routehint_minhtlc(node_factory, bitcoind):
# You should be able to pay the invoice!
l1.rpc.pay(inv['bolt11'])
- # And you should also be able to getroute (and have it ignore htlc_min/max constraints!)
- l1.rpc.getroute(l3.info['id'], amount_msat=0, riskfactor=1)
-
@pytest.mark.openchannel('v1')
@pytest.mark.openchannel('v2')
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.