메뉴
Migrate a Solidity project from Foundry to Hardhat 3. Maps `foundry.toml` to `hardhat.config.ts`, converts dependencies and imports, gets compilation and Solidity tests passing, and produces a migration report with feature-parity gaps and a cleanup checklist.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | migrate-foundry-to-hardhat |
| description | Migrate a Solidity project from Foundry to Hardhat 3. Maps `foundry.toml` to `hardhat.config.ts`, converts dependencies and imports, gets compilation and Solidity tests passing, and produces a migration report with feature-parity gaps and a cleanup checklist. |
| disable-model-invocation | true |
| argument-hint | [update | optional notes about the project] |
If the argument is update, skip to the Update an existing migration section below.
The goal is to get Hardhat compilation and Solidity tests passing, identify any blockers and missing features, and leave the user with a clear cleanup checklist for the original Foundry files. This involves config mapping, dependency conversion, import fixes, compilation, and test verification.
Important: Identifying blockers and missing Hardhat features relative to Forge is a primary goal of this migration. Do not overlook or guess at feature mappings. If a Forge feature has no clear Hardhat equivalent, do not silently skip it — leave a TODO comment in the config or code, link to a tracking issue if one exists, and flag it in the final migration report.
Foundry file preservation: Do NOT delete foundry.toml, foundry.lock, remappings.txt, lib/, or .gas-snapshot during the migration. The user needs them to cross-check results against Forge and roll back if needed. The final migration report contains a Foundry cleanup checklist that lists which files the user can delete once they've verified Hardhat works end-to-end — the user actions that checklist manually.
For package.json scripts: replace the convertible forge-based scripts (test, build, coverage, snapshot, snapshot:check) with their Hardhat equivalents under the same script name. Leave Forge-only scripts intact (e.g., forge script, forge bind, forge verify-contract) — they continue to work as long as Foundry is installed, and the report lists them as Foundry-only gaps the user must address before deleting foundry.toml.
Follow these steps in order. Do not skip ahead — each step depends on the previous one succeeding.
Before making changes, read and understand the existing project thoroughly:
foundry.toml — note ALL configured profiles and settings. Do not overlook any section.remappings.txt if it existslib/ — run ls lib/ and read .gitmodules if present. Ensure submodules are initialized — run git submodule update --init --recursive. Compilation will fail if submodule directories are empty.src/ or contracts/)test/ or tests/)script/.t.sol files for inline test config — forge-config: directives in both line comments (/// forge-config:, // forge-config:) and block comments (/** forge-config: ... */). Since Hardhat 3.3.0, inline config is supported at the function level and forge-config: is backwards-compatible (docs). Hardhat 3.5.0 / EDR 0.12.0-next.33 added function-level support for isolate and evm_version (edr#1349 closed). However, Hardhat only supports function-level inline config — contract-level inline config (directives placed on the contract definition rather than individual functions) is NOT supported. For contract-level configs, the workaround is to set the value globally in hardhat.config.ts. Flag any files using contract-level directives.package.json scripts — read every script entry and identify all Forge-dependent commands (not just forge test / forge build). Custom scripts using forge bind, forge script, forge snapshot, forge verify-contract, etc. represent additional Forge features the project actively uses. List them in the analysis file — they must appear in the feature parity table.foundry.toml for zkSync profiles (e.g., [profile.zksync]) and scan for zkSync-specific contract directories (contracts/zkSync/, contracts/zk*/, src/zkSync/, etc.). Assess what percentage of the codebase these contracts represent (file count relative to total .sol files). zkSync compilation settings and contracts may not be testable under Hardhat — flag them for the migration report.yarn.lock, package-lock.json, pnpm-lock.yaml) and note the corresponding tool (yarn, npm, pnpm). If no lockfile exists, use pnpm as the default. If multiple lockfiles exist, pick the one that is more recently modified OR has more dependencies defined — whichever gives the clearest signal. Check modification timestamps with ls -lt yarn.lock package-lock.json pnpm-lock.yaml 2>/dev/null and line counts with wc -l. Document the choice and the reason in the analysis file. Do not introduce a second lockfile. Lock in this choice — use it for every install command throughout the session (including patch-package steps). Never mix package managers.IMPORTANT: Migrating all configurations is KEY to the migration succeeding. Every section of foundry.toml must be accounted for — either mapped to a Hardhat equivalent, or explicitly documented as unsupported with a comment and issue link.
After analyzing, write a structured summary to a file named hardhat-migration/<project-name>-foundry-migration-analysis.md (where <project-name> is the directory name of the project being migrated) in the repository root. Create the hardhat-migration/ directory if it doesn't exist. The file includes:
foundry.toml section and setting found[profile.default], [profile.ci], etc.) and their settingsforge-config: comments) — list affected files and which inline settings are used, noting whether each directive is at the function level (supported in Hardhat 3.5.0+, including isolate / evm_version per edr#1349) or contract level (NOT supported in Hardhat — must be set globally).package.json scripts identified in step 8 aboveThis file serves as a reference throughout the migration so you don't have to re-read foundry.toml repeatedly. Present the summary to the user before proceeding.
Package manager: Use the package manager determined in Step 1.
Fetch the latest Hardhat version: Run view hardhat version using the package manager determined in Step 1 (e.g. pnpm view hardhat version), and note the version string returned. If the command fails, fall back to 3.9.0.
Edit package.json:
"hardhat": "^<latest-version>" to devDependencies, using the version fetched above."@nomicfoundation/hardhat-verify": "^3.0.11" to devDependencies (if [etherscan] section exists)"hardhat-ignore-warnings": "^0.3.0" to devDependencies (if ignored_warnings_from is set in foundry.toml) — see "Compiler warning suppression" in Step 3 for the matching config."type": "module" is set. Note: This switches the project to ESM, which is required by Hardhat 3. If the project has existing CommonJS files (.js with require()), this may break them — flag it to the user if so.forge-based scripts (test, build, coverage, snapshot, snapshot:check) with their Hardhat equivalents under the same script name — do NOT add a parallel -hardhat-suffixed entry. The original Forge commands remain recoverable from git history.forge script, forge bind, forge verify-contract, custom forge invocations). They continue to work as long as Foundry is installed; the migration report lists them as Foundry-only gaps the user must address before deleting foundry.toml.scripts section, or only non-Forge scripts like lint, prettier), do not add any Hardhat scripts to package.json.Common script replacements (replace in-place under the same key):
| Existing Foundry script | Replace with |
|---|---|
"test": "forge test" | "test": "hardhat test solidity" |
"build": "forge build" | "build": "hardhat compile" |
"coverage": "forge coverage ..." | "coverage": "hardhat test solidity --coverage" |
"snapshot": "forge snapshot ..." | "snapshot": "hardhat test solidity --snapshot" |
"snapshot:check": "forge snapshot --check ..." | "snapshot:check": "hardhat test solidity --snapshot-check" |
Note on coverage: Hardhat 3 has built-in coverage support (no plugin needed). The --coverage flag produces LCOV (coverage/lcov.info) and HTML (coverage/html/index.html) reports. Reference: https://hardhat.org/docs/tutorial/coverage
Then install dependencies using the package manager determined above. If the project has a postinstall script that runs Forge commands (e.g., forge install), use --ignore-scripts to skip it — it's unnecessary for the Hardhat migration and may be slow or fail. For yarn: yarn install --ignore-scripts. For npm: npm install --ignore-scripts. For pnpm: pnpm install --ignore-scripts.
Finally, add Hardhat's output directories to .gitignore if not already present:
# Hardhat
artifacts/
cache/
Create hardhat.config.ts by mapping settings from foundry.toml. Use the reference tables below for known mappings.
defineConfig()Always use defineConfig() — it is the recommended pattern across all Hardhat 3 documentation. Do NOT use the HardhatUserConfig type annotation approach (a Hardhat 2-era pattern that still compiles but is not the documented way to configure Hardhat 3).
When using plugins (e.g. hardhat-verify), pass them in the plugins array:
import { configVariable, defineConfig } from "hardhat/config";
import hardhatVerify from "@nomicfoundation/hardhat-verify";
export default defineConfig({
plugins: [hardhatVerify],
solidity: { ... },
networks: { ... },
verify: { ... }, // typed correctly via plugin
});
When no plugins are needed:
import { defineConfig } from "hardhat/config";
export default defineConfig({
solidity: { ... },
});
solidity)Map these from [profile.default] in foundry.toml:
| foundry.toml | hardhat.config.ts |
|---|---|
solc = "0.8.X" or solc_version = "0.8.X" | solidity.compilers[0].version: "0.8.X" |
optimizer = true | solidity.compilers[0].settings.optimizer.enabled: true |
optimizer_runs = 200 | solidity.compilers[0].settings.optimizer.runs: 200 |
evm_version = "cancun" | solidity.compilers[0].settings.evmVersion: "cancun" |
via_ir = true | solidity.compilers[0].settings.viaIR: true |
bytecode_hash = "none" | solidity.compilers[0].settings.metadata.bytecodeHash: "none" |
src = "src" | paths.sources: "./src" |
test = "tests" | paths.tests: "./tests" |
IMPORTANT — solidity structure rules:
overrides, you MUST use the compilers array format. The top-level version field is incompatible with overrides.profiles, you CANNOT have top-level compilers or version — all compiler config must live inside named profiles. A default profile is required.// WRONG — overrides + version are incompatible
solidity: { version: "0.8.28", overrides: { ... } }
// WRONG — top-level compilers + profiles are incompatible
solidity: { compilers: [...], profiles: { ... } }
// CORRECT — without profiles, use compilers array with overrides
solidity: { compilers: [{ version: "0.8.28", settings: { ... } }], overrides: { ... } }
// CORRECT — with profiles, put everything inside named profiles (default is required)
solidity: { profiles: { default: { compilers: [...] }, production: { compilers: [...], overrides: { ... } } } }
solidity.profiles)Foundry's [profile.*] sections, additional_compiler_profiles, and compilation_restrictions map to Hardhat's build profiles system.
When to use profiles vs plain compilers:
solidity.profiles when foundry.toml has multiple [profile.*] sections with different compiler settings (e.g., [profile.debug] changes via_ir or optimizer_runs). A default profile is required.solidity.compilers (without profiles) when there is only [profile.default] and no other profiles change compiler settings. Profiles that only override test settings (like [profile.pr.fuzz]) do not count — they have no Hardhat build profile equivalent.Create ALL Foundry profiles that have compiler settings — do not leave any unmigrated with a TODO comment if they can be expressed in Hardhat. Every [profile.*] section with compiler settings (optimizer, viaIR, optimizer_details, etc.) must become a named Hardhat build profile.
Reference: https://hardhat.org/docs/guides/writing-contracts/build-profiles
| Foundry concept | Hardhat 3 equivalent |
|---|---|
[profile.default] base settings | solidity.profiles.default (required when using profiles) |
additional_compiler_profiles + compilation_restrictions | solidity.profiles.<name>.overrides with exact file paths |
[profile.coverage] compiler settings | solidity.profiles.coverage |
Key limitations:
[profile.pr.fuzz] or [profile.ci.fuzz] that only change test settings have no direct equivalent — use env vars or CLI args. For settings that can't be expressed in Hardhat profiles (fuzz runs, gas snapshots, isolate, etc.), use the values from [profile.default] in the top-level test.solidity config and leave a comment explaining that the other Foundry profiles (pr, ci, coverage, gas) override these values but Hardhat profiles don't support test settings.[profile.debug] sets via_ir = false AND fuzz.runs = 100), create the Hardhat build profile with only the compiler settings and add a // TODO: comment for the test settings that cannot be included.**) in overrides. Each file must be listed individually. See: https://github.com/NomicFoundation/hardhat/issues/4686Usage: npx hardhat compile --build-profile production
DRY principle for profiles: When multiple profiles share most compiler settings, extract the common settings into a local variable to avoid duplication:
const baseCompilerSettings = {
optimizer: { enabled: true, runs: 1000000 },
evmVersion: "shanghai" as const,
viaIR: true,
};
export default defineConfig({
solidity: {
profiles: {
default: {
compilers: [{ version: "0.8.23", settings: baseCompilerSettings }],
},
lite: {
compilers: [
{
version: "0.8.23",
settings: {
...baseCompilerSettings,
optimizer: {
...baseCompilerSettings.optimizer,
details: { yulDetails: { optimizerSteps: "" } },
},
},
},
],
},
},
},
});
test.solidity)Map these from [profile.default] or [fuzz]/[invariant] sections:
| foundry.toml | hardhat.config.ts |
|---|---|
fuzz.runs = 256 | test.solidity.fuzz.runs: 256 |
fuzz.seed = "0x640" | test.solidity.fuzz.seed: "0x640" |
fuzz.max_test_rejects = 65536 | test.solidity.fuzz.maxTestRejects: 65536 |
fuzz.dictionary_weight = 40 | test.solidity.fuzz.dictionaryWeight: 40 |
invariant.runs = 256 | test.solidity.invariant.runs: 256 |
invariant.depth = 500 | test.solidity.invariant.depth: 500 |
invariant.fail_on_revert = false | test.solidity.invariant.failOnRevert: false |
ffi = true | test.solidity.ffi: true |
block_gas_limit | test.solidity.blockGasLimit |
gas_limit = N | test.solidity.gasLimit: Nn (must be bigint, use n suffix) |
fs_permissions = [{ access = "read", path = "./file" }] | test.solidity.fsPermissions: { readFile: ["./file"] } |
fs_permissions = [{ access = "write", path = "./file" }] | test.solidity.fsPermissions: { writeFile: ["./file"] } |
fs_permissions = [{ access = "read-write", path = "./file" }] | test.solidity.fsPermissions: { readWriteFile: ["./file"] } |
fs_permissions = [{ access = "read", path = "./dir" }] | test.solidity.fsPermissions: { readDirectory: ["./dir"] } |
fs_permissions = [{ access = "write", path = "./dir" }] | test.solidity.fsPermissions: { dangerouslyWriteDirectory: ["./dir"] } |
fs_permissions = [{ access = "read-write", path = "./dir" }] | test.solidity.fsPermissions: { dangerouslyReadWriteDirectory: ["./dir"] } |
allow_internal_expect_revert = true | test.solidity.allowInternalExpectRevert: true |
isolate = true | test.solidity.isolate: true |
[bind_json] include = ["path/to/EIP712Types.sol"] | test.solidity.eip712Types: { include: ["path/to/EIP712Types.sol"] } (Hardhat 3.5.0+) — see "EIP-712 cheatcodes" reference section |
Note on isolate: The global isolate = true in foundry.toml maps to test.solidity.isolate: true. Function-level inline /// forge-config: default.isolate = true overrides are supported as of Hardhat 3.5.0 / EDR 0.12.0-next.33 (edr#1349 closed). Contract-level inline isolate directives are still silently ignored. Do NOT set isolate globally as a workaround for contract-level usage — it dramatically slows down the entire test suite. Only set it globally if foundry.toml has isolate = true at the [profile.default] level (meaning it was already global in Forge). If only specific contracts use contract-level inline isolate, document it as a gap.
Note on inline config scope: Hardhat only supports inline forge-config: directives at the function level (on individual test functions). Foundry also supports contract-level inline config (directives placed on the contract definition, which apply to all functions in that contract). Contract-level directives are silently ignored by Hardhat.
When to apply global workarounds for unsupported inline config: Not all settings are safe to set globally. Evaluate the side effects before applying a global workaround:
allowInternalExpectRevert — enabling this globally is harmless; it only changes behavior when vm.expectRevert is used on internal/library calls, and enabling it on tests that don't use that pattern has no effect.isolate — this forces each test call to run in a separate EVM context, which dramatically slows down the entire test suite. If only a few test contracts/functions use isolate, setting it globally would impose a major performance penalty on all tests. Do NOT set isolate globally as a workaround. Instead, leave it as a documented gap in the migration report.disableBlockGasLimit, etc. — consider whether enabling them globally changes behavior for tests that don't expect it. When in doubt, do NOT set globally; document as a gap instead. (Note: evm_version is supported inline at function level since 3.5.0; only contract-level scope or global needs would force a workaround.)The guiding principle: only apply a global workaround if it is behaviorally neutral for tests that don't use the setting. If a global setting would change behavior or performance for unrelated tests, leave it as a gap.
fsPermissions key distinction: readFile/writeFile/readWriteFile use exact path matching (single file). readDirectory/dangerouslyWriteDirectory/dangerouslyReadWriteDirectory use prefix matching (recursive directory access). Use the directory variants when the Foundry path points to a directory.
Note: This table is not exhaustive. Hardhat 3 may support additional test settings not listed here. When encountering a Foundry test setting without a mapping in this table, check the Hardhat 3 documentation and the TypeScript type definitions in node_modules/hardhat/src/internal/builtin-plugins/solidity-test/type-extensions.ts before concluding it has no equivalent.
networks)Map [rpc_endpoints] from foundry.toml. Use configVariable() for environment variables (lazy resolution — only resolved when needed).
Note: Foundry uses "${VAR_NAME}" syntax for env vars. Strip the ${} wrapper when passing to configVariable("VAR_NAME").
Tip: The chainId for each network can often be found in the [etherscan] section of the same foundry.toml.
| foundry.toml | hardhat.config.ts |
|---|---|
[rpc_endpoints] mainnet = "${RPC_MAINNET}" | networks.mainnet: { type: "http", chainId: 1, url: configVariable("RPC_MAINNET") } |
configVariable() also supports a format parameter for URL templates:
url: configVariable(
"ALCHEMY_API_KEY",
"https://eth-mainnet.g.alchemy.com/v2/{variable}",
);
Reference: https://hardhat.org/docs/reference/configuration#network-configuration
verify)Map [etherscan] from foundry.toml. In Foundry, this section configures API keys for contract verification via forge verify-contract and forge create --verify (ref: https://book.getfoundry.sh/reference/config/etherscan). Requires the @nomicfoundation/hardhat-verify plugin in Hardhat 3.
IMPORTANT: Hardhat 3 uses Etherscan API v2 which requires a single API key for all supported chains. Foundry often has per-chain keys (ETHERSCAN_API_KEY_MAINNET, etc.). Document this difference with a comment.
verify: {
etherscan: {
apiKey: configVariable("ETHERSCAN_API_KEY"),
},
},
warnings)Map ignored_warnings_from from foundry.toml to the hardhat-ignore-warnings plugin. The plugin is HH3-compatible (peerDependencies: { hardhat: "^3.1.0" } as of v0.3.0). Add it to devDependencies per Step 2.
Foundry's ignored_warnings_from = ["lib/foo", "src/legacy"] silences all compiler warnings originating from the listed paths. Hardhat 3 has no built-in equivalent — the plugin provides path-keyed suppression via a top-level warnings field.
Register the plugin and translate each path into a glob key with { default: "off" }:
import { defineConfig } from "hardhat/config";
import hardhatIgnoreWarnings from "hardhat-ignore-warnings";
export default defineConfig({
plugins: [hardhatIgnoreWarnings],
solidity: { ... },
warnings: {
"lib/foo/**/*": { default: "off" },
"src/legacy/**/*": { default: "off" },
},
});
Path-to-glob conversion:
"lib/foo") become "lib/foo/**/*" to match every file under that directory recursively."src/legacy/Old.sol") stay as-is — no glob suffix needed.When combining with other plugins (e.g., hardhat-verify), pass them all in the plugins array.
Beyond ignored_warnings_from: The plugin also supports warning-code-specific rules (e.g., 'unused-param': 'off') and inline // solc-ignore-next-line <code> comments. Foundry has no equivalent for those — they're additional capabilities the user gains by adopting the plugin, not part of the mapping.
These foundry.toml settings and commands have no direct Hardhat equivalent. Leave a comment in hardhat.config.ts for each one present in the project.
Important: Presence in this table does NOT mean the feature should be classified as 🚩 Gap in the migration report. Each row includes a Status that indicates the actual parity level — many have workarounds, partial support, or are tools that work standalone regardless of build system. Use the Status column to determine the correct parity classification.
| foundry.toml | Status |
|---|---|
dynamic_test_linking | Foundry-only |
gas_snapshot_check / [profile.gas] | Supported (✅ Full) — npx hardhat test solidity --snapshot / --snapshot-check; gas values match Forge. Caveat (not a gap): Hardhat's whole-suite .gas-snapshot uses a Contract#function format incompatible with Forge's Contract:function() (by design), so --snapshot-check against a committed Forge-format .gas-snapshot errors with HHE803 — regenerate the baseline with --snapshot. See Update Step 5b "KEY FACT" and hardhat#8357. Docs: https://hardhat.org/docs/guides/testing/gas-snapshots |
[bind_json] | 🟡 Partial — the include field has a direct Hardhat equivalent in test.solidity.eip712Types.include (added in Hardhat 3.5.0). Both tools require the user to point at the file(s) defining EIP-712 structs so vm.eip712HashStruct / vm.eip712HashType can resolve names. Hardhat does NOT emit a JsonBindings.sol-style helper file — if any Solidity file in the project imports schema_* constants or serialize/deserialize helpers from the generated file, that part has no Hardhat equivalent (grep for JsonBindings imports / schema_ usage to confirm before classifying). See the "EIP-712 cheatcodes" reference section below. |
[fmt] | 🟡 Partial — forge fmt works standalone regardless of build tool; prettier-plugin-solidity is a mature alternative |
[lint] | Foundry-only (projects typically use prettier or solhint) |
forge doc | 🟡 Partial — community plugin @solarity/hardhat-markup supports HH3 for NatSpec documentation generation |
out = "out" | Hardhat uses its own artifacts/ + cache/ dirs |
libs = ["lib"] | Hardhat resolves lib/ deps via remappings.txt; npm deps via Node.js resolution |
[profile.zksync] / zkSync compilation (--zksync, fallback_oz, is_system, mode) | Foundry-only — check whether @matterlabs/hardhat-zksync supports HH3 (as of early 2026 it targets HH2 only). If not, zkSync contracts compile but can't be meaningfully tested |
/// forge-config: inline test config | 🟡 Partially supported — function-level only. forge-config: prefix is backwards-compatible. Fuzz/invariant settings and allowInternalExpectRevert have worked inline at function level since Hardhat 3.3.0; isolate and evm_version were added in Hardhat 3.5.0 / EDR 0.12.0-next.33 (edr#1349 closed). Contract-level inline config (directives on contract definitions) is NOT supported in any Hardhat 3 release — use global config as workaround. See: docs |
forge coverage --ir-minimum | Not needed — Hardhat 3's built-in --coverage handles via-IR projects natively without a separate flag. Note: coverage instrumentation may cause some tests to fail that pass without coverage — these are coverage-specific and should be investigated separately. |
Note: This table is not exhaustive. Before concluding a Foundry setting has no Hardhat equivalent, check test.solidity type definitions in node_modules/hardhat/src/internal/builtin-plugins/solidity-test/type-extensions.ts and the Hardhat 3 documentation.
If you encounter foundry.toml settings that don't have a clear mapping in the tables above:
solidity.settings (which accepts any solc input JSON option)test.solidityDo not assume mappings without documentation. When uncertain about what a Foundry setting does, look up the Foundry docs (https://book.getfoundry.sh/reference/config/) before mapping it to a Hardhat equivalent.
For any foundry.toml setting that cannot be mapped due to Hardhat limitations:
// TODO: comment in hardhat.config.ts describing the original Foundry settingAfter mapping all explicit foundry.toml settings, consult the "Reference: Forge vs Hardhat 3 default values" table at the bottom of this file. For every setting where Forge's default differs from Hardhat's default, explicitly set that value in hardhat.config.ts — even if the setting is absent from foundry.toml.
For example: if foundry.toml does not set optimizer or src, Forge still defaults to optimizer = true and src = "src". Hardhat's defaults are different (optimizer off, paths.sources = "./contracts"), so these must be explicitly configured to preserve the same behavior.
After finishing the config migration, briefly confirm with the user which settings were migrated, which are Foundry-only, and which have gaps — before moving on to Step 4. The full detailed report is presented in Step 7.
Hardhat 3 does not support absolute imports in .sol files. Scan all .sol files for absolute imports (imports that don't start with ./, ../, or a package name like @openzeppelin/).
Common patterns to look for:
import "src/SomeContract.sol";import "contracts/SomeContract.sol";import "test/helpers/SomeHelper.sol";import "lib/some-dep/SomeFile.sol";How to find absolute imports: Absolute imports come in two Solidity syntaxes. Search for both:
import "src/...";import { Foo } from "src/...";Use a regex like import\s.*["'](src|test|lib|contracts)/ to catch both forms and both quote styles (Solidity allows single or double quotes for import paths). Make sure to search all directories that contain .sol files, including examples/, script/, and any other non-standard directories — not just src/ and test/.
Count the number of files containing absolute imports (not the number of import statements):
remappings.txt file (e.g., src/=./src/, tests/=./tests/, lib/=./lib/). This is simpler than creating scoped remappings in subdirectories and works for all files.Note: This is a heuristic, not a strict threshold. When the count is close to the limit (e.g., 8–12 files), use your judgement. Consider the overall complexity of the changes, how many imports per file, and whether the project already uses remappings extensively. When in doubt, prefer relative imports — they are more portable and don't add implicit resolution rules.
Reference: https://hardhat.org/docs/cookbook/absolute-imports
IMPORTANT: Only compile and test using the default build profile. Non-default profiles (production, coverage, etc.) are migrated for completeness but should NOT be compiled or tested during this migration session. They may require environment-specific tooling (e.g., native solc for viaIR) that isn't available.
Run and store the output:
npx hardhat compile --show-stack-traces 2>&1 | tee /tmp/hardhat-compile-output.txt
Do NOT run npx hardhat compile --build-profile production or any other profile.
Output caching: If /tmp/hardhat-compile-output.txt already exists, analyze whether any relevant changes have been made since it was written. If not, read the stored file instead of re-running the command. Only re-run when it is justified. When re-running, state in your response what was fixed and why the re-run is necessary before issuing the command — e.g., "Added lib/=./lib/ remapping to fix HHE902 error on absolute lib imports — re-compiling."
If compilation fails, group errors by type before presenting them to the user. Then:
HHE902: ... is not exported by the package, see the "npm packages with restrictive exports fields" reference sectionDo not proceed to Step 6 until compilation passes cleanly.
Run and store the output:
npx hardhat test solidity --show-stack-traces 2>&1 | tee /tmp/hardhat-test-output.txt
Do NOT run tests with non-default build profiles.
Output caching: If /tmp/hardhat-test-output.txt already exists, analyze whether any relevant changes have been made since it was written. If not, read the stored file instead of re-running the command. Only re-run when it is justified. When re-running, state in your response what was fixed and why the re-run is necessary before issuing the command — e.g., "Commented out UnsupportedCheatcode tests — re-running to confirm remaining tests pass."
If tests fail:
UnsupportedCheatcode errors:
Error: UnsupportedCheatcode: vm.xyz(...). Do NOT comment out tests that fail with any other error type — even if those errors appear migration-related. All other failures must be handled via items 4–6 below (fix or flag to the user).UnsupportedCheatcode error, comment out the entire function (signature + body) using // line comments, and preserve the original code as commented-out lines so the disabled test remains readable. Use /* */ block comments only if the function body itself contains no block comments. Prefer // line comments in all cases to avoid nesting issues.// HARDHAT-SKIP: This test uses vm.xyz() which is not supported by Hardhat 3 (UnsupportedCheatcode).
// See: https://github.com/NomicFoundation/hardhat/issues/XXXX
// function test_foo() public {
// vm.xyz("some", abi.encode(param));
// assertEq(result, expected);
// }
test_foo() would pass trivially and give a false green — the test must not run at all.UnsupportedCheatcode nor fixable by editing the config — they indicate a behavioral difference or outright bug in Hardhat / EDR. These tests should not be modified, commented out, or worked around — the test code is correct Foundry-idiomatic code.hardhat-migration/bugs/<descriptive-slug>.md (create the hardhat-migration/bugs/ directory if needed). Use a slug that describes the affected feature or cheatcode — do NOT prefix with edr- or hardhat- (e.g. vm-readCallers-prank-state.md, not edr-vm-readCallers-prank-state.md). The responsible layer will be determined through the upstream filing process. The file should include:
hardhat.config.ts)Common error patterns and fixes:
"call didn't revert at a lower depth than cheatcode call depth" or "reverted with an unrecognized custom error" on tests using vm.expectRevert on internal/library calls → enable test.solidity.allowInternalExpectRevert: true in config (maps Foundry's allow_internal_expect_revert)test.solidity.gasLimit matches foundry.toml's gas_limit (must be a bigint with n suffix)vm.envString: environment variable "X" not found — tests that read env vars via vm.envString() or vm.envOr() in setUp() will fail if those vars aren't set. Fix: set the required env var in the Hardhat test script in package.json (e.g., "test": "MY_VAR=value hardhat test solidity")When tests pass, always show the full test output to the user so they can verify the results themselves.
Coverage verification (optional): If the project has a forge coverage script in package.json, run npx hardhat test solidity --coverage after tests pass to verify coverage works. Coverage instrumentation can reveal issues not seen in normal test runs. Compare the number of passing tests with and without --coverage — any discrepancy should be noted in the migration report. Note: Hardhat 3's coverage handles via-IR projects natively; Forge's --ir-minimum flag has no equivalent and is not needed.
Gas snapshot verification (optional): If the project uses gas snapshot cheatcodes (grep .t.sol files for vm.snapshotGasLastCall, vm.startSnapshotGas, vm.stopSnapshotGas), verify the feature works using the procedure in Update Step 5b. The same three-case logic applies — restore any snapshot files written during the check so the migration doesn't leave them modified. If the project doesn't use any of those cheatcodes, skip this step.
After compilation and tests complete (whether all pass or not), write the report to hardhat-migration/<project-name>-hardhat-migration-report.md in the repository root and present it to the user. The report must assess feature parity between Forge and Hardhat for this project and give a clear verdict.
Report structure: The report uses numbered ## sections. Conditional sections are omitted when empty — remaining sections are numbered contiguously (no gaps). The possible sections in order are:
hardhat-migration/bugs/When conditional sections are omitted, renumber the remaining sections contiguously. For example, if there are no bug reports and no commented-out tests: 1. Test Count, 2. Feature Parity, 3. Workarounds, 4. Foundry Cleanup Checklist, 5. Next Steps.
Count the number of function test* declarations in .t.sol files under the test directory (ignore example/ and examples/ directories). Compare against the number of tests Hardhat actually ran. Flag any discrepancy.
The section is split into two parts to keep width manageable:
For each Forge feature used by the project, assess Hardhat 3 parity. Only include entries for features the project actually uses (check foundry.toml, package.json scripts, script/ directory, test files).
The Parity column uses four values — use them precisely, and always include the corresponding emoji:
hardhat-migration/bugs/IMPORTANT — verify before classifying as 🚩 Gap: Before marking any Forge feature as 🚩 Gap, check whether a Hardhat equivalent exists via:
--coverage)HH3 compatibility is a hard requirement. If a community plugin exists but only supports HH2 (peerDependencies does NOT include hardhat ^3.0.0), classify as 🚩 Gap (not 🟡 Partial). Mention the HH2 plugin in the Workaround / Notes column as context (e.g., "HH2 plugin exists: <package-name>"), but the parity rating must reflect what's usable with HH3 today. Check the HH2 plugin directory for plugins that may not yet have HH3 support. Only classify as 🟡 Partial if the plugin's peerDependencies actually includes hardhat ^3.0.0. Verify via the package manager (e.g., npm view <pkg> peerDependencies).
Order rows from most to least severe: ❌ Bug first, then 🚩 Gap, then 🟡 Partial.
IMPORTANT — cross-reference checkpoint: Before finalizing the gap table, re-read the analysis file from Step 1 and verify that every item is accounted for in the report — every Forge-dependent package.json script, every Foundry-only foundry.toml setting, every inline forge-config: usage, and every unsupported cheatcode must have a corresponding row in the gap table or an entry in the full parity list. Do not rely on memory — explicitly check each item off against the analysis file.
To ensure consistent gap reporting across different repos, always use the exact feature names below in the Feature column. Do not paraphrase, abbreviate, or add parenthetical clarifications — inconsistent naming prevents deduplication.
| Canonical feature name | When to use |
|---|---|
Built-in formatter | Forge's built-in formatter ([fmt] config section, forge fmt command) |
Documentation generator | Forge's documentation generator (forge doc) |
Deployment scripting | Deployment/scripting via .s.sol files (forge script, vm.startBroadcast()). Also use this name for vm.startBroadcast() / vm.stopBroadcast() gaps — these cheatcodes only function inside forge script and are not a separate feature |
ABI binding generation | ABI binding generation (forge bind --alloy, etc.) |
Gas snapshots | Gas snapshots (forge snapshot, gas_snapshot_check, .forge-snapshots/). Hardhat equivalent: --snapshot / --snapshot-check CLI flags |
Inline test config | Per-test overrides via /// forge-config: or /// hardhat-config: comments |
Etherscan verification | Contract verification via Etherscan ([etherscan] config) |
Gas reports | Gas reporting (forge test --gas-report, gas_reports in foundry.toml) |
Fuzz/invariant profile overrides | Per-profile fuzz/invariant settings ([profile.ci.fuzz], [profile.pr.fuzz], [profile.debug] fuzz/invariant overrides, etc.) |
Test path filtering | no_match_path, match_path, test exclusion patterns in config |
Glob overrides | Glob patterns (**) in compiler overrides |
Dynamic test linking | Dynamic test linking config (dynamic_test_linking in foundry.toml) |
Compiler warning suppression | Suppressing compiler warnings by source (ignored_warnings_from in foundry.toml) |
Memory limit | Per-test or global memory limit (memory_limit in foundry.toml) |
If a feature is not listed above, use a short, descriptive name that starts with the Forge command or config section name (e.g., forge verify-contract, [profile.solx]). Avoid adding parenthetical synonyms — pick one name and use it.
Use this 4-column format (the Forge and Hardhat 3 columns are implicit — omit them):
| Feature | Parity | Impact | Workaround / Notes |
|---|---|---|---|
vm.someCheatcode() | ❌ Bug | High — N tests failing; genuine blocker | Local bug report (not yet filed upstream) — test code not modified; fix needed in Hardhat / EDR |
vm.unsupported() | 🚩 Gap | High — M test instances disabled; layer X is untested | No tracking issue found — consider filing one; workaround: implement equivalent logic in a Solidity helper |
| Glob overrides | 🚩 Gap | Medium — per-file compiler overrides must be listed individually | #4686 — no glob (**) support; enumerate each file path |
| Etherscan verification | 🟡 Partial | Low — key model differs; minor CI update needed | Consolidate to a single ETHERSCAN_API_KEY — Etherscan API v2 accepts one key across all supported chains |
Note:
Gas snapshotsis not a gap example — Hardhat supports--snapshot/--snapshot-checkwith identical gas values. The whole-suite.gas-snapshotfile format was simply not designed to be Forge-compatible (see Update Step 5b KEY FACT), which is ✅ Full parity, not a gap.
The Impact cell must start with a severity word (High / Medium / Low) followed by an em-dash and a short explanation of what breaks.
List ✅ Full features as a bullet list under the subheading ### Full parity, preceded by the sentence "These features work equivalently in Hardhat 3:".
Example:
### Full parity
These features work equivalently in Hardhat 3:
- Solidity compilation (`forge build` → `npx hardhat compile`)
- forge-std cheatcodes (`vm.*`) — general
If inline test config was detected in Step 1, check which inline settings the project uses and at what level (function vs contract). Inline config is 🟡 Partial if the project uses contract-level inline config (directives on contract definitions) — Hardhat only supports function-level; contract-level directives are silently ignored. The workaround is to set the value globally in hardhat.config.ts.
List the affected files and specify which directives are at contract level. Only classify as ✅ Full parity if all inline directives are at function level. As of Hardhat 3.5.0 / EDR 0.12.0-next.33, supported function-level settings include all fuzz/invariant settings, allowInternalExpectRevert, isolate, and evm_version (edr#1349 closed).
If any UnsupportedCheatcode errors were encountered, add one row per distinct unsupported cheatcode to the gap table above.
For each 🚩 Gap and ❌ Bug, populate the Workaround / Notes column with a tracking issue link and/or a concrete suggested path forward. "No workaround currently" is a valid entry when none exists — don't leave the cell blank.
Before including any GitHub issue link, fetch the issue URL and confirm its title and description are actually related to the feature being documented. Do not guess issue numbers. If no relevant issue exists, write "No tracking issue found — consider filing one" instead of leaving the cell empty or inventing a link.
Distinguish local bug reports from upstream issues. When linking to a file in hardhat-migration/bugs/, use the link text "Local bug report" and add "(not yet filed upstream)" next to it — never "Bug report filed", which implies the issue has already been created in the upstream tracker. Only use "filed upstream" if you have actually opened a GitHub issue and have a real issue URL to link to.
Environment variables read by tests (e.g., via vm.envString) are a configuration concern, not a feature parity issue. Handle them by setting the required env vars in the Hardhat script definitions in package.json. Do NOT add them as rows in the gap table.
zkSync-specific profiles with dedicated contract variants (identified in Step 1, item 9) should be classified as 🚩 Gap with impact proportional to the percentage of codebase affected. When tests conditionally deploy different contracts depending on the active profile, the zkSync path is untested under Hardhat — flag this in the Impact column.
Check for duplicate or overlapping rows before finalizing the table. The same Forge feature can appear under multiple angles (e.g., per-profile vs per-file). Consolidate overlapping rows into one row in the gap table, with a Notes column that explains the combined limitation.
Only include this section if behavioral bugs were identified in Step 6 (item 4). If no bugs were found (no files written to hardhat-migration/bugs/), omit this section entirely from the report.
For each behavioral bug identified in Step 6 (item 4), reference the corresponding bug report file written to hardhat-migration/bugs/. These files are drafts the user can file upstream at NomicFoundation/hardhat or NomicFoundation/edr — the responsible layer depends on whether the root cause lies in Hardhat's test runner or in EDR. Use the heading ## N. Hardhat / EDR Bug Reports (where N is the next section number).
In the report:
[Local bug report](bugs/vm-foo-bar.md) (not yet filed upstream) — <one-line summary>The verdict for any session that produces a bug report is Failed.
List every non-obvious change made to get compilation/tests working:
patch-package) and whypnpm.overrides, npm overrides, yarn resolutions) and whyFor each workaround, explain the root cause — not just what was changed, but why it was necessary and how Forge avoids the same issue. When the workaround relates to a difference in how Forge and Hardhat 3 resolve dependencies, explain both resolution models (Forge's global remappings vs Hardhat 3's Node.js module resolution) so the reader understands why the workaround is needed and what it reproduces. Reference the relevant sections from this skill file (e.g., "Transitive dependency version conflicts", "npm packages with restrictive exports fields") for the underlying technical context.
Only include this section if test functions were actually commented out due to UnsupportedCheatcode errors. If no functions were commented out, omit this section entirely from the report. When included, number it as a sub-section of Workarounds Applied (e.g., ## 3b. or ## 4b. depending on the Workarounds section number).
List every test function that was fully commented out (signature + body) due to UnsupportedCheatcode errors. These functions do not appear in the Hardhat test run at all — they are not counted in the passing total. The discrepancy between Forge's test count and Hardhat's running count reflects the number of commented-out functions.
For each commented-out function, include:
Each distinct cheatcode that causes commented-out tests must have a corresponding row in the gap table (section 2) — the UnsupportedCheatcode section provides the per-function detail.
This section is the user's manual cleanup guide for the original Foundry files preserved during the migration. Do NOT auto-delete anything — present the list as a checklist the user actions themselves once they're confident Hardhat tests pass and they've cross-checked behavior against Forge.
For each item below, state explicitly whether it is safe to delete now, keep for now (with the reason), or delete after a specific follow-up (with the follow-up named). Inspect the project state — do not write the bullet generically.
foundry.toml — safe to delete once the user confirms they no longer need to run forge commands. If any Forge-only package.json scripts were left intact (see Workarounds Applied), list them here and note that foundry.toml must stay until those scripts are addressed.foundry.lock — same disposition as foundry.toml. Delete together.remappings.txt — check the current contents. If every remapping is still required by Hardhat (e.g., absolute-import remappings added in Step 4, submodule remappings for lib/), keep it and say so. If it only contained Foundry-style remappings to node_modules/ that Hardhat resolves natively, mark it deletable.lib/ — keep if any submodule dependencies were NOT replaced with npm packages (most projects). Only mark deletable if every submodule was migrated to an npm dependency..gas-snapshot — deletable once the user has regenerated snapshots via npx hardhat test solidity --snapshot. If the snapshot location was reconfigured, name the new path..github/workflows/* and other CI files — scan for steps that invoke forge (e.g., forge install, forge test, forge build). List the exact file and step name; the user updates them to call the replaced package.json scripts. Do not edit CI files automatically.package.json scripts left intact — list each one (e.g., "deploy": "forge script ...") and the Forge feature it represents (deployment scripting, ABI binding, etc.). These block deleting foundry.toml until the user either ports them to a Hardhat equivalent or accepts that Foundry stays installed alongside Hardhat for those workflows.foundryup, the forge / cast / anvil binaries) — only mention this once every prior item in the checklist is resolved.If the verdict is anything other than Successful, prefix the section with a one-line warning that cleanup should wait until the listed blockers / gaps are addressed.
The report header (immediately below the title) must contain:
devDependencies.hardhat in package.jsonhardhat-migration/, so use just the filename: [Foundry analysis](<project-name>-foundry-migration-analysis.md))### Notable gaps (non-blocking, medium+ impact). Omit the section entirely if no medium+ gaps exist.Verdict values:
| Verdict | Emoji | Condition |
|---|---|---|
| Successful | ✅ | Full feature parity, all tests pass, nothing commented out — the Foundry cleanup checklist has nothing left blocking deletion of foundry.toml |
| Successful with gaps | 🟡 | All tests pass, but some used Forge features have no Hardhat equivalent (e.g., forge script left intact in package.json) — Foundry must stay installed for those workflows |
| Partial | 🟡 | Tests pass but functions were commented out — coverage is reduced; the user should investigate before deleting Foundry files |
| Failed | ❌ | Compilation or tests fail — the user should keep Foundry installed and the original config files in place until the blockers are resolved |
Example header for a Failed result:
**Hardhat version installed:** `^3.1.10` **Migration date:** 2026-03-03 **Foundry analysis:** [Foundry analysis](<project-name>-foundry-migration-analysis.md)
---
**Verdict:** ❌ **Failed**
### Blockers
- ❌ `vm.someCheatcode()` bug — N tests failing ([local bug report](bugs/vm-some-cheatcode.md), not yet filed upstream)
- 🚩 `vm.unsupported()` unsupported — M test instances commented out
### Notable gaps (non-blocking, medium+ impact)
- 🟡 Inline test config partially supported — contract-level directives are silently ignored
The final body section is Next Steps — it is always the last numbered section in the report. The verdict itself lives in the header, not here. This section contains a short numbered list of recommended actions, ordered from most to least impact. Each item must name the concrete action, state the impact justification (test count, severity, or workflow scope), and include a link where relevant. Three to five items is the target length — don't pad with low-impact items already covered by the gap table.
For a Successful or Successful-with-gaps verdict, the top items typically come from the Foundry Cleanup Checklist (delete foundry.toml/foundry.lock, port remaining Forge-only scripts, update CI). For a Failed verdict or one with bug reports, the top items are addressing blockers and filing bug-report drafts upstream — cleanup waits.
This flow is triggered when the argument is update. It assumes a previous migration has already been completed — the project has hardhat.config.ts, the analysis file (hardhat-migration/<project-name>-foundry-migration-analysis.md), and the migration report (hardhat-migration/<project-name>-hardhat-migration-report.md). The user may still have foundry.toml and other Foundry files around (kept intentionally — see the previous report's Foundry Cleanup Checklist), and the project's primary package.json scripts now run Hardhat.
Goal: Bring the migration up to date — upgrade Hardhat, re-evaluate every gap/partial/bug in the report against the current Hardhat version, remove workarounds that are no longer needed, and regenerate the report.
Follow these steps in order.
hardhat-migration/<project-name>-hardhat-migration-report.md) and analysis file (hardhat-migration/<project-name>-foundry-migration-analysis.md).hardhat.config.ts and package.json to understand the current configuration.foundry.toml to cross-reference against the original Foundry settings.package.json.<package-manager> view hardhat version (use the same package manager as the original migration — check the lockfile).package.json to use "hardhat": "^<latest-version>".<package-manager> install (with --ignore-scripts if needed, same as original migration).Since Hardhat 3.3.0, inline forge-config: directives are supported for most settings at the function level. Review hardhat.config.ts for global settings that were added solely as workarounds for missing inline config support:
test.solidity (e.g., allowInternalExpectRevert, disableBlockGasLimit) against the inline config that uses it.forge-config: was not supported (check the report's "Workarounds Applied" section and config comments), AND the setting is now supported inline by Hardhat (see inline config docs):
gasLimit, fsPermissions, fuzz.* — these are project-wide defaults from foundry.toml, not workarounds)0.12.0-next.33, this includes fuzz/invariant settings, allowInternalExpectRevert, isolate, and evm_version per edr#1349 closed)hardhat.config.ts about inline config support status (e.g., if the comment says "silently ignored", update it to reflect current support level — noting function-level vs contract-level distinction).Go through every row in the existing report's feature parity table (gaps, bugs, and partial support). For each one:
Check if the gap has been resolved in the current Hardhat version:
UnsupportedCheatcode entries, check if the cheatcode is now supported by running a quick test or checking EDR release notesIf a gap is resolved:
// HARDHAT-SKIP for this gap, uncomment them — see "Uncommenting HARDHAT-SKIP blocks" guidance belowUncommenting HARDHAT-SKIP blocks — use brace counting, not "stop at first }": A naive procedure that strips the // prefix from every line until it sees a closing brace at the function-definition indent will break when the function body has same-indent nested braces. This happens whenever an inner block (if { ... }, for { ... }, struct literal, etc.) was originally formatted at the same indent as the function declaration — common in auto-generated comment-out blocks where every body line is prefixed with a single // without preserving relative indentation. The naive procedure stops at the inner block's closing brace, leaving the rest of the function commented and producing invalid Solidity.
The correct algorithm: after the // HARDHAT-SKIP: header (and any optional // See: follow-up lines), uncomment every subsequent line that matches <indent>//. After uncommenting each line, strip string and comment content, then count { and } and track depth. Stop when depth has become positive (i.e., the function declaration's { was seen) and then returns to zero (the function's closing }). Quick sanity check after running: grep for any leftover lines matching ^<indent>// [a-z] or ^<indent>// } in the affected files — non-empty output indicates an incomplete uncomment.
If a gap is partially resolved (e.g., new inline config settings added but not all), update the parity level and notes accordingly
If a gap remains unchanged, keep it as-is
npx hardhat compile --show-stack-traces 2>&1 | tee /tmp/hardhat-compile-output.txtnpx hardhat test solidity --show-stack-traces 2>&1 | tee /tmp/hardhat-test-output.txtUnsupportedCheatcode, investigate:
// HARDHAT-SKIPConstraint: This step must never leave the project's snapshot files modified. The procedure below tests both --snapshot-check and --snapshot code paths, but every write is reverted at the end. Never run blanket git clean -fd to clean up — that would also nuke unrelated untracked work in the workspace.
KEY FACT — Hardhat's whole-suite .gas-snapshot format was never designed to be Forge-compatible (not "broken" — just not built for interop, confirmed with the Hardhat team); do NOT classify it as a gap or bug. Forge has two distinct gas-snapshot mechanisms that write different files:
forge snapshot command → whole-suite .gas-snapshot at the project root (one entry per test function).vm.snapshotGasLastCall, vm.startSnapshotGas / vm.stopSnapshotGas) → per-group snapshots/<group>.json files.Hardhat supports both (--snapshot / --snapshot-check) with identical gas values, but writes/reads the whole-suite file with a Contract#function separator where Forge uses Contract:function(), and does not read Forge's format by design. Decision rule:
forge snapshot-generated .gas-snapshot makes --snapshot-check fail with HHE803: Invalid format in snapshot file .gas-snapshot. The format error itself is NEVER the gap — it's not a bug and not a 🚩 Gap; do not file a bug report over it.npx hardhat test solidity --snapshot (rewrites .gas-snapshot in Hardhat's format), noting the two toolchains can't share the one file (hardcoded path, mutually unreadable formats — keep a per-toolchain baseline if both are needed).snapshots/*.json cheatcode files are cross-compatible, so --snapshot-check works normally against those.Background and the proposal to relax Hardhat's reader to also accept : are tracked in hardhat#8357 (open) — which also notes the separator change alone may not give full parity for projects with duplicate contract names.
Detection. First decide which of three cases applies:
| State | Detection |
|---|---|
| Cheatcodes used, baseline committed | Grep .t.sol files for vm.snapshotGasLastCall, vm.startSnapshotGas, vm.stopSnapshotGas (any match) AND one or more of: .gas-snapshot at project root, files matching the project's configured snapshot_path, a snapshots/ directory with .json files, or any other snapshot output declared in package.json scripts (forge snapshot --snap path/...). |
| Cheatcodes used, no baseline | Cheatcode grep matches but no snapshot files exist (fresh adoption, or snapshots are gitignored). |
| Cheatcodes not used | No cheatcode grep matches. |
Procedure per state:
--snapshot-check first (against the existing committed baseline): npx hardhat test solidity --snapshot-check 2>&1 | tee /tmp/hardhat-snapshot-check-output.txt. Ordering matters — running --snapshot first would overwrite the committed values and turn the subsequent check into a tautological self-comparison, losing the cross-toolchain signal.
HHE803: Invalid format in snapshot file .gas-snapshot, the committed baseline is a Forge-format .gas-snapshot that Hardhat does not read by design (see KEY FACT above). This is expected — do not treat it as an error to flag. Skip the --snapshot-check value comparison and instead verify gas equivalence directly: run --snapshot (step 3), then diff the regenerated file against the committed Forge baseline with the separator normalized — git show HEAD:.gas-snapshot | sed 's/:/#/' | sort vs sed -E 's#^[^ ]*\.t\.sol:##' .gas-snapshot | sort (the sed on the Hardhat file strips the FQN prefix Hardhat adds for duplicate contract names). Identical standard-test ((gas:)) lines → ✅ Full parity (fuzz (runs:) lines may differ by seed nondeterminism — not a gas change). If standard-test gas values diverge after normalization → 🟡 Partial per step 5's divergence bullet — the HHE803 was just the format; the value divergence is the actual gap. Then restore as in step 4.git status --short > /tmp/snapshot-before.txt.--snapshot to verify the generation code path: npx hardhat test solidity --snapshot 2>&1 | tee /tmp/hardhat-snapshot-output.txt.git status --short > /tmp/snapshot-after.txt, diff against before, then:
git checkout HEAD -- <path>.rm <path>.--snapshot-check result as a cross-toolchain gas-value sanity check:
HHE803: Invalid format on a .gas-snapshot baseline → committed baseline is Forge-format, which Hardhat does not read by design (see KEY FACT). The format error itself is not a gap/bug, but it leaves the value comparison unverified — run the normalized-diff path in step 1's sub-bullet, then fall through to the bullets below as if --snapshot-check had reported: identical values → ✅ Full parity (+ regenerate-baseline Next-Step); divergent values → 🟡 Partial.git status --short > /tmp/snapshot-before.txt.--snapshot: npx hardhat test solidity --snapshot 2>&1 | tee /tmp/hardhat-snapshot-output.txt.--snapshot exits cleanly and writes a non-empty output file, the feature works → ✅. Cross-toolchain value divergence cannot be assessed without a baseline; the report's gap-row note should say so explicitly rather than silently omit the comparison.Skip this step.
On failure (any case): if either command errors (not just produces unexpected values), keep Gas snapshots as 🚩 Gap — except the expected HHE803: Invalid format in snapshot file .gas-snapshot case (a committed Forge-format .gas-snapshot, which Hardhat does not read by design — see KEY FACT), which is not a gap and must be classified ✅ Full per step 1/5. For any other error, capture the exact message in the gap table's Workaround / Notes column and check whether the underlying issue is Hardhat / EDR or project-specific.
Regenerate the migration report following the same structure as Step 7 of the original migration:
function test* declarations and compare against the new test runfoundry.toml, lib/, or a Forge-only script in place has now been resolved, surface that explicitly in the updated checklist so the user knows they can delete it. Conversely, if Foundry files have already been deleted since the last run, mark those items as "already removed" rather than re-listing them as actionable.Review the analysis file (hardhat-migration/<project-name>-foundry-migration-analysis.md) and update any sections that reference Hardhat support status (e.g., inline config notes). The analysis file primarily documents the Foundry project structure and should not change much, but notes about Hardhat compatibility should reflect the current state.
When converting git submodules (in lib/) to npm packages:
| Foundry (lib/) | npm package |
|---|---|
openzeppelin-contracts | @openzeppelin/contracts |
openzeppelin-contracts-upgradeable | @openzeppelin/contracts-upgradeable |
solmate | solmate |
solady | solady |
prb-math | @prb/math |
prb-proxy | @prb/proxy |
Note: Hardhat 3 natively resolves dependencies from both node_modules/ and lib/ via remappings.txt — no plugin required. The optional @nomicfoundation/hardhat-foundry plugin extends this (e.g., reading remappings from foundry.toml), but is not needed for standard remappings.txt support. In most cases, submodule dependencies in lib/ can be kept as-is without converting to npm packages.
Hardhat 3 uses Node.js module resolution for Solidity imports, not Forge's remapping system (Hardhat 3 dependencies docs). This has two key implications:
Remappings targeting node_modules/ are redundant. Remappings like @openzeppelin/contracts/=node_modules/@openzeppelin/contracts/ duplicate what Node.js resolution already does. Hardhat 3 only needs remappings for non-npm paths (e.g., src/=./src/ for absolute imports, or lib/-based submodule paths).
Project-level remappings do not propagate into node_modules/. Each remappings.txt only affects files in its directory and subdirectories, excluding node_modules/. This is a key difference from Forge, where a remapping like @openzeppelin/contracts/=node_modules/@openzeppelin/contracts/ applies globally — forcing all packages to resolve to the same copy. In Hardhat 3, each npm package resolves its own dependencies via Node.js resolution, respecting the package manager's isolation rules. See the "Transitive dependency version conflicts" reference section for how this can cause Solidity type mismatches.