ElementsProject · rustyrussell · May 5, 2026
@@ -15924,6 +15924,45 @@
         }
       ]
     },
+    "graceful.json": {
+      "$schema": "../rpc-schema-draft.json",
+      "type": "object",
+      "rpc": "graceful",
+      "added": "v26.06",
+      "title": "Command to prepare Core Lightning node for stopping.",
+      "description": [
+        "**graceful** is a RPC command to prevent further htlcs, and disconnect all idle peers.  It returns when all HTLCs are complete, and all peers disconnected: then you can shutdown.  It also sends information about HTLC expiry, so you can judge how long it is safe to be offline."
+      ],
+      "request": {
+        "required": [],
+        "additionalProperties": false,
+        "properties": {}
+      },
+      "response": {
+        "required": [],
+        "additionalProperties": false,
+        "properties": {}
+      },
+      "author": [
+        "Rusty Russell [rusty@rustcorp.com.au](mailto:rusty@rustcorp.com.au) is mainly responsible."
+      ],
+      "see_also": [
+        "lightning-stop(7)"
+      ],
+      "resources": [
+        "Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)"
+      ],
+      "examples": [
+        {
+          "request": {
+            "id": "example:graceful#1",
+            "method": "graceful",
+            "params": {}
+          },
+          "response": {}
+        }
+      ]
+    },
     "help.json": {
       "$schema": "../rpc-schema-draft.json",
       "type": "object",
@@ -34964,6 +35003,9 @@
         "Vincenzo Palazzo [vincenzo.palazzo@protonmail.com](mailto:vincenzo.palazzo@protonmail.com) wrote the initial version of this man page,",
         "but many others did the hard work of actually implementing this rpc command."
       ],
+      "see_also": [
+        "lightning-graceful(7)"
+      ],
       "resources": [
         "Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)"
       ],

diff --git a/doc/Makefile b/doc/Makefile
@@ -76,6 +76,7 @@ MARKDOWNPAGES := doc/addgossip.7 \
 	doc/getlog.7 \
 	doc/getroute.7 \
 	doc/getroutes.7 \
+	doc/graceful.7 \
 	doc/help.7 \
 	doc/injectonionmessage.7 \
 	doc/injectpaymentonion.7 \

diff --git a/doc/index.rst b/doc/index.rst
@@ -84,6 +84,7 @@ Core Lightning Documentation
    getlog <getlog.7.md>
    getroute <getroute.7.md>
    getroutes <getroutes.7.md>
+   graceful <graceful.7.md>
    help <help.7.md>
    hook-commitment_revocation <hook-commitment_revocation.7.md>
    hook-custommsg <hook-custommsg.7.md>

diff --git a/doc/schemas/graceful.json b/doc/schemas/graceful.json
@@ -0,0 +1,42 @@
+{
+  "$schema": "../rpc-schema-draft.json",
+  "type": "object",
+  "rpc": "graceful",
+  "added": "v26.06",
+  "title": "Command to prepare Core Lightning node for stopping.",
+  "description": [
+    "**graceful** is a RPC command to prevent further htlcs, and disconnect all idle peers.  It returns when all HTLCs are complete, and all peers disconnected: then you can shutdown.  It also sends information about HTLC expiry, so you can judge how long it is safe to be offline."
+  ],
+  "request": {
+    "required": [],
+    "additionalProperties": false,
+    "properties": {}
+  },
+  "response": {
+    "required": [
+    ],
+    "additionalProperties": false,
+    "properties": {
+    }
+  },
+  "author": [
+    "Rusty Russell [rusty@rustcorp.com.au](mailto:rusty@rustcorp.com.au) is mainly responsible."
+  ],
+  "see_also": [
+    "lightning-stop(7)"
+  ],
+  "resources": [
+    "Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)"
+  ],
+  "examples": [
+    {
+      "request": {
+        "id": "example:graceful#1",
+        "method": "graceful",
+        "params": {}
+      },
+      "response": {
+      }
+    }
+  ]
+}
diff --git a/doc/schemas/stop.json b/doc/schemas/stop.json
@@ -30,6 +30,9 @@
     "Vincenzo Palazzo [vincenzo.palazzo@protonmail.com](mailto:vincenzo.palazzo@protonmail.com) wrote the initial version of this man page,",
     "but many others did the hard work of actually implementing this rpc command."
   ],
+  "see_also": [
+    "lightning-graceful(7)"
+  ],
   "resources": [
     "Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)"
   ],

diff --git a/lightningd/channel.c b/lightningd/channel.c
@@ -27,7 +27,7 @@ void channel_set_owner(struct channel *channel, struct subd *owner)
 		subd_release_channel(old_owner, channel);
 }
 
-struct htlc_out *channel_has_htlc_out(struct channel *channel)
+struct htlc_out *channel_has_htlc_out(const struct channel *channel)
 {
 	struct htlc_out_map_iter outi;
 	struct htlc_out *hout;
@@ -43,7 +43,7 @@ struct htlc_out *channel_has_htlc_out(struct channel *channel)
 	return NULL;
 }
 
-struct htlc_in *channel_has_htlc_in(struct channel *channel)
+struct htlc_in *channel_has_htlc_in(const struct channel *channel)
 {
 	struct htlc_in_map_iter ini;
 	struct htlc_in *hin;

diff --git a/lightningd/channel.h b/lightningd/channel.h
@@ -962,8 +962,8 @@ void get_channel_basepoints(struct lightningd *ld,
 void channel_set_billboard(struct channel *channel, bool perm,
 			   const char *str TAKES);
 
-struct htlc_in *channel_has_htlc_in(struct channel *channel);
-struct htlc_out *channel_has_htlc_out(struct channel *channel);
+struct htlc_in *channel_has_htlc_in(const struct channel *channel);
+struct htlc_out *channel_has_htlc_out(const struct channel *channel);
 
 /* hin can be NULL */
 const u8 *channel_update_for_error(const tal_t *ctx,

diff --git a/lightningd/jsonrpc.c b/lightningd/jsonrpc.c
@@ -1156,7 +1156,8 @@ static struct io_plan *start_json_stream(struct io_conn *conn,
 	io_wake(conn);
 
 	/* Once the stop_conn conn is drained, we can shut down. */
-	if (jcon->ld->stop_conn == conn && jcon->ld->state == LD_STATE_RUNNING) {
+	if (jcon->ld->stop_conn == conn
+	    && (jcon->ld->state == LD_STATE_RUNNING || jcon->ld->state == LD_STATE_GRACE)) {
 		/* Return us to toplevel lightningd.c */
 		log_debug(jcon->ld->log, "io_break: %s", __func__);
 		io_break(jcon->ld);

diff --git a/lightningd/lightningd.c b/lightningd/lightningd.c
@@ -238,6 +238,7 @@ static struct lightningd *new_lightningd(const tal_t *ctx)
 	list_head_init(&ld->splice_commands);
 	list_head_init(&ld->waitblockheight_commands);
 	list_head_init(&ld->wait_commands);
+	list_head_init(&ld->graceful_commands);
 
 	/*~ Tal also explicitly supports arrays: it stores the number of
 	 * elements, which can be accessed with tal_count() (or tal_bytelen()

diff --git a/lightningd/lightningd.h b/lightningd/lightningd.h
@@ -95,8 +95,13 @@ struct config {
 typedef STRMAP(const char *) alt_subdaemon_map;
 
 enum lightningd_state {
+	/* Starting up */
 	LD_STATE_INITIALIZING,
+	/* Normal */
 	LD_STATE_RUNNING,
+	/* Waiting for graceful shutdown */
+	LD_STATE_GRACE,
+	/* Shutting down */
 	LD_STATE_SHUTDOWN,
 };
 
@@ -250,7 +255,8 @@ struct lightningd {
 	struct list_head disconnect_commands;
 	/* Outstanding wait commands */
 	struct list_head wait_commands;
-
+	/* Outstanding graceful commands */
+	struct list_head graceful_commands;
 	/* Outstanding splice commands. */
 	struct list_head splice_commands;