From e74349c506a348fc18f250b15246f6d2793e93e3 Mon Sep 17 00:00:00 2001 From: ZmnSCPxj Date: Sun, 25 Nov 2018 23:37:58 +0000 Subject: [PATCH] doc/lightning-pay.7.txt: Clarify randomization by `pay` command. --- doc/lightning-pay.7 | 39 ++++++++++++++++++++++++++++++++++----- doc/lightning-pay.7.txt | 31 +++++++++++++++++++++++++++---- 2 files changed, 61 insertions(+), 9 deletions(-) diff --git a/doc/lightning-pay.7 b/doc/lightning-pay.7 index fd1ef7ad8..1983dbab3 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: 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\&. diff --git a/doc/lightning-pay.7.txt b/doc/lightning-pay.7.txt index c2dde8c10..04e830f65 100644 --- a/doc/lightning-pay.7.txt +++ b/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 ------------