lightningd: deprecate (undocumented!) "unknown" old_state field in channel_state_changed notification.

Reported-by: daywalker90
Changelog-Deprecated: JSON-RPC: channel_state_changed notification field `old_state` value "unknown" (it will be omitted, instead)
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

Author: rustyrussell

cln-grpc/proto/node.proto

@@ -188,12 +188,12 @@ impl ToString for ChannelStateChangedCause {
 
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct ChannelStateChangedNotification {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub old_state: Option<ChannelState>,
     // Path `channel_state_changed.cause`
     pub cause: ChannelStateChangedCause,
     // Path `channel_state_changed.new_state`
     pub new_state: ChannelState,
-    // Path `channel_state_changed.old_state`
-    pub old_state: ChannelState,
     pub channel_id: Sha256,
     pub message: String,
     pub peer_id: PublicKey,

cln-grpc/src/convert.rs

@@ -36672,7 +36672,6 @@
           "channel_id",
           "short_channel_id",
           "timestamp",
-          "old_state",
           "new_state",
           "cause",
           "message"
@@ -36725,7 +36724,8 @@
               "DUALOPEND_OPEN_COMMIT_READY"
             ],
             "description": [
-              "The channel state, in particular \"CHANNELD_NORMAL\" means the channel can be used normally"
+              "The channel state, in particular \"CHANNELD_NORMAL\" means the channel can be used normally.",
+              "The deprecated value 'unknown' is also present for new channels: after 26.02 this field will be omitted instead."
             ],
             "added": "pre-v0.10.1"
           },

cln-rpc/src/notifications.rs

@@ -27,6 +27,7 @@ hidden: false
 | xpay.ignore_bolt12_mpp               | Field              | v25.05           | v25.11         | Try MPP even if the BOLT12 invoice doesn't explicitly allow it (CLN didn't until 25.02)                                                |
 | listpeerchannels.max_total_htlc_in_msat | Field           | v25.02           | v26.02         | Use our_max_total_htlc_out_msat                                                                                                              |
 | wait.details                         | Field              | v25.05           | v26.05         | Use subsystem-specific object instead                                                                                                  |
+| channel_state_changed.old_state.unknown | Notification Field | v25.05        | v26.02         | Value "unknown" is deprecated: field will be omitted instead                                                                           |
 
 Inevitably there are features which need to change: either to be generalized, or removed when they can no longer be supported.
 

contrib/msggen/msggen/schema.json

@@ -15,7 +15,6 @@
       "channel_id",
       "short_channel_id",
       "timestamp",
-      "old_state",
       "new_state",
       "cause",
       "message"
@@ -68,7 +67,8 @@
           "DUALOPEND_OPEN_COMMIT_READY"
         ],
         "description": [
-          "The channel state, in particular \"CHANNELD_NORMAL\" means the channel can be used normally"
+          "The channel state, in particular \"CHANNELD_NORMAL\" means the channel can be used normally.",
+          "The deprecated value 'unknown' is also present for new channels: after 26.02 this field will be omitted instead."
         ],
         "added": "pre-v0.10.1"
       },

contrib/pyln-grpc-proto/pyln/grpc/node_pb2.py

@@ -255,6 +255,7 @@ void notify_channel_opened(struct lightningd *ld,
 }
 
 static void channel_state_changed_notification_serialize(struct json_stream *stream,
+							 struct lightningd *ld,
 							 const struct node_id *peer_id,
 							 const struct channel_id *cid,
 							 const struct short_channel_id *scid,
@@ -271,7 +272,10 @@ static void channel_state_changed_notification_serialize(struct json_stream *str
 	else
 		json_add_null(stream, "short_channel_id");
 	json_add_timeiso(stream, "timestamp", timestamp);
-	json_add_string(stream, "old_state", channel_state_str(old_state));
+	if (old_state != 0 || lightningd_deprecated_out_ok(ld, ld->deprecated_ok,
+							   "channel_state_changed", "old_state.unknown",
+							   "v25.05", "v26.02"))
+		json_add_string(stream, "old_state", channel_state_str(old_state));
 	json_add_string(stream, "new_state", channel_state_str(new_state));
 	json_add_string(stream, "cause", channel_change_state_reason_str(cause));
 	if (message != NULL)
@@ -293,7 +297,7 @@ void notify_channel_state_changed(struct lightningd *ld,
 				  const char *message)
 {
 	struct jsonrpc_notification *n = notify_start("channel_state_changed");
-	channel_state_changed_notification_serialize(n->stream, peer_id, cid, scid, timestamp, old_state, new_state, cause, message);
+	channel_state_changed_notification_serialize(n->stream, ld, peer_id, cid, scid, timestamp, old_state, new_state, cause, message);
 	notify_send(ld, n);
 }
 

doc/developers-guide/deprecations.md

@@ -1140,10 +1140,11 @@ static struct command_result *json_channel_state_changed(struct command *cmd,
 	struct channel_id cid;
 	const char *err, *old_state, *new_state;
 
+	old_state = NULL;
 	err = json_scan(tmpctx, buf, params,
 			"{channel_state_changed:"
 			"{channel_id:%"
-			",old_state:%"
+			",old_state?:%"
 			",new_state:%}}",
 			JSON_SCAN(json_to_channel_id, &cid),
 			JSON_SCAN_TAL(cmd, json_strdup, &old_state),
@@ -1159,6 +1160,9 @@ static struct command_result *json_channel_state_changed(struct command *cmd,
 	/* Moving out of "awaiting lockin",
 	 * means we clean up the datastore */
 	/* FIXME: splicing state? */
+	if (!old_state)
+		return notification_handled(cmd);
+
 	if (!streq(old_state, "DUALOPEND_AWAITING_LOCKIN")
 	    && !streq(old_state, "CHANNELD_AWAITING_LOCKIN"))
 		return notification_handled(cmd);

doc/schemas/notification/channel_state_changed.json

@@ -869,7 +869,7 @@ def wait_for_event(node):
         assert(event2['cause'] == "remote")
 
         for ev in [event1, event2]:
-            assert(ev['old_state'] == "unknown")
+            'old_state' not in ev
             assert(ev['new_state'] == "CHANNELD_AWAITING_LOCKIN")
             assert(ev['message'] == "new channel opened")
 
@@ -1006,7 +1006,7 @@ def wait_for_event(node):
         assert event2['new_state'] == "DUALOPEND_AWAITING_LOCKIN"
         assert event2['message'] == "Sigs exchanged, waiting for lock-in"
     else:
-        assert(event2['old_state'] == "unknown")
+        assert "unknown" not in event2
         assert(event2['new_state'] == "CHANNELD_AWAITING_LOCKIN")
         assert(event2['message'] == "new channel opened")