bolt12: allow to inject payer_metadata

Payer metadata is a field that controls the payer ID
provided during the fetchinvoice process.

There are use cases where this is highly useful, such as
proving that the payer has paid for the correct item.

Imagine visiting a merchant's website to pay for multiple offers, where
one of these offers is a default offer (with no description and no set amount).

In this scenario, the merchant could claim not to have received
payment for a specific item. Since the same offer may be used to
fetch invoices for different products, there needs to be a way to
identify which product the invoice corresponds to.

With this commit, it will be possible to inject payer metadata,
which helps solve the issue described above.

For example, possible payer metadata could be `to_hex(b"{payer_node_id}.{product_id}.{created_at}")`.

Changelog-Added: JSON-RPC: `fetchinvoice` allows setting invreq_metadata via `payer_metadata` parameter.
Signed-off-by: Vincenzo Palazzo <[email protected]>

Author: vincenzopalazzo

.msggen.json

@@ -1248,6 +1248,7 @@
         "FetchinvoiceRequest": {
             "FetchInvoice.amount_msat": 2,
             "FetchInvoice.offer": 1,
+            "FetchInvoice.payer_metadata": 9,
             "FetchInvoice.payer_note": 8,
             "FetchInvoice.quantity": 3,
             "FetchInvoice.recurrence_counter": 4,
@@ -5609,6 +5610,10 @@
             "added": "pre-v0.10.1",
             "deprecated": null
         },
+        "FetchInvoice.payer_metadata": {
+            "added": "v24.11",
+            "deprecated": null
+        },
         "FetchInvoice.payer_note": {
             "added": "pre-v0.10.1",
             "deprecated": null

cln-grpc/proto/node.proto

@@ -13425,6 +13425,13 @@
               "To ask the issuer to include in the fetched invoice."
             ]
           },
+          "payer_metadata": {
+            "type": "string",
+            "description": [
+              "Derive the payer_id from the specified payer_metadata. Please be sure that `payer_metdata` can not be derived by anyone, so put some secret into it."
+            ],
+            "added": "v24.11"
+          },
           "dev_reply_path": {
             "hidden": true
           },

cln-grpc/src/convert.rs

@@ -62,6 +62,13 @@
           "To ask the issuer to include in the fetched invoice."
         ]
       },
+      "payer_metadata": {
+        "type": "string",
+        "description": [
+          "Derive the payer_id from the specified payer_metadata. Please be sure that `payer_metdata` can not be derived by anyone, so put some secret into it."
+        ],
+        "added": "v24.11"
+      },
       "dev_reply_path": {
         "hidden": true
       },

cln-rpc/src/model.rs

@@ -376,6 +376,7 @@ static struct command_result *prev_payment(struct command *cmd,
 			    " label and offer");
 }
 
+/* FIXME(vincenzopalazzo): move this to comm/bolt12.h */
 static struct command_result *param_b12_invreq(struct command *cmd,
 					       const char *name,
 					       const char *buffer,

contrib/msggen/msggen/schema.json

@@ -819,6 +819,7 @@ struct command_result *json_fetchinvoice(struct command *cmd,
 {
 	struct amount_msat *msat;
 	const char *rec_label, *payer_note;
+	u8 *payer_metadata;
 	struct out_req *req;
 	struct tlv_invoice_request *invreq;
 	struct sent *sent = tal(cmd, struct sent);
@@ -835,6 +836,7 @@ struct command_result *json_fetchinvoice(struct command *cmd,
 		   p_opt("recurrence_label", param_string, &rec_label),
 		   p_opt_def("timeout", param_number, &timeout, 60),
 		   p_opt("payer_note", param_string, &payer_note),
+		   p_opt("payer_metadata", param_bin_from_hex, &payer_metadata),
 		   p_opt("dev_path_use_scidd", param_dev_scidd, &sent->dev_path_use_scidd),
 		   p_opt("dev_reply_path", param_dev_reply_path, &sent->dev_reply_path),
 		   NULL))
@@ -938,6 +940,10 @@ struct command_result *json_fetchinvoice(struct command *cmd,
 			return command_fail(cmd, JSONRPC2_INVALID_PARAMS,
 					    "needs recurrence_counter");
 
+		if (payer_metadata)
+			return command_fail(cmd, JSONRPC2_INVALID_PARAMS,
+					    "Cannot set payer_metadata for recurring offers");
+
 		/* BOLT-offers-recurrence #12:
 		 *    - if the offer contained `recurrence_base` with
 		 *      `start_any_period` non-zero:
@@ -998,13 +1004,18 @@ struct command_result *json_fetchinvoice(struct command *cmd,
 			return command_fail(cmd, JSONRPC2_INVALID_PARAMS,
 					    "unnecessary recurrence_start");
 
-		/* BOLT-offers #12:
-		 * - MUST set `invreq_metadata` to an unpredictable series of
-		 *   bytes.
-		 */
-		invreq->invreq_metadata = tal_arr(invreq, u8, 16);
-		randombytes_buf(invreq->invreq_metadata,
-				tal_bytelen(invreq->invreq_metadata));
+		/* if the payer force to use the payer_metadata */
+		if (payer_metadata) {
+			invreq->invreq_metadata = tal_steal(invreq, payer_metadata);
+		} else {
+			/* BOLT-offers #12:
+			 * - MUST set `invreq_metadata` to an unpredictable series of
+			 *   bytes.
+			 */
+			invreq->invreq_metadata = tal_arr(invreq, u8, 16);
+			randombytes_buf(invreq->invreq_metadata,
+					tal_bytelen(invreq->invreq_metadata));
+		}
 	}
 
 	/* We derive transient payer_id from invreq_metadata */
@@ -1044,7 +1055,6 @@ struct command_result *json_fetchinvoice(struct command *cmd,
 							payer_note,
 							strlen(payer_note),
 							0);
-
 	/* Make the invoice request (fills in payer_key and payer_info) */
 	req = jsonrpc_request_start(cmd, "createinvoicerequest",
 				    &invreq_done,