Enable forging

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

How to register as delegate is explained in the Registering as delegate section of "Consensus in Lisk".

For more information about forging, please see the Forging section in the Consensus in Lisk page.

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:

  • publicKey: The publicKey of the delegate.

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

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

To encrypt your passphrase and to generate the hash onion, it is recommended to use one of the following alternatives:

The first alternative with the Lisk Commander is described in detail below.

1. Encrypting the passphrase

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 --outputPublicKey
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",
        "publicKey": "a4465fd76c16fcc458448076372abf1912cc5b150663a64dffefe550f96feadd"
}
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.

  • Type in the passphrase followed by the password required for encryption.

  • This will result in the creation of an encryptedPassphrase key-value pair.

2. Generating the hash onion

$ lisk hash-onion -o ./hash_onion.json
# Output
#{
#    "count": 1000000,
#    "distance": 1000,
#    "hashes": [
#        "ff2156e33c4aefa4a5a790edbe329f4a",
#        "5f86db180d4e63be6412d42d444dfb49",
#        "10fc37bb42d7f77030138e45795fef65",
#        "f04a306a73c5d7d94cc4f262b4d5ebb4",
#        //[...]
#        "ca41d52225f4b76140fc7f277731d326",
#        "fde61109609b74ba16d5ebd72a8b446f",
#        "9752dc2228492466d7c2046354d5fdfd"
#    ]
#}
When you enable forging as a delegate on a new node, you need to use the exact same hash onion in the config as on the old node, to enable forging successfully.

3. Adding the delegate info to the config

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

{
  forging: {
    force: false,
    delegates: [ (1)
        {
            encryptedPassphrase: "iterations=1&salt=476d4299531718af8c88156aab0bb7d6&cipherText=663dde611776d87029ec188dc616d96d813ecabcef62ed0ad05ffe30528f5462c8d499db943ba2ded55c3b7c506815d8db1c2d4c35121e1d27e740dc41f6c405ce8ab8e3120b23f546d8b35823a30639&iv=1a83940b72adc57ec060a648&tag=b5b1e6c6e225c428a4473735bc8f1fc9&version=1",
            publicKey: "9d3058175acab969f41ad9b86f7a2926c74258670fe56b37c429c01fca9f2f0f"
            hashOnion: {
                "count": 1000000,
                "distance": 1000,
                "hashes": [
                    "ff2156e33c4aefa4a5a790edbe329f4a",
                    "5f86db180d4e63be6412d42d444dfb49",
                    "10fc37bb42d7f77030138e45795fef65",
                    "f04a306a73c5d7d94cc4f262b4d5ebb4",
                    //[...]
                    "ca41d52225f4b76140fc7f277731d326",
                    "fde61109609b74ba16d5ebd72a8b446f",
                    "9752dc2228492466d7c2046354d5fdfd"
                ]
            }
        }
    ],
  },
  modules: {
    http_api: {
      access: {
        whiteList: ["127.0.0.1", "REPLACE_ME"], (2)
      }
    }
  }
}
1 The list of delegates who are allowed to forge on this node.
2 Replace with the IP address which will be used to access the 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.

4. Enable/Disable Forging

Do not activate forging for the same delegate on multiple nodes. This behaviour will be punished by the network.

In case you want to change the node you are forging on, check the section Enabling forging on another node.

Please ensure your node is fully synchronized with the network, before you enable forging.

If the node is running on your local machine, it is possible to enable forging via the API, without any further interruption. If you want to enable forging from remote, ensure to whitelist the remote IP as described in the API access guide.

Use the following curl command to enable the forging for your delegate:

Enable forging
curl -X PUT \
  http://127.0.0.1:4000/api/node/status/forging \ (1)
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
          "publicKey": "YYYYYYYYY", (2)
          "password": "XXX", (3)
          "forging": true (4)
      }'
1 Replace 127.0.0.1 with the IP of your Lisk node, if you run the command remotely.
2 publicKey is the key for the delegate which is required to be enabled/disabled.
3 password is the password used to encrypt your passphrase in the config.
4 forging is the boolean value to enable or disable the forging.

Use the following curl command to disable the forging for your delegate:

Disable forging
curl -X PUT \
  http://127.0.0.1:4000/api/node/status/forging \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
          "publicKey": "YYYYYYYYY",
          "password": "XXX",
          "forging": false (1)
      }'
1 Change forging to false to disable forging for a delegate on the node.

The endpoints to enable and disable forging are idempotent.

This means that the results are identical, regardless of how many times the query is executed.

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.

    pg_dump -d lisk_dev -t forger_info > forger_info.sql

  7. Login to the server with the new node.

  8. Restore the forger_info table.

    pg_restore -d lisk_dev -t forger_info forger_info.sql

  9. Add the forging data 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.

    curl http://127.0.0.1:4000/api/node/status

  11. Please double check again, that forging for this delegate is not enabled on other nodes. See the section check forging

  12. Enable forging.

5. Check forging

Use the following curl command to verify the forging status of your delegate:

curl \
  http://127.0.0.1:4000/api/node/status/forging \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json'

The result should appear as shown below in the following code snippet:

{
  "meta": {},
  "data": [
    {
      "forging": true,
      "publicKey": "9bc945f92141d5e11e97274c275d127dc7656dda5c8fcbf1df7d44827a732664"
    }
  ],
  "links": {}
}