offers: allow explicit fronting nodes for an offer.

rustyrussell · rustyrussell · commit 64e4519288ce · 2026-02-23T19:05:37.000+10:30
The next commit makes us honor these when issuing a payment.

Changelog-Added: JSON-RPC: `offer` now has a `fronting_nodes` option to specify neighbors for payer to use to fetch invoices and make payments.
Signed-off-by: Rusty Russell &lt;rusty@rustcorp.com.au&gt;
diff --git a/.msggen.json b/.msggen.json
@@ -3337,6 +3337,7 @@
             "Offer.absolute_expiry": 6,
             "Offer.amount": 1,
             "Offer.description": 2,
+            "Offer.fronting_nodes[]": 15,
             "Offer.issuer": 3,
             "Offer.label": 4,
             "Offer.optional_recurrence": 14,
@@ -11988,6 +11989,10 @@
             "added": "pre-v0.10.1",
             "deprecated": null
         },
+        "Offer.fronting_nodes[]": {
+            "added": "v26.04",
+            "deprecated": null
+        },
         "Offer.issuer": {
             "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
@@ -27735,6 +27735,17 @@
               "Make recurrence optional, for backwards compatibility (older payers will only pay once)."
             ]
           },
+          "fronting_nodes": {
+            "added": "v26.04",
+            "type": "array",
+            "items": {
+              "type": "pubkey"
+            },
+            "description": [
+              "An optional array of peer nodes to create blinded paths from.  One of these blinded paths will also be used for the invoice, when they request it.  This overrides the `payment-fronting-node` configuration setting.  If set to the empty array, this means *no fronting nodes*."
+            ],
+            "default": "The `payment-fronting-node` configuration setting"
+          },
           "dev_paths": {
             "hidden": true
           }
diff --git a/contrib/pyln-client/pyln/client/lightning.py b/contrib/pyln-client/pyln/client/lightning.py
@@ -1120,7 +1120,7 @@ def newaddr(self, addresstype=None):
 
     def offer(self, amount, description=None, issuer=None, label=None, quantity_max=None, absolute_expiry=None,
               recurrence=None, recurrence_base=None, recurrence_paywindow=None, recurrence_limit=None,
-              single_use=None):
+              single_use=None, fronting_nodes=None):
         """
         Create an offer (or returns an existing one), which is a precursor to creating one or more invoices.
         It automatically enables the processing of an incoming invoice_request, and issuing of invoices.
@@ -1137,6 +1137,7 @@ def offer(self, amount, description=None, issuer=None, label=None, quantity_max=
             "recurrence_paywindow": recurrence_paywindow,
             "recurrence_limit": recurrence_limit,
             "single_use": single_use,
+            "fronting_nodes": fronting_nodes,
         }
         return self.call("offer", payload)
 
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/doc/schemas/offer.json b/doc/schemas/offer.json
@@ -103,6 +103,17 @@
           "Make recurrence optional, for backwards compatibility (older payers will only pay once)."
         ]
       },
+      "fronting_nodes": {
+        "added": "v26.04",
+        "type": "array",
+        "items": {
+          "type": "pubkey"
+        },
+        "description": [
+          "An optional array of peer nodes to create blinded paths from.  One of these blinded paths will also be used for the invoice, when they request it.  This overrides the `payment-fronting-node` configuration setting.  If set to the empty array, this means *no fronting nodes*."
+        ],
+        "default": "The `payment-fronting-node` configuration setting"
+      },
       "dev_paths": {
         "hidden": true
       }
diff --git a/plugins/offers.c b/plugins/offers.c
@@ -64,7 +64,9 @@ struct gossmap *get_gossmap(struct plugin *plugin)
  *     - MUST include `offer_paths` containing one or more paths to the node
  *       from publicly reachable nodes.
  */
-bool we_want_blinded_path(struct plugin *plugin, bool for_payment)
+bool we_want_blinded_path(struct plugin *plugin,
+			  const struct pubkey *fronting_nodes,
+			  bool for_payment)
 {
 	const struct offers_data *od = get_offers_data(plugin);
 	struct node_id local_nodeid;
@@ -79,7 +81,7 @@ bool we_want_blinded_path(struct plugin *plugin, bool for_payment)
 	struct tlv_node_ann_tlvs *na_tlvs;
 
 	/* If we're fronting, we always want a blinded path */
-	if (od->fronting_nodes)
+	if (fronting_nodes)
 		return true;
 
 	node_id_from_pubkey(&local_nodeid, &od->id);
@@ -318,7 +320,7 @@ struct find_best_peer_data {
 				     const struct chaninfo *,
 				     void *);
 	u64 needed_features;
-	const struct pubkey *fronting_only;
+	const struct pubkey *fronting_nodes;
 	void *arg;
 };
 
@@ -377,8 +379,8 @@ static struct command_result *listincoming_done(struct command *cmd,
 		}
 		ci.feebase = feebase.millisatoshis; /* Raw: feebase */
 
-		if (data->fronting_only) {
-			if (!is_in_pubkeys(data->fronting_only, &ci.id))
+		if (data->fronting_nodes) {
+			if (!is_in_pubkeys(data->fronting_nodes, &ci.id))
 				continue;
 
 			/* If disconnected, don't eliminate, simply
@@ -423,7 +425,7 @@ static struct command_result *listincoming_done(struct command *cmd,
 
 struct command_result *find_best_peer_(struct command *cmd,
 				       u64 needed_features,
-				       const struct pubkey *fronting_only,
+				       const struct pubkey *fronting_nodes,
 				       struct command_result *(*cb)(struct command *,
 								    const struct chaninfo *,
 								    void *),
@@ -434,7 +436,10 @@ struct command_result *find_best_peer_(struct command *cmd,
 	data->cb = cb;
 	data->arg = arg;
 	data->needed_features = needed_features;
-	data->fronting_only = fronting_only;
+	if (fronting_nodes)
+		data->fronting_nodes = tal_dup_talarr(data, struct pubkey, fronting_nodes);
+	else
+		data->fronting_nodes = NULL;
 	req = jsonrpc_request_start(cmd, "listincoming",
 				    listincoming_done, forward_error, data);
 	return send_outreq(req);
diff --git a/plugins/offers.h b/plugins/offers.h
@@ -86,20 +86,22 @@ struct chaninfo {
 /* Calls listpeerchannels, then cb with best peer (if any!) which has needed_feature */
 struct command_result *find_best_peer_(struct command *cmd,
 				       u64 needed_features,
-				       const struct pubkey *fronting_only,
+				       const struct pubkey *fronting_nodes,
 				       struct command_result *(*cb)(struct command *,
 								    const struct chaninfo *,
 								    void *),
 				       void *arg);
 
-#define find_best_peer(cmd, needed_features, fronting_only, cb, arg)	\
-	find_best_peer_((cmd), (needed_features), (fronting_only),	\
+#define find_best_peer(cmd, needed_features, fronting_nodes, cb, arg)	\
+	find_best_peer_((cmd), (needed_features), (fronting_nodes),	\
 			typesafe_cb_preargs(struct command_result *, void *, \
 					    (cb), (arg),		\
 					    struct command *,		\
 					    const struct chaninfo *),	\
 			(arg))
 
 /* Do we want a blinded path from a peer? */
-bool we_want_blinded_path(struct plugin *plugin, bool for_payment);
+bool we_want_blinded_path(struct plugin *plugin,
+			  const struct pubkey *fronting_nodes,
+			  bool for_payment);
 #endif /* LIGHTNING_PLUGINS_OFFERS_H */
diff --git a/plugins/offers_invreq_hook.c b/plugins/offers_invreq_hook.c
@@ -392,7 +392,7 @@ static struct command_result *add_blindedpaths(struct command *cmd,
 {
 	const struct offers_data *od = get_offers_data(cmd->plugin);
 
-	if (!we_want_blinded_path(cmd->plugin, true))
+	if (!we_want_blinded_path(cmd->plugin, od->fronting_nodes, true))
 		return create_invoicereq(cmd, ir);
 
 	/* Technically, this only needs OPT_ROUTE_BLINDING, but we have a report
diff --git a/plugins/offers_offer.c b/plugins/offers_offer.c
@@ -205,6 +205,7 @@ struct offer_info {
 	struct tlv_offer *offer;
 	const char *label;
 	bool *single_use;
+	const struct pubkey *fronting_nodes;
 };
 
 static struct command_result *check_result(struct command *cmd,
@@ -331,15 +332,15 @@ static struct command_result *maybe_add_path(struct command *cmd,
 		 *     - MUST include `offer_paths` containing one or more paths to the node from
 		 *       publicly reachable nodes.
 		 */
-		if (we_want_blinded_path(cmd->plugin, false)) {
+		if (we_want_blinded_path(cmd->plugin, offinfo->fronting_nodes, false)) {
 			/* We use *all* fronting nodes (not just "best" one)
 			 * for offers */
-			if (od->fronting_nodes) {
+			if (offinfo->fronting_nodes) {
 				offinfo->offer->offer_paths
 					= offer_onehop_paths(offinfo->offer, od,
 							     offinfo->offer,
-							     od->fronting_nodes,
-							     tal_count(od->fronting_nodes));
+							     offinfo->fronting_nodes,
+							     tal_count(offinfo->fronting_nodes));
 			} else {
 				return find_best_peer(cmd, 1ULL << OPT_ONION_MESSAGES,
 						      NULL,
@@ -446,6 +447,30 @@ static struct command_result *param_paths(struct command *cmd, const char *name,
 	return NULL;
 }
 
+static struct command_result *param_pubkey_arr(struct command *cmd,
+					       const char *name,
+					       const char *buffer,
+					       const jsmntok_t *tok,
+					       const struct pubkey **keys)
+{
+	size_t i;
+	const jsmntok_t *t;
+	struct pubkey *arr;
+
+	if (tok->type != JSMN_ARRAY)
+		return command_fail_badparam(cmd, name, buffer, tok,
+					     "should be an array of nodes");
+
+	arr = tal_arr(cmd, struct pubkey, tok->size);
+	json_for_each_arr(i, t, tok) {
+		if (!json_to_pubkey(buffer, t, &arr[i]))
+			return command_fail_badparam(cmd, name, buffer, t,
+						     "invalid pubkey");
+	}
+	*keys = arr;
+	return NULL;
+}
+
 struct command_result *json_offer(struct command *cmd,
 				  const char *buffer,
 				  const jsmntok_t *params)
@@ -484,10 +509,22 @@ struct command_result *json_offer(struct command *cmd,
 			 p_opt_def("optional_recurrence",
 				   param_bool,
 				   &optional_recurrence, false),
+			 p_opt("fronting_nodes",
+			       param_pubkey_arr,
+			       &offinfo->fronting_nodes),
 			 p_opt("dev_paths", param_paths, &paths),
 			 NULL))
 		return command_param_failed();
 
+
+	/* If they don't specify explicitly, use config (if any) */
+	if (!offinfo->fronting_nodes)
+		offinfo->fronting_nodes = od->fronting_nodes;
+	else if (tal_count(offinfo->fronting_nodes) == 0) {
+		/* [] means "no fronting" */
+		offinfo->fronting_nodes = tal_free(offinfo->fronting_nodes);
+	}
+
 	/* BOLT #12:
 	 *
 	 * - if the chain for the invoice is not solely bitcoin:
@@ -775,7 +812,7 @@ struct command_result *json_invoicerequest(struct command *cmd,
 	 *   - MUST set `invreq_features`.`features` to the bitmap of features.
 	 */
 
-	if (we_want_blinded_path(cmd->plugin, false)) {
+	if (we_want_blinded_path(cmd->plugin, od->fronting_nodes, false)) {
 		struct invrequest_data *idata = tal(cmd, struct invrequest_data);
 		idata->invreq = invreq;
 		idata->single_use = *single_use;
