mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-20 10:39:49 +01:00
145 lines
4.8 KiB
Plaintext
145 lines
4.8 KiB
Plaintext
LIGHTNING-GETROUTE(7)
|
|
=====================
|
|
:doctype: manpage
|
|
|
|
NAME
|
|
----
|
|
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" ]) which should be excluded from consideration for routing. The default is not to exclude any channels.
|
|
|
|
'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.
|
|
|
|
[options="header"]
|
|
|=======================
|
|
|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, 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), and 'delay' (the number of blocks to timeout at this
|
|
node).
|
|
|
|
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.
|
|
|
|
//FIXME:Enumerate errors
|
|
|
|
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
|