hardhat 3.1.9 → 3.1.11

package/src/internal/builtin-plugins/solidity-test/runner.ts

@@ -38,7 +38,7 @@ export interface RunOptions {
  * Despite the changes, the signature of the function should still be considered
  * a draft that may change in the future.
  *
- * TODO: Once the signature is finalised, give feedback to the EDR team.
+ * TODO: Once the signature is finalized, give feedback to the EDR team.
  */
 export function run(
   chainType: ChainType,

package/src/internal/builtin-plugins/solidity-test/task-action.ts

@@ -1,6 +1,8 @@
 import type { RunOptions } from "./runner.js";
 import type { TestEvent } from "./types.js";
 import type { NewTaskActionFunction } from "../../../types/tasks.js";
+import type { TestSummary } from "../../../types/test.js";
+import type { Result } from "../../../types/utils.js";
 import type {
   Artifact as EdrArtifact,
   BuildInfoAndOutput,
@@ -19,19 +21,10 @@ import { resolveFromRoot } from "@nomicfoundation/hardhat-utils/path";
 import { createNonClosingWriter } from "@nomicfoundation/hardhat-utils/stream";
 
 import { getFullyQualifiedName } from "../../../utils/contract-names.js";
+import { errorResult, successfulResult } from "../../../utils/result.js";
 import { HardhatRuntimeEnvironmentImplementation } from "../../core/hre.js";
 import { isSupportedChainType } from "../../edr/chain-type.js";
 import { ArtifactManagerImplementation } from "../artifacts/artifact-manager.js";
-import {
-  markTestRunStart as initCoverage,
-  markTestWorkerDone as saveCoverageData,
-  markTestRunDone as reportCoverage,
-} from "../coverage/helpers.js";
-import {
-  markTestRunStart as initGasStats,
-  markTestWorkerDone as saveGasStatsData,
-  markTestRunDone as reportGasStats,
-} from "../gas-analytics/helpers.js";
 import { edrGasReportToHardhatGasMeasurements } from "../network-manager/edr/utils/convert-to-edr.js";
 
 import { getEdrArtifacts, getBuildInfos } from "./edr-artifacts.js";
@@ -56,7 +49,7 @@ interface TestActionArguments {
 const runSolidityTests: NewTaskActionFunction<TestActionArguments> = async (
   { testFiles, chainType, grep, noCompile, verbosity, testSummaryIndex },
   hre,
-) => {
+): Promise<Result<TestSummary, TestSummary>> => {
   assertHardhatInvariant(
     hre instanceof HardhatRuntimeEnvironmentImplementation,
     "Expected HRE to be an instance of HardhatRuntimeEnvironmentImplementation",
@@ -98,7 +91,7 @@ const runSolidityTests: NewTaskActionFunction<TestActionArguments> = async (
 
   // EDR needs all artifacts (contracts + tests)
   const edrArtifacts: Array<{
-    edrAtifact: EdrArtifact;
+    edrArtifact: EdrArtifact;
     userSourceName: string;
   }> = [];
   const buildInfos: BuildInfoAndOutput[] = [];
@@ -110,20 +103,20 @@ const runSolidityTests: NewTaskActionFunction<TestActionArguments> = async (
   }
 
   const sourceNameToUserSourceName = new Map(
-    edrArtifacts.map(({ userSourceName, edrAtifact }) => [
-      edrAtifact.id.source,
+    edrArtifacts.map(({ userSourceName, edrArtifact }) => [
+      edrArtifact.id.source,
       userSourceName,
     ]),
   );
 
-  edrArtifacts.forEach(({ userSourceName, edrAtifact }) => {
+  edrArtifacts.forEach(({ userSourceName, edrArtifact }) => {
     if (
       testRootPaths.includes(
         resolveFromRoot(hre.config.paths.root, userSourceName),
       ) &&
-      isTestSuiteArtifact(edrAtifact)
+      isTestSuiteArtifact(edrArtifact)
     ) {
-      warnDeprecatedTestFail(edrAtifact, sourceNameToUserSourceName);
+      warnDeprecatedTestFail(edrArtifact, sourceNameToUserSourceName);
     }
   });
 
@@ -133,8 +126,8 @@ const runSolidityTests: NewTaskActionFunction<TestActionArguments> = async (
         resolveFromRoot(hre.config.paths.root, userSourceName),
       ),
     )
-    .filter(({ edrAtifact }) => isTestSuiteArtifact(edrAtifact))
-    .map(({ edrAtifact }) => edrAtifact.id);
+    .filter(({ edrArtifact }) => isTestSuiteArtifact(edrArtifact))
+    .map(({ edrArtifact }) => edrArtifact.id);
 
   console.log("Running Solidity tests");
   console.log();
@@ -186,12 +179,16 @@ const runSolidityTests: NewTaskActionFunction<TestActionArguments> = async (
   const options: RunOptions =
     solidityTestConfigToRunOptions(solidityTestConfig);
 
-  await initCoverage("solidity");
-  await initGasStats("solidity");
+  await hre.hooks.runHandlerChain(
+    "test",
+    "onTestRunStart",
+    ["solidity"],
+    async () => {},
+  );
 
   const runStream = run(
     chainType,
-    edrArtifacts.map(({ edrAtifact }) => edrAtifact),
+    edrArtifacts.map(({ edrArtifact }) => edrArtifact),
     testSuiteIds,
     config,
     tracingConfig,
@@ -271,26 +268,27 @@ const runSolidityTests: NewTaskActionFunction<TestActionArguments> = async (
     includesErrors = true;
   }
 
-  await saveCoverageData("solidity");
-  await saveGasStatsData("solidity");
-
-  // this may print coverage and gas statistics reports
-  await reportCoverage("solidity");
-  await reportGasStats("solidity");
+  await hre.hooks.runHandlerChain(
+    "test",
+    "onTestWorkerDone",
+    ["solidity"],
+    async () => {},
+  );
 
-  if (includesFailures || includesErrors) {
-    process.exitCode = 1;
-  }
+  await hre.hooks.runHandlerChain(
+    "test",
+    "onTestRunDone",
+    ["solidity"],
+    async () => {},
+  );
 
   console.log();
 
-  return {
-    failed,
-    passed,
-    skipped,
-    todo: 0,
-    failureOutput,
-  };
+  const summary = { failed, passed, skipped, todo: 0, failureOutput };
+
+  return includesFailures || includesErrors
+    ? errorResult(summary)
+    : successfulResult(summary);
 };
 
 export default runSolidityTests;

package/src/internal/builtin-plugins/solidity-test/type-extensions.ts

@@ -35,6 +35,7 @@ declare module "../../../types/test.js" {
     coinbase?: string; // 0x-prefixed hex string
     blockTimestamp?: bigint;
     prevRandao?: bigint;
+    gasLimit?: bigint;
     blockGasLimit?: bigint | false;
 
     fuzz?: {

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

@@ -1,5 +1,6 @@
 import type { NewTaskActionFunction } from "../../../types/tasks.js";
 
+import { errorResult, successfulResult } from "../../../utils/result.js";
 import {
   isTelemetryAllowed,
   setTelemetryEnabled,
@@ -15,8 +16,7 @@ const configureTelemetry: NewTaskActionFunction<
 > = async ({ enable, disable }) => {
   if (enable && disable) {
     console.error("Cannot enable and disable telemetry at the same time");
-    process.exitCode = 1;
-    return;
+    return errorResult();
   }
 
   if (enable) {
@@ -40,6 +40,8 @@ const configureTelemetry: NewTaskActionFunction<
       "Telemetry is disabled, to enable it run `npx hardhat telemetry --enable`",
     );
   }
+
+  return successfulResult();
 };
 
 export default configureTelemetry;

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

@@ -4,13 +4,21 @@ import type {
   Task,
   TaskArguments,
 } from "../../../types/tasks.js";
+import type { TestSummary } from "../../../types/test.js";
+import type { Result } from "../../../types/utils.js";
 
 import {
   assertHardhatInvariant,
   HardhatError,
 } from "@nomicfoundation/hardhat-errors";
+import { isObject } from "@nomicfoundation/hardhat-utils/lang";
 import chalk, { type ChalkInstance } from "chalk";
 
+import {
+  errorResult,
+  isResult,
+  successfulResult,
+} from "../../../utils/result.js";
 import { HardhatRuntimeEnvironmentImplementation } from "../../core/hre.js";
 
 interface TestActionArguments {
@@ -21,10 +29,27 @@ interface TestActionArguments {
   verbosity: number;
 }
 
+// Old plugins may only return { failed, passed } without skipped/todo,
+// so we accept a partial shape and fill defaults in the coordinator.
+interface PartialTestSummary extends Omit<TestSummary, "skipped" | "todo"> {
+  skipped?: number;
+  todo?: number;
+}
+
+function isTestSummary(value: unknown): value is PartialTestSummary {
+  return (
+    isObject(value) &&
+    typeof value.failed === "number" &&
+    typeof value.passed === "number" &&
+    (value.skipped === undefined || typeof value.skipped === "number") &&
+    (value.todo === undefined || typeof value.todo === "number")
+  );
+}
+
 const runAllTests: NewTaskActionFunction<TestActionArguments> = async (
   { testFiles, chainType, grep, noCompile, verbosity },
   hre,
-) => {
+): Promise<Result<void, void>> => {
   // If this code is executed, it means the user has not specified a test runner.
   // If file paths are specified, we need to determine which test runner applies to each test file.
   // If no file paths are specified, each test runner will execute all tests located under its configured path in the Hardhat configuration.
@@ -49,18 +74,10 @@ const runAllTests: NewTaskActionFunction<TestActionArguments> = async (
     hre._coverage.disableReport();
   }
 
-  const testSummaries: Record<
-    string,
-    {
-      failed?: number;
-      passed?: number;
-      skipped?: number;
-      todo?: number;
-      failureOutput?: string;
-    }
-  > = {};
+  const testSummaries: Record<string, TestSummary> = {};
 
   let failureIndex = 1;
+  let hasFailures = false;
   for (const subtask of thisTask.subtasks.values()) {
     const files = getTestFilesForSubtask(subtask, testFiles, subtasksToFiles);
 
@@ -84,18 +101,45 @@ const runAllTests: NewTaskActionFunction<TestActionArguments> = async (
       args.verbosity = verbosity;
     }
 
-    const summaryId = subtask.id[subtask.id.length - 1];
-
     if (subtask.options.has("testSummaryIndex")) {
       args.testSummaryIndex = failureIndex;
+    }
+
+    const subtaskResult = await subtask.run(args);
 
-      testSummaries[summaryId] = await subtask.run(args);
-      failureIndex += testSummaries[summaryId].failed ?? 0;
-    } else if (summaryId === "mocha") {
-      // mocha doesn't use the testSummaryIndex, but it does return failure & success counts
-      testSummaries[summaryId] = await subtask.run(args);
-    } else {
-      await subtask.run(args);
+    const isSubtaskResult = isResult(
+      subtaskResult,
+      isTestSummary,
+      isTestSummary,
+    );
+    const summary = isSubtaskResult
+      ? subtaskResult.success
+        ? subtaskResult.value
+        : subtaskResult.error
+      : isTestSummary(subtaskResult)
+        ? subtaskResult
+        : undefined;
+
+    if (summary !== undefined) {
+      const summaryId = subtask.id[subtask.id.length - 1];
+      testSummaries[summaryId] = {
+        skipped: 0,
+        todo: 0,
+        ...summary,
+      };
+
+      if (subtask.options.has("testSummaryIndex")) {
+        failureIndex += summary.failed;
+      }
+    }
+
+    if (
+      (isSubtaskResult && !subtaskResult.success) ||
+      // Backwards compatibility: old plugins may not return a Result, so fall
+      // back to the process exit code to detect failures
+      (process.exitCode !== undefined && process.exitCode !== 0)
+    ) {
+      hasFailures = true;
     }
   }
 
@@ -106,19 +150,19 @@ const runAllTests: NewTaskActionFunction<TestActionArguments> = async (
   const outputLines: string[] = [];
 
   for (const [subtaskName, results] of Object.entries(testSummaries)) {
-    if (results.passed !== undefined && results.passed > 0) {
+    if (results.passed > 0) {
       passed.push([subtaskName, results.passed]);
     }
 
-    if (results.failed !== undefined && results.failed > 0) {
+    if (results.failed > 0) {
       failed.push([subtaskName, results.failed]);
     }
 
-    if (results.skipped !== undefined && results.skipped > 0) {
+    if (results.skipped > 0) {
       skipped.push([subtaskName, results.skipped]);
     }
 
-    if (results.todo !== undefined && results.todo > 0) {
+    if (results.todo > 0) {
       todo.push([subtaskName, results.todo]);
     }
 
@@ -176,9 +220,11 @@ const runAllTests: NewTaskActionFunction<TestActionArguments> = async (
     console.log();
   }
 
-  if (process.exitCode !== undefined && process.exitCode !== 0) {
+  if (hasFailures) {
     console.error("Test run failed");
   }
+
+  return hasFailures ? errorResult() : successfulResult();
 };
 
 function logSummaryLine(

package/src/internal/builtin-plugins/test/type-extensions.ts

@@ -39,5 +39,47 @@ declare module "../../../types/hooks.js" {
         filePath: string,
       ) => Promise<string | undefined>,
     ) => Promise<string | undefined>;
+
+    /**
+     * This hook is triggered at the start of a test run, before tests execute.
+     *
+     * @param context The hook context.
+     * @param id A string identifier for the test runner (e.g., "solidity", "nodejs", "mocha").
+     * @param next A function to call the next handler for this hook, or the
+     * default implementation if no more handlers exist.
+     */
+    onTestRunStart: (
+      context: HookContext,
+      id: string,
+      next: (nextContext: HookContext, id: string) => Promise<void>,
+    ) => Promise<void>;
+
+    /**
+     * This hook is triggered when a test worker has finished executing.
+     *
+     * @param context The hook context.
+     * @param id A string identifier for the test runner (e.g., "solidity", "nodejs", "mocha").
+     * @param next A function to call the next handler for this hook, or the
+     * default implementation if no more handlers exist.
+     */
+    onTestWorkerDone: (
+      context: HookContext,
+      id: string,
+      next: (nextContext: HookContext, id: string) => Promise<void>,
+    ) => Promise<void>;
+
+    /**
+     * This hook is triggered at the end of a test run, after all tests have completed.
+     *
+     * @param context The hook context.
+     * @param id A string identifier for the test runner (e.g., "solidity", "nodejs", "mocha").
+     * @param next A function to call the next handler for this hook, or the
+     * default implementation if no more handlers exist.
+     */
+    onTestRunDone: (
+      context: HookContext,
+      id: string,
+      next: (nextContext: HookContext, id: string) => Promise<void>,
+    ) => Promise<void>;
   }
 }

package/src/internal/cli/banner-manager.ts

@@ -0,0 +1,234 @@
+import type { Dispatcher } from "@nomicfoundation/hardhat-utils/request";
+
+import path from "node:path";
+
+import {
+  readJsonFile,
+  writeJsonFile,
+  FileNotFoundError,
+} from "@nomicfoundation/hardhat-utils/fs";
+import { getCacheDir } from "@nomicfoundation/hardhat-utils/global-dir";
+import { isObject } from "@nomicfoundation/hardhat-utils/lang";
+import { getRequest } from "@nomicfoundation/hardhat-utils/request";
+import debug from "debug";
+
+const log = debug("hardhat:util:banner-manager");
+
+interface BannerConfig {
+  enabled: boolean;
+  formattedMessages: string[];
+  minSecondsBetweenDisplays: number;
+  minSecondsBetweenRequests: number;
+}
+
+export const BANNER_CONFIG_URL =
+  "https://raw.githubusercontent.com/NomicFoundation/hardhat/refs/heads/main/banner-config-v3.json";
+
+export const BANNER_CACHE_FILE_NAME = "banner-config-v3.json";
+
+export class BannerManager {
+  static #instance: BannerManager | undefined;
+
+  #bannerConfig: BannerConfig | undefined;
+  #lastDisplayTime: number;
+  #lastRequestTime: number;
+  readonly #dispatcher: Dispatcher | undefined;
+  readonly #print: (message: string) => void;
+
+  private constructor(
+    bannerConfig: BannerConfig | undefined,
+    lastDisplayTime: number,
+    lastRequestTime: number,
+    dispatcher: Dispatcher | undefined,
+    print: (message: string) => void,
+  ) {
+    this.#bannerConfig = bannerConfig;
+    this.#lastDisplayTime = lastDisplayTime;
+    this.#lastRequestTime = lastRequestTime;
+    this.#dispatcher = dispatcher;
+    this.#print = print;
+  }
+
+  /**
+   * Returns a global instance of BannerManager.
+   *
+   * @param options Options used for testing purposes. Only used in the first
+   * invocation of this function, or after calling `resetInstance`.
+   * @returns The current global instance of BannerManager.
+   */
+  public static async getInstance(options?: {
+    testDispatcher?: Dispatcher;
+    print?: (message: string) => void;
+  }): Promise<BannerManager> {
+    if (this.#instance === undefined) {
+      log("Initializing BannerManager");
+      const { bannerConfig, lastDisplayTime, lastRequestTime } =
+        await readCache();
+      this.#instance = new BannerManager(
+        bannerConfig,
+        lastDisplayTime,
+        lastRequestTime,
+        options?.testDispatcher,
+        options?.print ?? console.log,
+      );
+    }
+
+    return this.#instance;
+  }
+
+  public static resetInstance(): void {
+    this.#instance = undefined;
+  }
+
+  /**
+   * Displays a banner message, if any.
+   *
+   * @param timeout The timeout in milliseconds to wait for the banner display.
+   */
+  public async showBanner(timeout?: number): Promise<void> {
+    await this.#requestBannerConfig(timeout);
+
+    if (
+      this.#bannerConfig === undefined ||
+      !this.#bannerConfig.enabled ||
+      this.#bannerConfig.formattedMessages.length === 0
+    ) {
+      log("Banner is disabled or no messages available.");
+      return;
+    }
+
+    const { formattedMessages, minSecondsBetweenDisplays } = this.#bannerConfig;
+
+    const timeSinceLastDisplay = Date.now() - this.#lastDisplayTime;
+    if (timeSinceLastDisplay < minSecondsBetweenDisplays * 1000) {
+      log(
+        `Skipping banner display. Time since last display: ${timeSinceLastDisplay}ms`,
+      );
+      return;
+    }
+
+    // select a random message from the formattedMessages array
+    const randomIndex = Math.floor(Math.random() * formattedMessages.length);
+    const message = formattedMessages[randomIndex];
+
+    this.#print(message);
+    this.#lastDisplayTime = Date.now();
+    await writeCache({
+      bannerConfig: this.#bannerConfig,
+      lastDisplayTime: this.#lastDisplayTime,
+      lastRequestTime: this.#lastRequestTime,
+    });
+  }
+
+  async #requestBannerConfig(timeout?: number): Promise<void> {
+    if (this.#bannerConfig !== undefined) {
+      const timeSinceLastRequest = Date.now() - this.#lastRequestTime;
+      if (
+        timeSinceLastRequest <
+        this.#bannerConfig.minSecondsBetweenRequests * 1000
+      ) {
+        log(
+          `Skipping banner config request. Time since last request: ${timeSinceLastRequest}ms`,
+        );
+        return;
+      }
+    }
+
+    try {
+      const response = await getRequest(
+        BANNER_CONFIG_URL,
+        undefined,
+        this.#dispatcher ?? { timeout },
+      );
+
+      const bannerConfig: unknown = await response.body.json();
+
+      if (!this.#isBannerConfig(bannerConfig)) {
+        log(`Invalid banner config received:`, bannerConfig);
+        return;
+      }
+
+      this.#bannerConfig = bannerConfig;
+      this.#lastRequestTime = Date.now();
+
+      await writeCache({
+        bannerConfig: this.#bannerConfig,
+        lastDisplayTime: this.#lastDisplayTime,
+        lastRequestTime: this.#lastRequestTime,
+      });
+    } catch (error) {
+      log(
+        `Error requesting banner config: ${
+          error instanceof Error ? error.message : JSON.stringify(error)
+        }`,
+      );
+    }
+  }
+
+  #isBannerConfig(value: unknown): value is BannerConfig {
+    if (!isObject(value)) {
+      return false;
+    }
+
+    return (
+      Object.getOwnPropertyNames(value).length === 4 &&
+      "enabled" in value &&
+      typeof value.enabled === "boolean" &&
+      "formattedMessages" in value &&
+      Array.isArray(value.formattedMessages) &&
+      value.formattedMessages.every(
+        (message: unknown) => typeof message === "string",
+      ) &&
+      "minSecondsBetweenDisplays" in value &&
+      typeof value.minSecondsBetweenDisplays === "number" &&
+      "minSecondsBetweenRequests" in value &&
+      typeof value.minSecondsBetweenRequests === "number"
+    );
+  }
+}
+
+interface BannerCache {
+  bannerConfig: BannerConfig | undefined;
+  lastDisplayTime: number;
+  lastRequestTime: number;
+}
+
+async function readCache(): Promise<BannerCache> {
+  const cacheDir = await getCacheDir();
+  const bannerCacheFilePath = path.join(cacheDir, BANNER_CACHE_FILE_NAME);
+
+  try {
+    return await readJsonFile<BannerCache>(bannerCacheFilePath);
+  } catch (error) {
+    if (error instanceof FileNotFoundError) {
+      log("No banner cache file found, using defaults");
+    } else {
+      log(
+        `Error reading cache file: ${
+          error instanceof Error ? error.message : JSON.stringify(error)
+        }`,
+      );
+    }
+
+    return {
+      bannerConfig: undefined,
+      lastDisplayTime: 0,
+      lastRequestTime: 0,
+    };
+  }
+}
+
+async function writeCache(cache: BannerCache): Promise<void> {
+  const cacheDir = await getCacheDir();
+  const bannerCacheFilePath = path.join(cacheDir, BANNER_CACHE_FILE_NAME);
+
+  try {
+    await writeJsonFile(bannerCacheFilePath, cache);
+  } catch (error) {
+    log(
+      `Error writing cache file: ${
+        error instanceof Error ? error.message : JSON.stringify(error)
+      }`,
+    );
+  }
+}

package/src/internal/cli/error-handler.ts

@@ -5,6 +5,7 @@ import {
 import chalk from "chalk";
 
 import { HARDHAT_NAME, HARDHAT_WEBSITE_URL } from "../constants.js";
+import { UsingHardhat2PluginError } from "../using-hardhat2-plugin-errors.js";
 
 /**
  * The different categories of errors that can be handled by hardhat cli.
@@ -69,6 +70,11 @@ export function printErrorMessages(
   shouldShowStackTraces: boolean = false,
   print: (message: string | Error) => void = console.error,
 ): void {
+  if (error instanceof UsingHardhat2PluginError) {
+    printUsingHardhat2Error(error, print);
+    return;
+  }
+
   const showStackTraces =
     shouldShowStackTraces ||
     getErrorWithCategory(error).category === ErrorCategory.OTHER;
@@ -146,3 +152,15 @@ function getErrorMessages(error: Error): ErrorMessages {
       };
   }
 }
+function printUsingHardhat2Error(
+  error: UsingHardhat2PluginError,
+  print: (message: string | Error) => void = console.error,
+): void {
+  print(chalk.red.bold(`Hardhat 3 installation error:`));
+  print("");
+  if (error.callerRelativePath !== undefined) {
+    print(error.message);
+  } else {
+    print(error.stack);
+  }
+}

package/src/internal/cli/init/init.ts

@@ -131,6 +131,14 @@ export async function initHardhat(options?: InitHardhatOptions): Promise<void> {
     ]);
 
     showStarOnGitHubMessage();
+
+    try {
+      const { BannerManager } = await import("../banner-manager.js");
+      const bannerManager = await BannerManager.getInstance();
+      await bannerManager.showBanner();
+    } catch (bannerError) {
+      log("Error showing banner", bannerError);
+    }
   } catch (e) {
     if (e === "") {
       // If the user cancels any prompt, we quit silently