CKB v0.100.0 Upgrade Guide

English CKB Development & Technical Discussion
1

CKB v0.100.0 Upgrade Guide

[中文版本]

Upgrades Overview

The upgrade applies in two stages:

  1. Adapt to the incompatible updates accumulated because of the long absence of upgrades of ckb nodes, largely related to RPC.
  2. Comply with the new version of consensus. The new version of consensus, ckb2021, came with this hard fork, while ckb2019 will refer to the current consensus.

A three-step upgrade strategy applies:

  1. Upgrade CKB nodes to v0.100.0.
  2. Replace v0.100.0 with new versions v0.101.0 and v0.102.0, which activates ckb2021 for testnet and mainnet, respectively. These releases are compatible with v0.100.0.
  3. Comply with the ckb2021 after activation.

The version v0.100.0 will not activate the consensus ckb2021 when connecting to the testnet Aggron and the mainnet Lina, hence step 1 is primarily to adapt to the incompatible updates like RPC. Several RC versions will be available as previews before the release of v0.100.0. These RC versions have the same compatibility test results as the official v0.100.0, no need to test them all.

However, the new started dev chain activates ckb2021 by default from the genesis block and is for testing step 3 in advance.

The following sections will explain the further instructions on completing this three-step upgrade.

Upgrade to v0.100.0 or the RC Versions

The initial version of CKB officially online was 0.25.0. Since only minor versions introduce incompatibility upgrades, there have been 19 iterations, starting from 0.43.0 to 0.100.0.
Incompatibility upgrades mainly comprise:

  • RPC modifications
  • Configuration file modifications
  • Command line arguments revisions
  • Database migrations

Inevitably, records might be deficient as it has been two years, and more tests will eventually be required to guarantee compliance.

RPC modifications

This section lists the RPC incompatibility changes since 0.25.0 by versions. Please start with the version currently used in the project. Omitted versions mean there are no RPC modifications of concern.

0.30

Because of the discovery of some incompatibilities with RISC-V, send_transaction from 0.30 onwards screens output cells suspicious of holding RISC-V binaries, and if it found any instructions causing incompatibilities, the node rejects the transaction. The consensus ckb2021 will enable the new version of the VM (vm1), coexisting with the previous version of the VM (vm0). As vm1 has fixed these incompatibilities issues, after the ckb2021 activation, this RPC method will no longer check the incompatibilities. For details on VM version selection, please refer to the 0.100 note.

0.34

This version has dropped the RPC estimate_fee_rate. To automatically adjust the rate during network congestion, use the subscription RPC to get the relevant events and to calculate the rate, or use the median rate of the last N blocks instead.

0.35

Before version 0.35, the error code for an RPC error was -3. From this release onwards, each error has a separate error code and the error message becomes more readable. The data field will contain the backtrace for debugging.

Instead of using the error message to define the logic of the program, developers should consult the latest RPC documentation and depend on the error code accordingly.

Version 0.35 also added new return fields for the methods tx_pool_info, get_peers, and local_node_info. Refer to the RPC documentation if these methods are being used.

0.36
Version 0.36 deprecated get_cells_by_lock_hash and all RPC methods in the Indexer module. These methods no longer exist in 0.100. The external ckb-indexer should be used as a replacement.

Note that ckb-indexer is also in active development. The CKB v0.100 compatible version is ckb-indexer 0.3.0.

0.40

Version 0.40 removes get_cellbase_output_capacity_details. Please use get_block_economic_state instead. Notice the difference in the parameters passed to these two RPCs. In CKB, the cellbase outputs in block N reward the miner of the block N - 11. For the reward distribution of the block N - 11, get_block_economic_state requires the hash of N - 11, while the old RPC get_cellbase_output_capacity_details uses the hash of N.

0.42

Removed the RPC get_peers_state.

0.100

Version 0.100 introduced three major incompatible modifications, yet the more important changes are the consensus variations underlying these three modifications.

First, the uncles_hash field in the block header is removed and replaced with a new extra_hash field. Meanwhile, a new extension field is added to the block. Despite the removal of the uncles_hash field, calculations still need to be performed when building the block header, and the extra_hash is calculated based on uncles_hash and extension.

  • extra_hash equals uncles_hash if the extension field is default.
  • extra_hash is equivalent to ckbhash( uncles_hash || ckbhash(extension)) when extension exists.

The extension field schema is undefined in ckb2021, but for future fork upgrades. CKB nodes accept any extension content with proper length. The applications that use uncles_hash need to accommodate the rule changes. For example, to verify whether an uncle is in an uncle block, the ckbhash(extension) of the block must be in the proof.

Second, send_transaction allow list is enabled by default. Allow list is a preventive mechanism to avoid some common errors. Once developers are familiar with CKB, it can be disabled by the second parameter of send_transaction.

Third, the hash_type in the Script structure has an additional value, data1. If any code deals directly with the molecule binary, data1 corresponds to a value of 2.

As mentioned above, there are two versions of VMs in the ckb2021, vm0 and vm1, and the hash_type value decides which VM version to use.

hash_type before ckb2021 after ckb2021
data vm0 vm0
type vm0 vm1
data1 invalid vm1

Simply put, CKB uses the latest version of the VM to execute the code referenced via type, but it uses the specified version on data, data1, and future variants. For instance, later ckb20xx brings vm2, the table corresponding is:

hash_type before ckb2021 after ckb2021 after ckb20xx
data vm0 vm0 vm0
type vm0 vm1 vm2
data1 invalid vm1 vm1
data2 invalid invalid vm2

If the project deployed a contract and used type to reference, it is necessary to verify the compatibility of the new VM before ckb2021 activation given the automatic upgrade to the new VM version. Recommend using ckb-standale-debugger for testing.

If a deployed contract uses data to reference the code, the ckb-standalone-debugger can also detect any significant reduction in cycles for the new VM.

  • With significant reduction and no compatibility issues, application can use “data1” to reference contracts after enabled by ckb2021.
  • If a significant reduction and compatibility issues have occurred, the developers can deploy the new contract and use “data1” to reference it.
  • Without significant reduction, upgrade is not worth much, keep using “data” to reference the existing contract.

Config File Modificaiton

CKB will warn the deprecated options on launch, mainly for two reasons:

  • Options have been removed
  • Replaced by similar options

It is recommended to generate a new directory with a default configuration file and use diff to compare the updates, or send the list of deprecated options to ask for help.

The db options file has been imported in 0.37 to adjust the parameters of RocksDB. In case a performance problem with disk IO is detected through monitoring, the db options file is available for tuning. Following are the steps:

  • Add an optional item options_file = "default.db-options" under [db] in ckb.toml.
  • Create and change a new file default.db-options in the same directory as ckb.toml based on the ckb recommended configuration.

Command Line Parameter Modification

Only new commands and arguments have been added after 0.25.0. If a ckb call fails, please submit the error for help.

Database Migration

Versions 0.35, 0.40 and 0.43 respectively introduced the full database scan to migrate. It is recommended to sync with a new version of the node and distribute the database directory to all nodes to avoid data migration.

Upgrade v0.101.0 and v0.102.0

In contrast to v0.100.0, there will be no incompatibility update with v0.101.0 and v0.102.0, as the difference lies in the activation of ckb2021 at an epoch number. After the release, simply replace the ckb executable and reboot.

Comply with the consensus ckb2021

The most intuitive modification for most applications is the launch of the new VM version, which has been covered in the RPC revision guide for the RC upgrade.

Another is the removal of the immature rule for using header dep in ckb2021, which allows blocks from previous chains to be used as header dep. However, transactions using the recent block headers are vulnerable to invalidation, thus the recipient is expected to waiting for sufficient confirmations to secure the asset, while the application should evaluate how many blocks to wait before using a block as the header dep depending on the scenario.

The last, there are some modifications on the since field. The rule becomes stringent in ckb2021. When the since field uses the epoch number with a fraction as the unit, the ckb2021 requires that index cannot be greater than length, or both index and length are 0. For scenarios where the relative value of block header timestamp is used, the timestamp of the block that creates the cell is the start time in ckb2021, rather than the median of the previous 37 blocks in the consensus ckb2019. The modification substantially simplifies transaction construction.

Because ckb2021 will be activated starting on the specific epoch, applications can choose a strategy to respond to:

  1. Stop the app before activation, then relaunch the new version of the app when activated. Ideal for applications that are not yet available on the mainnet. If existing cells need to be migrated, allocate time to deal with this collectively before relaunching.
  2. Switch to the new consensus according to the latest block epoch number via techniques like feature switch. It is recommended to implement a lazy update strategy for existing cells as long as no security issues will be caused. In case of potential security issues, please contact [email protected]. The current network activation time can be found via the get_consensus RPC. The consensus ckb2021 corresponds to the set of 7 switches, such as 0028, 0029, and etc, which can be compared to the epoch in the get_tip_header to identify activation status. If the switch in get_consensus returns null, the activation time has not yet been determined.
2 Likes