OffchainLabs · gzeoneth · Apr 14, 2025 · Jan 8, 2025 · Jan 8, 2025 · Jan 8, 2025
diff --git a/README.md b/README.md
@@ -50,6 +50,10 @@ _This section is also referenced in the documentation on ["How to upgrade ArbOS
 
 For ArbOS upgrades, a common pre-requisite is to deploy new Nitro contracts to the parent chain of your Orbit chain before scheduling the ArbOS upgrade. These contracts include the rollup logic, fraud proof contracts, and interfaces for interacting with Nitro precompiles. The scripts and instructions in this repository are meant for Orbit chain owners to upgrade the aforementioned contracts, set the new WASM module root, and then schedule the ArbOS upgrade.
 
+### Nitro contracts 3.1.0 (for [BoLD](https://docs.arbitrum.io/how-arbitrum-works/bold/gentle-introduction))
+
+The [`nitro-contracts 3.1.0` upgrade guide](scripts/foundry/contract-upgrades/3.1.0) will use the [BOLDUpgradeAction](https://github.com/OffchainLabs/nitro-contracts/blob/main/src/rollup/BOLDUpgradeAction.sol) from the [nitro-contract](https://github.com/OffchainLabs/nitro-contracts) repo. There are no associated ArbOS upgrade for BoLD. 
+
 ### Nitro contracts 2.1.3
 
 The [`nitro-contracts 2.1.3` upgrade guide](scripts/foundry/contract-upgrades/2.1.3) will patch the `Inbox` and `SequencerInbox` to properly handle EIP7702 callers. This upgrade is required before the parent chain upgrades to include EIP7702.
@@ -62,7 +66,7 @@ This upgrade is only required if:
 
 1. The chain has a custom native token; AND
 1. The chain was originally deployed before `v2.0.0`; AND
-1. The chain wishes to upgrade to `v3.0.0` or `v2.1.3`
+1. The chain wishes to upgrade to `v3.1.0` or `v2.1.3`
 
 Do not perform this upgrade if the above requirements aren't met.
 

diff --git a/scripts/foundry/contract-upgrades/2.1.3/README.md b/scripts/foundry/contract-upgrades/2.1.3/README.md
@@ -1,13 +1,13 @@
 # Nitro contracts 2.1.3 upgrade
 
 > [!CAUTION]
-> This is a patch version and is only necessary for chains that aren't ready for v3.0.0 whose parent chains are upgrading to include EIP7702.
+> This is a patch version and is only necessary for chains that aren't ready for v3.1.0 whose parent chains are upgrading to include EIP7702.
 >
-> v3.0.0 is also compatible with an EIP7702 enabled parent chain.
+> v3.1.0 is also compatible with an EIP7702 enabled parent chain.
 
 These scripts deploy and execute the `NitroContracts2Point1Point3UpgradeAction` contract which allows Orbit chains to upgrade to [2.1.3 release](https://github.com/OffchainLabs/nitro-contracts/releases/tag/v2.1.3). Predeployed instances of the upgrade action exist on the chains listed in the following section.
 
-Upgrading to `v2.1.3` not required nor recommended if the chain aims to upgrade to v3.0.0 before the parent chain gets EIP7702.
+Upgrading to `v2.1.3` not required nor recommended if the chain aims to upgrade to v3.1.0 before the parent chain gets EIP7702.
 
 You may need to perform the `v2.1.2` upgrade first if your chain uses a custom gas token and was originally deployed before `v2.0.0`. Please refer to the top [README](/README.md#check-version-and-upgrade-path) `Check Version and Upgrade Path` on how to determine your current nitro contracts version.
 

diff --git a/scripts/foundry/contract-upgrades/3.1.0/README.md b/scripts/foundry/contract-upgrades/3.1.0/README.md
@@ -0,0 +1,86 @@
+# Nitro contracts 3.1.0 upgrade
+
+To upgrade to Nitro contracts 3.1.0 (BoLD), you will need to use the [BOLDUpgradeAction](https://github.com/OffchainLabs/nitro-contracts/blob/main/src/rollup/BOLDUpgradeAction.sol) from the [nitro-contract](https://github.com/OffchainLabs/nitro-contracts) repo. 
+
+BOLDUpgradeAction will perform the following actions:
+
+1. Upgrade bridge, inbox, rollupEventInbox, outbox, sequencerInbox to v3.1.0
+2. Deploy new v3.1.0 BoLD challenge manager
+3. Migrate v2 rollup into a new v3.1.0 rollup address
+4. Setup the rollup according to the new config and use the latest confirmed assertion on the old rollup as genesis of the new rollup
+
+Note that contracts without code changes are not upgraded. It is normal to have some contracts still in the old version after the upgrade as they are equivalent to the new version. There are no associated ArbOS upgrade for this version.
+
+## Requirements
+
+This upgrade only support upgrading from the following [nitro-contract release](https://github.com/OffchainLabs/nitro-contracts/releases):
+
+- Inbox: v1.1.0 - v2.1.3 inclusive
+- Outbox: any
+- SequencerInbox: v1.2.1 - v2.1.3 inclusive
+- Bridge
+  - eth chain: v1.1.0 - v2.1.3 inclusive
+  - custom-fee token chain: v2.0.0 - v2.1.3 inclusive
+- RollupProxy: v1.1.0 - v2.1.3 inclusive
+- RollupAdminLogic: v2.0.0 - v2.1.3 inclusive
+- RollupUserLogic: v2.0.0 - v2.1.3 inclusive
+- ChallengeManager: v2.0.0 - v2.1.3 inclusive
+
+Please refer to the top [README](../../README.md) `Check Version and Upgrade Path` on how to determine your current nitro contracts version.
+
+## How to use it
+
+1. Clone nitro-contract repo
+```
+$ git clone https://github.com/OffchainLabs/nitro-contracts.git
+$ cd nitro-contracts
+```
+
+2. Checkout the v3.1.0 tag
+```
+$ git checkout v3.1.0
+```
+
+3. Install dependencies and build contracts
+```
+$ yarn install
+$ yarn build:all
+```
+
+4. Edit `scripts/files/configs/custom.ts`, be very careful as they will override existing configs
+
+5. Setup .env in project root, make sure `CONFIG_NETWORK_NAME=custom`.
+```
+$ cp .env-sample .env
+```
+
+7. Run the prepare script, this will deploy the actions. L1_PRIV_KEY does not need to be the chain owner. Pass in the parent chain for `--network`
+```
+$ L1_PRIV_KEY=xxx INFURA_KEY=xxx ETHERSCAN_API_KEY=xxx yarn script:bold-prepare --network {mainnet|arb1|base|arbSepolia}
+...
+Verified contract BOLDUpgradeAction successfully.
+Deployed contracts written to: scripts/files/sepoliaDeployedContracts.json
+Done.
+```
+
+8. Make sure everything is configured correctly. It would be nice to temporarily shutdown all validators.
+
+9. Run the populate lookup script, this will store the last confirmed assertion on-chain for the next step.
+```
+$ L1_PRIV_KEY=xxx yarn script:bold-populate-lookup
+...
+Done.
+```
+
+10. Run the upgrade script. If the L1_PRIV_KEY is not the chain owner, it will print the upgrade payload. Execute the payload with the chain owner. 
+
+> [!CAUTION]
+> This script will not ask for confirmation before sending the transaction!
+
+```
+$ L1_PRIV_KEY=xxx yarn script:bold-local-execute
+upgrade executor: 0x5FEe78FE9AD96c1d8557C6D6BB22Eb5A61eeD315
+execute(...) call to upgrade executor: 0x1cff79cd000000000000000000000000f8199ca3702c09c78b957d4d820311125753c6d2000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000a4ebe03a93000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000030000000000000000000000008a8f0a24d7e58a76fc8f77bb68c7c902b91e182e00000000000000000000000087630025e63a30ecf9ca9d580d9d95922fea6af0000000000000000000000000c32b93e581db6ebc50c08ce381143a259b92f1ed00000000000000000000000000000000000000000000000000000000
+```
+
+## FAQ
diff --git a/scripts/orbit-versioner/orbitVersioner.ts b/scripts/orbit-versioner/orbitVersioner.ts
@@ -132,22 +132,22 @@ async function main() {
 
   // TODO: make this more generic to support other other upgrade paths in the future
   // TODO: also check  osp
-  _checkForPossibleUpgrades(versions, isFeeTokenChain)
+  _checkForPossibleUpgrades(versions, isFeeTokenChain, chainId)
 }
 
 function _checkForPossibleUpgrades(
   currentVersions: {
     [key: string]: string | null
   },
-  isFeeTokenChain: boolean
+  isFeeTokenChain: boolean,
+  parentChainId: bigint
 ) {
   // version need to be in descending order
   const targetVersionsDescending = [
-    // DISABLING BOLD UPGRADE FOR NOW
-    // {
-    //   version: 'v3.0.0',
-    //   actionName: 'BOLD UpgradeAction',
-    // },
+    {
+      version: 'v3.1.0',
+      actionName: 'BOLD UpgradeAction',
+    },
     {
       version: 'v2.1.3',
       actionName: 'NitroContracts2Point1Point3UpgradeAction',
@@ -166,14 +166,36 @@ function _checkForPossibleUpgrades(
     },
   ]
 
+  // if 2.1.3 and 3.1.0 are both possible, then notify and early return
+  if (
+    _canBeUpgradedToTargetVersion(
+      'v2.1.3',
+      currentVersions,
+      isFeeTokenChain,
+      parentChainId
+    ) &&
+    _canBeUpgradedToTargetVersion(
+      'v3.1.0',
+      currentVersions,
+      isFeeTokenChain,
+      parentChainId
+    )
+  ) {
+    console.log(
+      'This deployment can be upgraded to both v2.1.3 and v3.1.0. v3.1.0 is recommended'
+    )
+    return
+  }
+
   let canUpgradeTo = ''
   let canUpgradeToActionName = ''
   for (const target of targetVersionsDescending.reverse()) {
     if (
       _canBeUpgradedToTargetVersion(
         target.version,
         currentVersions,
-        isFeeTokenChain
+        isFeeTokenChain,
+        parentChainId
       )
     ) {
       if (canUpgradeTo === '') {
@@ -200,54 +222,85 @@ function _canBeUpgradedToTargetVersion(
     [key: string]: string | null
   },
   isFeeTokenChain: boolean,
+  parentChainId: bigint,
   verbose: boolean = false
 ): boolean {
   if (verbose)
     console.log('\nChecking if deployment can be upgraded to', targetVersion)
 
   let supportedSourceVersionsPerContract: { [key: string]: string[] } = {}
 
-  // DISABLING BOLD UPGRADE FOR NOW
-  // if (targetVersion === 'v3.0.0') {
-  //   // v3.0.0 will upgrade bridge, inbox, rollupEventInbox, outbox, sequencerInbox, rollup logics, challengeManager
-  //   supportedSourceVersionsPerContract = {
-  //     Inbox: [
-  //       'v1.1.0',
-  //       'v1.1.1',
-  //       'v1.2.0',
-  //       'v1.2.1',
-  //       'v1.3.0',
-  //       'v2.0.0',
-  //       'v2.1.0',
-  //     ],
-  //     Outbox: ['any'],
-  //     Bridge: [
-  //       'v1.1.0',
-  //       'v1.1.1',
-  //       'v1.2.0',
-  //       'v1.2.1',
-  //       'v1.3.0',
-  //       'v2.0.0',
-  //       'v2.1.0',
-  //     ],
-  //     RollupEventInbox: ['any'],
-  //     RollupProxy: ['any'],
-  //     RollupAdminLogic: ['v2.0.0', 'v2.1.0'],
-  //     RollupUserLogic: ['v2.0.0', 'v2.1.0'],
-  //     ChallengeManager: ['v2.0.0', 'v2.1.0'],
-  //     SequencerInbox: ['v1.2.1', 'v1.3.0', 'v2.0.0', 'v2.1.0'],
-  //   }
-  //   if (isFeeTokenChain) {
-  //     // cannot upgrade erc20 orbit chains from v1 to v3 right now due to a storage diff
-  //     supportedSourceVersionsPerContract.Bridge = ['v2.0.0', 'v2.1.0', 'v2.1.2']
-  //     // TODO: remove this later, but the script does not custom fee token chain yet
-  //     supportedSourceVersionsPerContract.Bridge = []
-  //   }
-  // } else
-  if (targetVersion === 'v2.1.3') {
+  if (targetVersion === 'v3.1.0') {
+    // todo: remove once nitro supports bold for L3's
+    if (parentChainId !== 1n && parentChainId !== 11155111n) {
+      supportedSourceVersionsPerContract = {
+        Inbox: [],
+        Outbox: [],
+        Bridge: [],
+        RollupEventInbox: [],
+        RollupProxy: [],
+        RollupAdminLogic: [],
+        RollupUserLogic: [],
+        ChallengeManager: [],
+        SequencerInbox: [],
+      }
+    } else {
+      // v3.1.0 will upgrade bridge, inbox, rollupEventInbox, outbox, sequencerInbox, rollup logics, challengeManager
+      supportedSourceVersionsPerContract = {
+        Inbox: [
+          'v1.1.0',
+          'v1.1.1',
+          'v1.2.0',
+          'v1.2.1',
+          'v1.3.0',
+          'v2.0.0',
+          'v2.1.0',
+          'v2.1.1',
+          'v2.1.2',
+          'v2.1.3',
+        ],
+        Outbox: ['any'],
+        Bridge: [
+          'v1.1.0',
+          'v1.1.1',
+          'v1.2.0',
+          'v1.2.1',
+          'v1.3.0',
+          'v2.0.0',
+          'v2.1.0',
+          'v2.1.1',
+          'v2.1.2',
+          'v2.1.3',
+        ],
+        RollupEventInbox: ['any'],
+        RollupProxy: ['any'],
+        RollupAdminLogic: ['v2.0.0', 'v2.1.0', 'v2.1.1', 'v2.1.2', 'v2.1.3'],
+        RollupUserLogic: ['v2.0.0', 'v2.1.0', 'v2.1.1', 'v2.1.2', 'v2.1.3'],
+        ChallengeManager: ['v2.0.0', 'v2.1.0', 'v2.1.1', 'v2.1.2', 'v2.1.3'],
+        SequencerInbox: [
+          'v1.2.1',
+          'v1.3.0',
+          'v2.0.0',
+          'v2.1.0',
+          'v2.1.1',
+          'v2.1.2',
+          'v2.1.3',
+        ],
+      }
+      if (isFeeTokenChain) {
+        supportedSourceVersionsPerContract.Bridge = [
+          'v2.0.0',
+          'v2.1.0',
+          'v2.1.1',
+          'v2.1.2',
+          'v2.1.3',
+        ]
+      }
+    }
+  } else if (targetVersion === 'v2.1.3') {
     // v2.1.3 will upgrade the SequencerInbox and Inbox contracts to prevent 7702 accounts from calling certain functions
-    // v2.1.3 or v3.0.0 must be performed before the parent chain upgrades with 7702
-    // has the same prerequisites as v3.0.0
+    // v2.1.3 or v3.1.0 must be performed before the parent chain upgrades with 7702
+    // has the same prerequisites as v3.1.0
     supportedSourceVersionsPerContract = {
       Inbox: [
         'v1.1.0',