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

.msggen.json

@@ -2223,6 +2223,7 @@
             "GetRoute.route[].style": 6
         },
         "GetroutesRequest": {
+            "GetRoutes.allow_circular": 10,
             "GetRoutes.amount_msat": 3,
             "GetRoutes.destination": 2,
             "GetRoutes.final_cltv": 7,
@@ -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

contrib/msggen/msggen/schema.json

@@ -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"
@@ -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"
           }
         }
       },

contrib/pyln-client/pyln/client/lightning.py

@@ -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,
@@ -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)
 

doc/schemas/getroutes.json

@@ -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"
@@ -81,6 +85,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"
       }
     }
   },