hardhat 3.4.0 → 3.4.2

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

@@ -23,35 +23,94 @@ export class HookManagerImplementation implements HookManager {
 
   readonly #projectRoot: string;
 
-  readonly #pluginsInReverseOrder: HardhatPlugin[];
-
   /**
+   * The context passed to hook handlers, except to the `config` ones, to break
+   * a circular dependency between the config and the hook handler.
+   *
    * Initially `undefined` to be able to run the config hooks during
    * initialization.
    */
   #context: HookContext | undefined;
 
   /**
-   * The initialized handler categories for each plugin.
+   * Plugins that provide hook handlers for each category, in reverse order.
+   *
+   * Precomputed from the plugin list at construction.
+   */
+  readonly #pluginsByHookCategory: Map<keyof HardhatHooks, HardhatPlugin[]> =
+    new Map();
+
+  /**
+   * Cached resolved category objects per hook category in reverse plugin
+   * order.
+   *
+   * Only written by #getStaticHookHandlerCategories, which uses a mutex to
+   * ensure that every Hook Category Factory is run once per HookManager
+   * instance.
    */
-  readonly #staticHookHandlerCategories: Map<
-    string,
-    Map<keyof HardhatHooks, Partial<HardhatHooks[keyof HardhatHooks]>>
+  readonly #resolvedStaticCategories: Map<
+    keyof HardhatHooks,
+    Array<Partial<HardhatHooks[keyof HardhatHooks]>>
   > = new Map();
 
   /**
    * A map of the dynamically registered handler categories.
    *
    * Each array is a list of categories, in reverse order of registration.
+   *
+   * Written by registerHandlers and unregisterHandlers.
    */
   readonly #dynamicHookHandlerCategories: Map<
     keyof HardhatHooks,
     Array<Partial<HardhatHooks[keyof HardhatHooks]>>
   > = new Map();
 
+  /**
+   * Cached combined (dynamic + static) handlers per (category, hook name) in
+   * chained running order.
+   *
+   * Only written by #getHandlersInChainedRunningOrder, and invalidated
+   * per-category on dynamic handlers register/unregister.
+   */
+  readonly #chainedHandlers: Map<keyof HardhatHooks, Map<string, any[]>> =
+    new Map();
+
+  /**
+   * Cached combined handlers per (category, hook name) in sequential running
+   * order (reverse of chained).
+   *
+   * Only written by #getHandlersInSequentialRunningOrder, and invalidated
+   * per-category on dynamic handlers register/unregister.
+   */
+  readonly #sequentialHandlers: Map<keyof HardhatHooks, Map<string, any[]>> =
+    new Map();
+
   constructor(projectRoot: string, plugins: HardhatPlugin[]) {
     this.#projectRoot = projectRoot;
-    this.#pluginsInReverseOrder = plugins.toReversed();
+
+    for (const plugin of plugins.toReversed()) {
+      if (plugin.hookHandlers === undefined) {
+        continue;
+      }
+
+      for (const hookCategoryName of Object.keys(plugin.hookHandlers) as Array<
+        keyof HardhatHooks
+      >) {
+        if (plugin.hookHandlers[hookCategoryName] === undefined) {
+          continue;
+        }
+
+        let pluginsForCategory =
+          this.#pluginsByHookCategory.get(hookCategoryName);
+
+        if (pluginsForCategory === undefined) {
+          pluginsForCategory = [];
+          this.#pluginsByHookCategory.set(hookCategoryName, pluginsForCategory);
+        }
+
+        pluginsForCategory.push(plugin);
+      }
+    }
   }
 
   public setContext(context: HookContext): void {
@@ -69,6 +128,8 @@ export class HookManagerImplementation implements HookManager {
     }
 
     categories.unshift(hookHandlerCategory);
+
+    this.#invalidateResolvedHandlersCache(hookCategoryName);
   }
 
   public unregisterHandlers<HookCategoryNameT extends keyof HardhatHooks>(
@@ -84,6 +145,8 @@ export class HookManagerImplementation implements HookManager {
       hookCategoryName,
       categories.filter((c) => c !== hookHandlerCategory),
     );
+
+    this.#invalidateResolvedHandlersCache(hookCategoryName);
   }
 
   public async runHandlerChain<
@@ -96,10 +159,23 @@ export class HookManagerImplementation implements HookManager {
     params: InitialChainedHookParams<HookCategoryNameT, HookT>,
     defaultImplementation: LastParameter<HookT>,
   ): Promise<Awaited<Return<HardhatHooks[HookCategoryNameT][HookNameT]>>> {
-    const handlers = await this.#getHandlersInChainedRunningOrder(
-      hookCategoryName,
-      hookName,
-    );
+    // Synchronous fast path for already cached handlers. This duplicates
+    // the check inside #getHandlersInChainedRunningOrder on purpose:
+    // calling that async method introduces a microtask tick even on a
+    // cache hit, whereas a direct Map lookup stays on the current tick.
+    // That tick matters here because runHandlerChain is on every hook's
+    // hot path, and this path pairs with the empty-handlers shortcut
+    // below to dispatch straight to defaultImplementation with no awaits.
+    const cachedHandlers = this.#chainedHandlers
+      .get(hookCategoryName)
+      ?.get(hookName as string);
+
+    const handlers =
+      cachedHandlers ??
+      (await this.#getHandlersInChainedRunningOrder(
+        hookCategoryName,
+        hookName,
+      ));
 
     let handlerParams: Parameters<typeof defaultImplementation>;
     if (hookCategoryName !== "config") {
@@ -113,6 +189,13 @@ export class HookManagerImplementation implements HookManager {
       handlerParams = params as any;
     }
 
+    // Fast path for the common case of no registered handlers: skip building
+    // handlerParams and the `next` closure, and call the default implementation
+    // directly.
+    if (handlers.length === 0) {
+      return (await defaultImplementation(...handlerParams)) as any;
+    }
+
     const numberOfHandlers = handlers.length;
     let index = 0;
     const next = async (...nextParams: typeof handlerParams) => {
@@ -124,7 +207,7 @@ export class HookManagerImplementation implements HookManager {
       return result;
     };
 
-    return next(...handlerParams);
+    return await next(...handlerParams);
   }
 
   public async runSequentialHandlers<
@@ -192,7 +275,7 @@ export class HookManagerImplementation implements HookManager {
       handlerParams = params;
     }
 
-    return Promise.all(
+    return await Promise.all(
       handlers.map((handler) => (handler as any)(...handlerParams)),
     );
   }
@@ -220,14 +303,48 @@ export class HookManagerImplementation implements HookManager {
     hookCategoryName: HookCategoryNameT,
     hookName: HookNameT,
   ): Promise<Array<HardhatHooks[HookCategoryNameT][HookNameT]>> {
-    const pluginHooks = await this.#getPluginHooks(hookCategoryName, hookName);
+    let handlersByName = this.#chainedHandlers.get(hookCategoryName);
+    if (handlersByName === undefined) {
+      handlersByName = new Map();
+      this.#chainedHandlers.set(hookCategoryName, handlersByName);
+    }
 
-    const dynamicHooks = await this.#getDynamicHooks(
+    const cached = handlersByName.get(hookName as string);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const staticCategories =
+      await this.#getStaticHookHandlerCategories(hookCategoryName);
+
+    // IMPORTANT NOTE: Accessing the dynamic hook handlers MUST happen
+    // after awaiting the static ones. See
+    // #invalidateResolvedHandlersCache for more info.
+    const dynamicCategories = this.#dynamicHookHandlerCategories.get(
       hookCategoryName,
-      hookName,
-    );
+    ) as Array<Partial<HardhatHooks[HookCategoryNameT]>> | undefined;
+
+    const handlers: Array<HardhatHooks[HookCategoryNameT][HookNameT]> = [];
 
-    return [...dynamicHooks, ...pluginHooks];
+    if (dynamicCategories !== undefined) {
+      for (const category of dynamicCategories) {
+        const handler = category[hookName];
+        if (handler !== undefined) {
+          handlers.push(handler as HardhatHooks[HookCategoryNameT][HookNameT]);
+        }
+      }
+    }
+
+    for (const category of staticCategories) {
+      const handler = category[hookName];
+      if (handler !== undefined) {
+        handlers.push(handler as HardhatHooks[HookCategoryNameT][HookNameT]);
+      }
+    }
+
+    handlersByName.set(hookName as string, handlers);
+
+    return handlers;
   }
 
   async #getHandlersInSequentialRunningOrder<
@@ -237,111 +354,158 @@ export class HookManagerImplementation implements HookManager {
     hookCategoryName: HookCategoryNameT,
     hookName: HookNameT,
   ): Promise<Array<HardhatHooks[HookCategoryNameT][HookNameT]>> {
-    const handlersInChainedOrder = await this.#getHandlersInChainedRunningOrder(
+    let handlersByName = this.#sequentialHandlers.get(hookCategoryName);
+    if (handlersByName === undefined) {
+      handlersByName = new Map();
+      this.#sequentialHandlers.set(hookCategoryName, handlersByName);
+    }
+
+    const cached = handlersByName.get(hookName as string);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const chained = await this.#getHandlersInChainedRunningOrder(
       hookCategoryName,
       hookName,
     );
 
-    return handlersInChainedOrder.reverse();
+    const sequential = chained.toReversed();
+
+    handlersByName.set(hookName as string, sequential);
+
+    return sequential;
   }
 
-  async #getDynamicHooks<
+  async #getStaticHookHandlerCategories<
     HookCategoryNameT extends keyof HardhatHooks,
-    HookNameT extends keyof HardhatHooks[HookCategoryNameT],
   >(
     hookCategoryName: HookCategoryNameT,
-    hookName: HookNameT,
-  ): Promise<Array<HardhatHooks[HookCategoryNameT][HookNameT]>> {
-    const categories = this.#dynamicHookHandlerCategories.get(
-      hookCategoryName,
-    ) as Array<Partial<HardhatHooks[HookCategoryNameT]>> | undefined;
+  ): Promise<Array<Partial<HardhatHooks[HookCategoryNameT]>>> {
+    const cached = this.#resolvedStaticCategories.get(hookCategoryName) as
+      | Array<Partial<HardhatHooks[HookCategoryNameT]>>
+      | undefined;
 
-    if (categories === undefined) {
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const plugins = this.#pluginsByHookCategory.get(hookCategoryName);
+
+    // We don't need to get the mutex to resolve this case, as it will always
+    // be an empty array, and won't execute any factory.
+    if (plugins === undefined) {
+      this.#resolvedStaticCategories.set(hookCategoryName, []);
       return [];
     }
 
-    return categories.flatMap((hookCategory) => {
-      return (hookCategory[hookName] ?? []) as Array<
-        HardhatHooks[HookCategoryNameT][HookNameT]
-      >;
+    return await this.#mutex.exclusiveRun(async () => {
+      // Re-check under the mutex in case another caller just populated it.
+      const recheck = this.#resolvedStaticCategories.get(hookCategoryName) as
+        | Array<Partial<HardhatHooks[HookCategoryNameT]>>
+        | undefined;
+
+      if (recheck !== undefined) {
+        return recheck;
+      }
+
+      const resolved = await Promise.all(
+        plugins.map(
+          async (plugin) =>
+            await this.#getPluginStaticHookCategory(plugin, hookCategoryName),
+        ),
+      );
+
+      this.#resolvedStaticCategories.set(hookCategoryName, resolved);
+
+      return resolved;
     });
   }
 
-  async #getPluginHooks<
+  /**
+   * Returns the hook category object for a plugin that has the hook category
+   * defined.
+   *
+   * @param plugin A plugin that MUST have the given hook category defined.
+   * @param hookCategoryName The name of the hook category.
+   * @returns The hook category object.
+   */
+  async #getPluginStaticHookCategory<
     HookCategoryNameT extends keyof HardhatHooks,
-    HookNameT extends keyof HardhatHooks[HookCategoryNameT],
   >(
+    plugin: HardhatPlugin,
     hookCategoryName: HookCategoryNameT,
-    hookName: HookNameT,
-  ): Promise<Array<HardhatHooks[HookCategoryNameT][HookNameT]>> {
-    const categories: Array<
-      Partial<HardhatHooks[HookCategoryNameT]> | undefined
-    > = await this.#mutex.exclusiveRun(async () => {
-      return Promise.all(
-        this.#pluginsInReverseOrder.map(async (plugin) => {
-          const existingCategory = this.#staticHookHandlerCategories
-            .get(plugin.id)
-            ?.get(hookCategoryName);
-
-          if (existingCategory !== undefined) {
-            return existingCategory as Partial<HardhatHooks[HookCategoryNameT]>;
-          }
-
-          const hookHandlerCategoryFactory =
-            plugin.hookHandlers?.[hookCategoryName];
-
-          if (hookHandlerCategoryFactory === undefined) {
-            return;
-          }
-
-          let factory;
-          try {
-            factory = (await hookHandlerCategoryFactory()).default;
-          } catch (error) {
-            ensureError(error);
-
-            await detectPluginNpmDependencyProblems(
-              this.#projectRoot,
-              plugin,
-              error,
-            );
-
-            throw error;
-          }
-
-          assertHardhatInvariant(
-            typeof factory === "function",
-            `Plugin ${plugin.id} doesn't export a hook factory for category ${hookCategoryName}`,
-          );
-
-          const hookCategory = await factory();
-
-          assertHardhatInvariant(
-            hookCategory !== null && typeof hookCategory === "object",
-            `Plugin ${plugin.id} doesn't export a valid factory for category ${hookCategoryName}, it didn't return an object`,
-          );
-
-          if (!this.#staticHookHandlerCategories.has(plugin.id)) {
-            this.#staticHookHandlerCategories.set(plugin.id, new Map());
-          }
-
-          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- Defined right above
-          this.#staticHookHandlerCategories
-            .get(plugin.id)!
-            .set(hookCategoryName, hookCategory);
-
-          return hookCategory;
-        }),
-      );
-    });
+  ): Promise<Partial<HardhatHooks[HookCategoryNameT]>> {
+    const hookHandlerCategoryFactory = plugin.hookHandlers?.[hookCategoryName];
 
-    return categories.flatMap((category) => {
-      const handler = category?.[hookName];
-      if (handler === undefined) {
-        return [];
-      }
+    assertHardhatInvariant(
+      hookHandlerCategoryFactory !== undefined,
+      "#pluginsByHookCategory only contains plugins with this hook category",
+    );
 
-      return handler as HardhatHooks[HookCategoryNameT][HookNameT];
-    });
+    let factory;
+    try {
+      factory = (await hookHandlerCategoryFactory()).default;
+    } catch (error) {
+      ensureError(error);
+
+      await detectPluginNpmDependencyProblems(this.#projectRoot, plugin, error);
+
+      throw error;
+    }
+
+    assertHardhatInvariant(
+      typeof factory === "function",
+      `Plugin ${plugin.id} doesn't export a hook factory for category ${hookCategoryName}`,
+    );
+
+    const hookCategory = await factory();
+
+    assertHardhatInvariant(
+      hookCategory !== null && typeof hookCategory === "object",
+      `Plugin ${plugin.id} doesn't export a valid factory for category ${hookCategoryName}, it didn't return an object`,
+    );
+
+    return hookCategory;
+  }
+
+  #invalidateResolvedHandlersCache<
+    HookCategoryNameT extends keyof HardhatHooks,
+  >(hookCategoryName: HookCategoryNameT) {
+    // Invalidation deletes the outer entry rather than clearing the inner
+    // map. This matters under concurrency.
+    //
+    // A reader of #getHandlersInChainedRunningOrder (or its sequential
+    // sibling) captures a reference to the inner map before awaiting the
+    // static categories, and writes its computed array back after the
+    // await. If invalidation runs during that await, deleting the outer
+    // entry leaves the reader's inner map orphaned: its write lands in a
+    // map no longer reachable from #chainedHandlers/#sequentialHandlers,
+    // so it cannot poison the shared cache. The next reader sees
+    // `undefined`, installs a fresh inner map, and rebuilds from the
+    // current dynamic state.
+    //
+    // Two distinct properties make this safe, guaranteed by two different
+    // things:
+    //
+    //   1. The in-flight reader's own return value is correct. This is
+    //      because #getHandlersInChainedRunningOrder reads
+    //      #dynamicHookHandlerCategories *after* awaiting the static
+    //      categories. Any invalidation that happened during the await is
+    //      visible to the reader when it resumes, so the array it builds
+    //      reflects the current dynamic state.
+    //
+    //   2. The shared cache never holds a stale array. This is guaranteed
+    //      by the orphaning-by-delete described above: a reader that
+    //      started before the invalidation can only write into an
+    //      unreachable inner map.
+    //
+    // Property 1 depends on the ordering of the dynamic handlers read relative
+    // to the await. If that read ever moved *before* the await, a reader
+    // could build a stale array and return it to its caller — the cache
+    // would still be protected by property 2, but the reader's caller
+    // would see the stale result.
+    this.#chainedHandlers.delete(hookCategoryName);
+    this.#sequentialHandlers.delete(hookCategoryName);
   }
 }

package/src/internal/core/hre.ts

@@ -40,9 +40,9 @@ import {
   resolveGlobalOptions,
 } from "./global-options.js";
 import { HookManagerImplementation } from "./hook-manager.js";
+import { LazyUserInterruptionManager } from "./lazy-user-interruptions.js";
 import { resolvePluginList } from "./plugins/resolve-plugin-list.js";
 import { TaskManagerImplementation } from "./tasks/task-manager.js";
-import { UserInterruptionManagerImplementation } from "./user-interruptions.js";
 
 export class HardhatRuntimeEnvironmentImplementation
   implements HardhatRuntimeEnvironment
@@ -134,7 +134,7 @@ export class HardhatRuntimeEnvironmentImplementation
 
     // Set the HookContext in the hook manager so that non-config hooks can
     // use it
-    const interruptions = new UserInterruptionManagerImplementation(hooks);
+    const interruptions = new LazyUserInterruptionManager(hooks);
 
     const hre = new HardhatRuntimeEnvironmentImplementation(
       extendedUserConfig,
@@ -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/lazy-user-interruptions.ts

@@ -0,0 +1,75 @@
+import type { UserInterruptionManagerImplementation as UserInterruptionManagerImplementationT } from "./user-interruptions.js";
+import type { HookManager } from "../../types/hooks.js";
+import type { UserInterruptionManager } from "../../types/user-interruptions.js";
+
+let UserInterruptionManagerImplementation:
+  | typeof UserInterruptionManagerImplementationT
+  | undefined;
+
+export class LazyUserInterruptionManager implements UserInterruptionManager {
+  readonly #hooks: HookManager;
+
+  #userInterruptionManager: UserInterruptionManagerImplementationT | undefined;
+
+  constructor(hooks: HookManager) {
+    this.#hooks = hooks;
+  }
+
+  public async displayMessage(
+    interruptor: string,
+    message: string,
+  ): Promise<void> {
+    const userInterruptionManager = await this.#getUserInterruptionManager();
+    return await userInterruptionManager.displayMessage(interruptor, message);
+  }
+
+  public async requestInput(
+    interruptor: string,
+    inputDescription: string,
+  ): Promise<string> {
+    const userInterruptionManager = await this.#getUserInterruptionManager();
+    return await userInterruptionManager.requestInput(
+      interruptor,
+      inputDescription,
+    );
+  }
+
+  public async requestSecretInput(
+    interruptor: string,
+    inputDescription: string,
+  ): Promise<string> {
+    const userInterruptionManager = await this.#getUserInterruptionManager();
+    return await userInterruptionManager.requestSecretInput(
+      interruptor,
+      inputDescription,
+    );
+  }
+
+  public async uninterrupted<ReturnT>(
+    f: () => ReturnT,
+  ): Promise<Awaited<ReturnT>> {
+    const userInterruptionManager = await this.#getUserInterruptionManager();
+    return await userInterruptionManager.uninterrupted(f);
+  }
+
+  async #getUserInterruptionManager(): Promise<UserInterruptionManagerImplementationT> {
+    // Note: `await import` must run BEFORE the instance cache check so that
+    // concurrent callers share a single microtask-dedupe point — otherwise
+    // each suspended caller re-enters the branch and constructs its own
+    // impl, so callers end up holding different impl instances and state,
+    // which can cause concurrency issues.
+    if (UserInterruptionManagerImplementation === undefined) {
+      ({ UserInterruptionManagerImplementation } = await import(
+        "./user-interruptions.js"
+      ));
+    }
+
+    if (this.#userInterruptionManager === undefined) {
+      this.#userInterruptionManager = new UserInterruptionManagerImplementation(
+        this.#hooks,
+      );
+    }
+
+    return this.#userInterruptionManager;
+  }
+}

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);
   }
 
   /**