hardhat 3.5.0 → 3.6.0

package/skills/hardhat-toolbox-viem/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: hardhat-toolbox-viem
+description: Use alongside the `hardhat` skill when the project depends on `@nomicfoundation/hardhat-toolbox-viem`. Covers the viem clients exposed on `network.create()`, contract interaction (`viem.deployContract`, `read`, `write`, `getContractAt`), and `viem.assertions` (revert / event / balance assertions).
+metadata:
+  package: "@nomicfoundation/hardhat-toolbox-viem"
+---
+
+# Hardhat toolbox: viem
+
+This skill builds on the core **`hardhat`** skill. Load that first for test organization, the `network.create()` shape, `networkHelpers`, fixtures, and the typechecking workflow. Everything below hangs off the connection returned by `network.create()`:
+
+```ts
+import { network } from "hardhat";
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+describe("Counter", async function () {
+  const { viem, networkHelpers } = await network.create();
+  // ...
+});
+```
+
+## `viem`: clients and contract interaction
+
+```ts
+// Clients
+const publicClient = await viem.getPublicClient();
+const [owner, alice, bob] = await viem.getWalletClients(); // default accounts
+const testClient = await viem.getTestClient(); // dev-only operations
+
+// Deploy a contract, returns a fully typed instance
+const counter = await viem.deployContract("Counter");
+
+// Read state (return type inferred from ABI)
+const value = await counter.read.x();
+
+// Write transactions. Args and options are type-checked against the ABI at
+// compile time; passing wrong types, wrong argument counts, or `value` on a
+// non-payable function is a TypeScript error
+await counter.write.inc();
+await counter.write.inc({ account: alice.account }); // different sender
+await counter.write.incBy([3n]); // with args
+await counter.write.deposit({ value: 10n ** 18n }); // no parameters and payable
+
+// Attach to an already-deployed contract
+const existing = await viem.getContractAt("Counter", "0xabc...");
+```
+
+Avoid using `walletClient.writeContract` to interact with contracts — it has no ABI typing, so wrong args slip through. Prefer the typed instance returned by `viem.deployContract` or `viem.getContractAt`.
+
+Inside a `loadFixture` setup function (see the `hardhat` skill for the surrounding pattern), `viem.deployContract` is the canonical deploy step:
+
+```ts
+async function deployCounter() {
+  const counter = await viem.deployContract("Counter");
+  return { counter };
+}
+
+const { counter } = await networkHelpers.loadFixture(deployCounter);
+```
+
+## `viem.assertions`: Ethereum-specific assertions
+
+Use `viem.assertions` for contract-specific checks. Pass the **unawaited** transaction promise as the first argument:
+
+```ts
+// Reverts
+await viem.assertions.revert(counter.write.inc({ account: banned }));
+await viem.assertions.revertWith(
+  counter.write.inc({ account: banned }),
+  "Not authorized",
+);
+await viem.assertions.revertWithCustomError(
+  counter.write.inc({ account: banned }),
+  counter,
+  "Unauthorized",
+);
+await viem.assertions.revertWithCustomErrorWithArgs(
+  counter.write.inc({ account: banned }),
+  counter,
+  "Unauthorized",
+  [banned],
+);
+
+// Events
+await viem.assertions.emit(counter.write.inc(), counter, "Increment");
+await viem.assertions.emitWithArgs(counter.write.inc(), counter, "Increment", [
+  1n,
+]);
+
+// ETH balance changes (positive = received, negative = spent, before gas)
+await viem.assertions.balancesHaveChanged(game.write.claim(), {
+  [winner]: PRIZE,
+  [loser]: -STAKE,
+});
+```
+
+The `*WithArgs` matchers (`revertWithCustomErrorWithArgs` and `emitWithArgs`) accept a `(value) => boolean` predicate at any arg position, alongside concrete values. The plugin also ships an `anyValue` helper for positions you don't care about:
+
+```ts
+import { anyValue } from "@nomicfoundation/hardhat-toolbox-viem/predicates";
+
+// Inline predicate at any arg position. Useful for ranges or computed conditions.
+await viem.assertions.revertWithCustomErrorWithArgs(
+  contract.write.failing(),
+  contract,
+  "BadValue",
+  [(n: bigint) => n > 100n, "another error arg"],
+);
+await viem.assertions.emitWithArgs(
+  counter.write.incBy([3n]),
+  counter,
+  "Increment",
+  [(by: bigint) => by >= 1n],
+);
+
+// `anyValue` matches anything — handy for fields you don't care about.
+await viem.assertions.revertWithCustomErrorWithArgs(
+  contract.write.failing(),
+  contract,
+  "BadValue",
+  [anyValue, "another error arg"],
+);
+```
+
+For plain TypeScript assertions (equality, arrays, types), use `node:assert/strict`.

package/src/internal/builtin-plugins/flatten/task-action.ts

@@ -2,6 +2,7 @@ import type { NewTaskActionFunction } from "../../../types/tasks.js";
 
 import { styleText } from "node:util";
 
+import { HardhatError } from "@nomicfoundation/hardhat-errors";
 import { resolveFromRoot } from "@nomicfoundation/hardhat-utils/path";
 
 import {
@@ -261,7 +262,8 @@ function getPragmaAbicoderDirectiveInfo(
   };
 }
 
-// Returns files sorted in topological order
+// Returns files sorted in topological order. Throws if the graph contains a
+// cycle.
 function getSortedFiles(dependencyGraph: DependencyGraph): ResolvedFile[] {
   const sortedFiles: ResolvedFile[] = [];
   const visitedFiles = new Set<ResolvedFile>();
@@ -273,30 +275,58 @@ function getSortedFiles(dependencyGraph: DependencyGraph): ResolvedFile[] {
     );
   };
 
-  // Depth-first walking
-  const walk = (files: ResolvedFile[]) => {
+  // Depth-first walking. `importChain` is the chain of files leading to the
+  // current visit; a dep that reappears in it indicates a cycle.
+  const walk = (
+    files: ResolvedFile[],
+    importChain: readonly ResolvedFile[],
+  ) => {
     for (const file of files) {
-      if (visitedFiles.has(file)) continue;
+      if (visitedFiles.has(file)) {
+        continue;
+      }
 
-      visitedFiles.add(file);
+      throwIfCycle(file, importChain);
 
       const dependencies = sortBySourceName(
         Array.from(dependencyGraph.getDependencies(file)).map((d) => d.file),
       );
 
-      walk(dependencies);
+      walk(dependencies, [...importChain, file]);
 
+      visitedFiles.add(file);
       sortedFiles.push(file);
     }
   };
 
   const roots = sortBySourceName(dependencyGraph.getRoots().values());
 
-  walk(roots);
+  walk(roots, []);
 
   return sortedFiles;
 }
 
+function throwIfCycle(
+  file: ResolvedFile,
+  importChain: readonly ResolvedFile[],
+): void {
+  const cycleStart = importChain.indexOf(file);
+
+  if (cycleStart === -1) {
+    return;
+  }
+
+  const cycle = [
+    ...importChain.slice(cycleStart).map(formatSourceName),
+    formatSourceName(file),
+  ].join(" -> ");
+
+  throw new HardhatError(
+    HardhatError.ERRORS.CORE.BUILTIN_TASKS.FLATTEN_CYCLIC_DEPENDENCY,
+    { cycle },
+  );
+}
+
 function removeDuplicateAndSurroundingWhitespaces(str: string): string {
   return str.replace(/\s+/g, " ").trim();
 }

package/src/internal/builtin-plugins/solidity/build-system/build-system.ts

@@ -29,6 +29,7 @@ import type {
   CompilerOutputError,
   DependencyGraph,
   SolidityBuildInfo,
+  ResolvedBuildOptions,
 } from "../../../../types/solidity.js";
 
 import os from "node:os";
@@ -95,21 +96,6 @@ export function isSolcSolidityCompilerConfig(
   return config.type === undefined || config.type === "solc";
 }
 
-// Compiler warnings to suppress from build output.
-// Each rule specifies a warning message and the source file it applies to.
-// This allows suppressing known warnings from internal files (e.g., console.sol)
-// while still showing the same warning type from user code.
-export const SUPPRESSED_WARNINGS: Array<{
-  message: string;
-  sourceFile: string;
-}> = [
-  {
-    message:
-      "Natspec memory-safe-assembly special comment for inline assembly is deprecated and scheduled for removal. Use the memory-safe block annotation instead.",
-    sourceFile: path.normalize("hardhat/console.sol"),
-  },
-];
-
 interface CompilationResult {
   compilationJob: CompilationJob;
   compilerOutput: CompilerOutput;
@@ -123,6 +109,7 @@ export interface SolidityBuildSystemOptions {
   readonly artifactsPath: string;
   readonly cachePath: string;
   readonly solidityTestsPath: string;
+  readonly coverage: boolean;
 }
 
 /**
@@ -291,13 +278,14 @@ export class SolidityBuildSystemImplementation implements SolidityBuildSystem {
     rootFilePaths: string[],
     options?: BuildOptions,
   ): Promise<CompilationJobCreationError | Map<string, FileBuildResult>> {
-    const resolvedOptions: Required<BuildOptions> = {
+    const resolvedOptions: ResolvedBuildOptions = {
       buildProfile: DEFAULT_BUILD_PROFILE,
       concurrency: Math.max(os.cpus().length - 1, 1),
       force: false,
       isolated: false,
       quiet: false,
       scope: "contracts",
+      cleanupArtifacts: false,
       ...options,
     };
 
@@ -382,6 +370,8 @@ export class SolidityBuildSystemImplementation implements SolidityBuildSystem {
         ReadonlyMap<string, string[]>
       > = new Map();
 
+      let contractArtifactsAfterBuild: string[] | undefined;
+
       if (isSuccessfulBuild) {
         log("Emitting artifacts of successful build");
         await Promise.all(
@@ -411,6 +401,43 @@ export class SolidityBuildSystemImplementation implements SolidityBuildSystem {
         );
 
         await saveCache(this.#options.cachePath, this.#compileCache);
+
+        if (resolvedOptions.cleanupArtifacts) {
+          const paths = await this.cleanupArtifacts(rootFilePaths, {
+            scope: resolvedOptions.scope,
+          });
+
+          if (resolvedOptions.scope !== "tests") {
+            contractArtifactsAfterBuild = paths;
+          }
+        }
+
+        if (resolvedOptions.scope !== "tests") {
+          if (
+            await this.#hooks.hasHandlers(
+              "solidity",
+              "processArtifactsAfterSuccessfulBuild",
+            )
+          ) {
+            contractArtifactsAfterBuild ??=
+              await this.#getCurrentContractArtifactPaths();
+
+            if (!this.#options.solidityConfig.splitTestsCompilation) {
+              // In unified mode the contracts artifacts directory also contains
+              // test artifacts, so we must filter them out before invoking the
+              // processArtifactsAfterSuccessfulBuild hook.
+              contractArtifactsAfterBuild = await this.#filterOutTestArtifacts(
+                contractArtifactsAfterBuild,
+              );
+            }
+
+            await this.#hooks.runSequentialHandlers(
+              "solidity",
+              "processArtifactsAfterSuccessfulBuild",
+              [contractArtifactsAfterBuild, rootFilePaths, resolvedOptions],
+            );
+          }
+        }
       }
 
       spinner.stop();
@@ -429,10 +456,16 @@ export class SolidityBuildSystemImplementation implements SolidityBuildSystem {
           "We emitted contract artifacts for all the jobs if the build was successful",
         );
 
-        const errors = await Promise.all(
-          (result.compilerOutput.errors ?? []).map((error) =>
-            this.remapCompilerError(result.compilationJob, error, true),
-          ),
+        const errors = await this.#hooks.runHandlerChain(
+          "solidity",
+          "getCompilationJobErrors",
+          [result.compilationJob, result.compilerOutput],
+          async (_context, nextCompilationJob, nextCompilerOutput) =>
+            await Promise.all(
+              (nextCompilerOutput.errors ?? []).map((error) =>
+                this.remapCompilerError(nextCompilationJob, error, true),
+              ),
+            ),
         );
 
         this.#printSolcErrorsAndWarnings(errors);
@@ -1078,7 +1111,7 @@ export class SolidityBuildSystemImplementation implements SolidityBuildSystem {
   public async cleanupArtifacts(
     rootFilePaths: string[],
     options: { scope?: BuildScope } = {},
-  ): Promise<void> {
+  ): Promise<string[]> {
     const scope = options.scope ?? "contracts";
 
     this.#ensureSplitCompilationModeIfTestsScope(scope);
@@ -1205,6 +1238,77 @@ export class SolidityBuildSystemImplementation implements SolidityBuildSystem {
         async () => {},
       );
     }
+
+    return artifactPaths;
+  }
+
+  /**
+   * Returns every `.json` artifact under the contracts artifacts directory,
+   * excluding the project-wide top-level files (e.g. `artifacts.d.ts`) and
+   * the `build-info/` subtree.
+   *
+   * In unified mode, the returned list also contains test artifacts. Callers
+   * that need a contracts-only view should pass the result through
+   * `#filterOutTestArtifacts`.
+   */
+  async #getCurrentContractArtifactPaths(): Promise<string[]> {
+    const artifactsDirectory = await this.getArtifactsDirectory("contracts");
+    const buildInfosDir = path.join(artifactsDirectory, `build-info`);
+
+    const allArtifactFiles = await getAllFilesMatching(
+      artifactsDirectory,
+      (p) => {
+        // Ignore top level files (e.g. the project-wide artifacts.d.ts)
+        if (
+          p.indexOf(path.sep, artifactsDirectory.length + path.sep.length) ===
+          -1
+        ) {
+          return false;
+        }
+        return p.endsWith(".json");
+      },
+      (dir) => dir !== buildInfosDir,
+    );
+
+    return allArtifactFiles;
+  }
+
+  /**
+   * Returns `artifactPaths` with the test artifacts removed.
+   *
+   * This is only meaningful in unified mode, where contracts and tests share
+   * the same artifacts directory. The caller is responsible for ensuring that
+   * precondition.
+   *
+   * Each artifact's user source name is recovered from its path and classified
+   * via `getScope`. Results are cached per source name to avoid repeating the
+   * FS stat work for sibling artifacts. npm-style source names don't resolve
+   * to a real path inside the project, so `getScope` falls back to
+   * `"contracts"`, which is the intended outcome.
+   */
+  async #filterOutTestArtifacts(artifactPaths: string[]): Promise<string[]> {
+    const artifactsDirectory = await this.getArtifactsDirectory("contracts");
+    const scopeBySource = new Map<string, BuildScope>();
+    const contractArtifactPaths: string[] = [];
+
+    for (const artifactPath of artifactPaths) {
+      const userSourceName = toForwardSlash(
+        path.relative(artifactsDirectory, path.dirname(artifactPath)),
+      );
+
+      let scope = scopeBySource.get(userSourceName);
+      if (scope === undefined) {
+        const fsPath = path.resolve(this.#options.projectRoot, userSourceName);
+        scope = await this.getScope(fsPath);
+        scopeBySource.set(userSourceName, scope);
+      }
+
+      if (scope === "contracts") {
+        contractArtifactPaths.push(artifactPath);
+      }
+    }
+
+    return contractArtifactPaths;
   }
 
   public async compileBuildInfo(
@@ -1417,6 +1521,7 @@ export class SolidityBuildSystemImplementation implements SolidityBuildSystem {
       msg,
       this.#options.solidityTestsPath,
       this.#options.projectRoot,
+      this.#options.coverage,
     );
   }
 

package/src/internal/builtin-plugins/solidity/build-system/warning-suppression.ts

@@ -1,97 +1,119 @@
 import path from "node:path";
 
-// Compiler warnings to suppress from build output.
-// Supports two types of suppression rules:
-//
-// 1. scope: 'specific-file' - Suppress warnings from specific file paths
-//    - Use this to suppress known warnings from internal/library files (e.g., console.sol)
-//    - The same warning type will still be shown for user code
-//
-// 2. scope: 'test-files' - Suppress warnings from all test files
-//    - Test files are identified as:
-//      * Files ending in .t.sol (e.g., Counter.t.sol)
-//      * Files inside test/contracts/ directory
-//        (e.g., test/contracts/Example.sol)
-//    - Use this for warnings that are acceptable in test code but not in production code
-//      (e.g., missing SPDX license identifiers or pragma statements)
-export const SUPPRESSED_WARNINGS: Array<
-  | {
-      message: string;
-      scope: "specific-file";
-      filePath: string;
-    }
-  | {
-      message: string;
-      scope: "test-files";
-    }
-> = [
+import { COVERAGE_LIBRARY_FILE_NAME } from "@nomicfoundation/edr";
+
+export const NATSPEC_MEMORY_SAFE_ASSEMBLY_WARNING =
+  "Natspec memory-safe-assembly special comment for inline assembly is deprecated and scheduled for removal. Use the memory-safe block annotation instead.";
+export const SPDX_WARNING = "SPDX license identifier not provided";
+export const PRAGMA_WARNING =
+  "Source file does not specify required compiler version";
+const CONTRACT_SIZE_WARNING = "Contract code size is";
+
+// Suppression rules are grouped by scope. Each array has its own match logic
+// in `shouldSuppressWarning` function; add new entries to the array that fits, or add
+// a new array + block for a new scope.
+
+// Warnings tied to a specific internal file (e.g. console.sol). Suppressed
+// only when the warning points at that file.
+const SPECIFIC_FILE_RULES: ReadonlyArray<{
+  message: string;
+  filePath: string;
+}> = [
   {
-    message:
-      "Natspec memory-safe-assembly special comment for inline assembly is deprecated and scheduled for removal. Use the memory-safe block annotation instead.",
-    scope: "specific-file",
+    message: NATSPEC_MEMORY_SAFE_ASSEMBLY_WARNING,
     // Normalize to handle different OS path separators
     filePath: path.normalize("hardhat/console.sol"),
   },
+];
+
+// Warnings acceptable in test files. Suppressed when the warning points at a
+// file ending in `.t.sol` or inside the configured Solidity test directory.
+const TEST_FILE_WARNING_MESSAGES: readonly string[] = [
+  SPDX_WARNING,
+  PRAGMA_WARNING,
+];
+
+// Warnings suppressed only when running with `--coverage`. An entry with no
+// `filePath` matches the message anywhere (e.g. contract-size warnings that
+// fire on user files as a side effect of instrumentation); an entry with a
+// `filePath` only matches when the diagnostic also points at that file
+// (e.g. the injected coverage library file, which users can't edit).
+const COVERAGE_MODE_RULES: ReadonlyArray<{
+  message: string;
+  filePath?: string;
+}> = [
+  { message: CONTRACT_SIZE_WARNING },
   {
-    message: "SPDX license identifier not provided",
-    scope: "test-files",
-  },
-  {
-    message: "Source file does not specify required compiler version",
-    scope: "test-files",
+    message: NATSPEC_MEMORY_SAFE_ASSEMBLY_WARNING,
+    filePath: COVERAGE_LIBRARY_FILE_NAME,
   },
 ];
 
 /**
- * Determines if a compiler warning should be suppressed based on the suppression rules.
+ * Determines if a compiler warning should be suppressed.
  *
  * @param errorMessage - The formatted error message from the compiler
  * @param absoluteSolidityTestsPath - Absolute path to the Solidity test directory
  * @param absoluteProjectRoot - Absolute path to the project root
+ * @param coverage - Whether the build is running with `--coverage` enabled
  * @returns true if the warning should be suppressed, false otherwise
  */
 export function shouldSuppressWarning(
   errorMessage: string,
   absoluteSolidityTestsPath: string,
   absoluteProjectRoot: string,
+  coverage: boolean,
 ): boolean {
-  // Compute relative path from project root to test directory.
-  // Example:
-  // absoluteSolidityTestsPath: /workspaces/hardhat-4/packages/example-project/test/contracts
-  // absoluteProjectRoot:       /workspaces/hardhat-4/packages/example-project
-  // relativeTestPath:          test/contracts/ - note the addition of the `/`
-  // to avoid partial matches, e.g.: test/contractsUtils/
-  const relativeTestPath = path.join(
-    path.relative(absoluteProjectRoot, absoluteSolidityTestsPath),
-    "/",
-  );
-
-  return SUPPRESSED_WARNINGS.some((rule) => {
-    if (!errorMessage.includes(rule.message)) {
-      return false;
-    }
+  // Warnings suppressed only when running with `--coverage`.
+  if (
+    coverage &&
+    COVERAGE_MODE_RULES.some(
+      (rule) =>
+        errorMessage.includes(rule.message) &&
+        (rule.filePath === undefined || errorMessage.includes(rule.filePath)),
+    )
+  ) {
+    return true;
+  }
 
-    if (rule.scope === "specific-file") {
-      return errorMessage.includes(rule.filePath);
-    }
+  // Warnings tied to a specific internal file (e.g. console.sol).
+  if (
+    SPECIFIC_FILE_RULES.some(
+      (rule) =>
+        errorMessage.includes(rule.message) &&
+        errorMessage.includes(rule.filePath),
+    )
+  ) {
+    return true;
+  }
 
-    // Check if the message contains a path to a test file
+  // Warnings allowed in test files.
+  if (TEST_FILE_WARNING_MESSAGES.some((m) => errorMessage.includes(m))) {
     // Test files are identified by:
     // - Ending in .t.sol (e.g., Counter.t.sol)
     // - Being inside the configured Solidity test directory
-
     if (/\.t\.sol(:|$|\s)/.test(errorMessage)) {
       return true;
     }
 
-    // Extract file path from error message
+    // Compute relative path from project root to test directory.
+    // Example:
+    // absoluteSolidityTestsPath: /workspaces/hardhat-4/packages/example-project/test/contracts
+    // absoluteProjectRoot:       /workspaces/hardhat-4/packages/example-project
+    // relativeTestPath:          test/contracts/ - note the addition of the `/`
+    // to avoid partial matches, e.g.: test/contractsUtils/
+    const relativeTestPath = path.join(
+      path.relative(absoluteProjectRoot, absoluteSolidityTestsPath),
+      "/",
+    );
+
+    // Extract file path from error message.
     // Format: "Warning: message\n  --> path/to/file.sol:line:column:"
     const pathMatches = errorMessage.match(/-->\s+([^\s:]+\.sol)/);
-
     if (pathMatches !== null) {
       return pathMatches[1].includes(relativeTestPath);
     }
+  }
 
-    return false;
-  });
+  return false;
 }

package/src/internal/builtin-plugins/solidity/hook-handlers/hre.ts

@@ -114,7 +114,7 @@ class LazySolidityBuildSystem implements SolidityBuildSystem {
   public async cleanupArtifacts(
     rootFilePaths: string[],
     options: { scope?: BuildScope } = {},
-  ): Promise<void> {
+  ): Promise<string[]> {
     const buildSystem = await this.#getBuildSystem();
     return await buildSystem.cleanupArtifacts(rootFilePaths, options);
   }
@@ -152,7 +152,7 @@ class LazySolidityBuildSystem implements SolidityBuildSystem {
 
 export default async (): Promise<Partial<HardhatRuntimeEnvironmentHooks>> => {
   return {
-    created: async (_context, hre) => {
+    created: async (context, hre) => {
       hre.solidity = new LazySolidityBuildSystem(hre.hooks, {
         solidityConfig: hre.config.solidity,
         projectRoot: hre.config.paths.root,
@@ -160,6 +160,7 @@ export default async (): Promise<Partial<HardhatRuntimeEnvironmentHooks>> => {
         artifactsPath: hre.config.paths.artifacts,
         cachePath: hre.config.paths.cache,
         solidityTestsPath: hre.config.paths.tests.solidity,
+        coverage: context.globalOptions.coverage,
       });
     },
   };

package/src/internal/builtin-plugins/solidity/tasks/build.ts

@@ -186,6 +186,7 @@ async function runSolidityBuild({
       buildProfile,
       quiet,
       scope,
+      cleanupArtifacts: isFullBuild,
     },
   );
 
@@ -194,12 +195,6 @@ async function runSolidityBuild({
   // We use the result keys in case a hook added or removed root files
   const builtRootPaths = [...results.keys()];
 
-  if (isFullBuild) {
-    await solidity.cleanupArtifacts(builtRootPaths, {
-      scope,
-    });
-  }
-
   const preBuildRoots = new Set([...contractRootPaths, ...testRootPaths]);
   if (
     builtRootPaths.length === preBuildRoots.size &&