BNB Smart Chain Testnet: Luban Upgrade Announcement

BNB Smart Chain Testnet: Luban Upgrade Announcement

BNB Smart Chain Chapel Testnet is expected to have a scheduled hard fork upgrade named Luban at block height 29,295,050. The current block generation speed forecasts this to occur around 27th Apr 2023 at 06:30 AM (UTC). The validators and full node operators on Testnet should switch their software version to v1.2.1 before 27th Apr 2023.

1. Background Story

1.1 Who is Luban?

Luban(507-? BC), also known as Gongshu Ban, was a legendary figure in ancient China who was celebrated for his exceptional skills in carpentry, architecture, and engineering. He was a gifted artisan, engineer, and inventor who lived during the Warring States period (475-221 BC) and his contributions to the fields of carpentry, architecture, and engineering were truly remarkable. His designs and innovations were not only groundbreaking for his time, but they have also laid the foundation for many modern-day engineering feats that we continue to marvel at today.

1.2 What is a hard fork upgrade?

A hard fork is an upgrade that is not compatible with the previous release because some breaking changes are introduced in the latest release. A hard fork in BNB Smart Chain requires more than half of all validators to successfully upgrade to keep making blocks. If the existing full nodes in the network do not upgrade, they will not be able to receive and execute further blocks normally after the hard fork block height.

1.3 What happens during a network upgrade?

Logic changes will occur at block height 29,295,050 for this upgrade. After the activation of the upgrade, the blockchain is able to handle a series of new features and bug fixes.

2. How does this upgrade affect me?

2.1 As a full node operator, what do I have to do?

This release is breaking and you need to switch to v1.2.1. Upgrade instructions are (all the below should be done before the hardfork block height):

  1. If your node is already synced with the network, please download and compile the latest version
  2. Stop the geth process and restart it with v1.2.1.

2.2.Important: For Validator Operator

If you are running as a validator, the following extra steps are needed!

Step 1. Create a voting key first: ./geth bls account new --datadir <path>

  • It will generate a wallet if it has not been created before, you have to keep the wallet password. If the wallet has been created before, you only need to provide the password.
  • Then it will create an account, you have to keep the account password too, the password length should >=10 characters.
    Remember, you can create several accounts, but only one will be used.

Step 2. You can view keys in the wallet by: ./geth bls account list --datadir <path>
Remember the first one listed here will be used as the voting key, other keys are not used right now.

Step 3. update the config file: config.toml

  • add 2 fields under Node section: BLSPasswordFile & BLSWalletDir
    You need to provide the file: /<path>/bls/blspassword.txt, may generate it by: echo <WalletPassword> >/<path>/bls/blspassword.txt
  • add 1 field in [Eth.Miner] section: VoteEnable = true to enable it.
    Or you may manually add an option on node start: geth --vote to enable it as well.

The content of the config.toml for example:

BLSPasswordFile = "/<path>/bls/blspassword.txt"
BLSWalletDir = "/<path>/bls/wallet"
VoteEnable = true

note: if the node prints: “BLS wallet did not exists.”,
then you may add the flag to specify it: “–blswallet /<path>/bls/wallet”

Step 4: restart
You may only provide the flag: --vote, if you did not specify it in config.toml
Then you may go ahead, just restart the node.

2.3 What will happen if I forget to upgrade my full node in time?

If you cannot upgrade your software, you cannot sync with the upgraded BNB Smart Chain peer/validator nodes. You will not be able to connect or send transactions.

How to recover?

  1. Download and compile the latest version v1.2.1.
  2. Stop the geth process and restart it with v1.2.1.

2.4 As a developer, what do I have to do?

There are no changes to the EVM module. You do not need to do anything.

3. Upcoming Changes

3.1 BEP-126: Introduce Fast Finality Mechanism (Part 1)

This BEP describes a fast finality mechanism to finalize a block, once the block has been finalized, it won’t be reverted forever.

The finality of a block can be achieved within two blocks in most cases, this is expected to reduce the chance of chain re-organization and stabilize the block producing further.

Luban upgrade only provides the capability of fast finality, the validators can vote, but the votes are not used to finalize a block and the reward & punishment mechanisms are not enabled either.

Fast Finality will not be fully ignited until the upgrade: Plato.

3.2 BEP-174: Cross Chain Relayer Management

This BEP introduces a new governance proposal type to manage the set of whitelisted Relayers.
A Relayer whitelist was introduced recently to the BSC genesis contracts (PR-198). This BEP will improve the management of the relayer whitelist by introducing Relayer Managers, where a Relayer Manager can manage the registration of a single Relayer. Managers will be elected and ejected via governance.

3.3 BEP-221: CometBFT Light Block Validation

This BEP introduces a new precompiled contract to validate the CometBFT light blocks.

3.4 Other Notable Changes


  • #1357 Integration API for EIP-4337 bundler with an L2 validator/sequencer


  • #1486 feature: remove diff protocol registration


  • #1430 docker: upgrade alpine version & remove apks version
  • #1458 cmd/faucet: clear reqs list when reorg to lower nonce
  • #1484 fix: a deadlock caused by bsc protocol handshake timeout

Find us on



Telegram: Telegram: Contact @BNBchaincommunity

Discord: BNB Chain

Hi, thank you for sharing the detailed announcement about the Luban Upgrade for the BNB Smart Chain Chapel Testnet. The information on upcoming changes, including BEP-126, BEP-174, BEP-221, and other notable changes, gives an exciting insight into the improvements expected with the Luban upgrade. The fast finality mechanism, cross-chain relayer management, and CometBFT light block validation will surely contribute to the overall growth and stability of the BNB Smart Chain ecosystem.

What is the BLS Wallet and Password?
Which feature is it related to ?

BLS represents: Boneh–Lynn–Shacham, is a kind of threshold signature.
detail: BLS digital signature - Wikipedia
And the BLS Wallet here is used to manage the voting keys.
The BEP behind it is: BEP-126: FastFinality

Hello - a question regarding the files generated by geth bls account new - if we migrate our existing Validator to a new server, do we also have to migrate the BLS keys also or can we simply generate a new one?