mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-20 10:39:49 +01:00
533 lines
7.6 KiB
Groff
533 lines
7.6 KiB
Groff
'\" t
|
|
.\" Title: lightning-getroute
|
|
.\" Author: [see the "AUTHOR" section]
|
|
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
|
|
.\" Date: 03/01/2019
|
|
.\" Manual: \ \&
|
|
.\" Source: \ \&
|
|
.\" Language: English
|
|
.\"
|
|
.TH "LIGHTNING\-GETROUTE" "7" "03/01/2019" "\ \&" "\ \&"
|
|
.\" -----------------------------------------------------------------
|
|
.\" * Define some portability stuff
|
|
.\" -----------------------------------------------------------------
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
.\" http://bugs.debian.org/507673
|
|
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\" -----------------------------------------------------------------
|
|
.\" * set default formatting
|
|
.\" -----------------------------------------------------------------
|
|
.\" disable hyphenation
|
|
.nh
|
|
.\" disable justification (adjust text to left margin only)
|
|
.ad l
|
|
.\" -----------------------------------------------------------------
|
|
.\" * MAIN CONTENT STARTS HERE *
|
|
.\" -----------------------------------------------------------------
|
|
.SH "NAME"
|
|
lightning-getroute \- Command for routing a payment (low\-level)\&.
|
|
.SH "SYNOPSIS"
|
|
.sp
|
|
\fBgetroute\fR \fIid\fR \fImsatoshi\fR \fIriskfactor\fR [\fIcltv\fR] [\fIfromid\fR] [\fIfuzzpercent\fR] [\fIexclude\fR] [\fImaxhops\fR]
|
|
.SH "DESCRIPTION"
|
|
.sp
|
|
The \fBgetroute\fR RPC command attempts to find the best route for the payment of \fImsatoshi\fR to lightning node \fIid\fR, such that the payment will arrive at \fIid\fR with \fIcltv\fR\-blocks to spare (default 9)\&.
|
|
.sp
|
|
\fImsatoshi\fR is in millisatoshi precision; it can be a whole number, or a whole number ending in \fImsat\fR or \fIsat\fR, or a number with three decimal places ending in \fIsat\fR, or a number with 1 to 11 decimal places ending in \fIbtc\fR\&.
|
|
.sp
|
|
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 \fIriskfactor\fR floating\-point field controls this tradeoff; it is the annual cost of your funds being stuck (as a percentage)\&.
|
|
.sp
|
|
For example, if you thought the convenience of keeping your funds liquid (not stuck) was worth 20% per annum interest, \fIriskfactor\fR would be 20\&.
|
|
.sp
|
|
If you didn\(cqt care about risk, \fIriskfactor\fR would be zero\&.
|
|
.sp
|
|
\fIfromid\fR is the node to start the route from: default is this node\&.
|
|
.sp
|
|
The \fIfuzzpercent\fR is a positive floating\-point number, representing a percentage of the actual fee\&. The \fIfuzzpercent\fR 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\&.
|
|
.sp
|
|
\fIexclude\fR 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\&.
|
|
.sp
|
|
\fImaxhops\fR is the maximum number of channels to return; default is 20\&.
|
|
.SH "RISKFACTOR EFFECT ON ROUTING"
|
|
.sp
|
|
The risk factor is treated as if it were an additional fee on the route, for the purposes of comparing routes\&.
|
|
.sp
|
|
The formula used is the following approximation:
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
risk\-fee = amount x blocks\-timeout x per\-block\-cost
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
We are given a \fIriskfactor\fR expressed as a percentage\&. There are 52596 blocks per year, thus \fIper\-block\-cost\fR is \fIriskfactor\fR divided by 5,259,600\&.
|
|
.sp
|
|
The final result is:
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
risk\-fee = amount x blocks\-timeout x riskfactor / 5259600
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
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\&.
|
|
.TS
|
|
allbox tab(:);
|
|
ltB ltB ltB ltB ltB.
|
|
T{
|
|
Amount (msat)
|
|
T}:T{
|
|
Riskfactor
|
|
T}:T{
|
|
Delay
|
|
T}:T{
|
|
Risk Fee
|
|
T}:T{
|
|
Route fee
|
|
T}
|
|
.T&
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt
|
|
lt lt lt lt lt.
|
|
T{
|
|
.sp
|
|
10,000
|
|
T}:T{
|
|
.sp
|
|
1
|
|
T}:T{
|
|
.sp
|
|
14
|
|
T}:T{
|
|
.sp
|
|
0
|
|
T}:T{
|
|
.sp
|
|
1001
|
|
T}
|
|
T{
|
|
.sp
|
|
10,000
|
|
T}:T{
|
|
.sp
|
|
10
|
|
T}:T{
|
|
.sp
|
|
14
|
|
T}:T{
|
|
.sp
|
|
0
|
|
T}:T{
|
|
.sp
|
|
1001
|
|
T}
|
|
T{
|
|
.sp
|
|
10,000
|
|
T}:T{
|
|
.sp
|
|
100
|
|
T}:T{
|
|
.sp
|
|
14
|
|
T}:T{
|
|
.sp
|
|
2
|
|
T}:T{
|
|
.sp
|
|
1001
|
|
T}
|
|
T{
|
|
.sp
|
|
10,000
|
|
T}:T{
|
|
.sp
|
|
1000
|
|
T}:T{
|
|
.sp
|
|
14
|
|
T}:T{
|
|
.sp
|
|
26
|
|
T}:T{
|
|
.sp
|
|
1001
|
|
T}
|
|
T{
|
|
.sp
|
|
1,000,000
|
|
T}:T{
|
|
.sp
|
|
1
|
|
T}:T{
|
|
.sp
|
|
14
|
|
T}:T{
|
|
.sp
|
|
2
|
|
T}:T{
|
|
.sp
|
|
1001
|
|
T}
|
|
T{
|
|
.sp
|
|
1,000,000
|
|
T}:T{
|
|
.sp
|
|
10
|
|
T}:T{
|
|
.sp
|
|
14
|
|
T}:T{
|
|
.sp
|
|
26
|
|
T}:T{
|
|
.sp
|
|
1001
|
|
T}
|
|
T{
|
|
.sp
|
|
1,000,000
|
|
T}:T{
|
|
.sp
|
|
100
|
|
T}:T{
|
|
.sp
|
|
14
|
|
T}:T{
|
|
.sp
|
|
266
|
|
T}:T{
|
|
.sp
|
|
1001
|
|
T}
|
|
T{
|
|
.sp
|
|
1,000,000
|
|
T}:T{
|
|
.sp
|
|
1000
|
|
T}:T{
|
|
.sp
|
|
14
|
|
T}:T{
|
|
.sp
|
|
2661
|
|
T}:T{
|
|
.sp
|
|
1001
|
|
T}
|
|
T{
|
|
.sp
|
|
100,000,000
|
|
T}:T{
|
|
.sp
|
|
1
|
|
T}:T{
|
|
.sp
|
|
14
|
|
T}:T{
|
|
.sp
|
|
266
|
|
T}:T{
|
|
.sp
|
|
1100
|
|
T}
|
|
T{
|
|
.sp
|
|
100,000,000
|
|
T}:T{
|
|
.sp
|
|
10
|
|
T}:T{
|
|
.sp
|
|
14
|
|
T}:T{
|
|
.sp
|
|
2661
|
|
T}:T{
|
|
.sp
|
|
1100
|
|
T}
|
|
T{
|
|
.sp
|
|
100,000,000
|
|
T}:T{
|
|
.sp
|
|
100
|
|
T}:T{
|
|
.sp
|
|
14
|
|
T}:T{
|
|
.sp
|
|
26617
|
|
T}:T{
|
|
.sp
|
|
1100
|
|
T}
|
|
T{
|
|
.sp
|
|
100,000,000
|
|
T}:T{
|
|
.sp
|
|
1000
|
|
T}:T{
|
|
.sp
|
|
14
|
|
T}:T{
|
|
.sp
|
|
266179
|
|
T}:T{
|
|
.sp
|
|
1100
|
|
T}
|
|
T{
|
|
.sp
|
|
10,000
|
|
T}:T{
|
|
.sp
|
|
1
|
|
T}:T{
|
|
.sp
|
|
144
|
|
T}:T{
|
|
.sp
|
|
0
|
|
T}:T{
|
|
.sp
|
|
1001
|
|
T}
|
|
T{
|
|
.sp
|
|
10,000
|
|
T}:T{
|
|
.sp
|
|
10
|
|
T}:T{
|
|
.sp
|
|
144
|
|
T}:T{
|
|
.sp
|
|
2
|
|
T}:T{
|
|
.sp
|
|
1001
|
|
T}
|
|
T{
|
|
.sp
|
|
10,000
|
|
T}:T{
|
|
.sp
|
|
100
|
|
T}:T{
|
|
.sp
|
|
144
|
|
T}:T{
|
|
.sp
|
|
27
|
|
T}:T{
|
|
.sp
|
|
1001
|
|
T}
|
|
T{
|
|
.sp
|
|
10,000
|
|
T}:T{
|
|
.sp
|
|
1000
|
|
T}:T{
|
|
.sp
|
|
144
|
|
T}:T{
|
|
.sp
|
|
273
|
|
T}:T{
|
|
.sp
|
|
1001
|
|
T}
|
|
T{
|
|
.sp
|
|
1,000,000
|
|
T}:T{
|
|
.sp
|
|
1
|
|
T}:T{
|
|
.sp
|
|
144
|
|
T}:T{
|
|
.sp
|
|
27
|
|
T}:T{
|
|
.sp
|
|
1001
|
|
T}
|
|
T{
|
|
.sp
|
|
1,000,000
|
|
T}:T{
|
|
.sp
|
|
10
|
|
T}:T{
|
|
.sp
|
|
144
|
|
T}:T{
|
|
.sp
|
|
273
|
|
T}:T{
|
|
.sp
|
|
1001
|
|
T}
|
|
T{
|
|
.sp
|
|
1,000,000
|
|
T}:T{
|
|
.sp
|
|
100
|
|
T}:T{
|
|
.sp
|
|
144
|
|
T}:T{
|
|
.sp
|
|
2737
|
|
T}:T{
|
|
.sp
|
|
1001
|
|
T}
|
|
T{
|
|
.sp
|
|
1,000,000
|
|
T}:T{
|
|
.sp
|
|
1000
|
|
T}:T{
|
|
.sp
|
|
144
|
|
T}:T{
|
|
.sp
|
|
27378
|
|
T}:T{
|
|
.sp
|
|
1001
|
|
T}
|
|
T{
|
|
.sp
|
|
100,000,000
|
|
T}:T{
|
|
.sp
|
|
1
|
|
T}:T{
|
|
.sp
|
|
144
|
|
T}:T{
|
|
.sp
|
|
2737
|
|
T}:T{
|
|
.sp
|
|
1100
|
|
T}
|
|
T{
|
|
.sp
|
|
100,000,000
|
|
T}:T{
|
|
.sp
|
|
10
|
|
T}:T{
|
|
.sp
|
|
144
|
|
T}:T{
|
|
.sp
|
|
27378
|
|
T}:T{
|
|
.sp
|
|
1100
|
|
T}
|
|
T{
|
|
.sp
|
|
100,000,000
|
|
T}:T{
|
|
.sp
|
|
100
|
|
T}:T{
|
|
.sp
|
|
144
|
|
T}:T{
|
|
.sp
|
|
273785
|
|
T}:T{
|
|
.sp
|
|
1100
|
|
T}
|
|
T{
|
|
.sp
|
|
100,000,000
|
|
T}:T{
|
|
.sp
|
|
1000
|
|
T}:T{
|
|
.sp
|
|
144
|
|
T}:T{
|
|
.sp
|
|
2737850
|
|
T}:T{
|
|
.sp
|
|
1100
|
|
T}
|
|
.TE
|
|
.sp 1
|
|
.SH "RECOMMENDED RISKFACTOR VALUES"
|
|
.sp
|
|
The default \fIfuzz\fR factor is 5%, so as you can see from the table above, that tends to overwhelm the effect of \fIriskfactor\fR less than about 5\&.
|
|
.sp
|
|
1 is a conservative value for a stable lightning network with very few failures\&.
|
|
.sp
|
|
1000 is an aggressive value for trying to minimize timeouts at all costs\&.
|
|
.sp
|
|
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\&.
|
|
.SH "RETURN VALUE"
|
|
.sp
|
|
On success, a "route" array is returned\&. Each array element contains \fIid\fR (the node being routed through), \fImsatoshi\fR (the millisatoshis sent), \fIamount_msat\fR (the same, with \fImsat\fR appended), and \fIdelay\fR (the number of blocks to timeout at this node)\&.
|
|
.sp
|
|
The final \fIid\fR will be the destination \fIid\fR given in the input\&. The difference between the first \fImsatoshi\fR minus the \fImsatoshi\fR given in the input is the fee\&. The first \fIdelay\fR is the very worst case timeout for the payment failure, in blocks\&.
|
|
.SH "AUTHOR"
|
|
.sp
|
|
Rusty Russell <rusty@rustcorp\&.com\&.au> is mainly responsible\&.
|
|
.SH "SEE ALSO"
|
|
.sp
|
|
lightning\-pay(7), lightning\-sendpay(7)\&.
|
|
.SH "RESOURCES"
|
|
.sp
|
|
Main web site: https://github\&.com/ElementsProject/lightning
|