mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2024-11-19 09:54:16 +01:00
Code Issues Projects Releases Wiki Activity

doc: Update manpage for getroute and pay for route randomization.

Browse Source
This commit is contained in:
ZmnSCPxj 2018-02-16 16:00:58 +00:00 committed by Rusty Russell
parent 61d0b50c54
commit 1cf32f9f05
4 changed files with 32 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
doc/lightning-getroute.7
View File

@ -2,12 +2,12 @@
.\" Title: lightning-getroute
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\" Date: 01/16/2018
.\" Date: 02/19/2018
.\" Manual: \ \&
.\" Source: \ \&
.\" Language: English
.\"
.TH "LIGHTNING\-GETROUTE" "7" "01/16/2018" "\ \&" "\ \&"
.TH "LIGHTNING\-GETROUTE" "7" "02/19/2018" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
@ -31,7 +31,7 @@
lightning-getroute \- Protocol for routing a payment (low\-level)\&.
.SH "SYNOPSIS"
.sp
\fBgetroute\fR \fIid\fR \fImsatoshi\fR \fIriskfactor\fR [\fIcltv\fR]
\fBgetroute\fR \fIid\fR \fImsatoshi\fR \fIriskfactor\fR [\fIcltv\fR] [\fIfuzzpercent\fR] [\fIseed\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)\&.
@ -41,6 +41,10 @@ There are two considerations for how good a route is: how low the fees are, and
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, \fIriskfactor\fR would be 20\&.
.sp
If you didn\(cqt care about risk, \fIriskfactor\fR would be zero\&.
.sp
The \fIfuzzpercent\fR is a floating\-point number, between 0\&.0 to 100\&.0, unit of percent\&. 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
The \fIseed\fR is a string whose bytes are used to seed the RNG for the route randomization\&. If not specified, a random string is used\&.
.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\&.

15
doc/lightning-getroute.7.txt
View File

@ -9,7 +9,7 @@ lightning-getroute - Protocol for routing a payment (low-level).
SYNOPSIS
--------
*getroute* 'id' 'msatoshi' 'riskfactor' ['cltv']
*getroute* 'id' 'msatoshi' 'riskfactor' ['cltv'] ['fuzzpercent'] ['seed']
DESCRIPTION
-----------
@ -29,6 +29,19 @@ fail, and it would cost you 20% per annum if that happened,
If you didn't care about risk, 'riskfactor' would be zero.
The 'fuzzpercent' is a floating-point number, between 0.0 to 100.0,
unit of percent.
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.
The 'seed' is a string whose bytes are used to seed the RNG for
the route randomization.
If not specified, a random string is used.
RISKFACTOR EFFECT ON ROUTING
----------------------------
The risk factor is treated as if it were an additional fee on the route,

8
doc/lightning-pay.7
View File

@ -2,12 +2,12 @@
.\" Title: lightning-pay
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\" Date: 02/17/2018
.\" Date: 02/19/2018
.\" Manual: \ \&
.\" Source: \ \&
.\" Language: English
.\"
.TH "LIGHTNING\-PAY" "7" "02/17/2018" "\ \&" "\ \&"
.TH "LIGHTNING\-PAY" "7" "02/19/2018" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
@ -36,12 +36,14 @@ lightning-pay \- Protocol for sending a payment to a BOLT11 invoice
.sp
The \fBpay\fR RPC command attempts to find a route to the given destination, and send the funds it asks for\&. If the \fIbolt11\fR does not contain an amount, \fImsatoshi\fR is required, otherwise if it is specified it must be \fInull\fR\&. If \fIbolt11\fR contains a description hash (\fIh\fR field) \fIdescription\fR is required, otherwise it is unused\&. The \fIriskfactor\fR is described in detail in lightning\-getroute(7), and defaults to 1\&.0\&. The \fImaxfeepercent\fR limits the money paid in fees, and defaults to 0\&.5\&. The \(oqmaxfeepercent\(cq is a percentage of the amount that is to be paid\&.
.sp
The \fBpay\fR RPC command will randomize routes slightly, as long as the route achieves the targeted \fImaxfeepercent\fR\&.
.sp
The response will occur when the payment fails or succeeds\&. Once a payment has succeeded, calls to \fBpay\fR with the same \fIbolt11\fR will succeed immediately\&.
.sp
When using \fIlightning\-cli\fR, you may skip optional parameters by using \fInull\fR\&. Alternatively, use \fB\-k\fR option to provide parameters by name\&.
.SH "RETURN VALUE"
.sp
On success, this returns the payment \fIpreimage\fR which hashes to the \fIpayment_hash\fR to prove that the payment was successful\&.
On success, this returns the payment \fIpreimage\fR which hashes to the \fIpayment_hash\fR to prove that the payment was successful\&. It will also return, a \fIgetroute_tries\fR and a \fIsendpay_tries\fR statistics for the number of times it internally called \fBgetroute\fR and \fBsendpay\fR\&.
.sp
On error, if the error occurred from a node other than the final destination, the route table will be updated so that getroute(7) should return an alternate route (if any)\&. An error from the final destination implies the payment should not be retried\&.
.sp

6
doc/lightning-pay.7.txt
View File

@ -23,6 +23,9 @@ The 'maxfeepercent' limits the money paid in fees, and defaults to 0.5.
The `maxfeepercent' is a percentage of the amount that is to be
paid.
The *pay* RPC command will randomize routes slightly, as long as the
route achieves the targeted 'maxfeepercent'.
The response will occur when the payment fails or succeeds. Once a
payment has succeeded, calls to *pay* with the same 'bolt11' will
succeed immediately.
@ -36,6 +39,9 @@ RETURN VALUE
On success, this returns the payment 'preimage' which hashes to the
'payment_hash' to prove that the payment was successful.
It will also return, a 'getroute_tries' and a 'sendpay_tries'
statistics for the number of times it internally called *getroute*
and *sendpay*.
On error, if the error occurred from a node other than the final
destination, the route table will be updated so that getroute(7)