Lisk Core Migration
The migration is a special case of upgrading your Lisk Core node. A migration is needed if the new version of the software is not compatible with older Lisk Core versions.
As a consequence, the majority of the network needs to do this software update simultaneously to stabilize the forked chain and as a result, make it grow faster as the outdated version of the chain.
To achieve this, a height is picked to proceed with a simultaneous global upgrade. When the blockheight of the network reaches the predefined height, it will invoke the update on all nodes in the network at the same time. This way the probabilities of creating forks are lower.
Besides the normal update script, the Lisk Bridge script might include additional scripts. E.g. if the new update includes changes in the structure of the configuration file, the script would try to reorganize your existing config to the new structure and then run the normal update script afterward. If you don’t want to use the automated script, you can read a detailed explanatio of how to migrate manually below.
The following section describes how to use the automated migration script for binary distributions of Lisk Core, to make your migration as seamless as possible. Additionally, you can find information below on how to perform the migration process manually.
We assume that you have already installed Lisk Core and are familiar with the application. Nevertheless, we want to highlight a couple of things to double-check:
Revisit the setup steps before continuing.
Verify that the following ports are open, depending on the network:
Make a backup of
config.json. While this process does make a backup automatically in a
backup/directory, it’s recommended to make one yourself as you can never be too careful. At the end of this tutorial, we include some advanced cases to guide you.
The next section introduces a tool we have implemented to make a gapless migration.
We introduced a tool to perform the migration called Lisk Bridge, available at downloads.lisk.io. Here are the direct download links depending on the network your node is connected to:
It’s a wrapper script that invokes
installLisk.sh upgrade at a specific block height - and thus is intended for users using the Binary installation.
To upgrade your node on a specific network height, you should download
lisk_bridge.sh to where you would normally download and run installLisk.sh.
In other words, it should be 1 directory up from where the lisk application is stored.
For example, if you’re currently running
Lisk Core 0.9.16 as a user called
Lisk Core 0.9.16 is most likely installed in
installLisk.sh is stored in
/home/lisk, the lisk user’s home directory.
As the lisk user then, you could run the following:
su - lisk (1) rm -f lisk_bridge.sh (2) wget https://downloads.lisk.io/lisk/<network>/lisk_bridge.sh (3)
|1||change to lisk user|
|2||remove old versions of lisk_bridge.sh|
Then run the script with the desired parameters:
bash lisk_bridge.sh -n <network> -h <blockheight>
<network> can either be
main for Mainnet or
test for Testnet.
<blockheight> is the before announced blockheight, when the hard fork is going to happen.
The bridge script will run and wait for the specified height of the network and upon reaching this height, will invoke
installLisk.sh to update the code, migrate the database to the new model and update the config files.
If you’re doing a fully automated migration, you could run
lisk_bridge.sh inside of tmux, screen, byobu or another terminal multiplexer and detach your session even days ahead of time, though you’d want to minimize this lead time if you’re exporting
Important note for delegates: After automated upgrade, you still need to enable forging again manually, like described in configuration section.
We have prepared a small clip showing the expected output from the script execution. You can watch it to verify your migration was completed as expected:
For reference, here is the lisk_bridge.sh usage help:
Usage: bash lisk_bridge.sh <-h <BLOCKHEIGHT>> [-s <DIRECTORY>] [-n <NETWORK>] -h <BLOCKHEIGHT> -- specify blockheight at which bridging will be initiated -f <TARBALL> -- specify path to local tarball containing the target release -s <DIRECTORY> -- Lisk home directory -n <NETWORK> -- choose main or test Example: bash lisk_bridge.sh -h 50000000 -n test -s /home/lisk/lisk-test Set the LISK_MASTER_PASSWORD environment variable if you want to do secrets migration in non-interactive mode
Don’t panic! Counting from the migration height, you have 2 full forging rounds time to upgrade your node manually by following the steps described in Migrate manually. If 2 full forging rounds have already passed since migration, your Node will be probably on a fork after the upgrade. To resolve this, rebuild your version of the blockchain from snaphot or from genesis block.
The following utility scripts are run by
update_config.js: migrates config to new structure
During the execution of
lisk_bridge.sh, it will prompt you asking for a password in the case where it finds a passphrase.
It will encrypt and migrate that passphrase to the new format.
If you want to avoid this prompt and make a full-automated migration, add the next environment variable to your system:
To migrate a Lisk node manually, do the following steps:
You don’t need to run these script if you have run
lisk_bridge.sh before as it is automatically executed there.
There are a couple of command line scripts that facilitate users of lisk to perform handy operations.
All scripts are located under
./scripts/ directory and can be executed directly by
This script will help you to generate a unified version of the configuration file for any network. Here is the usage of the script:
Usage: node scripts/generate_config.js [options] Options: -h, --help output usage information -V, --version output the version number -c, --config [config] custom config file -n, --network [network] specify the network or use LISK_NETWORK
network is required and can by
mainnet or any other network folder available under
This script keeps track of all changes introduced in Lisk over time in different versions. If you have one config file in any of specific version and you want to make it compatible with other versions of the Lisk, this scripts will do it for you.
Usage: node scripts/update_config.js [options] <input_file> <from_version> [to_version] Options: -h, --help output usage information -V, --version output the version number -n, --network [network] specify the network or use LISK_NETWORK -o, --output [output] output file path
As you can see from the usage guide,
from_version are required.
If you skip
to_version argument changes in config.json will be applied up to the latest version of Lisk Core.
If you do not specify
--output path the final config.json will be printed to stdout.
If you do not specify
--network argument you will have to load it from
LISK_NETWORK env variable.