lightningd: add channel_id filter to listpeerchannels

nepet · cdecker · commit 2971f5d95663 · 2026-02-24T16:51:59.000+01:00
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 known yet.

Signed-off-by: Peter Neuroth &lt;pet.v.ne@gmail.com&gt;
diff --git a/.msggen.json b/.msggen.json
@@ -3045,6 +3045,7 @@
             "ListPeerChannels.channels[].updates.remote.htlc_minimum_msat": 1
         },
         "ListpeerchannelsRequest": {
+            "ListPeerChannels.channel_id": 3,
             "ListPeerChannels.id": 1,
             "ListPeerChannels.short_channel_id": 2
         },
@@ -10757,6 +10758,10 @@
             "added": "v23.02",
             "deprecated": null
         },
+        "ListPeerChannels.channel_id": {
+            "added": "v26.03",
+            "deprecated": null
+        },
         "ListPeerChannels.channels[]": {
             "added": "v23.02",
             "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
@@ -23509,9 +23509,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"
@@ -23523,14 +23525,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": "v26.03",
+            "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'."
             ]
           }
         }
diff --git a/contrib/pyln-client/pyln/client/lightning.py b/contrib/pyln-client/pyln/client/lightning.py
@@ -1052,7 +1052,7 @@ def listpeers(self, peerid=None, level=None):
         }
         return self.call("listpeers", payload)
 
-    def listpeerchannels(self, peer_id=None, short_channel_id=None):
+    def listpeerchannels(self, peer_id=None, short_channel_id=None, channel_id=None):
         """
         Show current peers channels, and if the {peer_id} is specified
         all the channels for the peer are returned, and if {short_channel_id} is
@@ -1061,6 +1061,7 @@ def listpeerchannels(self, peer_id=None, short_channel_id=None):
         payload = {
             "id": peer_id,
             "short_channel_id": short_channel_id,
+            "channel_id": channel_id,
         }
         return self.call("listpeerchannels", 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/listpeerchannels.json b/doc/schemas/listpeerchannels.json
@@ -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": "v26.03",
+        "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'."
         ]
       }
     }
diff --git a/lightningd/peer_control.c b/lightningd/peer_control.c
@@ -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>
@@ -2630,16 +2631,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");
@@ -2652,6 +2659,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;
 
diff --git a/lightningd/test/run-invoice-select-inchan.c b/lightningd/test/run-invoice-select-inchan.c
@@ -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(); }
diff --git a/plugins/lsps-plugin/src/cln_adapters/rpc.rs b/plugins/lsps-plugin/src/cln_adapters/rpc.rs
@@ -80,6 +80,7 @@ impl LightningProvider for ClnApiRpc {
         let mut rpc = self.create_rpc().await?;
         let r = rpc
             .call_typed(&ListpeerchannelsRequest {
+                channel_id: None,
                 id: Some(peer_id.to_owned()),
                 short_channel_id: None,
             })
diff --git a/tests/test_connection.py b/tests/test_connection.py
@@ -4635,8 +4635,21 @@ def test_listpeerchannels_by_scid(node_factory):
     assert l2.rpc.listpeerchannels(short_channel_id=c['alias']['local']) == chans
     assert l2.rpc.listpeerchannels(short_channel_id=c['alias']['remote']) == {'channels': []}
 
-    with pytest.raises(RpcError, match="Cannot specify both short_channel_id and id"):
+    with pytest.raises(RpcError, match="Must not specify more than one of short_channel_id, channel_id or id"):
         l2.rpc.listpeerchannels(peer_id=l1.info['id'], short_channel_id='1x2x3')
+        l2.rpc.listpeerchannels(channel_id=c["channel_id"], short_channel_id='1x2x3')
+
+
+def test_listpeerchannels_by_channel_id(node_factory):
+    l1, l2, l3 = node_factory.line_graph(3, announce_channels=False)
+
+    chans = l2.rpc.listpeerchannels(l1.info['id'])
+    c = only_one(chans['channels'])
+    assert l2.rpc.listpeerchannels(channel_id=c['channel_id']) == chans
+
+    with pytest.raises(RpcError, match="Must not specify more than one of short_channel_id, channel_id or id"):
+        l2.rpc.listpeerchannels(peer_id=l1.info['id'], channel_id=c['channel_id'])
+        l2.rpc.listpeerchannels(short_channel_id="1x2x3", channel_id=['channel_id'])
 
 
 def test_networkevents(node_factory, executor):

Original file line number	Diff line number	Diff line change
`@@ -1052,7 +1052,7 @@ def listpeers(self, peerid=None, level=None):`
`1052`	`1052`	`}`
`1053`	`1053`	`return self.call("listpeers", payload)`
`1054`	`1054`
`1055`		`- def listpeerchannels(self, peer_id=None, short_channel_id=None):`
	`1055`	`+ def listpeerchannels(self, peer_id=None, short_channel_id=None, channel_id=None):`
`1056`	`1056`	`"""`
`1057`	`1057`	`Show current peers channels, and if the {peer_id} is specified`
`1058`	`1058`	`all the channels for the peer are returned, and if {short_channel_id} is`
`@@ -1061,6 +1061,7 @@ def listpeerchannels(self, peer_id=None, short_channel_id=None):`
`1061`	`1061`	`payload = {`
`1062`	`1062`	`"id": peer_id,`
`1063`	`1063`	`"short_channel_id": short_channel_id,`
	`1064`	`+ "channel_id": channel_id,`
`1064`	`1065`	`}`
`1065`	`1066`	`return self.call("listpeerchannels", payload)`
`1066`	`1067`