hardhat 3.1.8 → 3.1.10

package/src/internal/core/tasks/task-manager.ts

@@ -19,6 +19,7 @@ import { TaskDefinitionType } from "../../../types/tasks.js";
 import { ResolvedTask } from "./resolved-task.js";
 import { formatTaskId, getActorFragment } from "./utils.js";
 import {
+  validateAction,
   validateId,
   validateOption,
   validatePositionalArgument,
@@ -41,7 +42,7 @@ export class TaskManagerImplementation implements TaskManager {
       }
 
       for (const taskDefinition of plugin.tasks) {
-        this.#validateTaskDefinition(taskDefinition);
+        this.#validateTaskDefinition(taskDefinition, true);
         this.#reduceTaskDefinition(
           globalOptionDefinitions,
           taskDefinition,
@@ -52,7 +53,7 @@ export class TaskManagerImplementation implements TaskManager {
 
     // reduce global user defined tasks
     for (const taskDefinition of this.#hre.config.tasks) {
-      this.#validateTaskDefinition(taskDefinition);
+      this.#validateTaskDefinition(taskDefinition, false);
       this.#reduceTaskDefinition(globalOptionDefinitions, taskDefinition);
     }
   }
@@ -171,7 +172,9 @@ export class TaskManagerImplementation implements TaskManager {
           this.#hre,
           taskDefinition.id,
           taskDefinition.description,
-          taskDefinition.action,
+          taskDefinition.action !== undefined
+            ? { action: taskDefinition.action }
+            : { inlineAction: taskDefinition.inlineAction },
           taskDefinition.options,
           taskDefinition.positionalArguments,
           pluginId,
@@ -278,10 +281,18 @@ export class TaskManagerImplementation implements TaskManager {
       task.description = taskDefinition.description;
     }
 
-    task.actions.push({ pluginId, action: taskDefinition.action });
+    task.actions.push({
+      pluginId,
+      ...(taskDefinition.action !== undefined
+        ? { action: taskDefinition.action }
+        : { inlineAction: taskDefinition.inlineAction }),
+    });
   }
 
-  #validateTaskDefinition(taskDefinition: TaskDefinition): void {
+  #validateTaskDefinition(
+    taskDefinition: TaskDefinition,
+    isPlugin: boolean,
+  ): void {
     validateId(taskDefinition.id);
 
     // Empty tasks don't have actions, options, or positional arguments
@@ -289,6 +300,13 @@ export class TaskManagerImplementation implements TaskManager {
       return;
     }
 
+    validateAction(
+      taskDefinition.action,
+      taskDefinition.inlineAction,
+      taskDefinition.id,
+      isPlugin,
+    );
+
     const usedNames = new Set<string>();
 
     Object.values(taskDefinition.options).forEach((optionDefinition) =>

package/src/internal/core/tasks/validations.ts

@@ -4,6 +4,12 @@ import type {
   OptionDefinition,
   PositionalArgumentDefinition,
 } from "../../../types/arguments.js";
+import type {
+  LazyActionObject,
+  NewTaskActionFunction,
+  TaskArguments,
+  TaskOverrideActionFunction,
+} from "../../../types/tasks.js";
 
 import { HardhatError } from "@nomicfoundation/hardhat-errors";
 
@@ -23,6 +29,40 @@ export function validateId(id: string | string[]): void {
   }
 }
 
+export function validateAction(
+  action:
+    | LazyActionObject<NewTaskActionFunction<TaskArguments>>
+    | LazyActionObject<TaskOverrideActionFunction<TaskArguments>>
+    | undefined,
+  inlineAction:
+    | NewTaskActionFunction<TaskArguments>
+    | TaskOverrideActionFunction<TaskArguments>
+    | undefined,
+  taskId: string[],
+  isPlugin: boolean,
+): void {
+  if (isPlugin && inlineAction !== undefined) {
+    throw new HardhatError(
+      HardhatError.ERRORS.CORE.TASK_DEFINITIONS.INLINE_ACTION_CANNOT_BE_USED_IN_PLUGINS,
+      { task: formatTaskId(taskId) },
+    );
+  }
+
+  if (action !== undefined && inlineAction !== undefined) {
+    throw new HardhatError(
+      HardhatError.ERRORS.CORE.TASK_DEFINITIONS.ACTION_AND_INLINE_ACTION_SET,
+      { task: formatTaskId(taskId) },
+    );
+  }
+
+  if (action === undefined && inlineAction === undefined) {
+    throw new HardhatError(
+      HardhatError.ERRORS.CORE.TASK_DEFINITIONS.NO_ACTION,
+      { task: formatTaskId(taskId) },
+    );
+  }
+}
+
 export function validateOption(
   { name, shortName, type, defaultValue }: OptionDefinition,
   usedNames: Set<string>,

package/src/internal/deprecated-module-imported-from-hardhat2-plugin.ts

@@ -0,0 +1,12 @@
+// This is an empty module that is used to exported it with a subpath that's
+// commonly used by Hardhat 2 plugins. This is to avoid the plugins breaking
+// when the `require` it, so that they have an opportunity to run a function
+// that throws a better error message.
+
+// The reason this module can be empty is that Hardhat 2 plugins are CJS modules
+// so they can destructure the require and get `undefined` values, instead of
+// a load-time error.
+
+// We could also throw from this file, but if it gets imported by an ESM module
+// you don't get an import-stack-trace, so you loose the possibility of figuring
+// out which plugin is triggering the error.

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

@@ -0,0 +1,108 @@
+import { fileURLToPath } from "node:url";
+
+import { CustomError } from "@nomicfoundation/hardhat-utils/error";
+import { shortenPath } from "@nomicfoundation/hardhat-utils/path";
+import chalk from "chalk";
+
+export class UsingHardhat2PluginError extends CustomError {
+  public readonly callerRelativePath: string | undefined;
+  constructor() {
+    const callerPath = getCallerRelativePath();
+
+    let message: string;
+    if (callerPath !== undefined) {
+      message = `You are trying to use a Hardhat 2 plugin in a Hardhat 3 project.
+
+This file is part of a Hardhat 2 plugin calling an API that was removed in Hardhat 3: ${chalk.bold(callerPath)}
+
+Please read https://hardhat.org/migrate-from-hardhat2 to learn how to migrate your project to Hardhat 3.
+`;
+    } else {
+      message = `You are trying to use a Hardhat 2 plugin in a Hardhat 3 project.
+      
+Check the stack trace below to identify which plugin is causing this.
+
+Please read https://hardhat.org/migrate-from-hardhat2 to learn how to migrate your project to Hardhat 3.
+`;
+    }
+
+    super(message);
+    this.callerRelativePath = callerPath;
+  }
+}
+
+/**
+ * Returns the relative path of the file that called a deprecated Hardhat
+ * plugin API, based on the stack trace. This helps identify which plugin
+ * file is triggering usage of Hardhat 2 APIs in a Hardhat 3 project.
+ *
+ * @param {number} [depth=5] The stack trace depth to locate the caller's
+ * source file. By default, depth 5 is used because:
+ *   0 = message
+ *   1 = getCallerRelativePath
+ *   2 = UsingHardhat2PluginError constructor
+ *   3 = throwUsingHardhat2PluginError
+ *   4 = deprecated function
+ *   5 = actual caller (the plugin file)
+ *
+ * @returns {string|undefined} The shortened relative path of the caller file,
+ * or undefined if not found.
+ *
+ * @example
+ * If the stack trace is:
+ * // Error
+ * //     at getCallerRelativePath (src/internal/using-hardhat2-plugin-errors.ts:34:15)
+ * //     at UsingHardhat2PluginError.constructor (src/internal/using-hardhat2-plugin-errors.ts:7:3)
+ * //     at throwUsingHardhat2PluginError (src/internal/using-hardhat2-plugin-errors.ts:90:3)
+ * //     at deprecatedFunction (plugins/example-plugin/deprecated.js:50:10)
+ * //     at main (plugins/example-plugin/index.js:100:5)
+ * Calling getCallerRelativePath() returns 'plugins/example-plugin/index.js'
+ */
+export function getCallerRelativePath(depth: number = 5): string | undefined {
+  try {
+    const stack = new Error().stack;
+    if (stack === undefined) {
+      return undefined;
+    }
+
+    const lines = stack.split("\n");
+    const callerLine = lines[depth];
+    if (callerLine === undefined) {
+      return undefined;
+    }
+
+    /**
+     * Matches a single stack trace line:
+     *
+     * at FunctionName (path/to/file.ts:10:5)
+     * at path/to/file.ts:10:5
+     *
+     * Captures:
+     *  - group 1: file location (without line/column)
+     */
+    const STACK_TRACE_LINE_REGEX =
+      /^at (?:.+? \()?([^\(].*?)(?::\d+)?(?::\d+)?\)?$/;
+
+    const match = callerLine.trim().match(STACK_TRACE_LINE_REGEX);
+    if (match === null || match[1] === undefined) {
+      return undefined;
+    }
+
+    let filePath = match[1];
+
+    // Handle file:// URLs from ESM stack traces
+    if (filePath.startsWith("file://")) {
+      filePath = fileURLToPath(filePath);
+    }
+
+    return shortenPath(filePath);
+  } catch {
+    return undefined;
+  }
+}
+
+export function throwUsingHardhat2PluginError(): 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();
+}

package/src/plugins.ts

@@ -1 +1,17 @@
 export { HardhatPluginError } from "@nomicfoundation/hardhat-errors";
+
+import { throwUsingHardhat2PluginError } from "./internal/using-hardhat2-plugin-errors.js";
+
+/**
+ * @deprecated This function is part of the Hardhat 2 plugin API.
+ */
+export function lazyFunction(..._args: any): any {
+  throwUsingHardhat2PluginError();
+}
+
+/**
+ * @deprecated This function is part of the Hardhat 2 plugin API.
+ */
+export function lazyObject(..._args: any): any {
+  throwUsingHardhat2PluginError();
+}

package/src/types/index.ts

@@ -0,0 +1,14 @@
+export * from "./arguments.js";
+export * from "./artifacts.js";
+export * from "./config.js";
+export * from "./global-options.js";
+export * from "./hooks.js";
+export * from "./hre.js";
+export * from "./network.js";
+export * from "./plugins.js";
+export * from "./providers.js";
+export * from "./solidity.js";
+export * from "./tasks.js";
+export * from "./test.js";
+export * from "./user-interruptions.js";
+export * from "./utils.js";

package/src/types/plugins.ts

@@ -65,8 +65,8 @@ export interface HardhatPlugin {
    * returning an object with a handler for the `extendUserConfig` hook.
    *
    * You can define each factory in two ways:
-   *  - As an inline function.
-   *  - As a string with the path to a file that exports the factory as `default`.
+   * - As an inline function.
+   * - As a string with the path to a file that exports the factory as `default`.
    *
    * The first option should only be used for development. You MUST use the second
    * option for production.

package/src/types/solidity/errors.ts

@@ -91,6 +91,11 @@ export interface NpmRootFileOfUninstalledPackageError {
   type: RootResolutionErrorType.NPM_ROOT_FILE_OF_UNINSTALLED_PACKAGE;
   npmModule: string;
   installationName: string;
+  /**
+   * A boolean indicating if the Hardhat project has a foundry.toml file in its
+   * root.
+   */
+  projectHasFoundryToml?: boolean;
 }
 
 export interface NpmRootResolutionWithRemappingErrors {
@@ -109,6 +114,10 @@ export interface NpmRootFileWithIncorrectCasingError
   extends ResolvedFileReference {
   type: RootResolutionErrorType.NPM_ROOT_FILE_WITH_INCORRECT_CASING;
   npmModule: string;
+  /**
+   * The correct casing of the file, expressed as the relative fs path from the
+   * package's root, using forward slashes, and without a leading "./".
+   */
   correctCasing: string;
 }
 
@@ -216,6 +225,10 @@ export interface ImportInvalidCasingError extends ResolvedFileReference {
   type: ImportResolutionErrorType.IMPORT_INVALID_CASING;
   fromFsPath: string;
   importPath: string;
+  /**
+   * The correct casing of the file, expressed as the relative fs path from the
+   * package's root, using forward slashes, and without a leading "./".
+   */
   correctCasing: string;
 }
 
@@ -230,6 +243,11 @@ export interface ImportOfUninstalledPackageError {
   fromFsPath: string;
   importPath: string;
   installationName: string;
+  /**
+   * A boolean indicating weather the import is from a source file whose package
+   * has a foundry.toml file in its root.
+   */
+  importerPackageHasFoundryToml?: boolean;
 }
 
 export interface ImportWithRemappingErrorsError {
@@ -348,10 +366,14 @@ export interface ResolvedFileReference {
   //    package's input source name root, after applying the user remapping.
   //  - For an npm import, it's the npm-subpath. i.e. the module identifier
   //    without the package name.
+  //
+  // This never includes a leading "./".
   subpath: string;
 
   // The subpath after resolving package.exports
   //
   // Only present when actually using package.exports.
+  //
+  // This never includes a leading "./".
   packageExportsResolvedSubpath?: string;
 }

package/src/types/tasks.ts

@@ -75,6 +75,17 @@ export enum TaskDefinitionType {
   TASK_OVERRIDE = "TASK_OVERRIDE",
 }
 
+export type TaskAction =
+  | { action: LazyActionObject<NewTaskActionFunction>; inlineAction?: never }
+  | { inlineAction: NewTaskActionFunction; action?: never };
+
+export type TaskOverrideAction =
+  | {
+      action: LazyActionObject<TaskOverrideActionFunction>;
+      inlineAction?: never;
+    }
+  | { inlineAction: TaskOverrideActionFunction; action?: never };
+
 /**
  * Empty task definition. It is meant to be used as a placeholder task that only
  * prints information about its subtasks.
@@ -90,37 +101,44 @@ export interface EmptyTaskDefinition {
 }
 
 /**
- * The definition of a new task.
+ * The base definition of a new task.
  */
-export interface NewTaskDefinition {
+export interface BaseTaskDefinition {
   type: TaskDefinitionType.NEW_TASK;
 
   id: string[];
 
   description: string;
 
-  action: LazyActionObject<NewTaskActionFunction>;
-
   options: Record<string, OptionDefinition>;
 
   positionalArguments: PositionalArgumentDefinition[];
 }
 
 /**
- * An override of an existing task.
+ * The definition of a new task.
  */
-export interface TaskOverrideDefinition {
+export type NewTaskDefinition = BaseTaskDefinition & TaskAction;
+
+/**
+ * The base definition of an override of an existing task.
+ */
+export interface BaseTaskOverrideDefinition {
   type: TaskDefinitionType.TASK_OVERRIDE;
 
   id: string[];
 
   description?: string;
 
-  action: LazyActionObject<TaskOverrideActionFunction>;
-
   options: Record<string, OptionDefinition>;
 }
 
+/**
+ * An override of an existing task.
+ */
+export type TaskOverrideDefinition = BaseTaskOverrideDefinition &
+  TaskOverrideAction;
+
 /**
  * The definition of a task, as used in the plugins and user config. They are
  * declarative descriptions of the task, which are later processed to create the
@@ -160,9 +178,16 @@ export interface EmptyTaskDefinitionBuilder {
 
 /**
  * A builder for creating NewTaskDefinitions.
+ *
+ * @template TaskArgumentsT The arguments of the task.
+ * @template ActionTypeT Tracks if the action is "LAZY_ACTION" (Plugin Safe) or "INLINE_ACTION".
  */
 export interface NewTaskDefinitionBuilder<
   TaskArgumentsT extends TaskArguments = TaskArguments,
+  ActionTypeT extends
+    | "LAZY_ACTION"
+    | "INLINE_ACTION"
+    | "MISSING_ACTION" = "MISSING_ACTION",
 > {
   /**
    * Sets the description of the task.
@@ -172,15 +197,38 @@ export interface NewTaskDefinitionBuilder<
   /**
    * Sets the action of the task.
    *
-   * It can be provided as a function, or as a `file://` URL pointing to a file
-   * that exports a default NewTaskActionFunction.
+   * It must be provided as a lazy import function that returns a module with
+   * a default export, like `() => import("./my-action.js")`.
    *
-   * Note that plugins can only use the inline function form for development
-   * purposes.
+   * Note that plugins cannot use inline actions (see {@link setInlineAction}).
+   * They must use this method with a lazy import.
+   *
+   * @remarks
+   * This method can only be called once per task definition. Calling it multiple
+   * times will result in a runtime error.
+   *
+   * This method cannot be used together with {@link setInlineAction} on the same
+   * task. Use one or the other.
    */
   setAction(
     action: LazyActionObject<NewTaskActionFunction<TaskArgumentsT>>,
-  ): this;
+  ): NewTaskDefinitionBuilder<TaskArgumentsT, "LAZY_ACTION">;
+
+  /**
+   * Sets the inline action of the task.
+   *
+   * It must be provided as a function.
+   *
+   * @remarks
+   * This method can only be called once per task definition. Calling it multiple
+   * times will result in a runtime error.
+   *
+   * This method cannot be used together with {@link setAction} on the same
+   * task. Use one or the other.
+   */
+  setInlineAction(
+    inlineAction: NewTaskActionFunction<TaskArgumentsT>,
+  ): NewTaskDefinitionBuilder<TaskArgumentsT, "INLINE_ACTION">;
 
   /**
    * Adds an option to the task.
@@ -202,7 +250,8 @@ export interface NewTaskDefinitionBuilder<
     defaultValue: ArgumentTypeToValueType<TypeT>;
     hidden?: boolean;
   }): NewTaskDefinitionBuilder<
-    ExtendTaskArguments<NameT, TypeT, TaskArgumentsT>
+    ExtendTaskArguments<NameT, TypeT, TaskArgumentsT>,
+    ActionTypeT
   >;
 
   /**
@@ -214,7 +263,8 @@ export interface NewTaskDefinitionBuilder<
     description?: string;
     hidden?: boolean;
   }): NewTaskDefinitionBuilder<
-    ExtendTaskArguments<NameT, ArgumentType.FLAG, TaskArgumentsT>
+    ExtendTaskArguments<NameT, ArgumentType.FLAG, TaskArgumentsT>,
+    ActionTypeT
   >;
 
   /**
@@ -226,7 +276,8 @@ export interface NewTaskDefinitionBuilder<
     description?: string;
     defaultValue?: number;
   }): NewTaskDefinitionBuilder<
-    ExtendTaskArguments<NameT, ArgumentType.LEVEL, TaskArgumentsT>
+    ExtendTaskArguments<NameT, ArgumentType.LEVEL, TaskArgumentsT>,
+    ActionTypeT
   >;
 
   /**
@@ -254,7 +305,8 @@ export interface NewTaskDefinitionBuilder<
     type?: TypeT;
     defaultValue?: ArgumentTypeToValueType<TypeT>;
   }): NewTaskDefinitionBuilder<
-    ExtendTaskArguments<NameT, TypeT, TaskArgumentsT>
+    ExtendTaskArguments<NameT, TypeT, TaskArgumentsT>,
+    ActionTypeT
   >;
 
   /**
@@ -280,20 +332,35 @@ export interface NewTaskDefinitionBuilder<
     type?: TypeT;
     defaultValue?: Array<ArgumentTypeToValueType<TypeT>>;
   }): NewTaskDefinitionBuilder<
-    ExtendTaskArguments<NameT, TypeT[], TaskArgumentsT>
+    ExtendTaskArguments<NameT, TypeT[], TaskArgumentsT>,
+    ActionTypeT
   >;
 
   /**
    * Builds the NewTaskDefinition.
    */
-  build(): NewTaskDefinition;
+  build(): ActionTypeT extends "LAZY_ACTION"
+    ? Extract<
+        NewTaskDefinition,
+        { action: LazyActionObject<NewTaskActionFunction> }
+      >
+    : ActionTypeT extends "INLINE_ACTION"
+      ? Extract<NewTaskDefinition, { inlineAction: NewTaskActionFunction }>
+      : never;
 }
 
 /**
- * A builder for overriding existing tasks.
+ * A builder for overriding existing tasks
+ *
+ * @template TaskArgumentsT The arguments of the task.
+ * @template ActionTypeT Tracks if the action is "LAZY_ACTION" (Plugin Safe) or "INLINE_ACTION".
  */
 export interface TaskOverrideDefinitionBuilder<
   TaskArgumentsT extends TaskArguments = TaskArguments,
+  ActionTypeT extends
+    | "LAZY_ACTION"
+    | "INLINE_ACTION"
+    | "MISSING_ACTION" = "MISSING_ACTION",
 > {
   /**
    * Sets a new description for the task.
@@ -307,7 +374,16 @@ export interface TaskOverrideDefinitionBuilder<
    */
   setAction(
     action: LazyActionObject<TaskOverrideActionFunction<TaskArgumentsT>>,
-  ): this;
+  ): TaskOverrideDefinitionBuilder<TaskArgumentsT, "LAZY_ACTION">;
+
+  /**
+   * Sets a new inline action for the task.
+   *
+   * @see NewTaskDefinitionBuilder.setInlineAction
+   */
+  setInlineAction(
+    inlineAction: TaskOverrideActionFunction<TaskArgumentsT>,
+  ): TaskOverrideDefinitionBuilder<TaskArgumentsT, "INLINE_ACTION">;
 
   /**
    * Adds a new option to the task.
@@ -325,7 +401,8 @@ export interface TaskOverrideDefinitionBuilder<
     defaultValue: ArgumentTypeToValueType<TypeT>;
     hidden?: boolean;
   }): TaskOverrideDefinitionBuilder<
-    ExtendTaskArguments<NameT, TypeT, TaskArgumentsT>
+    ExtendTaskArguments<NameT, TypeT, TaskArgumentsT>,
+    ActionTypeT
   >;
 
   /**
@@ -337,7 +414,8 @@ export interface TaskOverrideDefinitionBuilder<
     description?: string;
     hidden?: boolean;
   }): TaskOverrideDefinitionBuilder<
-    ExtendTaskArguments<NameT, ArgumentType.FLAG, TaskArgumentsT>
+    ExtendTaskArguments<NameT, ArgumentType.FLAG, TaskArgumentsT>,
+    ActionTypeT
   >;
 
   /**
@@ -349,36 +427,55 @@ export interface TaskOverrideDefinitionBuilder<
     description?: string;
     defaultValue?: number;
   }): TaskOverrideDefinitionBuilder<
-    ExtendTaskArguments<NameT, ArgumentType.LEVEL, TaskArgumentsT>
+    ExtendTaskArguments<NameT, ArgumentType.LEVEL, TaskArgumentsT>,
+    ActionTypeT
   >;
 
   /**
    * Builds the TaskOverrideDefinition.
    */
-  build(): TaskOverrideDefinition;
+  build(): ActionTypeT extends "LAZY_ACTION"
+    ? Extract<
+        TaskOverrideDefinition,
+        { action: LazyActionObject<TaskOverrideActionFunction> }
+      >
+    : ActionTypeT extends "INLINE_ACTION"
+      ? Extract<
+          TaskOverrideDefinition,
+          { inlineAction: TaskOverrideActionFunction }
+        >
+      : never;
 }
 
 /**
  * The actions associated to the task, in order.
  *
  * Each of them has the pluginId of the plugin that defined it, if any, and the
- * action itself.
+ * action itself. The action is stored either in `action` or `inlineAction`.
+ * Note that `inlineAction` is reserved for user tasks and is not allowed for plugins.
  *
- * Note that the first action is a `NewTaskActionFunction`, `string`, or
- * `undefined`. `undefined` is only used for empty tasks.
+ * Note that the first action is a `NewTaskActionFunction` or undefined.
+ * `undefined` is only used for empty tasks.
  *
- * The rest of the actions always have a `TaskOverrideActionFunction` or a
- * `string`.
+ * The rest of the actions always have a `TaskOverrideActionFunction`.
  */
 export type TaskActions = [
+  // The Task Definition
   {
     pluginId?: string;
-    action?: LazyActionObject<NewTaskActionFunction>;
-  },
-  ...Array<{
-    pluginId?: string;
-    action: LazyActionObject<TaskOverrideActionFunction>;
-  }>,
+  } & (
+    | TaskAction
+    | {
+        action?: undefined;
+        inlineAction?: undefined;
+      }
+  ),
+  // The Task Overrides
+  ...Array<
+    {
+      pluginId?: string;
+    } & TaskOverrideAction
+  >,
 ];
 
 /**