Enabling forging
How to enable forging on a node for a particular delegate, and how to safely re-enable forging on another node.
1. Adding the delegate info to the config
This step only needs to be performed when a delegate is enabling forging on a node for the first time.
To enable your node to forge for a particular delegate, firstly it is required to insert certain 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.
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 --pretty
The command will ask for the delegate passphrase, and in order to symmetrically encrypt the passphrase for the config, it will also ask for a password.
Store the password you used for the encryption somewhere safe. It will be required everytime you wish to enable forging, in order to decrypt the delegates' passphrase in the config. |
Add the JSON object to the config under forging.delegates
.
forging.delegates
stores the list of delegates who are allowed to forge on this node:
{
//...
"logger": {
"fileLogLevel": "error",
"consoleLogLevel": "info" (1)
},
"rpc": {
"enable": true, (2)
"mode": "ipc"
},
"forging": {
"delegates": [ (3)
{
"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 | Set the console log level to info to view all relevant logs on the console. |
2 | Enable IPC to be able to use all commands of the Lisk Core CLI (see Command line interface) |
3 | Add the delegate config info here, under forging.delegates of the node configuration. |
Restart the node to apply the changes in the config. |
2. Forger_info data
The forger_info
data contains the following three properties:
-
height
: Last forged block height. -
maxHeightPreviouslyForged
: Delegates largest previously forged height. -
maxHeightPrevoted
: Delegates largest prevoted height for a block.
For each of these properties, the forger config contains the value used in the last block forged by the node.
These three variables are required for enabling forging for the corresponding delegate.
3. Checking the forging status
To check the forging status of a Lisk Core node, execute the following command:
lisk-core forging:status
[{"address":"89aa5fc8861d392f60662f76a379cc348fe97d28","forging":true,"height":670237,"maxHeightPrevoted":670159,"maxHeightPreviouslyForged":670187}]
The command returns a list of delegates, based on the list under forging.delegates
in the Lisk Core config, (based on the details added to the config in the previous step, Adding the delegate info to the config).
The following information is displayed for each delegate:
-
The hexadecimal representation of the delegate address.
-
If the delegate has forging enabled or not.
-
The Forger_info data.
4. Enable forging
|
Enable forging with the following command:
lisk-core forging:enable 9bd82e637d306533b1e1ad66e19ca0047faa1a6a --use-status-values (1)
1 | Replace 9bd82e637d306533b1e1ad66e19ca0047faa1a6a with the hex string representation of your delegate address, which was displayed while Checking the forging status. |
This will automatically use the currently saved forger_info
data to enable forging on the node.
Verify the correctness of the values height
, maxHeightPrevoted
, and maxHeightPreviouslyForged
by answering yes
, and use your password to decrypt the passphrase for forging.
Don’t trust Forger_info data from public APIs or explorers, make sure to always use your local data!
You can use your data automatically by setting the flag --use-status-values .
|
Current forging status for delegate account 331e287263c8166febde9d77a5f333df75056c74 is:
{"height":14814092,"maxHeightPrevoted":14814017,"maxHeightPreviouslyForged":14814025}
? Do you want to use the above values to enable forging? yes
? Enter password to decrypt the encrypted passphrase: **********
Updated forging status:
{"address":"331e287263c8166febde9d77a5f333df75056c74","forging":true}
forging:enable
command:Enable forging for the given delegate address.
USAGE
$ lisk-core forging:enable ADDRESS [HEIGHT] [MAXHEIGHTPREVIOUSLYFORGED] [MAXHEIGHTPREVOTED]
ARGUMENTS
ADDRESS Address of an account in hex 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)
-y, --yes Do you want to use these values to enable forging.
--overwrite Overwrites the forger info.
--pretty Prints JSON in pretty format rather than condensed.
--use-status-values Use delegates forging status values.
EXAMPLES
forging:enable ab0041a7d3f7b2c290b5b834d46bdc7b7eb85815 --use-status-values
forging:enable ab0041a7d3f7b2c290b5b834d46bdc7b7eb85815 --use-status-values --yes
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
5. Disable forging
Sometimes it is necessary to disable forging, for example to update to the latest Lisk Core version, or if you are moving your node to a different server.
If you would like to completely stop forging without being punished by the network, make sure to unvote yourself, see:
|
Disable forging with the following command:
lisk-core forging:disable 9bd82e637d306533b1e1ad66e19ca0047faa1a6a (1)
1 | Replace 9bd82e637d306533b1e1ad66e19ca0047faa1a6a with the hexadecimal representation of your delegate address, which was displayed while Checking the forging status. |
forging:disable
command:Disable forging for the 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
6. Safely enabling forging on another node
To safely enable forging on another node, please ensure to follow the steps below:
-
Setup a new node on another server.
-
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.
-
Login to the server with the old node.
-
Disable forging on the old node.
-
Stop the old node.
-
Dump the data in the
forger_info
table of the db of your node.lisk-core forger-info:export
-
Login to the server with the new node.
-
Restore the
forger_info
table.lisk-core forger-info:import ./forger.db.tar.gz
-
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
-
Fetch the forging data needed to enable forging by Checking the forging status.
7. Safely enabling forging without forger_info data
- Configurable Constants
-
-
BLOCK_TIME = 10
: The block time of the considered blockchain in seconds, i.e., 10 for Lisk Mainnet. -
MAX_FORK_DEPTH = 8640
: An upper boundary on the largest chain of off-chain blocks for which the validator generated a block, i.e., for every block at heighth
generated by the validator, the parent block at heighth - MAX_FORK_DEPTH
must be contained in the canonical chain that is eventually finalized. It is recommended to useMAX_FORK_DEPTH
= 8640 = 24*60 *6 (number of blocks generated in 24 h).
-
- Required Delegate Input
-
-
lastHeightActive
: Unix timestamp of the last height when the validator node could have possibly been active and forging, (over estimate with a larger number when uncertain about the exact time).
-
- Instructions
-
-
Start a new node with forging deactivated and synchronize with the Lisk blockchain until there is a block
finalizedBlock
that is finalized, and that the finalized block header timestamp is greater than the last active height:finalizedBlock.header.timestamp > lastHeightActive
-
Obtain a block
parentBlock
which is a parent block offinalizedBlock
at heightfinalizedBlock.header.height - MAX_FORK_DEPTH
.parentBlock.header.height = finalizedBlock.header.height - MAX_FORK_DEPTH
-
Compute the number of missed blocks in the current chain between the
finalizedBlock
and theparentBlock
, i.e., as shown below:missedBlocks = ceil((finalizedBlock.header.timestamp - parentBlock.header.timestamp)/BLOCK_TIME) - (finalizedBlock.header.height - parentBlock.header.height)
-
Use the following forging configuration and activate forging:
height = finalizedBlock.header.height maxHeightPreviouslyForged = finalizedBlock.header.height + missedBlocks heightPrevoted = finalizedBlock.header.height
-