feat: add Docker support for running upgrade scripts

.dockerignore

@@ -0,0 +1,28 @@
+# Dependencies (will be installed fresh in container)
+node_modules/
+
+# Build artifacts (will be built fresh in container)
+out/
+cache_forge/
+cache/
+artifacts/
+typechain-types/
+
+# Environment files (contain secrets)
+/.env
+
+# Git
+.git/
+.gitignore
+
+# IDE
+.vscode/
+.idea/
+
+# Test artifacts
+broadcast/
+coverage/
+
+# Docker
+Dockerfile
+.dockerignore

.eslintignore

@@ -1 +1,2 @@
 lib/
+dist/

.eslintrc.js

@@ -60,7 +60,7 @@ module.exports = {
         'plugin:@typescript-eslint/recommended',
         'plugin:prettier/recommended',
       ],
-      plugins: ['@typescript-eslint', 'prettier', '@typescript-eslint/tslint'],
+      plugins: ['@typescript-eslint', 'prettier'],
       rules: {
         'no-empty-pattern': 'warn',
         'prettier/prettier': ['error', { singleQuote: true }],
@@ -77,12 +77,6 @@ module.exports = {
             caughtErrorsIgnorePattern: '^_',
           },
         ],
-        '@typescript-eslint/tslint/config': [
-          'error',
-          {
-            rules: { 'strict-comparisons': true },
-          },
-        ],
         'no-implicit-coercion': 'error',
         '@typescript-eslint/no-shadow': ['error'],
       },

.github/workflows/publish-docker.yml

@@ -0,0 +1,48 @@
+name: Publish Docker
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Build and Push Docker Image
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract metadata for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          # "orbit" is a deprecated term; the published image uses "chain-actions"
+          images: offchainlabs/chain-actions
+          tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=ref,event=branch
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/test-docker.yml

@@ -0,0 +1,32 @@
+name: Test Docker
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test-docker:
+    name: Test Docker Image
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          load: true
+          tags: orbit-actions:test
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Run Docker smoke tests
+        run: ./test/docker/test-docker.bash
+        env:
+          DOCKER_IMAGE: orbit-actions:test

.gitignore

@@ -1,5 +1,9 @@
 node_modules
 .env
+.DS_Store
+
+# TypeScript build output
+/dist
 
 # Hardhat files
 /cache

Dockerfile

@@ -0,0 +1,31 @@
+FROM node:22-slim
+
+# Install dependencies for Foundry, git, and jq (for JSON parsing in upgrade scripts)
+RUN apt-get update && apt-get install -y \
+    curl \
+    git \
+    jq \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Foundry
+ENV PATH="/root/.foundry/bin:${PATH}"
+RUN curl -L https://foundry.paradigm.xyz | bash && foundryup --install stable
+
+# Install Yarn Classic (v1) - matches the repo's yarn.lock format
+RUN npm install -g --force yarn@1.22.22
+
+WORKDIR /app
+
+# Copy package files first for better layer caching
+COPY package.json yarn.lock ./
+
+# --ignore-scripts: forge install runs separately after full copy
+RUN yarn install --frozen-lockfile --ignore-scripts
+
+COPY . .
+# forge install can't run here: it clones git submodules, but .dockerignore
+# excludes .git/. CI runs forge install on the host so lib/ is copied in above.
+RUN forge build
+RUN yarn build:cli
+
+ENTRYPOINT ["node", "/app/dist/cli/index.js"]

README.md

@@ -52,7 +52,7 @@ For ArbOS upgrades, a common pre-requisite is to deploy new Nitro contracts to t
 
 ### 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 is no associated ArbOS upgrade for BoLD. 
+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 is no associated ArbOS upgrade for BoLD.
 
 ### Nitro contracts 2.1.3
 
@@ -132,4 +132,94 @@ See [setCacheManager](scripts/foundry/stylus/setCacheManager).
 
 Currently limited to L2s; L3 support is expected in a future update.
 
-See [Nitro contracts 3.1.0 upgrade](https://github.com/OffchainLabs/orbit-actions/tree/main/scripts/foundry/contract-upgrades/3.1.0). 
+See [Nitro contracts 3.1.0 upgrade](https://github.com/OffchainLabs/orbit-actions/tree/main/scripts/foundry/contract-upgrades/3.1.0).
+
+# CLI
+
+The `orbit-actions` CLI provides a guided interface for running upgrade scripts. It wraps Foundry commands and handles the deploy/execute/verify workflow.
+
+```bash
+# Browse available scripts
+yarn cli                              # List top-level directories
+yarn cli -- contract-upgrades            # List versions
+yarn cli -- contract-upgrades/1.2.1      # List contents + commands
+
+# View files
+yarn cli -- contract-upgrades/1.2.1/README.md
+
+# Run contract upgrade steps individually
+yarn cli -- contract-upgrades/1.2.1/deploy
+yarn cli -- contract-upgrades/1.2.1/execute
+yarn cli -- contract-upgrades/1.2.1/verify
+
+# Run ArbOS upgrade steps individually
+yarn cli -- arbos-upgrades/at-timestamp/deploy 32
+yarn cli -- arbos-upgrades/at-timestamp/execute
+yarn cli -- arbos-upgrades/at-timestamp/verify
+```
+
+Run `yarn cli -- help` for full usage details.
+
+### Configuration
+
+The CLI reads chain-specific configuration (RPC URLs, contract addresses) from a `.env` file in the project root. See env templates in each version directory for examples.
+
+Forge behavior -- broadcasting, authentication, verbosity, verification -- is controlled via standard `FOUNDRY_*` / `ETH_*` env vars in the same `.env` file. The CLI passes `process.env` through to forge, so any env var forge recognizes will work.
+
+Key forge env vars:
+
+| Variable                 | Effect                                                           |
+| ------------------------ | ---------------------------------------------------------------- |
+| `FOUNDRY_BROADCAST=true` | Broadcast transactions (without this, scripts run in simulation) |
+| `ETH_PRIVATE_KEY=0x...`  | Private key for signing transactions                             |
+
+All `FOUNDRY_*` env vars are supported -- see [Foundry configuration](https://book.getfoundry.sh/reference/config/) for the full list.
+
+### Full upgrade flow
+
+The deploy, execute, and verify steps are run separately. This allows multisig users to submit Safe approvals between steps, and EOA users can chain the commands:
+
+```bash
+# 1. Deploy the upgrade action contract
+yarn cli -- contract-upgrades/2.1.3/deploy
+# Note the deployed action address printed at the end
+
+# 2. Set UPGRADE_ACTION_ADDRESS in .env, then execute
+yarn cli -- contract-upgrades/2.1.3/execute
+
+# 3. Verify the upgrade
+yarn cli -- contract-upgrades/2.1.3/verify
+```
+
+### Writing new deploy scripts
+
+The CLI identifies the action contract address by reading the last `CREATE` transaction from Forge's broadcast file. Deploy scripts must deploy all dependencies first and the action contract last.
+
+## Docker
+
+The CLI is available as a Docker image at `offchainlabs/orbit-actions`:
+
+```bash
+# Check contract versions
+docker run --rm \
+  -e INBOX_ADDRESS=0xaE21fDA3de92dE2FDAF606233b2863782Ba046F9 \
+  -e INFURA_KEY=$INFURA_KEY \
+  offchainlabs/orbit-actions:versioner \
+  --network arb1
+
+# Browse upgrade scripts
+docker run --rm offchainlabs/orbit-actions contract-upgrades
+
+# Deploy with env file (simulation mode -- no FOUNDRY_BROADCAST)
+docker run --rm \
+  -v $(pwd)/.env:/app/.env \
+  -v $(pwd)/broadcast:/app/broadcast \
+  offchainlabs/orbit-actions \
+  contract-upgrades/2.1.3/deploy
+
+# Execute with broadcasting enabled
+docker run --rm \
+  -v $(pwd)/.env:/app/.env \
+  offchainlabs/orbit-actions \
+  contract-upgrades/2.1.3/execute
+```

package.json

@@ -4,6 +4,8 @@
   "repository": "https://github.com/OffchainLabs/blockchain-eng-template.git",
   "license": "Apache 2.0",
   "scripts": {
+    "build:cli": "tsc -p tsconfig.cli.json",
+    "cli": "ts-node src/cli/index.ts",
     "prepare": "forge install && cd lib/arbitrum-sdk && yarn",
     "minimal-publish": "./scripts/publish.bash",
     "minimal-install": "yarn --ignore-scripts && forge install",
@@ -20,6 +22,7 @@
     "test:gas-check": "forge snapshot --check --tolerance 1 --match-path \"test/unit/**/*.t.sol\"",
     "test:sigs": "./test/signatures/test-sigs.bash",
     "test:storage": "./test/storage/test-storage.bash",
+    "test:docker": "./test/docker/test-docker.bash",
     "orbit:contracts:version": "hardhat run scripts/orbit-versioner/orbitVersioner.ts",
     "gas-snapshot": "forge snapshot --match-path \"test/unit/**/*.t.sol\"",
     "fix": "yarn format; yarn test:sigs; yarn test:storage; yarn gas-snapshot"
@@ -61,5 +64,9 @@
     "ts-node": ">=8.0.0",
     "typechain": "^8.3.0",
     "typescript": ">=4.5.0"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "execa": "^5.1.1"
   }
 }

scripts/foundry/arbos-upgrades/at-timestamp/DeployUpgradeArbOSVersionAtTimestampAction.s.sol

@@ -25,7 +25,8 @@ contract DeployUpgradeArbOSVersionAtTimestampActionScript is Script {
 
         vm.startBroadcast();
 
-        // finally deploy upgrade action
+        // Deploy the action contract last. The CLI identifies the deployed action
+        // by taking the last CREATE from the broadcast file.
         new UpgradeArbOSVersionAtTimestampAction({
             _newArbOSVersion: uint64(arbosVersion), _upgradeTimestamp: uint64(scheduleTimestamp)
         });

scripts/foundry/arbos-upgrades/at-timestamp/env-templates/.env.local-upgrade.example

@@ -1,3 +1,10 @@
+## Forge configuration (uncomment/adjust as needed)
+## All FOUNDRY_* env vars are supported: https://book.getfoundry.sh/reference/config/
+# FOUNDRY_BROADCAST=true
+# ETH_PRIVATE_KEY=0x...
+
+## Chain and contract addresses
+CHILD_CHAIN_RPC=
 UPGRADE_ACTION_ADDRESS="0x217788c286797D56Cd59aF5e493f3699C39cbbe8"
 CHILD_UPGRADE_EXECUTOR_ADDRESS="0x6A17B0D4EA37c4F519caCf776450cb42199Df0A4"
 ARBOS_VERSION=20

scripts/foundry/arbos-upgrades/at-timestamp/env-templates/.env.sepolia-upgrade.example

@@ -1,3 +1,10 @@
+## Forge configuration (uncomment/adjust as needed)
+## All FOUNDRY_* env vars are supported: https://book.getfoundry.sh/reference/config/
+# FOUNDRY_BROADCAST=true
+# ETH_PRIVATE_KEY=0x...
+
+## Chain and contract addresses
+CHILD_CHAIN_RPC=
 UPGRADE_ACTION_ADDRESS="0x7A132A8130a0C2dCeABd1FDb42ed01FCf6B9494a"
 CHILD_UPGRADE_EXECUTOR_ADDRESS="0x059EF6e2CaA4d779e087273646EfF49ef45dBD81"
 ARBOS_VERSION=20

scripts/foundry/contract-upgrades/1.2.1/DeployNitroContracts1Point2Point1UpgradeAction.s.sol

@@ -82,7 +82,8 @@ contract DeployNitroContracts1Point2Point1UpgradeActionScript is Script {
             abi.encode(vm.envUint("MAX_DATA_SIZE"), reader4844Address, vm.envBool("IS_FEE_TOKEN_CHAIN"))
         );
 
-        // finally deploy upgrade action
+        // Deploy the action contract last. The CLI identifies the deployed action
+        // by taking the last CREATE from the broadcast file.
         new NitroContracts1Point2Point1UpgradeAction({
             _newWasmModuleRoot: vm.envBytes32("WASM_MODULE_ROOT"),
             _newSequencerInboxImpl: seqInbox,

scripts/foundry/contract-upgrades/1.2.1/README.md

@@ -57,7 +57,7 @@ forge script --sender $EXECUTOR --rpc-url $PARENT_CHAIN_RPC --broadcast ./Execut
 ```
 If you have a multisig as executor, you can still run the above command without broadcasting to get the payload for the multisig transaction.
 
-4. That's it, upgrade has been performed. You can make sure it has successfully executed by checking wasm module root:
+4. That's it, upgrade has been performed. You can verify by running:
 ```bash
-cast call --rpc-url $PARENT_CHAIN_RPC $ROLLUP "wasmModuleRoot()"
+forge script --rpc-url $PARENT_CHAIN_RPC VerifyNitroContracts1Point2Point1Upgrade -vvv
 ```

scripts/foundry/contract-upgrades/1.2.1/VerifyNitroContracts1Point2Point1Upgrade.s.sol

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity 0.8.16;
+
+import "forge-std/Script.sol";
+
+interface IRollupCore {
+    function wasmModuleRoot() external view returns (bytes32);
+}
+
+/**
+ * @title VerifyNitroContracts1Point2Point1Upgrade
+ * @notice Verifies the upgrade to Nitro Contracts 1.2.1 by checking the wasmModuleRoot
+ */
+contract VerifyNitroContracts1Point2Point1Upgrade is Script {
+    function run() public view {
+        address rollup = vm.envAddress("ROLLUP");
+        bytes32 wasmRoot = IRollupCore(rollup).wasmModuleRoot();
+        console.log("wasmModuleRoot:");
+        console.logBytes32(wasmRoot);
+    }
+}