What a Besu migration involves
This page covers moving an existing private Besu network onto a current release. It does not cover a new build. Three removals drive most of these projects. Besu 25.6.0 removed the Tessera privacy feature and onchain permissioning. Besu 25.7.0 removed the EEA and PRIV privacy RPC API groups. Besu 26.4.0 removed Clique consensus, so pure Clique networks can no longer start or produce blocks. A network that depends on any of these features needs a replacement design before it can move forward.
The short answer depends on two questions. Teams with in-house Besu skills and no removed features in use can often plan the move themselves, using the release notes and a staging environment. Teams that must replace privacy or permissioning behavior, or that run on Clique, usually benefit from a partner's review of the design before cutover, because those changes alter how transactions, participants and validators are governed.
Start with an inventory. Check whether any node still uses Tessera, whether permissioning is enforced through smart contracts, whether client applications call EEA or PRIV methods, and whether the genesis file and consensus settings still specify Clique. Ask the application owners and any vendors to confirm each item in writing, since a missed dependency usually surfaces during cutover.
Where a removed feature must continue, the Besu maintainers point to plugins or community forks. That path changes the support model, because your team then carries the code across future releases. Ask any prospective partner which parts of the replacement design they would own after go-live, and who would maintain them.
What the work includes
Each package ends in a document, configuration or tested procedure that your team keeps after the engagement. The packages run in order, and each one depends on the decisions recorded in the one before it.
Current network inventory
Record the running network before anything changes: Besu and JDK versions, the genesis file, consensus type, permissioning files, privacy dependencies such as Tessera, and every application that calls node RPC endpoints. The output is a dated inventory document. Check it against the live nodes, because files on disk often differ from what is actually running.
Target network design
Define the target network on a current Besu release, including the validator set, node roles, key custody, JSON-RPC access and the JDK version that current releases require. Confirm the consensus choice between QBFT and IBFT 2.0 against the Besu documentation before design starts. The deliverable is an architecture document and a configuration set reviewed by your security team.
Replacement for removed features
Each removed feature needs a written replacement or retirement decision. Tessera privacy and onchain permissioning were removed in 25.6.0, the EEA and PRIV RPC groups in 25.7.0, and Clique in 26.4.0. For each one, the plan names the replacement, such as local permissioning files, a plugin or a retired business flow, and records who approved it.
Data and state migration
Plan how chain data and state reach the new network, and how the original data stays recoverable. Current Besu upgrades the Bonsai database automatically on first start, and older versions cannot open the upgraded database. The procedure therefore needs a verified backup taken before any node is upgraded, plus a restore test of that backup.
Validator and node rollout
Sequence the rollout across validators, RPC nodes and bootnodes so enough validators stay online for consensus at every step. Node keys, peer lists and static configuration change per node under a written checklist. Rehearse each step on a staging network first, and confirm the fault tolerance of the validator set before each change.
Cutover, rollback and handover
Define the cutover window, the go and no-go checks, and the rollback trigger and steps, including restoring the pre-upgrade backup. Handover delivers runbooks, configuration repositories, alert definitions and recovery procedures to your operators. They run a rehearsal of rollback before go-live so the procedure is proven by your own team.
What drives cost and duration
This table lists the factors that change how much work a Besu migration takes, why each one adds effort, and what the team can do early to reduce it.
| Driver | Why it raises effort | What reduces it |
|---|---|---|
| Tessera privacy and EEA or PRIV calls | Private transactions need a new design, and every caller of EEA or PRIV methods must change after the removals in 25.6.0 and 25.7.0. | Decide the privacy replacement early and retire unused EEA or PRIV calls before cutover. |
| Onchain permissioning | Rules held in smart contracts must be exported and rewritten as local node and account permissions files. | Inventory every active rule and test each one against the local permissions configuration before cutover. |
| Clique consensus | Pure Clique networks cannot start or produce blocks after 26.4.0, so the chain's consensus must change, which is a design decision rather than a version bump. | Confirm the target consensus and cutover path with the maintainers' guidance before touching production nodes. |
| Validators and operators | Each validator needs its own key, host and an operator who can act during upgrades and incidents, so coordination grows with the set. | Agree the validator set, operator roles and upgrade windows before the build starts. |
| RPC consumers and integrations | Each application, exchange or custom integration calling the node API may break when methods are removed or authentication changes. | Log which methods each consumer calls, then update or retire them and test before cutover. |
| Chain data size and age | Bonsai auto-upgrades its database on first start and older versions cannot open it, so a rollback depends on a backup taken first. | Measure data size and sync time on a copy of the chain, and verify backups before each upgrade. |
| Number of environments | Each environment, such as development, test, staging and production, repeats the migration and needs its own validation. | Use one repeatable deployment definition and promote the same steps through each environment. |
| Key custody model | Node keys are not encrypted by default, and hardware-backed storage through a security module plugin adds integration and testing work. | Choose the custody model before cutover and confirm that the plugin supports your hardware. |
| Compliance evidence required | Assessors expect records of permissioning changes, key handling and cutover approvals, which must be captured while the work happens. | Define evidence requirements at scoping and collect them as each migration step runs. |
Project phases and outputs
The sequence moves a private network from its current Besu or legacy setup to a supported release with each decision, test and cutover step recorded before production changes.
Confirm discovery and inventory scope
The team inventories every node, validator, genesis file, database version, privacy dependency, permissioning rule, Clique or onchain permissioning setting, RPC consumer and key custody arrangement. The output is an inventory report that the consortium signs off, listing each item as keep, replace or retire.
Record target design and feature replacements
For each removed feature, such as Tessera privacy, onchain permissioning, Clique consensus or the EEA and PRIV RPC groups, the team records a replacement decision. Options include local permissioning files, application-layer privacy, a plugin, or a community fork, each with trade-offs the consortium must accept. The output is a decision record with a target Besu release and JDK version.
Rehearse on a test network
The current configuration is rebuilt on a test network and migrated to the target release. Upgrade steps, database conversion, validator restarts and rollback are run and logged, including the backup restore path. The output is a rehearsal log with every failure, its fix and a rerun result.
Plan data and genesis strategy
The team decides whether chain history is carried forward, whether a new genesis is required, and how state and node databases are preserved. Because the Bonsai database upgrades on first start and older versions cannot open it, backup and restore procedures are written and tested. The output is a runbook section covering data, genesis and backup verification.
Roll out validators and nodes
Validators, RPC nodes and bootnodes are sequenced for the rolling upgrade, with the validator set kept at a fault-tolerant level throughout. Key custody, node permissioning files and JSON-RPC authentication are checked on each node. The output is a validator rollout plan naming the order, owners and health checks for each node.
Execute production cutover with rollback
The production change follows the rehearsed runbook against a cutover checklist, with a go or no-go checkpoint, a verified backup and a defined rollback point. Monitoring and block production are confirmed before the change is closed. The output is a signed cutover checklist and a record of the final state of each node.
Hold a post-cutover review
After the network runs stably, the team reviews incidents, monitoring gaps, documentation and open decisions, and updates the runbook for future monthly releases. The output is a review report with assigned follow-up items. Ask the partner to confirm in writing whether this review and any later support are inside the agreed scope and schedule.
What to keep in-house and what to outsource
This table shows which migration work a consortium usually keeps, which it often outsources, and the Besu, Java, Linux, Prometheus and design skills each part requires.
| Work | Usually sits with | Skill needed |
|---|---|---|
| Business rules for who may join | In-house consortium | Consortium governance and legal design, plus enough Besu permissioning knowledge to check the rules against node and account permissions |
| Governance votes on validators and network rules | In-house consortium | Consortium governance and an understanding of QBFT validator voting and how votes change the validator set |
| Sign-off on data retention | In-house consortium, with legal and compliance review | Records and data protection policy, and knowledge of what the node database keeps and how long it lives |
| Version and feature audit of the current network | Outsourced, with in-house review of findings | Besu operations, reading release notes for removed features, and Java and JDK 25 familiarity for build and runtime checks |
| Replacement design for Tessera privacy, onchain permissioning or Clique | Outsourced design, with in-house approval of the target model | Smart-contract and privacy design knowledge, Besu plugin API familiarity, and Besu operations for the new consensus or permissioning setup |
| Rehearsal runs on a copy of the network | Outsourced execution, with in-house operators observing | Linux administration, Besu operations, and Prometheus to confirm peer count, block production and sync status during each run |
| Runbook writing for cutover and rollback | Shared, with in-house operators owning the final version | Besu operations and Linux administration, including database backup and restore steps that precede any version upgrade |
What goes wrong and how to prevent it
Five risks are specific to moving a private network onto current Besu. Each card names the prevention step and the test that shows the step worked.
No rollback after Bonsai upgrade
Besu 26.10.0 auto-upgrades the Bonsai database on first start, and older Besu versions cannot open the upgraded data. Stop the node, copy the full data directory, and keep the previous binary and JDK available. Test by starting the old version against a copy of the backup on a separate host, then confirm it boots before the upgraded node goes live.
Private data stranded without Tessera
Besu 25.6.0 removed the Tessera privacy feature, so private transaction payloads held through Tessera need a documented path forward. Inventory every private contract and participant, then agree with each party whether to export payloads, re-issue state or retire the contract. Test by reconciling a sample of private contract state on a test network against the exported records before cutover.
Applications still calling EEA and PRIV
Besu 25.7.0 removed the EEA and PRIV privacy RPC API groups. Services, middleware and scripts that still call them can fail after the upgrade, often on paths that run rarely, such as month-end reporting or admin tasks. Log the JSON-RPC methods each service calls over a representative period, map each one to its replacement, and update clients before the node moves. Test by running the integration suite against the upgraded test node and failing the build on any method-not-found error.
Validators on different versions
During a rolling cutover, validators run different Besu releases for a period, and the team must confirm in each release's notes whether that mix is supported. Write a version matrix that lists the current and target release for every validator, and freeze other changes for the window. Test by reproducing the same version mix on the test network and confirming blocks keep producing and finality holds through each stop and restart.
Clique genesis and signer assumptions
Besu 26.4.0 removed Clique consensus, so a pure Clique network can no longer start or produce blocks. Genesis files, signer lists and tooling that assume Clique fields or signer voting need rework before any node is upgraded, and the consortium must agree the consensus path in writing. Test by rebuilding the genesis on a test network with the agreed consensus, checking that every validator address and signer count matches the governance record, and confirming the chain produces blocks.
How the work differs by starting point
Besu 26.4.0 removed Clique consensus, so a pure Clique network can no longer start or produce blocks on current releases. The migration starts with a consensus decision, and the upgrade follows from it.
- Consensus target first: choose QBFT or IBFT 2.0, the proof-of-authority options Besu supports for private networks, and confirm the validator set and fault tolerance before changing any node.
- Chain continuity: decide whether existing history carries forward or a new genesis starts from a agreed state. Test the approach on a copy of the chain before deciding.
- Signer mapping: confirm which current Clique signers become validators and how each one's keys move to the new set.
- Evidence needed: the current genesis file, node configuration files and a record of recent signer activity.
Besu 25.6.0 removed Tessera privacy and onchain permissioning, and 25.7.0 removed the EEA and PRIV privacy RPC groups. Networks that depended on these features must decide what replaces them before any version change.
- Feature inventory first: list which private transactions, participant restrictions and account rules the business still needs, and which applications call the removed RPC groups.
- Replacement design: the Besu documentation describes local permissioning through node and account permissions files. Confirm whether that covers each rule, or whether a plugin or a fork you maintain is needed.
- Governance change: onchain permissioning contracts held the rules in one place. Assign who owns the replacement rules and how changes are approved.
- Evidence needed: the permissioning contract source and state, Tessera configuration, the participant register and application code that uses private transaction calls.
A network on an older release needs more than one upgrade step. Each step changes behavior, and some changes cannot be reversed without a backup.
- Target release: pick the release to land on. The GitHub releases page lists 26.7.0 (July 13, 2026), 26.8.0 (August 19, 2026), 26.9.0 (September 25, 2026) and 26.10.0 (October 16, 2026), and each release has its own notes.
- Irreversible database change: the Besu 26.10.0 release notes say the Bonsai database upgrades automatically on first start, and older versions cannot open it. Take and test a backup before each node starts a newer version.
- Runtime requirement: the 26.6.0 release notes state that Besu requires JDK 25, so confirm the JDK on every host or image early.
- Evidence needed: the running version on each node, a list of removed options from every release note in the path and plugin compatibility records.
On Kubernetes, the platform adds decisions about node identity, storage and secrets. The Besu logic stays the same, but the rollout and recovery paths change.
- Storage and identity: decide how each validator keeps its data volume and node key across pod restarts, and confirm that volumes survive a redeploy before any upgrade.
- Rollout order: plan validator restarts one at a time so the network keeps its fault tolerance, and confirm the chart or operator pins the image version you intend to run.
- Secret handling: node keys and RPC credentials should come from your secret store, not from image layers or plain manifests.
- Evidence needed: the cluster version, Helm values or manifests, storage class details, volume snapshot support and the monitoring setup, including the Besu metrics endpoint when metrics are enabled.
In an air-gapped or regulated environment, the plan must show how software, keys and data move in and out of the network under your controls.
- Software intake: plan an offline mirror of Besu, JDK 25 and any plugins, and record the checksum and approval for each artifact.
- Key custody: the Besu documentation says the local node private key file is not encrypted. Decide whether a hardware-backed security module plugin, such as the Besu HSM plugin enabled with the --security-module option, is required.
- RPC exposure: Besu does not terminate HTTPS natively, so plan TLS and authentication at a layer you control before any RPC access is opened.
- Evidence needed: change approvals for each release, network diagrams, backup and restore records and access logs. Confirm with your auditor which evidence they expect, since DeployOpen prepares evidence but does not issue assessments.
What you need to provide
Start by sending the inputs that define the current network, because the migration plan cannot be sized without them. Provide access to every existing node, the genesis file, and the consensus settings it contains. Provide the permissioning configuration files for node and account permissioning, plus an inventory of every key file. Record where each node private key file sits, who can read it, and how it is backed up. The local node private key file is not encrypted by default, so this inventory also shows whether any key already sits behind hardware-backed storage or an HSM security module plugin.
Next, list the applications that submit transactions or read data from the network, and the JSON-RPC methods each one calls. The privacy API groups EEA and PRIV were removed in Besu 25.7.0, so any caller that depends on them will break, and this list drives the feature gap review. For privacy data, identify which private transaction payloads must survive cutover, the system that holds them today, where they are stored, and the retention period your policy requires. Name who may restore or export that data.
Name an accountable owner for each validator, with a deputy who can act during the change window. Agree the change window in writing with the business owners of the network, including how much time is available for rollback if a cutover fails. Provide a rehearsal environment that matches the current topology closely enough to test upgrades, restores and the database step. Bonsai upgrades automatically on first start and older versions cannot open the upgraded database, so rehearsal is the only safe place to learn that behavior. Name one decision maker who can choose between a plugin, a fork, or retiring each feature that depended on removed functions.
Confirm the target Besu version against the official releases list when the project starts. Besu ships roughly monthly, so the target can change during planning. Check the release notes for the JDK version the target requires, and make sure a verified backup exists before any upgrade step. Record the agreed version, the release notes reviewed, and the rollout order in the written scope so that everyone works from the same baseline.
Frequently asked questions
Can our own team migrate a Besu network without a partner?
Yes, if your team has the skills and time to plan it, but a migration is more than an upgrade. You need to check which removed features the network depends on, such as Tessera privacy, onchain permissioning or Clique, and decide how each one is replaced. Your team also needs to rehearse data migration, validator cutover and rollback in a non-production environment first. Teams that already run Besu validators and have a tested change process are in the strongest position to do this alone. Teams without that experience often bring in a partner for the design decisions.
What does a Besu migration cost and what drives the price?
The price depends on the written scope, and DeployOpen provides a quote once that scope is agreed. The main cost drivers are the number of nodes and validators, the number of environments, how much network data must be moved and verified, whether removed features need a plugin or fork, and how key custody and monitoring change. Most migration work is one-time, covering planning, build and cutover. Recurring costs sit in the infrastructure you run and the people who operate validators after go-live. Ask for the work broken down by phase, the effort assumptions and the exclusions.
How long does a Besu migration take to complete?
No duration is given here, because the timeline depends on the scope and your environment. The main drivers are the number of validators and environments, the removed features the network relies on, the size and state of the existing chain data, and the approval and maintenance windows your organization allows. Replacing Tessera privacy or onchain permissioning adds design and testing work. A cutover that must keep the network running also needs more rehearsal. Ask for a phased schedule in the written scope, with your own approval and test dates listed as dependencies.
Can we keep Tessera privacy after upgrading Besu?
Current Besu releases do not include Tessera privacy, so this requires a decision before the migration design is set. Besu 25.6.0 removed the Tessera privacy feature and onchain permissioning, and 25.7.0 removed the EEA and PRIV privacy RPC API groups. The maintainers suggest that teams still needing these features use a plugin or a community fork. Either option creates ongoing maintenance against each future Besu release. Confirm the options with the maintainers and with your legal and risk owners before choosing a replacement path.
What do we need to provide for a Besu migration project?
The project needs an inventory of your current network, including chain configuration, node versions and access to the existing nodes and their configuration files. Provide the list of validators, operators, RPC consumers and applications that depend on the network. Share the permissioning rules and any Tessera or onchain permissioning contracts in use. You also need a non-production environment for rehearsal, details of key custody, monitoring and backup arrangements, and named owners who can approve changes and maintenance windows. Confirm the full list in the written scope before work starts.
Can we roll back Besu after an upgrade during migration?
Rollback is possible only if you take a backup before the upgrade. The Besu 26.10.0 release notes state that the Bonsai database upgrades automatically on first start, and older Besu versions cannot open an upgraded database. A backup taken before the upgrade is therefore your rollback path, and it should be verified by restoring it in a test environment. Plan the backup window, the storage for the copy and a change record showing which version each node runs. Treat the upgrade as irreversible for the live database unless that backup exists.
How DeployOpen delivers this service
DeployOpen plans and carries out Hyperledger Besu migrations inside infrastructure you control, starting from an inventory of what your private network actually depends on today. The work is scoped in writing before it starts, so the features being removed, the data to move and the cutover steps are agreed before any node is touched.
How we scope
- Inventory the current network: Besu or other client versions, genesis settings, consensus type, and any Tessera, onchain permissioning or Clique dependencies.
- Record the target Besu release and JDK version, and confirm which removed features need replacing, retiring or moving to plugins or forks.
- Agree the written scope covering environments, validator and RPC nodes, data migration, cutover window, rollback points and acceptance tests before work starts.
How we build
- Stand up parallel target nodes and rehearse the data migration in a staging network that mirrors your validator set and permissioning rules.
- Rebuild permissioning as node and account permissions files, and move JSON-RPC access controls and metrics endpoints onto your own standards.
- Take and verify backups of node data and keys before the Bonsai database upgrade, then test the rollback path on a copy of the data.
How we hand over
- Deliver runbooks for validator rolling upgrades, cutover steps, rollback, key handling and monitoring checks used during and after migration.
- Document the final configuration, deviations from the original network, and any custom plugin code, with ownership and release-tracking notes for your team.
- Run agreed acceptance tests against the migrated network and record results so your team can repeat them at the next Besu release.
How we support
- Support after cutover can be arranged as a retainer covering monitoring review, release reading and planned upgrades of the Besu network.
- Retainers can include reviewing monthly Besu releases for breaking changes, JDK requirements and database upgrade notes before your team schedules them.
- Confirm during scoping which post-migration tasks your internal team keeps and which a retainer covers, since this shapes ongoing effort.
