Arbitrum Orbit Upgrades

Major version upgrades for Arbitrum Orbit chains typically involve breaking changes to the core contracts (e.g., nitro-contracts), the node software, or both.

---

Official Resources

When any major upgrade is available, review the official release notes and migration guides:

• Per-version upgrade scripts & READMEs: https://github.com/OffchainLabs/orbit-actions/tree/main/scripts/foundry/contract-upgrades
• nitro-contracts releases & migration guides: https://github.com/OffchainLabs/nitro-contracts/releases
• Nitro node releases: https://github.com/OffchainLabs/nitro/releases
• Orbit SDK (if applicable): https://github.com/OffchainLabs/arbitrum-orbit-sdk
• Arbitrum docs: https://docs.arbitrum.io/launch-orbit-chain/orbit-gentle-introduction

Each major version upgrade has a dedicated folder under orbit-actions with a README containing step-by-step instructions and the Foundry scripts needed to execute the upgrade. This is the primary reference — start here before anything else.

General Upgrade Process

1. Review the Release Notes

Go to the relevant GitHub repository and read the release notes for the target version. Pay close attention to:

• Breaking changes in contract interfaces
• New contract deployments required
• Node version compatibility requirements
• Any changes to dispute protocols or proof systems

2. Audit Your Custom Contracts

If your chain has custom or modified contracts that reference core Arbitrum addresses (e.g., rollup contract, inbox, outbox), identify any immutable address references that may be affected by new deployments. These will need to be redeployed or reconfigured.

3. Plan the Migration

• Determine which contracts need to be upgraded vs. redeployed from scratch
• Identify any contracts with immutable constructor arguments pointing to addresses that will change
• Plan the upgrade ordering (some contracts depend on others being upgraded first)
• Coordinate with your chain's validators/sequencer operators

4. Test on a Staging Environment

Always run through the full upgrade on a testnet or staging chain before touching production. Verify:

• All contracts deploy and initialize correctly
• The node software connects and syncs
• Any custom modules (e.g., TEE proofs, custom dispute resolution) function as expected

5. Execute the On-Chain Upgrade

Follow the step-by-step instructions in the official migration guide for the target version. This typically involves:

• Deploying new contract implementations
• Calling upgrade/admin functions on the rollup contract
• Updating any proxy implementations

6. Upgrade the Node Software

Update your node to the version compatible with the new contracts. Refer to the nitro release notes for the correct node version pairing. Restart and confirm the node syncs without errors.

7. Verify & Monitor

After the upgrade:

• Confirm new blocks are being produced
• Verify assertions are being posted correctly
• Monitor for any errors in the dispute/challenge protocol
• Test deposits and withdrawals end-to-end