{"_rev":"5-f362b44b1b1020cde7a6e4346892597d","time":{"created":"2026-05-04T12:15:21.507Z","modified":"2026-05-04T12:15:22.092Z","0.0.0":"2026-04-27T13:50:23.579Z","0.0.1":"2026-04-27T13:54:13.075Z","1.0.0":"2026-05-04T12:15:21.853Z"},"_id":"@alxdc/chain-actions","name":"@alxdc/chain-actions","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@alxdc/chain-actions","version":"1.0.0","repository":{"type":"git","url":"git+https://github.com/OffchainLabs/chain-actions.git"},"license":"Apache-2.0","publishConfig":{"access":"public"},"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","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 && hardhat typechain && forge build","clean":"hardhat clean && forge clean","test:unit":"./test/unit/test-unit.bash","test:fork":"./test/fork/test-fork.bash","test:e2e":"./test/e2e/test-e2e.bash","test:sizes":"forge build --sizes","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","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"},"devDependencies":{"@arbitrum/nitro-contracts-1.2.1":"npm:@arbitrum/nitro-contracts@1.2.1","@arbitrum/nitro-contracts-1.3.0":"npm:@arbitrum/nitro-contracts@1.3.0","@arbitrum/nitro-contracts-2.1.0":"npm:@arbitrum/nitro-contracts@2.1.0","@arbitrum/nitro-contracts-2.1.2":"npm:@arbitrum/nitro-contracts@2.1.2","@arbitrum/nitro-contracts-2.1.3":"npm:@arbitrum/nitro-contracts@2.1.3","@arbitrum/token-bridge-1.2.2":"npm:@arbitrum/token-bridge-contracts@1.2.2","@nomicfoundation/hardhat-chai-matchers":"^2.0.0","@nomicfoundation/hardhat-ethers":"^3.0.0","@nomicfoundation/hardhat-foundry":"^1.1.1","@nomicfoundation/hardhat-network-helpers":"^1.0.0","@nomicfoundation/hardhat-toolbox":"^4.0.0","@nomicfoundation/hardhat-verify":"^2.0.0","@offchainlabs/upgrade-executor":"1.1.0-beta.0","@typechain/ethers-v6":"^0.5.0","@typechain/hardhat":"^9.0.0","@types/chai":"^4.2.0","@types/mocha":">=9.1.0","@types/node":">=16.0.0","@typescript-eslint/eslint-plugin":"^7.0.1","@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","solidity-coverage":"^0.8.0","toml":"3.0.0","ts-node":">=8.0.0","typechain":"^8.3.0","typescript":">=4.5.0"},"dependencies":{"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"}},"_id":"@alxdc/chain-actions@1.0.0","gitHead":"912d8f1ebf684a6f5c72bac46e6514fceee49f52","description":"A set of contracts for upgrading and manipulating Arbitrum chains. These contracts are similar to the [gov-action-contracts](https://github.com/ArbitrumFoundation/governance/tree/main/src/gov-action-contracts) used by Arbitrum One.","bugs":{"url":"https://github.com/OffchainLabs/chain-actions/issues"},"homepage":"https://github.com/OffchainLabs/chain-actions#readme","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-/W0ZrfSDqQtBJ+xfcP96l+/z0bWIHYydLsnoxkCUhTDF8CD3+nfCLyb5I8tAzQyvoY49w+xvK1hT6o9Of+Faqw==","shasum":"4be57ed55f328bdc26dd3336ae43e0e9ea3d9a06","tarball":"https://registry.npmjs.org/@alxdc/chain-actions/-/chain-actions-1.0.0.tgz","fileCount":452,"unpackedSize":2201247,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCl77s+dnuG8T1NOf2wXZeA+YusepgVZSgY/EjcfhF7swIgHvwtnkDNJ6dW3OwC6GSx6guINV5/2MMIu/a+2gITiXY="}]},"_npmUser":{"name":"alxdc","email":"alexandre@gelato.digital"},"directories":{},"maintainers":[{"name":"alxdc","email":"alexandre@gelato.digital"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/chain-actions_1.0.0_1777896921643_0.985612898239079"},"_hasShrinkwrap":false}},"maintainers":[{"name":"alxdc","email":"alexandre@gelato.digital"}],"description":"A set of contracts for upgrading and manipulating Arbitrum chains. These contracts are similar to the [gov-action-contracts](https://github.com/ArbitrumFoundation/governance/tree/main/src/gov-action-contracts) used by Arbitrum One.","homepage":"https://github.com/OffchainLabs/chain-actions#readme","repository":{"type":"git","url":"git+https://github.com/OffchainLabs/chain-actions.git"},"bugs":{"url":"https://github.com/OffchainLabs/chain-actions/issues"},"license":"Apache-2.0","readme":"# Chain Action Contracts\n\nA set of contracts for upgrading and manipulating Arbitrum chains. These contracts are similar to the [gov-action-contracts](https://github.com/ArbitrumFoundation/governance/tree/main/src/gov-action-contracts) used by Arbitrum One.\n\n## Requirments\n\n[yarn](https://classic.yarnpkg.com/lang/en/docs/install/) and [foundry](https://book.getfoundry.sh/getting-started/installation) are required to run the scripts\n\nMost of the action contracts only support the following ownership setup:\n\n- Rollup Contract on Parent Chain owned by a `ParentUpgradeExecutor`\n- Rollup ProxyAdmin on Parent Chain owned by a `ParentUpgradeExecutor`\n- Arb Owner on the Child Arbitrum Chain is granted to alias of `ParentUpgradeExecutor`\n- Arb Owner on the Child Arbitrum Chain is granted to `ChildUpgradeExecutor`\n\nFor token bridge related operations, these are the additional requirements:\n\n- Token Bridge ProxyAdmin on Parent Chain owned by `ParentUpgradeExecutor`\n- Token Bridge ProxyAdmin on Child Arbitrum Chain owned by `ChildUpgradeExecutor`\n- Parent Chain Gateway Router and Custom Gateway owned by `ParentUpgradeExecutor`\n\n## Setup\n\n```\nyarn install\n```\n\n## Check Version and Upgrade Path\n\nRun the following command to check the version of Nitro contracts deployed on the parent chain of your Orbit chain.\n\n```\n$ INBOX_ADDRESS=0xaE21fDA3de92dE2FDAF606233b2863782Ba046F9 \\\n  PARENT_CHAIN_RPC=https://arb1.arbitrum.io/rpc \\\n  yarn chain:contracts:version\nGet the version of Orbit chain's nitro contracts (inbox 0xaE21fDA3de92dE2FDAF606233b2863782Ba046F9), hosted on chain 42161\nVersion of deployed Inbox: v1.1.1\nVersion of deployed Outbox: v1.1.1\nVersion of deployed SequencerInbox: v1.1.1\nVersion of deployed Bridge: v1.1.1\nVersion of deployed RollupProxy: v1.1.1\nVersion of deployed RollupAdminLogic: v1.1.1\nVersion of deployed RollupUserLogic: v1.1.1\nThis deployment can be upgraded to v1.2.1 using NitroContracts1Point2Point1UpgradeAction\n```\n\nRun `yarn chain:contracts:version --help` for usage details.\n\n## Nitro Contracts Upgrades\n\n_This section is also referenced in the documentation on [\"How to upgrade ArbOS on your Arbitrum chain\"](https://docs.arbitrum.io/launch-arbitrum-chain/configure-your-chain/common/validation-and-security/arbos-upgrade)_ as Step 2 and Step 3.\n\nFor ArbOS upgrades, a common pre-requisite is to deploy new Nitro contracts to the parent chain of your Arbitrum 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 Arbitrum chain owners to upgrade the aforementioned contracts, set the new WASM module root, and then schedule the ArbOS upgrade.\n\n### Nitro contracts 3.1.0 (for [BoLD](https://docs.arbitrum.io/how-arbitrum-works/bold/gentle-introduction))\n\nThe [`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.\n\n### Nitro contracts 2.1.3\n\nThe [`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.\n\n### Nitro contracts 2.1.2\n\nThe [`nitro-contracts 2.1.2` upgrade guide](scripts/foundry/contract-upgrades/2.1.2) will patch the `ERC20Bridge` with a storage layout fix.\n\nThis upgrade is only required if:\n\n1. The chain has a custom native token; AND\n1. The chain was originally deployed before `v2.0.0`; AND\n1. The chain wishes to upgrade to `v3.1.0` or `v2.1.3`\n\nDo not perform this upgrade if the above requirements aren't met.\n\n### Nitro contracts 2.1.0 (for [ArbOS 32 Bianca](https://docs.arbitrum.io/run-arbitrum-node/arbos-releases/arbos32))\n\nThe [`nitro-contracts 2.1.0` upgrade action](scripts/foundry/contract-upgrades/2.1.0) will deploy `nitro-contracts v2.1.0` contracts to your Arbitrum chain's parent chain. Note that this action will only work for chains with `nitro-contracts v1.2.1` or `nitro-contracts v1.3.0`.\n\nNote: nitro contracts upgrade brings support for AnyTrust fast confirmations and Stylus. However, Stylus will be enabled only when `ArbOS 32 Bianca` upgrade takes place, once it will be officially supported for Arbitrum chains.\n\n### Nitro contracts 1.2.1 (for [ArbOS 20 Atlas](https://docs.arbitrum.io/run-arbitrum-node/arbos-releases/arbos20))\n\nThe [`nitro-contracts 1.2.1` upgrade action](scripts/foundry/contract-upgrades/1.2.1) will deploy `nitro-contracts v1.2.1` contracts to your Arbitrum chain's parent chain. Note that this action will only work for chains with `nitro-contracts v1.1.0` or `nitro-contracts v.1.1.1`. ArbOS 20 Atlas, shipped via [Nitro v2.3.0](https://github.com/OffchainLabs/nitro/releases/tag/v2.3.0), requires [**`nitro-contracts v1.2.1`**](https://github.com/OffchainLabs/nitro-contracts/releases/tag/v1.2.1) or higher.\n\n## Scheduling the ArbOS upgrade\n\n_This section is also referenced in the documentation on [\"How to upgrade ArbOS on your Arbitrum chain\"](https://docs.arbitrum.io/launch-arbitrum-chain/configure-your-chain/common/validation-and-security/arbos-upgrade)_\n\nNext, you will need to schedule the actual upgrade using the [ArbOS upgrade at timestamp action](scripts/foundry/arbos-upgrades/at-timestamp).\n\nThis action schedule an upgrade of the ArbOS to a specific version at a specific timestamp.\n\n## Common upgrade paths\n\nHere is a list of common upgrade paths that can be used to upgrade Arbitrum chains, beginning with the most recent upgrade. These instructions are duplicated from the docs on [How to upgrade ArbOS on your Arbitrum chain](https://docs.arbitrum.io/launch-arbitrum-chain/configure-your-chain/common/validation-and-security/arbos-upgrade), specifically Steps 1 through 3. Step 4 is mentioned below under \"Other Actions\".\n\n### [ArbOS 51 Dia](https://docs.arbitrum.io/run-arbitrum-node/arbos-releases/arbos51)\n\n1. Upgrade your Nitro node(s) to [Nitro v3.9.3](https://github.com/OffchainLabs/nitro/releases/tag/v3.9.3) or higher\n1. Update the wasm module root on the Rollup contract in the parent chain to `0x8a7513bf7bb3e3db04b0d982d0e973bcf57bf8b88aef7c6d03dba3a81a56a499`, following the instructions in [Set wasmModuleRoot](docs/arbos-upgrades/set-wasm-module-root/README.md)\n1. Schedule the ArbOS 51 Dia upgrade using [ArbOS upgrade at timestamp action](scripts/foundry/arbos-upgrades/at-timestamp)\n\n### [ArbOS 40 Callisto](https://docs.arbitrum.io/run-arbitrum-node/arbos-releases/arbos40)\n\n1. Upgrade your Nitro node(s) to [Nitro v3.6.5](https://github.com/OffchainLabs/nitro/releases/tag/v3.6.5) or higher\n1. Upgrade `nitro-contracts` to `v3.1.0` using [nitro-contract 3.1.0 BoLD upgrade action](scripts/foundry/contract-upgrades/3.1.0)\n1. Schedule the ArbOS 40 Callisto upgrade using [ArbOS upgrade at timestamp action](scripts/foundry/arbos-upgrades/at-timestamp)\n\n### [ArbOS 32 Bianca](https://docs.arbitrum.io/run-arbitrum-node/arbos-releases/arbos32)\n\n1. Upgrade your Nitro node(s) to [Nitro v3.3.1](https://github.com/OffchainLabs/nitro/releases/tag/v3.3.1)\n1. Upgrade `nitro-contracts` to `2.1.0` using [nitro-contract 2.1.0 upgrade action](scripts/foundry/contract-upgrades/2.1.0)\n1. Schedule the ArbOS 32 Bianca upgrade using [ArbOS upgrade at timestamp action](scripts/foundry/arbos-upgrades/at-timestamp)\n\n### [ArbOS 20 Atlas](https://docs.arbitrum.io/run-arbitrum-node/arbos-releases/arbos20)\n\n1. Upgrade your Nitro node(s) to [Nitro v2.3.1](https://github.com/OffchainLabs/nitro/releases/tag/v2.3.1)\n1. Upgrade `nitro-contracts` to `v1.2.1` using [nitro-contract 1.2.1 upgrade action](scripts/foundry/contract-upgrades/1.2.1)\n1. Schedule the ArbOS 20 Atlas upgrade using [ArbOS upgrade at timestamp action](scripts/foundry/arbos-upgrades/at-timestamp)\n\n# Other Actions\n\nBelow are additional on-chain actions that Arbitrum chain owners and maintainers can take as part of [Step 4: Enable ArbOS specific configurations or feature flags](https://docs.arbitrum.io/launch-arbitrum-chain/configure-your-chain/common/validation-and-security/arbos-upgrade#step-4-enable-arbos-specific-configurations-or-feature-flags-not-always-required).\n\n## Enable Fast Confirmation\n\nSee [EnableFastConfirmAction](scripts/foundry/fast-confirm).\n\n## Enable Stylus Cache Manager\n\nSee [setCacheManager](scripts/foundry/stylus/setCacheManager).\n\n## Enable BoLD\n\nCurrently limited to L2s; L3 support is expected in a future update.\n\nSee [Nitro contracts 3.1.0 upgrade](https://github.com/OffchainLabs/chain-actions/tree/main/scripts/foundry/contract-upgrades/3.1.0).\n\n# CLI\n\nThe `chain-actions` CLI provides a guided interface for running upgrade scripts. It wraps Foundry commands and handles the deploy/execute/verify workflow.\n\n```bash\n# Browse available scripts\nyarn cli                              # List top-level directories\nyarn cli -- contract-upgrades            # List versions\nyarn cli -- contract-upgrades/1.2.1      # List contents + commands\n\n# View files\nyarn cli -- contract-upgrades/1.2.1/README.md\n\n# Run contract upgrade steps individually\nyarn cli -- contract-upgrades/1.2.1/deploy\nyarn cli -- contract-upgrades/1.2.1/execute\nyarn cli -- contract-upgrades/1.2.1/verify\n\n# Run ArbOS upgrade steps individually\nyarn cli -- arbos-upgrades/at-timestamp/deploy 32\nyarn cli -- arbos-upgrades/at-timestamp/execute\nyarn cli -- arbos-upgrades/at-timestamp/verify\n```\n\nRun `yarn cli -- help` for full usage details.\n\n### Configuration\n\nThe 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.\n\nForge 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.\n\nKey forge env vars:\n\n| Variable                 | Effect                                                           |\n| ------------------------ | ---------------------------------------------------------------- |\n| `FOUNDRY_BROADCAST=true` | Broadcast transactions (without this, scripts run in simulation) |\n| `ETH_PRIVATE_KEY=0x...`  | Private key for signing transactions                             |\n\nAll `FOUNDRY_*` env vars are supported -- see [Foundry configuration](https://book.getfoundry.sh/reference/config/) for the full list.\n\n### Full upgrade flow\n\nThe 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:\n\n```bash\n# 1. Deploy the upgrade action contract\nyarn cli -- contract-upgrades/2.1.3/deploy\n# Note the deployed action address printed at the end\n\n# 2. Set UPGRADE_ACTION_ADDRESS in .env, then execute\nyarn cli -- contract-upgrades/2.1.3/execute\n\n# 3. Verify the upgrade\nyarn cli -- contract-upgrades/2.1.3/verify\n```\n\n### Writing new deploy scripts\n\nThe 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.\n\n## Docker\n\nThe CLI is available as a Docker image at `offchainlabs/chain-actions`:\n\n```bash\n# Check contract versions\ndocker run --rm \\\n  --entrypoint yarn \\\n  -e INBOX_ADDRESS=0xaE21fDA3de92dE2FDAF606233b2863782Ba046F9 \\\n  -e PARENT_CHAIN_RPC=https://arb1.arbitrum.io/rpc \\\n  offchainlabs/chain-actions \\\n  chain:contracts:version\n\n# Browse upgrade scripts\ndocker run --rm offchainlabs/chain-actions contract-upgrades\n\n# Deploy with env file (simulation mode -- no FOUNDRY_BROADCAST)\ndocker run --rm \\\n  -v $(pwd)/.env:/app/.env \\\n  -v $(pwd)/broadcast:/app/broadcast \\\n  offchainlabs/chain-actions \\\n  contract-upgrades/2.1.3/deploy\n\n# Execute with broadcasting enabled\ndocker run --rm \\\n  -v $(pwd)/.env:/app/.env \\\n  offchainlabs/chain-actions \\\n  contract-upgrades/2.1.3/execute\n```\n","readmeFilename":"README.md"}