mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-19 18:11:28 +01:00
6d1897b796
They render the comment as if it's in the list. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
151 lines
4.6 KiB
Groff
Generated
151 lines
4.6 KiB
Groff
Generated
.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 non-negative
|
||
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 non-negative 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" ]) or node-id which should be excluded
|
||
from consideration for routing\. The default is not to exclude any channels
|
||
or nodes\. Note if the source or destination is excluded, the command result
|
||
is undefined\.
|
||
|
||
|
||
\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, an object containing \fBroute\fR is returned\. It is an array of objects, where each object contains:
|
||
|
||
.RS
|
||
.IP \[bu]
|
||
\fBid\fR (pubkey): The node at the end of this hop
|
||
.IP \[bu]
|
||
\fBchannel\fR (short_channel_id): The channel joining these nodes
|
||
.IP \[bu]
|
||
\fBdirection\fR (u32): 0 if this channel is traversed from lesser to greater \fBid\fR, otherwise 1
|
||
.IP \[bu]
|
||
\fBamount_msat\fR (msat): The amount expected by the node at the end of this hop
|
||
.IP \[bu]
|
||
\fBdelay\fR (u32): The total CLTV expected by the node at the end of this hop
|
||
.IP \[bu]
|
||
\fBstyle\fR (string): The features understood by the destination node (one of "legacy", "tlv")
|
||
|
||
.RE
|
||
|
||
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 (assuming the first hop is free)\. 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
|
||
|
||
\" SHA256STAMP:fc6982d81943e6d235a9cfd1584573e3dd4e4da369ffc9da8e3c5fc2e3726370
|