Enabling forging

Use the command-line interface to enable or disable forging.

To enable your node to forge for a particular delegate, firstly it is required to insert some data into the config file under the forging.delegates array as described below:

  • address: The address of the delegate.

  • encryptedPassphrase: The symmetrically encrypted 12 word mnemonic passphrase of the delegate account.

  • hashOnion: The onion of hashes that is used by the delegate.

1. Adding the delegate info to the config

Generate the necessary config object conveniently with the Lisk Core CLI.

The following command will return a config object to the console. The object can be copy-pasted directly into the application configuration as shown below:

lisk-core forging:config --passphrase your_passphrase --password your_password --pretty

Add the JSON object to the config under forging.delegates as shown below:

{
  //...
  forging: {
    force: false,
    delegates: [ (1)
        {
            address: "86555265f0110b4ed5a8cb95dbc732e77732c474",
            encryptedPassphrase: "iterations=1&salt=476d4299531718af8c88156aab0bb7d6&cipherText=663dde611776d87029ec188dc616d96d813ecabcef62ed0ad05ffe30528f5462c8d499db943ba2ded55c3b7c506815d8db1c2d4c35121e1d27e740dc41f6c405ce8ab8e3120b23f546d8b35823a30639&iv=1a83940b72adc57ec060a648&tag=b5b1e6c6e225c428a4473735bc8f1fc9&version=1",
            hashOnion: {
                "count": 1000000,
                "distance": 1000,
                "hashes": [
                    "ff2156e33c4aefa4a5a790edbe329f4a",
                    "5f86db180d4e63be6412d42d444dfb49",
                    "10fc37bb42d7f77030138e45795fef65",
                    "f04a306a73c5d7d94cc4f262b4d5ebb4",
                    //[...]
                    "ca41d52225f4b76140fc7f277731d326",
                    "fde61109609b74ba16d5ebd72a8b446f",
                    "9752dc2228492466d7c2046354d5fdfd"
                ]
            }
        }
    ],
  },
  //...
}
1 The list of delegates who are allowed to forge on this node.
Restart the node to apply the changes in the config.

2. Checking the forging status

To check the forging status of a Lisk Core node execute the following command:

lisk-core forging:status
Example output
[{"address":"89aa5fc8861d392f60662f76a379cc348fe97d28","forging":true,"height":670237,"maxHeightPrevoted":670159,"maxHeightPreviouslyForged":670187}]

The command returns the hexadecimal representation of the delegate address based on the details added to the config in the previous step Adding the delegate info to the config and if the delegate has forging enabled or not.

It also returns the following three variables that are required to enable forging for a delegate:

  • height: Last forged block height.

  • maxHeightPreviouslyForged: Delegates largest previously forged height.

  • maxHeightPrevoted: Delegates largest prevoted height for a block.

If a delegate enables forging for the first time, the value for height, maxHeightPreviouslyForged and maxHeightPrevoted is always 0.

3. forging:enable

Enable forging for given delegate address.

USAGE
  $ lisk-core forging:enable ADDRESS HEIGHT MAXHEIGHTPREVIOUSLYFORGED MAXHEIGHTPREVOTED

ARGUMENTS
  ADDRESS                    Address of an account in a hexadecimal format.
  HEIGHT                     Last forged block height.
  MAXHEIGHTPREVIOUSLYFORGED  Delegates largest previously forged height.
  MAXHEIGHTPREVOTED          Delegates largest prevoted height for a block.

OPTIONS
  -d, --data-path=data-path  Directory path to specify where node data is stored. Environment variable "LISK_DATA_PATH" can also be used.

  -w, --password=password    Specifies a source for your secret password. Command will prompt you for input if this option is not set.
                             	Examples:
                             	- --password=pass:password123 (should only be used where security is not important)

  --overwrite                Overwrites the forger info

  --pretty                   Prints JSON in pretty format rather than condensed.

EXAMPLES
  forging:enable ab0041a7d3f7b2c290b5b834d46bdc7b7eb85815 100 100 10
  forging:enable ab0041a7d3f7b2c290b5b834d46bdc7b7eb85815 100 100 10 --overwrite
  forging:enable ab0041a7d3f7b2c290b5b834d46bdc7b7eb85815 100 100 10 --data-path ./data
  forging:enable ab0041a7d3f7b2c290b5b834d46bdc7b7eb85815 100 100 10 --data-path ./data --password your_password

4. forging:disable

Disable forging for given delegate address.

USAGE
  $ lisk-core forging:disable ADDRESS

ARGUMENTS
  ADDRESS  Address of an account in a hexadecimal format.

OPTIONS
  -d, --data-path=data-path  Directory path to specify where node data is stored. Environment variable "LISK_DATA_PATH" can also be used.

  -w, --password=password    Specifies a source for your secret password. Command will prompt you for input if this option is not set.
                             	Examples:
                             	- --password=pass:password123 (should only be used where security is not important)

  --overwrite                Overwrites the forger info

  --pretty                   Prints JSON in pretty format rather than condensed.

EXAMPLES
  forging:disable ab0041a7d3f7b2c290b5b834d46bdc7b7eb85815
  forging:disable ab0041a7d3f7b2c290b5b834d46bdc7b7eb85815 --data-path ./data
  forging:disable ab0041a7d3f7b2c290b5b834d46bdc7b7eb85815 --data-path ./data --password your_password

5. Safely enabling forging on another node

To safely enable forging on another node, please ensure to follow the steps below:

  1. Setup a new node on another server.

  2. Start the node and let it synchronize with the network. If available, it is recommended to synchronize from snapshots to speed up the synchronization process.

  3. Login to the server with the old node.

  4. Disable forging on the old node.

  5. Stop the old node.

  6. Dump the data in the forger_info table of the db of your node.

    lisk-core forger-info:export
  7. Login to the server with the new node.

  8. Restore the forger_info table.

    lisk-core forger-info:import ./forger.db.tar.gz
  9. Adding the delegate info to the config.

  10. Ensure the node is fully synchronized with the network. The height of your node should be equal to the current network height.

    lisk-core node:info
  11. Please double check again, that forging for this delegate is not enabled on other nodes.

  12. Fetch the forging data needed to enable forging by Checking the forging status.

  13. Enable forging.