offers: add used_count to listoffers

alexgrad42 · alexgrad42 · commit e3719b3021ce · 2026-05-21T23:44:34.000+03:00
This adds a new 'used_count' field to the 'listoffers' RPC command output to see the exact number of times a BOLT12 offer has been paid by counting associated settled invoices. Changelog-Added: add a new 'used_count' field to the 'listoffers' RPC command Closes #9146
diff --git a/.msggen.json b/.msggen.json
@@ -3181,7 +3181,8 @@
             "ListOffers.offers[].label": 6,
             "ListOffers.offers[].offer_id": 1,
             "ListOffers.offers[].single_use": 3,
-            "ListOffers.offers[].used": 5
+            "ListOffers.offers[].used": 5,
+            "ListOffers.offers[].used_count": 9
         },
         "ListoffersRequest": {
             "ListOffers.active_only": 2,
@@ -11483,6 +11484,10 @@
             "added": "pre-v0.10.1",
             "deprecated": null
         },
+        "ListOffers.offers[].used_count": {
+            "added": "pre-v0.10.1",
+            "deprecated": null
+        },
         "ListPays": {
             "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
@@ -24461,6 +24461,12 @@
                     "True if an associated invoice has been paid."
                   ]
                 },
+                "used_count": {
+                  "type": "u64",
+                  "description": [
+                    "The number of times this offer has been paid."
+                  ]
+                },
                 "label": {
                   "type": "string",
                   "description": [
@@ -24499,23 +24505,26 @@
                 "single_use": false,
                 "bolt12": "lno1qgsq000bolt210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000",
                 "description": "Fish sale!",
-                "used": false
+                "used": false,
+                "used_count": 1
               },
               {
                 "offer_id": "offeridl22000002200000220000022000002200000220000022000002200000",
                 "active": true,
                 "single_use": false,
                 "bolt12": "lno1qgsq000bolt220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000",
                 "description": "Coffee",
-                "used": false
+                "used": false,
+                "used_count": 1
               },
               {
                 "offer_id": "offeridl23000002300000230000023000002300000230000023000002300000",
                 "active": true,
                 "single_use": false,
                 "bolt12": "lno1qgsq000bolt230002300023000230002300023000230002300023000230002300023000230002300023000230002300023000230002300023000230002300023000",
                 "description": "Movie ticket",
-                "used": false
+                "used": false,
+                "used_count": 1
               }
             ]
           }
@@ -24535,7 +24544,8 @@
                 "active": true,
                 "single_use": false,
                 "bolt12": "lno1qgsq000bolt230002300023000230002300023000230002300023000230002300023000230002300023000230002300023000230002300023000230002300023000",
-                "used": false
+                "used": false,
+                "used_count": 1
               }
             ]
           }
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
@@ -1698,6 +1698,7 @@ def listoffers_offers2py(m):
         "offer_id": hexlify(m.offer_id),  # PrimitiveField in generate_composite
         "single_use": m.single_use,  # PrimitiveField in generate_composite
         "used": m.used,  # PrimitiveField in generate_composite
+        "used_count": m.used_count,  # PrimitiveField in generate_composite
     })
 
 
diff --git a/doc/schemas/listoffers.json b/doc/schemas/listoffers.json
@@ -91,6 +91,12 @@
                 "True if an associated invoice has been paid."
               ]
             },
+            "used_count": {
+                "type": "u64",
+                "description": [ 
+                  "The number of times this offer has been paid."
+                ]
+            },
             "label": {
               "type": "string",
               "description": [
@@ -129,23 +135,26 @@
             "single_use": false,
             "bolt12": "lno1qgsq000bolt210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000210002100021000",
             "description": "Fish sale!",
-            "used": false
+            "used": false,
+            "used_count": 1
           },
           {
             "offer_id": "offeridl22000002200000220000022000002200000220000022000002200000",
             "active": true,
             "single_use": false,
             "bolt12": "lno1qgsq000bolt220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000220002200022000",
             "description": "Coffee",
-            "used": false
+            "used": false,
+            "used_count": 1
           },
           {
             "offer_id": "offeridl23000002300000230000023000002300000230000023000002300000",
             "active": true,
             "single_use": false,
             "bolt12": "lno1qgsq000bolt230002300023000230002300023000230002300023000230002300023000230002300023000230002300023000230002300023000230002300023000",
             "description": "Movie ticket",
-            "used": false
+            "used": false,
+            "used_count": 1
           }
         ]
       }
@@ -165,7 +174,8 @@
             "active": true,
             "single_use": false,
             "bolt12": "lno1qgsq000bolt230002300023000230002300023000230002300023000230002300023000230002300023000230002300023000230002300023000230002300023000",
-            "used": false
+            "used": false,
+            "used_count": 1
           }
         ]
       }
diff --git a/lightningd/offer.c b/lightningd/offer.c
@@ -179,6 +179,8 @@ static struct command_result *json_listoffers(struct command *cmd,
 			json_populate_offer(response,
 					    offer_id, b12,
 					    label, status, force_paths);
+			u64 used_count = wallet_offer_count_payments(wallet, offer_id);
+			json_add_u64(response, "used_count", used_count);
 			description = offer_description_from_b12(tmpctx, cmd->ld, b12);
 			if (description)
 				json_add_stringn(response, "description", description, tal_bytelen(description));
@@ -198,6 +200,8 @@ static struct command_result *json_listoffers(struct command *cmd,
 				json_populate_offer(response,
 						    &id, b12,
 						    label, status, force_paths);
+				u64 used_count = wallet_offer_count_payments(wallet, offer_id);
+		    	        json_add_u64(response, "used_count", used_count);
 				description = offer_description_from_b12(tmpctx, cmd->ld, b12);
 				if (description)
 					json_add_stringn(response, "description", description, tal_bytelen(description));
diff --git a/tests/test_pay.py b/tests/test_pay.py
@@ -7329,3 +7329,40 @@ def test_createproof_include(node_factory, bitcoind):
     # Unknown name is an error.
     with pytest.raises(RpcError, match=r'Unknown field name'):
         l1.rpc.call('createproof', {'invstring': inv, 'include': ['no_such_field']})
+
+def test_offer_used_count(node_factory, bitcoind):
+    """Verify that the used_count counter increments correctly for BOLT12 offers"""
+    # Build a working 3-node graph with localhost permissions exactly like the working test
+    l1, l2, l3 = node_factory.line_graph(3, wait_for_announce=True,
+                                         opts=[{},
+                                               {'dev-allow-localhost': None},
+                                               {'dev-allow-localhost': None}])
+
+    # Create a BOLT12 offer on the recipient node (l3)
+    offer = l3.rpc.offer('5000msat', 'used_count test')
+    offer_id = offer['offer_id']
+
+    # Verify that the initial usage counter on l3 is equal to 0
+    offers = l3.rpc.listoffers(offer_id=offer_id)['offers']
+    assert len(offers) == 1
+    assert 'used_count' in offers[0], "Error: used_count field is missing from listoffers response!"
+    assert offers[0]['used_count'] == 0
+
+    # The sender node (l1) requests an invoice based on l3's offer
+    inv = l1.rpc.fetchinvoice(offer['bolt12'])['invoice']
+
+    # Pay the invoice from l1 using xpay
+    l1.rpc.xpay(inv)
+
+    # Verify that l3's database counter increments to 1 after successful settlement
+    offers = l3.rpc.listoffers(offer_id=offer_id)['offers']
+    assert offers[0]['used_count'] == 1
+
+    # Perform a second payment to ensure the aggregate COUNT(*) functions properly
+    inv2 = l1.rpc.fetchinvoice(offer['bolt12'])['invoice']
+    l1.rpc.xpay(inv2)
+
+    # Verify that the counter scales up to 2
+    offers = l3.rpc.listoffers(offer_id=offer_id)['offers']
+    assert offers[0]['used_count'] == 2
+    
diff --git a/wallet/wallet.c b/wallet/wallet.c
@@ -6057,6 +6057,28 @@ char *wallet_offer_find(const tal_t *ctx,
 	return bolt12;
 }
 
+u64 wallet_offer_count_payments(struct wallet *w,
+				const struct sha256 *offer_id)
+{
+	struct db_stmt *stmt;
+	u64 count = 0;
+
+	stmt = db_prepare_v2(w->db, SQL("SELECT COUNT(*)"
+					"  FROM invoices"
+					"  WHERE local_offer_id = ?"
+					"  AND state = 1;")); 
+	
+	db_bind_sha256(stmt, offer_id);
+	db_query_prepared(stmt);
+
+	if (db_step(stmt)) {
+		count = db_col_u64(stmt, "COUNT(*)");
+	}
+
+	tal_free(stmt);
+	return count;
+}
+
 struct db_stmt *wallet_offer_id_first(struct wallet *w, struct sha256 *offer_id)
 {
 	struct db_stmt *stmt;
diff --git a/wallet/wallet.h b/wallet/wallet.h
@@ -1504,6 +1504,20 @@ char *wallet_offer_find(const tal_t *ctx,
 			bool *force_paths)
 	NON_NULL_ARGS(1,2,3);
 
+/**
+ * Count the number of successful payments for a given offer.
+ * @w: the wallet
+ * @offer_id: the merkle root of the offer to check (must be unique)
+ *
+ * Scans the database invoices table to find all settled (paid) invoices
+ * that are associated with the specified @offer_id.
+ *
+ * Returns the total count of completed payments as a 64-bit unsigned integer.
+ */
+u64 wallet_offer_count_payments(struct wallet *w,
+				const struct sha256 *offer_id);
+	NON_NULL_ARGS(1,2);
+
 /**
  * Iterate through all the offers.
  * @w: the wallet
