Lisk Core Migration
v1.0.0 is a hard fork which includes several changes. A height iss picked in order to proceed with a simultaneous global upgrade. This way the probabilities of creating forks are lower.
The recommended migration path is as follows:
The above should be enough to complete the migration. For more curious users, we've included a few more advanced sections:
- Check configuration changes
- Migrate your config file
- Enable forging (optional, just if you need to forge)
- Lisk Bridge Command Reference
Prepare your workspace
We assume that you have already installed Lisk Core and are familiar with the application. Nevertheless, we want to highlight a couple things to double-check:
- Revisit the setup steps before continuing. Supported Linux distributions are Ubuntu 14.04 LTS through and including Ubuntu 18.04 LTS.
- 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 consciously implemented to make a gapless migration. We expect it to be executed in an Ubuntu 16 environment that follows the recommended specs you can find in the readme. In summary: Node 6.14.1, PostgreSQL 9.6.8 and Redis.
Lisk Bridge : Automate Lisk Core Upgrade
We introduced the tool to perform the migration called Lisk Bridge. 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:
cd ~ rm -f lisk_bridge.sh wget https://downloads.lisk.io/lisk/test/lisk_bridge.sh bash lisk_bridge.sh -n <network> -h <blockheight>
<network> can either be
The bridge script will run and wait for the specified height of the network and upon reaching this height , will invoke installLisk.sh in order to update the code, migrate the database to the new model and update the config files
When the script arrives to your config file, 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. You can find more information in the following sections. If you want to avoid this prompt and make a full-automated migration, add the next environment variable to your system:
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
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.
What if I miss the block height or if
Lisk Bridge fails?
Go through the normal upgrade process using
installLisk.sh, either syncing from genesis or rebuilding from snapshot
It's also necessary when upgrading from 0.9 to 1.0 to specify
-c to remove old peers from the database.
Here are the key options available when upgrading:
-cto remove old peers from the database
-hto rebuild from snapshot
-0to sync from genesis.
bash installLisk.sh upgrade -c -h
Configuration changes from 0.9 to 1.0
Lisk has a variety of configurations under
config.json. Each of them are thoroughly explained in this section. Running nodes behave according to which configuration you choose in that file. Remember if you modify anything, you need to restart the node to apply it.
During the course of development we have introduced some changes in the configuration which are not backward compatible. They are strictly related to the version you are running. This section will describe each of these changes for your reference:
- Introduced new required configuration
wsPortfor P2P communication over web sockets.
db.maxfor maximum db connections.
db.minas minimum alive db connections fore more responsive db operations.
db.logFileNameto log db related stuff to a seperate file.
api.options.corsto manage CORS settings for http API. It have two options
peers.options.limitsas we moved P2P layer to web socket.
broadcast.activeas boolean value to enable/disable the broadcasting behavior.
transactions.maxTransactionsPerQueuefor better readability.
loading.verifyOnLoadingconfig option and set this behaviour as built-in.
dappconfig option. It will came up with new configuration structure for Dapps soon.
peers.list.wsPortas moving P2P to web socket port.
- Each passphrase under
forging.secretsare translated to new object structure containing
- Introduced in the new configuration
forging.defaultPassword. It is the default password for every encrypted passphrases. It is just intended for testing environments.
The latest version of Lisk Core
v1.0.0 contains a utility called
update_config.js. It enables users to automatically migrate your old configuration to the new structure. You don't need to run this script if you have run
lisk_bridge.sh before as it is automatically executed there. If you still want to use it for any other purpose, the command to run the script is:
node scripts/update_config.js <old_config_path> <new_config_path> [--password]
<old_config_path>first argument you specify absolute or relative path of the old configuration file from 0.9.x
<new_config_path>second argument you specify absolute or relative path of the new configuration file from 1.0.0
[--password]It should be used only in testing environments. It will serve as default password to encrypt the passphrases.
Using --password as the command line option is just for testing purposes. Do not use it in production environment. It will expose your password to shell history.
The same script is able to encrypt old plain passphrases following the new mechanism. This is intended for those users who have a forging delegate or a delegate who can forge in a close future.
When you run
scripts/update_config.js, it checks
forging.secret array in the old configuration file. If there are some values, it will prompt you the next message:
We found some secrets in your config, if you want to migrate, please type in your password (enter to skip):
To perform automatic passphrase migration, type-in the password of your choice. If you type a word with a minimum of 5 characters, the script will create the
forging.delegates array in the new configuration file. The same password will be used for every passphrase presented in the old config file.
Lisk Bridge Command Reference
For reference, here is the lisk_bridge.sh usage help:
Usage: 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```