Merge pull request #189 from LiskHQ/188-output-commands-to-execute-po…

…st-migration

Output commands to execute post migration

.eslintrc.js

@@ -16,8 +16,9 @@ module.exports = {
  rules: {
  'max-len': 'off', // Managed by prettier
  'no-underscore-dangle': 'off', // Used for private variables and methods
- 'implicit-arrow-linebreak': 'off', // Prefered
+ 'implicit-arrow-linebreak': 'off', // Preferred
  'no-mixed-spaces-and-tabs': 'off', // Managed by prettier
+ 'no-shadow': 'off',
  'operator-linebreak': 'off',
  'import/prefer-default-export': 'off',
  'lines-between-class-members': 'off', // Off because typescript has members and methods
@@ -31,6 +32,7 @@ module.exports = {
  '@typescript-eslint/no-unnecessary-boolean-literal-compare': ['error'],
  '@typescript-eslint/no-unnecessary-qualifier': ['error'],
  '@typescript-eslint/no-unnecessary-type-arguments': ['error'],
+ '@typescript-eslint/no-shadow': 'warn',
  '@typescript-eslint/prefer-for-of': ['error'],
  '@typescript-eslint/prefer-function-type': ['error'],
  '@typescript-eslint/prefer-includes': ['error'],

docs/migration.md

@@ -1,11 +1,12 @@
 # Migration Guide
 
-This section explains how to migrate a Lisk Core v3.0.4 (or later) node to Lisk Core v4.x using the Lisk Migrator.
+This section explains how to migrate a Lisk Core v3.1.0 node to Lisk Core v4.0.0 using the Lisk Migrator.
 
-The Lisk Migrator CLI tool will generate a new genesis (snapshot) block for Lisk Core v4.x.
-The new genesis block is created based on a snapshot of the existing blockchain (running on Lisk Core v3.0.4+) at a pre-determined height.
+The Lisk Migrator CLI tool will generate a new genesis (snapshot) block for Lisk Core v4.0.0.
+The new genesis block is created based on a snapshot of the existing blockchain (running on Lisk Core v3.1.0) at a pre-determined height.
 
-Lisk Migrator automatically exports the node's Forging Status information to the file named `forgingStatus.json` under the output directory. In case, Lisk Migrator is unable to save to the disk, as a fallback, the Forging Status information is logged to the standard output.
+Lisk Migrator automatically exports the node's Forging Status information to the file named `forgingStatus.json` under the output directory.
+In case, the Lisk Migrator is unable to save to the disk, as a fallback, the Forging Status information is logged to the standard output.
 
 <!--
 
@@ -67,7 +68,7 @@ export PATH="$PATH:$HOME/lisk-migrator/bin"
 **Check the announced snapshot height**
 
 - For Mainnet: `TBD`
-- For Testnet: `TBD`
+- For Testnet: `20449414`
 
 ### Run Lisk Migrator
 

src/constants.ts

@@ -11,6 +11,8 @@
  *
  * Removal or modification of this copyright notice is prohibited.
  */
+import { homedir } from 'os';
+
 import { utils } from '@liskhq/lisk-cryptography';
 
 import { NetworkConfigLocal } from './types';
@@ -93,3 +95,20 @@ export const LEGACY_DB_PATH = `${DEFAULT_LISK_CORE_PATH}/${DEFAULT_DATA_DIR}/leg
 
 export const DEFAULT_VERSION = '0.1.0';
 export const EVENT_NEW_BLOCK = 'app:block:new';
+
+export const FILE_NAME = {
+ COMMANDS_TO_EXEC: 'commandsToExecute.txt',
+ FORGING_STATUS: 'forgingStatus.json',
+ KEYS: 'keys.json',
+};
+
+export const enum ERROR_CODE {
+ DEFAULT = 0,
+ INVALID_CONFIG = 1,
+ GENESIS_BLOCK_CREATE = 2,
+ LISK_CORE_START = 3,
+ BACKUP_LEGACY_DATA_DIR = 4,
+ COPY_LEGACY_DB = 5,
+}
+
+export const LISK_V3_BACKUP_DATA_DIR = `${homedir()}/.lisk/lisk-core-v3`;

src/events.ts

@@ -17,7 +17,7 @@ import { Block } from '@liskhq/lisk-chain';
 import { address } from '@liskhq/lisk-cryptography';
 import { APIClient } from '@liskhq/lisk-api-client';
 import { write } from './utils/fs';
-import { EVENT_NEW_BLOCK } from './constants';
+import { EVENT_NEW_BLOCK, FILE_NAME } from './constants';
 import { ForgingStatus } from './types';
 
 const { getLisk32AddressFromAddress } = address;
@@ -41,7 +41,7 @@ export const captureForgingStatusAtSnapshotHeight = (
 
  if (finalForgingStatuses.length) {
  try {
- const forgingStatusJsonFilepath = resolve(outputDir, 'forgingStatus.json');
+ const forgingStatusJsonFilepath = resolve(outputDir, FILE_NAME.FORGING_STATUS);
  await write(forgingStatusJsonFilepath, JSON.stringify(finalForgingStatuses, null, '\t'));
  _this.log(`\nFinished exporting forging status to ${forgingStatusJsonFilepath}.`);
  } catch (error) {

src/index.ts

@@ -26,6 +26,10 @@ import {
  SNAPSHOT_DIR,
  MIN_SUPPORTED_LISK_CORE_VERSION,
  DEFAULT_LISK_CORE_PATH,
+ ERROR_CODE,
+ FILE_NAME,
+ LISK_V3_BACKUP_DATA_DIR,
+ LEGACY_DB_PATH,
 } from './constants';
 import { getAPIClient } from './client';
 import {
@@ -46,14 +50,22 @@ import { captureForgingStatusAtSnapshotHeight } from './events';
 import {
  copyGenesisBlock,
  createGenesisBlock,
+ getGenesisBlockCreateCommand,
  writeGenesisAssets,
  writeGenesisBlock,
 } from './utils/genesis_block';
 import { CreateAsset } from './createAsset';
 import { ApplicationConfigV3, NetworkConfigLocal, NodeInfo } from './types';
-import { installLiskCore, startLiskCore, isLiskCoreV3Running } from './utils/node';
+import {
+ installLiskCore,
+ startLiskCore,
+ isLiskCoreV3Running,
+ getLiskCoreStartCommand,
+} from './utils/node';
 import { resolveAbsolutePath, verifyOutputPath } from './utils/path';
 import { execAsync } from './utils/process';
+import { MigratorException } from './utils/exception';
+import { writeCommandsToExec } from './utils/commands';
 
 let configCoreV4: PartialApplicationConfig;
 class LiskMigrator extends Command {
@@ -110,48 +122,49 @@ class LiskMigrator extends Command {
  };
 
  public async run(): Promise<void> {
- try {
- const { flags } = this.parse(LiskMigrator);
- const liskCoreV3DataPath = resolveAbsolutePath(
- flags['lisk-core-v3-data-path'] ?? DEFAULT_LISK_CORE_PATH,
+ const { flags } = this.parse(LiskMigrator);
+ const liskCoreV3DataPath = resolveAbsolutePath(
+ flags['lisk-core-v3-data-path'] ?? DEFAULT_LISK_CORE_PATH,
+ );
+ const outputPath = flags.output ?? join(__dirname, '..', 'output');
+ const snapshotHeight = flags['snapshot-height'];
+ const customConfigPath = flags.config;
+ const autoMigrateUserConfig = flags['auto-migrate-config'] ?? false;
+ const autoStartLiskCoreV4 = flags['auto-start-lisk-core-v4'];
+ const pageSize = Number(flags['page-size']);
+
+ verifyOutputPath(outputPath);
+
+ const client = await getAPIClient(liskCoreV3DataPath);
+ const nodeInfo = (await client.node.getNodeInfo()) as NodeInfo;
+ const { version: appVersion, networkIdentifier } = nodeInfo;
+
+ cli.action.start('Verifying if backup height from node config matches snapshot height');
+ if (snapshotHeight !== nodeInfo.backup.height) {
+ this.error(
+ `Lisk Core v3 backup height (${nodeInfo.backup.height}) does not match the expected snapshot height (${snapshotHeight}).`,
  );
- const outputPath = flags.output ?? join(__dirname, '..', 'output');
- const snapshotHeight = flags['snapshot-height'];
- const customConfigPath = flags.config;
- const autoMigrateUserConfig = flags['auto-migrate-config'] ?? false;
- const autoStartLiskCoreV4 = flags['auto-start-lisk-core-v4'];
- const pageSize = Number(flags['page-size']);
-
- verifyOutputPath(outputPath);
-
- const client = await getAPIClient(liskCoreV3DataPath);
- const nodeInfo = (await client.node.getNodeInfo()) as NodeInfo;
- const { version: appVersion, networkIdentifier } = nodeInfo;
-
- cli.action.start('Verifying if backup height from node config matches snapshot height');
- if (snapshotHeight !== nodeInfo.backup.height) {
- this.error(
- `Lisk Core v3 backup height (${nodeInfo.backup.height}) does not match the expected snapshot height (${snapshotHeight}).`,
- );
- }
- cli.action.stop('Snapshot height matches backup height');
-
- cli.action.start(
- `Verifying snapshot height to be multiples of round length i.e ${ROUND_LENGTH}`,
+ }
+ cli.action.stop('Snapshot height matches backup height');
+
+ cli.action.start(
+ `Verifying snapshot height to be multiples of round length i.e ${ROUND_LENGTH}`,
+ );
+ if (snapshotHeight % ROUND_LENGTH !== 0) {
+ this.error(
+ `Invalid snapshot height provided: ${snapshotHeight}. It must be an exact multiple of round length (${ROUND_LENGTH}).`,
  );
- if (snapshotHeight % ROUND_LENGTH !== 0) {
- this.error(
- `Invalid snapshot height provided: ${snapshotHeight}. It must be an exact multiple of round length (${ROUND_LENGTH}).`,
- );
- }
- cli.action.stop('Snapshot height is valid');
+ }
+ cli.action.stop('Snapshot height is valid');
 
-  const networkConstant = NETWORK_CONSTANT[networkIdentifier] as NetworkConfigLocal;
-  const outputDir = flags.output ? outputPath : `${outputPath}/${networkIdentifier}`;
+ const networkConstant = NETWORK_CONSTANT[networkIdentifier] as NetworkConfigLocal;
+ const outputDir = flags.output ? outputPath : `${outputPath}/${networkIdentifier}`;
 
- // Ensure the output directory is present
- if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
+ // Ensure the output directory is present
+ if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
+ const filePathCommandsToExec = `${outputDir}/${FILE_NAME.COMMANDS_TO_EXEC}`;
 
+ try {
  // Asynchronously capture the node's Forging Status information at the snapshot height
  // This information is necessary for the node operators to enable generator post-migration without getting PoM'd
  captureForgingStatusAtSnapshotHeight(this, client, snapshotHeight, outputDir);
@@ -235,7 +248,12 @@ class LiskMigrator extends Command {
  const isValidConfig = await validateConfig(migratedConfigV4);
  cli.action.stop();
 
- if (!isValidConfig) throw new Error('Migrated user configuration is invalid.');
+ if (!isValidConfig) {
+ throw new MigratorException(
+ 'Migrated user configuration is invalid.',
+ ERROR_CODE.INVALID_CONFIG,
+ );
+ }
 
  cli.action.start(`Exporting user configuration to the path: ${outputDir}`);
  await writeConfig(migratedConfigV4, outputDir);
@@ -306,13 +324,13 @@ class LiskMigrator extends Command {
  "Lisk Core v3 still running. Please stop the node, type 'yes' to proceed and 'no' to exit. [yes/no]",
  );
  if (!isStopReconfirmed) {
- this.error(
+ throw new Error(
  `Cannot proceed with Lisk Core v4 auto-start. Please continue manually. In order to access legacy blockchain information posts-migration, please copy the contents of the ${snapshotDirPath} directory to 'data/legacy.db' under the Lisk Core v4 data directory (e.g: ${DEFAULT_LISK_CORE_PATH}/data/legacy.db/). Exiting!!!`,
  );
  } else if (numTriesLeft === 0 && isStopReconfirmed) {
  const isCoreV3StillRunning = await isLiskCoreV3Running(liskCoreV3DataPath);
  if (isCoreV3StillRunning) {
- this.error(
+ throw new Error(
  `Cannot auto-start Lisk Core v4 as Lisk Core v3 is still running. Please continue manually. In order to access legacy blockchain information posts-migration, please copy the contents of the ${snapshotDirPath} directory to 'data/legacy.db' under the Lisk Core v4 data directory (e.g: ${DEFAULT_LISK_CORE_PATH}/data/legacy.db/). Exiting!!!`,
  );
  }
@@ -339,13 +357,16 @@ class LiskMigrator extends Command {
  );
  }
  } else {
- this.error(
+ throw new Error(
  `User did not confirm Lisk Core v3 node shutdown. Skipping the Lisk Core v4 auto-start process. Please continue manually. In order to access legacy blockchain information posts-migration, please copy the contents of the ${snapshotDirPath} directory to 'data/legacy.db' under the Lisk Core v4 data directory (e.g: ${DEFAULT_LISK_CORE_PATH}/data/legacy.db/). Exiting!!!`,
  );
  }
  } catch (err) {
- /* eslint-disable-next-line @typescript-eslint/restrict-template-expressions */
- this.error(`Failed to auto-start Lisk Core v4.\nError: ${(err as Error).message}`);
+ const errorMsg = `Failed to auto-start Lisk Core v4.\nError: ${(err as Error).message}`;
+ throw new MigratorException(
+ errorMsg,
+ err instanceof MigratorException ? err.code : ERROR_CODE.LISK_CORE_START,
+ );
  }
  } else {
  this.log(
@@ -354,9 +375,94 @@ class LiskMigrator extends Command {
  this.log('Please copy genesis block to the Lisk Core V4 network directory.');
  }
  } catch (error) {
- this.error(error as string);
+ const commandsToExecute: string[] = [];
+ const code = Number(`${(error as MigratorException).code}`);
+
+ const basicStartCommand = `lisk-core start --network ${networkConstant.name}`;
+ const liskCoreStartCommand = getLiskCoreStartCommand() ?? basicStartCommand;
+
+ const backupLegacyDataDirCommand = `mv ${liskCoreV3DataPath} ${LISK_V3_BACKUP_DATA_DIR}`;
+ const copyLegacyDBCommand = `cp -r ${
+ (resolve(LISK_V3_BACKUP_DATA_DIR, SNAPSHOT_DIR), LEGACY_DB_PATH)
+ }`;
+
+ if (
+ [ERROR_CODE.DEFAULT, ERROR_CODE.INVALID_CONFIG, ERROR_CODE.GENESIS_BLOCK_CREATE].includes(
+ code,
+ )
+ ) {
+ const genesisBlockCreateCommand = getGenesisBlockCreateCommand();
+ commandsToExecute.push(
+ '\n',
+ '## Create the genesis block',
+ '## NOTE: This requires installing Lisk Core v4 locally. Please visit https://lisk.com/documentation/lisk-core/v4/setup/npm.html for further instructions',
+ '\n',
+ );
+ commandsToExecute.push(genesisBlockCreateCommand);
+ commandsToExecute.push('\n', '-----------------------------------------------------', '\n');
+ }
+
+ if (
+ [
+ ERROR_CODE.DEFAULT,
+ ERROR_CODE.INVALID_CONFIG,
+ ERROR_CODE.GENESIS_BLOCK_CREATE,
+ ERROR_CODE.BACKUP_LEGACY_DATA_DIR,
+ ].includes(code)
+ ) {
+ commandsToExecute.push('\n', '## Backup Lisk Core v3 data directory', '\n');
+ commandsToExecute.push(backupLegacyDataDirCommand);
+ commandsToExecute.push('\n', '-----------------------------------------------------', '\n');
+ }
+
+ if (
+ [
+ ERROR_CODE.DEFAULT,
+ ERROR_CODE.INVALID_CONFIG,
+ ERROR_CODE.GENESIS_BLOCK_CREATE,
+ ERROR_CODE.BACKUP_LEGACY_DATA_DIR,
+ ERROR_CODE.COPY_LEGACY_DB,
+ ].includes(code)
+ ) {
+ commandsToExecute.push(
+ '\n',
+ '## Copy legacy (v3) blockchain information to Lisk Core v4 legacy.db',
+ '\n',
+ );
+ commandsToExecute.push(copyLegacyDBCommand);
+ commandsToExecute.push('\n', '-----------------------------------------------------', '\n');
+ }
+
+ if (
+ [
+ ERROR_CODE.DEFAULT,
+ ERROR_CODE.INVALID_CONFIG,
+ ERROR_CODE.GENESIS_BLOCK_CREATE,
+ ERROR_CODE.BACKUP_LEGACY_DATA_DIR,
+ ERROR_CODE.COPY_LEGACY_DB,
+ ERROR_CODE.LISK_CORE_START,
+ ].includes(code)
+ ) {
+ commandsToExecute.push(
+ '\n',
+ '## Lisk Core v4 start command - Please modify if necessary',
+ '\n',
+ );
+ commandsToExecute.push(liskCoreStartCommand);
+ commandsToExecute.push('\n', '-----------------------------------------------------', '\n');
+ }
+
+ await writeCommandsToExec(this, networkConstant, outputDir, commandsToExecute);
+
+ this.error(
+ `Migrator could not finish execution successfully due to: ${
+ (error as Error).message
+ }\nPlease check the commands to be executed in the file: ${filePathCommandsToExec}`,
+ );
  }
 
+ await writeCommandsToExec(this, networkConstant, outputDir);
+
  this.log('Successfully finished migration. Exiting!!!');
  process.exit(0);
  }