LIGHTNING-GETROUTE(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

💖 NAME 💖

lightning-getroute(7) is the manual page for getroute — the low-level command for routing a payment. Bestie, it's the “find me a route” tool, and yes, it's deprecated (more on that in a sec). 💅

✨ SYNOPSIS ✨

getroute id amount_msat riskfactor [cltv] [fromid] [fuzzpercent]
[exclude] [maxhops]

🎀 DESCRIPTION 🎀

Deprecation era: getroute was deprecated in v26.06 and removed after v27.03. Like, it's giving legacy API, bestie. 💀
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.

Okay so 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.

  • id (pubkey) — Node pubkey to find the best route for the payment.
  • 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. The 0 value is special: it ignores any htlc_minimum_msat setting on channels, and simply returns a possible route (if any) which is useful for simple probing.
  • riskfactor (u64) — A non-negative floating-point field controls this tradeoff; it is the annual cost of your funds being stuck (as a percentage). For example, if you thought the convenience of keeping your funds liquid (not stuck) was worth 20% per annum interest, riskfactor would be 20. If you didn't care about risk, riskfactor would be zero.
  • cltv (u32, optional) — Cltv-blocks to spare. The default is 9.
  • fromid (pubkey, optional) — The node to start the route from. The default is this node.
  • fuzzpercent (u32, optional) — Used to distort fees to provide some randomization to the route generated, but it was not properly implemented and is ignored. So yeah, it's just there being ignored, bestie. 🙈
  • exclude (array of strings, optional) — A JSON array of short-channel-id/direction (e.g. ['564334x877x1/0', '564195x1292x0/1' ]) or node-id which should be excluded from consideration for routing. Note if the source or destination is excluded, the command result is undefined. The default is not to exclude any channels or nodes:
    • (string, optional)
  • maxhops (u32, optional) — The maximum number of channels to return. The default is 20.

🔥 RISKFACTOR EFFECT ON ROUTING 🔥

The risk factor is treated as if it were an additional fee on the route, for the purposes of comparing routes.

The formula used is the following approximation:

risk-fee = amount x blocks-timeout x per-block-cost

We are given a riskfactor expressed as a percentage. There are 52596 blocks per year, thus per-block-cost is riskfactor divided by 5,259,600.

The final result is:

risk-fee = amount x blocks-timeout x riskfactor / 5259600

Here are the risk fees in millisatoshis, using various parameters. Assume a channel charges the default of 1000 millisatoshis plus 1 part-per-million. Common to_self_delay values on the network at 14 and 144 blocks.

  • Amount (msat): 10,000 · Riskfactor: 1 · Delay: 14 · Risk Fee: 0 · Route fee: 1001
  • Amount (msat): 10,000 · Riskfactor: 10 · Delay: 14 · Risk Fee: 0 · Route fee: 1001
  • Amount (msat): 10,000 · Riskfactor: 100 · Delay: 14 · Risk Fee: 2 · Route fee: 1001
  • Amount (msat): 10,000 · Riskfactor: 1000 · Delay: 14 · Risk Fee: 26 · Route fee: 1001
  • Amount (msat): 1,000,000 · Riskfactor: 1 · Delay: 14 · Risk Fee: 2 · Route fee: 1001
  • Amount (msat): 1,000,000 · Riskfactor: 10 · Delay: 14 · Risk Fee: 26 · Route fee: 1001
  • Amount (msat): 1,000,000 · Riskfactor: 100 · Delay: 14 · Risk Fee: 266 · Route fee: 1001
  • Amount (msat): 1,000,000 · Riskfactor: 1000 · Delay: 14 · Risk Fee: 2661 · Route fee: 1001
  • Amount (msat): 100,000,000 · Riskfactor: 1 · Delay: 14 · Risk Fee: 266 · Route fee: 1100
  • Amount (msat): 100,000,000 · Riskfactor: 10 · Delay: 14 · Risk Fee: 2661 · Route fee: 1100
  • Amount (msat): 100,000,000 · Riskfactor: 100 · Delay: 14 · Risk Fee: 26617 · Route fee: 1100
  • Amount (msat): 100,000,000 · Riskfactor: 1000 · Delay: 14 · Risk Fee: 266179 · Route fee: 1100
  • Amount (msat): 10,000 · Riskfactor: 1 · Delay: 144 · Risk Fee: 0 · Route fee: 1001
  • Amount (msat): 10,000 · Riskfactor: 10 · Delay: 144 · Risk Fee: 2 · Route fee: 1001
  • Amount (msat): 10,000 · Riskfactor: 100 · Delay: 144 · Risk Fee: 27 · Route fee: 1001
  • Amount (msat): 10,000 · Riskfactor: 1000 · Delay: 144 · Risk Fee: 273 · Route fee: 1001
  • Amount (msat): 1,000,000 · Riskfactor: 1 · Delay: 144 · Risk Fee: 27 · Route fee: 1001
  • Amount (msat): 1,000,000 · Riskfactor: 10 · Delay: 144 · Risk Fee: 273 · Route fee: 1001
  • Amount (msat): 1,000,000 · Riskfactor: 100 · Delay: 144 · Risk Fee: 2737 · Route fee: 1001
  • Amount (msat): 1,000,000 · Riskfactor: 1000 · Delay: 144 · Risk Fee: 27378 · Route fee: 1001
  • Amount (msat): 100,000,000 · Riskfactor: 1 · Delay: 144 · Risk Fee: 2737 · Route fee: 1100
  • Amount (msat): 100,000,000 · Riskfactor: 10 · Delay: 144 · Risk Fee: 27378 · Route fee: 1100
  • Amount (msat): 100,000,000 · Riskfactor: 100 · Delay: 144 · Risk Fee: 273785 · Route fee: 1100
  • Amount (msat): 100,000,000 · Riskfactor: 1000 · Delay: 144 · Risk Fee: 2737850 · Route fee: 1100

ok so quick vibe check on what number to actually put in there 💅

The default fuzz factor is 5%, which means — as you can literally see from the table above — it tends to overwhelm the effect of any riskfactor less than about 5. like, your riskfactor is fighting for its life against the fuzz and losing 😭

  • 1 — the conservative pick 🎀 for a stable lightning network with very few failures.
  • 1000 — the aggressive pick 🔥 for when you're trying to minimize timeouts at all costs. no thoughts, just speed.

The default for lightning-pay(7) is 10, which starts to become a major factor for larger amounts, and is basically ignored for tiny ones. iykyk ✨

💖 RETURN VALUE 💖

On success, you get back an object containing route. It's an array of objects (yes bestie, an array of objects, buckle up), and each object contains:

  • id (pubkey) — the node at the end of this hop 🧚
  • channel (short_channel_id) — the channel joining these nodes
  • direction (u32) — 0 if this channel is traversed from lesser to greater id, otherwise 1
  • amount_msat (msat) — the amount expected by the node at the end of this hop
  • delay (u32) — the total CLTV expected by the node at the end of this hop
  • style (string) (always "tlv") — the features understood by the destination node

The final id will be the destination id given in the input. The difference between the first amount_msat minus the amount_msat given in the input is the fee (assuming the first hop is free). The first delay is the very worst case timeout for the payment failure, in blocks. periodt 🌸

👑 AUTHOR 👑

Rusty Russell rusty@rustcorp.com.au is mainly responsible. king behaviour fr fr 💜

🦋 SEE ALSO 🦋

🌈 RESOURCES 🌈

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

⭐ EXAMPLES ⭐

🌸 Example 1

Request:

$ lightning-cli getroute -k "id"="nodeid030303030303030303030303030303030303030303030303030303030303" "amount_msat"=10000 "riskfactor"=1
{
  "id": "example:getroute#1",
  "method": "getroute",
  "params": {
    "id": "nodeid030303030303030303030303030303030303030303030303030303030303",
    "amount_msat": 10000,
    "riskfactor": 1
  }
}

Response:

{
  "route": [
    {
      "id": "nodeid020202020202020202020202020202020202020202020202020202020202",
      "channel": "109x1x1",
      "direction": 1,
      "amount_msat": 10001,
      "delay": 15,
      "style": "tlv"
    },
    {
      "id": "nodeid030303030303030303030303030303030303030303030303030303030303",
      "channel": "111x1x1",
      "direction": 0,
      "amount_msat": 10000,
      "delay": 9,
      "style": "tlv"
    }
  ]
}

🎀 Example 2

Request:

$ lightning-cli getroute -k "id"="nodeid040404040404040404040404040404040404040404040404040404040404" "amount_msat"=500000 "riskfactor"=10 "cltv"=9
{
  "id": "example:getroute#2",
  "method": "getroute",
  "params": {
    "id": "nodeid040404040404040404040404040404040404040404040404040404040404",
    "amount_msat": 500000,
    "riskfactor": 10,
    "cltv": 9
  }
}

Response:

{
  "route": [
    {
      "id": "nodeid030303030303030303030303030303030303030303030303030303030303",
      "channel": "111x1x1",
      "direction": 0,
      "amount_msat": 500006,
      "delay": 15,
      "style": "tlv"
    },
    {
      "id": "nodeid040404040404040404040404040404040404040404040404040404040404",
      "channel": "125x1x1",
      "direction": 0,
      "amount_msat": 500000,
      "delay": 9,
      "style": "tlv"
    }
  ]
}

ok that's literally the whole page bestie, go route something iconic 💅✨ This one's from Core Lightning v26.06.9, and you're reading LIGHTNING-GETROUTE(7) — screenshot it, frame it, send it to the group chat 🫶💖

📦 where this page comes from