Support Hardhat 3 in Hardhat Upgrades

.changeset/migrate-to-hardhat-3.md

@@ -0,0 +1,30 @@
+---
+'@openzeppelin/hardhat-upgrades': major
+---
+
+Migrate to Hardhat 3 with ESM module structure and plugin hooks architecture.
+
+### Breaking Changes
+
+- **Requires Hardhat 3**: minimum `hardhat@^3.0.0` required.
+- **ESM-only**: package converted to ESM; CommonJS is no longer supported.
+- **API Changes**:
+  - No automatic `hre.upgrades` — call the `upgrades(hre, connection)` factory explicitly.
+  - Factory functions (`upgrades`, `defender`) are async and require a network connection.
+  - Network connection must be explicitly created: `const connection = await hre.network.connect()`. Share one connection across operations.
+  - `ethers` now comes from the connection (`const { ethers } = connection`), not `hre.ethers`.
+- **Import Changes**: import factory functions instead of a side-effect import.
+  - Before: `import '@openzeppelin/hardhat-upgrades'`
+  - After: `import { upgrades, defender } from '@openzeppelin/hardhat-upgrades'`
+
+### Usage and Migration
+
+See the [README](./README.md) for Hardhat 3 usage, the [examples](./examples/README.md) directory for sample projects, and the [Migration Guide](./MIGRATION.md) for Hardhat 2 to 3 migration steps.
+
+### Changes
+
+- Migrated from `extendEnvironment` to Hardhat 3's `HardhatPlugin` with `hookHandlers`.
+- Converted package to ESM.
+- Etherscan verification requires `@nomicfoundation/hardhat-verify@^3.0.10` (optional peer dependency).
+- Support [Solidity tests in Hardhat 3](./README.md#solidity-tests) with `@openzeppelin/foundry-upgrades`.
+- Added example projects for Hardhat 3 (Transparent, UUPS, and Solidity-test scaffolds under `packages/plugin-hardhat/examples/`).

.changeset/support-hardhat-3-build-info.md

@@ -0,0 +1,8 @@
+---
+'@openzeppelin/upgrades-core': minor
+---
+
+Support Hardhat 3 build-info file format for CLI validation.
+- Handle the split `.json` / `.output.json` file format used by Hardhat 3.
+- Improve support for validating build-info files in the CLI across Hardhat 3, Hardhat 2, and Foundry.
+- Improve error handling for Hardhat 3 `.output.json` files.

.eslintrc.js

@@ -1,7 +1,7 @@
 module.exports = {
   root: true,
   parserOptions: {
-    ecmaVersion: 2020,
+    ecmaVersion: 2022,
   },
   extends: ['eslint:recommended', 'plugin:prettier/recommended'],
   env: {
@@ -15,7 +15,13 @@ module.exports = {
     'unicorn/no-array-reduce': 'warn',
     'no-plusplus': ['warn', { allowForLoopAfterthoughts: true }],
   },
-  ignorePatterns: ['submodules'],
+  ignorePatterns: [
+    'submodules',
+    // ESLint 8.x doesn't support ES2025 import attributes syntax
+    // uses import attributes (import ... with { type: 'json' })
+    // which is valid ES2025 syntax but ESLint parser doesn't support it yet
+    'packages/plugin-hardhat/test/*.js',
+  ],
   overrides: [
     {
       files: ['*.ts'],
@@ -29,10 +35,14 @@ module.exports = {
       },
     },
     {
-      files: ['ava.config.js'],
+      files: ['ava.config.js', 'packages/plugin-hardhat/test/*.js', 'packages/plugin-hardhat/src/*.js'],
       parserOptions: {
+        ecmaVersion: 'latest',
         sourceType: 'module',
       },
+      rules: {
+        'no-unused-vars': ['warn', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+      },
     },
     {
       files: ['packages/plugin-truffle/**'],

.github/actions/setup/action.yml

@@ -5,9 +5,19 @@ runs:
   steps:
     - uses: actions/setup-node@v4
       with:
-        node-version: 20.x
+        node-version: 22.x
         cache: yarn
 
+    - name: Cache Hardhat solc compilers
+      uses: actions/cache@v4
+      with:
+        path: |
+          ~/.cache/hardhat/compilers-v3
+          ~/.cache/hardhat-nodejs/compilers-v3
+        key: hardhat-compilers-${{ runner.os }}-${{ hashFiles('**/package.json', '**/yarn.lock') }}
+        restore-keys: |
+          hardhat-compilers-${{ runner.os }}-
+
     - name: Install dependencies
       run: yarn --frozen-lockfile --prefer-offline
       shell: bash

.github/workflows/changeset.yml

@@ -22,6 +22,7 @@ jobs:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 #v4.2.2
         with:
           fetch-depth: 0 # Include history so Changesets finds merge-base
+          submodules: recursive
       - name: Set up environment
         uses: ./.github/actions/setup
       - name: Check changeset

.github/workflows/checks.yml

@@ -17,6 +17,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
+      with:
+        submodules: recursive
 
     - name: Set up environment
       uses: ./.github/actions/setup
@@ -35,10 +37,16 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
+      with:
+        submodules: recursive
 
     - name: Set up environment
       uses: ./.github/actions/setup
 
+    - name: Assert upgrades-core resolution (plugin-hardhat)
+      if: matrix.package == 'plugin-hardhat'
+      run: bash packages/plugin-hardhat/scripts/assert-upgrades-core-resolution.sh
+
     - name: Run tests
       run: yarn --cwd "packages/${{matrix.package}}" run test
 
@@ -47,10 +55,15 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
+      with:
+        submodules: recursive
 
     - name: Set up environment
       uses: ./.github/actions/setup
 
+    - name: Assert upgrades-core resolution
+      run: bash packages/plugin-hardhat/scripts/assert-upgrades-core-resolution.sh
+
     - name: Run coverage
       run: yarn coverage
 
@@ -114,4 +127,4 @@ jobs:
       if: steps.create_pull_request.outcome == 'failure'
       run: |
         git push origin --delete $BRANCH_NAME
-
+

.github/workflows/publish.yml

@@ -18,6 +18,7 @@ jobs:
         with:
           fetch-depth: 0 # To get all tags
           ref: ${{ github.ref }}
+          submodules: recursive
       - name: Set up environment
         uses: ./.github/actions/setup
       - name: Create Prepare Release PR or Publish

.github/workflows/version.yml

@@ -21,6 +21,7 @@ jobs:
         with:
           fetch-depth: 0 # To get all tags
           ref: ${{ github.ref }}
+          submodules: recursive
       - name: Set up environment
         uses: ./.github/actions/setup
       - name: Create Prepare Release PR

.node-version

@@ -1 +1 @@
-20
+22

package.json

@@ -22,7 +22,7 @@
     "eslint-config-prettier": "^9.0.0",
     "eslint-plugin-prettier": "^5.0.0",
     "eslint-plugin-unicorn": "^51.0.0",
-    "ethers": "^6.8.1",
+    "ethers": "^6.14.0",
     "nyc": "^17.0.0",
     "prettier": "^3.0.0",
     "typescript": "^5.0.0",

packages/core/CHANGELOG.md

@@ -1,6 +1,5 @@
 # Changelog
 
-
 ## 1.44.2 (2025-11-03)
 
 - Add Celo Sepolia network to manifest file names. ([#1189](https://github.com/OpenZeppelin/openzeppelin-upgrades/pull/1189))

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openzeppelin/upgrades-core",
-  "version": "1.44.2",
+  "version": "1.45.0-alpha.1",
   "description": "",
   "repository": "https://github.com/OpenZeppelin/openzeppelin-upgrades",
   "license": "MIT",