Skip to content

askrene: opt-in circular (self-rebalance) routes in getroutes #9286

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ksedgwic wants to merge 2 commits into
base: master
Choose a base branch
from
Open

askrene: opt-in circular (self-rebalance) routes in getroutes #9286

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3013db6
askrene: support circular (self-rebalance) routes via gossmap node-split
ksedgwic Jun 29, 2026
65d4a82
askrene: test circular (self-rebalance) getroutes
ksedgwic Jun 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .msggen.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2223,6 +2223,7 @@
"GetRoute.route[].style": 6
},
"GetroutesRequest": {
"GetRoutes.allow_circular": 10,
"GetRoutes.amount_msat": 3,
"GetRoutes.destination": 2,
"GetRoutes.final_cltv": 7,
Expand Down Expand Up @@ -8717,6 +8718,10 @@
"added": "v24.08",
"deprecated": null
},
"GetRoutes.allow_circular": {
"added": "v26.09",
"deprecated": null
},
"GetRoutes.amount_msat": {
"added": "v24.08",
"deprecated": null
Expand Down
1 change: 1 addition & 0 deletions cln-grpc/proto/node.proto
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions cln-grpc/src/convert.rs
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions cln-rpc/src/model.rs
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

14 changes: 13 additions & 1 deletion contrib/msggen/msggen/schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16495,7 +16495,11 @@
"",
"Layers are generally maintained by plugins, either to contain persistent information about capacities which have been discovered, or to contain transient information for this particular payment (such as blinded paths or routehints).",
"",
"There are some automatic layers: *auto.localchans* contains information on local channels from this node (including non-public ones), and their exact current spendable capacities. *auto.sourcefree* overrides all channels (including those from previous layers) leading out of the *source* to be zero fee and zero delay. These are both useful in the case where the source is the current node. *auto.include_fees* that fixes the send amount and deducts fee from there, ie. the receiver pays for fees instead of the sender. *auto.no_mpp_support* is deprecated in v26.06: use `maxparts=1` instead."
"There are some automatic layers: *auto.localchans* contains information on local channels from this node (including non-public ones), and their exact current spendable capacities. *auto.sourcefree* overrides all channels (including those from previous layers) leading out of the *source* to be zero fee and zero delay. These are both useful in the case where the source is the current node. *auto.include_fees* that fixes the send amount and deducts fee from there, ie. the receiver pays for fees instead of the sender. *auto.no_mpp_support* is deprecated in v26.06: use `maxparts=1` instead.",
"",
"Circular (self-rebalance) routing: normally *source* and *destination* must differ, and *source* == *destination* is rejected as invalid input. If *allow_circular* is set, *source* == *destination* is instead treated as a request for a self-rebalance cycle: a route that leaves *source*, traverses the network, and returns to *source*. This is intended for moving liquidity between one's own channels. Combine it with a layer that disables every (*source* -> peer) direction except the channels you want the cycle to drain, and every (peer -> *source*) direction except the channels you want it to fill, to pin both ends of the cycle.",
"",
"In a circular result, the final hop of each route is a *sentinel* closing hop rather than a real channel: its *short_channel_id_dir* and *node_id_out* are placeholders for a synthetic internal node, not a real channel or peer. The caller must replace them with the real closing channel and their own node id when building the payment. Its *amount_out_msat*, *cltv_out*, and the fees it implies are real and describe the closing hop the caller is expected to construct, so the cycle balances."
],
"categories": [
"readonly"
Expand Down Expand Up @@ -16565,6 +16569,14 @@
"Maximum number of routes in the solution."
],
"default": "100"
},
"allow_circular": {
"type": "boolean",
"added": "v26.09",
"description": [
"If set, permit *source* to equal *destination* and return a circular (self-rebalance) route: a cycle that leaves *source*, traverses the network, and returns to *source*. Without this, *source* == *destination* is rejected as invalid input. See \"Circular (self-rebalance) routing\" below."
],
"default": "false"
}
}
},
Expand Down
6 changes: 4 additions & 2 deletions contrib/pyln-client/pyln/client/lightning.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -897,10 +897,11 @@ def getroute(self, node_id, amount_msat, riskfactor, cltv=9, fromid=None,
return self.call("getroute", payload)

def getroutes(self, source, destination, amount_msat, layers, maxfee_msat,
final_cltv, maxdelay=None, maxparts=None):
final_cltv, maxdelay=None, maxparts=None, allow_circular=None):
"""Find routes from {source} to {destination} for {amount_msat},
applying {layers}, paying no more than {maxfee_msat},
ending in {final_cltv}.
ending in {final_cltv}. If {allow_circular} is set, permit
{source} == {destination} and return a self-rebalance cycle.
"""
payload = {
"source": source,
Expand All @@ -911,6 +912,7 @@ def getroutes(self, source, destination, amount_msat, layers, maxfee_msat,
"final_cltv": final_cltv,
"maxdelay": maxdelay,
"maxparts": maxparts,
"allow_circular": allow_circular,
}
return self.call("getroutes", payload)

Expand Down
532 changes: 266 additions & 266 deletions contrib/pyln-grpc-proto/pyln/grpc/node_pb2.py
View file
Open in desktop

Large diffs are not rendered by default.

14 changes: 13 additions & 1 deletion doc/schemas/getroutes.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,11 @@
"",
"Layers are generally maintained by plugins, either to contain persistent information about capacities which have been discovered, or to contain transient information for this particular payment (such as blinded paths or routehints).",
"",
"There are some automatic layers: *auto.localchans* contains information on local channels from this node (including non-public ones), and their exact current spendable capacities. *auto.sourcefree* overrides all channels (including those from previous layers) leading out of the *source* to be zero fee and zero delay. These are both useful in the case where the source is the current node. *auto.include_fees* that fixes the send amount and deducts fee from there, ie. the receiver pays for fees instead of the sender. *auto.no_mpp_support* is deprecated in v26.06: use `maxparts=1` instead."
"There are some automatic layers: *auto.localchans* contains information on local channels from this node (including non-public ones), and their exact current spendable capacities. *auto.sourcefree* overrides all channels (including those from previous layers) leading out of the *source* to be zero fee and zero delay. These are both useful in the case where the source is the current node. *auto.include_fees* that fixes the send amount and deducts fee from there, ie. the receiver pays for fees instead of the sender. *auto.no_mpp_support* is deprecated in v26.06: use `maxparts=1` instead.",
"",
"Circular (self-rebalance) routing: normally *source* and *destination* must differ, and *source* == *destination* is rejected as invalid input. If *allow_circular* is set, *source* == *destination* is instead treated as a request for a self-rebalance cycle: a route that leaves *source*, traverses the network, and returns to *source*. This is intended for moving liquidity between one's own channels. Combine it with a layer that disables every (*source* -> peer) direction except the channels you want the cycle to drain, and every (peer -> *source*) direction except the channels you want it to fill, to pin both ends of the cycle.",
"",
"In a circular result, the final hop of each route is a *sentinel* closing hop rather than a real channel: its *short_channel_id_dir* and *node_id_out* are placeholders for a synthetic internal node, not a real channel or peer. The caller must replace them with the real closing channel and their own node id when building the payment. Its *amount_out_msat*, *cltv_out*, and the fees it implies are real and describe the closing hop the caller is expected to construct, so the cycle balances."
],
"categories": [
"readonly"
Expand Down Expand Up @@ -81,6 +85,14 @@
"Maximum number of routes in the solution."
],
"default": "100"
},
"allow_circular": {

@Lagrang3 Lagrang3 Jul 9, 2026

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.

We can be increasing the number of flags forever. That's why, I guess, Rusty preferred
to introduce these as auto layers. So I would prefer to adhere to that pattern.
Instead of a boolean option this would be a auto.allow_circular layer.

"type": "boolean",
"added": "v26.09",
"description": [
"If set, permit *source* to equal *destination* and return a circular (self-rebalance) route: a cycle that leaves *source*, traverses the network, and returns to *source*. Without this, *source* == *destination* is rejected as invalid input. See \"Circular (self-rebalance) routing\" below."
],
"default": "false"
}
}
},
Expand Down
Loading
Loading