Migration of a Lisk Node is only necessary during a hard fork. For normal software updates that do not invoke a hard fork, please perform a normal upgrade. Please see Upgrade vs Migration for further details.
The migration is a special case of upgrading your Lisk Core node. A migration is required 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 perform 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 may include additional scripts.
For example, 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 afterwards. To perform the migration manually instead of using the automated script, a detailed explanation of how to migrate manually is covered later in this section.
The following section describes how to use the automated migration script for binary distributions of Lisk Core, in order to ensure the migration is performed as seamlessly as possible, and also covers the manual migration process.
At this point it is assumed that Lisk Core has now already been installed and the user is familiar with the application. Nevertheless, it is recommended to double check the 2 points listed below:
Revisit the setup steps before continuing.
Verify that the following ports are open depending on the network in use:
Make a backup of
config.json. While this process does make a backup automatically in a
backup/directory, it is recommended to additionally perform another back up just to be on the safe side. At the end of this tutorial, some advanced cases are shown to assist and further guide the user in the right direction.
The next section introduces a tool specifically designed in order to perform a gap-less migration.
This migration tool is called Lisk Bridge, and can be found here: downloads.lisk.io. The direct download links depending on the specific network your node is using, are displayed below:
The wrapper script that invokes
installLisk.sh upgrade at a specific block height is intended for users using the Binary installation.
To upgrade your node on a specific network height, please download
lisk_bridge.sh to the same directory where
installLisk.sh would be downloaded and run from.
In other words, it should be one directory above where the lisk application is stored.
For example, in the case whereby
Lisk Core 0.9.16 is currently running as a user called
Lisk Core 0.9.16 it is most likely installed in
installLisk.sh is stored in
/home/lisk, the lisk user’s home directory.
As the lisk user it should then be possible to execute the following commands:
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 execute the script shown below 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 blockheight announced previously when the hard fork is going to occur.
The bridge script will run and wait for the specified height of the network.
Upon reaching the specified height it will invoke
installLisk.sh in order to update the code, migrate the database to the new model, and update the config files.
If a fully automated migration is being performed it will be possible to run
lisk_bridge.sh inside of tmux, screen, byobu, or another terminal multiplexer and detach your session days ahead of time if required.
However, it is recommended to minimize this lead time when exporting the
Important note for delegates: After an automated upgrade is performed, it will still be necessary to manually enable forging again, as described in the configuration section.
A short video clip showing the expected output from the script execution can be viewed below, which will assist the user in ensuring the migration was completed successfully:
lisk_bridge.sh usage help menu can be seen below:
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 a secret migration in non-interactive mode is required.
Counting from the migration height, there are 2 full forging rounds of time avaialble 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 probably be on a fork after the upgrade. In order 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, a password prompt will occur in the case where it finds a passphrase.
It will encrypt and migrate that passphrase to the new format.
In order to to avoid this prompt and perform a fully automated migration, add the next environment variable to your system as shown below:
To migrate a Lisk node manually, perform the following steps:
It is not necessary run these scripts if
lisk_bridge.sh has previously been executed as it will have already been performed automatically.
There are 2 useful command line scripts described below that will further assist the user.
All scripts are located under the
./scripts/ directory and can be executed directly by
This script will assist the user in generating a unified version of the configuration file for any network, and the usage of this script can be seen below:
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 this can be either the
mainnet or any other network folder available under
This script keeps track of all changes introduced in Lisk over time in different versions. In the case whereby one config file exists (regardless of which version), it is possible to make this compatible with other versions of Lisk by running the following script:
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 can be seen from the usage guide,
from_version are required.
to_version is omitted, then argument changes in config.json will be applied up to the latest version of Lisk Core.
--output path is not specified, the final config.json will be printed to stdout.
Finally, if the
--network argument is not specified, it will have to be loaded from
LISK_NETWORK env variable.