hardhat 3.1.9 → 3.1.11

package/src/types/tasks.ts

@@ -5,6 +5,8 @@ import type {
   PositionalArgumentDefinition,
 } from "./arguments.js";
 import type { HardhatRuntimeEnvironment } from "./hre.js";
+/* eslint-disable-next-line @typescript-eslint/no-unused-vars -- used in JSDoc {@link} */
+import type { Result } from "./utils.js";
 
 // We add the TaskManager to the HRE with a module augmentation to avoid
 // introducing a circular dependency that would look like this:
@@ -75,6 +77,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 +103,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 type NewTaskDefinition = BaseTaskDefinition & TaskAction;
+
+/**
+ * The base definition of an override of an existing task.
  */
-export interface TaskOverrideDefinition {
+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 +180,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 +199,46 @@ 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 cannot use inline actions (see {@link setInlineAction}).
+   * They must use this method with a lazy import.
    *
-   * Note that plugins can only use the inline function form for development
-   * purposes.
+   * @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.
+   *
+   * Task actions may return a {@link Result} to signal success or failure.
+   * If a task returns a failed `Result`, the CLI will set the process exit code
+   * to 1.
    */
   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.
+   *
+   * Task actions may return a {@link Result} to signal success or failure.
+   * If a task returns a failed `Result`, the CLI will set the process exit code
+   * to 1.
+   */
+  setInlineAction(
+    inlineAction: NewTaskActionFunction<TaskArgumentsT>,
+  ): NewTaskDefinitionBuilder<TaskArgumentsT, "INLINE_ACTION">;
 
   /**
    * Adds an option to the task.
@@ -202,7 +260,8 @@ export interface NewTaskDefinitionBuilder<
     defaultValue: ArgumentTypeToValueType<TypeT>;
     hidden?: boolean;
   }): NewTaskDefinitionBuilder<
-    ExtendTaskArguments<NameT, TypeT, TaskArgumentsT>
+    ExtendTaskArguments<NameT, TypeT, TaskArgumentsT>,
+    ActionTypeT
   >;
 
   /**
@@ -214,7 +273,8 @@ export interface NewTaskDefinitionBuilder<
     description?: string;
     hidden?: boolean;
   }): NewTaskDefinitionBuilder<
-    ExtendTaskArguments<NameT, ArgumentType.FLAG, TaskArgumentsT>
+    ExtendTaskArguments<NameT, ArgumentType.FLAG, TaskArgumentsT>,
+    ActionTypeT
   >;
 
   /**
@@ -226,7 +286,8 @@ export interface NewTaskDefinitionBuilder<
     description?: string;
     defaultValue?: number;
   }): NewTaskDefinitionBuilder<
-    ExtendTaskArguments<NameT, ArgumentType.LEVEL, TaskArgumentsT>
+    ExtendTaskArguments<NameT, ArgumentType.LEVEL, TaskArgumentsT>,
+    ActionTypeT
   >;
 
   /**
@@ -254,7 +315,8 @@ export interface NewTaskDefinitionBuilder<
     type?: TypeT;
     defaultValue?: ArgumentTypeToValueType<TypeT>;
   }): NewTaskDefinitionBuilder<
-    ExtendTaskArguments<NameT, TypeT, TaskArgumentsT>
+    ExtendTaskArguments<NameT, TypeT, TaskArgumentsT>,
+    ActionTypeT
   >;
 
   /**
@@ -280,20 +342,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 +384,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 +411,8 @@ export interface TaskOverrideDefinitionBuilder<
     defaultValue: ArgumentTypeToValueType<TypeT>;
     hidden?: boolean;
   }): TaskOverrideDefinitionBuilder<
-    ExtendTaskArguments<NameT, TypeT, TaskArgumentsT>
+    ExtendTaskArguments<NameT, TypeT, TaskArgumentsT>,
+    ActionTypeT
   >;
 
   /**
@@ -337,7 +424,8 @@ export interface TaskOverrideDefinitionBuilder<
     description?: string;
     hidden?: boolean;
   }): TaskOverrideDefinitionBuilder<
-    ExtendTaskArguments<NameT, ArgumentType.FLAG, TaskArgumentsT>
+    ExtendTaskArguments<NameT, ArgumentType.FLAG, TaskArgumentsT>,
+    ActionTypeT
   >;
 
   /**
@@ -349,36 +437,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
+  >,
 ];
 
 /**

package/src/types/test.ts

@@ -5,3 +5,15 @@ export interface HardhatTestUserConfig {}
 /* eslint-disable-next-line @typescript-eslint/no-empty-interface -- Empty
 interface allow plugins to extend the Test configuration for Hardhat. */
 export interface HardhatTestConfig {}
+
+/**
+ * Summary of a test run, containing counts of test outcomes and optional
+ * failure output.
+ */
+export interface TestSummary {
+  failed: number;
+  passed: number;
+  skipped: number;
+  todo: number;
+  failureOutput?: string;
+}

package/src/types/utils.ts

@@ -50,3 +50,17 @@ export type Return<T> = T extends (...args: any[]) => infer Ret ? Ret : never;
 export type RequireField<T, K extends keyof T> = T & {
   [P in K]-?: T[P];
 };
+
+/**
+ * A result that can either have a value or an error.
+ */
+export type Result<ValueT, ErrorT> =
+  | { readonly success: true; readonly value: ValueT }
+  | { readonly success: false; readonly error: ErrorT };
+
+/**
+ * Returns the keys of T tht don't map to never.
+ */
+export type NonNeverKeys<T> = {
+  [K in keyof T]: T[K] extends never ? never : K;
+}[keyof T];

package/src/utils/result.ts

@@ -0,0 +1,57 @@
+import type { Result } from "../types/utils.js";
+
+import { isObject } from "@nomicfoundation/hardhat-utils/lang";
+
+/**
+ * Creates a successful Result with the given value.
+ *
+ * @param value The value to include in the result.
+ * @returns A Result with success: true and the given value.
+ */
+export function successfulResult<ValueT = undefined>(
+  ...args: ValueT extends undefined | void ? [] : [value: ValueT]
+): { success: true; value: ValueT } {
+  /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  -- Cast needed because TS loses the conditional rest parameter context */
+  return { success: true, value: args[0] as ValueT };
+}
+
+/**
+ * Creates a failed Result with the given error.
+ *
+ * @param error The error to include in the result.
+ * @returns A Result with success: false and the given error.
+ */
+export function errorResult<ErrorT = undefined>(
+  ...args: ErrorT extends undefined | void ? [] : [error: ErrorT]
+): { success: false; error: ErrorT } {
+  /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  -- Cast needed because TS loses the conditional rest parameter context */
+  return { success: false, error: args[0] as ErrorT };
+}
+
+/**
+ * A type guard that checks if a value is a Result.
+ *
+ * Optionally validates the value and error fields using type guard functions.
+ *
+ * @param value The value to check.
+ * @param isValue Optional type guard for the value field.
+ * @param isError Optional type guard for the error field.
+ * @returns true if the value is a Result.
+ */
+export function isResult<ValueT = unknown, ErrorT = unknown>(
+  value: unknown,
+  isValue?: (v: unknown) => v is ValueT,
+  isError?: (e: unknown) => e is ErrorT,
+): value is Result<ValueT, ErrorT> {
+  if (!isObject(value) || typeof value.success !== "boolean") {
+    return false;
+  }
+
+  if (value.success === true) {
+    return "value" in value && (isValue === undefined || isValue(value.value));
+  }
+
+  return "error" in value && (isError === undefined || isError(value.error));
+}

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

@@ -5,22 +5,22 @@
   "description": "A TypeScript Hardhat project using Node Test Runner and Viem",
   "type": "module",
   "devDependencies": {
-    "hardhat": "workspace:^3.1.9",
-    "@nomicfoundation/hardhat-toolbox-viem": "workspace:^5.0.2",
-    "@nomicfoundation/hardhat-ignition": "workspace:^3.0.7",
+    "hardhat": "workspace:^3.1.11",
+    "@nomicfoundation/hardhat-toolbox-viem": "workspace:^5.0.3",
+    "@nomicfoundation/hardhat-ignition": "workspace:^3.0.9",
     "@types/node": "^22.8.5",
     "forge-std": "foundry-rs/forge-std#v1.9.4",
     "typescript": "~5.8.0",
     "viem": "^2.43.0"
   },
   "peerDependencies": {
-    "@nomicfoundation/hardhat-ignition-viem": "workspace:^3.0.7",
-    "@nomicfoundation/hardhat-keystore": "workspace:^3.0.4",
-    "@nomicfoundation/hardhat-network-helpers": "workspace:^3.0.3",
-    "@nomicfoundation/hardhat-node-test-runner": "workspace:^3.0.8",
-    "@nomicfoundation/hardhat-viem": "workspace:^3.0.2",
-    "@nomicfoundation/hardhat-viem-assertions": "workspace:^3.0.5",
-    "@nomicfoundation/hardhat-verify": "workspace:^3.0.10",
-    "@nomicfoundation/ignition-core": "workspace:^3.0.7"
+    "@nomicfoundation/hardhat-ignition-viem": "workspace:^3.0.9",
+    "@nomicfoundation/hardhat-keystore": "workspace:^3.0.5",
+    "@nomicfoundation/hardhat-network-helpers": "workspace:^3.0.4",
+    "@nomicfoundation/hardhat-node-test-runner": "workspace:^3.0.10",
+    "@nomicfoundation/hardhat-viem": "workspace:^3.0.4",
+    "@nomicfoundation/hardhat-viem-assertions": "workspace:^3.0.7",
+    "@nomicfoundation/hardhat-verify": "workspace:^3.0.12",
+    "@nomicfoundation/ignition-core": "workspace:^3.0.9"
   }
 }

package/templates/hardhat-3/02-mocha-ethers/package.json

@@ -5,30 +5,30 @@
   "description": "A TypeScript Hardhat project using Mocha and Ethers.js",
   "type": "module",
   "devDependencies": {
-    "hardhat": "workspace:^3.1.9",
-    "@nomicfoundation/hardhat-toolbox-mocha-ethers": "workspace:^3.0.2",
-    "@nomicfoundation/hardhat-ethers": "workspace:^4.0.4",
-    "@nomicfoundation/hardhat-ignition": "workspace:^3.0.7",
-    "@types/chai": "^4.2.0",
+    "hardhat": "workspace:^3.1.11",
+    "@nomicfoundation/hardhat-toolbox-mocha-ethers": "workspace:^3.0.3",
+    "@nomicfoundation/hardhat-ethers": "workspace:^4.0.6",
+    "@nomicfoundation/hardhat-ignition": "workspace:^3.0.9",
+    "@types/chai": "^5.2.3",
     "@types/chai-as-promised": "^8.0.1",
     "@types/mocha": ">=10.0.10",
     "@types/node": "^22.8.5",
-    "chai": "^5.1.2",
+    "chai": "^6.2.2",
     "ethers": "^6.14.0",
     "forge-std": "foundry-rs/forge-std#v1.9.4",
     "mocha": "^11.0.0",
     "typescript": "~5.8.0"
   },
   "peerDependencies": {
-    "@nomicfoundation/hardhat-ethers": "workspace:^4.0.4",
-    "@nomicfoundation/hardhat-ethers-chai-matchers": "workspace:^3.0.2",
-    "@nomicfoundation/hardhat-ignition": "workspace:^3.0.7",
-    "@nomicfoundation/hardhat-ignition-ethers": "workspace:^3.0.7",
-    "@nomicfoundation/hardhat-keystore": "workspace:^3.0.4",
-    "@nomicfoundation/hardhat-mocha": "workspace:^3.0.10",
-    "@nomicfoundation/hardhat-network-helpers": "workspace:^3.0.3",
-    "@nomicfoundation/hardhat-typechain": "workspace:^3.0.2",
-    "@nomicfoundation/hardhat-verify": "workspace:^3.0.10",
-    "@nomicfoundation/ignition-core": "workspace:^3.0.7"
+    "@nomicfoundation/hardhat-ethers": "workspace:^4.0.6",
+    "@nomicfoundation/hardhat-ethers-chai-matchers": "workspace:^3.0.3",
+    "@nomicfoundation/hardhat-ignition": "workspace:^3.0.9",
+    "@nomicfoundation/hardhat-ignition-ethers": "workspace:^3.0.9",
+    "@nomicfoundation/hardhat-keystore": "workspace:^3.0.5",
+    "@nomicfoundation/hardhat-mocha": "workspace:^3.0.12",
+    "@nomicfoundation/hardhat-network-helpers": "workspace:^3.0.4",
+    "@nomicfoundation/hardhat-typechain": "workspace:^3.0.4",
+    "@nomicfoundation/hardhat-verify": "workspace:^3.0.12",
+    "@nomicfoundation/ignition-core": "workspace:^3.0.9"
   }
 }

package/templates/hardhat-3/03-minimal/package.json

@@ -5,7 +5,7 @@
   "description": "A minimal Hardhat project",
   "type": "module",
   "devDependencies": {
-    "hardhat": "workspace:^3.1.9",
+    "hardhat": "workspace:^3.1.11",
     "@types/node": "^22.8.5",
     "typescript": "~5.8.0"
   }

package/dist/src/internal/builtin-plugins/network-manager/edr/types/output.d.ts

@@ -1,19 +0,0 @@
-export interface RpcStructLog {
-    depth: number;
-    gas: number;
-    gasCost: number;
-    op: string;
-    pc: number;
-    memory?: string[];
-    stack?: string[];
-    storage?: Record<string, string>;
-    memSize?: number;
-    error?: Record<string, string>;
-}
-export interface RpcDebugTraceOutput {
-    failed: boolean;
-    gas: number;
-    returnValue: string;
-    structLogs: RpcStructLog[];
-}
-//# sourceMappingURL=output.d.ts.map

package/dist/src/internal/builtin-plugins/network-manager/edr/types/output.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../../../../../../src/internal/builtin-plugins/network-manager/edr/types/output.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,YAAY,EAAE,CAAC;CAC5B"}

package/dist/src/internal/builtin-plugins/network-manager/edr/types/output.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=output.js.map

package/dist/src/internal/builtin-plugins/network-manager/edr/types/output.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"output.js","sourceRoot":"","sources":["../../../../../../../src/internal/builtin-plugins/network-manager/edr/types/output.ts"],"names":[],"mappings":""}

package/src/internal/builtin-plugins/network-manager/edr/types/output.ts

@@ -1,19 +0,0 @@
-export interface RpcStructLog {
-  depth: number;
-  gas: number;
-  gasCost: number;
-  op: string;
-  pc: number;
-  memory?: string[];
-  stack?: string[];
-  storage?: Record<string, string>;
-  memSize?: number;
-  error?: Record<string, string>;
-}
-
-export interface RpcDebugTraceOutput {
-  failed: boolean;
-  gas: number;
-  returnValue: string;
-  structLogs: RpcStructLog[];
-}