feat: prepare versioner to be exported as package

README.md

@@ -27,11 +27,13 @@ yarn install
 
 ## Check Version and Upgrade Path
 
-Run the follow command to check the version of Nitro contracts deployed on the parent chain of your Arbitrum chain.
+Run the following command to check the version of Nitro contracts deployed on the parent chain of your Orbit chain.
 
 ```
-$ INBOX_ADDRESS=0xaE21fDA3de92dE2FDAF606233b2863782Ba046F9 yarn orbit:contracts:version --network arb1
-Get the version of the chain's nitro contracts (inbox 0xaE21fDA3de92dE2FDAF606233b2863782Ba046F9), hosted on chain 42161
+$ INBOX_ADDRESS=0xaE21fDA3de92dE2FDAF606233b2863782Ba046F9 \
+  PARENT_CHAIN_RPC=https://arb1.arbitrum.io/rpc \
+  yarn chain:contracts:version
+Get the version of Orbit chain's nitro contracts (inbox 0xaE21fDA3de92dE2FDAF606233b2863782Ba046F9), hosted on chain 42161
 Version of deployed Inbox: v1.1.1
 Version of deployed Outbox: v1.1.1
 Version of deployed SequencerInbox: v1.1.1
@@ -42,7 +44,7 @@ Version of deployed RollupUserLogic: v1.1.1
 This deployment can be upgraded to v1.2.1 using NitroContracts1Point2Point1UpgradeAction
 ```
 
-For other networks, replace `arb1` with the network name and configure INFURA_KEY or the rpc in hardhat.config.ts
+Run `yarn chain:contracts:version --help` for usage details.
 
 ## Nitro Contracts Upgrades
 
@@ -202,10 +204,11 @@ The CLI is available as a Docker image at `offchainlabs/chain-actions`:
 ```bash
 # Check contract versions
 docker run --rm \
+  --entrypoint yarn \
   -e INBOX_ADDRESS=0xaE21fDA3de92dE2FDAF606233b2863782Ba046F9 \
-  -e INFURA_KEY=$INFURA_KEY \
-  offchainlabs/chain-actions:versioner \
-  --network arb1
+  -e PARENT_CHAIN_RPC=https://arb1.arbitrum.io/rpc \
+  offchainlabs/chain-actions \
+  chain:contracts:version
 
 # Browse upgrade scripts
 docker run --rm offchainlabs/chain-actions contract-upgrades

package.json

@@ -1,19 +1,21 @@
 {
-  "name": "orbit-actions",
+  "name": "@arbitrum/chain-actions",
   "version": "1.0.0",
-  "repository": "https://github.com/OffchainLabs/blockchain-eng-template.git",
+  "repository": "https://github.com/OffchainLabs/chain-actions.git",
   "license": "Apache 2.0",
   "scripts": {
     "build:cli": "tsc -p tsconfig.cli.json",
+    "build:package": "rm -rf dist && yarn build && tsc -p tsconfig.package-runtime.json",
     "cli": "ts-node src/cli/index.ts",
+    "prepack": "yarn build:package",
     "prepare": "forge install && cd lib/arbitrum-sdk && yarn",
     "minimal-publish": "./scripts/publish.bash",
     "minimal-install": "yarn --ignore-scripts && forge install",
     "audit:ci": "audit-ci --config ./audit-ci.jsonc",
     "upload-all-selectors": "forge build && find ./out -name \"*.json\" -exec cast upload-signature {} +",
     "format": "cat .prettierignore .gitignore > .pignore && prettier --ignore-path .pignore \"**/*.{js,ts,json}\" --write && rm .pignore && forge fmt",
     "lint": "tsc --noEmit && eslint . && forge fmt --check",
-    "build": "hardhat compile && forge build",
+    "build": "hardhat compile && hardhat typechain && forge build",
     "clean": "hardhat clean && forge clean",
     "test:unit": "./test/unit/test-unit.bash",
     "test:fork": "./test/fork/test-fork.bash",
@@ -23,7 +25,7 @@
     "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",
+    "chain:contracts:version": "ts-node scripts/chain-versioner/chainVersioner.ts",
     "gas-snapshot": "forge snapshot --match-path \"test/unit/**/*.t.sol\"",
     "fix": "yarn format; yarn test:sigs; yarn test:storage; yarn gas-snapshot"
   },
@@ -50,12 +52,14 @@
     "@typescript-eslint/parser": "^7.0.1",
     "audit-ci": "^6.6.1",
     "chai": "^4.2.0",
+    "commander": "^12.0.0",
     "dotenv": "^16.4.5",
     "eslint": "^8.56.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-prettier": "^5.1.3",
     "ethers": "^6.4.0",
     "ethers-v5": "npm:ethers@^5.7.2",
+    "execa": "^5.1.1",
     "hardhat": "^2.19.5",
     "hardhat-gas-reporter": "^1.0.8",
     "prettier": "^3.2.5",
@@ -66,7 +70,18 @@
     "typescript": ">=4.5.0"
   },
   "dependencies": {
-    "commander": "^12.0.0",
-    "execa": "^5.1.1"
-  }
+    "ethers": "^6.4.0"
+  },
+  "types": "./dist/scripts/chain-versioner/chainVersioner.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/scripts/chain-versioner/chainVersioner.d.ts",
+      "require": "./dist/scripts/chain-versioner/chainVersioner.js",
+      "default": "./dist/scripts/chain-versioner/chainVersioner.js"
+    }
+  },
+  "files": [
+    "dist/scripts/chain-versioner/**",
+    "dist/typechain-types/**"
+  ]
 }

scripts/orbit-versioner/orbitVersioner.ts → scripts/chain-versioner/chainVersioner.ts

@@ -1,14 +1,32 @@
-import { ethers } from 'hardhat'
 import metadataHashes from './referentMetadataHashes.json'
-import { HardhatEthersProvider } from '@nomicfoundation/hardhat-ethers/internal/hardhat-ethers-provider'
 import {
   IBridge__factory,
   IInbox__factory,
   IRollupCore__factory,
 } from '../../typechain-types'
+import { ethers, JsonRpcProvider } from 'ethers'
 
-export function isJsonMode(env: NodeJS.ProcessEnv = process.env): boolean {
-  return env.JSON_OUTPUT?.toLowerCase() === 'true'
+const HELP_TEXT = `Usage: yarn chain:contracts:version [--help]
+
+Reports the deployed Nitro contract versions for an Orbit chain and prints any
+supported upgrade path.
+
+Required environment variables:
+  INBOX_ADDRESS     Address of the Orbit chain inbox on the parent chain
+  PARENT_CHAIN_RPC  RPC URL for the Orbit chain's parent chain
+
+Optional environment variables:
+  JSON_OUTPUT       Set to "true" to print machine-readable JSON
+
+Example:
+  INBOX_ADDRESS=0x... PARENT_CHAIN_RPC=https://... yarn chain:contracts:version`
+
+function createLogger(jsonOutput: boolean) {
+  return (...args: unknown[]) => {
+    if (!jsonOutput) {
+      console.log(...args)
+    }
+  }
 }
 
 /**
@@ -50,26 +68,28 @@ export interface OrbitVersionerReport {
   upgradeRecommendation: UpgradeRecommendation
 }
 
+export type ChainVersionerReport = OrbitVersionerReport
+
 /**
  * Load the referent metadata hashes
  */
-
 const referentMetadataHashes: MetadataHashesByVersion = metadataHashes
 
 /**
  * Script will
  */
-async function main(): Promise<OrbitVersionerReport> {
-  if (!process.env.INBOX_ADDRESS) {
-    throw new Error('INBOX_ADDRESS env variable shall be set')
-  }
+export async function runChainVersioner(
+  inboxAddress: string,
+  parentRpcUrl: string,
+  jsonOutput: boolean
+): Promise<OrbitVersionerReport> {
+  const log = createLogger(jsonOutput)
 
   /// get provider
-  const provider = ethers.provider
+  const provider = new ethers.JsonRpcProvider(parentRpcUrl)
   const chainId = (await provider.getNetwork()).chainId
-  const inboxAddress = process.env.INBOX_ADDRESS!
 
-  console.log(
+  log(
     `Get the version of Orbit chain's nitro contracts (inbox ${inboxAddress}), hosted on chain ${chainId}`
   )
 
@@ -126,7 +146,7 @@ async function main(): Promise<OrbitVersionerReport> {
   }
 
   if (process.env.DEV === 'true') {
-    console.log('\nMetadataHashes of deployed contracts:', metadataHashes, '\n')
+    log('\nMetadataHashes of deployed contracts:', metadataHashes, '\n')
   }
 
   let isFeeTokenChain = false
@@ -138,7 +158,7 @@ async function main(): Promise<OrbitVersionerReport> {
     )
     versions[key] = version
     if (key === 'Bridge' && isErc20) isFeeTokenChain = true
-    console.log(
+    log(
       `Version of deployed ${key}: ${versions[key] ? versions[key] : 'unknown'}`
     )
   })
@@ -151,7 +171,7 @@ async function main(): Promise<OrbitVersionerReport> {
     chainId
   )
 
-  console.log(upgradeRecommendation.message)
+  log(upgradeRecommendation.message)
 
   return {
     versions,
@@ -510,7 +530,7 @@ function _getVersionOfDeployedContract(metadataHash: string): {
 
 async function _getMetadataHash(
   contractAddress: string,
-  provider: HardhatEthersProvider
+  provider: JsonRpcProvider
 ): Promise<string> {
   const bytecode = await provider.getCode(contractAddress)
 
@@ -528,7 +548,7 @@ async function _getMetadataHash(
 
 async function _getLogicAddress(
   contractAddress: string,
-  provider: HardhatEthersProvider
+  provider: JsonRpcProvider
 ): Promise<string> {
   const logic = (
     await _getAddressAtStorageSlot(
@@ -547,7 +567,7 @@ async function _getLogicAddress(
 
 async function _getAddressAtStorageSlot(
   contractAddress: string,
-  provider: HardhatEthersProvider,
+  provider: JsonRpcProvider,
   storageSlotBytes: string
 ): Promise<string> {
   const storageValue = await provider.getStorage(
@@ -567,20 +587,45 @@ async function _getAddressAtStorageSlot(
   return ethers.getAddress(formatAddress)
 }
 
+// Docker / CLI entrypoint
 if (require.main === module) {
-  if (isJsonMode()) {
-    console.log = (...args) => console.error(...args)
+  const args = process.argv.slice(2)
+  if (args.includes('--help')) {
+    process.stdout.write(`${HELP_TEXT}\n`)
+    process.exit(0)
+  }
+
+  const inboxAddress = process.env.INBOX_ADDRESS
+  const parentRpcUrl = process.env.PARENT_CHAIN_RPC
+  const jsonOutput = process.env.JSON_OUTPUT?.toLowerCase() === 'true'
+
+  if (!inboxAddress) {
+    const errorMessage = 'INBOX_ADDRESS env variable should be set'
+    if (jsonOutput) {
+      process.stderr.write(`${JSON.stringify({ error: errorMessage })}\n`)
+      process.exit(1)
+    }
+    throw new Error(errorMessage)
+  }
+
+  if (!parentRpcUrl) {
+    const errorMessage = 'PARENT_CHAIN_RPC env variable should be set'
+    if (jsonOutput) {
+      process.stderr.write(`${JSON.stringify({ error: errorMessage })}\n`)
+      process.exit(1)
+    }
+    throw new Error(errorMessage)
   }
 
-  main()
+  runChainVersioner(inboxAddress, parentRpcUrl, jsonOutput)
     .then(result => {
-      if (isJsonMode()) {
+      if (jsonOutput) {
         process.stdout.write(`${JSON.stringify(result)}\n`)
       }
       process.exit(0)
     })
     .catch((error: Error) => {
-      if (isJsonMode()) {
+      if (jsonOutput) {
         process.stderr.write(`${JSON.stringify({ error: error.message })}\n`)
       } else {
         console.error(error)

test/docker/test-docker.bash

@@ -119,7 +119,7 @@ run_test "help command" docker run --rm "$IMAGE_NAME" help
 # Test 7: Yarn scripts work
 echo ""
 echo "--- Yarn Scripts ---"
-run_test "yarn orbit:contracts:version --help" docker run --rm --entrypoint yarn "$IMAGE_NAME" orbit:contracts:version --help
+run_test "yarn chain:contracts:version --help" docker run --rm --entrypoint yarn "$IMAGE_NAME" chain:contracts:version --help
 
 # Test 8: Unit tests pass
 echo ""

tsconfig.package-runtime.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": ".",
+    "declaration": true
+  },
+  "include": [
+    "scripts/chain-versioner/chainVersioner.ts",
+    "typechain-types/**/*.ts"
+  ],
+  "exclude": ["./lib/"]
+}