hardhat 3.3.0 → 3.4.1

package/src/internal/cli/telemetry/error-reporter/global-error-handlers.ts

@@ -0,0 +1,64 @@
+import { isObject } from "@nomicfoundation/hardhat-utils/lang";
+import debug from "debug";
+
+import { sendErrorTelemetry } from "./reporter.js";
+
+const log = debug("hardhat:core:telemetry:global-error-handlers");
+
+function createUnhandledErrorListener(isPromiseRejection: boolean) {
+  const description = isPromiseRejection
+    ? "Unhandled promise rejection"
+    : "Uncaught exception";
+
+  const mechanismType = isPromiseRejection
+    ? "onunhandledrejection"
+    : "onuncaughtexception";
+
+  async function listener(error: Error | unknown) {
+    log(description, error);
+
+    const telemetryError =
+      error instanceof Error
+        ? error
+        : new Error(
+            isObject(error) &&
+            "message" in error &&
+            typeof error.message === "string"
+              ? error.message
+              : "Unknown error",
+            { cause: error },
+          );
+
+    try {
+      await sendErrorTelemetry(telemetryError, {
+        unhandled: true,
+        mechanismType,
+      });
+    } catch (telemetryErrorReportingError) {
+      log(
+        "Failed to send telemetry for unhandled error",
+        telemetryErrorReportingError,
+      );
+    }
+
+    console.error();
+    console.error(`${description}:`);
+    console.error();
+    console.error(error);
+
+    process.exit(1);
+  }
+
+  return listener;
+}
+
+/**
+ * Sets up global error handlers that report unhandled errors and promise
+ * rejections if authorized by the user.
+ */
+export function setupGlobalUnhandledErrorHandlers(): void {
+  log("Setting up global unhandled error handlers");
+
+  process.on("uncaughtException", createUnhandledErrorListener(false));
+  process.on("unhandledRejection", createUnhandledErrorListener(true));
+}

package/src/internal/cli/telemetry/error-reporter/reporter.ts

@@ -0,0 +1,49 @@
+import type * as SentryReporterT from "../sentry/reporter.js";
+
+// Sentry's reporter loads a large number of modules, so we only load it if
+// needed.
+let sentryReporterModule: typeof SentryReporterT | undefined;
+
+// We cache the `setCliHardhatConfigPath` to avoid loading the reporter just
+// for this setting. We load it and set the config path if needed.
+let cliHardhatConfigPath: string | undefined;
+
+/**
+ * Reports an error if telemetry is authorized by the user.
+ *
+ * While this function is async, it's expected to always complete quickly,
+ * delegating the actual reporting to a subprocess.
+ *
+ * @param error - The error to report.
+ * @param hint - Optional metadata describing how the error was captured, used
+ *   to tag the event in Sentry so unhandled crashes can be distinguished from
+ *   errors caught and reported by the CLI.
+ * @param hint.unhandled - Whether the error reached a global handler without
+ *   being caught (e.g. an uncaught exception or unhandled promise rejection).
+ *   Defaults to `false` (i.e. the error was handled).
+ * @param hint.mechanismType - The Sentry mechanism type, used as a tag on the
+ *   event. Common values are `"onuncaughtexception"`, `"onunhandledrejection"`,
+ *   `"instrument"`, and `"generic"`. Defaults to `"generic"`.
+ */
+export async function sendErrorTelemetry(
+  error: Error,
+  hint?: { unhandled?: boolean; mechanismType?: string },
+): Promise<void> {
+  if (sentryReporterModule === undefined) {
+    sentryReporterModule = await import("../sentry/reporter.js");
+  }
+
+  if (cliHardhatConfigPath !== undefined) {
+    sentryReporterModule.setCliHardhatConfigPath(cliHardhatConfigPath);
+  }
+
+  await sentryReporterModule.sendErrorTelemetry(error, hint);
+}
+
+/**
+ * Sets the config path used in the Hardhat CLI. This is used for better
+ * anonymization of errors.
+ */
+export function setCliHardhatConfigPath(configPath: string): void {
+  cliHardhatConfigPath = configPath;
+}

package/src/internal/cli/telemetry/sentry/anonymizer.ts

@@ -359,7 +359,7 @@ export class Anonymizer {
   async #anonymizeFrames(frames: StackFrame[]): Promise<StackFrame[]> {
     const anonymizedFrames = await Promise.all(
       frames.map(async (frame) => {
-        return this.#anonymizeFrame(frame);
+        return await this.#anonymizeFrame(frame);
       }),
     );
     return anonymizedFrames;

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

@@ -1,10 +1,6 @@
 /* This file is inspired by https://github.com/getsentry/sentry-javascript/blob/9.4.0/packages/node/src/sdk/index.ts */
 
-import type {
-  Client,
-  ServerRuntimeClientOptions,
-  Transport,
-} from "@sentry/core";
+import type { ServerRuntimeClientOptions, Transport } from "@sentry/core";
 
 import os from "node:os";
 import path from "node:path";
@@ -18,15 +14,12 @@ import {
   ServerRuntimeClient,
   stackParserFromStackParserOptions,
 } from "@sentry/core";
-import debug from "debug";
 
 import { GENERIC_SERVER_NAME } from "./constants.js";
 import { nodeContextIntegration } from "./vendor/integrations/context.js";
 import { contextLinesIntegration } from "./vendor/integrations/contextlines.js";
 import { createGetModuleFromFilename } from "./vendor/utils/module.js";
 
-const log = debug("hardhat:core:sentry:init");
-
 interface GlobalCustomSentryReporterOptions {
   /**
    * Sentry's DSN
@@ -49,12 +42,6 @@ interface GlobalCustomSentryReporterOptions {
    * See the transport module for the different options.
    */
   transport: Transport;
-
-  /**
-   * If `true`, the global unhandled rejection and uncaught exception handlers
-   * will be installed.
-   */
-  installGlobalHandlers?: boolean;
 }
 
 /**
@@ -72,12 +59,9 @@ interface GlobalCustomSentryReporterOptions {
  * The reason that this uses the global instance of sentry (by calling
  * initAndBind), is that using the client directly doesn't work with the linked
  * errors integration.
- *
- * Calling `init` also has an option to set global unhandled rejection and
- * uncaught exception handlers.
  */
 export function init(options: GlobalCustomSentryReporterOptions): void {
-  const client = initAndBind<ServerRuntimeClient, ServerRuntimeClientOptions>(
+  initAndBind<ServerRuntimeClient, ServerRuntimeClientOptions>(
     ServerRuntimeClient,
     {
       dsn: options.dsn,
@@ -113,48 +97,4 @@ export function init(options: GlobalCustomSentryReporterOptions): void {
       ),
     },
   );
-
-  setupGlobalUnhandledErrorHandlers(client);
-}
-
-function createUnhandledErrorListener(
-  client: Client,
-  isPromiseRejection: boolean,
-) {
-  const description = isPromiseRejection
-    ? "Unhandled promise rejection"
-    : "Uncaught exception";
-
-  async function listener(error: Error | unknown) {
-    log(description, error);
-
-    client.captureException(error, {
-      captureContext: {
-        level: "fatal",
-      },
-      mechanism: {
-        handled: false,
-        type: "onuncaughtexception",
-      },
-    });
-
-    await client.flush(100);
-    await client.close(100);
-
-    console.error();
-    console.error(`${description}:`);
-    console.error();
-    console.error(error);
-
-    process.exit(1);
-  }
-
-  return listener;
-}
-
-function setupGlobalUnhandledErrorHandlers(client: Client) {
-  log("Setting up global unhandled error handlers");
-
-  process.on("uncaughtException", createUnhandledErrorListener(client, false));
-  process.on("unhandledRejection", createUnhandledErrorListener(client, true));
 }

package/src/internal/cli/telemetry/sentry/reporter.ts

@@ -19,15 +19,16 @@ const log = debug("hardhat:cli:telemetry:sentry:reporter");
 export const SENTRY_DSN =
   "https://572b03708e298427cc72fc26dac1e8b2@o385026.ingest.us.sentry.io/4508780138856448"; // PROD
 
-// TODO: This could be done in a more elegant way, but for now, we just
-// initialize the entire reporter so that it sets the global error handlers.
-export async function setupErrorTelemetryIfEnabled(): Promise<void> {
-  await Reporter.getInstance(true);
-}
-
-export async function sendErrorTelemetry(error: Error): Promise<boolean> {
+/**
+ * @deprecated Use packages/hardhat/src/internal/cli/telemetry/error-reporter/reporter.ts
+ *   instead.
+ */
+export async function sendErrorTelemetry(
+  error: Error,
+  hint?: { unhandled?: boolean; mechanismType?: string },
+): Promise<boolean> {
   const instance = await Reporter.getInstance();
-  return instance.reportErrorViaSubprocess(error);
+  return await instance.reportErrorViaSubprocess(error, hint);
 }
 
 export function setCliHardhatConfigPath(configPath: string): void {
@@ -57,9 +58,7 @@ class Reporter {
     this.#hardhatConfigPath = configPath;
   }
 
-  public static async getInstance(
-    shouldSetupErrorHandlers = false,
-  ): Promise<Reporter> {
+  public static async getInstance(): Promise<Reporter> {
     if (this.#instance !== undefined) {
       return this.#instance;
     }
@@ -94,7 +93,6 @@ class Reporter {
       ),
       release,
       environment,
-      installGlobalHandlers: shouldSetupErrorHandlers,
     });
 
     setExtra("nodeVersion", process.version);
@@ -108,17 +106,31 @@ class Reporter {
     this.#instance = undefined;
   }
 
-  public async reportErrorViaSubprocess(error: Error): Promise<boolean> {
+  public async reportErrorViaSubprocess(
+    error: Error,
+    hint?: { unhandled?: boolean; mechanismType?: string },
+  ): Promise<boolean> {
     if (!(await this.#shouldBeReported(error))) {
       log("Error not send: this type of error should not be reported");
       return false;
     }
 
-    const { captureException } = await import("@sentry/core");
+    const { captureException, flush } = await import("@sentry/core");
 
     log("Capturing exception");
 
-    captureException(error);
+    captureException(
+      error,
+      hint !== undefined
+        ? {
+            mechanism: {
+              type: hint.mechanismType ?? "generic",
+              handled: hint.unhandled !== true,
+            },
+          }
+        : undefined,
+    );
+    await flush();
 
     return true;
   }

package/src/internal/cli/telemetry/sentry/transport.ts

@@ -139,7 +139,7 @@ export async function sendEnvelopeToSentryBackend(
   dsn: string,
   envelope: Envelope,
 ): Promise<TransportMakeRequestResponse> {
-  return sendSerializedEnvelopeToSentryBackend(
+  return await sendSerializedEnvelopeToSentryBackend(
     dsn,
     serializeEnvelope(envelope),
   );

package/src/internal/cli/telemetry/telemetry-permissions.ts

@@ -35,7 +35,7 @@ export async function isTelemetryAllowed(
     return process.env.HARDHAT_TEST_TELEMETRY_ENABLED === "true" ? true : false;
   }
 
-  return isTelemetryEnabled(telemetryConfigFilePath);
+  return await isTelemetryEnabled(telemetryConfigFilePath);
 }
 
 /**

package/src/internal/config-loading.ts

@@ -34,15 +34,15 @@ export async function resolveHardhatConfigPath(
   userProvidedPath?: string,
 ): Promise<string> {
   if (userProvidedPath !== undefined) {
-    return normalizeConfigPath(userProvidedPath);
+    return await normalizeConfigPath(userProvidedPath);
   }
 
   if (process.env.HARDHAT_CONFIG !== undefined) {
     log("Using config file path from the HARDHAT_CONFIG env var");
-    return normalizeConfigPath(process.env.HARDHAT_CONFIG);
+    return await normalizeConfigPath(process.env.HARDHAT_CONFIG);
   }
 
-  return findClosestHardhatConfig();
+  return await findClosestHardhatConfig();
 }
 
 /**

package/src/internal/core/configuration-variables.ts

@@ -118,24 +118,25 @@ export class LazyResolvedConfigurationVariable extends BaseResolvedConfiguration
     const mutex = LazyResolvedConfigurationVariable.#mutexes.get(this.#hooks);
     assertHardhatInvariant(mutex !== undefined, "Mutex must be defined");
 
-    return mutex.exclusiveRun(async () =>
-      this.#hooks.runHandlerChain(
-        "configurationVariables",
-        "fetchValue",
-        [this.#variable],
-        async (_context, v) => {
-          const value = process.env[v.name];
-
-          if (typeof value !== "string") {
-            throw new HardhatError(
-              HardhatError.ERRORS.CORE.GENERAL.ENV_VAR_NOT_FOUND,
-              { name: v.name },
-            );
-          }
-
-          return value;
-        },
-      ),
+    return await mutex.exclusiveRun(
+      async () =>
+        await this.#hooks.runHandlerChain(
+          "configurationVariables",
+          "fetchValue",
+          [this.#variable],
+          async (_context, v) => {
+            const value = process.env[v.name];
+
+            if (typeof value !== "string") {
+              throw new HardhatError(
+                HardhatError.ERRORS.CORE.GENERAL.ENV_VAR_NOT_FOUND,
+                { name: v.name },
+              );
+            }
+
+            return value;
+          },
+        ),
     );
   }
 }

package/src/internal/core/hook-manager.ts

@@ -124,7 +124,7 @@ export class HookManagerImplementation implements HookManager {
       return result;
     };
 
-    return next(...handlerParams);
+    return await next(...handlerParams);
   }
 
   public async runSequentialHandlers<
@@ -192,7 +192,7 @@ export class HookManagerImplementation implements HookManager {
       handlerParams = params;
     }
 
-    return Promise.all(
+    return await Promise.all(
       handlers.map((handler) => (handler as any)(...handlerParams)),
     );
   }
@@ -277,7 +277,7 @@ export class HookManagerImplementation implements HookManager {
     const categories: Array<
       Partial<HardhatHooks[HookCategoryNameT]> | undefined
     > = await this.#mutex.exclusiveRun(async () => {
-      return Promise.all(
+      return await Promise.all(
         this.#pluginsInReverseOrder.map(async (plugin) => {
           const existingCategory = this.#staticHookHandlerCategories
             .get(plugin.id)

package/src/internal/core/hre.ts

@@ -193,7 +193,9 @@ export class HardhatRuntimeEnvironmentImplementation
 export async function resolveProjectRoot(
   absolutePathWithinProject: string | undefined,
 ): Promise<string> {
-  return findClosestPackageRoot(absolutePathWithinProject ?? process.cwd());
+  return await findClosestPackageRoot(
+    absolutePathWithinProject ?? process.cwd(),
+  );
 }
 
 /**
@@ -292,7 +294,7 @@ async function runUserConfigExtensions(
   hooks: HookManager,
   config: HardhatUserConfig,
 ): Promise<HardhatUserConfig> {
-  return hooks.runHandlerChain(
+  return await hooks.runHandlerChain(
     "config",
     "extendUserConfig",
     [config],
@@ -320,7 +322,7 @@ async function resolveUserConfig(
     paths: resolvePaths(projectRoot, configPath, config.paths),
   } as HardhatConfig;
 
-  return hooks.runHandlerChain(
+  return await hooks.runHandlerChain(
     "config",
     "resolveUserConfig",
     [config, (variable) => resolveConfigurationVariable(hooks, variable)],

package/src/internal/core/plugins/resolve-plugin-list.ts

@@ -12,7 +12,7 @@ export async function resolvePluginList(
   projectRoot: string,
   userConfigPluginList: HardhatPlugin[] = [],
 ): Promise<HardhatPlugin[]> {
-  return reverseTopologicalSort(projectRoot, userConfigPluginList);
+  return await reverseTopologicalSort(projectRoot, userConfigPluginList);
 }
 
 /**

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

@@ -175,22 +175,22 @@ export class ResolvedTask implements Task {
       if (currentIndex === 0) {
         /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions --
         We know that the first action in the array is a NewTaskActionFunction */
-        return (actionFn as NewTaskActionFunction)(
+        return await (actionFn as NewTaskActionFunction)(
           nextTaskArguments,
           this.#hre,
         );
       }
 
-      return actionFn(
+      return await actionFn(
         nextTaskArguments,
         this.#hre,
         async (newTaskArguments: TaskArguments) => {
-          return next(newTaskArguments, currentIndex - 1);
+          return await next(newTaskArguments, currentIndex - 1);
         },
       );
     };
 
-    return next(validatedTaskArguments);
+    return await next(validatedTaskArguments);
   }
 
   /**

package/src/internal/core/user-interruptions.ts

@@ -21,8 +21,8 @@ export class UserInterruptionManagerImplementation
     interruptor: string,
     message: string,
   ): Promise<void> {
-    return this.#mutex.exclusiveRun(async () => {
-      return this.#hooks.runHandlerChain(
+    return await this.#mutex.exclusiveRun(async () => {
+      return await this.#hooks.runHandlerChain(
         "userInterruptions",
         "displayMessage",
         [interruptor, message],
@@ -35,8 +35,8 @@ export class UserInterruptionManagerImplementation
     interruptor: string,
     inputDescription: string,
   ): Promise<string> {
-    return this.#mutex.exclusiveRun(async () => {
-      return this.#hooks.runHandlerChain(
+    return await this.#mutex.exclusiveRun(async () => {
+      return await this.#hooks.runHandlerChain(
         "userInterruptions",
         "requestInput",
         [interruptor, inputDescription],
@@ -49,8 +49,8 @@ export class UserInterruptionManagerImplementation
     interruptor: string,
     inputDescription: string,
   ): Promise<string> {
-    return this.#mutex.exclusiveRun(async () => {
-      return this.#hooks.runHandlerChain(
+    return await this.#mutex.exclusiveRun(async () => {
+      return await this.#hooks.runHandlerChain(
         "userInterruptions",
         "requestSecretInput",
         [interruptor, inputDescription],
@@ -62,7 +62,7 @@ export class UserInterruptionManagerImplementation
   public async uninterrupted<ReturnT>(
     f: () => ReturnT,
   ): Promise<Awaited<ReturnT>> {
-    return this.#mutex.exclusiveRun(f);
+    return await this.#mutex.exclusiveRun(f);
   }
 }
 
@@ -84,7 +84,7 @@ async function defaultRequestInput(
     output: process.stdout,
   });
 
-  return new Promise<string>((resolve) => {
+  return await new Promise<string>((resolve) => {
     rl.question(
       chalk.blue(`[${interruptor}]`) + ` ${inputDescription}: `,
       (answer) => {
@@ -138,7 +138,7 @@ async function defaultRequestSecretInput(
     }
   };
 
-  return new Promise<string>((resolve) => {
+  return await new Promise<string>((resolve) => {
     rl.question(
       chalk.blue(`[${interruptor}]`) + ` ${inputDescription}: `,
       (answer) => {

package/src/internal/hre-initialization.ts

@@ -65,7 +65,7 @@ export async function createHardhatRuntimeEnvironment(
     unsafeOptions.globalOptionDefinitions = globalOptionDefinitions;
   }
 
-  return HardhatRuntimeEnvironmentImplementation.create(
+  return await HardhatRuntimeEnvironmentImplementation.create(
     config,
     userProvidedGlobalOptions,
     resolvedProjectRoot,

package/src/types/artifacts.ts

@@ -89,11 +89,11 @@ export interface ArtifactManager {
   /**
    * Returns true if an artifact exists.
    *
-   * This function doesn't throw if the name is not unique.
+   * This function doesn't throw if the name is not unique, this means that
+   * this method may return `true`, and a successive call to `readArtifact` can
+   * throw because of a duplicated name.
    *
    * @param contractNameOrFullyQualifiedName Contract or fully qualified name.
-   * @throws Throws an error if a non-unique contract name is used,
-   *   indicating which fully qualified names can be used instead.
    */
   artifactExists(contractNameOrFullyQualifiedName: string): Promise<boolean>;
 
@@ -120,7 +120,8 @@ export interface ArtifactManager {
    * If it does return an id, it's not guaranteed that the build info is
    * present.
    *
-   * @param contractNameOrFullyQualifiedName Contract or fully qualified name, whose artifact must exist.
+   * @param contractNameOrFullyQualifiedName Contract or fully qualified name,
+   *  whose artifact must exist.
    * @throws Throws an error if a non-unique contract name is used,
    *   indicating which fully qualified names can be used instead.
    * @throws Throws an error if the artifact doesn't exist.

package/src/types/network.ts

@@ -48,11 +48,59 @@ export interface NetworkConnectionParams<
   override?: NetworkConfigOverride;
 }
 
+export interface CachedNetworkConnectionParams<
+  ChainTypeT extends ChainType | string = DefaultChainType,
+> extends NetworkConnectionParams<ChainTypeT> {
+  override?: never;
+}
+
 export interface NetworkManager {
+  /**
+   * Creates a new network connection based on the provided parameters.
+   *
+   * @param networkOrParams The network name or connection parameters. When
+   * omitted, the default network is used.
+   *
+   * @returns A new {@link NetworkConnection} for the specified network.
+   */
+  create<ChainTypeT extends ChainType | string = DefaultChainType>(
+    networkOrParams?: NetworkConnectionParams<ChainTypeT> | string,
+  ): Promise<NetworkConnection<ChainTypeT>>;
+
+  /**
+   * Creates a new network connection based on the provided parameters.
+   *
+   * @deprecated Use {@link NetworkManager.create} or
+   * {@link NetworkManager.getOrCreate} instead.
+   *
+   * - {@link NetworkManager.create} always creates a new network instance.
+   * - {@link NetworkManager.getOrCreate} returns an existing instance if one exists.
+   *
+   * `connect` will be removed in a future version of Hardhat.
+   *
+   * @param networkOrParams The network name or connection parameters. When
+   * omitted, the default network is used.
+   *
+   * @returns A new {@link NetworkConnection} for the specified network.
+   */
   connect<ChainTypeT extends ChainType | string = DefaultChainType>(
     networkOrParams?: NetworkConnectionParams<ChainTypeT> | string,
   ): Promise<NetworkConnection<ChainTypeT>>;
 
+  /**
+   * Returns an existing network connection if one was previously created
+   * with the same network name and chain type. Creates a new one otherwise.
+   *
+   * @param networkOrParams The network name or connection parameters. When
+   * omitted, the default network is used. Overrides are not supported.
+   *
+   * @returns A {@link NetworkConnection} for the specified network, cached
+   * by network name and chain type.
+   */
+  getOrCreate<ChainTypeT extends ChainType | string = DefaultChainType>(
+    networkOrParams?: CachedNetworkConnectionParams<ChainTypeT> | string,
+  ): Promise<NetworkConnection<ChainTypeT>>;
+
   /**
    * Spawns an Ethereum JSON-RPC server listening on HTTP and Websocket.
    *