hardhat 3.2.0 → 3.4.0

package/src/internal/builtin-plugins/solidity/type-extensions.ts

@@ -1,4 +1,4 @@
-import type { SolcConfig } from "../../../types/config.js";
+import type { SolidityCompilerConfig } from "../../../types/config.js";
 import type {
   BuildOptions,
   CompilationJobCreationError,
@@ -13,6 +13,26 @@ import type {
 
 import "../../../types/config.js";
 declare module "../../../types/config.js" {
+  /**
+   * An interface with a key per compiler type.
+   * The types of the values don't matter; we use `true` as a convention.
+   *
+   * By default, only "solc" is provided. Plugins can extend this via
+   * declaration merging to add new compiler types (e.g. "solx").
+   */
+  export interface SolidityCompilerTypeDefinitions {
+    solc: true;
+  }
+
+  /**
+   * The different Solidity compiler types, derived from
+   * SolidityCompilerTypeDefinitions. Extensible via declaration merging.
+   */
+  export type SolidityCompilerType = keyof SolidityCompilerTypeDefinitions;
+
+  /**
+   * The type of `userConfig.solidity`.
+   */
   export type SolidityUserConfig =
     | string
     | string[]
@@ -20,68 +40,271 @@ declare module "../../../types/config.js" {
     | MultiVersionSolidityUserConfig
     | BuildProfilesSolidityUserConfig;
 
-  export interface SolcUserConfig {
+  /**
+   * Fields that all the object-typed variants of SolidityUserConfig share.
+   *
+   * Note: All the variants of SolidityUserConfig except for the string and
+   * array of strings MUST extend this interface. For plugins creating their
+   * own `SingleVersionSolidityUserConfig` variant, see
+   * {@link CommonSingleVersionSolidityUserConfig}.
+   */
+  export interface CommonSolidityUserConfig {
+    isolated?: boolean;
+    npmFilesToBuild?: string[];
+    /**
+     * Controls whether Solidity test files are compiled in a separate pass
+     * from contract files.
+     *
+     * When `false` (the default), contracts and tests are compiled together
+     * in a single pass.
+     *
+     * When `true`, contracts and tests are compiled separately.
+     */
+    splitTestsCompilation?: boolean;
+  }
+
+  /**
+   * Common fields for every SingleVersionSolidityUserConfig variant.
+   *
+   * NOTE: All the variants of SingleVersionSolidityUserConfig must extend this
+   * interface.
+   */
+  export interface CommonSingleVersionSolidityUserConfig
+    extends CommonSolidityUserConfig {
+    toolVersionsInBuildInfo?: boolean;
+  }
+
+  /**
+   * Fields that all the SolidityCompilerUserConfig variants share.
+   *
+   * Note: All the types of SolidityCompilerUserConfig MUST extend this
+   * interface. This is especially relevant for plugins creating their own
+   * `SolidityCompilerUserConfig` variant.
+   */
+  export interface CommonSolidityCompilerUserConfig {
+    type?: SolidityCompilerType;
     version: string;
     settings?: any;
     path?: string;
-    preferWasm?: boolean;
   }
 
-  export interface SingleVersionSolcUserConfig extends SolcUserConfig {
-    isolated?: boolean;
+  /**
+   * Deprecated: Use `SolcSolidityCompilerUserConfig` instead.
+   * @deprecated
+   */
+  export interface SolcUserConfig extends CommonSolidityCompilerUserConfig {
+    // Note: This field is optional for backwards compatibility. No `type` means
+    // "solc" across all of Hardhat.
+    type?: "solc";
     preferWasm?: boolean;
   }
 
-  export interface MultiVersionSolcUserConfig {
-    isolated?: boolean;
-    preferWasm?: boolean;
-    compilers: SolcUserConfig[];
-    overrides?: Record<string, SolcUserConfig>;
+  /**
+   * Solc-specific SolidityCompilerUserConfig.
+   */
+  /* eslint-disable-next-line @typescript-eslint/no-empty-interface -- Defined
+    in SolcUserConfig for backwards compatibility */
+  export interface SolcSolidityCompilerUserConfig extends SolcUserConfig {}
+
+  /**
+   * A map from compiler type to its SolidityCompilerUserConfig type.
+   *
+   * Note: The types MUST extend `CommonSolidityCompilerUserConfig`.
+   */
+  export interface SolidityCompilerUserConfigPerType {
+    solc: SolcSolidityCompilerUserConfig;
   }
 
-  export interface CommonSolidityUserConfig {
-    npmFilesToBuild?: string[];
+  /**
+   * The type of all the compiler user configs.
+   */
+  export type SolidityCompilerUserConfig =
+    | {
+        [type in keyof SolidityCompilerUserConfigPerType]: SolidityCompilerUserConfigPerType[type];
+      }[keyof SolidityCompilerUserConfigPerType]
+    // SolcSolidityCompilerUserConfig when the type isn't present
+    | (Omit<SolcSolidityCompilerUserConfig, "type"> &
+        Partial<Pick<SolcSolidityCompilerUserConfig, "type">>);
+
+  /**
+   * Deprecated: Use `SolcSingleVersionSolidityUserConfig` instead.
+   * @deprecated
+   */
+  export interface SingleVersionSolcUserConfig
+    extends SolcSolidityCompilerUserConfig,
+      CommonSingleVersionSolidityUserConfig {}
+
+  /**
+   * Solc-specific SingleVersionSolidityUserConfig.
+   */
+  /* eslint-disable-next-line @typescript-eslint/no-empty-interface -- Defined
+    in SingleVersionSolcUserConfig for backwards compatibility */
+  export interface SolcSingleVersionSolidityUserConfig
+    extends SingleVersionSolcUserConfig {}
+
+  /**
+   * A map from compiler type to its SingleVersionSolidityUserConfig type.
+   *
+   * Note: The types MUST extend `CommonSingleVersionSolidityUserConfig`.
+   */
+  export interface SingleVersionSolidityUserConfigPerType {
+    solc: SolcSingleVersionSolidityUserConfig;
   }
 
-  export interface SingleVersionSolidityUserConfig
-    extends SingleVersionSolcUserConfig,
-      CommonSolidityUserConfig {}
+  /**
+   * The type of all the single version user configs.
+   */
+  export type SingleVersionSolidityUserConfig =
+    | {
+        [type in keyof SingleVersionSolidityUserConfigPerType]: SingleVersionSolidityUserConfigPerType[type];
+      }[keyof SingleVersionSolidityUserConfigPerType]
+    // SolcSingleVersionSolidityUserConfig when the type isn't present
+    | (Omit<SolcSingleVersionSolidityUserConfig, "type"> &
+        Partial<Pick<SolcSingleVersionSolidityUserConfig, "type">>);
+
+  /**
+   * Deprecated: Use `MultiVersionSolidityUserConfig` or
+   * `MultiVersionBuildProfileUserConfig` instead.
+   * @deprecated
+   */
+  export interface MultiVersionSolcUserConfig {
+    // Note: preferWasm is here for backwards compatibility. It can't be
+    // defined or not dependent on the type, as there isn't a top-level type.
+    // Instead, we post-validate the resolved config to make sure that it's
+    // only `true` if all the `compilers` and `overrides` have type `solc`.
+    preferWasm?: boolean;
+    // Note: Duplicated wrt CommonSolidityUserConfig for backwards compatibility
+    isolated?: boolean;
+    compilers: SolidityCompilerUserConfig[];
+    overrides?: Record<string, SolidityCompilerUserConfig>;
+  }
 
+  /**
+   * The type of a multi-version SolidityUserConfig.
+   *
+   * Partially defined in `MultiVersionSolcUserConfig` for backwards
+   * compatibility.
+   */
   export interface MultiVersionSolidityUserConfig
     extends MultiVersionSolcUserConfig,
-      CommonSolidityUserConfig {}
+      CommonSolidityUserConfig {
+    toolVersionsInBuildInfo?: boolean;
+  }
+
+  /**
+   * The type of a single-version build profile user config.
+   */
+  export type SingleVersionBuildProfileUserConfig =
+    SolidityCompilerUserConfig & {
+      isolated?: boolean;
+      toolVersionsInBuildInfo?: boolean;
+    };
 
+  /**
+   * The type of a multi-version build profile user config.
+   * Mostly defined in `MultiVersionSolcUserConfig` for backwards compatibility
+   */
+  export interface MultiVersionBuildProfileUserConfig
+    extends MultiVersionSolcUserConfig {
+    toolVersionsInBuildInfo?: boolean;
+  }
+
+  /**
+   * The type of the build profile version of the SolidityUserConfig.
+   */
   export interface BuildProfilesSolidityUserConfig
     extends CommonSolidityUserConfig {
     profiles: Record<
       string,
-      SingleVersionSolcUserConfig | MultiVersionSolcUserConfig
+      SingleVersionBuildProfileUserConfig | MultiVersionBuildProfileUserConfig
     >;
   }
 
+  /**
+   * Extension of HardhatUserConfig with the `solidity` property.
+   */
   export interface HardhatUserConfig {
     solidity?: SolidityUserConfig;
   }
 
-  export interface SolcConfig {
+  /**
+   * Common fields of a SolidityCompilerConfig.
+   *
+   * Note: All the types of SolidityCompiler config MUST extend this interface.
+   * This is especially relevant for plugins creating their own
+   * `SolidityCompilerConfig` variant.
+   */
+  export interface CommonSolidityCompilerConfig {
+    type?: SolidityCompilerType;
     version: string;
     settings: any;
     path?: string;
+  }
+
+  /**
+   * Deprecated: Use `SolcSolidityCompilerConfig` instead.
+   * @deprecated
+   */
+  export interface SolcConfig extends CommonSolidityCompilerConfig {
+    // Note: This field is optional for backwards compatibility. No `type` means
+    // "solc" across all of Hardhat.
+    type?: "solc";
     preferWasm?: boolean;
   }
 
+  /**
+   * The type of a solc-specific SolidityCompilerConfig.
+   */
+  /* eslint-disable-next-line @typescript-eslint/no-empty-interface -- Defined
+    in SolcConfig for backwards compatibility */
+  export interface SolcSolidityCompilerConfig extends SolcConfig {}
+
+  /**
+   * A map from compiler type to its `SolidityCompilerConfig` type. Note that
+   * the types MUST extend `CommonSolidityCompilerConfig`.
+   */
+  export interface SolidityCompilerConfigPerType {
+    solc: SolcSolidityCompilerConfig;
+  }
+
+  /**
+   * The type of all the compiler configs.
+   */
+  export type SolidityCompilerConfig =
+    | {
+        [type in keyof SolidityCompilerConfigPerType]: SolidityCompilerConfigPerType[type] & {
+          type: type;
+        };
+      }[keyof SolidityCompilerConfigPerType]
+    | (Omit<SolcSolidityCompilerConfig, "type"> &
+        Partial<Pick<SolcSolidityCompilerConfig, "type">>);
+
+  /**
+   * The type of a resolved build profile config.
+   */
   export interface SolidityBuildProfileConfig {
     isolated: boolean;
     preferWasm: boolean;
-    compilers: SolcConfig[];
-    overrides: Record<string, SolcConfig>;
+    // Note: This is optional for backwards compatibility.
+    // If `undefined` is present, it's equivalent to `false`.
+    toolVersionsInBuildInfo?: boolean;
+    compilers: SolidityCompilerConfig[];
+    overrides: Record<string, SolidityCompilerConfig>;
   }
 
+  /**
+   * Resolved Solidity config.
+   */
   export interface SolidityConfig {
     profiles: Record<string, SolidityBuildProfileConfig>;
     npmFilesToBuild: string[];
+    registeredCompilerTypes: SolidityCompilerType[];
+    splitTestsCompilation: boolean;
   }
 
+  /**
+   * An extension of HardhatConfig with the `solidity` property.
+   */
   export interface HardhatConfig {
     solidity: SolidityConfig;
   }
@@ -116,6 +339,40 @@ 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 to obtain a Compiler instance for a given compiler configuration.
+     * The default handler returns a solc compiler. Plugins can intercept to
+     * return their own compiler (e.g. SolxCompiler for type: "solx").
+     *
+     * @param context The hook context.
+     * @param compilerConfig The compiler configuration to get a compiler for.
+     * @param next A function to call the next handler for this hook.
+     * @returns A Compiler instance.
+     */
+    getCompiler: (
+      context: HookContext,
+      compilerConfig: SolidityCompilerConfig,
+      next: (
+        nextContext: HookContext,
+        nextCompilerConfig: SolidityCompilerConfig,
+      ) => Promise<Compiler>,
+    ) => Promise<Compiler>;
+
     /**
      * Hook triggered during the cleanup process of Solidity compilation artifacts.
      * This hook runs after unused artifacts and build-info files have been removed.
@@ -166,7 +423,7 @@ declare module "../../../types/hooks.js" {
     ): Promise<string>;
 
     /**
-     * Hook triggered within the compilation job when its' solc input is first constructed.
+     * Hook triggered within the compilation job when its solc input is first constructed.
      *
      * @param context The hook context.
      * @param solcInput The solc input that will be passed to solc.
@@ -215,18 +472,18 @@ declare module "../../../types/hooks.js" {
     ) => Promise<CompilationJobCreationError | Map<string, FileBuildResult>>;
 
     /**
-     * Hook triggered to invoke a passed in Solc compiler on the
-     * Solc input generated for a given compilation job.
-     * This hook allows for manipulating the Solc input passed into the Solc
-     * compiler Hardhat has selected for the compilation job, and similarly to
-     * manipulate the Solc output.
+     * Hook triggered to invoke a compiler on the standard-json input
+     * generated for a given compilation job.
+     * This hook allows for manipulating the input passed into the compiler
+     * Hardhat has selected for the compilation job, and similarly to
+     * manipulate the output.
      *
      * @param context The hook context.
-     * @param compile The Solc compiler selected by Hardhat for this compilation
-     * job.
-     * @param solcInput The solc input json constructed from the compilation
+     * @param compiler The compiler selected by Hardhat for this compilation
      * job.
-     * @param solcConfig The configuration used to setup solc e.g. version.
+     * @param solcInput The standard-json input constructed from the
+     * compilation job.
+     * @param solcConfig The compiler configuration (version, type, etc.).
      * @param next A function to call the next handler for this hook, or the
      * default implementation if no more handlers exist.
      */
@@ -234,12 +491,12 @@ declare module "../../../types/hooks.js" {
       context: HookContext,
       compiler: Compiler,
       solcInput: CompilerInput,
-      solcConfig: SolcConfig,
+      solcConfig: SolidityCompilerConfig,
       next: (
         nextContext: HookContext,
         nextCompiler: Compiler,
         nextSolcInput: CompilerInput,
-        nextSolcConfig: SolcConfig,
+        nextSolcConfig: SolidityCompilerConfig,
       ) => Promise<CompilerOutput>,
     ): Promise<CompilerOutput>;
 

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

@@ -19,6 +19,7 @@ import {
   conditionalUnionType,
   sensitiveStringSchema,
   sensitiveUrlSchema,
+  unionType,
   validateUserConfigZodType,
 } from "@nomicfoundation/hardhat-zod-utils";
 import { z } from "zod";
@@ -28,7 +29,6 @@ export const DEFAULT_FUZZ_SEED =
   "0x7727ea51af0441c20da14dcd68a15dac8c9ebd589c5be8fa8c87c1d3720450bc";
 
 const solidityTestUserConfigType = z.object({
-  timeout: z.number().optional(),
   fsPermissions: z
     .object({
       readWriteFile: z.array(z.string()).optional(),
@@ -66,7 +66,12 @@ const solidityTestUserConfigType = z.object({
   forking: z
     .object({
       url: z.optional(sensitiveUrlSchema),
-      blockNumber: z.bigint().optional(),
+      blockNumber: z.optional(
+        unionType(
+          [z.number().int().nonnegative().safe(), z.bigint().nonnegative()],
+          "Expected a nonnegative safe int or a nonnegative bigint",
+        ),
+      ),
       rpcEndpoints: z.record(sensitiveStringSchema).optional(),
     })
     .optional(),
@@ -122,6 +127,10 @@ export function resolveSolidityTestForkingConfig(
 
   return {
     ...forkingUserConfig,
+    blockNumber:
+      forkingUserConfig.blockNumber !== undefined
+        ? BigInt(forkingUserConfig.blockNumber)
+        : undefined,
     url:
       forkingUserConfig.url !== undefined
         ? resolveConfigurationVariable(forkingUserConfig.url)

package/src/internal/builtin-plugins/solidity-test/edr-artifacts.ts

@@ -1,14 +1,24 @@
 import type { Artifact, ArtifactManager } from "../../../types/artifacts.js";
 import type {
-  BuildInfoAndOutput,
+  BuildInfoAndOutput as EdrBuildInfoAndOutput,
   Artifact as EdrArtifact,
 } from "@nomicfoundation/edr";
 
 import { assertHardhatInvariant } from "@nomicfoundation/hardhat-errors";
 import { readBinaryFile } from "@nomicfoundation/hardhat-utils/fs";
 
-const BUILD_INFO_FORMAT =
-  /^solc-(?<major>\d+)_(?<minor>\d+)_(?<patch>\d+)-[0-9a-fA-F]*$/;
+export interface BuildInfoAndOutput extends EdrBuildInfoAndOutput {
+  buildInfoId: string;
+}
+
+export interface EdrArtifactWithMetadata {
+  edrArtifact: EdrArtifact;
+  userSourceName: string;
+  buildInfoId: string;
+}
+
+export const BUILD_INFO_FORMAT: RegExp =
+  /^solc-(?<major>\d+)_(?<minor>\d+)_(?<patch>\d+)(?:-(?<compilerType>[a-zA-Z][a-zA-Z0-9]*))?-[0-9a-fA-F]*$/;
 
 /**
  * This function returns all the build infos and associated outputs.
@@ -16,16 +26,16 @@ const BUILD_INFO_FORMAT =
  * @param artifactManager The artifact manager.
  * @returns The build infos in the Hardhat v3 format as expected by the EDR.
  */
-export async function getBuildInfos(
+export async function getBuildInfosAndOutputs(
   artifactManager: ArtifactManager,
 ): Promise<BuildInfoAndOutput[]> {
-  const buildIds = await artifactManager.getAllBuildInfoIds();
+  const buildInfoIds = await artifactManager.getAllBuildInfoIds();
 
   return Promise.all(
-    Array.from(buildIds).map(async (buildId) => {
-      const buildInfoPath = await artifactManager.getBuildInfoPath(buildId);
+    Array.from(buildInfoIds).map(async (buildInfoId) => {
+      const buildInfoPath = await artifactManager.getBuildInfoPath(buildInfoId);
       const buildInfoOutputPath =
-        await artifactManager.getBuildInfoOutputPath(buildId);
+        await artifactManager.getBuildInfoOutputPath(buildInfoId);
 
       // This is only safe because of how we currently interact with getBuildInfos
       // i.e. we call it immediately after a build which should ensure both
@@ -45,6 +55,7 @@ export async function getBuildInfos(
       const output = await readBinaryFile(buildInfoOutputPath);
 
       return {
+        buildInfoId,
         buildInfo,
         output,
       };
@@ -58,9 +69,9 @@ export async function getBuildInfos(
  * @param artifactManager The artifact manager.
  * @returns The artifacts in the format expected by the EDR.
  */
-export async function getEdrArtifacts(
+export async function buildEdrArtifactsWithMetadata(
   artifactManager: ArtifactManager,
-): Promise<Array<{ edrArtifact: EdrArtifact; userSourceName: string }>> {
+): Promise<EdrArtifactWithMetadata[]> {
   const fullyQualifiedNames = await artifactManager.getAllFullyQualifiedNames();
 
   const artifacts = await Promise.all(
@@ -145,6 +156,7 @@ export async function getEdrArtifacts(
         contract,
       },
       userSourceName: artifact.sourceName,
+      buildInfoId: artifact.buildInfoId,
     };
   });
 }