The Nervos Address Format Upgrade

NervosLearning Resources

The address format used on Nervos’ Layer 1 is being updated to support new features. Layer 1 addresses are those that begin with “ckb” and are used with many of the popular dApps and wallets in the Nervos ecosystem.

On Nervos, an address represents more than just a public key to an account. It is a powerful format that is used to encode information about how to access an asset, including who the owner is, what smart contract code governs it (lock script), and what specific conditions must be met in order to grant access.

The existing address format has been deprecated in favor of the new “Full Payload Format” addresses, which are commonly referred to as “CKB2021 Addresses”. This new address format allows the use of certain features that are part of the Major Protocol Upgrade and is also better designed to be more future-proof, removing the need for more frequent updating in the future.

Removal of Short Addresses

The first thing you will notice is the CKB2021 addresses are usually longer than the old short address format which you may have seen in commonly used wallets like Neuron, imToken, and on some exchanges.

Below is an example of a short address using the old format:


Using the CKB2021 address format, this address would convert to:


Both of these addresses are for the same account that uses the SECP256K1 + Blake160 lock script, which is more commonly referred to as the default lock. The short address omits the information about the lock script used and instead uses a one-byte predefined ID code to indicate the default lock was used. This works because the default lock is considered well-known. The default lock was included in the genesis block, and it is the most supported and commonly used lock script in the Nervos ecosystem, so every dApp should know about it.

However, there are problems with this approach. Everyone has to agree on what a well-known lock script is. Users of Portal Wallet quickly noticed that their addresses were much longer than the addresses from Neuron and imToken. This is because Portal Wallet relies on PW-Lock, which was created by the Lay2 team and was not considered to be well-known at the time it was released. This creates a governance problem since someone has to decide what is considered to be well-known, so it could also be viewed as a form of centralization or favoritism.

In addition to the governance problem, this requires a list of well-known lock scripts to be included in the configuration of every dApp and wallet. If the list is updated, every single dApp and wallet must upgrade their configuration or they will not be able to properly send to some addresses. This creates another problem since it has been exceedingly difficult to get everyone to make updates in a timely manner. Some users have had problems with certain exchanges not being able to send CKB to some wallet addresses. This is due to outdated libraries that the exchange has neglected to update even though they have been notified of the problem and the steps to resolve it.

Targeting of CKB-VM V1

With the Major Protocol Upgrade comes CKB-VM v1, a new version of the virtual machine that executes smart contracts on Nervos’ Layer 1. There are numerous updates in CKB-VM v1 which may be highly beneficial to smart contract development, but the previous address format did not provide a way to specify which virtual machine version should be used for a lock script.

The CKB2021 address format allows for the specification of the necessary VM version through the `hash type` value. This value is explicitly defined as a single byte in the hash type data field, which means if more VM versions are added in the future, the CKB2021 address format will be able to target them without having to change the address format specifically to use a new virtual machine.


If you are a developer who utilizes Layer 1 addresses in any capacity, you may need to make updates to add support for CKB2021 Addresses. In some cases, this is as simple as updating your libraries and node software. We recommend that all developers read through the CKB2021 Hardfork Migration Guide to ensure that your dApp is properly updated and ready.

If you are a user of any dApp, app, or exchange that exhibits problems, we recommend that you report the problems you encounter directly to the developers of what is affected. Only the developers are able to fix problems with the product they provide and hearing reports from their customers is the best way to let them know they need to prioritize a fix.

Even though these types of changes can create periods of incompatibility while updates are being done, we believe that making this change now will have far greater benefits in the long run as we continue to add more features and expand our ecosystem in the future. Thank you for your patience during this transitional period.