forked from bitcoin-atom/lightning
-
Notifications
You must be signed in to change notification settings - Fork 0
/
lightning-getroute.7.txt
109 lines (84 loc) · 3.17 KB
/
lightning-getroute.7.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
LIGHTNING-GETROUTE(7)
=====================
:doctype: manpage
NAME
----
lightning-getroute - Protocol for routing a payment.
SYNOPSIS
--------
*getroute* 'id' 'msatoshi' 'riskfactor'
DESCRIPTION
-----------
The *getroute* RPC command attempts to find the best route for the payment
of 'msatoshi' to lightning node 'id'.
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 <[email protected]> is mainly responsible.
SEE ALSO
--------
lightning-listinvoice(7), lightning-delinvoice(7),
lightning-getroute(7), lightning-sendpay(7).
RESOURCES
---------
Main web site: https://github.com/ElementsProject/lightning