Enabling forging

Describes how to enable forging on a node as a delegate.

1. Registering a delegate

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

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

    const tx = await apiClient.transaction.create({
        moduleID: 5,
        assetID: 0,
        fee: 1100000000,
        asset: {
            username: 'lightcurve', (1)
        },
    }, passphrase);

    try {
      response = await apiClient.transaction.send(tx);
    } catch (error) {
      response = error;
    }
}
1 The chosen delegate name has to be unique in the network.

For more information about forging, please check the forging explanations on the DPoS module page.

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 enrypted 12 word mnemonic passphrase of the delegate account.

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

To encrypt your passphrase, it is recommended to use one of the following alternatives listed below:

The first alternative with the Lisk Commander is described in detail below. 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 (binary) 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 behaviour will be punished by the network.

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

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 Binary address in 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.