hardhat 3.9.0 → 3.9.1

package/src/internal/builtin-plugins/index.ts

@@ -6,6 +6,10 @@ import console from "./console/index.js";
 import coverage from "./coverage/index.js";
 import flatten from "./flatten/index.js";
 import gasAnalytics from "./gas-analytics/index.js";
+// The hhu / `utils` feature is unreleased and intentionally not wired up yet.
+// To enable it, uncomment the three `hhu` lines (this import, the type re-export
+// below, and the `builtinPlugins` entry) and re-add `bin.hhu` in package.json.
+// import hhu from "./hhu/index.js";
 import networkManager from "./network-manager/index.js";
 import node from "./node/index.js";
 import run from "./run/index.js";
@@ -22,6 +26,7 @@ export type * from "./console/index.js";
 export type * from "./coverage/index.js";
 export type * from "./flatten/index.js";
 export type * from "./gas-analytics/index.js";
+// export type * from "./hhu/index.js";
 export type * from "./network-manager/index.js";
 export type * from "./node/index.js";
 export type * from "./run/index.js";
@@ -46,4 +51,5 @@ export const builtinPlugins: HardhatPlugin[] = [
   node,
   flatten,
   telemetry,
+  // hhu,
 ];

package/src/internal/builtin-plugins/network-manager/edr/stack-traces/stack-trace-solidity-errors.ts

@@ -21,6 +21,32 @@ import {
   UNRECOGNIZED_FUNCTION_NAME,
 } from "./solidity-stack-trace.js";
 
+interface CheatcodeSuggestion {
+  message: string;
+  docsUrl?: string;
+}
+
+const CHEATCODE_SUGGESTIONS: Record<string, CheatcodeSuggestion> = {
+  "eip712HashType(string,string)": {
+    message:
+      "Providing a path to a bindings file is not supported, please use the eip712HashType(string calldata typeNameOrDefinition) cheatcode instead.",
+    docsUrl:
+      "https://hardhat.org/docs/reference/cheatcodes/utilities/eip712-hash-type",
+  },
+};
+
+export function getCheatcodeSuggestion(cheatcode: string): string {
+  const suggestion = CHEATCODE_SUGGESTIONS[cheatcode];
+
+  if (suggestion === undefined) {
+    return "";
+  }
+
+  return suggestion.docsUrl !== undefined
+    ? `${suggestion.message} See ${suggestion.docsUrl} for more information.`
+    : suggestion.message;
+}
+
 export function createSolidityErrorWithStackTrace(
   fallbackMessage: string,
   stackTrace: SolidityStackTrace,
@@ -277,6 +303,13 @@ function getMessageFromLastStackTraceEntry(
         switch (stackTraceEntry.details.code) {
           case CheatcodeErrorCode.UnsupportedCheatcode:
             message = `Cheatcode '${stackTraceEntry.details.cheatcode}' is not supported by Hardhat.`;
+
+            const suggestion = getCheatcodeSuggestion(
+              stackTraceEntry.details.cheatcode,
+            );
+
+            message += suggestion.length > 0 ? " " + suggestion : "";
+
             break;
           case CheatcodeErrorCode.MissingCheatcode:
             message = `Cheatcode '${stackTraceEntry.details.cheatcode}' is not yet available in this version of Hardhat.`;

package/src/internal/builtin-plugins/network-manager/index.ts

@@ -1,8 +1,8 @@
 import type { HardhatPlugin } from "../../../types/plugins.js";
 
 import { definePlugin } from "../../../plugins.js";
-import { ArgumentType } from "../../../types/arguments.js";
-import { globalOption } from "../../core/config.js";
+
+import { NETWORK_GLOBAL_OPTION } from "./network-option.js";
 
 export type * from "./type-extensions/config.js";
 export type * from "./type-extensions/global-options.js";
@@ -16,14 +16,7 @@ const hardhatPlugin: HardhatPlugin = definePlugin({
     hre: () => import("./hook-handlers/hre.js"),
     network: () => import("./hook-handlers/network.js"),
   },
-  globalOptions: [
-    globalOption({
-      name: "network",
-      description: "The network to connect to",
-      type: ArgumentType.STRING_WITHOUT_DEFAULT,
-      defaultValue: undefined,
-    }),
-  ],
+  globalOptions: [NETWORK_GLOBAL_OPTION],
   npmPackage: "hardhat",
   dependencies: () => [import("../artifacts/index.js")],
 });

package/src/internal/builtin-plugins/network-manager/network-option.ts

@@ -0,0 +1,17 @@
+import type { GlobalOptionDefinition } from "../../../types/arguments.js";
+
+import { ArgumentType } from "../../../types/arguments.js";
+import { globalOption } from "../../core/config.js";
+
+/**
+ * The `--network` global option, contributed by the network-manager plugin.
+ *
+ * Exported so the standalone hhu binary, which doesn't load the plugin, can
+ * reuse the exact same definition instead of duplicating it.
+ */
+export const NETWORK_GLOBAL_OPTION: GlobalOptionDefinition = globalOption({
+  name: "network",
+  description: "The network to connect to",
+  type: ArgumentType.STRING_WITHOUT_DEFAULT,
+  defaultValue: undefined,
+});

package/src/internal/builtin-plugins/network-manager/request-handlers/handlers/accounts/automatic-sender-handler.ts

@@ -1,32 +1,62 @@
-import { assertHardhatInvariant } from "@nomicfoundation/hardhat-errors";
+import type {
+  JsonRpcRequest,
+  JsonRpcResponse,
+} from "../../../../../../types/providers.js";
+
+import { isObject } from "@nomicfoundation/hardhat-utils/lang";
+
+import { getRequestParams } from "../../../json-rpc.js";
+import { InternalError } from "../../../provider-errors.js";
 
 import { SenderHandler } from "./sender.js";
 
 /**
  * This class automatically retrieves and caches the first available account from the connected provider.
- * It overrides the getSender method of the base class to request the list of accounts if the first account has not been fetched yet,
- * ensuring dynamic selection of the sender for all JSON-RPC requests without requiring manual input.
+ * On the first supported request, fetches and caches `eth_accounts` so callers don't need to set `from` manually.
+ * If `eth_accounts` responds with a non-array, it returns a JSON-RPC error.
  */
 export class AutomaticSenderHandler extends SenderHandler {
   #alreadyFetchedAccounts = false;
   #firstAccount: string | undefined;
 
-  protected async getSender(): Promise<string | undefined> {
+  public override async handle(
+    jsonRpcRequest: JsonRpcRequest,
+  ): Promise<JsonRpcRequest | JsonRpcResponse> {
+    if (!this.isSupportedMethod(jsonRpcRequest)) {
+      return jsonRpcRequest;
+    }
+
+    const [tx] = getRequestParams(jsonRpcRequest);
+    if (!isObject(tx) || tx.from !== undefined) {
+      // Skip the eth_accounts fetch when we won't need a sender anyway:
+      // the tx isn't an object, or it already carries a `from`.
+      return await super.handle(jsonRpcRequest);
+    }
+
     if (this.#alreadyFetchedAccounts === false) {
       const accounts = await this.provider.request({
         method: "eth_accounts",
       });
 
-      // TODO: This shouldn't be an exception but a failed JSON response!
-      assertHardhatInvariant(
-        Array.isArray(accounts),
-        "eth_accounts response should be an array",
-      );
+      if (!Array.isArray(accounts)) {
+        return {
+          jsonrpc: "2.0",
+          id: jsonRpcRequest.id,
+          error: {
+            code: InternalError.CODE,
+            message: "eth_accounts did not return an array of accounts",
+          },
+        };
+      }
 
       this.#firstAccount = accounts[0];
       this.#alreadyFetchedAccounts = true;
     }
 
+    return await super.handle(jsonRpcRequest);
+  }
+
+  protected async getSender(): Promise<string | undefined> {
     return this.#firstAccount;
   }
 }

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

@@ -55,10 +55,7 @@ const solidityTestProfileUserConfigType = z.object({
   prevRandao: z.bigint().optional(),
   gasLimit: z.bigint().optional(),
   blockGasLimit: z.number().or(z.bigint()).or(z.literal(false)).optional(),
-  // TODO: widen back to .number().or(z.bigint()).or(z.literal(false))
-  // once Solidity test runner no longer breaks setUp() when
-  // disableTransactionGasCap is false. See PR #8301.
-  transactionGasCap: z.literal(false).optional(),
+  transactionGasCap: z.number().or(z.bigint()).or(z.literal(false)).optional(),
   fuzz: z
     .object({
       failurePersistDir: z.string().optional(),

package/src/internal/builtin-plugins/solidity-test/stack-trace-solidity-errors.ts

@@ -6,6 +6,7 @@ import {
   StackTraceEntryType,
   CheatcodeErrorCode,
 } from "../network-manager/edr/stack-traces/solidity-stack-trace.js";
+import { getCheatcodeSuggestion } from "../network-manager/edr/stack-traces/stack-trace-solidity-errors.js";
 
 export function getMessageFromLastStackTraceEntry(
   stackTraceEntry: SolidityStackTraceEntry,
@@ -71,7 +72,11 @@ export function getMessageFromLastStackTraceEntry(
       if (stackTraceEntry.details !== undefined) {
         switch (stackTraceEntry.details.code) {
           case CheatcodeErrorCode.UnsupportedCheatcode:
-            return `Cheatcode '${stackTraceEntry.details.cheatcode}' is not supported by Hardhat.`;
+            const suggestion = getCheatcodeSuggestion(
+              stackTraceEntry.details.cheatcode,
+            );
+
+            return `Cheatcode '${stackTraceEntry.details.cheatcode}' is not supported by Hardhat.${suggestion.length > 0 ? " " + suggestion : ""}`;
           case CheatcodeErrorCode.MissingCheatcode:
             return `Cheatcode '${stackTraceEntry.details.cheatcode}' is not yet available in this version of Hardhat.`;
         }

package/src/internal/cli/help/get-global-help-string.ts

@@ -14,6 +14,7 @@ import {
 export async function getGlobalHelpString(
   rootTasks: Map<string, Task>,
   globalOptionDefinitions: GlobalOptionDefinitions,
+  { command = "hardhat" }: { command?: "hardhat" | "hhu" } = {},
 ): Promise<string> {
   const version = await getHardhatVersion();
 
@@ -27,7 +28,7 @@ export async function getGlobalHelpString(
 
   let output = `Hardhat version ${version}
 
-Usage: hardhat [GLOBAL OPTIONS] <TASK> [SUBTASK] [TASK OPTIONS] [--] [TASK ARGUMENTS]
+Usage: ${command} [GLOBAL OPTIONS] <TASK> [SUBTASK] [TASK OPTIONS] [--] [TASK ARGUMENTS]
 `;
 
   if (tasks.length > 0) {
@@ -40,7 +41,7 @@ Usage: hardhat [GLOBAL OPTIONS] <TASK> [SUBTASK] [TASK OPTIONS] [--] [TASK ARGUM
 
   output += getSection("GLOBAL OPTIONS", globalOptions, namePadding);
 
-  output += `\nTo get help for a specific task run: npx hardhat <TASK> [SUBTASK] --help`;
+  output += `\nTo get help for a specific task run: npx ${command} <TASK> [SUBTASK] --help`;
 
   return output;
 }

package/src/internal/cli/help/get-help-string.ts

@@ -16,6 +16,7 @@ import {
 export async function getHelpString(
   task: Task,
   globalOptionDefinitions: GlobalOptionDefinitions,
+  { command = "hardhat" }: { command?: "hardhat" | "hhu" } = {},
 ): Promise<string> {
   const { options, positionalArguments } = parseOptions(task);
 
@@ -34,20 +35,20 @@ export async function getHelpString(
   let output = `${styleText("bold", task.description)}`;
 
   if (task.isEmpty) {
-    output += `\n\nUsage: hardhat [GLOBAL OPTIONS] ${task.id.join(" ")} <SUBTASK> [SUBTASK OPTIONS] [--] [SUBTASK POSITIONAL ARGUMENTS]\n`;
+    output += `\n\nUsage: ${command} [GLOBAL OPTIONS] ${task.id.join(" ")} <SUBTASK> [SUBTASK OPTIONS] [--] [SUBTASK POSITIONAL ARGUMENTS]\n`;
 
     if (subtasks.length > 0) {
       output += getSection("AVAILABLE SUBTASKS", subtasks, namePadding);
 
       output += getSection("GLOBAL OPTIONS", globalOptions, namePadding);
 
-      output += `\nTo get help for a specific task run: npx hardhat ${task.id.join(" ")} <SUBTASK> --help`;
+      output += `\nTo get help for a specific task run: npx ${command} ${task.id.join(" ")} <SUBTASK> --help`;
     }
 
     return output;
   }
 
-  const usage = getUsageString(task, options, positionalArguments);
+  const usage = getUsageString(task, options, positionalArguments, { command });
 
   output += `\n\n${usage}\n`;
 

package/src/internal/cli/help/utils.ts

@@ -172,8 +172,9 @@ export function getUsageString(
   task: Task,
   options: ReturnType<typeof parseOptions>["options"],
   positionalArguments: ReturnType<typeof parseOptions>["positionalArguments"],
+  { command = "hardhat" }: { command?: "hardhat" | "hhu" } = {},
 ): string {
-  let output = `Usage: hardhat [GLOBAL OPTIONS] ${task.id.join(" ")}`;
+  let output = `Usage: ${command} [GLOBAL OPTIONS] ${task.id.join(" ")}`;
 
   if (options.length > 0) {
     output += ` ${options

package/src/internal/cli/hhu.ts

@@ -0,0 +1,298 @@
+import type { GlobalOptionDefinitions } from "../../types/global-options.js";
+import type { HardhatRuntimeEnvironment } from "../../types/hre.js";
+import type { Task, TaskDefinition } from "../../types/tasks.js";
+import type { FakeHhuHardhatRuntimeEnvironment } from "../builtin-plugins/hhu/types.js";
+
+import {
+  assertHardhatInvariant,
+  HardhatError,
+} from "@nomicfoundation/hardhat-errors";
+import { isCi } from "@nomicfoundation/hardhat-utils/ci";
+import { createDebug } from "@nomicfoundation/hardhat-utils/debug";
+import { setGlobalOptionsAsEnvVariables } from "@nomicfoundation/hardhat-utils/env";
+import { ensureError } from "@nomicfoundation/hardhat-utils/error";
+
+import { isResult } from "../../utils/result.js";
+import { generateTasks } from "../builtin-plugins/hhu/tasks/index.js";
+import { NETWORK_GLOBAL_OPTION } from "../builtin-plugins/network-manager/network-option.js";
+import { globalFlag } from "../core/config.js";
+import { TaskManagerImplementation } from "../core/tasks/task-manager.js";
+import { getHardhatVersion } from "../utils/package.js";
+
+import { printErrorMessages } from "./error-handler.js";
+import { getGlobalHelpString } from "./help/get-global-help-string.js";
+import { getHelpString } from "./help/get-help-string.js";
+import {
+  parseGlobalOptions,
+  parseRawArguments,
+  parseTask,
+  parseTaskArguments,
+} from "./parser.js";
+import { sendTaskAnalytics } from "./telemetry/analytics/analytics.js";
+import { setupGlobalUnhandledErrorHandlers } from "./telemetry/error-reporter/global-error-handlers.js";
+import { sendErrorTelemetry } from "./telemetry/error-reporter/reporter.js";
+
+interface MainOptions {
+  print?: (message: string) => void;
+  rethrowErrors?: true;
+}
+
+export async function main(
+  rawArguments: string[],
+  options: MainOptions = {},
+): Promise<void> {
+  // We set up the global unhandled errors before running any functionality
+  setupGlobalUnhandledErrorHandlers();
+
+  const print = options.print ?? console.log;
+
+  const log = createDebug("hardhat:core:hhu:main");
+
+  let hhuGlobalOptions;
+
+  log("hhu started");
+
+  try {
+    const cliArguments = parseRawArguments(rawArguments);
+
+    const usedCliArguments: boolean[] = new Array(cliArguments.length).fill(
+      false,
+    );
+
+    hhuGlobalOptions = await parseHhuGlobalOptions(
+      cliArguments,
+      usedCliArguments,
+    );
+
+    // We forward `network` as an env variable so it's available when we lazily
+    // import the real HRE in utils that need it. We explicitly whitelist it
+    // (rather than forwarding every hhu global option) so that hhu-only options
+    // never leak into the real HRE's global-option namespace.
+    setGlobalOptionsAsEnvVariables({ network: hhuGlobalOptions.network });
+
+    log("Parsed hhu global options");
+
+    if (hhuGlobalOptions.version) {
+      return await printHhuVersionMessage(print);
+    }
+
+    const globalOptionDefinitions: GlobalOptionDefinitions = new Map(
+      HHU_GLOBAL_OPTIONS_DEFINITIONS,
+    );
+
+    const rootTasks = taskDefinitionsToTasksMap(
+      generateTasks({ prefixWithUtils: false }),
+    );
+
+    const taskOrId = parseTask(cliArguments, usedCliArguments, rootTasks);
+
+    if (Array.isArray(taskOrId)) {
+      if (taskOrId.length === 0) {
+        const globalHelp = await getGlobalHelpString(
+          rootTasks,
+          globalOptionDefinitions,
+          { command: "hhu" },
+        );
+
+        print(globalHelp);
+        return;
+      }
+
+      throw new HardhatError(
+        HardhatError.ERRORS.CORE.TASK_DEFINITIONS.TASK_NOT_FOUND,
+        { task: taskOrId.join(" ") },
+      );
+    }
+
+    const task = taskOrId;
+
+    if (task.isEmpty && usedCliArguments.includes(false)) {
+      const invalidSubtask = cliArguments[usedCliArguments.indexOf(false)];
+
+      throw new HardhatError(
+        HardhatError.ERRORS.CORE.TASK_DEFINITIONS.UNRECOGNIZED_SUBTASK,
+        {
+          task: task.id.join(" "),
+          invalidSubtask,
+        },
+      );
+    }
+
+    if (hhuGlobalOptions.help || task.isEmpty) {
+      const taskHelp = await getHelpString(task, globalOptionDefinitions, {
+        command: "hhu",
+      });
+
+      print(taskHelp);
+      return;
+    }
+
+    const taskArguments = parseTaskArguments(
+      cliArguments,
+      usedCliArguments,
+      task,
+    );
+
+    log(`Running task "${task.id.join(" ")}"`);
+
+    const [taskResult] = await Promise.all([
+      task.run(taskArguments),
+      sendTaskAnalytics(task.id, "hhu"),
+    ]);
+
+    if (isResult(taskResult) && !taskResult.success) {
+      process.exitCode = 1;
+    }
+  } catch (error) {
+    ensureError(error);
+    await printErrorMessages(error, hhuGlobalOptions?.showStackTraces);
+
+    try {
+      await sendErrorTelemetry(error);
+    } catch (e) {
+      log("Couldn't report error to sentry: %O", e);
+    }
+
+    if (options.rethrowErrors) {
+      throw error;
+    }
+
+    process.exitCode = 1;
+  }
+}
+
+const HHU_GLOBAL_OPTIONS_DEFINITIONS: GlobalOptionDefinitions = new Map([
+  [
+    "help",
+    {
+      pluginId: "builtin",
+      option: globalFlag({
+        name: "help",
+        shortName: "h",
+        description:
+          "Show this message, or a task's help if its name is provided.",
+      }),
+    },
+  ],
+  [
+    "showStackTraces",
+    {
+      pluginId: "builtin",
+      option: globalFlag({
+        name: "showStackTraces",
+        description: "Show stack traces (always enabled on CI servers).",
+      }),
+    },
+  ],
+  [
+    "version",
+    {
+      pluginId: "builtin",
+      option: globalFlag({
+        name: "version",
+        description: "Show the version of hhu.",
+      }),
+    },
+  ],
+  [
+    "network",
+    {
+      pluginId: "builtin",
+      option: NETWORK_GLOBAL_OPTION,
+    },
+  ],
+]);
+
+export async function parseHhuGlobalOptions(
+  cliArguments: string[],
+  usedCliArguments: boolean[],
+): Promise<{
+  help: boolean;
+  showStackTraces: boolean;
+  version: boolean;
+  network: string | undefined;
+}> {
+  const hhuGlobalOptions = await parseGlobalOptions(
+    HHU_GLOBAL_OPTIONS_DEFINITIONS,
+    cliArguments,
+    usedCliArguments,
+  );
+
+  return {
+    help: hhuGlobalOptions.help ?? false,
+    showStackTraces: hhuGlobalOptions.showStackTraces ?? isCi(),
+    version: hhuGlobalOptions.version ?? false,
+    network: hhuGlobalOptions.network,
+  };
+}
+
+export async function printHhuVersionMessage(
+  print: (message: string) => void = console.log,
+): Promise<void> {
+  print(await getHardhatVersion());
+}
+
+function makeStrictProxy<T extends object>(
+  name: string,
+  object: Partial<T>,
+): T {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- inaccessible properties will throw an assertion error
+  return new Proxy(object as T, {
+    get(target, property) {
+      assertHardhatInvariant(
+        Object.hasOwn(object, property),
+        `Unexpected access of property "${String(property)}" in ${name}.`,
+      );
+
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- we know this is safe because of the assertion above
+      return target[property as keyof T];
+    },
+  });
+}
+
+function taskDefinitionsToTasksMap(tasks: TaskDefinition[]): Map<string, Task> {
+  // To be able to parse the hhu arguments, we need to create a tasks map from
+  // the task definitions. The easiest way to do that is by using
+  // `TaskManagerImplementation`, but this needs an HRE and we don't want to
+  // create one just for this. So we use a fake HRE that has the minimum
+  // properties needed.
+  //
+  // The exception is `network.create`: utils that need a network get the real
+  // implementation, which lazily loads Hardhat (and thus creates the project's
+  // HRE) only when such a util actually runs.
+  //
+  // One downside of this approach is that we _won't_ get a compilation error
+  // if `TaskManagerImplementation` tries to access a property that doesn't exist in the
+  // fake HRE, but tests should catch that.
+  //
+  // The `satisfies FakeHhuHardhatRuntimeEnvironment` keeps this fake HRE in sync
+  // with the surface utils actions rely on.
+  const fakeHre = makeStrictProxy<HardhatRuntimeEnvironment>(
+    "hhu's proxied HRE",
+    {
+      config: makeStrictProxy<HardhatRuntimeEnvironment["config"]>(
+        "hhu's proxied config",
+        {
+          tasks,
+          plugins: [],
+        },
+      ),
+      network: makeStrictProxy<HardhatRuntimeEnvironment["network"]>(
+        "hhu's proxied network",
+        {
+          create: async (networkOrParams) => {
+            const hre = await import("../../index.js");
+            return await hre.network.create(networkOrParams);
+          },
+        },
+      ),
+    } satisfies FakeHhuHardhatRuntimeEnvironment,
+  );
+
+  const taskManager = new TaskManagerImplementation(
+    fakeHre,
+    new Map(HHU_GLOBAL_OPTIONS_DEFINITIONS),
+  );
+
+  return taskManager.rootTasks;
+}