You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

110 lines
3.2 KiB

LIGHTNING-GETROUTE(7)
=====================
:doctype: manpage
NAME
----
lightning-getroute - Protocol for routing a payment (low-level).
SYNOPSIS
--------
*getroute* 'id' 'msatoshi' 'riskfactor' ['cltv']
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).
There are two considerations for how good a route is: how low the
fees are, and how long your payment will get stuck 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), multiplied by the percentage chance of each node failing.
For example, if you thought there was a 1% chance that a node would
fail, and it would cost you 20% per annum if that happened,
'riskfactor' would be 20.
If you didn't care about risk, 'riskfactor' would be zero.
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:
----
hop-risk = num-hops x per-hop-risk
timeout-cost = blocks-timeout x per-block-cost
risk-fee = amount x hop-risk x timeout-cost
----
We are given a 'riskfactor'; expressed as two multiplied percentages
is the same as fractions multiplied by 10000. There are 52596 blocks
per year, thus 'per-block-cost' x 'per-hop-risk' is riskfactor'
divided by 5,259,600,000.
The final result is:
----
risk-fee = amount x num-hops x blocks-timeout x riskfactor / 5259600000
----
Here are the risk fees as a percentage of the amount sent, using
various parameters. For comparison with actual fees, we assume nodes
charge 0.05%:
[options="header"]
|=======================
|Riskfactor |Nodes | Delay per node |Risk Fee % |Route fee %
|0.001 |5 | 6 |0 |0.25
|1 |5 | 6 |0 |0.25
|1000 |5 | 6 |0.0029 |0.25
|0.001 |10 | 72 |0 |0.5
|1 |10 | 72 |0.0001 |0.5
|1000 |10 | 72 |0.1369 |0.5
|0.001 |20 | 1008 |0 |1.0
|1 |20 | 1008 |0.0077 |1.0
|1000 |20 | 1008 |7.6660 |1.0
|=======================
RECOMMENDED RISKFACTOR VALUES
-----------------------------
0.001 is a value for tie-breaking in favor of shorter routes, but not really
costing in any risk.
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.
RETURN VALUE
------------
On success, a "route" array is returned. Each array element contains
{id} (the node being routed through), {msatoshi} (the millisatoshis
sent), 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