Upgrade & Hard Fork
Last updated
Last updated
Klaytn and its ServiceChain have constantly released new versions to develop new features and fix bugs. This page is a guide to upgrade ServiceChain binaries and setting hard fork block numbers for your ServiceChain.
This section shows how to upgrade the ServiceChain binary.
NOTE Upgrading ServiceChain binaries may be irreversible and backward-incompatible, meaning you cannot downgrade to an older version. Refer to the release notes for more details. For example, the says:
NOTE: This version updates the version of the database to support snapshot sync. You cannot downgrade to the older versions with existing data after updating to v1.9.0.
You can get the latest version of Klaytn and ServiceChain binaries in one of the below links:
To upgrade the ServiceChain binary, stop the ServiceChain node and replace the binary. For example, you can use below commands to stop an SCN node and replace the binary with a newer one.
You may restart the ServiceChain node after the upgrade. However, if you are planning to activate hard fork in the ServiceChain, you have to keep the ServiceChain nodes down. Refer to the for instructions of ServiceChain hard fork.
This section describes the steps for applying Klaytn to ServiceChain.
To apply the hard fork to the ServiceChain, you need to:
Pick an appropriate block number for the hard fork
Upgrade the ServiceChain binary to a version that supports the hard fork
Set the hard fork block number in the ServiceChain
In the Javascript console of the ServiceChain, you can check the current block number as shown below.
Now, you have to choose an appropriate block number to activate the hard fork. Make sure to have enough number of blocks (which is produced every second) between the current block and the block of hard fork.
If you have upgraded the ServiceChain binaries with a version that supports the desired hard fork, you can set the hard fork block number in the ServiceChain by re-initializing the chain config with updated genesis.
First, specify the hard fork number in the config field of genesis.json. For example, if you are trying to activate the Magma hard fork in your ServiceChain, you should specify the magmaCompatibleBlock in config field of the genesis, like below.
To enable a hard fork in the chain config, previous hard forks should be enabled. That is, to enable Magma hard fork, the EthTxType hard fork should be already enabled. If there are missing fields for the compatible block numbers of preceding hard forks in the chain config, you have to add them too.
For example, if you want to set Magma hard fork block number and if your genesis.json does not have ethTxTypeCompatibleBlock in its config field like below:
You have to add ethTxTypeCompatibleBlock too, when you add magmaCompatibleBlock in the config field, like below.
If you have updated your genesis.json with desired hard forks, re-initialize the chain config and apply your change.
NOTE It is normal that the following error log is printed when you re-initialize the chain config.
Now, restart the ServiceChain node. For example, you can restart a SCN node with the following command.
Then, in the Javascript console of SCN, you can check the updated chain config.
This section describes some details for a specific hard fork.
The Magma hard fork introduces the KIP-71, dynamic gas fee. It includes the upper and lower bound of the gas price.
To set the gas price to a static value, you have to set the upper and lower bound of the gas price to the same value. For example, you can set gas price to 0, using governance.vote API in the Javascript console of the SCN nodes.
NOTE The governance voting and its update are available regardless of the activation of the Magma hard fork. That is, the governance voting can be also done prior to the Magma hard fork activation.
If the votes for updating the upper and lower bound of the gas price were successful, those changes will take effect after 2 istanbul epochs (An epoch has the value in block numbers).
For example, if the epoch is 3600, and the votes for updating the upper and lower bounds of gas price has been placed in the block #4000, those changes will take effect starting from the block #10800. In detail, the votes will be finalized when their first epoch was reached at the block #7200, and the changes are applied at the second epoch (block #10800).
To check the epoch, you can use the governanace.itemsAt API, like below.
You can see that the istanbul.epoch has a value of 3600 blocks, which would normally take an hour to pass.
You can change the epoch too, using the governance.vote API.
Refer to the section in this page for instructions on upgrading the ServiceChain binaries. Make sure to keep the ServiceChain nodes down (or stopped) for now. You will restart them after you have set the hard fork block number.
You can find the history of Klaytn hard forks in the .
By default, the upper bound is set to 750000000000 and the lower bound is set to 25000000000. You can change those bounds in the Javascript console of SCN nodes using the . Obviously, lower bound cannot exceed the upper bound.