lightning-getroute – Command for routing a payment (low-level)

SYNOPSIS

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

DESCRIPTION

The getroute RPC command attempts to find the best route for the payment of msatoshi to lightning node id, such that the payment will arrive at id with cltv-blocks to spare (default 9).

msatoshi is in millisatoshi precision; 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.

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. The riskfactor 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.

fromid is the node to start the route from: default is this node.

The fuzzpercent is a positive floating-point number, representing a percentage of the actual fee. The fuzzpercent is used to distort computed fees along each channel, to provide some randomization to the route generated. 0.0 means the exact fee of that channel is used, while 100.0 means the fee used might be from 0 to twice the actual fee. The default is 5.0, or up to 5% fee distortion.

exclude is 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. The default is not to exclude any channels or nodes. Note if the source or destination is excluded, the command result is undefined.

maxhops is the maximum number of channels to return; 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. I 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) Riskfactor Delay Risk Fee Route fee

10,000

1

14

0

1001

10,000

10

14

0

1001

10,000

100

14

2

1001

10,000

1000

14

26

1001

1,000,000

1

14

2

1001

1,000,000

10

14

26

1001

1,000,000

100

14

266

1001

1,000,000

1000

14

2661

1001

100,000,000

1

14

266

1100

100,000,000

10

14

2661

1100

100,000,000

100

14

26617

1100

100,000,000

1000

14

266179

1100

10,000

1

144

0

1001

10,000

10

144

2

1001

10,000

100

144

27

1001

10,000

1000

144

273

1001

1,000,000

1

144

27

1001

1,000,000

10

144

273

1001

1,000,000

100

144

2737

1001

1,000,000

1000

144

27378

1001

100,000,000

1

144

2737

1100

100,000,000

10

144

27378

1100

100,000,000

100

144

273785

1100

100,000,000

1000

144

2737850

1100

RETURN VALUE

On success, a “route” array is returned. Each array element contains id (the node being routed through), msatoshi (the millisatoshis sent), amount_msat (the same, with msat appended), delay (the number of blocks to timeout at this node), and style (indicating the features which can be used for this hop).

The final id will be the destination id given in the input. The difference between the first msatoshi minus the msatoshi given in the input is the fee. The first delay is the very worst case timeout for the payment failure, in blocks.

AUTHOR

Rusty Russell <rusty@rustcorp.com.au> is mainly responsible.

SEE ALSO

lightning-pay(7), lightning-sendpay(7).