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.

One option is to create the transaction object with the application CLI:

1.1. Start the blockchain application

./bin/run start

1.2. Create the Delegate Registration transaction

./bin/run transaction:create 5 0 1100000000 --asset='{"username":"myname"}'
? Please enter passphrase:  [hidden]
? Please re-enter passphrase:  [hidden]
{"transaction":"0805100018032080d6c28c042a20bad983c72bed43fd274f852658c298b74c71ab6fc50508879fef309e3836384b32080a066d796e616d653a4045afdd04d0c0bc6e548c0915d5fabef1311b1b75b1eb919a43b88dab539e7b6a99b9075f5d6382ec3bbebfca3301651a15d8af3f999d5b6fa7873b3969cd3d0c"}

1.3. Send the transaction

./bin/run transaction:send 0805100018032080d6c28c042a20bad983c72bed43fd274f852658c298b74c71ab6fc50508879fef309e3836384b32080a066d796e616d653a4045afdd04d0c0bc6e548c0915d5fabef1311b1b75b1eb919a43b88dab539e7b6a99b9075f5d6382ec3bbebfca3301651a15d8af3f999d5b6fa7873b3969cd3d0c
Transaction with id: '1809da284fe26dba90d34dc3aab837a32d3c291a4ca78a9bfa263f927c69598a' received by node.

1.4. Check account details

Use the account:get command to verify the account has now registered a delegate name:

 ./bin/run account:get ed86183c22f8399f7aa28f7d2c2f1680224f7281 --pretty

The new delegate name should be under dpos.delegate.username:

{
  "address": "ed86183c22f8399f7aa28f7d2c2f1680224f7281",
  "token": {
    "balance": "8888869000"
  },
  "sequence": {
    "nonce": "4"
  },
  "keys": {
    "numberOfSignatures": 0,
    "mandatoryKeys": [],
    "optionalKeys": []
  },
  "dpos": {
    "delegate": {
      "username": "myname",
      "pomHeights": [],
      "consecutiveMissedBlocks": 0,
      "lastForgedHeight": 2467,
      "isBanned": false,
      "totalVotesReceived": "0"
    },
    "sentVotes": [],
    "unlocking": []
  },
  "hello": {
    "helloMessage": "Greetings World!"
  }
}

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.