lightningd: add created_index and updated_index to listhtlcs.

rustyrussell · rustyrussell · commit 7ba6263c488f · 2025-04-29T09:38:20.000+09:30
Signed-off-by: Rusty Russell &lt;rusty@rustcorp.com.au&gt;
Changelog-Added: JSON-RPC: `listhtlcs` has `created_index` and `updated_index` fields.
diff --git a/.msggen.json b/.msggen.json
@@ -2560,12 +2560,14 @@
         },
         "ListhtlcsHtlcs": {
             "ListHtlcs.htlcs[].amount_msat": 4,
+            "ListHtlcs.htlcs[].created_index": 8,
             "ListHtlcs.htlcs[].direction": 5,
             "ListHtlcs.htlcs[].expiry": 3,
             "ListHtlcs.htlcs[].id": 2,
             "ListHtlcs.htlcs[].payment_hash": 6,
             "ListHtlcs.htlcs[].short_channel_id": 1,
-            "ListHtlcs.htlcs[].state": 7
+            "ListHtlcs.htlcs[].state": 7,
+            "ListHtlcs.htlcs[].updated_index": 9
         },
         "ListhtlcsRequest": {
             "ListHtlcs.id": 1
@@ -9583,6 +9585,10 @@
             "added": "pre-v0.10.1",
             "deprecated": null
         },
+        "ListHtlcs.htlcs[].created_index": {
+            "added": "v25.05",
+            "deprecated": null
+        },
         "ListHtlcs.htlcs[].direction": {
             "added": "pre-v0.10.1",
             "deprecated": null
@@ -9607,6 +9613,10 @@
             "added": "pre-v0.10.1",
             "deprecated": null
         },
+        "ListHtlcs.htlcs[].updated_index": {
+            "added": "v25.05",
+            "deprecated": null
+        },
         "ListHtlcs.id": {
             "added": "pre-v0.10.1",
             "deprecated": null
diff --git a/cln-grpc/proto/node.proto b/cln-grpc/proto/node.proto
diff --git a/cln-grpc/src/convert.rs b/cln-grpc/src/convert.rs
diff --git a/cln-rpc/src/model.rs b/cln-rpc/src/model.rs
diff --git a/contrib/msggen/msggen/schema.json b/contrib/msggen/msggen/schema.json
@@ -21549,6 +21549,7 @@
               "type": "object",
               "additionalProperties": false,
               "required": [
+                "created_index",
                 "short_channel_id",
                 "id",
                 "expiry",
@@ -21564,6 +21565,20 @@
                     "The channel that contains/contained the HTLC."
                   ]
                 },
+                "created_index": {
+                  "added": "v25.05",
+                  "type": "u64",
+                  "description": [
+                    "1-based index indicating order this htlc was created in."
+                  ]
+                },
+                "updated_index": {
+                  "added": "v25.05",
+                  "type": "u64",
+                  "description": [
+                    "1-based index indicating order this htlc was changed (only present if it has changed since creation)."
+                  ]
+                },
                 "id": {
                   "type": "u64",
                   "description": [
diff --git a/contrib/pyln-grpc-proto/pyln/grpc/node_pb2.py b/contrib/pyln-grpc-proto/pyln/grpc/node_pb2.py
diff --git a/contrib/pyln-testing/pyln/testing/grpc2py.py b/contrib/pyln-testing/pyln/testing/grpc2py.py
@@ -1715,10 +1715,12 @@ def listhtlcs_htlcs2py(m):
         "direction": str(m.direction),  # EnumField in generate_composite
         "state": str(m.state),  # EnumField in generate_composite
         "amount_msat": amount2msat(m.amount_msat),  # PrimitiveField in generate_composite
+        "created_index": m.created_index,  # PrimitiveField in generate_composite
         "expiry": m.expiry,  # PrimitiveField in generate_composite
         "id": m.id,  # PrimitiveField in generate_composite
         "payment_hash": hexlify(m.payment_hash),  # PrimitiveField in generate_composite
         "short_channel_id": m.short_channel_id,  # PrimitiveField in generate_composite
+        "updated_index": m.updated_index,  # PrimitiveField in generate_composite
     })
 
 
diff --git a/doc/schemas/listhtlcs.json b/doc/schemas/listhtlcs.json
@@ -33,6 +33,7 @@
           "type": "object",
           "additionalProperties": false,
           "required": [
+            "created_index",
             "short_channel_id",
             "id",
             "expiry",
@@ -48,6 +49,20 @@
                 "The channel that contains/contained the HTLC."
               ]
             },
+            "created_index": {
+              "added": "v25.05",
+              "type": "u64",
+              "description": [
+                "1-based index indicating order this htlc was created in."
+              ]
+            },
+            "updated_index": {
+              "added": "v25.05",
+              "type": "u64",
+              "description": [
+                "1-based index indicating order this htlc was changed (only present if it has changed since creation)."
+              ]
+            },
             "id": {
               "type": "u64",
               "description": [
diff --git a/lightningd/peer_htlcs.c b/lightningd/peer_htlcs.c
@@ -3106,7 +3106,7 @@ static struct command_result *json_listhtlcs(struct command *cmd,
 	struct channel *chan;
 	struct wallet_htlc_iter *i;
 	struct short_channel_id scid;
-	u64 htlc_id;
+	u64 htlc_id, created_index, updated_index;
 	int cltv_expiry;
 	enum side owner;
 	struct amount_msat msat;
@@ -3122,12 +3122,17 @@ static struct command_result *json_listhtlcs(struct command *cmd,
 	json_array_start(response, "htlcs");
 	for (i = wallet_htlcs_first(cmd, cmd->ld->wallet, chan,
 				    &scid, &htlc_id, &cltv_expiry, &owner, &msat,
-				    &payment_hash, &hstate);
+				    &payment_hash, &hstate,
+				    &created_index, &updated_index);
 	     i;
 	     i = wallet_htlcs_next(cmd->ld->wallet, i,
 				   &scid, &htlc_id, &cltv_expiry, &owner, &msat,
-				   &payment_hash, &hstate)) {
+				   &payment_hash, &hstate,
+				   &created_index, &updated_index)) {
 		json_object_start(response, NULL);
+		json_add_u64(response, "created_index", created_index);
+		if (updated_index != 0)
+			json_add_u64(response, "updated_index", updated_index);
 		json_add_short_channel_id(response, "short_channel_id", scid);
 		json_add_u64(response, "id", htlc_id);
 		json_add_u32(response, "expiry", cltv_expiry);
diff --git a/tests/test_connection.py b/tests/test_connection.py
@@ -4342,27 +4342,35 @@ def test_multichan(node_factory, executor, bitcoind):
     assert l1htlcs == l1.rpc.listhtlcs(scid12)['htlcs']
     assert l1htlcs == [{"short_channel_id": scid12,
                         "id": 0,
+                        "created_index": 1,
+                        "updated_index": 9,
                         "expiry": 117,
                         "direction": "out",
                         "amount_msat": Millisatoshi(100001001),
                         "payment_hash": inv1['payment_hash'],
                         "state": "RCVD_REMOVE_ACK_REVOCATION"},
                        {"short_channel_id": scid12,
                         "id": 1,
+                        "created_index": 2,
+                        "updated_index": 18,
                         "expiry": 117,
                         "direction": "out",
                         "amount_msat": Millisatoshi(100001001),
                         "payment_hash": inv2['payment_hash'],
                         "state": "RCVD_REMOVE_ACK_REVOCATION"},
                        {"short_channel_id": scid12,
                         "id": 2,
+                        "created_index": 3,
+                        "updated_index": 27,
                         "expiry": 135,
                         "direction": "out",
                         "amount_msat": Millisatoshi(100001001),
                         "payment_hash": inv3['payment_hash'],
                         "state": "RCVD_REMOVE_ACK_REVOCATION"},
                        {"short_channel_id": scid12,
                         "id": 3,
+                        "created_index": 4,
+                        "updated_index": 36,
                         "expiry": 135,
                         "direction": "out",
                         "amount_msat": Millisatoshi(100001001),
@@ -4373,7 +4381,16 @@ def test_multichan(node_factory, executor, bitcoind):
     for h in l1htlcs:
         h['direction'] = 'in'
         h['state'] = 'SENT_REMOVE_ACK_REVOCATION'
-    assert l2.rpc.listhtlcs(scid12)['htlcs'] == l1htlcs
+        # These won't match!
+        del h['created_index']
+        del h['updated_index']
+
+    l2htlcs = l2.rpc.listhtlcs(scid12)['htlcs']
+    for h in l2htlcs:
+        del h['created_index']
+        del h['updated_index']
+
+    assert l2htlcs == l1htlcs
 
 
 def test_mutual_reconnect_race(node_factory, executor, bitcoind):
diff --git a/tests/test_misc.py b/tests/test_misc.py
@@ -3294,13 +3294,18 @@ def test_listforwards_and_listhtlcs(node_factory, bitcoind):
     assert [h['direction'] for h in c1htlcs] == ['out'] * 3
     assert [h['state'] for h in c1htlcs] == ['RCVD_REMOVE_ACK_REVOCATION'] * 3
 
-    # These should be a mirror!
+    # These should be a mirror! (Except indexes)
     c2c1htlcs = l2.rpc.listhtlcs(c12)['htlcs']
     for h in c2c1htlcs:
         assert h['state'] == 'SENT_REMOVE_ACK_REVOCATION'
         assert h['direction'] == 'in'
         h['state'] = 'RCVD_REMOVE_ACK_REVOCATION'
         h['direction'] = 'out'
+        del h['created_index']
+        del h['updated_index']
+    for h in c1htlcs:
+        del h['created_index']
+        del h['updated_index']
     assert c2c1htlcs == c1htlcs
 
     # One channel at a time should result in all htlcs.
@@ -3312,11 +3317,29 @@ def test_listforwards_and_listhtlcs(node_factory, bitcoind):
     for h in allhtlcs:
         assert h in parthtlcs
 
-    # Now, close and forget.
+    # Now, close and forget (first mine c23 close)
+    bitcoind.generate_block(1, wait_for_mempool=1)
     l2.rpc.close(c24)
+    bitcoind.generate_block(1, wait_for_mempool=1)
     l2.rpc.close(c12)
+    # Not actually deleted yet.
+    assert l2.rpc.wait('htlcs', 'deleted', 0)['deleted'] == 0
+
+    # 99 blocks is not enough for them to be deleted.
+    bitcoind.generate_block(97)
+    assert l2.rpc.wait('htlcs', 'deleted', 0)['deleted'] == 0
+
+    # This will forget c23
+    bitcoind.generate_block(1)
+    assert l2.rpc.wait('htlcs', 'deleted', 1)['deleted'] == 1
+
+    # This will forget c24
+    bitcoind.generate_block(1)
+    assert l2.rpc.wait('htlcs', 'deleted', 2)['deleted'] == 2
 
-    bitcoind.generate_block(100, wait_for_mempool=3)
+    # This will forget c12
+    bitcoind.generate_block(1)
+    assert l2.rpc.wait('htlcs', 'deleted', 3)['deleted'] == 5
 
     # Once channels are gone, htlcs are gone.
     for n in (l1, l2, l3, l4):
diff --git a/tests/test_plugin.py b/tests/test_plugin.py
@@ -3653,6 +3653,10 @@ def test_sql(node_factory, bitcoind):
             'indices': [['short_channel_id', 'id']],
             'columns': [{'name': 'short_channel_id',
                          'type': 'short_channel_id'},
+                        {'name': 'created_index',
+                         'type': 'u64'},
+                        {'name': 'updated_index',
+                         'type': 'u64'},
                         {'name': 'id',
                          'type': 'u64'},
                         {'name': 'expiry',
diff --git a/wallet/wallet.c b/wallet/wallet.c
@@ -6198,7 +6198,9 @@ struct wallet_htlc_iter *wallet_htlcs_first(const tal_t *ctx,
 					    enum side *owner,
 					    struct amount_msat *msat,
 					    struct sha256 *payment_hash,
-					    enum htlc_state *hstate)
+					    enum htlc_state *hstate,
+					    u64 *created_index,
+					    u64 *updated_index)
 {
 	struct wallet_htlc_iter *i = tal(ctx, struct wallet_htlc_iter);
 
@@ -6214,6 +6216,8 @@ struct wallet_htlc_iter *wallet_htlcs_first(const tal_t *ctx,
 					    ", h.msatoshi"
 					    ", h.payment_hash"
 					    ", h.hstate"
+					    ", h.id"
+					    ", h.updated_index"
 					    " FROM channel_htlcs h"
 					    " WHERE channel_id = ?"
 					    " ORDER BY id ASC"));
@@ -6229,6 +6233,8 @@ struct wallet_htlc_iter *wallet_htlcs_first(const tal_t *ctx,
 					    ", h.msatoshi"
 					    ", h.payment_hash"
 					    ", h.hstate"
+					    ", h.id"
+					    ", h.updated_index"
 					    " FROM channel_htlcs h"
 					    " JOIN channels ON channels.id = h.channel_id"
 					    " ORDER BY h.id ASC"));
@@ -6239,7 +6245,8 @@ struct wallet_htlc_iter *wallet_htlcs_first(const tal_t *ctx,
 
 	return wallet_htlcs_next(w, i,
 				 scid, htlc_id, cltv_expiry, owner, msat,
-				 payment_hash, hstate);
+				 payment_hash, hstate,
+				 created_index, updated_index);
 }
 
 struct wallet_htlc_iter *wallet_htlcs_next(struct wallet *w,
@@ -6250,7 +6257,9 @@ struct wallet_htlc_iter *wallet_htlcs_next(struct wallet *w,
 					   enum side *owner,
 					   struct amount_msat *msat,
 					   struct sha256 *payment_hash,
-					   enum htlc_state *hstate)
+					   enum htlc_state *hstate,
+					   u64 *created_index,
+					   u64 *updated_index)
 {
 	if (!db_step(iter->stmt))
 		return tal_free(iter);
@@ -6274,6 +6283,8 @@ struct wallet_htlc_iter *wallet_htlcs_next(struct wallet *w,
 	db_col_sha256(iter->stmt, "h.payment_hash", payment_hash);
 	*cltv_expiry = db_col_int(iter->stmt, "h.cltv_expiry");
 	*hstate = db_col_int(iter->stmt, "h.hstate");
+	*created_index = db_col_u64(iter->stmt, "h.id");
+	*updated_index = db_col_u64(iter->stmt, "h.updated_index");
 	return iter;
 }
 
diff --git a/wallet/wallet.h b/wallet/wallet.h
@@ -1691,7 +1691,9 @@ struct wallet_htlc_iter *wallet_htlcs_first(const tal_t *ctx,
 					    enum side *owner,
 					    struct amount_msat *msat,
 					    struct sha256 *payment_hash,
-					    enum htlc_state *hstate);
+					    enum htlc_state *hstate,
+					    u64 *created_index,
+					    u64 *updated_index);
 
 /**
  * Iterate through the htlcs table.
@@ -1709,7 +1711,9 @@ struct wallet_htlc_iter *wallet_htlcs_next(struct wallet *w,
 					   enum side *owner,
 					   struct amount_msat *msat,
 					   struct sha256 *payment_hash,
-					   enum htlc_state *hstate);
+					   enum htlc_state *hstate,
+					   u64 *created_index,
+					   u64 *updated_index);
 
 /* Make a PSBT from these utxos, or enhance @base if non-NULL. */
 struct wally_psbt *psbt_using_utxos(const tal_t *ctx,
