lnrpc: Clarify payment_addr and payment_secret

tdb3 · tdb3 · commit 3288490df3ab · 2024-02-13T19:04:18.000-05:00
Fix #7438, adding clarification statements in lnrpc proto files. Originally proposed by daredevil3435 in PR #7873 and PR #7885.
diff --git a/lnrpc/invoicesrpc/invoices.pb.go b/lnrpc/invoicesrpc/invoices.pb.go
diff --git 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
@@ -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
diff --git 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
@@ -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
diff --git 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
@@ -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",
