b0da807700
This commit will remove parameter descriptions from RPC markdown but we will fix it in next commits by reading these descriptions directly from json. - Removing parameter description text - Adding/removing newlines for cleaner formatting - Adding ERRORS title wherever needed - Updating titles for consistency - Adding resources links
9.6 KiB
lightning-getroute -- Command for routing a payment (low-level)
SYNOPSIS
getroute id amount_msat riskfactor [cltv] [fromid] [fuzzpercent] [exclude] [maxhops]
DESCRIPTION
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.
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 |
RECOMMENDED RISKFACTOR VALUES
The default fuzz factor is 5%, so as you can see from the table above, that tends to overwhelm the effect of riskfactor less than about 5.
1 is a conservative value for a stable lightning network with very few failures.
1000 is an aggressive value for trying to minimize timeouts at all costs.
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.
RETURN VALUE
On success, an object containing route is returned. It is an array of objects, where 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): The features understood by the destination node (always "tlv")
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.
AUTHOR
Rusty Russell <rusty@rustcorp.com.au> is mainly responsible.
SEE ALSO
lightning-pay(7), lightning-sendpay(7).
RESOURCES
Main web site: https://github.com/ElementsProject/lightning