Why custom Besu plugins need their own upgrade plan
Plugin compatibility is a separate workstream from the node upgrade, and it needs its own owner, test set and sign-off. If your permissioned network runs custom plugins for HSM signing, transaction selection or event consumers, a successful move to a new Besu release does not prove those plugins still work. The node can start cleanly while a plugin quietly depends on an API that is being reorganized or deprecated. Treat each Besu release as two changes: the node binary and the plugin build that loads into it. Besu is reorganizing its plugin API into per-feature modules. The besu-plugin-api artifact re-exports every module, so existing plugins compile unchanged until a future breaking release. That protection is a window, not a guarantee. The supported path is to track deprecations now, while the old types still compile, and move your plugins onto the new module locations before the breaking release arrives. Plan against the 26.x calendar cadence: the GitHub releases page lists 26.7.0, 26.8.0, 26.9.0 and 26.10.0 between July and October 2026, so each release needs a short compatibility review before it reaches production. Confirm the breaking release version with the Besu maintainers rather than assuming a date. Start by inventorying every plugin, its Besu version and every Besu service class it imports. Read the deprecation notes in each release on the Besu releases page and map them to your code. Decide who owns each plugin build, which Besu versions each build is pinned to, and what evidence you need before a plugin version is approved. Ask your plugin developers or vendor to state in writing which Besu versions their build has been tested against.
Which plugin-facing changes affect your build
This table compares each plugin-facing change in the Besu release line with what it does to a custom plugin build and what your team should do now. Read each row against the plugin's imports, the services it calls and the Besu version it is pinned to. The main takeaway is that most changes need watching and testing now, while the removal of BesuEvents and the deprecated mining and transaction selector methods need code work before the breaking release.
| Change | Impact on your plugin | Action needed |
|---|---|---|
| Plugin API reorganized into feature modules | Existing plugins compile unchanged, because besu-plugin-api re-exports every module until a future breaking release | Watch the breaking release notes and rebuild against each Besu version you test |
| BesuEvents deprecated | Scheduled for removal at the breaking release, so plugins that subscribe through it will stop compiling then | Find every BesuEvents subscription and plan a move to the event families on the new services |
| Event families moving to BlockchainService, TransactionPoolService and SynchronizationService | Replacement location for the events that BesuEvents carries today | Map each event your plugin consumes to its new service and test the handlers |
| MiningService deprecated for removal | Plugins that call MiningService may break at removal, and the release notes are the authority on timing | Search for MiningService usage and confirm the replacement in the current release notes |
| PluginTransactionSelectorFactory.create(SelectorsStateManager) deprecated for removal | Transaction selector plugins that use this factory method need updating before it is removed | Review selector factories and confirm the supported replacement before upgrading |
| JDK 25 requirement since 26.6.0 | Plugin builds must target the runtime Besu now requires, or the node will not run with the plugin | Rebuild plugin artifacts with JDK 25 and include the JDK in your pipeline and images |
| Clique removal in 26.4.0 | Plugins that assume Clique networks will not work because Besu can no longer start or produce blocks on pure Clique networks | Confirm your network is not pure Clique and retire any Clique-specific plugin logic |
| Tessera privacy and onchain permissioning removed in 25.6.0, EEA and PRIV RPC removed in 25.7.0 | Plugins that depended on these features or their RPC groups stop working on current releases | If your plugin relied on them, plan a replacement or a community fork before upgrading past these versions |
How a plugin breaks when the API moves
A plugin can fail in two different ways, and the difference decides when you find out. A compile-time break happens when your build stops because a class, method or package it imports has moved or changed signature. A runtime break is quieter: the plugin builds, the node starts, and the failure appears only when the code path that calls the changed service runs. Besu's plugin API is being reorganized into per-feature modules, and the besu-plugin-api artifact re-exports every module so existing plugins compile unchanged until a future breaking release. That protection covers the build step only. It tells you nothing about whether behavior at runtime is still the same, so a green build is not proof of compatibility.
Deprecation is where runtime surprises usually start. BesuEvents is deprecated and will be removed at the breaking release, and its event families move to BlockchainService, TransactionPoolService and SynchronizationService. A plugin that subscribes through BesuEvents can therefore load and run normally on today's release, then fail to start or stop receiving events after the breaking release removes the class. The same pattern applies to MiningService and the PluginTransactionSelectorFactory.create(SelectorsStateManager) method, which are deprecated for removal. Check each deprecation warning in your build logs, map every one to its replacement, and confirm the removal version in the release notes for your target Besu version, since the breaking release date is not supplied here.
Removed features are the most damaging case. Besu has already removed Tessera privacy and onchain permissioning in 25.6.0, the EEA and PRIV privacy RPC API groups in 25.7.0, and Clique consensus in 26.4.0. A plugin or node configuration that still depends on one of these can fail at startup, or stop block production on a network that relied on it, because the code it calls no longer exists. Inventory every plugin against the removal list in the release notes, and rehearse startup on a staging node built from the target version. Confirm exact behavior for each removal in the GitHub release notes for your target version rather than relying on a summary.
What to inventory and back up before touching plugins
Plugin breakage on a Besu upgrade is usually found too late, after a node has already been upgraded and its database changed. The four items below set up the evidence and recovery path you need before any plugin or node binary changes, so a failed compatibility check stays a test result instead of an outage.
Plugin inventory by API surface
List every custom plugin, its owner, the Besu version it was built against, and each Besu API package it imports. For each plugin, record which services it calls, such as BlockchainService, TransactionPoolService, SynchronizationService, or BesuEvents. Deprecated services are the first items to review because the plugin API is being reorganized into feature modules, and BesuEvents is slated for removal at a future breaking release. Flag every plugin that calls MiningService or the PluginTransactionSelectorFactory.create(SelectorsStateManager) method.
**Full node backups before each upgrade**
Take a backup of every node's data directory before any Besu binary changes. The Bonsai database upgrades automatically on first start, and older Besu versions cannot open an upgraded database, so a plugin problem found after restart may leave you with no working downgrade path. Confirm you can restore the backup on a spare host and that the restored node syncs and reaches the same chain head. Record the backup time and the Besu version in your change record.
Pinned test environment matching production
Build a staging network that uses the same Besu version, the same JDK, and the same plugin jars as production. Since Besu 26.6.0 requires JDK 25 to build and run, a test that uses a different JDK can pass while production fails. Pin each image or host package version so a test result maps to exactly one combination of Besu, JDK, and plugin build. Run plugin startup, RPC calls that touch plugin services, and block production in this environment before any production node is touched.
Node private key and HSM configuration
The local node private key file is not encrypted, so anyone who can read the data directory can copy the node identity. Before upgrading, confirm where the key lives and whether the HSM plugin is configured with the --security-module option. Check that the plugin version pairs with the target Besu version and that the HSM connection and credentials still work on the upgraded node. Include the key file and HSM configuration in your backup scope, and store the backup with the same access controls as the key.
How to move a plugin to a new Besu version
This sequence takes a custom Besu plugin from its current build to a tested, pinned version on the target Besu release, with a rollback point at every node. It keeps the permissioning and HSM setup under test so the upgrade does not change how the network behaves.
Inventory plugins and their Besu API usage
The plugin owner lists every custom plugin, its source repository, the Besu version it was last built against, and the Besu API packages and services it imports. Map each import to the feature module it belongs to, so you can see which parts of the plugin API the target release reorganizes. Record the security module plugin, such as the HSM plugin, as its own line item because it is tied to the signing path. The step is done when every plugin has an owner, a current Besu version and a complete list of API touchpoints in a shared register.
Flag deprecated calls in each plugin
Search each plugin for the calls Besu has marked for removal: BesuEvents, MiningService, and the PluginTransactionSelectorFactory.create(SelectorsStateManager) method. For BesuEvents, identify which event families the plugin consumes so you can move them to BlockchainService, TransactionPoolService or SynchronizationService, where the release notes say they are available. Mark each finding with the replacement you plan to use. The step is done when every deprecated call has a documented replacement or a recorded decision to defer it, and a reviewer has signed off on the list.
Build against the target Besu version and JDK
The build engineer updates the plugin's dependencies to the target Besu release and compiles with the JDK that release requires. Confirm the JDK version in the target release notes, since the 26.x line requires JDK 25, and make sure the build image and CI runners use the same runtime. Fix compile errors, and treat any warning about a deprecated API as a task to resolve rather than a message to ignore. The step is done when the plugin builds cleanly from a tagged commit and produces a versioned artifact with a recorded build log.
Test the plugin on a staging network
Deploy the new artifact to a staging network that matches production in its permissioning configuration, its node permissions and account permissions, and its HSM or security module setup. Run the plugin's functional tests, then check that transactions, permissioning decisions and key operations behave as they did on the previous version. Include a node restart and a check that the plugin loads without errors in the logs. The step is done when the test report shows no regressions and the staging configuration is recorded alongside the results.
Pin the plugin to the tested Besu version
Record the exact Besu version and plugin version in the deployment artifact, such as the container image tag, the Ansible variables or the Helm values, so that no node can start with an unpinned or mismatched pair. Store the checksum of the plugin jar alongside the Besu version and link it to the staging test report. Ask the platform team to block deployments where the two versions do not match. The step is done when the pinned pair deploys from a single change and the artifact records both versions and the test evidence.
Take a backup before any database format change
Before any node starts the new version, check the release notes for changes to the database format. Where the release changes the format, take a verified backup of each node's data and store it outside the node, because older Besu versions cannot open an upgraded database. Confirm the backup can be restored on a test host. The step is done when each node has a backup with a restore check recorded, or when the release notes confirm no format change applies.
Roll out node by node with rollback points
Upgrade one node at a time, starting with a non-validator node where your topology allows it. After each node restarts, confirm it peers with the network, produces or imports blocks as expected, and loads the plugin without errors. Keep the previous image and the backup in place until the next step is approved, and record a rollback point after each node. The step is done when every node runs the pinned pair, the network has stayed live through the sequence, and the change record lists each node with its checks and rollback point.
Pinning strategies for the HSM plugin and custom plugins
This option fixes one Besu version and one plugin build together and changes neither until a tested pair is ready. It gives the most control over what runs in production and makes change records simple, because every node reports the same known combination. The cost is that every move to a newer Besu release, including security fixes, becomes a deliberate project that you own.
- Control: Production runs a single, documented combination of Besu and plugin builds.
- Upgrade effort: Each new Besu version needs a compatibility check of the plugin before rollout, and that check repeats for every move.
- Security lag risk: Staying on an old Besu version for long periods can leave fixes unapplied, so the plan needs a defined review cadence.
- Support ownership: You confirm with the plugin vendor or your own team which Besu versions a given plugin build supports.
- Artifact control: Keep the exact plugin artifacts and checksums in your own repository so a rebuild does not drift.
Before adopting this option, ask the HSM vendor which Besu versions its plugin build has been tested against and how quickly they publish updates.
This option keeps the plugin on a defined release train, such as one Besu calendar release at a time, and runs a fixed test suite against each release before promotion. It suits teams that follow Besu's roughly monthly cadence and want predictable upgrades rather than occasional large jumps. Control stays with you, but the work becomes a recurring routine that must be staffed continuously.
- Control: Promotion happens only after the candidate Besu release passes your plugin and node tests in staging.
- Upgrade effort: Effort recurs on every calendar release, so the test suite and staging capacity must be sized for that rhythm.
- Early signal: Reviewing release notes for each version lets you catch removed or deprecated plugin services before they reach production.
- Support ownership: Your team owns the test results and the decision to promote, even when the plugin itself comes from a vendor.
- Skipped releases: Decide in advance whether you may skip a release, and record why.
Ask your plugin provider whether they test against each Besu release and what they commit to when a release breaks an interface.
Besu's maintainers have suggested plugins or community forks for teams that still need the privacy and permissioning features removed from Besu, including Tessera privacy and onchain permissioning. A fork gives you the most freedom to keep those features and to change plugin code, but it moves maintenance of the Besu codebase, or at least of the plugin layer, into your organization. Treat this option as a long-term engineering commitment rather than a shortcut.
- Control: You decide which features stay, which upstream changes you merge, and when.
- Upgrade effort: Each upstream Besu release must be reviewed, merged and tested against your changes, which is continuous work.
- Security ownership: Your team is responsible for patching vulnerabilities in the fork and for tracking upstream advisories.
- Skills: Plan for Java, JDK 25 build tooling and Besu internals knowledge held by named people, not one contractor.
- Exit path: Document how you would return to upstream Besu if the fork falls behind.
Before choosing a fork, confirm who will review upstream changes each release and what happens if that person leaves.
What makes plugin upgrades take longer
This table lists the factors that lengthen a custom plugin upgrade on a permissioned Besu network, what each one changes, and what to check before estimating work. Read each row as a question for your own inventory: the more rows that apply to your network, the more staging and regression testing the upgrade will need. Plugins that touch removed features or deprecated services usually dominate the effort.
| Effort driver | Why it adds effort | What to check |
|---|---|---|
| Number of plugins and services used | Each plugin must be rebuilt and retested against the target Besu version, and shared services multiply the test matrix. | Inventory every plugin, its Besu version pin, and which services it calls from the plugin API. |
| Use of deprecated services | BesuEvents is deprecated and will be removed at the breaking release. MiningService and PluginTransactionSelectorFactory.create(SelectorsStateManager) are deprecated for removal. | Search plugin code for BesuEvents, MiningService and the deprecated selector factory method, then map each use to its replacement. |
| Use of removed privacy or permissioning features | Tessera privacy, onchain permissioning and the EEA and PRIV RPC groups were removed in earlier releases, so plugins depending on them need redesign, not a version bump. | Confirm whether any plugin still relies on onchain permissioning, Tessera or EEA/PRIV calls, and which replacement is planned. |
| HSM integration and key ceremony | A security module plugin such as the Besu HSM plugin must match a tested Besu version, and key handling changes need witnessed procedures and change records. | Check the HSM plugin's tested Besu versions with its vendor, and schedule key ceremony steps around each restage. |
| JDK 25 build changes | Besu requires JDK 25 to build and run since 26.6.0, so plugin builds, images and JVM options must follow the runtime. | Confirm the plugin compiles and runs on JDK 25 in your build pipeline and container images. |
| Number of networks and nodes to restage | Every node running the plugin needs the same tested build, and mixed plugin versions across a consortium can cause divergent behavior. | List each network, node role and plugin build, and agree the restage order with every operator. |
| Size of chain data | Bonsai database upgrades run automatically on first start and older versions cannot open upgraded data, so backup and restore time grows with chain size. | Measure current data size per node and confirm restore time in a staging copy before the upgrade window. |
Questions teams ask before upgrading custom plugins
How much does it cost to upgrade custom Besu plugins?
Cost depends on how many plugins you run, how many of them touch deprecated services, and how much testing your environment requires. The main cost components are the engineering time to read the release notes, change code where needed, rebuild and retest each plugin, and the test network time to prove the node still produces and validates blocks. Those costs are largely one-time for each Besu release you adopt, but they recur with every calendar release you follow. Ask any partner for a quote built from a written list of plugins, the Besu versions in scope, and the test environments they will use. No public figure for plugin upgrade effort has been published by the Besu project, so treat any number you receive as a scoped estimate to verify.
Can our own engineers upgrade custom plugins without a partner?
Yes, if your team has Java engineers who understand the plugin API, can build against the Besu release you target, and can run a permissioned test network. The plugin API is being reorganized into per-feature modules, and besu-plugin-api re-exports every module so existing plugins compile unchanged until a future breaking release. That gives an in-house team time, but it does not remove the work: BesuEvents is deprecated and will be removed at the breaking release, and MiningService and the PluginTransactionSelectorFactory.create(SelectorsStateManager) method are deprecated for removal. Teams that lack this skill set or capacity often bring in a partner for a fixed-scope review and migration.
How long does a plugin upgrade take, and what sets the timeline?
The timeline is set by the number of plugins, the depth of any deprecated API use, the Besu release you are moving to, and how quickly you can get a test network that matches production. Plugins that only rely on stable interfaces move faster than plugins that use BesuEvents or deprecated mining and transaction selection calls. Build pipeline changes also matter: if your plugin builds must follow a new JDK, that work sits on the critical path. Your change approval cycle and the calendar of Besu releases you choose to follow will add further lead time. Ask for a written schedule with dated milestones for code changes, test cycles and the approval gate, and confirm the Besu version each milestone targets.
What do we need to provide for a plugin upgrade?
You need to supply people and environments that the work cannot run without. The main items are:
- API owners who can confirm what each plugin is supposed to do and which behaviors must be preserved
- A test network that matches your production topology, including validators, the same genesis settings and the plugins under test
- A change approval path that accepts the plugin version, the target Besu version and the test evidence
- Access to your build pipeline, container images and secrets for signing and HSM connectivity
Agree in advance who signs off each stage, since regulated operators usually need that record.
Will our existing plugin still compile after the Besu plugin API reorganization?
Probably, for the current release line, but you should confirm it by building. According to the Besu release notes, besu-plugin-api re-exports every module, so existing plugins compile unchanged until a future breaking release. The risk is not the current build but the next breaking release, and the deprecated items that will be removed at that point. Run a build of each plugin against the Besu version you plan to adopt, check for deprecation warnings, and map any use of BesuEvents to BlockchainService, TransactionPoolService or SynchronizationService. Confirm the exact release where the breaking change lands with the Besu release notes before you schedule work.
How should we handle the HSM plugin version when we upgrade Besu?
Pin the HSM plugin to a version that you have tested against a specific Besu release, and do not upgrade Besu and the HSM plugin in the same unverified step. Besu documentation says that deployments needing hardware-backed key storage can use a security module plugin such as the Besu HSM plugin with the --security-module option, so the plugin is part of your signing path. Test signing and node start-up on a non-production network with the same HSM firmware and client libraries you run in production. Record the plugin version, Besu version and HSM configuration together in your change record. Confirm the compatibility matrix with the HSM plugin provider before you move versions.
How DeployOpen scopes and delivers plugin upgrades
DeployOpen plans, builds, tests and hands over custom Besu plugin work inside your own infrastructure, starting with an inventory of every plugin and the Besu versions it must run on. Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
How we scope
- Inventory every custom plugin, its Besu API imports and the Besu versions it currently runs on
- Map each plugin dependency to the feature modules, deprecated services and HSM plugin versions it touches
- Agree in writing which Besu releases the plugins must support and which upgrade paths are in scope
How we build
- Migrate deprecated BesuEvents usage to BlockchainService, TransactionPoolService and SynchronizationService event families
- Replace deprecated MiningService and PluginTransactionSelectorFactory.create calls with supported alternatives
- Pin each plugin and the HSM plugin to tested Besu versions, with the build aligned to the required JDK
How we hand over
- Deliver a compatibility matrix listing each plugin, its pinned Besu version and its test results
- Document the upgrade procedure, rollback steps and a staging test script your team can rerun
- Train your engineers to review Besu release notes and assess plugin impact before each upgrade
How we support
- Review each new Besu release against the plugin inventory and report affected plugins before planning starts
- Offer ongoing support and upgrade work as a retainer, scoped to your plugin set and release cadence
- Confirm with your team the change records and approvals your governance process requires for each release
