From 24a9bbfcd5507a1ab56f8ae8ebaf74f834085485 Mon Sep 17 00:00:00 2001 From: ZmnSCPxj Date: Fri, 16 Feb 2018 16:00:58 +0000 Subject: [PATCH] doc: Update manpage for getroute and pay for route randomization. --- doc/lightning-getroute.7 | 10 +++++++--- doc/lightning-getroute.7.txt | 15 ++++++++++++++- doc/lightning-pay.7 | 8 +++++--- doc/lightning-pay.7.txt | 6 ++++++ 4 files changed, 32 insertions(+), 7 deletions(-) diff --git a/doc/lightning-getroute.7 b/doc/lightning-getroute.7 index d5405be09e5e..546c403f529a 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/16/2018 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "LIGHTNING\-GETROUTE" "7" "01/16/2018" "\ \&" "\ \&" +.TH "LIGHTNING\-GETROUTE" "7" "02/16/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] [\fIinefficiency\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 \fIinefficiency\fR is a floating\-point number, between 0\&.0 to 1\&.0\&. The \fIinefficiency\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 1\&.0 means the fee used might be from 0 to twice the actual fee\&. The default is 0\&.0, which disables route randomization\&. +.sp +The \fIseed\fR is a string whose bytes are used to seed the RNG for the route randomization\&. If not specified, a fixed string is used; you should specify it if you have non\-zero \fIinefficiency\fR\&. .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 c321f62e5a86..926b20908956 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'] ['inefficiency'] ['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 'inefficiency' is a floating-point number, between 0.0 to 1.0. +The 'inefficiency' 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 1.0 means the fee used might be from 0 to twice the actual fee. +The default is 0.0, which disables route randomization. + +The 'seed' is a string whose bytes are used to seed the RNG for +the route randomization. +If not specified, a fixed string is used; +you should specify it if you have non-zero 'inefficiency'. + + 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 c64c94114c42..e2e5c5951370 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/11/2018 +.\" Date: 02/16/2018 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "LIGHTNING\-PAY" "7" "02/11/2018" "\ \&" "\ \&" +.TH "LIGHTNING\-PAY" "7" "02/16/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 405bc04d303e..1b103584fa79 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)