Enabling forging

How to enable forging on a node as a delegate. For more information about forging, please check the forging explanations on the DPoS module page.

1. Registering a delegate

Before it is possible to enable forging on a node, it is required to register as a delegate. This is achieved by choosing a unique delegate name, and posting a corresponding Register Delegate transaction to the network.

There are many possibilities to post the transaction, use the one you prefer: Lisk Desktop, Lisk Elements, or the Dashboard plugin.

2. Add forging data to config

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:

  • publicKey: The publicKey of the delegate.

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

  • hashOnion: The hash onion stores the random seeds of the delegate for each forging round.

To create the forging configuration data, it is recommended to use one of the following alternatives listed below:

  • Option A - Creating the data with the application CLI

  • Option B - Creating the data with Lisk Commander

If the blockchain application was bootstrapepd with Lisk Commander, it is possible to generate the relevant forging data conveniently with the command forging:config.

$ ./bin/run forging:config --count=4000 --output ./forging_config.json
? Please enter passphrase:  [hidden] (1)
? Please re-enter passphrase:  [hidden]
? Please enter password:  [hidden] (2)
? Please re-enter password:  [hidden]
1 Passphrase of the delegate account.
2 Password to encrypt the passphrase of the delegate account.
For this example, we reduce the value of count to 4000, with a default distance of 1000 this will only produce 5 hashes in the hash onion. Generally though, it is recommended to use high values for count, so the delegate has enough hashes to forge for a long time.
forging_data.json
{
 "address": "92ff111dfc904d1d8b077bf6e815fd21d881b005",
 "encryptedPassphrase": "iterations=1000000&cipherText=75e886380f60687b4bc12879236cd58ffbc5aa8b99855bd69e6957f1c278f02c6cd759ea11614f85d353502eeae3abb622ca118b403d4670674403314ce3ade57c69df5c157c506303e950&iv=8e375e50e2a66fb71a25cd40&salt=739f615c7502b880e94fa79c8228a8a9&tag=1138f01b695fad6ff60352c83cd34a6c&version=1",
 "hashOnion": {
  "count": 4000,
  "distance": 1000,
  "hashes": [
   "2ca1380a0f8c123d9e7c2bcbe7a25aa0",
   "4cab4f42f6b36d2e7003556001f18d93",
   "03d5229b74873e6b14436e568bb65756",
   "99212decf3ff2c0e31059f63e596a135",
   "1c46b49528b6793ff4a1bd9859d00b7c"
  ]
 }
}

Please ensure the Lisk Commander is installed in a secure environment. Upon completion, please follow these commands to generate the encrypted passphrase:

$ lisk
lisk passphrase:encrypt --json
Please enter your secret passphrase: ***** (1)
Please re-enter your secret passphrase: *****
Please enter your password: *** (2)
Please re-enter your password: ***
{
        "encryptedPassphrase": "iterations=1000000&cipherText=30a3c8&iv=b0d7322bf24e0dfe08462f4f&salt=aa7e26c9f4317b61b4f45b5c6909f941&tag=a2e0eadaf1f11a10b342965bc3bafc68&version=1",
}
1 Enter the secret passphrase here that needs to be encrypted.
2 Enter the password here that will be required to decrypt the passphrase again.

Be sure to use a strong password.

See the Guidelines for password strength at Wikipedia for reference.

The hash onion can be generated with Lisk Commander in the following manner:

lisk hash-onion --json
  • Add the hash onion and the delegate address in hexadecimal representation to the object with the encryptedPassphraser.

  • 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":[
                "a623885d5422ce0f2aad3ee128e447ce",
                "91e7ecad63bafdf36a5b02556ea77fe7",
                "4a66b400290185cba622f8c9f5d37181",
                //[...]
                "fb8eee95e630e812cdf90d054acc903a"
              ]
            }
        }
    ]
  }
}
1 The list of delegates who are allowed to forge on this node.

Now restart the node to apply the changes in the config.

For more information about the configuration of the Lisk SDK check out the configuration guide.

3. Enable/Disable Forging

  1. Do not activate forging for the same delegate on multiple nodes at the same time. This behavior will be punished by the network.

  2. Ensure the node is fully synchronized with the network, before enabling forging on that node.

  • Option A - Updating the forging status with the application CLI

  • Option B - Updating the forging status via application action

If the blockchain application was bootstrapped with Lisk Commander, it is possible to generate the relevant forging data conveniently with the command forging:enable.

The blockchain application needs to be running to successfully enable forging on the node.
Enable forging
$ ./bin/run forging:enable ab0041a7d3f7b2c290b5b834d46bdc7b7eb85815 100 100 10
Disable forging
$ ./bin/run forging:disable ab0041a7d3f7b2c290b5b834d46bdc7b7eb85815

Invoke the following action to enable the forging for a delegate:

Enable forging
const { createWSClient } = require('@liskhq/lisk-api-client');

export const enableForging = async () => {
    let apiClient = await createWSClient('ws://localhost:8080/ws');
    let response;

    const { data } = await apiClient.invoke('app:updateForgingStatus', {
      address: string, (1)
      password: string, (2)
      forging: true, (3)
      height?: number, (4)
      maxHeightPrevoted?: number, (5)
      maxHeightPreviouslyForged?: number, (6)
      override?: boolean (7)
    });

    try {
      response = await apiClient.transaction.send(tx);
    } catch (error) {
      response = error;
    }
};
1 Address as hex string.
2 Password that was used above to encrypt the passphrase in the configuration.
3 When enabling forging, the value should be true.
4 Not required, when enabling forging for a delegate for the first time. Height of the last forged block by the delegate.
5 Not required, when enabling forging for a delegate for the first time. Height of the previously prevoted block by any delegate. Must match the value in the forger_info data.
6 Not required, when enabling forging for a delegate for the first time. Height of the previously last forged block. Must match the value in the forger_info data.
7 Optional: If true, overrides maxHeightPreviouslyForged and maxHeightPrevoted values in the forger_info data.

Invoke the following action to disable the forging for a delegate:

Disable forging
const { createWSClient } = require('@liskhq/lisk-api-client');

export const disableForging = async () => {
    let apiClient = await createWSClient('ws://localhost:8080/ws');
    const { data } = await apiClient.invoke('app:updateForgingStatus', {
      address: string,
      password: string,
      forging: false (1)
    });
};
1 Change forging to false to disable forging for a delegate on the node.