Migration

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.

What happens during migration?

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 block height 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.

Automated migration

Prepare your workspace

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:

Network HTTP WebSocket

Mainnet

8000

8001

Testnet

7000

7001

  • 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.

Lisk Bridge: Automated Lisk Core 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 Application 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, Lisk Core 0.9.16 it is most likely installed in /home/lisk/lisk-main, and 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.
3 <network> can either be main for Mainnet, or test for Testnet.

Now execute the script shown below with the desired parameters:

bash lisk_bridge.sh -n <network> -h <blockheight>

Where <network> can either be main for Mainnet, or test for Testnet. The <blockheight> is the block height 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 LISK_MASTER_PASSWORD.

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 Command reference

The 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.

What if I miss the block height or if Lisk Bridge script fails?

Counting from the migration height, there are 2 full forging rounds of time available 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 the genesis block.

Migration notes Lisk Core 0.9 to 1.0

Neccessary utility scripts

The following utility scripts are run by lisk_bridge.sh as described below:

During the execution of lisk_bridge.sh, a password prompt will appear in the case whereby 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:

export LISK_MASTER_PASSWORD=XXXXXXXX

Migrate manually

To migrate a Lisk node manually, perform the following steps:

  1. Backup your data.

  2. Run the necessary utility scripts. These scripts prepare the Lisk node for the migration and are required before the upgrade script can run successfully. The utility scripts that need to be run can vary depending on the migration.

  3. Follow the default upgrade process.

Utility scripts

It is not necessary to 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 node scripts/<file_name>.

Generate config

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

The argument network is required, and this can be either the devnet, testnet, mainnet, or any other network folder available under ./config directory.

Update config

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, input_file and from_version are required. If to_version is omitted, then argument changes in config.json will be applied up to the latest version of Lisk Core. If the --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.