From bbec8f62e0018f32c1cdccfad6be022fce2240a3 Mon Sep 17 00:00:00 2001
From: ZmnSCPxj <ZmnSCPxj@protonmail.com>
Date: Thu, 23 May 2019 12:19:05 +0000
Subject: [PATCH] doc/lightning-pay.7.txt: Remove references to value
 randomization, since it is no longer implemented, and describe shadow routes.

Fixes: #2659

Value randomization is not implemented since `pay` was made into a plugin.
Nobody has been asking for it, so do not implement it and just remove
from documentation.

Shadow routes is implemented, and not describe, so describe it now.
---
 doc/lightning-pay.7     | 10 +++++-----
 doc/lightning-pay.7.txt | 21 ++++++++++++---------
 2 files changed, 17 insertions(+), 14 deletions(-)

diff --git a/doc/lightning-pay.7 b/doc/lightning-pay.7
index ecdec7185..92760ef99 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 <http://docbook.sf.net/>
-.\"      Date: 05/22/2019
+.\"      Date: 05/23/2019
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "LIGHTNING\-PAY" "7" "05/22/2019" "\ \&" "\ \&"
+.TH "LIGHTNING\-PAY" "7" "05/23/2019" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -66,14 +66,14 @@ Route Randomization
 .sp -1
 .IP "  2." 4.2
 .\}
-Value Randomization
+Shadow Route
 .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\&.
+Shadow route means the payment algorithm will virtually extend the time delays along the route, making it appear to intermediate nodes that the route is longer than it actually is\&. This prevents intermediate nodes from reliably guessing their distance from the payee\&.
 .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\&.
+Route randomization will never exceed \fImaxfeepercent\fR of the payment\&. Route randomization and shadow routing 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 aaddc1f58..841d2e64b 100644
--- a/doc/lightning-pay.7.txt
+++ b/doc/lightning-pay.7.txt
@@ -52,7 +52,7 @@ RANDOMIZATION
 To protect user privacy, the payment algorithm performs some randomization.
 
 1. Route Randomization
-2. Value Randomization
+2. Shadow Route
 
 Route randomization means the payment algorithm
 does not always use the lowest-fee or shortest route.
@@ -61,16 +61,19 @@ 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.
+Shadow route means the payment algorithm
+will virtually extend the time delays
+along the route,
+making it appear to intermediate nodes
+that the route is longer than it actually is.
+This prevents intermediate nodes
+from reliably guessing their distance
+from the payee.
 
-Both randomizations respect 'maxfeepercent'.
-Route randomization plus the random value in value randomization
+Route randomization
 will never exceed 'maxfeepercent' of the payment.
-Route randomization will not take routes that would exceed 'maxdelay'.
+Route randomization and shadow routing
+will not take routes that would exceed 'maxdelay'.
 
 RETURN VALUE
 ------------