Add downloadCompilers parallel hook for extensible compiler downloads

marianfe · marianfe · commit 83b412ef7d0e · 2026-03-23T12:22:43.000+01:00
diff --git a/.changeset/good-eels-buy.md b/.changeset/good-eels-buy.md
@@ -0,0 +1,5 @@
+---
+"hardhat": patch
+---
+
+Add downloadCompilers parallel hook for extensible compiler downloads
diff --git a/v-next/hardhat/src/internal/builtin-plugins/solidity/build-system/build-system.ts b/v-next/hardhat/src/internal/builtin-plugins/solidity/build-system/build-system.ts
@@ -1107,20 +1107,17 @@ export class SolidityBuildSystemImplementation implements SolidityBuildSystem {
       return;
     }
 
-    await downloadSolcCompilers(this.#getAllCompilerVersions(), quiet);
+    const allSolidityCompilerConfigs = this.#getAllSolidityCompilerConfigs();
+    await this.#hooks.runParallelHandlers("solidity", "downloadCompilers", [
+      allSolidityCompilerConfigs,
+      quiet,
+    ]);
     this.#configuredCompilersDownloaded = true;
   }
 
-  #getAllCompilerVersions(): Set<string> {
-    return new Set(
-      Object.values(this.#options.solidityConfig.profiles)
-        .map((profile) => [
-          ...profile.compilers.map((compiler) => compiler.version),
-          ...Object.values(profile.overrides).map(
-            (override) => override.version,
-          ),
-        ])
-        .flat(1),
+  #getAllSolidityCompilerConfigs(): SolidityCompilerConfig[] {
+    return Object.values(this.#options.solidityConfig.profiles).flatMap(
+      (profile) => [...profile.compilers, ...Object.values(profile.overrides)],
     );
   }
 
diff --git a/v-next/hardhat/src/internal/builtin-plugins/solidity/hook-handlers/solidity.ts b/v-next/hardhat/src/internal/builtin-plugins/solidity/hook-handlers/solidity.ts
@@ -0,0 +1,16 @@
+import type { SolidityHooks } from "../../../../types/hooks.js";
+
+import { isSolcConfig } from "../build-system/build-system.js";
+import { downloadSolcCompilers } from "../build-system/compiler/index.js";
+
+export default async (): Promise<Partial<SolidityHooks>> => ({
+  downloadCompilers: async (_context, compilerConfigs, quiet) => {
+    const solcVersions = new Set(
+      compilerConfigs.filter(isSolcConfig).map((c) => c.version),
+    );
+
+    if (solcVersions.size > 0) {
+      await downloadSolcCompilers(solcVersions, quiet);
+    }
+  },
+});
diff --git a/v-next/hardhat/src/internal/builtin-plugins/solidity/index.ts b/v-next/hardhat/src/internal/builtin-plugins/solidity/index.ts
@@ -41,6 +41,7 @@ const hardhatPlugin: HardhatPlugin = {
   hookHandlers: {
     config: () => import("./hook-handlers/config.js"),
     hre: () => import("./hook-handlers/hre.js"),
+    solidity: () => import("./hook-handlers/solidity.js"),
   },
   tasks: [
     {
diff --git a/v-next/hardhat/src/internal/builtin-plugins/solidity/type-extensions.ts b/v-next/hardhat/src/internal/builtin-plugins/solidity/type-extensions.ts
@@ -309,6 +309,21 @@ declare module "../../../types/hooks.js" {
   }
 
   export interface SolidityHooks {
+    /**
+     * Hook triggered to download compilers needed for compilation.
+     * Each handler should download compilers it is responsible for.
+     * Runs in parallel — all registered handlers execute concurrently.
+     *
+     * @param context The hook context.
+     * @param compilerConfigs All compiler configurations from all build profiles.
+     * @param quiet Whether to suppress download progress output.
+     */
+    downloadCompilers: (
+      context: HookContext,
+      compilerConfigs: SolidityCompilerConfig[],
+      quiet: boolean,
+    ) => Promise<void>;
+
     /**
      * Hook triggered during the cleanup process of Solidity compilation artifacts.
      * This hook runs after unused artifacts and build-info files have been removed.
diff --git a/v-next/hardhat/test/internal/builtin-plugins/solidity/build-system/build-system.ts b/v-next/hardhat/test/internal/builtin-plugins/solidity/build-system/build-system.ts
@@ -24,6 +24,7 @@ import {
 } from "@nomicfoundation/hardhat-utils/fs";
 
 import { SolidityBuildSystemImplementation } from "../../../../../src/internal/builtin-plugins/solidity/build-system/build-system.js";
+import createSolidityHookHandlers from "../../../../../src/internal/builtin-plugins/solidity/hook-handlers/solidity.js";
 import { HookManagerImplementation } from "../../../../../src/internal/core/hook-manager.js";
 
 async function emitArtifacts(solidity: SolidityBuildSystem): Promise<void> {
@@ -107,6 +108,7 @@ describe(
       const hooks = new HookManagerImplementation(process.cwd(), []);
       // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- We don't care about hooks in this context
       hooks.setContext({} as HookContext);
+      hooks.registerHandlers("solidity", await createSolidityHookHandlers());
       solidity = new SolidityBuildSystemImplementation(hooks, {
         solidityConfig,
         projectRoot: process.cwd(),
@@ -130,6 +132,7 @@ describe(
       const hooks = new HookManagerImplementation(process.cwd(), []);
       // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- We don't care about hooks in this context
       hooks.setContext({} as HookContext);
+      hooks.registerHandlers("solidity", await createSolidityHookHandlers());
       solidity = new SolidityBuildSystemImplementation(hooks, {
         solidityConfig,
         projectRoot: process.cwd(),
diff --git a/v-next/hardhat/test/internal/builtin-plugins/solidity/hooks.ts b/v-next/hardhat/test/internal/builtin-plugins/solidity/hooks.ts
@@ -245,4 +245,233 @@ describe("solidity - hooks", () => {
       });
     });
   });
+
+  describe("downloadCompilers", () => {
+    useFixtureProject("solidity/simple-project");
+
+    it("should invoke downloadCompilers hook with compiler configs during build", async () => {
+      let capturedConfigs: SolidityCompilerConfig[] = [];
+      let downloadHookCalled = false;
+
+      const downloadPlugin: HardhatPlugin = {
+        id: "test-download-compilers-plugin",
+        hookHandlers: {
+          solidity: async () => ({
+            default: async () => {
+              const handlers: Partial<SolidityHooks> = {
+                downloadCompilers: async (
+                  _context: HookContext,
+                  compilerConfigs: SolidityCompilerConfig[],
+                  _quiet: boolean,
+                ) => {
+                  downloadHookCalled = true;
+                  capturedConfigs = compilerConfigs;
+                },
+              };
+
+              return handlers;
+            },
+          }),
+        },
+      };
+
+      const hre = await createHardhatRuntimeEnvironment({
+        plugins: [downloadPlugin],
+        solidity: "0.8.23",
+      });
+
+      const roots = await hre.solidity.getRootFilePaths();
+      await hre.solidity.build(roots, {
+        force: true,
+        quiet: true,
+      });
+
+      assert.ok(
+        downloadHookCalled,
+        "The downloadCompilers hook should be triggered during build",
+      );
+      assert.ok(
+        capturedConfigs.length > 0,
+        "The downloadCompilers hook should receive compiler configs",
+      );
+      assert.equal(
+        capturedConfigs[0].version,
+        "0.8.23",
+        "The compiler config should have the expected version",
+      );
+    });
+
+    it("should pass all compiler configs from all profiles", async () => {
+      let capturedConfigs: SolidityCompilerConfig[] = [];
+
+      const downloadPlugin: HardhatPlugin = {
+        id: "test-download-all-configs-plugin",
+        hookHandlers: {
+          solidity: async () => ({
+            default: async () => {
+              const handlers: Partial<SolidityHooks> = {
+                downloadCompilers: async (
+                  _context: HookContext,
+                  compilerConfigs: SolidityCompilerConfig[],
+                  _quiet: boolean,
+                ) => {
+                  capturedConfigs = compilerConfigs;
+                },
+              };
+
+              return handlers;
+            },
+          }),
+        },
+      };
+
+      const hre = await createHardhatRuntimeEnvironment({
+        plugins: [downloadPlugin],
+        solidity: {
+          compilers: [{ version: "0.8.23" }, { version: "0.8.24" }],
+        },
+      });
+
+      const roots = await hre.solidity.getRootFilePaths();
+      await hre.solidity.build(roots, {
+        force: true,
+        quiet: true,
+      });
+
+      const versions = capturedConfigs.map((c) => c.version);
+      // Both default and production profiles have these compilers
+      assert.ok(versions.includes("0.8.23"), "Should include version 0.8.23");
+      assert.ok(versions.includes("0.8.24"), "Should include version 0.8.24");
+    });
+
+    it("should include overrides in compiler configs", async () => {
+      let capturedConfigs: SolidityCompilerConfig[] = [];
+
+      const downloadPlugin: HardhatPlugin = {
+        id: "test-download-overrides-plugin",
+        hookHandlers: {
+          solidity: async () => ({
+            default: async () => {
+              const handlers: Partial<SolidityHooks> = {
+                downloadCompilers: async (
+                  _context: HookContext,
+                  compilerConfigs: SolidityCompilerConfig[],
+                  _quiet: boolean,
+                ) => {
+                  capturedConfigs = compilerConfigs;
+                },
+              };
+
+              return handlers;
+            },
+          }),
+        },
+      };
+
+      const hre = await createHardhatRuntimeEnvironment({
+        plugins: [downloadPlugin],
+        solidity: {
+          compilers: [{ version: "0.8.23" }],
+          overrides: {
+            "contracts/Special.sol": { version: "0.8.24" },
+          },
+        },
+      });
+
+      const roots = await hre.solidity.getRootFilePaths();
+      await hre.solidity.build(roots, {
+        force: true,
+        quiet: true,
+      });
+
+      const versions = capturedConfigs.map((c) => c.version);
+      assert.ok(
+        versions.includes("0.8.24"),
+        "Should include override version 0.8.24",
+      );
+    });
+
+    it("should filter non-solc configs in built-in handler", async () => {
+      // The built-in handler should only download solc compilers.
+      // A non-solc config (type: "solx") should not cause a download failure.
+      // We verify this by building with a mixed config — if the built-in
+      // handler tried to download "solx" type, it would fail since there's
+      // no solx binary to download via the solc downloader.
+      let capturedConfigs: SolidityCompilerConfig[] = [];
+
+      const downloadPlugin: HardhatPlugin = {
+        id: "test-filter-non-solc-plugin",
+        hookHandlers: {
+          solidity: async () => ({
+            default: async () => {
+              const handlers: Partial<SolidityHooks> = {
+                downloadCompilers: async (
+                  _context: HookContext,
+                  compilerConfigs: SolidityCompilerConfig[],
+                  _quiet: boolean,
+                ) => {
+                  capturedConfigs = compilerConfigs;
+                  // Don't call next — we handle all downloads here
+                  // to prevent the built-in handler from running
+                },
+              };
+
+              return handlers;
+            },
+          }),
+        },
+      };
+
+      const hre = await createHardhatRuntimeEnvironment({
+        plugins: [downloadPlugin],
+        solidity: {
+          compilers: [
+            { version: "0.8.23" },
+            { type: "solx", version: "0.8.23" },
+          ],
+        },
+      });
+
+      const roots = await hre.solidity.getRootFilePaths();
+      await hre.solidity.build(roots, {
+        force: true,
+        quiet: true,
+      });
+
+      // Verify both configs are passed (the hook receives ALL configs)
+      assert.equal(
+        capturedConfigs.filter((c) => c.type === undefined).length > 0,
+        true,
+        "Should include solc configs (type undefined)",
+      );
+      assert.equal(
+        capturedConfigs.filter((c) => c.type === "solx").length > 0,
+        true,
+        "Should include non-solc configs (type solx)",
+      );
+    });
+
+    it("should only download solc compilers in built-in handler", async () => {
+      // Build with both solc and non-solc configs.
+      // The built-in handler uses isSolcConfig() to filter — only solc
+      // versions should be downloaded. If it tried to download a non-existent
+      // "solx" version via the solc downloader, the build would fail.
+      const hre = await createHardhatRuntimeEnvironment({
+        solidity: {
+          compilers: [
+            { version: "0.8.23" },
+            { type: "solx", version: "0.8.23", path: "/mock/path/to/solx" },
+          ],
+        },
+      });
+
+      const roots = await hre.solidity.getRootFilePaths();
+      // This should NOT throw — the built-in handler should skip the solx
+      // config and only download solc 0.8.23 (which is cached)
+      await hre.solidity.build(roots, {
+        force: true,
+        quiet: true,
+      });
+    });
+  });
 });

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"hardhat": patch
 +---
++
 +Add downloadCompilers parallel hook for extensible compiler downloads
Original file line number	Diff line number	Diff line change
`@@ -41,6 +41,7 @@ const hardhatPlugin: HardhatPlugin = {`
`41`	`41`	`hookHandlers: {`
`42`	`42`	`config: () => import("./hook-handlers/config.js"),`
`43`	`43`	`hre: () => import("./hook-handlers/hre.js"),`
	`44`	`+ solidity: () => import("./hook-handlers/solidity.js"),`
`44`	`45`	`},`
`45`	`46`	`tasks: [`
`46`	`47`	`{`