Upgrades, Migration, and Interoperability
This domain tests changing a running network safely: upgrading Besu, moving from another client, and interoperating with other nodes and a consensus layer.
Core rules
- Upgrade sequence: read release notes for breaking changes such as a higher JDK, storage format changes or removed features; back up the data directory, genesis and config; stop the node cleanly; swap the binary; start; verify block height and peer count.
- Database schema upgrades are one-way. Downgrading generally requires deleting the data directory and resyncing, so plan a snapshot or fallback node.
- Besu interoperates at P2P with any client that shares the same genesis, chain ID and fork schedule. Post-merge networks additionally require a consensus client connected through the Engine API with a shared JWT.
- Migrating from another client means exporting the genesis and keys and resyncing. Databases are client-specific and cannot be copied across.
- Test upgrades on a non-production replica before touching validators, and keep validator keys available during the restart.
Worked example
You move a private network from another client to Besu. Copy the existing genesis file unchanged, create a fresh data directory, place the node key and validator key in the expected locations, start Besu with the matching config, and wait for sync. Peers connect immediately because genesis and chain ID match. Copying the old database instead produces startup errors or an unusable chain.
Traps
- Copying a database between clients or between Bonsai and Forest.
- Upgrading a validator without checking the JDK requirement first.
- Assuming a downgrade is supported after the schema has migrated.
- A fork configuration that differs subtly, such as a missing timestamp-based activation.
- Forgetting the Engine API JWT when pairing with a consensus client.