diff --git a/doc/lightning-getroute.7 b/doc/lightning-getroute.7 index d5405be09..e26a7b060 100644 --- a/doc/lightning-getroute.7 +++ b/doc/lightning-getroute.7 @@ -2,12 +2,12 @@ .\" Title: lightning-getroute .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.79.1 -.\" 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\&. diff --git a/doc/lightning-getroute.7.txt b/doc/lightning-getroute.7.txt index c321f62e5..8cdd6fadc 100644 --- a/doc/lightning-getroute.7.txt +++ b/doc/lightning-getroute.7.txt @@ -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, diff --git a/doc/lightning-pay.7 b/doc/lightning-pay.7 index c0cbfc099..39d169ba3 100644 --- a/doc/lightning-pay.7 +++ b/doc/lightning-pay.7 @@ -2,12 +2,12 @@ .\" Title: lightning-pay .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.79.1 -.\" 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 diff --git a/doc/lightning-pay.7.txt b/doc/lightning-pay.7.txt index a9b019c39..73053a94d 100644 --- a/doc/lightning-pay.7.txt +++ b/doc/lightning-pay.7.txt @@ -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)