lightningd: expose created_index and updated_index fields.

If you miss a wait event, you can catch up by doing listinvoices and getting the max of these fields. It's also a good debugging clue. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2025-12-24 01:24:26 +01:00 · 2023-07-22 20:29:17 +09:30
parent 284262d006
commit d25a8ca0fd
27 changed files with 559 additions and 325 deletions
--- a/doc/lightning-createinvoice.7.md
+++ b/doc/lightning-createinvoice.7.md
@@ -38,6 +38,7 @@ On success, an object is returned, containing:
 - **status** (string): Whether it has been paid, or can no longer be paid (one of "paid", "expired", "unpaid")
 - **description** (string): Description extracted from **bolt11** or **bolt12**
 - **expires\_at** (u64): UNIX timestamp of when invoice expires (or expired)
+- **created\_index** (u64): 1-based index indicating order this invoice was created in *(added v23.08)*
 - **bolt11** (string, optional): the bolt11 string (always present unless **bolt12** is)
 - **bolt12** (string, optional): the bolt12 string instead of **bolt11** (**experimental-offers** only)
 - **amount\_msat** (msat, optional): The amount of the invoice (if it has one)
@@ -75,4 +76,4 @@ RESOURCES

 Main web site: <https://github.com/ElementsProject/lightning>

-[comment]: # ( SHA256STAMP:fffebe36aa6671261082894e8b1429035c08f797064a60b03e3e9ea10ea71038)
+[comment]: # ( SHA256STAMP:2d2180c9e903e2b79d5ddb2b0cf995b1f7aa27b0f9bb1f6e19252b94dcd46ef1)
--- a/doc/lightning-delinvoice.7.md
+++ b/doc/lightning-delinvoice.7.md
@@ -29,12 +29,14 @@ On success, an object is returned, containing:

 - **label** (string): Unique label given at creation time
 - **payment\_hash** (hash): the hash of the *payment\_preimage* which will prove payment
+- **created\_index** (u64): 1-based index indicating order this invoice was created in *(added v23.08)*
 - **status** (string): State of invoice (one of "paid", "expired", "unpaid")
 - **expires\_at** (u64): UNIX timestamp when invoice expires (or expired)
 - **bolt11** (string, optional): BOLT11 string
 - **bolt12** (string, optional): BOLT12 string
 - **amount\_msat** (msat, optional): the amount required to pay this invoice
 - **description** (string, optional): description used in the invoice
+- **updated\_index** (u64, optional): 1-based index indicating order this invoice was changed (only present if it has changed since creation) *(added v23.08)*

 If **bolt12** is present:

@@ -81,4 +83,4 @@ RESOURCES

 Main web site: <https://github.com/ElementsProject/lightning>

-[comment]: # ( SHA256STAMP:f29100ae7e0ad26fee559e175e104a9e29e1a2cd6917c4072d521ce0600d1656)
+[comment]: # ( SHA256STAMP:4b9c2449a664f955e2155656eaef44f40c36cf84f1fc2890812676a3216b666b)
--- a/doc/lightning-invoice.7.md
+++ b/doc/lightning-invoice.7.md
@@ -82,6 +82,7 @@ On success, an object is returned, containing:
 - **payment\_hash** (hash): the hash of the *payment\_preimage* which will prove payment
 - **payment\_secret** (secret): the *payment\_secret* to place in the onion
 - **expires\_at** (u64): UNIX timestamp of when invoice expires
+- **created\_index** (u64): 1-based index indicating order this invoice was created in *(added v23.08)*

 The following warnings may also be returned:

@@ -119,4 +120,4 @@ RESOURCES

 Main web site: <https://github.com/ElementsProject/lightning>

-[comment]: # ( SHA256STAMP:095393c4a1050a9a458eba1033162e99283019329747a66b6461a5bb13fa7a2f)
+[comment]: # ( SHA256STAMP:ffe488e123bad4592e4083c5eaaad0c01194d6ecc9fe14ce9a6ffd488aae8129)
--- a/doc/lightning-listinvoices.7.md
+++ b/doc/lightning-listinvoices.7.md
@@ -32,12 +32,14 @@ On success, an object containing **invoices** is returned.  It is an array of ob
 - **payment\_hash** (hash): the hash of the *payment\_preimage* which will prove payment
 - **status** (string): Whether it's paid, unpaid or unpayable (one of "unpaid", "paid", "expired")
 - **expires\_at** (u64): UNIX timestamp of when it will become / became unpayable
+- **created\_index** (u64): 1-based index indicating order this invoice was created in *(added v23.08)*
 - **description** (string, optional): description used in the invoice
 - **amount\_msat** (msat, optional): the amount required to pay this invoice
 - **bolt11** (string, optional): the BOLT11 string (always present unless *bolt12* is)
 - **bolt12** (string, optional): the BOLT12 string (always present unless *bolt11* is)
 - **local\_offer\_id** (hash, optional): the *id* of our offer which created this invoice (**experimental-offers** only).
 - **invreq\_payer\_note** (string, optional): the optional *invreq\_payer\_note* from invoice\_request which created this invoice (**experimental-offers** only).
+- **updated\_index** (u64, optional): 1-based index indicating order this invoice was changed (only present if it has changed since creation) *(added v23.08)*

 If **status** is "paid":

@@ -63,4 +65,4 @@ RESOURCES

 Main web site: <https://github.com/ElementsProject/lightning>

-[comment]: # ( SHA256STAMP:7b1b70f04245395de28eb378e364537920e2f690db3c97ee638cefd282712dca)
+[comment]: # ( SHA256STAMP:e698b0e345ed4912b7699b43f2571a4cc3bb4ae909efeb631b02dd94a87e765c)
--- a/doc/lightning-sendinvoice.7.md
+++ b/doc/lightning-sendinvoice.7.md
@@ -45,8 +45,10 @@ On success, an object is returned, containing:
 - **payment\_hash** (hash): the hash of the *payment\_preimage* which will prove payment
 - **status** (string): Whether it's paid, unpaid or unpayable (one of "unpaid", "paid", "expired")
 - **expires\_at** (u64): UNIX timestamp of when it will become / became unpayable
+- **created\_index** (u64): 1-based index indicating order this invoice was created in *(added v23.08)*
 - **amount\_msat** (msat, optional): the amount required to pay this invoice
 - **bolt12** (string, optional): the BOLT12 string
+- **updated\_index** (u64, optional): 1-based index indicating order this invoice was changed (only present if it has changed since creation) *(added v23.08)*

 If **status** is "paid":

@@ -79,4 +81,4 @@ RESOURCES

 Main web site: <https://github.com/ElementsProject/lightning>

-[comment]: # ( SHA256STAMP:79a371e3dc60c1395f591e16c3dd039f8fdee53c9402f345fa8823d85a18d819)
+[comment]: # ( SHA256STAMP:682cf05a868d744b3a70a4747d26a23ba802ffe3abc0cce4bd89683377be1930)
--- a/doc/lightning-sql.7.md
+++ b/doc/lightning-sql.7.md
@@ -205,6 +205,8 @@ The following tables are currently supported:
  - `bolt12` (type `string`, sqltype `TEXT`)
  - `local_offer_id` (type `hash`, sqltype `BLOB`)
  - `invreq_payer_note` (type `string`, sqltype `TEXT`)
+  - `created_index` (type `u64`, sqltype `INTEGER`)
+  - `updated_index` (type `u64`, sqltype `INTEGER`)
  - `pay_index` (type `u64`, sqltype `INTEGER`)
  - `amount_received_msat` (type `msat`, sqltype `INTEGER`)
  - `paid_at` (type `u64`, sqltype `INTEGER`)
@@ -511,4 +513,4 @@ RESOURCES
 ---------

 Main web site: <https://github.com/ElementsProject/lightning>
-[comment]: # ( SHA256STAMP:4cfeeb2855f92a12d6a52d912a58df7573fc34f1f17a190bba26e46695f54de6)
+[comment]: # ( SHA256STAMP:094d94f4d2cfd8e8bdc99be8b692100d3cbd70ab3c297ed8e191c8d4a0f9b6a7)
--- a/doc/lightning-waitanyinvoice.7.md
+++ b/doc/lightning-waitanyinvoice.7.md
@@ -41,9 +41,11 @@ On success, an object is returned, containing:
 - **payment\_hash** (hash): the hash of the *payment\_preimage* which will prove payment
 - **status** (string): Whether it's paid or expired (one of "paid", "expired")
 - **expires\_at** (u64): UNIX timestamp of when it will become / became unpayable
+- **created\_index** (u64): 1-based index indicating order this invoice was created in *(added v23.08)*
 - **amount\_msat** (msat, optional): the amount required to pay this invoice
 - **bolt11** (string, optional): the BOLT11 string (always present unless *bolt12* is)
 - **bolt12** (string, optional): the BOLT12 string (always present unless *bolt11* is)
+- **updated\_index** (u64, optional): 1-based index indicating order this invoice was changed (only present if it has changed since creation) *(added v23.08)*

 If **status** is "paid":

@@ -75,4 +77,4 @@ RESOURCES

 Main web site: <https://github.com/ElementsProject/lightning>

-[comment]: # ( SHA256STAMP:86e3d74f12d2997b7960a0d0732ff51422af6dc9851134e216723b1497bc0573)
+[comment]: # ( SHA256STAMP:a0ace35f11efcdfbac39ef830cd7b2b6c8f48816c5512d7d2300edb9463aa4e6)
--- a/doc/lightning-waitinvoice.7.md
+++ b/doc/lightning-waitinvoice.7.md
@@ -23,9 +23,11 @@ On success, an object is returned, containing:
 - **payment\_hash** (hash): the hash of the *payment\_preimage* which will prove payment
 - **status** (string): Whether it's paid or expired (one of "paid", "expired")
 - **expires\_at** (u64): UNIX timestamp of when it will become / became unpayable
+- **created\_index** (u64): 1-based index indicating order this invoice was created in *(added v23.08)*
 - **amount\_msat** (msat, optional): the amount required to pay this invoice
 - **bolt11** (string, optional): the BOLT11 string (always present unless *bolt12* is)
 - **bolt12** (string, optional): the BOLT12 string (always present unless *bolt11* is)
+- **updated\_index** (u64, optional): 1-based index indicating order this invoice was changed (only present if it has changed since creation) *(added v23.08)*

 If **status** is "paid":

@@ -60,4 +62,4 @@ RESOURCES

 Main web site: <https://github.com/ElementsProject/lightning>

-[comment]: # ( SHA256STAMP:86e3d74f12d2997b7960a0d0732ff51422af6dc9851134e216723b1497bc0573)
+[comment]: # ( SHA256STAMP:a0ace35f11efcdfbac39ef830cd7b2b6c8f48816c5512d7d2300edb9463aa4e6)
--- a/doc/schemas/createinvoice.schema.json
+++ b/doc/schemas/createinvoice.schema.json
@@ -4,6 +4,7 @@
  "additionalProperties": false,
  "required": [
    "label",
+    "created_index",
    "payment_hash",
    "status",
    "description",
@@ -47,6 +48,11 @@
      "type": "u64",
      "description": "UNIX timestamp of when invoice expires (or expired)"
    },
+    "created_index": {
+      "type": "u64",
+      "added": "v23.08",
+      "description": "1-based index indicating order this invoice was created in"
+    },
    "pay_index": {
      "type": "u64",
      "description": "Incrementing id for when this was paid (**status** *paid* only)"
--- a/doc/schemas/delinvoice.schema.json
+++ b/doc/schemas/delinvoice.schema.json
@@ -5,6 +5,7 @@
    "label",
    "payment_hash",
    "status",
+    "created_index",
    "expires_at"
  ],
  "additionalProperties": true,
@@ -33,6 +34,16 @@
      "type": "hash",
      "description": "the hash of the *payment_preimage* which will prove payment"
    },
+    "created_index": {
+      "type": "u64",
+      "added": "v23.08",
+      "description": "1-based index indicating order this invoice was created in"
+    },
+    "updated_index": {
+      "type": "u64",
+      "added": "v23.08",
+      "description": "1-based index indicating order this invoice was changed (only present if it has changed since creation)"
+    },
    "status": {
      "type": "string",
      "description": "State of invoice",
@@ -67,6 +78,8 @@
          "description": {},
          "payment_hash": {},
          "pay_index": {},
+          "created_index": {},
+          "updated_index": {},
          "amount_received_msat": {},
          "paid_at": {},
          "payment_preimage": {},
@@ -95,6 +108,8 @@
          "description": {},
          "payment_hash": {},
          "pay_index": {},
+          "created_index": {},
+          "updated_index": {},
          "amount_received_msat": {},
          "msatoshi_received": {},
          "paid_at": {},
@@ -133,6 +148,8 @@
          "payment_hash": {},
          "invreq_payer_note": {},
          "local_offer_id": {},
+          "created_index": {},
+          "updated_index": {},
          "pay_index": {
            "type": "u64",
            "description": "unique index for this invoice payment"
@@ -163,6 +180,8 @@
          "description": {},
          "payment_hash": {},
          "expires_at": {},
+          "created_index": {},
+          "updated_index": {},
          "pay_index": {},
          "invreq_payer_note": {},
          "local_offer_id": {}
--- a/doc/schemas/invoice.schema.json
+++ b/doc/schemas/invoice.schema.json
@@ -5,6 +5,7 @@
  "required": [
    "payment_hash",
    "expires_at",
+    "created_index",
    "bolt11",
    "payment_secret"
  ],
@@ -25,6 +26,11 @@
      "type": "u64",
      "description": "UNIX timestamp of when invoice expires"
    },
+    "created_index": {
+      "type": "u64",
+      "added": "v23.08",
+      "description": "1-based index indicating order this invoice was created in"
+    },
    "warning_capacity": {
      "type": "string",
      "description": "even using all possible channels, there's not enough incoming capacity to pay this invoice."
--- a/doc/schemas/listinvoices.schema.json
+++ b/doc/schemas/listinvoices.schema.json
@@ -13,6 +13,7 @@
        "additionalProperties": true,
        "required": [
          "label",
+          "created_index",
          "payment_hash",
          "status",
          "expires_at"
@@ -62,6 +63,16 @@
          "invreq_payer_note": {
            "type": "string",
            "description": "the optional *invreq_payer_note* from invoice_request which created this invoice (**experimental-offers** only)."
+          },
+          "created_index": {
+            "type": "u64",
+            "added": "v23.08",
+            "description": "1-based index indicating order this invoice was created in"
+          },
+          "updated_index": {
+            "type": "u64",
+            "added": "v23.08",
+            "description": "1-based index indicating order this invoice was changed (only present if it has changed since creation)"
          }
        },
        "allOf": [
@@ -96,6 +107,8 @@
                "local_offer_id": {},
                "invreq_payer_note": {},
                "expires_at": {},
+                "created_index": {},
+                "updated_index": {},
                "pay_index": {
                  "type": "u64",
                  "description": "Unique incrementing index for this payment"
@@ -127,6 +140,8 @@
                "bolt12": {},
                "local_offer_id": {},
                "invreq_payer_note": {},
+                "created_index": {},
+                "updated_index": {},
                "expires_at": {}
              }
            }
--- a/doc/schemas/sendinvoice.schema.json
+++ b/doc/schemas/sendinvoice.schema.json
@@ -7,6 +7,7 @@
    "description",
    "payment_hash",
    "status",
+    "created_index",
    "expires_at"
  ],
  "properties": {
@@ -42,6 +43,16 @@
    "bolt12": {
      "type": "string",
      "description": "the BOLT12 string"
+    },
+    "created_index": {
+      "type": "u64",
+      "added": "v23.08",
+      "description": "1-based index indicating order this invoice was created in"
+    },
+    "updated_index": {
+      "type": "u64",
+      "added": "v23.08",
+      "description": "1-based index indicating order this invoice was changed (only present if it has changed since creation)"
    }
  },
  "allOf": [
@@ -73,6 +84,8 @@
          "amount_msat": {},
          "bolt12": {},
          "expires_at": {},
+          "created_index": {},
+          "updated_index": {},
          "pay_index": {
            "type": "u64",
            "description": "Unique incrementing index for this payment"
--- a/doc/schemas/waitanyinvoice.schema.json
+++ b/doc/schemas/waitanyinvoice.schema.json
@@ -7,6 +7,7 @@
    "description",
    "payment_hash",
    "status",
+    "created_index",
    "expires_at"
  ],
  "properties": {
@@ -45,6 +46,16 @@
    "bolt12": {
      "type": "string",
      "description": "the BOLT12 string (always present unless *bolt11* is)"
+    },
+    "created_index": {
+      "type": "u64",
+      "added": "v23.08",
+      "description": "1-based index indicating order this invoice was created in"
+    },
+    "updated_index": {
+      "type": "u64",
+      "added": "v23.08",
+      "description": "1-based index indicating order this invoice was changed (only present if it has changed since creation)"
    }
  },
  "allOf": [
@@ -77,6 +88,8 @@
          "bolt11": {},
          "bolt12": {},
          "expires_at": {},
+          "created_index": {},
+          "updated_index": {},
          "pay_index": {
            "type": "u64",
            "description": "Unique incrementing index for this payment"
@@ -106,6 +119,8 @@
          "amount_msat": {},
          "bolt11": {},
          "bolt12": {},
+          "created_index": {},
+          "updated_index": {},
          "expires_at": {}
        }
      }
--- a/doc/schemas/waitinvoice.schema.json
+++ b/doc/schemas/waitinvoice.schema.json
@@ -7,6 +7,7 @@
    "description",
    "payment_hash",
    "status",
+    "created_index",
    "expires_at"
  ],
  "properties": {
@@ -45,6 +46,16 @@
    "bolt12": {
      "type": "string",
      "description": "the BOLT12 string (always present unless *bolt11* is)"
+    },
+    "created_index": {
+      "type": "u64",
+      "added": "v23.08",
+      "description": "1-based index indicating order this invoice was created in"
+    },
+    "updated_index": {
+      "type": "u64",
+      "added": "v23.08",
+      "description": "1-based index indicating order this invoice was changed (only present if it has changed since creation)"
    }
  },
  "allOf": [
@@ -77,6 +88,8 @@
          "bolt11": {},
          "bolt12": {},
          "expires_at": {},
+          "created_index": {},
+          "updated_index": {},
          "pay_index": {
            "type": "u64",
            "description": "Unique incrementing index for this payment"
@@ -106,6 +119,8 @@
          "amount_msat": {},
          "bolt11": {},
          "bolt12": {},
+          "created_index": {},
+          "updated_index": {},
          "expires_at": {}
        }
      }