Migrate to Hardhat 3

.changeset/spotty-teeth-show.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+Migrate test suite and helpers to Hardhat 3

.codecov.yml

@@ -14,3 +14,4 @@ ignore:
   - "test"
   - "contracts/mocks"
   - "contracts/vendor"
+  - "contracts-exposed"

.github/actions/gas-compare/action.yml

@@ -29,11 +29,10 @@ runs:
         GITHUB_TOKEN: ${{ inputs.token }}
       shell: bash
       continue-on-error: true
-      id: reference
     - name: Compare reports
-      if: steps.reference.outcome == 'success' && github.event_name == 'pull_request'
+      if: github.event_name == 'pull_request' && hashFiles(inputs.ref_report) != ''
       run: |
-        node scripts/checks/compareGasReports.js ${{ inputs.report }} ${{ inputs.ref_report }} >> $GITHUB_STEP_SUMMARY
+        node scripts/checks/compare-gas-reports.js ${{ inputs.report }} ${{ inputs.ref_report }} >> $GITHUB_STEP_SUMMARY
       env:
         STYLE: markdown
       shell: bash

.github/actions/setup/action.yml

@@ -8,7 +8,7 @@ inputs:
   foundry:
     description: Whether to set up Foundry
     required: false
-    default: 'on' # 'off' | 'on' | <specific version>
+    default: 'off' # 'off' | 'on' | <specific version>
   java:
     description: Whether to set up Java
     required: false

.github/actions/storage-layout/action.yml

@@ -37,9 +37,8 @@ runs:
         GITHUB_TOKEN: ${{ inputs.token }}
       shell: bash
       continue-on-error: true
-      id: reference
     - name: Compare layouts
-      if: steps.reference.outcome == 'success' && github.event_name == 'pull_request'
+      if: github.event_name == 'pull_request' && hashFiles(inputs.ref_layout) != ''
       run: |
         node scripts/checks/compare-layout.js --head ${{ inputs.layout }} --ref ${{ inputs.ref_layout }}
       shell: bash

.github/workflows/checks.yml

@@ -35,10 +35,14 @@ jobs:
       GAS: true
     steps:
       - uses: actions/checkout@v6
+        with:
+          submodules: recursive
       - name: Set up environment
         uses: ./.github/actions/setup
+        with:
+          foundry: 'on' # needed by npm run test:pragma
       - name: Run tests and generate gas report
-        run: npm run test
+        run: npm run test -- --gas-stats-json gasReport.json
       - name: Check linearisation of the inheritance graph
         run: npm run test:inheritance
       - name: Check pragma validity
@@ -49,6 +53,7 @@ jobs:
         uses: ./.github/actions/gas-compare
         with:
           token: ${{ github.token }}
+          report: gasReport.json
 
   tests-upgradeable:
     runs-on: ubuntu-latest
@@ -57,9 +62,12 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
+          submodules: recursive
           fetch-depth: 0 # Include history so patch conflicts are resolved automatically
       - name: Set up environment
         uses: ./.github/actions/setup
+        with:
+          foundry: 'on' # needed by npm run test:pragma
       - name: Copy non-upgradeable contracts as dependency
         run: |
           mkdir -p lib/openzeppelin-contracts
@@ -78,21 +86,12 @@ jobs:
         with:
           token: ${{ github.token }}
 
-  tests-foundry:
+  coverage:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
         with:
           submodules: recursive
-      - name: Set up environment
-        uses: ./.github/actions/setup
-      - name: Run tests
-        run: forge test -vvv
-
-  coverage:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
       - name: Set up environment
         uses: ./.github/actions/setup
       - name: Run coverage
@@ -105,6 +104,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+        with:
+          submodules: recursive
       - name: Set up environment
         uses: ./.github/actions/setup
       - name: Compile harnesses

.github/workflows/formal-verification.yml

@@ -55,6 +55,7 @@ jobs:
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
+          foundry: 'on'
           python: 'on'
           python-requirements: 'fv-requirements.txt'
       - name: Run Halmos

foundry.toml

@@ -6,15 +6,4 @@ optimizer_runs = 200
 src = 'contracts'
 out = 'out'
 libs = ['node_modules', 'lib']
-test = 'test'
 cache_path  = 'cache_forge'
-fs_permissions = [{ access = "read", path = "./node_modules/hardhat-predeploy/bin" }]
-
-[lint]
-exclude_lints = ["mixed-case-function", "asm-keccak256", "screaming-snake-case-immutable", "incorrect-shift", "mixed-case-variable"]
-ignore = ["./contracts/interfaces/**/*.sol", "./contracts/mocks/Stateless.sol"]
-lint_on_build = false
-
-[fuzz]
-runs = 5000
-max_test_rejects = 150000

hardhat.config.ts

@@ -0,0 +1,95 @@
+import { defineConfig } from 'hardhat/config';
+
+// Plugins
+import hardhatEthers from '@nomicfoundation/hardhat-ethers';
+import hardhatEthersChaiMatchers from '@nomicfoundation/hardhat-ethers-chai-matchers';
+import hardhatIgnoreWarnings from 'hardhat-ignore-warnings';
+import hardhatMocha from '@nomicfoundation/hardhat-mocha';
+import hardhatNetworkHelpers from '@nomicfoundation/hardhat-network-helpers';
+import hardhatPredeploy from 'hardhat-predeploy';
+import hardhatExposed from './hardhat/hardhat-exposed/plugin.ts';
+import hardhatTranspiler from './hardhat/hardhat-transpiler/plugin.ts';
+import hardhatOzContractsHelpers from './hardhat/hardhat-oz-contracts-helpers/plugin.ts';
+import './hardhat/async-test-sanity.js';
+
+// Parameters
+import yargs from 'yargs/yargs';
+const argv = await yargs()
+  .env('')
+  .options({
+    compiler: { type: 'string', default: '0.8.31' },
+    src: { type: 'string', default: 'contracts' },
+    runs: { type: 'number', default: 200 },
+    ir: { type: 'boolean', default: false },
+    evm: { type: 'string', default: 'osaka' },
+  })
+  .parse();
+
+// Configuration
+export default defineConfig({
+  plugins: [
+    // Imported plugins
+    hardhatEthers,
+    hardhatEthersChaiMatchers,
+    hardhatIgnoreWarnings,
+    hardhatMocha,
+    hardhatNetworkHelpers,
+    hardhatPredeploy,
+    // Local plugins
+    hardhatExposed,
+    hardhatTranspiler,
+    hardhatOzContractsHelpers,
+  ],
+  paths: {
+    sources: argv.src,
+  },
+  solidity: {
+    version: argv.compiler,
+    settings: {
+      optimizer: {
+        enabled: true,
+        runs: argv.runs,
+      },
+      evmVersion: argv.evm,
+      viaIR: argv.ir,
+      outputSelection: { '*': { '*': ['storageLayout'] } },
+    },
+  },
+  networks: {
+    default: {
+      type: 'edr-simulated',
+      hardfork: argv.evm,
+      // Exposed contracts often exceed the maximum contract size. For normal contract,
+      // we rely on the `code-size` compiler warning, that will cause a compilation error.
+      allowUnlimitedContractSize: true,
+    },
+  },
+  test: {
+    solidity: {
+      fuzz: {
+        runs: 5000,
+        maxTestRejects: 150000,
+      },
+      fsPermissions: {
+        readDirectory: ['node_modules/hardhat-predeploy/bin'],
+      },
+    },
+  },
+  warnings: {
+    'npm/**/*': 'off',
+    'test/**/*': 'off',
+    'contracts-exposed/**/*': {
+      'code-size': 'off',
+      'initcode-size': 'off',
+    },
+    '*': {
+      'transient-storage': 'off',
+      default: 'error',
+    },
+  },
+  exposed: {
+    initializers: true,
+    include: ['contracts/**/*.sol'],
+    exclude: ['**/*WithInit.sol'],
+  },
+});

hardhat/hardhat-exposed/hook-handlers/clean.ts

@@ -0,0 +1,9 @@
+import fs from 'node:fs/promises';
+
+import type { CleanHooks } from 'hardhat/types/hooks';
+
+export type * from '../type-extensions.ts';
+
+export default async (): Promise<Partial<CleanHooks>> => ({
+  onClean: context => fs.rm(context.config.exposed.outDir, { recursive: true, force: true }),
+});