lightning-getroutes -- Command for routing a payment

SYNOPSIS

getroutes source destination amount_msat layers maxfee_msat final_cltv

DESCRIPTION

Command added in v24.08.

The getroutes RPC command attempts to find the best set of paths for the payment from source to destination of amount_msat, using the given layers on top of the gossip information. The result is constrained by maxfee, and will arrive at the destination with final_cltv.

NOTE: The returned paths are a different format then getroute, being more appropriate for creating intermediary onion layers.

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 two automatic layers: auto.localchans contains information on local channels from this node (including non-public ones), and their exact current spendable capacities, and 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.

source (pubkey): Node pubkey to start the paths
destination (pubkey): Node pubkey to end the paths
amount_msat (msat): Amount to send. It can be a whole number, or a whole number ending in msat or sat, or a number with three decimal places ending in sat, or a number with 1 to 11 decimal places ending in btc.
layers (array of strings):
- (string, optional): Layer to apply to the gossip map before attempting to find routes.
maxfee_msat (msat): Maximum fee to spend: we will never return a set of routes more expensive than this. It can be a whole number, or a whole number ending in msat or sat, or a number with three decimal places ending in sat, or a number with 1 to 11 decimal places ending in btc.
final_cltv (u32): Number of blocks for the final node. We need to know this because no HTLC is allowed to have a CLTV delay more than 2016 blocks.

RETURN VALUE

On success, an object is returned, containing:

probability_ppm (u64): The estimated probability of success using these routes, in millionths.
routes (array of objects):
- probability_ppm (u64): The estimated probability of success using this route, in millionths.
- amount_msat (msat): The amount delivered to the destination by this path.
- final_cltv (u32): Number of blocks required by the final node (set by caller)
- path (array of objects): The hops to get from source to destination.:
  - short_channel_id_dir (short_channel_id_dir): The channel and direction joining these nodes.
  - amount_msat (msat): The amount to send into this hop.
  - next_node_id (pubkey): The peer id at the end of this hop.
  - delay (u32): The total CLTV expected by the node at the start of this hop.

AUTHOR

<[email protected]> wrote the minimum-cost-flow solver, Rusty Russell <[email protected]> wrote the API and this documentation.

RESOURCES

Main web site: https://github.com/ElementsProject/lightning

EXAMPLES

Example 1:

Request:

lightning-cli getroutes -k "source"="nodeid010101010101010101010101010101010101010101010101010101010101" "destination"="nodeid030303030303030303030303030303030303030303030303030303030303" "amount_msat"=1250000 "layers"='[]' "maxfee_msat"=125000 "final_cltv"=0

{
  "id": "example:getroutes#1",
  "method": "getroutes",
  "params": {
    "source": "nodeid010101010101010101010101010101010101010101010101010101010101",
    "destination": "nodeid030303030303030303030303030303030303030303030303030303030303",
    "amount_msat": 1250000,
    "layers": [],
    "maxfee_msat": 125000,
    "final_cltv": 0
  }
}

Response:

{
  "probability_ppm": 997501,
  "routes": [
    {
      "probability_ppm": 997501,
      "amount_msat": 1250000,
      "final_cltv": 0,
      "path": [
        {
          "short_channel_id_dir": "109x1x1/1",
          "next_node_id": "nodeid020202020202020202020202020202020202020202020202020202020202",
          "amount_msat": 1250026,
          "delay": 12
        },
        {
          "short_channel_id_dir": "123x1x1/0",
          "next_node_id": "nodeid030303030303030303030303030303030303030303030303030303030303",
          "amount_msat": 1250013,
          "delay": 6
        }
      ]
    }
  ]
}