For the best viewing experience, please turn your phone to portrait mode.

Lisk Core Migration

Lisk Core v1.0.0 is a hard fork which includes several changes. A height was picked in order to proceed with a simultaneous global upgrade. This way the probabilities of creating forks are lower.

The flow to properly migrate consists of four main steps:

Configuration changes from 0.9 to 1.0

Lisk has a variety of configurations under config.json each of them are very thoroughly explained in this section. Running nodes behave according to which configuration you choose in that file.

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:

  • Renamed port config to httpPort.
  • Introduced new required configuration wsPort for P2P communication over web sockets.
  • Renamed db.poolSize to db.max for maximum db connections.
  • Introduced db.min as minimum alive db connections fore more responsive db operations.
  • Introduced db.logFileName to log db related stuff to a seperate file.
  • Introduced api.options.cors to manage CORS settings for http API. It have two options origin and methods to configure.
  • Removed peers.options.limits as we moved P2P layer to web socket.
  • Introduced broadcast.active as boolean value to enable/disable the broadcasting behavior.
  • Renamed transactions.maxTxsPerQueue to transactions.maxTransactionsPerQueue for better readability.
  • Removed loading.verifyOnLoading config option and set this behavior as built-in.
  • Removed dapp config option. It will came up with new configuration structure for Dapps soon.
  • Renamed peers.list[].port to peers.list[].wsPort as moving P2P to web socket port.
  • Renamed forging.secret to forging.delegates.
  • Each passphrase under forging.secrets are translated to new object structure containing encryptedPassphrase and publicKey.
  • Introduced in the new configuration forging.defaultPassword. It is the default password for every encrypted passphrases. It is just intended for testing environments.

Migrate configuration

The latest version of Lisk Core contains update_config.js file. It enables users to automatically migrate your old configuration to the new structure. 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.
Warning

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.

Migrate Passphrases

Automatically (Not safe)

When you run scripts/update_config.js, it will check 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 want to skip this step just press enter.
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. In addtion, a forging.defaultPassword parameter will be included in the config file. It shows the password in plaintext as highlighted below:

"defaultPassword": "sdkfjklsadjfgklsjdklgjsdkl"

Using the same password for all the passphrases and exposing your password in plaintext are two reasons to bear in mind if you aim the best security standards. For that, we recommend to migrate your passphrases with Lisk-Commander.

You can also migrate your passphrases manually one by one. This way for example you will be able to encrypt every passphrase with a different password. In order to do this, first install Lisk Commander. Upon completion, please follow the commands below to generate the encryptedPassphrase:

$ lisk
lisk> encrypt passphrase
Please enter your secret passphrase: *****
Please re-enter your secret passphrase: *****
Please enter your password: ***
Please re-enter your password: ***
╔═════════════════════╤════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ encryptedPassphrase │ salt=5426da113a5896f11255f69bb49c49eb&cipherText=947b537de9&iv=67d7344ce8a3b2fc879e316a&tag=dc5db5bfb41a3e968278e99651c68523&version=1 ║
╚═════════════════════╧════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
  1. In the first step, type in your passphrase and then type in the password you want to use for encryption.
  2. Afterwards you will get an encryptedPassphrase key value pair.
  3. Now create a JSON object like below:
    {
    "encryptedPassphrase": "salt=5426da113a5896f11255f69bb49c49eb&cipherText=947b537de9&iv=67d7344ce8a3b2fc879e316a&tag=dc5db5bfb41a3e968278e99651c68523&version=1",
    "publicKey": "123a8aac752b37c676b0d46a798f7625e37efa1e96091983274e04ab7aae2"
    }
  4. Add this JSON object to your config.json under forging.delegates.

Automate Lisk Core Upgrade

We've prepared a tool named Lisk Bridge. This script is intended for users used to binaries installation or more advanced users installing from source. To upgrade your node on a specific network height, you can use the following script:

rm -f lisk_bridge.sh
wget https://downloads.lisk.io/lisk/test/lisk_bridge.sh
bash lisk_bridge.sh -n <network> -h <height>

Where <network> can either be main or test and <height> can be any of your preferred height to upgrade.

The bridge script will run and wait for the particular height of the network and then internally run the commands given below to upgrade. So lisk_bridge.sh is just a wrapper on top of installLisk.sh upgrade in order to perform the upgrade on a particular height. If you decide to use lisk_bridge.sh you do not need to run installLisk.sh upgrade later as it will be done automatically by the bridge script.

How to migrate if I miss the block height or if Lisk Bridge fails?

Go through the normal upgrade process using installLisk.sh. Specify the next parameters depending what you intend:

  • -c to remove old peers from the database
  • -h to rebuild from snapshot
  • -0 to sync from genesis.

Example:

bash installLisk.sh upgrade -c -h