Hardhat artifact cache serves stale ABI after Solidity version update

Answer to the Question

Hardhat automatically treats a change in the solidity version in hardhat.config.js as a new compilation job. The internal cache key is built from the full compiler configuration (version, optimizer, evmVersion, etc.) and the file‑content hash. Because the key changes, Hardhat does not reuse the old build‑info and therefore recompiles the affected contracts. A manual npx hardhat clean is only required when you suspect the cache is corrupted or when you want to guarantee a completely fresh state.

How the Cache is Keyed

• File hash – a SHA‑256 of the source file content.
• Compiler config – the full solc configuration object (including version, optimizer, evmVersion, etc.).
• These two values are concatenated to form a job identifier that is stored in cache/solidity-files-cache.json and referenced by the build‑info files.

When the version field changes, the compiler config part of the key changes, so any entry whose key no longer matches is considered stale and ignored. The old build‑info files remain on disk but are simply not used for that job.

When to Invalidate Manually

1. Suspected corruption – e.g., interrupted compilation, manual edits to the cache, or mismatched dependencies.
2. Cross‑branch builds – if you switch branches that change the compiler version but keep the same artifact path.
3. Plugin‑managed artifacts – some third‑party plugins maintain their own caches that may not react to compiler changes.

In all other cases, Hardhat will automatically recompile when the version changes.

Verifying Fresh Compilation Without Deleting the Cache

1. Inspect the build‑info file:

   cat artifacts/build-info/$(ls artifacts/build-info | tail -n1)/input.json | jq '.compiler.version'
   

   This shows the solc version used for the latest compile.
2. Check the internal cache mapping:

   cat cache/solidity-files-cache.json | jq '.files[] | {path: .path, version: .solc.version}'
   

   Each source file should list the new compiler version.
3. Force a recompile and compare hashes:

   npx hardhat compile --force
   # look at artifacts/build-info/*.json and compare the outputHash field to the previous compile
   

   If the hash changes, recompilation occurred.

Common Pitfalls That Look Like Stale Artifacts

• The ABI often stays identical across minor compiler upgrades, so you might think the artifact is stale when in fact the bytecode changed.
• Deploy scripts that import a hard‑coded ABI from a frontend repo will always use the stale copy regardless of Hardhat’s cache.
• Deploying to a chain that does not support the default evmVersion of the new compiler (e.g., PUSH0 in 0.8.20+ on pre‑Shanghai networks) can cause runtime reverts that are mistaken for stale artifacts.

Next Diagnostic Step

To confirm that Hardhat’s own cache is behaving as described, could you tell me which Hardhat major version you are using (e.g., 2.12.x, 2.13.x)? This helps rule out any version‑specific quirks in the cache implementation.