doc/lightning-pay.7.txt: Clarify randomization by pay command.

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: 09/07/2018
+.\"      Date: 11/26/2018
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "LIGHTNING\-PAY" "7" "09/07/2018" "\ \&" "\ \&"
+.TH "LIGHTNING\-PAY" "7" "11/26/2018" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -31,18 +31,47 @@
 lightning-pay \- Command for sending a payment to a BOLT11 invoice
 .SH "SYNOPSIS"
 .sp
-\fBpay\fR \fIbolt11\fR [\fImsatoshi\fR] [\fIdescription\fR] [\fIriskfactor\fR] [\fImaxfeepercent\fR] [\fIretry_for\fR] [\fImaxdelay\fR]
+\fBpay\fR \fIbolt11\fR [\fImsatoshi\fR] [\fIdescription\fR] [\fIriskfactor\fR] [\fImaxfeepercent\fR] [\fIretry_for\fR] [\fImaxdelay\fR] [\fIexemptfee\fR]
 .SH "DESCRIPTION"
 .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 maxfeepercent\*(Aq is a percentage of the amount that is to be paid\&. The `exemptfee option can be used for tiny payments which would be dominated by the fee leveraged by forwarding nodes\&. Setting exemptfee allows the maxfeepercent check to be skipped on fees that are smaller than exemptfee (default: 5000 millisatoshi)\&.
 .sp
-The \fBpay\fR RPC command will randomize routes slightly, as long as the route achieves the targeted \fImaxfeepercent\fR and \fImaxdelay\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
 The command will keep finding routes and retrying the payment until it succeeds, or the given \fIretry_for\fR seconds passes\&. Note that the command may stop retrying while a pending payment is ongoing, which you need to monitor with \fBlistpayments\fR or \fBwaitsendpay\fR\&. \fIretry_for\fR defaults to 60 seconds and can only be an integer\&.
 .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 "RANDOMIZATION"
+.sp
+To protect user privacy, the payment algorithm performs some randomization\&.
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  1." 4.2
+.\}
+Route Randomization
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+.sp -1
+.IP "  2." 4.2
+.\}
+Value Randomization
+.RE
+.sp
+Route randomization means the payment algorithm does not always use the lowest\-fee or shortest route\&. This prevents some highly\-connected node from learning all of the user payments by reducing their fees below the network average\&.
+.sp
+Value randomization means the payment algorithm will add a small random amount to the actual value paid to the destination\&. This prevents intervening nodes from identifying exactly how much is being transacted\&.
+.sp
+Both randomizations respect \fImaxfeepercent\fR\&. Route randomization plus the random value in value randomization will never exceed \fImaxfeepercent\fR of the payment\&. Route randomization will not take routes that would exceed \fImaxdelay\fR\&.
 .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\&. 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\&.

doc/lightning-pay.7.txt

@@ -8,7 +8,7 @@ lightning-pay - Command for sending a payment to a BOLT11 invoice
 
 SYNOPSIS
 --------
-*pay* 'bolt11' ['msatoshi'] ['description'] ['riskfactor'] ['maxfeepercent'] ['retry_for'] ['maxdelay']
+*pay* 'bolt11' ['msatoshi'] ['description'] ['riskfactor'] ['maxfeepercent'] ['retry_for'] ['maxdelay'] ['exemptfee']
 
 DESCRIPTION
 -----------
@@ -27,9 +27,6 @@ the fee leveraged by forwarding nodes. Setting `exemptfee` allows the
 `maxfeepercent` check to be skipped on fees that are smaller than `exemptfee`
 (default: 5000 millisatoshi).
 
-The *pay* RPC command will randomize routes slightly, as long as the
-route achieves the targeted 'maxfeepercent' and 'maxdelay'.
-
 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.
@@ -44,6 +41,32 @@ When using 'lightning-cli', you may skip optional parameters by using
 'null'.
 Alternatively, use *-k* option to provide parameters by name.
 
+RANDOMIZATION
+-------------
+
+To protect user privacy, the payment algorithm performs some randomization.
+
+1. Route Randomization
+2. Value Randomization
+
+Route randomization means the payment algorithm
+does not always use the lowest-fee or shortest route.
+This prevents some highly-connected node
+from learning all of the user payments
+by reducing their fees below
+the network average.
+
+Value randomization means the payment algorithm
+will add a small random amount to the actual value
+paid to the destination.
+This prevents intervening nodes
+from identifying exactly how much is being transacted.
+
+Both randomizations respect 'maxfeepercent'.
+Route randomization plus the random value in value randomization
+will never exceed 'maxfeepercent' of the payment.
+Route randomization will not take routes that would exceed 'maxdelay'.
+
 RETURN VALUE
 ------------