xpay: allow setting payer_note for spamming when paying BIP353 or raw offers.

Simply forwards this to the fetchinvoice call.

Signed-off-by: Rusty Russell <[email protected]>
Changelog-Added: JSON-RPC: `xpay` supports `payer_note` to embed a note in the invoice when paying BIP353 or offers.

Author: rustyrussell

.msggen.json

@@ -3887,6 +3887,7 @@
             "Xpay.maxdelay": 7,
             "Xpay.maxfee": 3,
             "Xpay.partial_msat": 6,
+            "Xpay.payer_note": 8,
             "Xpay.retry_for": 5
         },
         "XpayResponse": {
@@ -13422,6 +13423,10 @@
             "added": "v24.11",
             "deprecated": null
         },
+        "Xpay.payer_note": {
+            "added": "v25.12",
+            "deprecated": null
+        },
         "Xpay.payment_preimage": {
             "added": "v24.11",
             "deprecated": null

cln-grpc/proto/node.proto

@@ -36058,6 +36058,13 @@
               "A payment may be delayed for up to `maxdelay` blocks by another node; clients should be prepared for this worst case."
             ],
             "default": "2016"
+          },
+          "payer_note": {
+            "type": "string",
+            "added": "v25.12",
+            "description": [
+              "To ask the issuer to include in the fetched invoice (only if invstring is a BIP353 address or offer)"
+            ]
           }
         }
       },

cln-grpc/src/convert.rs

@@ -65,6 +65,13 @@
           "A payment may be delayed for up to `maxdelay` blocks by another node; clients should be prepared for this worst case."
         ],
         "default": "2016"
+      },
+      "payer_note": {
+        "type": "string",
+        "added": "v25.12",
+        "description": [
+          "To ask the issuer to include in the fetched invoice (only if invstring is a BIP353 address or offer)"
+        ]
       }
     }
   },

cln-rpc/src/model.rs

@@ -1695,6 +1695,7 @@ struct xpay_params {
 	unsigned int retryfor;
 	u32 maxdelay, dev_maxparts;
 	const char *bip353;
+	const char *payer_note;
 };
 
 static struct command_result *
@@ -1729,6 +1730,8 @@ do_fetchinvoice(struct command *cmd, const char *offerstr, struct xpay_params *x
 		json_add_amount_msat(req->js, "amount_msat", *xparams->msat);
 	if (xparams->bip353)
 		json_add_string(req->js, "bip353", xparams->bip353);
+	if (xparams->payer_note)
+		json_add_string(req->js, "payer_note", xparams->payer_note);
 	return send_outreq(req);
 }
 
@@ -1777,6 +1780,7 @@ static struct command_result *json_xpay_params(struct command *cmd,
 	unsigned int *retryfor;
 	struct out_req *req;
 	struct xpay_params *xparams;
+	const char *payer_note;
 
 	if (!param_check(cmd, buffer, params,
 			 p_req("invstring", param_invstring, &invstring),
@@ -1786,6 +1790,7 @@ static struct command_result *json_xpay_params(struct command *cmd,
 			 p_opt_def("retry_for", param_number, &retryfor, 60),
 			 p_opt("partial_msat", param_msat, &partial),
 			 p_opt_def("maxdelay", param_u32, &maxdelay, 2016),
+			 p_opt("payer_note", param_string, &payer_note),
 			 p_opt_dev("dev_maxparts", param_u32, &maxparts, 100),
 			 NULL))
 		return command_param_failed();
@@ -1812,6 +1817,7 @@ static struct command_result *json_xpay_params(struct command *cmd,
 		xparams->layers = layers;
 		xparams->retryfor = *retryfor;
 		xparams->maxdelay = *maxdelay;
+		xparams->payer_note = tal_steal(xparams, payer_note);
 		xparams->dev_maxparts = *maxparts;
 		xparams->bip353 = NULL;
 
@@ -1827,6 +1833,7 @@ static struct command_result *json_xpay_params(struct command *cmd,
 		xparams->layers = layers;
 		xparams->retryfor = *retryfor;
 		xparams->maxdelay = *maxdelay;
+		xparams->payer_note = tal_steal(xparams, payer_note);
 		xparams->dev_maxparts = *maxparts;
 		xparams->bip353 = invstring;
 
@@ -1841,6 +1848,10 @@ static struct command_result *json_xpay_params(struct command *cmd,
 		return send_outreq(req);
 	}
 
+	if (payer_note)
+		return command_fail(cmd, JSONRPC2_INVALID_PARAMS,
+				    "payer_note only valid when paying an offer or BIP353 address");
+
 	return xpay_core(cmd, invstring,
 			 msat, maxfee, layers, *retryfor, partial, *maxdelay, *maxparts,
 			 as_pay);

contrib/msggen/msggen/schema.json

@@ -201,6 +201,12 @@ def test_xpay_simple(node_factory):
     with pytest.raises(RpcError, match="Already paid"):
         l1.rpc.xpay(b11_paid)
 
+    # Cannot specify payer_note with normal invoice
+    with pytest.raises(RpcError, match=r"payer_note only valid when paying an offer or BIP353 address"):
+        l1.rpc.xpay(invstring=b11, payer_note='x')
+    with pytest.raises(RpcError, match=r"payer_note only valid when paying an offer or BIP353 address"):
+        l1.rpc.xpay(invstring=b12, payer_note='x')
+
 
 def test_xpay_selfpay(node_factory):
     l1 = node_factory.get_node()
@@ -997,6 +1003,10 @@ def test_xpay_offer(node_factory):
     l1.rpc.xpay(offer2)
     l1.rpc.xpay(offer2, 5000)
 
+    # Now with a payer_note:
+    l1.rpc.xpay(invstring=offer2, payer_note="Eat at Joes!")
+    assert l1.rpc.decode(l2.rpc.listinvoices()['invoices'][3]['bolt12'])['invreq_payer_note'] == "Eat at Joes!"
+
 
 def test_xpay_bip353(node_factory):
     fakebip353_plugin = Path(__file__).parent / "plugins" / "fakebip353.py"
@@ -1022,3 +1032,7 @@ def test_xpay_bip353(node_factory):
     l2.daemon.wait_for_log('plugin-cln-xpay: notify msg info: DNS lookup for [email protected]')
     l2.daemon.wait_for_log('plugin-cln-xpay: notify msg info: Fetching invoice for offer')
     l2.daemon.wait_for_log(f'plugin-cln-xpay: notify msg debug: offer is {offer}')
+
+    # Now with a payer_note:
+    l2.rpc.xpay(invstring='[email protected]', amount_msat=123, payer_note="Eat at Joes!")
+    assert l1.rpc.decode(l1.rpc.listinvoices()['invoices'][1]['bolt12'])['invreq_payer_note'] == "Eat at Joes!"