When a Besu IBFT 2.0 network should move to QBFT
An operator should move a permissioned Besu network from IBFT 2.0 to QBFT when they want the newer proof-of-authority consensus on the existing chain, without rebuilding it. The Besu docs describe a live cutover that keeps every block already produced, so the decision is less about whether the switch is possible and more about whether your organization can run it safely across all validators. The Besu project page lists QBFT and IBFT 2.0 as the two proof-of-authority options for private networks, and the migration path is the documented way to move between them. Before committing, confirm with your Besu release team that the version you run supports the migration as documented, since the migration guide is the source for the exact steps.
The effort is driven by the operating model around the change, not by a single command. The main variables are the number of validators, how many organizations must approve the change, how quickly each operator can restart its node in a planned window, and how thoroughly you can verify the result on every node. A network with a few validators run by one team differs sharply from a consortium where each member applies the genesis change on its own schedule. QBFT is not a copy of IBFT 2.0 with a new name: parameters such as blockperiodseconds can take different values from the IBFT 2.0 settings, so the target block time and timeouts need an explicit decision and review. No price or duration is given here because none was supplied. Ask any partner for a written scope that lists validator count, change approvals, test environments and verification steps, and quote against that scope.
What carries over from IBFT 2.0 and what changes in QBFT
This table compares each element of an IBFT 2.0 network with its QBFT counterpart, so operators can see what the live cutover leaves alone and what they must edit. Read the middle column as the current state and the right column as what the migration requires. The main takeaway is that existing blocks and extraData remain valid, while the genesis consensus section, the migration block and client compatibility are the items that need deliberate work.
| Element | IBFT 2.0 network | QBFT after migration |
|---|---|---|
| Existing blocks and extraData | Historical blocks carry IBFT 2.0 extraData with the validator set | Existing blocks and extraData stay valid and are not rewritten |
| Validator set source | Validators are read from block headers under the IBFT 2.0 rules | Besu reads the validator set from block headers, so the set continues from the chain state |
| Genesis consensus section | The genesis file declares the ibft2 consensus block | Operators add a qbft section with a qbft.startBlock value greater than 0 and ahead of the chain head |
| Migration block choice | No cutover block exists | Choose a future block height that every node reaches before restart, confirmed against current chain head |
| Block period settings | Block period follows the IBFT 2.0 blockperiodseconds value | blockperiodseconds can be set to a different value, so confirm the target value in the new genesis |
| Wire protocol during transition | Nodes register the IBFT 2.0 wire protocol | Nodes register both IBFT 2.0 and QBFT wire protocols during the transition |
| Node configuration files | Node config and genesis reference IBFT 2.0 settings | Each node needs the same updated genesis before the migration block; restart validators one at a time |
| Monitoring and dashboards | Dashboards and alerts track IBFT 2.0 consensus metrics | Confirm that metric names and alert rules still match the consensus engine in use after restart |
| Client and tooling compatibility | Scripts, genesis generators and custom tooling may assume IBFT 2.0 key names | Confirm the Besu version supports QBFT on your release, and update any tooling that reads or writes the consensus key |
Documented migration path and supporting tooling
The documented path centers on the genesis file and the node configuration. Operators add a QBFT section to the genesis config with a qbft.startBlock value that marks the block at which QBFT takes over from IBFT 2.0. The migration guide requires that this value be greater than 0 and greater than the chain head at the moment each node restarts, so the value has to be chosen with headroom for the time the rollout will take. The existing extraData stays valid because Besu reads the validator set from block headers, so operators do not rewrite historical headers. QBFT parameters such as blockperiodseconds may differ from the IBFT 2.0 values, and any change should be made deliberately in the same rollout.
- Start block value:
qbft.startBlockmust be identical on every validator and set above the current chain head when the restart happens. - Genesis consistency: every node must apply the same updated genesis before the migration block, because a node still on the old genesis at that block forks off.
- Block period: confirm whether
blockperiodsecondschanges, and record the value in the change ticket. - Node command line: keep the node startup flags, data path and genesis path consistent across the rollout so a restart does not pick up stale settings.
- Historical headers: verify that
extraDataon existing blocks remains readable by the restarted nodes.
Before the cutover, confirm the exact genesis keys and flag names for your Besu version against the migration guide, since configuration keys can change between releases.
During the switch, the node runtime is the evidence you rely on. Besu nodes register both IBFT 2.0 and QBFT wire protocols during the transition, so peers can communicate while validators are restarted at different times. Operators should watch peer counts, block height and validator participation on every node rather than assuming a successful restart means a healthy network. Besu exposes metrics for Prometheus when the --metrics-enabled option is set, with the default endpoint on port 9545, and it can push to a Prometheus push gateway. The project also documents a sample Grafana dashboard that teams can adapt.
- Metrics endpoint: enable
--metrics-enabledon every validator before the first restart so you have a baseline. - Port and scrape rules: confirm the default port 9545 is reachable from your Prometheus servers and not exposed to untrusted networks.
- Push gateway option: use the push gateway only where your network design cannot allow inbound scrapes, and document who owns it.
- Dashboards: start from the sample Grafana dashboard and add panels for peer count and block height per validator.
- Logs: capture each validator's startup logs during the restart window so you can reconstruct the order of events if a fork or stall occurs.
Check that alerting covers loss of a validator and a stalled chain head, since those are the two conditions the migration guide warns about.
Permissioning is local to each node in Besu's documented model. Each node reads a permissions configuration file for node permissioning, which restricts connections to known participants, and account permissioning, which governs onboarding, suspension and restricted actions. These files are not shared automatically, so a validator restarted with a different allowlist can refuse peers that the rest of the network accepts. The migration does not change the permissioning model, but the restart is the moment when mismatched files cause problems, so consistency must be checked before any node goes down.
- Node allowlist: confirm that every validator and boot node holds the same set of permitted node identities before the first restart.
- Account rules: compare account permissioning files across validators so transactions are accepted or rejected consistently.
- Change control: treat permissioning file edits as part of the migration change set, not as a separate task run later.
- Ownership: assign one person to hash or diff the files across nodes and record the result.
- Onchain permissioning: note that Besu removed smart-contract-based permissioning in 25.6.0, so older guidance that relies on it does not apply to this cutover.
Before the cutover, ask your consortium to confirm in writing which permissioning files each member will apply and when.
The migration sits on top of Besu release choices, and several recent releases change what operators can do. Besu requires JDK 25 to build and run, according to the 26.6.0 release notes, so the runtime on every validator must meet that requirement before the cutover. Besu 26.4.0 removed Clique consensus, so networks that are not on IBFT 2.0 or QBFT cannot use this path. The 26.10.0 release notes state that the Bonsai database upgrades automatically on first start and that older Besu versions cannot open an upgraded database. A backup taken before the upgrade is therefore the only documented route back.
- Runtime version: confirm the Besu version and JDK on each validator and record them in the change plan.
- Database backup: take and verify a backup of each node's data before any version change, not only before the consensus change.
- Release pinning: keep all validators on the same Besu release for the cutover window.
- Consensus check: confirm each network is on IBFT 2.0 today, since the path described here does not cover Clique networks.
- Rollback limits: agree in advance whether a rollback is a binary downgrade, a data restore or a fresh resync, and who makes that call.
Recheck the release notes for the exact Besu version you plan to run, because the fixed behavior described here may change in later releases.
How to sequence the cutover without losing quorum
The sequence keeps the network live while every node moves to the same QBFT genesis before the migration block arrives, so the switch happens once and on one chain. Each step ends with a check that tells the operator whether the next step is safe.
Inventory validators and genesis copies
The network operator lists every validator node, every boot or bootnode, and every place a copy of the genesis file lives, including backups, configuration management repositories and container images. Each node is recorded with its current client version, its data directory and the owner who can restart it. The step is done when the list matches the validator set recorded in the current chain and every operator confirms the list in writing. Any node missing from the list is a likely fork risk later, so resolve gaps before choosing a block.
Confirm Besu version and JDK on each node
Each operator checks that its Besu binary supports the QBFT transition and that the Java runtime on the host meets the version the chosen release requires. The Besu 26.6.0 release notes state that Besu requires JDK 25 to build and run, so confirm the runtime on every host rather than assume it. Upgrade nodes that are behind before the migration starts, because mixing unrelated client changes into the consensus change makes failures harder to attribute. The step is done when a version report from every node is compared against the release notes.
Choose the migration block well ahead of head
The network team picks a future block number for qbft.startBlock that is comfortably above the current chain head, so every operator has time to stage the new genesis before the chain reaches it. The docs require the value to be greater than 0 and greater than the chain head when each node restarts, so a block that is already passed will not work. Record the chosen number, the reason for it, and the date and time the operators expect the chain to reach it, with a named owner to confirm progress. The step is done when every operator has acknowledged the number in the change record.
Stage the new genesis on every node
Each operator writes the QBFT genesis with the agreed start block and any QBFT parameters that differ from IBFT 2.0, such as the block period, into the node's configuration without restarting the node yet. The existing extraData stays valid because Besu reads the validator set from block headers, but the genesis file must still match across the network. A checksum of the file on every node is compared against the agreed copy. The step is done when all checksums match and no node holds an older genesis that could still be loaded.
Restart validators one at a time
Operators restart validators sequentially, waiting for each node to rejoin and sync before touching the next one. Nodes register both IBFT 2.0 and QBFT wire protocols during the transition, so restarted and not-yet-restarted validators can still talk. Losing more than one third of validators during restarts stalls the network, so the team keeps at least two thirds of the validator set online at all times and watches block production between restarts. The step is done when every validator runs the staged genesis and the chain keeps producing blocks after the last restart.
Restart non-validator nodes on the new genesis
Non-validating nodes such as RPC endpoints, archive nodes and boot nodes are restarted on the same staged genesis, in an order that keeps the RPC tier serving applications. A node that still runs the old genesis when the migration block is reached forks off the network, so this step is not optional even for nodes that do not sign blocks. Load balancers should be checked so that traffic is not routed to a node that has not yet switched. The step is done when every node reports the same head and the same genesis hash as the validators.
Verify the switch at the migration block
The team confirms that the chain passes the migration block with all nodes on one head, that blocks are produced and finalized under QBFT, and that the validator set reported by the network matches the inventory from the first step. Logs and metrics are reviewed for peer disconnections, rejected blocks or repeated round changes, which are signs of a node on the wrong genesis. The Besu migration documentation is the reference for expected behavior at this point, so the operator records which checks were run. The step is done when a signed verification record shows no forks and no unexplained stalls.
Retire IBFT 2.0 settings
After the chain has run on QBFT for a period the operators agree on, they remove IBFT 2.0 settings and any leftover staged genesis files from configuration repositories, images and runbooks, so a future restart cannot reintroduce the old setting. Backups of the pre-migration data and genesis are kept under the retention policy the organization already applies to chain data. The step is done when a configuration search finds no active IBFT 2.0 references and the change record is closed with the verification results attached.
What drives the effort and the quote
The effort for an IBFT 2.0 to QBFT cutover is set less by the software change than by how many parties must agree, how many configuration copies must change together, and how much rehearsal the team needs before touching a live chain. The cards below cover the drivers that move a quote up or down and the costs that are paid once versus those that recur.
Validator and node count
Every validator and non-validator node must be restarted with the new genesis and configuration, and validators are restarted one at a time. A network with more nodes has more restart windows, more health checks between them, and more chances for one node to be missed. Ask the quote to list each node by role, host and restart window so the effort can be counted per node.
Organizations that must agree
The migration block must be chosen and approved by every operator in the consortium, because any node still on the old genesis at that block forks off. Each organization adds a sign-off step, a change ticket and a contact who can act during the window. Ask the quote to state which parties are in scope and who owns the final go or no-go decision.
Access to genesis and node configuration
The change touches the genesis file and the node configuration on every machine, and the stored genesis copies must match exactly. Teams often find that copies live in different repositories, secret stores or runbooks. Confirm early that the consultant can read every genesis and configuration source, including containers, Helm values or Ansible inventories, before the fixed scope is agreed.
Change-control windows
Validator restarts must fit inside approved maintenance windows, and the migration block must be set far enough ahead that every node can be updated before the chain reaches it. Narrow or infrequent windows lengthen the calendar even when the hands-on work is small. Ask for the schedule of windows, the rollback decision point and who can call a stop during the cutover.
Monitoring coverage
Operators need visibility into peer counts, block production and validator set changes before, during and after the switch. Where Prometheus metrics and dashboards already exist for every node, verification is faster. Where they do not, monitoring setup becomes part of the one-time work. Ask the quote to state which metrics, alerts and dashboards are assumed to exist and which will be built.
Rehearsal network
A rehearsal on a copy of the network shows how the genesis change, restarts and block selection behave with your own node set and tooling. It adds one-time cost for building and tearing down the copy, but it reduces the risk of a fork on the live chain. Ask whether the scope includes a rehearsal, who hosts it, and how its results are signed off before the production window is booked.
Fork, quorum and verification risks to prevent before cutover
What happens if a node is still on the old genesis at the migration block?
That node forks off the chain. According to the Besu migration documentation, any node still running the old genesis at the migration block will diverge from the network that has switched to QBFT. The prevention step is to inventory every validator and non-validator node before the cutover and confirm that each one has the updated genesis file, with the qbft.startBlock value and the QBFT settings, staged on disk before any restart is scheduled. Use a checksum comparison across all nodes so that one stale file is caught before the migration block, not after. Confirm the exact behavior and recovery steps for your Besu version in a rehearsal environment.
Why does restarting too many validators at once stall a Besu network?
Consensus needs a quorum of validators to produce and finalize blocks, and the Besu migration documentation warns that losing more than one third of validators during restarts stalls the network. Restarting validators one at a time keeps the remaining set above that threshold while each node comes back on the new configuration. Plan the restart order, confirm each validator has rejoined and is peering before starting the next, and keep a written rollback point if a node fails to return. Count validators against the fault tolerance of your own validator set, and rehearse the full sequence so the timing of each restart is measured, not guessed.
Why can a migration block set too close to the chain head be rejected?
The Besu documentation says the qbft.startBlock value must be greater than 0 and greater than the chain head at the moment each node restarts. If the chosen block is already behind or at the head when a node restarts, the node will not accept the configuration as intended. Choose a migration block with enough headroom ahead of the current head to allow the rolling restart to finish, and recheck the head immediately before each restart window. Because the block height moves continuously, the margin should be decided in the rehearsal and confirmed against live block numbers on the day of the cutover.
How do mismatched permissions files cause problems during the switch?
Besu enforces node permissioning through a local permissions configuration file, and each node decides which peers it will connect to based on that file. If validators or peers carry different allowlists after the restart, some nodes may refuse connections that others expect, which can split peering and slow or block block propagation. Keep the permissions files under version control, compare their checksums across all nodes before the cutover, and apply the same change set everywhere in one controlled batch. Confirm the peer counts and connection state of each node after the restart before declaring the switch complete.
How should the validator set be verified after the QBFT switch?
Verify it directly from the chain and from every node rather than assuming the restart succeeded. Confirm that each validator reports the expected validator set at the current head, that all nodes agree on the same block hashes at recent heights, and that new blocks are being produced at the QBFT parameters you configured. The Besu documentation notes that the existing extraData stays valid because Besu reads the validator set from block headers, so the check should compare headers across nodes. Record the results as evidence for the change, and repeat the checks after the network has produced a meaningful number of blocks.
What should a team confirm about mixed IBFT 2.0 and QBFT protocol support during the transition?
The Besu migration documentation says nodes register both IBFT 2.0 and QBFT wire protocols during the transition, which allows a rolling restart rather than a single coordinated stop. Teams should confirm in a rehearsal that every node version in the network supports this dual registration, and that no older build is left running that only speaks one protocol. Check the release you run against the current Besu release notes before scheduling, because support for older behavior can change between releases. Treat any node on an unexpected version as a blocker until it is upgraded or explicitly excluded from the window.
How do you rehearse the cutover so these risks are caught before production?
Build a rehearsal network that mirrors the production validator count, genesis, permissions files, node versions and restart order, then run the full sequence end to end. Include deliberate failure tests such as a node left on the old genesis, a restart outside the quorum limit, and a migration block placed too close to the head, and record what the network does in each case. Use the results to write the runbook, the go or no-go criteria and the rollback steps. Any behavior you cannot reproduce in rehearsal should be treated as unknown and confirmed with the Besu documentation or the maintainers before the production window.
What changes for operators after the switch
Once the chain runs QBFT, the most important day-two change is that the genesis and node configuration files become a controlled record of consensus behavior. Keep the QBFT qbft section of each node's genesis, the migration block height, and any blockperiodseconds and timeout values under change control, with a named owner and a reviewed diff for every edit. The Besu documentation notes that QBFT parameters such as blockperiodseconds can differ from the IBFT 2.0 values, so the block period is a setting to confirm explicitly rather than assume it carried over. Record the values each validator is actually running, because a node that drifts from the agreed file is the most likely source of a later fork.
Your monitoring should change as well. Add dashboards or alerts for the QBFT consensus messages and round behavior your Besu metrics expose, and compare validator block production and round changes against the pre-migration baseline for several days. Confirm the exact metric names in the Besu metrics documentation for your release, since the supplied sources do not list them here. Also plan for the cadence of Besu releases, which roll monthly. Each new release needs a documented check that its consensus behavior, configuration keys and RPC surface still match your genesis and runbooks, and a test on a non-production network before any validator is upgraded.
Later validator set changes also work differently from the IBFT 2.0 period. Adding or removing validators is a governance decision that must be coordinated across every organization in the consortium, and it needs a rehearsed procedure that keeps quorum through each step. Confirm with your Besu version and the Besu migration documentation which validator-management method your network will use going forward, and write that procedure into the runbook before the first change request arrives.
How DeployOpen scopes and delivers a Besu consensus migration
DeployOpen plans, implements and hardens self-hosted open-source platforms inside your own infrastructure, and that includes running a live IBFT 2.0 to QBFT cutover on a permissioned Besu network. We start from a written scope, rehearse the change on a copy of your network, and hand over the runbook and evidence your operators need to run it again.
How we scope
- Inventory every validator, bootnode and RPC node, with its Besu version, genesis file and host owner.
- Confirm the migration block, which must sit above the current chain head at restart time, with your change window.
- Agree in writing which consensus parameters change, such as block period, and which stay the same.
- Record who approves the change, who holds each node, and how a rollback decision is made.
How we build
- Rehearse the full cutover on a non-production copy of the network before touching validators.
- Prepare the QBFT genesis changes and confirm every node file is updated to the same migration block.
- Script a rolling restart plan that takes validators down one at a time and checks quorum before each step.
- Take and verify node data backups before any Besu upgrade step, since upgraded databases may not open on older versions.
How we hand over
- Deliver the tested runbook, genesis diff and restart order used in rehearsal and production.
- Document the verification checks that confirm all nodes share one chain, one validator set and one consensus mode.
- Provide a rollback procedure and a record of the backups it depends on, written for your operators.
- Walk your platform and security teams through the handover and the monitoring signals to watch afterward.
How we support
- Fixed-scope engagements close with a written acceptance step tied to the verification checks agreed at the start.
- Post-cutover support, Besu release upgrades and follow-up testing are available as a retainer.
- Monitoring dashboards and alerts for block production, peer counts and validator availability can be included in the scope.
- Confirm with us in the quote which of these items, and which vendor or standards references, your environment requires.
