lightningd: add channel_id filter to listpeerchannels

Sometimes we don't know the short_channel_id yet (e.g the channel has
not been broadcasted), but we still know the channel_id from the funding
transaction. Add a channel_id filter to listpeerchannels and clarify
that id, short_channel_id and channel_id are mutually exclusive.

Changelog-Added: `listpeerchannels` now accepts a `channel_id` filter,
for cases where the `short_channel_id` is not yet known.

Signed-off-by: Peter Neuroth <[email protected]>

Author: nepet

.msggen.json

@@ -3030,6 +3030,7 @@
             "ListPeerChannels.channels[].updates.remote.htlc_minimum_msat": 1
         },
         "ListpeerchannelsRequest": {
+            "ListPeerChannels.channel_id": 3,
             "ListPeerChannels.id": 1,
             "ListPeerChannels.short_channel_id": 2
         },
@@ -10692,6 +10693,10 @@
             "added": "v23.02",
             "deprecated": null
         },
+        "ListPeerChannels.channel_id": {
+            "added": "v25.12",
+            "deprecated": null
+        },
         "ListPeerChannels.channels[]": {
             "added": "v23.02",
             "deprecated": null

cln-grpc/proto/node.proto

@@ -23853,9 +23853,11 @@
       "rpc": "listpeerchannels",
       "title": "Command returning data on channels of connected lightning nodes",
       "description": [
-        "The **listpeerchannels** RPC command returns list of this node's channels, with the possibility to filter them by peer's node id.",
+        "The **listpeerchannels** RPC command returns a list of this node's channels.",
         "",
-        "If no *id* is supplied, then channel data on all lightning nodes that are connected, or not connected but have open channels with this node, are returned."
+        "By default, data for all known channels is returned, including those to peers that are currently connected and those to peers that are disconnected but still have open channels.",
+        "",
+        "At most one of *id*, *short_channel_id* or *channel_id* may be provided as a filter. If more than one is provided, the command fails with an error."
       ],
       "categories": [
         "readonly"
@@ -23867,14 +23869,21 @@
           "id": {
             "type": "pubkey",
             "description": [
-              "If supplied, limits the channels to just the peer with the given ID, if it exists."
+              "If supplied, limits the channels to just the peer with the given ID, if it exists. Cannot be used with 'short_channel_id' or 'channel_id'."
             ]
           },
           "short_channel_id": {
             "added": "v25.05",
             "type": "short_channel_id",
             "description": [
-              "If supplied, limits the channels to just this short_channel_id (or local alias), if it exists.  Cannot be used with 'id'."
+              "If supplied, limits the channels to just this short_channel_id (or local alias), if it exists. Cannot be used with 'id' or 'channel_id'."
+            ]
+          },
+          "channel_id": {
+            "added": "v25.12",
+            "type": "hash",
+            "description": [
+              "If supplied, limits the channels to just this channel_id, if it exists. Cannot be used with 'id' or 'short_channel_id'."
             ]
           }
         }

cln-grpc/src/convert.rs

@@ -5,9 +5,11 @@
   "rpc": "listpeerchannels",
   "title": "Command returning data on channels of connected lightning nodes",
   "description": [
-    "The **listpeerchannels** RPC command returns list of this node's channels, with the possibility to filter them by peer's node id.",
+    "The **listpeerchannels** RPC command returns a list of this node's channels.",
     "",
-    "If no *id* is supplied, then channel data on all lightning nodes that are connected, or not connected but have open channels with this node, are returned."
+    "By default, data for all known channels is returned, including those to peers that are currently connected and those to peers that are disconnected but still have open channels.",
+    "",
+    "At most one of *id*, *short_channel_id* or *channel_id* may be provided as a filter. If more than one is provided, the command fails with an error."
   ],
   "categories": [
     "readonly"
@@ -19,14 +21,21 @@
       "id": {
         "type": "pubkey",
         "description": [
-          "If supplied, limits the channels to just the peer with the given ID, if it exists."
+          "If supplied, limits the channels to just the peer with the given ID, if it exists. Cannot be used with 'short_channel_id' or 'channel_id'."
         ]
       },
       "short_channel_id": {
         "added": "v25.05",
         "type": "short_channel_id",
         "description": [
-          "If supplied, limits the channels to just this short_channel_id (or local alias), if it exists.  Cannot be used with 'id'."
+          "If supplied, limits the channels to just this short_channel_id (or local alias), if it exists. Cannot be used with 'id' or 'channel_id'."
+        ]
+      },
+      "channel_id": {
+        "added": "v25.12",
+        "type": "hash",
+        "description": [
+          "If supplied, limits the channels to just this channel_id, if it exists. Cannot be used with 'id' or 'short_channel_id'."
         ]
       }
     }

cln-rpc/src/model.rs

@@ -6,6 +6,7 @@
 #include <ccan/tal/str/str.h>
 #include <channeld/channeld_wiregen.h>
 #include <common/addr.h>
+#include <common/channel_id.h>
 #include <common/htlc_trim.h>
 #include <common/initial_commit_tx.h>
 #include <common/json_channel_type.h>
@@ -2631,16 +2632,22 @@ static struct command_result *json_listpeerchannels(struct command *cmd,
 	struct peer *peer;
 	struct json_stream *response;
 	struct short_channel_id *scid;
+	struct channel_id *cid;
 
 	if (!param_check(cmd, buffer, params,
 			 p_opt("id", param_node_id, &peer_id),
 			 p_opt("short_channel_id", param_short_channel_id, &scid),
+			 p_opt("channel_id", param_channel_id, &cid),
 			 NULL))
 		return command_param_failed();
 
-	if (scid && peer_id)
+	int count = (peer_id != NULL) + (scid != NULL) + (cid != NULL);
+	if (count > 1) {
 		return command_fail(cmd, JSONRPC2_INVALID_PARAMS,
-				    "Cannot specify both short_channel_id and id");
+				    "Must not specify more than one of "
+					 "short_channel_id, channel_id or id"
+		);
+	}
 
 	response = json_stream_success(cmd);
 	json_array_start(response, "channels");
@@ -2653,6 +2660,10 @@ static struct command_result *json_listpeerchannels(struct command *cmd,
 		const struct channel *c = any_channel_by_scid(cmd->ld, *scid, true);
 		if (c)
 			json_add_channel(cmd, response, NULL, c, c->peer);
+	} else if (cid) {
+		const struct channel *c = channel_by_cid(cmd->ld, cid);
+		if (c)
+			json_add_channel(cmd, response, NULL, c, c->peer);
 	} else {
 		struct peer_node_id_map_iter it;
 

contrib/msggen/msggen/schema.json

@@ -53,6 +53,10 @@ void broadcast_tx_(const tal_t *ctx UNNEEDED,
 		   bool (*refresh)(struct channel * UNNEEDED, const struct bitcoin_tx ** UNNEEDED, void *) UNNEEDED,
 		   void *cbarg TAKES UNNEEDED)
 { fprintf(stderr, "broadcast_tx_ called!\n"); abort(); }
+/* Generated stub for channel_by_cid */
+struct channel *channel_by_cid(struct lightningd *ld UNNEEDED,
+			       const struct channel_id *cid UNNEEDED)
+{ fprintf(stderr, "channel_by_cid called!\n"); abort(); }
 /* Generated stub for channel_change_state_reason_str */
 const char *channel_change_state_reason_str(enum state_change reason UNNEEDED)
 { fprintf(stderr, "channel_change_state_reason_str called!\n"); abort(); }