lukechilds
/
lightning
mirror of https://github.com/lukechilds/lightning.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
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.
8742 Commits
55 Branches
107 Tags
38 MiB
Tree: b2ec5a9f45
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'b2ec5a9f45'
${ noResults }
lightning/doc/lightning-getroute.7.md

306 lines
11 KiB
Raw Normal View History

docs: Update manpages to be recognized correctly by mrkd 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.
5 years ago
lightning-getroute -- Command for routing a payment (low-level)
===============================================================
doc/manpages: replace asciidoc by markdown
5 years ago
SYNOPSIS
--------
**getroute** *id* *msatoshi* *riskfactor* \[*cltv*\] \[*fromid*\]
\[*fuzzpercent*\] \[*exclude*\] \[*maxhops*\]
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).
*msatoshi* is in millisatoshi precision; it can be a whole number, or a
whole number ending in *msat* or *sat*, or a number with three decimal
places ending in *sat*, or a number with 1 to 11 decimal places ending
in *btc*.
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
wire: remove towire_double() Before this patch we used to send `double`s over the wire by just copying them. This is not portable because the internal represenation of a `double` is implementation specific. Instead of this, multiply any floating-point numbers that come from the outside (e.g. JSONs) by 1 million and round them to integers when handling them. * Introduce a new param_millionths() that expects a floating-point number and returns it multipled by 1000000 as an integer. * Replace param_double() and param_percent() with param_millionths() * Previously the riskfactor would be allowed to be negative, which must have been unintentional. This patch changes that to require a non-negative number. Changelog-None
5 years ago
node goes down during the process. The *riskfactor* non-negative
floating-point field controls this tradeoff; it is the annual cost of
your funds being stuck (as a percentage).
doc/manpages: replace asciidoc by markdown
5 years ago
For example, if you thought the convenience of keeping your funds liquid
(not stuck) was worth 20% per annum interest, *riskfactor* would be 20.
If you didn’t care about risk, *riskfactor* would be zero.
*fromid* is the node to start the route from: default is this node.
wire: remove towire_double() Before this patch we used to send `double`s over the wire by just copying them. This is not portable because the internal represenation of a `double` is implementation specific. Instead of this, multiply any floating-point numbers that come from the outside (e.g. JSONs) by 1 million and round them to integers when handling them. * Introduce a new param_millionths() that expects a floating-point number and returns it multipled by 1000000 as an integer. * Replace param_double() and param_percent() with param_millionths() * Previously the riskfactor would be allowed to be negative, which must have been unintentional. This patch changes that to require a non-negative number. Changelog-None
5 years ago
The *fuzzpercent* is a non-negative floating-point number, representing a
doc/manpages: replace asciidoc by markdown
5 years ago
percentage of the actual fee. The *fuzzpercent* 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.
*exclude* is a JSON array of short-channel-id/direction (e.g. \[
doc: Update the document of `getroute`about excluding nodes
5 years ago
"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.
doc/manpages: replace asciidoc by markdown
5 years ago
*maxhops* is the maximum number of channels to return; default is 20.
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:
risk-fee = amount x blocks-timeout x per-block-cost
We are given a *riskfactor* expressed as a percentage. There are 52596
blocks per year, thus *per-block-cost* is *riskfactor* divided by
5,259,600.
The final result is:
risk-fee = amount x blocks-timeout x riskfactor / 5259600
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.
<table>
<colgroup>
<col style="width: 20%" />
<col style="width: 20%" />
<col style="width: 20%" />
<col style="width: 20%" />
<col style="width: 20%" />
</colgroup>
<thead>
<tr class="header">
<th style="text-align: left;">Amount (msat)</th>
<th style="text-align: left;">Riskfactor</th>
<th style="text-align: left;">Delay</th>
<th style="text-align: left;">Risk Fee</th>
<th style="text-align: left;">Route fee</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;"><p>10,000</p></td>
<td style="text-align: left;"><p>1</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>0</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>10,000</p></td>
<td style="text-align: left;"><p>10</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>0</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>10,000</p></td>
<td style="text-align: left;"><p>100</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>2</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>10,000</p></td>
<td style="text-align: left;"><p>1000</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>26</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>1,000,000</p></td>
<td style="text-align: left;"><p>1</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>2</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>1,000,000</p></td>
<td style="text-align: left;"><p>10</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>26</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>1,000,000</p></td>
<td style="text-align: left;"><p>100</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>266</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>1,000,000</p></td>
<td style="text-align: left;"><p>1000</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>2661</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>100,000,000</p></td>
<td style="text-align: left;"><p>1</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>266</p></td>
<td style="text-align: left;"><p>1100</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>100,000,000</p></td>
<td style="text-align: left;"><p>10</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>2661</p></td>
<td style="text-align: left;"><p>1100</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>100,000,000</p></td>
<td style="text-align: left;"><p>100</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>26617</p></td>
<td style="text-align: left;"><p>1100</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>100,000,000</p></td>
<td style="text-align: left;"><p>1000</p></td>
<td style="text-align: left;"><p>14</p></td>
<td style="text-align: left;"><p>266179</p></td>
<td style="text-align: left;"><p>1100</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>10,000</p></td>
<td style="text-align: left;"><p>1</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>0</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>10,000</p></td>
<td style="text-align: left;"><p>10</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>2</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>10,000</p></td>
<td style="text-align: left;"><p>100</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>27</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>10,000</p></td>
<td style="text-align: left;"><p>1000</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>273</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>1,000,000</p></td>
<td style="text-align: left;"><p>1</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>27</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>1,000,000</p></td>
<td style="text-align: left;"><p>10</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>273</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>1,000,000</p></td>
<td style="text-align: left;"><p>100</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>2737</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>1,000,000</p></td>
<td style="text-align: left;"><p>1000</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>27378</p></td>
<td style="text-align: left;"><p>1001</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>100,000,000</p></td>
<td style="text-align: left;"><p>1</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>2737</p></td>
<td style="text-align: left;"><p>1100</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>100,000,000</p></td>
<td style="text-align: left;"><p>10</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>27378</p></td>
<td style="text-align: left;"><p>1100</p></td>
</tr>
<tr class="odd">
<td style="text-align: left;"><p>100,000,000</p></td>
<td style="text-align: left;"><p>100</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>273785</p></td>
<td style="text-align: left;"><p>1100</p></td>
</tr>
<tr class="even">
<td style="text-align: left;"><p>100,000,000</p></td>
<td style="text-align: left;"><p>1000</p></td>
<td style="text-align: left;"><p>144</p></td>
<td style="text-align: left;"><p>2737850</p></td>
<td style="text-align: left;"><p>1100</p></td>
</tr>
</tbody>
</table>
RECOMMENDED RISKFACTOR VALUES
-----------------------------
The default *fuzz* factor is 5%, so as you can see from the table above,
that tends to overwhelm the effect of *riskfactor* 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 lightning-pay(7) is 10, which starts to become a major
factor for larger amounts, and is basically ignored for tiny ones.
RETURN VALUE
------------
On success, a "route" array is returned. Each array element contains
*id* (the node being routed through), *msatoshi* (the millisatoshis
lightningd: expose/accept &#34;style&#34; parameter in routes. Default is legacy. If we have future styles, new strings can be defined, but for now it&#39;s &#34;tlv&#34; or &#34;legacy&#34;. Signed-off-by: Rusty Russell &lt;rusty@rustcorp.com.au&gt;
5 years ago
sent), *amount\_msat* (the same, with *msat* appended), *delay* (the
number of blocks to timeout at this node), and *style* (indicating
the features which can be used for this hop).
doc/manpages: replace asciidoc by markdown
5 years ago
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.
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>
doc: force refresh of all manpages. The idea is that you regenerate the man pages in the same commit you alter them: that&#39;s how we know whether to try regenerating them or not (git doesn&#39;t store timestamps, so it can&#39;t really tell). Travis will now check this, so force them all to sync to this commit. Signed-off-by: Rusty Russell &lt;rusty@rustcorp.com.au&gt;
4 years ago