mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-19 18:11:28 +01:00
c3254e6639
mrkd started enforcing the `name -- short description` style of top-level headings somewhere, and was thus failing to build the man-pages. I swapped the title and with the existing short description to make it work again. `mrkd` will automatically infer the section from the filename so no need to put it in the title as well. In addition I removed the "last updated" lines at the bottom since they are out of date at best, and misleading at the worst. If we want to keep them, I'd suggest generating them from the commit that last touched them.
135 lines
4.0 KiB
Groff
135 lines
4.0 KiB
Groff
.TH "LIGHTNING-GETROUTE" "7" "" "" "lightning-getroute"
|
||
.SH NAME
|
||
lightning-getroute - Command for routing a payment (low-level)
|
||
.SH SYNOPSIS
|
||
|
||
\fBgetroute\fR \fIid\fR \fImsatoshi\fR \fIriskfactor\fR [\fIcltv\fR] [\fIfromid\fR]
|
||
[\fIfuzzpercent\fR] [\fIexclude\fR] [\fImaxhops\fR]
|
||
|
||
.SH DESCRIPTION
|
||
|
||
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)\.
|
||
|
||
|
||
\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\.
|
||
|
||
|
||
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)\.
|
||
|
||
|
||
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\.
|
||
|
||
|
||
If you didn’t care about risk, \fIriskfactor\fR would be zero\.
|
||
|
||
|
||
\fIfromid\fR is the node to start the route from: default is this node\.
|
||
|
||
|
||
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\.
|
||
|
||
|
||
\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\.
|
||
|
||
|
||
\fImaxhops\fR is the maximum number of channels to return; default is 20\.
|
||
|
||
.SH 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:
|
||
|
||
.nf
|
||
.RS
|
||
risk-fee = amount x blocks-timeout x per-block-cost
|
||
|
||
|
||
.RE
|
||
|
||
.fi
|
||
|
||
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\.
|
||
|
||
|
||
The final result is:
|
||
|
||
.nf
|
||
.RS
|
||
risk-fee = amount x blocks-timeout x riskfactor / 5259600
|
||
|
||
|
||
.RE
|
||
|
||
.fi
|
||
|
||
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\.
|
||
|
||
|
||
.SH RECOMMENDED RISKFACTOR VALUES
|
||
|
||
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\.
|
||
|
||
|
||
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 \fBlightning-pay\fR(7) is 10, which starts to become a major
|
||
factor for larger amounts, and is basically ignored for tiny ones\.
|
||
|
||
.SH RETURN VALUE
|
||
|
||
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)\.
|
||
|
||
|
||
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
|
||
|
||
Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
|
||
|
||
.SH SEE ALSO
|
||
|
||
\fBlightning-pay\fR(7), \fBlightning-sendpay\fR(7)\.
|
||
|
||
.SH RESOURCES
|
||
|
||
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
|
||
|