Lisk Core Migration

Migration of a Lisk Node is only necessary during a hard fork.
For normal software updates that don't invoke a hard fork, please perform a normal upgrade, see Upgrade vs Migration.

What happens during 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 explanation 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.

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.

Lisk Bridge: Automated Lisk Core 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, Lisk Core 0.9.16 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 then, you could run the following:

Where <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 LISK_MASTER_PASSWORD.

Important note for delegates: After automated upgrade, you still need to enable forging again manually, like described in configuration section

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

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.

Migration Notes Lisk Core 0.9 to 1.0

Neccessary utility scripts

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:

export LISK_MASTER_PASSWORD=XXXXXXXX

Migrate manually

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

Backup your data.

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.

Argument network is required and can by 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.
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.

As you can see from the usage guide, input_file andfrom_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.

What's next?

When accessing our website, we obtain and process your personal data. We also use cookies to improve your experience on our site. To find out more about our use of your data, read our updated privacy policy To continue using our website, click „I accept“.