Upgrade to 12.4.15
Getting started12.4.15+

Upgrade to 12.4.15

Move a node from an earlier version to lotusd 12.4.15: what to back up, the steps for binaries and Docker, and what each 12.4.x release changes.

An upgrade replaces the binaries and keeps the data directory. The 12.4.x release notes ask for no reindex and no manual migration: the node updates its own databases at the first start.

12.4.16+

12.4.16 changes no consensus rule: it validates, relays and mines exactly like 12.4.15, and the Napoleon activation time is the same. It adds the asynchronous explorer indexer (-asyncindex, on by default; -asyncindex=0 keeps the 12.4.15 path with the same database contents), batch transaction submission, light block templates, Taproot addresses in the wallets, the miners and the pool, and one GPU miner for NVIDIA and AMD.

Napoleon upgrade

Every node must run 12.4.13 or later before 21 December 2026, 20:50:00 UTC. 12.4.15 has the same consensus rules as 12.4.13 and 12.4.14. See Napoleon.

Before you start #

Check the version you run now:

Shell
curl -s http://127.0.0.1:10604/api/v1/node

Read subversion, for example /lotusd:12.4.13(EB32.0)/.

Back up the node's wallets, if it has any. For each loaded wallet:

Shell
lotus-cli listwallets
lotus-cli -rpcwallet=<name> backupwallet /path/to/backup/<name>.bak

backupwallet copies the wallet file safely while the node runs. Wallet files are in wallets/ under the data directory when that directory exists, otherwise in the data directory itself. A wallet created by this version is a wallet.sqlite file; older ones are wallet.dat.

The browser wallet at /wallet/ is not in the node: its keys are in your browser, and its backup is the 12-word recovery phrase. See Wallets.

Upgrade the binaries #

  1. Download and verify 12.4.15 as in Install a node.
  2. Stop the node and wait until the process has exited:
Shell
lotus-cli stop
  1. Replace lotusd, lotus-cli and the other tools with the new files.
  2. Start the node with the same options and the same data directory:
Shell
lotusd -daemon

Upgrade with Docker #

Pull the new tag, stop the container with enough time to shut down, and start a new one on the same volume:

Shell
docker pull ghcr.io/lotusdevorg/lotusd:12.4.15
docker stop -t 120 lotusd
docker rm lotusd
docker run -d --name lotusd \
  -v lotus-data:/root/.lotus \
  -p 10605:10605 \
  ghcr.io/lotusdevorg/lotusd:12.4.15

Add the options your container had before. With Compose, change the image tag, then docker compose stop -t 120 and docker compose up -d. See Docker.

Check the result #

Shell
lotusd -version
lotus-cli getnetworkinfo
curl -s http://127.0.0.1:10604/api/v1/health
  • lotusd -version prints the version of the binary on disk.
  • getnetworkinfo and /api/v1/health describe the running node: subversion must be /lotusd:12.4.15(EB32.0)/ and version in the health answer 12041500.
  • /api/v1/upgrades must list napoleon with activation_time 1797886200.

What changes on the way to 12.4.15 #

Read the notes of every release between yours and 12.4.15. The points that need attention:

Coming fromWhat happens or what to do
12.4.11 or olderThe first start of 12.4.13 or later walks the coin set once to build its hash. It takes minutes on mainnet; the log shows UTXO hash: computing ....
12.4.10 or older, pool nodesPool protocol 3 arrived in 12.4.11. Pool nodes of 12.4.10 and of 12.4.11 or later refuse each other: stop every -poolpayouts node, upgrade them all, start them.
Any version, pool nodesEvery node of a pool must run 12.4.13 or later before 15 January 2027, 08:00 UTC (median time past 1800000000), when two pool rules start.
12.4.13 or 12.4.14 release binariescreatewallet and loadwallet of an SQLite wallet failed, and a node started with -wallet=<sqlite wallet> refused to start. Fixed in 12.4.15.
12.4.13The explorer database gets a schema version with forward-only migrations in 12.4.14. Version 2 adds a tip marker without rewriting a table; nothing to do.
12.4.14 with -thin=1Upgrade the proof servers to 12.4.15 before the thin node.

Two options were renamed in 12.4.13. The old names are deprecated aliases; switch to the new ones:

Old nameNew name
-secondkingsactivationtime-napoleonactivationtime
-coinbasetagaftersecondkings-coinbasetagafternapoleon

If you turn the explorer index back on (-explorerindex=1) on a data directory that ran with -explorerindex=0, the node needs -reindex.

Going back #

The 12.4.13 release notes state that, before the Napoleon activation, a 12.4.13 node can be rolled back to 12.4.11: stop it cleanly, put the old binaries or image back, start it. What 12.4.13 adds to the databases is ignored by 12.4.11.

The notes of 12.4.14 and 12.4.15 describe no rollback, and 12.4.14 made the explorer database migrations forward-only. Going back to an older version is not always possible once a newer one has written to the data directory.

After the activation, a rolled-back node leaves the chain at the first block that uses a new rule. Do not go below 12.4.13.

Source share/www/docs/upgrade.md in the lotusd repository
Checked against doc/release-notes/release-notes-12.4.11.md doc/release-notes/release-notes-12.4.13.md doc/release-notes/release-notes-12.4.14.md doc/release-notes/release-notes-12.4.15.md src/wallet/init.cpp src/wallet/rpcwallet.cpp src/napoleonargs.h