lightningd: deprecate "message": null in channel_state_changed notifications.

rustyrussell · rustyrussell · commit f5ce32dc8068 · 2025-10-01T10:22:38.000+09:30
Somehow I missed this when deprecating `short_channel_id` being null.

Changelog-Deprecated: Plugins: `channel_state_changed` notification `message` field being `null`: it will be omitted instead.
Signed-off-by: Rusty Russell &lt;rusty@rustcorp.com.au&gt;
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/notifications.rs b/cln-rpc/src/notifications.rs
@@ -192,6 +192,8 @@ impl ToString for ChannelStateChangedCause {
 
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct ChannelStateChangedNotification {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub message: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub old_state: Option<ChannelState>,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -201,7 +203,6 @@ pub struct ChannelStateChangedNotification {
     // Path `channel_state_changed.new_state`
     pub new_state: ChannelState,
     pub channel_id: Sha256,
-    pub message: String,
     pub peer_id: PublicKey,
     pub timestamp: String,
 }
diff --git a/common/json_stream.c b/common/json_stream.c
@@ -323,11 +323,6 @@ void json_add_bool(struct json_stream *result, const char *fieldname, bool value
 	json_add_primitive(result, fieldname, value ? "true" : "false");
 }
 
-void json_add_null(struct json_stream *stream, const char *fieldname)
-{
-	json_add_primitive(stream, fieldname, "null");
-}
-
 void json_add_hex(struct json_stream *js, const char *fieldname,
 		  const void *data, size_t len)
 {
diff --git a/common/json_stream.h b/common/json_stream.h
@@ -242,8 +242,7 @@ void json_add_s32(struct json_stream *result, const char *fieldname,
 void json_add_bool(struct json_stream *result, const char *fieldname,
 		   bool value);
 
-/* '"fieldname" : null' or 'null' if fieldname is NULL */
-void json_add_null(struct json_stream *stream, const char *fieldname);
+/* Looking for json_add_null?  Don't do that: we omit fields, don't 'null' them! */
 
 /* '"fieldname" : "0189abcdef..."' or "0189abcdef..." if fieldname is NULL */
 void json_add_hex(struct json_stream *result, const char *fieldname,
diff --git a/contrib/msggen/msggen/schema.json b/contrib/msggen/msggen/schema.json
@@ -36286,8 +36286,7 @@
           "channel_id",
           "timestamp",
           "new_state",
-          "cause",
-          "message"
+          "cause"
         ],
         "properties": {
           "peer_id": {
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/developers-guide/deprecated-features.md b/doc/developers-guide/deprecated-features.md
@@ -24,6 +24,7 @@ hidden: false
 | channel_state_changed.null_scid         | Notification Field | v25.09        | v26.09         | In channel_state_changed notification, `short_channel_id` will be missing instead of `null`                                            |
 | notification.payload                    | Notification Field | v25.09        | v26.09         | Notifications from plugins used to have fields in `payload` sub-object, now they are not (just like normal notifications)              |
 | pay_notifications.raw_fields            | Field              | v25.09           | v26.09         | `channel_hint_update`, `pay_failure` and `pay_success` notifications now wrap members in an object of the same name                    |
+| channel_state_changed.null_message     | Notification Field | v25.12        | v26.12         | In channel_state_changed notification, `message` will be missing instead of `null`                                                      |
 
 Inevitably there are features which need to change: either to be generalized, or removed when they can no longer be supported.
 
diff --git a/doc/schemas/notification/channel_state_changed.json b/doc/schemas/notification/channel_state_changed.json
@@ -15,8 +15,7 @@
       "channel_id",
       "timestamp",
       "new_state",
-      "cause",
-      "message"
+      "cause"
     ],
     "properties": {
       "peer_id": {
diff --git a/lightningd/notification.c b/lightningd/notification.c
@@ -275,6 +275,12 @@ void notify_channel_opened(struct lightningd *ld,
 	notify_send(ld, n);
 }
 
+/* Don't use this: omit fields instead! */
+static void json_add_null(struct json_stream *stream, const char *fieldname)
+{
+	json_add_primitive(stream, fieldname, "null");
+}
+
 static void channel_state_changed_notification_serialize(struct json_stream *stream,
 							 struct lightningd *ld,
 							 const struct node_id *peer_id,
@@ -304,8 +310,12 @@ static void channel_state_changed_notification_serialize(struct json_stream *str
 	json_add_string(stream, "cause", channel_change_state_reason_str(cause));
 	if (message != NULL)
 		json_add_string(stream, "message", message);
-	else
+	else if (lightningd_deprecated_out_ok(ld, ld->deprecated_ok,
+					      "channel_state_changed",
+					      "null_message",
+					      "v25.12", "v26.12")) {
 		json_add_null(stream, "message");
+	}
 }
 
 REGISTER_NOTIFICATION(channel_state_changed)
diff --git a/plugins/bcli.c b/plugins/bcli.c
@@ -396,6 +396,12 @@ static struct command_result *command_err_bcli_badjson(struct bitcoin_cli *bcli,
 	return command_done_err(bcli->cmd, BCLI_ERROR, err, NULL);
 }
 
+/* Don't use this in general: it's better to omit fields. */
+static void json_add_null(struct json_stream *stream, const char *fieldname)
+{
+	json_add_primitive(stream, fieldname, "null");
+}
+
 static struct command_result *process_getutxout(struct bitcoin_cli *bcli)
 {
 	const jsmntok_t *tokens;
diff --git a/tests/test_plugin.py b/tests/test_plugin.py
@@ -967,12 +967,12 @@ def wait_for_event(node):
     assert(event1['old_state'] == "ONCHAIN")
     assert(event1['new_state'] == "CLOSED")
     assert(event1['cause'] == "onchain")
-    assert(event1['message'] is None)
+    assert('message' not in event1)
     event2 = wait_for_event(l2)
     assert(event2['old_state'] == "ONCHAIN")
     assert(event2['new_state'] == "CLOSED")
     assert(event2['cause'] == "onchain")
-    assert(event2['message'] is None)
+    assert('message' not in event2)
 
 
 @pytest.mark.openchannel('v1')
@@ -1102,13 +1102,13 @@ def wait_for_event(node):
     assert(event1['old_state'] == "ONCHAIN")
     assert(event1['new_state'] == "CLOSED")
     assert(event1['cause'] == "onchain")
-    assert(event1['message'] is None)
+    assert('message' not in event1)
 
     event2 = wait_for_event(l2)
     assert(event2['old_state'] == "ONCHAIN")
     assert(event2['new_state'] == "CLOSED")
     assert(event2['cause'] == "onchain")
-    assert(event2['message'] is None)
+    assert('message' not in event2)
 
 
 @pytest.mark.openchannel('v1')

Original file line number	Diff line number	Diff line change
`@@ -323,11 +323,6 @@ void json_add_bool(struct json_stream result, const char fieldname, bool value`
`323`	`323`	`json_add_primitive(result, fieldname, value ? "true" : "false");`
`324`	`324`	`}`
`325`	`325`
`326`		`-void json_add_null(struct json_stream stream, const char fieldname)`
`327`		`-{`
`328`		`- json_add_primitive(stream, fieldname, "null");`
`329`		`-}`
`330`		`-`
`331`	`326`	`void json_add_hex(struct json_stream js, const char fieldname,`
`332`	`327`	`const void *data, size_t len)`
`333`	`328`	`{`