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

doc/lightning-getroute.7

@@ -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/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\&.

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,

doc/lightning-pay.7

@@ -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/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

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)