Downgrade tool #8702

rustyrussell · 2025-11-20T06:49:20Z

Fairly easy, for this release. The real problem was writing the tests!

This will allow a downgrade tool to attempt to downgrade a node to the previous version. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

This will make it easier to share with the downgrade tool. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

When installed, the name is `lightning-hsmtool`. We actually copy `tools/hsmtool` to `tools/lightning-hsmtool` but that's a silly step which we should get rid of. So: 1. Make sure our documentation always refers to it as lightning-hsmtool. 2. Make sure our tests invoke it as `lightning-hsmtool`. 3. Rename the C file. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

And leave $(TOOLS) as user-visible tools. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-Added: tools: `lightningd-downgrade` can downgrade your database from v25.12 to v25.09 if something goes wrong.

In particular, document when downgrades are not possible. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

sangbida · 2025-11-24T23:59:32Z

wallet/db.c

+			       scid ? fmt_short_channel_id(tmpctx, *scid) : "no short channel id");
+	}
+
+	/* For sqlite3 needs "2021-03-12 (3.35.0)" or above */


Is there a way to enforce this requirement? Or is it an okay assumption that if they're running >25.9 version they have updated their sqlite version 🤔

It will simply fail. Won't downgrade, will give an error message. It would be nice to fix, but that is a really old sqlite...

sangbida · 2025-11-25T02:00:25Z

wallet/db.c

+	 /* Simply drop table. */
+	 "DROP TABLE network_events"},
+    {NULL, migrate_fail_pending_payments_without_htlcs,
+     /* Failing pending payments is idempotent, so no revert needed */


What happens if you downgrade and then upgrade here?

From wikipedia:
"Idempotence is the property of certain operations in mathematics and computer science whereby they can be applied multiple times without changing the result beyond the initial application."

i.e. if you run this more than once, the second time won't do anything (it will have converted them the first time).

dang I've been wikipedia-ed 😭

sangbida · 2025-11-25T02:04:38Z

wallet/db.c

 struct migration {
 	const char *sql;
 	void (*func)(struct lightningd *ld, struct db *db);
+	const char *revertsql;


Not exactly sure where to add this (or if this comment is to premature I've only looked at this commit so far) but I'm guessing we also need a way to clean up the datastore between v25.09 and v25.12?

Excellent point. This is true, if a plugin changed its datastore format, it would need to do this.

I looked through, and indeed, node bias support in v25.12 for askrene. If this is used, the plugin will error out on downgrade! Will add fix and test...

sangbida · 2025-11-25T02:07:59Z

wallet/migrations.h

+void fillin_missing_lease_satoshi(struct lightningd *ld,
+				  struct db *db);
+void fillin_missing_lease_satoshi(struct lightningd *ld,


This was there in the deleted code in db.c as well but there's a duplication here.

sangbida · 2025-11-25T02:08:37Z

wallet/migrations.h

+void migrate_remove_chain_moves_duplicates(struct lightningd *ld, struct db *db);
+void migrate_from_account_db(struct lightningd *ld, struct db *db);
+void migrate_remove_chain_moves_duplicates(struct lightningd *ld, struct db *db);


There's a duplication here as well.

sangbida · 2025-11-25T02:13:24Z

wallet/migrations.h

+
+const struct db_migration *get_db_migrations(size_t *num);
+
+/* All the functions provided by wallet.c */


This comment might need to be changed to migrations.c

sangbida · 2025-11-25T02:21:32Z

Makefile

 # Any mention of BOLT# must be followed by an exact quote, modulo whitespace.
-bolt-check/%: % bolt-precheck tools/check-bolt
-	@if [ -d .tmp.lightningrfc ]; then tools/check-bolt $(CHECK_BOLT_PREFIX) .tmp.lightningrfc $<; else echo "Not checking BOLTs: BOLTDIR $(BOLTDIR) does not exist" >&2; fi
+bolt-check/%: % bolt-precheck devtools/check-bolt


This commit looks good, but why are we doing this?

devtools are for tools run by developers only.

sangbida · 2025-11-25T02:27:21Z

tools/Makefile

 tools/headerversions.o: ccan/config.h
-tools/lightning-hsmtool: tools/lightning-hsmtool.o libcommon.a
+tools/lightning-hsmtool: tools/lightning-hsmtool.o
+tools/lightning-downgrade.o: CFLAGS:=$(CFLAGS) -DCLN_PREV_VERSION=$(CLN_PREV_VERSION)


Does this work okay without quotes?

sangbida · 2025-11-25T02:38:43Z

tools/Makefile

+	tools/lightning-downgrade.o		\
+	wallet/migrations.o			\
+	$(DB_OBJS)				\
+	$(WALLET_DB_QUERIES:.c=.o)		\
+	tools/lightning-downgrade.o


This is duplicated

sangbida · 2025-11-25T02:44:20Z

Makefile

 $(info Building version $(VERSION))

 # Next release.
 CLN_NEXT_VERSION := v25.12


Is this something manually updated or updated by one of the build scripts? I'm guessing it's okay for the previous release version to always stay as 25.09 because we will always try to make our releases downgradable from here on out?

sangbida · 2025-11-25T02:49:12Z

doc/lightning-downgrade.8.md

+--------
+
+```bash
+lightning-downgrade method [ARGUMENTS]...


What is method? It doesn't seem like the main function accepts any arguments?

sangbida · 2025-11-25T02:59:33Z

tools/lightning-downgrade.c

+static const struct db_version db_versions[] = {
+	{ "v25.09", 276, false },
+	/* When we implement v25.12 downgrade: { "v25.12", 280, ???}, */
+};


Do we need to add a warning in the docs to indicate that the gossip store is deleted? Also, when we have a new release we will have to manually update the release version and the migration version, is that okay to do? Should we add a point in the release checklist to do so?

wallet: add optional sql and functions to downgrade db.

8f9cdeb

This will allow a downgrade tool to attempt to downgrade a node to the previous version. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

rustyrussell added this to the v25.12 milestone Nov 20, 2025

rustyrussell force-pushed the guilt/downgrade-tool branch 3 times, most recently from 06f7a80 to d4efc16 Compare November 21, 2025 01:54

rustyrussell requested a review from cdecker as a code owner November 21, 2025 01:54

rustyrussell added 3 commits November 21, 2025 14:51

wallet: separate migration table into its own source file.

6421931

This will make it easier to share with the downgrade tool. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

check-bolt: move to devtools, clean up tools/

3c89231

And leave $(TOOLS) as user-visible tools. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

rustyrussell force-pushed the guilt/downgrade-tool branch 3 times, most recently from 5f6d819 to 04e2c73 Compare November 22, 2025 01:49

rustyrussell added 3 commits November 22, 2025 14:45

tools/lightning-downgrade: tool to downgrade (offline) v25.12 to v25.09.

d74d89d

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-Added: tools: `lightningd-downgrade` can downgrade your database from v25.12 to v25.09 if something goes wrong.

doc: add a manual page.

dd7e460

In particular, document when downgrades are not possible. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

CI: add test that we can downgrade the node and run it under v25.09.

b4be1b1

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

rustyrussell force-pushed the guilt/downgrade-tool branch from 04e2c73 to b4be1b1 Compare November 22, 2025 04:15

sangbida reviewed Nov 24, 2025

View reviewed changes

sangbida reviewed Nov 25, 2025

View reviewed changes


		const struct db_migration get_db_migrations(size_t num);

		/* All the functions provided by wallet.c */

Downgrade tool #8702

Are you sure you want to change the base?

Downgrade tool #8702

Uh oh!

Conversation

rustyrussell commented Nov 20, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sangbida Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sangbida Nov 25, 2025 •

edited

Loading