hardhat 3.8.0 → 3.9.1

package/src/internal/cli/parser.ts

@@ -0,0 +1,472 @@
+import type {
+  GlobalOptionDefinitions,
+  GlobalOptions,
+} from "../../types/global-options.js";
+import type { Task, TaskArguments } from "../../types/tasks.js";
+
+import {
+  HardhatError,
+  assertHardhatInvariant,
+} from "@nomicfoundation/hardhat-errors";
+import { isCi } from "@nomicfoundation/hardhat-utils/ci";
+import { kebabToCamelCase } from "@nomicfoundation/hardhat-utils/string";
+
+import {
+  ArgumentType,
+  type OptionDefinition,
+  type PositionalArgumentDefinition,
+} from "../../types/arguments.js";
+import { parseArgumentValue } from "../core/arguments.js";
+import { isArgumentRequired } from "../core/tasks/utils.js";
+
+export async function parseBuiltinGlobalOptions(
+  cliArguments: string[],
+  usedCliArguments: boolean[],
+): Promise<{
+  init: boolean;
+  configPath: string | undefined;
+  showStackTraces: boolean;
+  help: boolean;
+  version: boolean;
+}> {
+  let configPath: string | undefined;
+  let showStackTraces: boolean = isCi();
+  let help: boolean = false;
+  let version: boolean = false;
+  let init: boolean = false;
+
+  // TODO: Use parseGlobalOptions(BUILTIN_GLOBAL_OPTIONS_DEFINITIONS, ...) instead
+  for (let i = 0; i < cliArguments.length; i++) {
+    const arg = cliArguments[i];
+
+    if (arg === "--init") {
+      usedCliArguments[i] = true;
+      init = true;
+      continue;
+    }
+
+    if (arg === "--config") {
+      usedCliArguments[i] = true;
+
+      if (configPath !== undefined) {
+        throw new HardhatError(
+          HardhatError.ERRORS.CORE.ARGUMENTS.DUPLICATED_NAME,
+          {
+            name: "--config",
+          },
+        );
+      }
+
+      if (
+        usedCliArguments[i + 1] === undefined ||
+        usedCliArguments[i + 1] === true
+      ) {
+        throw new HardhatError(
+          HardhatError.ERRORS.CORE.ARGUMENTS.MISSING_CONFIG_FILE,
+        );
+      }
+
+      configPath = cliArguments[i + 1];
+      i++;
+
+      usedCliArguments[i] = true;
+      continue;
+    }
+
+    if (arg === "--show-stack-traces") {
+      usedCliArguments[i] = true;
+      showStackTraces = true;
+      continue;
+    }
+
+    if (arg === "--help" || arg === "-h") {
+      usedCliArguments[i] = true;
+      help = true;
+      continue;
+    }
+
+    if (arg === "--version") {
+      usedCliArguments[i] = true;
+      version = true;
+      continue;
+    }
+  }
+
+  if (init && configPath !== undefined) {
+    throw new HardhatError(
+      HardhatError.ERRORS.CORE.ARGUMENTS.CANNOT_COMBINE_INIT_AND_CONFIG_PATH,
+    );
+  }
+
+  return { init, configPath, showStackTraces, help, version };
+}
+
+export async function parseGlobalOptions(
+  globalOptionDefinitions: GlobalOptionDefinitions,
+  cliArguments: string[],
+  usedCliArguments: boolean[],
+): Promise<Partial<GlobalOptions>> {
+  const globalOptions: Partial<GlobalOptions> = {};
+
+  const optionDefinitions = new Map(
+    [...globalOptionDefinitions].map(([key, value]) => [key, value.option]),
+  );
+
+  parseOptions(
+    cliArguments,
+    usedCliArguments,
+    optionDefinitions,
+    globalOptions,
+    true,
+  );
+
+  return globalOptions;
+}
+
+/**
+ * Parses the task from the cli args.
+ *
+ * @returns The task, or an array with the unrecognized task id.
+ * If no task id is provided, an empty array is returned.
+ */
+export function parseTask(
+  cliArguments: string[],
+  usedCliArguments: boolean[],
+  tasksMap: Map<string, Task>,
+): Task | string[] {
+  const taskOrId = getTaskFromCliArguments(
+    cliArguments,
+    usedCliArguments,
+    tasksMap,
+  );
+
+  return taskOrId;
+}
+
+function getTaskFromCliArguments(
+  cliArguments: string[],
+  usedCliArguments: boolean[],
+  tasksMap: Map<string, Task>,
+): string[] | Task {
+  const taskId: string[] = [];
+  let task: Task | undefined;
+
+  for (let i = 0; i < cliArguments.length; i++) {
+    if (usedCliArguments[i]) {
+      continue;
+    }
+
+    const arg = cliArguments[i];
+
+    if (arg.startsWith("-")) {
+      /* A standalone '--' is ok because it is used to separate CLI tool arguments
+       * from task arguments, ensuring the tool passes subsequent options directly
+       * to the task. Everything after "--" should be considered as a positional
+       * argument. */
+      if (arg === "--" || task !== undefined) {
+        break;
+      }
+
+      /* At this point in the code, the global options have already been parsed, so
+       * the remaining options starting with '--' are task options. Hence, if no task
+       * is defined, it means that the option is not assigned to any task, and it's
+       * an error. */
+      throw new HardhatError(
+        HardhatError.ERRORS.CORE.ARGUMENTS.UNRECOGNIZED_OPTION,
+        {
+          option: arg,
+        },
+      );
+    }
+
+    if (task === undefined) {
+      task = tasksMap.get(arg);
+
+      if (task === undefined) {
+        return [arg]; // No task found
+      }
+    } else {
+      const subtask = task.subtasks.get(arg);
+
+      if (subtask === undefined) {
+        break;
+      }
+
+      task = subtask;
+    }
+
+    usedCliArguments[i] = true;
+    taskId.push(arg);
+  }
+
+  if (task === undefined) {
+    return taskId;
+  }
+
+  return task;
+}
+
+export function parseTaskArguments(
+  cliArguments: string[],
+  usedCliArguments: boolean[],
+  task: Task,
+): TaskArguments {
+  const taskArguments: TaskArguments = {};
+
+  // Parse options
+  parseOptions(cliArguments, usedCliArguments, task.options, taskArguments);
+
+  parsePositionalAndVariadicArguments(
+    cliArguments,
+    usedCliArguments,
+    task,
+    taskArguments,
+  );
+
+  const unusedIndex = usedCliArguments.indexOf(false);
+
+  if (unusedIndex !== -1) {
+    throw new HardhatError(HardhatError.ERRORS.CORE.ARGUMENTS.UNUSED_ARGUMENT, {
+      value: cliArguments[unusedIndex],
+    });
+  }
+
+  return taskArguments;
+}
+
+/**
+ * Parses the raw arguments from the command line, returning an array of
+ * arguments. If an argument starts with "--" and contains "=" (i.e. "--option=123")
+ * it is split into two separate arguments: the option name and the option value.
+ */
+export function parseRawArguments(rawArguments: string[]): string[] {
+  return rawArguments.flatMap((arg) => {
+    if (arg.startsWith("--") && arg.includes("=")) {
+      const index = arg.indexOf("=");
+      const optionName = arg.substring(0, index);
+      const optionValue = arg.substring(index + 1);
+
+      return [optionName, optionValue];
+    }
+
+    return arg;
+  });
+}
+
+function parseOptions(
+  cliArguments: string[],
+  usedCliArguments: boolean[],
+  optionDefinitions: Map<string, OptionDefinition>,
+  providedArguments: TaskArguments,
+  ignoreUnknownOption = false,
+) {
+  const optionDefinitionsByShortName = new Map<string, OptionDefinition>();
+  for (const optionDefinition of optionDefinitions.values()) {
+    if (optionDefinition.shortName !== undefined) {
+      optionDefinitionsByShortName.set(
+        optionDefinition.shortName,
+        optionDefinition,
+      );
+    }
+  }
+
+  for (let i = 0; i < cliArguments.length; i++) {
+    if (usedCliArguments[i]) {
+      continue;
+    }
+
+    if (cliArguments[i] === "--") {
+      /* A standalone '--' is ok because it is used to separate CLI tool arguments
+       * from task arguments, ensuring the tool passes subsequent options directly
+       * to the task. Everything after "--" should be considered as a positional
+       * argument. */
+      break;
+    }
+
+    const arg = cliArguments[i];
+
+    let optionDefinition: OptionDefinition | undefined;
+
+    const providedByName = arg.startsWith("--");
+    const providedByShortName = !providedByName && arg.startsWith("-");
+
+    if (providedByName) {
+      const name = kebabToCamelCase(arg.substring(2));
+      optionDefinition = optionDefinitions.get(name);
+    } else if (providedByShortName) {
+      const shortName = arg[1];
+
+      // Check if the short name is valid
+      if (Array.from(arg.substring(1)).some((c) => c !== shortName)) {
+        throw new HardhatError(
+          HardhatError.ERRORS.CORE.ARGUMENTS.CANNOT_GROUP_OPTIONS,
+          {
+            option: arg,
+          },
+        );
+      }
+
+      optionDefinition = optionDefinitionsByShortName.get(shortName);
+    } else {
+      continue;
+    }
+
+    if (optionDefinition === undefined) {
+      if (ignoreUnknownOption === true) {
+        continue;
+      }
+
+      // Only throw an error when the argument is not a global option, because
+      // it might be a option related to a task
+      throw new HardhatError(
+        HardhatError.ERRORS.CORE.ARGUMENTS.UNRECOGNIZED_OPTION,
+        {
+          option: arg,
+        },
+      );
+    }
+
+    if (optionDefinition.hidden === true) {
+      throw new HardhatError(
+        HardhatError.ERRORS.CORE.ARGUMENTS.NO_HIDDEN_OPTION_CLI,
+        {
+          option: arg,
+        },
+      );
+    }
+
+    const optionName = optionDefinition.name;
+
+    // Check if the short name is valid again now that we know its type
+    // E.g. --flag --flag
+    const optionAlreadyProvided = providedArguments[optionName] !== undefined;
+    // E.g. -ff
+    const shortOptionGroupedAndRepeated = providedByShortName && arg.length > 2;
+    const isLevelOption = optionDefinition.type === ArgumentType.LEVEL;
+    if (
+      optionAlreadyProvided ||
+      (shortOptionGroupedAndRepeated && !isLevelOption)
+    ) {
+      throw new HardhatError(
+        HardhatError.ERRORS.CORE.ARGUMENTS.CANNOT_REPEAT_OPTIONS,
+        {
+          option: arg,
+          type: optionDefinition.type,
+        },
+      );
+    }
+
+    usedCliArguments[i] = true;
+
+    if (optionDefinition.type === ArgumentType.FLAG) {
+      providedArguments[optionName] = true;
+      continue;
+    } else if (
+      optionDefinition.type === ArgumentType.LEVEL &&
+      providedByShortName
+    ) {
+      providedArguments[optionName] = arg.length - 1;
+      continue;
+    } else if (
+      usedCliArguments[i + 1] !== undefined &&
+      usedCliArguments[i + 1] === false
+    ) {
+      i++;
+
+      providedArguments[optionName] = parseArgumentValue(
+        cliArguments[i],
+        optionDefinition.type,
+        optionName,
+      );
+
+      usedCliArguments[i] = true;
+
+      continue;
+    }
+
+    throw new HardhatError(
+      HardhatError.ERRORS.CORE.ARGUMENTS.MISSING_VALUE_FOR_ARGUMENT,
+      {
+        argument: arg,
+      },
+    );
+  }
+}
+
+function parsePositionalAndVariadicArguments(
+  cliArguments: string[],
+  usedCliArguments: boolean[],
+  task: Task,
+  providedArguments: TaskArguments,
+) {
+  let argIndex = 0;
+
+  for (let i = 0; i < cliArguments.length; i++) {
+    if (usedCliArguments[i] === true) {
+      continue;
+    }
+
+    if (cliArguments[i] === "--") {
+      /* A standalone '--' is ok because it is used to separate CLI tool arguments
+       * from task arguments, ensuring the tool passes subsequent options directly
+       * to the task. Everything after "--" should be considered as a positional
+       * argument. */
+      usedCliArguments[i] = true;
+      continue;
+    }
+
+    const argumentDefinition = task.positionalArguments[argIndex];
+
+    if (argumentDefinition === undefined) {
+      break;
+    }
+
+    usedCliArguments[i] = true;
+
+    const formattedValue = parseArgumentValue(
+      cliArguments[i],
+      argumentDefinition.type,
+      argumentDefinition.name,
+    );
+
+    if (argumentDefinition.isVariadic === false) {
+      providedArguments[argumentDefinition.name] = formattedValue;
+      argIndex++;
+      continue;
+    }
+
+    // Handle variadic arguments. No longer increment "argIndex" because there can
+    // only be one variadic argument, and it will consume all remaining arguments.
+    providedArguments[argumentDefinition.name] =
+      providedArguments[argumentDefinition.name] ?? [];
+    const variadicTaskArg = providedArguments[argumentDefinition.name];
+    assertHardhatInvariant(
+      Array.isArray(variadicTaskArg),
+      "Variadic argument values should be an array",
+    );
+    variadicTaskArg.push(formattedValue);
+  }
+
+  // Check if all the required arguments have been used
+  validateRequiredArguments(task.positionalArguments, providedArguments);
+}
+
+function validateRequiredArguments(
+  argumentDefinitions: PositionalArgumentDefinition[],
+  taskArguments: TaskArguments,
+) {
+  const missingRequiredArgument = argumentDefinitions.find(
+    ({ defaultValue, name, type }) =>
+      isArgumentRequired(type, defaultValue) &&
+      taskArguments[name] === undefined,
+  );
+
+  if (missingRequiredArgument === undefined) {
+    return;
+  }
+
+  throw new HardhatError(
+    HardhatError.ERRORS.CORE.ARGUMENTS.MISSING_VALUE_FOR_ARGUMENT,
+    { argument: missingRequiredArgument.name },
+  );
+}

package/src/internal/cli/telemetry/analytics/analytics.ts

@@ -52,11 +52,15 @@ export async function sendTelemetryConfigAnalytics(
   return true;
 }
 
-export async function sendTaskAnalytics(taskId: string[]): Promise<boolean> {
+export async function sendTaskAnalytics(
+  taskId: string[],
+  command: "hardhat" | "hhu",
+): Promise<boolean> {
   const taskAnalyticsEvent: AnalyticsEvent = {
     name: "task",
     params: {
       task: taskId.join(", "),
+      command,
     },
   };
 

package/src/internal/cli/telemetry/analytics/types.ts

@@ -37,6 +37,9 @@ export type AnalyticsEvent =
       name: "task";
       params: {
         task: string;
+        // The CLI surface that ran the task, so `hhu` usage can be measured
+        // separately from the `hardhat` CLI.
+        command: "hardhat" | "hhu";
       };
     }
   | {

package/src/internal/edr/context.ts

@@ -10,32 +10,48 @@ import {
   opSolidityTestRunnerFactory,
 } from "@nomicfoundation/edr";
 
-let _globalEdrContext: EdrContext | undefined;
+// We cache the initialization *promise* (assigned synchronously, before any
+// await) rather than the resolved context. This way concurrent callers share a
+// single in-flight initialization and always receive a fully-registered
+// context, instead of racing on a half-initialized one.
+let _globalEdrContext: Promise<EdrContext> | undefined;
 
 export async function getGlobalEdrContext(): Promise<EdrContext> {
   if (_globalEdrContext === undefined) {
-    _globalEdrContext = new EdrContext();
-    await _globalEdrContext.registerProviderFactory(
-      GENERIC_CHAIN_TYPE,
-      genericChainProviderFactory(),
-    );
-    await _globalEdrContext.registerProviderFactory(
-      L1_CHAIN_TYPE,
-      l1ProviderFactory(),
-    );
-    await _globalEdrContext.registerProviderFactory(
-      OP_CHAIN_TYPE,
-      opProviderFactory(),
-    );
-    await _globalEdrContext.registerSolidityTestRunnerFactory(
-      L1_CHAIN_TYPE,
-      l1SolidityTestRunnerFactory(),
-    );
-    await _globalEdrContext.registerSolidityTestRunnerFactory(
-      OP_CHAIN_TYPE,
-      opSolidityTestRunnerFactory(),
-    );
+    const context = createGlobalEdrContext();
+    _globalEdrContext = context;
+
+    // If initialization fails, clear the cached promise so a later call can
+    // retry instead of permanently returning a rejected promise. The identity
+    // guard prevents a stale rejection from wiping a newer promise created by
+    // a retry.
+    context.catch(() => {
+      if (_globalEdrContext === context) {
+        _globalEdrContext = undefined;
+      }
+    });
   }
 
-  return _globalEdrContext;
+  return await _globalEdrContext;
+}
+
+async function createGlobalEdrContext(): Promise<EdrContext> {
+  const context = new EdrContext();
+
+  await context.registerProviderFactory(
+    GENERIC_CHAIN_TYPE,
+    genericChainProviderFactory(),
+  );
+  await context.registerProviderFactory(L1_CHAIN_TYPE, l1ProviderFactory());
+  await context.registerProviderFactory(OP_CHAIN_TYPE, opProviderFactory());
+  await context.registerSolidityTestRunnerFactory(
+    L1_CHAIN_TYPE,
+    l1SolidityTestRunnerFactory(),
+  );
+  await context.registerSolidityTestRunnerFactory(
+    OP_CHAIN_TYPE,
+    opSolidityTestRunnerFactory(),
+  );
+
+  return context;
 }

package/src/internal/using-hardhat2-plugin-errors.ts

@@ -6,7 +6,7 @@ import { shortenPath } from "@nomicfoundation/hardhat-utils/path";
 
 export class UsingHardhat2PluginError extends CustomError {
   public readonly callerRelativePath: string | undefined;
-  constructor() {
+  constructor(apiName: string, migrationHint?: string) {
     const callerPath = getCallerRelativePath();
 
     let message: string;
@@ -18,6 +18,12 @@ This file is part of a Hardhat 2 plugin calling an API that was removed in Hardh
       message = `You are trying to use a Hardhat 2 plugin in a Hardhat 3 project.`;
     }
 
+    message += `\n\nThe removed API is: ${styleText("bold", apiName)}.`;
+
+    if (migrationHint !== undefined) {
+      message += `\n\n${migrationHint}`;
+    }
+
     super(message);
     // Use a non-enumerable property so that `console.error(error)` does not
     // print `{ callerRelativePath: '…' }` after the stack trace.
@@ -98,8 +104,11 @@ export function getCallerRelativePath(depth: number = 5): string | undefined {
   }
 }
 
-export function throwUsingHardhat2PluginError(): never {
+export function throwUsingHardhat2PluginError(
+  apiName: string,
+  migrationHint?: string,
+): never {
   /* eslint-disable-next-line no-restricted-syntax -- Intentionally throwing a
     custom error here so that we always print the stack trace */
-  throw new UsingHardhat2PluginError();
+  throw new UsingHardhat2PluginError(apiName, migrationHint);
 }

package/src/internal/{builtin-plugins/solidity-test/eip712 → utils}/glob.ts

@@ -15,11 +15,11 @@ export function isPathSelected(
     return false;
   }
 
-  if (!matchesAny(path, include)) {
+  if (!matchesAnyGlob(path, include)) {
     return false;
   }
 
-  if (exclude.length > 0 && matchesAny(path, exclude)) {
+  if (exclude.length > 0 && matchesAnyGlob(path, exclude)) {
     return false;
   }
 
@@ -29,7 +29,7 @@ export function isPathSelected(
 /**
  * Returns true if `value` matches at least one of the given glob patterns.
  */
-function matchesAny(value: string, patterns: string[]): boolean {
+export function matchesAnyGlob(value: string, patterns: string[]): boolean {
   for (const pattern of patterns) {
     if (getCompiledGlob(pattern).test(value)) {
       return true;

package/src/plugins.ts

@@ -5,6 +5,9 @@ import type { HardhatPlugin } from "./types/plugins.js";
 import { registerLoadedPlugin } from "./internal/core/plugins/loaded-plugins-registry.js";
 import { throwUsingHardhat2PluginError } from "./internal/using-hardhat2-plugin-errors.js";
 
+const LAZY_LOADING_MIGRATION_HINT =
+  "To migrate a plugin to Hardhat 3, export a plugin object with definePlugin from hardhat/plugins and register lazy-loaded logic through dependencies, hook handlers, and task actions.";
+
 /**
  * Defines a Hardhat plugin.
  *
@@ -25,12 +28,12 @@ export function definePlugin(plugin: HardhatPlugin): HardhatPlugin {
  * @deprecated This function is part of the Hardhat 2 plugin API.
  */
 export function lazyFunction(..._args: any): any {
-  throwUsingHardhat2PluginError();
+  throwUsingHardhat2PluginError("lazyFunction", LAZY_LOADING_MIGRATION_HINT);
 }
 
 /**
  * @deprecated This function is part of the Hardhat 2 plugin API.
  */
 export function lazyObject(..._args: any): any {
-  throwUsingHardhat2PluginError();
+  throwUsingHardhat2PluginError("lazyObject", LAZY_LOADING_MIGRATION_HINT);
 }

package/templates/hardhat-3/01-node-test-runner-viem/package.json

@@ -5,9 +5,9 @@
   "description": "A TypeScript Hardhat project using Node Test Runner and Viem",
   "type": "module",
   "devDependencies": {
-    "hardhat": "workspace:^3.8.0",
+    "hardhat": "workspace:^3.9.1",
     "@nomicfoundation/hardhat-toolbox-viem": "workspace:^5.0.7",
-    "@nomicfoundation/hardhat-ignition": "workspace:^3.1.7",
+    "@nomicfoundation/hardhat-ignition": "workspace:^3.1.8",
     "@types/node": "^22.8.5",
     "forge-std": "foundry-rs/forge-std#v1.9.4",
     "typescript": "~6.0.3",
@@ -16,11 +16,11 @@
   "peerDependencies": {
     "@nomicfoundation/hardhat-ignition-viem": "workspace:^3.1.6",
     "@nomicfoundation/hardhat-keystore": "workspace:^3.0.12",
-    "@nomicfoundation/hardhat-network-helpers": "workspace:^3.0.10",
+    "@nomicfoundation/hardhat-network-helpers": "workspace:^3.0.11",
     "@nomicfoundation/hardhat-node-test-runner": "workspace:^3.0.17",
     "@nomicfoundation/hardhat-viem": "workspace:^3.0.9",
-    "@nomicfoundation/hardhat-viem-assertions": "workspace:^3.1.1",
-    "@nomicfoundation/hardhat-verify": "workspace:^3.0.19",
-    "@nomicfoundation/ignition-core": "workspace:^3.1.7"
+    "@nomicfoundation/hardhat-viem-assertions": "workspace:^3.1.2",
+    "@nomicfoundation/hardhat-verify": "workspace:^3.0.21",
+    "@nomicfoundation/ignition-core": "workspace:^3.1.8"
   }
 }