Merge pull request #6641 from priyanshiiit/invoice_params

lnrpc: improves invoice documentation

Author: guggero

lnrpc/invoicesrpc/invoices.swagger.json

@@ -452,7 +452,7 @@
         "r_hash": {
           "type": "string",
           "format": "byte",
-          "description": "The hash of the preimage. When using REST, this field must be encoded as\nbase64."
+          "description": "The hash of the preimage. When using REST, this field must be encoded as\nbase64.\nNote: Output only, don't specify for creating an invoice."
         },
         "value": {
           "type": "string",
@@ -473,16 +473,16 @@
         "creation_date": {
           "type": "string",
           "format": "int64",
-          "title": "When this invoice was created"
+          "description": "When this invoice was created.\nNote: Output only, don't specify for creating an invoice."
         },
         "settle_date": {
           "type": "string",
           "format": "int64",
-          "title": "When this invoice was settled"
+          "description": "When this invoice was settled.\nNote: Output only, don't specify for creating an invoice."
         },
         "payment_request": {
           "type": "string",
-          "description": "A bare-bones invoice for a payment within the Lightning Network. With the\ndetails of the invoice, the sender has all the data necessary to send a\npayment to the recipient."
+          "description": "A bare-bones invoice for a payment within the Lightning Network. With the\ndetails of the invoice, the sender has all the data necessary to send a\npayment to the recipient.\nNote: Output only, don't specify for creating an invoice."
         },
         "description_hash": {
           "type": "string",
@@ -517,12 +517,12 @@
         "add_index": {
           "type": "string",
           "format": "uint64",
-          "description": "The \"add\" index of this invoice. Each newly created invoice will increment\nthis index making it monotonically increasing. Callers to the\nSubscribeInvoices call can use this to instantly get notified of all added\ninvoices with an add_index greater than this one."
+          "description": "The \"add\" index of this invoice. Each newly created invoice will increment\nthis index making it monotonically increasing. Callers to the\nSubscribeInvoices call can use this to instantly get notified of all added\ninvoices with an add_index greater than this one.\nNote: Output only, don't specify for creating an invoice."
         },
         "settle_index": {
           "type": "string",
           "format": "uint64",
-          "description": "The \"settle\" index of this invoice. Each newly settled invoice will\nincrement this index making it monotonically increasing. Callers to the\nSubscribeInvoices call can use this to instantly get notified of all\nsettled invoices with an settle_index greater than this one."
+          "description": "The \"settle\" index of this invoice. Each newly settled invoice will\nincrement this index making it monotonically increasing. Callers to the\nSubscribeInvoices call can use this to instantly get notified of all\nsettled invoices with an settle_index greater than this one.\nNote: Output only, don't specify for creating an invoice."
         },
         "amt_paid": {
           "type": "string",
@@ -532,39 +532,39 @@
         "amt_paid_sat": {
           "type": "string",
           "format": "int64",
-          "description": "The amount that was accepted for this invoice, in satoshis. This will ONLY\nbe set if this invoice has been settled. We provide this field as if the\ninvoice was created with a zero value, then we need to record what amount\nwas ultimately accepted. Additionally, it's possible that the sender paid\nMORE that was specified in the original invoice. So we'll record that here\nas well."
+          "description": "The amount that was accepted for this invoice, in satoshis. This will ONLY\nbe set if this invoice has been settled. We provide this field as if the\ninvoice was created with a zero value, then we need to record what amount\nwas ultimately accepted. Additionally, it's possible that the sender paid\nMORE that was specified in the original invoice. So we'll record that here\nas well.\nNote: Output only, don't specify for creating an invoice."
         },
         "amt_paid_msat": {
           "type": "string",
           "format": "int64",
-          "description": "The amount that was accepted for this invoice, in millisatoshis. This will\nONLY be set if this invoice has been settled. We provide this field as if\nthe invoice was created with a zero value, then we need to record what\namount was ultimately accepted. Additionally, it's possible that the sender\npaid MORE that was specified in the original invoice. So we'll record that\nhere as well."
+          "description": "The amount that was accepted for this invoice, in millisatoshis. This will\nONLY be set if this invoice has been settled. We provide this field as if\nthe invoice was created with a zero value, then we need to record what\namount was ultimately accepted. Additionally, it's possible that the sender\npaid MORE that was specified in the original invoice. So we'll record that\nhere as well.\nNote: Output only, don't specify for creating an invoice."
         },
         "state": {
           "$ref": "#/definitions/InvoiceInvoiceState",
-          "description": "The state the invoice is in."
+          "description": "The state the invoice is in.\nNote: Output only, don't specify for creating an invoice."
         },
         "htlcs": {
           "type": "array",
           "items": {
             "$ref": "#/definitions/lnrpcInvoiceHTLC"
           },
-          "description": "List of HTLCs paying to this invoice [EXPERIMENTAL]."
+          "description": "List of HTLCs paying to this invoice [EXPERIMENTAL].\nNote: Output only, don't specify for creating an invoice."
         },
         "features": {
           "type": "object",
           "additionalProperties": {
             "$ref": "#/definitions/lnrpcFeature"
           },
-          "description": "List of features advertised on the invoice."
+          "description": "List of features advertised on the invoice.\nNote: Output only, don't specify for creating an invoice."
         },
         "is_keysend": {
           "type": "boolean",
-          "description": "Indicates if this invoice was a spontaneous payment that arrived via keysend\n[EXPERIMENTAL]."
+          "description": "Indicates if this invoice was a spontaneous payment that arrived via keysend\n[EXPERIMENTAL].\nNote: Output only, don't specify for creating an invoice."
         },
         "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."
+          "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."
         },
         "is_amp": {
           "type": "boolean",
@@ -575,7 +575,7 @@
           "additionalProperties": {
             "$ref": "#/definitions/lnrpcAMPInvoiceState"
           },
-          "description": "Maps a 32-byte hex-encoded set ID to the sub-invoice AMP state for the\ngiven set ID. This field is always populated for AMP invoices, and can be\nused along side LookupInvoice to obtain the HTLC information related to a\ngiven sub-invoice.",
+          "description": "Maps a 32-byte hex-encoded set ID to the sub-invoice AMP state for the\ngiven set ID. This field is always populated for AMP invoices, and can be\nused along side LookupInvoice to obtain the HTLC information related to a\ngiven sub-invoice.\nNote: Output only, don't specify for creating an invoice.",
           "title": "[EXPERIMENTAL]:"
         }
       }

lnrpc/lightning.pb.go

@@ -3171,6 +3171,7 @@ message Invoice {
     /*
     The hash of the preimage. When using REST, this field must be encoded as
     base64.
+    Note: Output only, don't specify for creating an invoice.
     */
     bytes r_hash = 4;
 
@@ -3191,16 +3192,23 @@ message Invoice {
     // Whether this invoice has been fulfilled
     bool settled = 6 [deprecated = true];
 
-    // When this invoice was created
+    /*
+    When this invoice was created.
+    Note: Output only, don't specify for creating an invoice.
+    */
     int64 creation_date = 7;
 
-    // When this invoice was settled
+    /*
+    When this invoice was settled.
+    Note: Output only, don't specify for creating an invoice.
+    */
     int64 settle_date = 8;
 
     /*
     A bare-bones invoice for a payment within the Lightning Network. With the
     details of the invoice, the sender has all the data necessary to send a
     payment to the recipient.
+    Note: Output only, don't specify for creating an invoice.
     */
     string payment_request = 9;
 
@@ -3235,6 +3243,7 @@ message Invoice {
     this index making it monotonically increasing. Callers to the
     SubscribeInvoices call can use this to instantly get notified of all added
     invoices with an add_index greater than this one.
+    Note: Output only, don't specify for creating an invoice.
     */
     uint64 add_index = 16;
 
@@ -3243,6 +3252,7 @@ message Invoice {
     increment this index making it monotonically increasing. Callers to the
     SubscribeInvoices call can use this to instantly get notified of all
     settled invoices with an settle_index greater than this one.
+    Note: Output only, don't specify for creating an invoice.
     */
     uint64 settle_index = 17;
 
@@ -3256,6 +3266,7 @@ message Invoice {
     was ultimately accepted. Additionally, it's possible that the sender paid
     MORE that was specified in the original invoice. So we'll record that here
     as well.
+    Note: Output only, don't specify for creating an invoice.
     */
     int64 amt_paid_sat = 19;
 
@@ -3266,6 +3277,7 @@ message Invoice {
     amount was ultimately accepted. Additionally, it's possible that the sender
     paid MORE that was specified in the original invoice. So we'll record that
     here as well.
+    Note: Output only, don't specify for creating an invoice.
     */
     int64 amt_paid_msat = 20;
 
@@ -3278,25 +3290,34 @@ message Invoice {
 
     /*
     The state the invoice is in.
+    Note: Output only, don't specify for creating an invoice.
     */
     InvoiceState state = 21;
 
-    // List of HTLCs paying to this invoice [EXPERIMENTAL].
+    /*
+    List of HTLCs paying to this invoice [EXPERIMENTAL].
+    Note: Output only, don't specify for creating an invoice.
+    */
     repeated InvoiceHTLC htlcs = 22;
 
-    // List of features advertised on the invoice.
+    /*
+    List of features advertised on the invoice.
+    Note: Output only, don't specify for creating an invoice.
+    */
     map<uint32, Feature> features = 24;
 
     /*
     Indicates if this invoice was a spontaneous payment that arrived via keysend
     [EXPERIMENTAL].
+    Note: Output only, don't specify for creating an 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.
+    Note: Output only, don't specify for creating an invoice.
     */
     bytes payment_addr = 26;
 
@@ -3312,6 +3333,7 @@ message Invoice {
     given set ID. This field is always populated for AMP invoices, and can be
     used along side LookupInvoice to obtain the HTLC information related to a
     given sub-invoice.
+    Note: Output only, don't specify for creating an invoice.
     */
     map<string, AMPInvoiceState> amp_invoice_state = 28;
 }