Upgrading Rollups
Coordinate software, contracts, circuits, configuration, and user communication as one controlled release.
A rollup upgrade can touch node software, contracts, proof circuits, database migrations, indexers, wallets, bridges, and governance. Treat those dependencies as one release, even when they are deployed by different teams. The OP Stack chain-operator configuration guide is an example of why genesis settings and component-specific configuration need to be reviewed as a coordinated release.
Before an upgrade, document compatibility, contract addresses, migration steps, rollback limits, pause conditions, and user impact. Rehearse the change in a representative environment with real settlement and bridge flows. For proof-based systems, prove and verify a transition using the exact intended versions.
During the change, preserve evidence: pre-upgrade health, configuration and artifact digests, governance approvals, transaction hashes, observed downtime, and post-upgrade acceptance checks. If rollback is impossible after a contract or state migration, state that clearly before the change begins.
Upgrade sequence
- Freeze the release manifest and identify every component and contract affected.
- Test upgrade and rollback in a representative environment using the intended data, bridge, and settlement paths.
- Confirm governance approvals, timelocks, signer availability, and user communication.
- Pause or rate-limit only the services required by the planned change, with clear entry and exit criteria.
- Apply the upgrade in dependency order, verifying health after each stage.
- Submit representative transactions and verify execution, publication, settlement, indexing, and bridge flows.
- Watch the new version through a defined observation period before closing the change.
Upgrade stop conditions
Define stop conditions before the window: unexpected contract address, invalid proof, missed settlement deadline, unrecoverable database migration, bridge message mismatch, or loss of monitoring. When one occurs, stop advancing the release, preserve evidence, and use the pre-agreed rollback or incident path rather than improvising a second change.