Repository: lightningnetwork/lnd (language: go)

Issue:
[feature]: more clearly define the `payment_addr` field in all documentation
`lncli addinvoice` yields a `payment_addr` field. When using `lncli sendpayment` and manually specifying a payment, a `pay_addr` field is required. Similarly for `lncli buildroute`, we must pass a `payment_addr` in order for `lncli sendtoroute ` to actually work with the route that was built. What is this parameter for? I can't find it in any BOLTS.

I "think" it is supposed to be the `payment_secret`, which is mentioned here https://github.com/lightning/bolts/blob/master/04-onion-routing.md#payload-for-the-last-node and https://github.com/lightning/bolts/blob/master/11-payment-encoding.md#tagged-fields . Also, https://github.com/lightning/bolts/pull/643#discussion_r318941367 suggests a `payment_address` parameter, which I think is the same thing.

If I run `lncli addinvoice` and put the `payment_request` output into https://www.bolt11.org/ the `payment_secret` seems to match the `payment_addr`.

Please clarify the documentation so that so much interrogation isn't required to understand the `payment_addr` field.


Discussion / hints:
+1

I just spent at least 20 minutes figuring out that `payment_addr` corresponds to `payment_secret` in the spec.  `payment_secret` shows up nowhere in the LND source code.
I want to work on this issue. I have recently found this repo so I'll be asking very basic questions like how do i get started. So can anyone please explain me what I am supposed to do?  I think in documentation payment_secret is being used instead of 
payment_addr? so we need to clarify difference between these two terms if there any. correct me if I am wrong 
I think a good starting point would be to add a comment to all `*.proto` files in `lnrpc/` where a `payment_addr` field appears. Maybe something along the lines of `This field is also called "payment_secret" in other contexts.`
Also make sure to read our [contribution guidelines](https://github.com/lightningnetwork/lnd/blob/master/docs/code_contribution_guidelines.md), [formatting guides](https://github.com/lightningnetwork/lnd/blob/master/docs/code_formatting_rules.md) and our [pull request checklist](https://github.com/lightningnetwork/lnd/blob/master/.github/pull_request_template.md)

Fix patch:
diff --git a/lnrpc/invoicesrpc/invoices.pb.go b/lnrpc/invoicesrpc/invoices.pb.go
index afd8d33a62..cfb561377e 100644
--- a/lnrpc/invoicesrpc/invoices.pb.go
+++ b/lnrpc/invoicesrpc/invoices.pb.go
@@ -317,8 +317,9 @@ type AddHoldInvoiceResp struct {
 	// SubscribeInvoices call can use this to instantly get notified of all added
 	// invoices with an add_index greater than this one.
 	AddIndex uint64 `protobuf:"varint,2,opt,name=add_index,json=addIndex,proto3" json:"add_index,omitempty"`
-	// The payment address of the generated invoice. This value should be used
-	// in all payments for this invoice as we require it for end to end
+	// The payment address of the generated invoice. This is also called
+	// the payment secret in specifications (e.g. BOLT 11). This value should
+	// be used in all payments for this invoice as we require it for end to end
 	// security.
 	PaymentAddr []byte `protobuf:"bytes,3,opt,name=payment_addr,json=paymentAddr,proto3" json:"payment_addr,omitempty"`
 }
diff --git a/lnrpc/invoicesrpc/invoices.proto b/lnrpc/invoicesrpc/invoices.proto
index 441f668d26..7afffba4e3 100644
--- a/lnrpc/invoicesrpc/invoices.proto
+++ b/lnrpc/invoicesrpc/invoices.proto
@@ -138,8 +138,9 @@ message AddHoldInvoiceResp {
     uint64 add_index = 2;
 
     /*
-    The payment address of the generated invoice. This value should be used
-    in all payments for this invoice as we require it for end to end
+    The payment address of the generated invoice. This is also called
+    the payment secret in specifications (e.g. BOLT 11). This value should
+    be used in all payments for this invoice as we require it for end to end
     security.
     */
     bytes payment_addr = 3;
diff --git a/lnrpc/invoicesrpc/invoices.swagger.json b/lnrpc/invoicesrpc/invoices.swagger.json
index eaf51fd896..b54d9fb38e 100644
--- a/lnrpc/invoicesrpc/invoices.swagger.json
+++ b/lnrpc/invoicesrpc/invoices.swagger.json
@@ -300,7 +300,7 @@
         "payment_addr": {
           "type": "string",
           "format": "byte",
-          "description": "The payment address of the generated invoice. This value should be used\nin all payments for this invoice as we require it for end to end\nsecurity."
+          "description": "The payment address of the generated invoice. This is also called\nthe payment secret in specifications (e.g. BOLT 11). This value should\nbe used in all payments for this invoice as we require it for end to end\nsecurity."
         }
       }
     },
@@ -565,7 +565,7 @@
         "payment_addr": {
           "type": "string",
           "format": "byte",
-          "description": "The payment address of this invoice. This value will be used in MPP\npayments, and also for newer invoices that always require the MPP payload\nfor added end-to-end security.\nNote: Output only, don't specify for creating an invoice."
+          "description": "The payment address of this invoice. This is also called payment secret in\nspecifications (e.g. BOLT 11). This value will be used in MPP payments, and\nalso for newer invoices that always require the MPP payload for added\nend-to-end security.\nNote: Output only, don't specify for creating an invoice."
         },
         "is_amp": {
           "type": "boolean",
diff --git a/lnrpc/lightning.pb.go b/lnrpc/lightning.pb.go
index 8095e547d3..b9425529d7 100644
--- a/lnrpc/lightning.pb.go
+++ b/lnrpc/lightning.pb.go
@@ -2258,7 +2258,8 @@ type SendRequest struct {
 	// the router will try to load destination features from the graph as a
 	// fallback.
 	DestFeatures []FeatureBit `protobuf:"varint,15,rep,packed,name=dest_features,json=destFeatures,proto3,enum=lnrpc.FeatureBit" json:"dest_features,omitempty"`
-	// The payment address of the generated invoice.
+	// The payment address of the generated invoice.  This is also called
+	// payment secret in specifications (e.g. BOLT 11).
 	PaymentAddr []byte `protobuf:"bytes,16,opt,name=payment_addr,json=paymentAddr,proto3" json:"payment_addr,omitempty"`
 }
 
@@ -10128,7 +10129,8 @@ type MPPRecord struct {
 	// A unique, random identifier used to authenticate the sender as the intended
 	// payer of a multi-path payment. The payment_addr must be the same for all
 	// subpayments, and match the payment_addr provided in the receiver's invoice.
-	// The same payment_addr must be used on all subpayments.
+	// The same payment_addr must be used on all subpayments. This is also called
+	// payment secret in specifications (e.g. BOLT 11).
 	PaymentAddr []byte `protobuf:"bytes,11,opt,name=payment_addr,json=paymentAddr,proto3" json:"payment_addr,omitempty"`
 	// The total amount in milli-satoshis being sent as part of a larger multi-path
 	// payment. The caller is responsible for ensuring subpayments to the same node
@@ -12396,9 +12398,10 @@ type Invoice struct {
 	// [EXPERIMENTAL].
 	// Note: Output only, don't specify for creating an invoice.
 	IsKeysend bool `protobuf:"varint,25,opt,name=is_keysend,json=isKeysend,proto3" json:"is_keysend,omitempty"`
-	// The payment address of this invoice. This value will be used in MPP
-	// payments, and also for newer invoices that always require the MPP payload
-	// for added end-to-end security.
+	// The payment address of this invoice. This is also called payment secret in
+	// specifications (e.g. BOLT 11). This value will be used in MPP payments, and
+	// also for newer invoices that always require the MPP payload for added
+	// end-to-end security.
 	// Note: Output only, don't specify for creating an invoice.
 	PaymentAddr []byte `protobuf:"bytes,26,opt,name=payment_addr,json=paymentAddr,proto3" json:"payment_addr,omitempty"`
 	// Signals whether or not this is an AMP invoice.
@@ -12879,9 +12882,9 @@ type AddInvoiceResponse struct {
 	// SubscribeInvoices call can use this to instantly get notified of all added
 	// invoices with an add_index greater than this one.
 	AddIndex uint64 `protobuf:"varint,16,opt,name=add_index,json=addIndex,proto3" json:"add_index,omitempty"`
-	// The payment address of the generated invoice. This value should be used
-	// in all payments for this invoice as we require it for end to end
-	// security.
+	// The payment address of the generated invoice. This is also called
+	// payment secret in specifications (e.g. BOLT 11). This value should be used
+	// in all payments for this invoice as we require it for end to end security.
 	PaymentAddr []byte `protobuf:"bytes,17,opt,name=payment_addr,json=paymentAddr,proto3" json:"payment_addr,omitempty"`
 }
 
diff --git a/lnrpc/lightning.proto b/lnrpc/lightning.proto
index 1d01850d1a..e0107e97b4 100644
--- a/lnrpc/lightning.proto
+++ b/lnrpc/lightning.proto
@@ -884,7 +884,8 @@ message SendRequest {
     repeated FeatureBit dest_features = 15;
 
     /*
-    The payment address of the generated invoice.
+    The payment address of the generated invoice.  This is also called
+    payment secret in specifications (e.g. BOLT 11).
     */
     bytes payment_addr = 16;
 }
@@ -3197,7 +3198,8 @@ message MPPRecord {
     A unique, random identifier used to authenticate the sender as the intended
     payer of a multi-path payment. The payment_addr must be the same for all
     subpayments, and match the payment_addr provided in the receiver's invoice.
-    The same payment_addr must be used on all subpayments.
+    The same payment_addr must be used on all subpayments. This is also called
+    payment secret in specifications (e.g. BOLT 11).
     */
     bytes payment_addr = 11;
 
@@ -3776,9 +3778,10 @@ message Invoice {
     bool is_keysend = 25;
 
     /*
-    The payment address of this invoice. This value will be used in MPP
-    payments, and also for newer invoices that always require the MPP payload
-    for added end-to-end security.
+    The payment address of this invoice. This is also called payment secret in
+    specifications (e.g. BOLT 11). This value will be used in MPP payments, and
+    also for newer invoices that always require the MPP payload for added
+    end-to-end security.
     Note: Output only, don't specify for creating an invoice.
     */
     bytes payment_addr = 26;
@@ -3883,9 +3886,9 @@ message AddInvoiceResponse {
     uint64 add_index = 16;
 
     /*
-    The payment address of the generated invoice. This value should be used
-    in all payments for this invoice as we require it for end to end
-    security.
+    The payment address of the generated invoice. This is also called
+    payment secret in specifications (e.g. BOLT 11). This value should be used
+    in all payments for this invoice as we require it for end to end security.
     */
     bytes payment_addr = 17;
 }
diff --git a/lnrpc/lightning.swagger.json b/lnrpc/lightning.swagger.json
index a7567031f1..e5821994a9 100644
--- a/lnrpc/lightning.swagger.json
+++ b/lnrpc/lightning.swagger.json
@@ -3250,7 +3250,7 @@
         "payment_addr": {
           "type": "string",
           "format": "byte",
-          "description": "The payment address of the generated invoice. This value should be used\nin all payments for this invoice as we require it for end to end\nsecurity."
+          "description": "The payment address of the generated invoice. This is also called\npayment secret in specifications (e.g. BOLT 11). This value should be used\nin all payments for this invoice as we require it for end to end security."
         }
       }
     },
@@ -5407,7 +5407,7 @@
         "payment_addr": {
           "type": "string",
           "format": "byte",
-          "description": "The payment address of this invoice. This value will be used in MPP\npayments, and also for newer invoices that always require the MPP payload\nfor added end-to-end security.\nNote: Output only, don't specify for creating an invoice."
+          "description": "The payment address of this invoice. This is also called payment secret in\nspecifications (e.g. BOLT 11). This value will be used in MPP payments, and\nalso for newer invoices that always require the MPP payload for added\nend-to-end security.\nNote: Output only, don't specify for creating an invoice."
         },
         "is_amp": {
           "type": "boolean",
@@ -5715,7 +5715,7 @@
         "payment_addr": {
           "type": "string",
           "format": "byte",
-          "description": "A unique, random identifier used to authenticate the sender as the intended\npayer of a multi-path payment. The payment_addr must be the same for all\nsubpayments, and match the payment_addr provided in the receiver's invoice.\nThe same payment_addr must be used on all subpayments."
+          "description": "A unique, random identifier used to authenticate the sender as the intended\npayer of a multi-path payment. The payment_addr must be the same for all\nsubpayments, and match the payment_addr provided in the receiver's invoice.\nThe same payment_addr must be used on all subpayments. This is also called\npayment secret in specifications (e.g. BOLT 11)."
         },
         "total_amt_msat": {
           "type": "string",
@@ -7052,7 +7052,7 @@
         "payment_addr": {
           "type": "string",
           "format": "byte",
-          "description": "The payment address of the generated invoice."
+          "description": "The payment address of the generated invoice.  This is also called\npayment secret in specifications (e.g. BOLT 11)."
         }
       }
     },
diff --git a/lnrpc/routerrpc/router.pb.go b/lnrpc/routerrpc/router.pb.go
index f56414cf44..2b869b7ebb 100644
--- a/lnrpc/routerrpc/router.pb.go
+++ b/lnrpc/routerrpc/router.pb.go
@@ -480,6 +480,7 @@ type SendPaymentRequest struct {
 	// any channel may be used.
 	OutgoingChanIds []uint64 `protobuf:"varint,19,rep,packed,name=outgoing_chan_ids,json=outgoingChanIds,proto3" json:"outgoing_chan_ids,omitempty"`
 	// An optional payment addr to be included within the last hop of the route.
+	// This is also called payment secret in specifications (e.g. BOLT 11).
 	PaymentAddr []byte `protobuf:"bytes,20,opt,name=payment_addr,json=paymentAddr,proto3" json:"payment_addr,omitempty"`
 	// The largest payment split that should be attempted when making a payment if
 	// splitting is necessary. Setting this value will effectively cause lnd to
@@ -2099,6 +2100,7 @@ type BuildRouteRequest struct {
 	// pubkey.
 	HopPubkeys [][]byte `protobuf:"bytes,4,rep,name=hop_pubkeys,json=hopPubkeys,proto3" json:"hop_pubkeys,omitempty"`
 	// An optional payment addr to be included within the last hop of the route.
+	// This is also called payment secret in specifications (e.g. BOLT 11).
 	PaymentAddr []byte `protobuf:"bytes,5,opt,name=payment_addr,json=paymentAddr,proto3" json:"payment_addr,omitempty"`
 }
 
diff --git a/lnrpc/routerrpc/router.proto b/lnrpc/routerrpc/router.proto
index 5766d22415..de57bfaa29 100644
--- a/lnrpc/routerrpc/router.proto
+++ b/lnrpc/routerrpc/router.proto
@@ -306,7 +306,10 @@ message SendPaymentRequest {
     */
     repeated uint64 outgoing_chan_ids = 19;
 
-    // An optional payment addr to be included within the last hop of the route.
+    /*
+    An optional payment addr to be included within the last hop of the route.
+    This is also called payment secret in specifications (e.g. BOLT 11).
+    */
     bytes payment_addr = 20;
 
     /*
@@ -659,7 +662,10 @@ message BuildRouteRequest {
     */
     repeated bytes hop_pubkeys = 4;
 
-    // An optional payment addr to be included within the last hop of the route.
+    /*
+    An optional payment addr to be included within the last hop of the route.
+    This is also called payment secret in specifications (e.g. BOLT 11).
+    */
     bytes payment_addr = 5;
 }
 
diff --git a/lnrpc/routerrpc/router.swagger.json b/lnrpc/routerrpc/router.swagger.json
index 9c8962bae1..2a163d030c 100644
--- a/lnrpc/routerrpc/router.swagger.json
+++ b/lnrpc/routerrpc/router.swagger.json
@@ -927,7 +927,7 @@
         "payment_addr": {
           "type": "string",
           "format": "byte",
-          "description": "A unique, random identifier used to authenticate the sender as the intended\npayer of a multi-path payment. The payment_addr must be the same for all\nsubpayments, and match the payment_addr provided in the receiver's invoice.\nThe same payment_addr must be used on all subpayments."
+          "description": "A unique, random identifier used to authenticate the sender as the intended\npayer of a multi-path payment. The payment_addr must be the same for all\nsubpayments, and match the payment_addr provided in the receiver's invoice.\nThe same payment_addr must be used on all subpayments. This is also called\npayment secret in specifications (e.g. BOLT 11)."
         },
         "total_amt_msat": {
           "type": "string",
@@ -1173,7 +1173,7 @@
         "payment_addr": {
           "type": "string",
           "format": "byte",
-          "description": "An optional payment addr to be included within the last hop of the route."
+          "description": "An optional payment addr to be included within the last hop of the route.\nThis is also called payment secret in specifications (e.g. BOLT 11)."
         }
       }
     },
@@ -1774,7 +1774,7 @@
         "payment_addr": {
           "type": "string",
           "format": "byte",
-          "description": "An optional payment addr to be included within the last hop of the route."
+          "description": "An optional payment addr to be included within the last hop of the route.\nThis is also called payment secret in specifications (e.g. BOLT 11)."
         },
         "max_shard_size_msat": {
           "type": "string",


Test patch: