hardhat 3.1.9 → 3.1.11

package/src/internal/using-hardhat2-plugin-errors.ts

@@ -0,0 +1,108 @@
+import { fileURLToPath } from "node:url";
+
+import { CustomError } from "@nomicfoundation/hardhat-utils/error";
+import { shortenPath } from "@nomicfoundation/hardhat-utils/path";
+import chalk from "chalk";
+
+export class UsingHardhat2PluginError extends CustomError {
+  public readonly callerRelativePath: string | undefined;
+  constructor() {
+    const callerPath = getCallerRelativePath();
+
+    let message: string;
+    if (callerPath !== undefined) {
+      message = `You are trying to use a Hardhat 2 plugin in a Hardhat 3 project.
+
+This file is part of a Hardhat 2 plugin calling an API that was removed in Hardhat 3: ${chalk.bold(callerPath)}
+
+Please read https://hardhat.org/migrate-from-hardhat2 to learn how to migrate your project to Hardhat 3.
+`;
+    } else {
+      message = `You are trying to use a Hardhat 2 plugin in a Hardhat 3 project.
+      
+Check the stack trace below to identify which plugin is causing this.
+
+Please read https://hardhat.org/migrate-from-hardhat2 to learn how to migrate your project to Hardhat 3.
+`;
+    }
+
+    super(message);
+    this.callerRelativePath = callerPath;
+  }
+}
+
+/**
+ * Returns the relative path of the file that called a deprecated Hardhat
+ * plugin API, based on the stack trace. This helps identify which plugin
+ * file is triggering usage of Hardhat 2 APIs in a Hardhat 3 project.
+ *
+ * @param {number} [depth=5] The stack trace depth to locate the caller's
+ * source file. By default, depth 5 is used because:
+ *   0 = message
+ *   1 = getCallerRelativePath
+ *   2 = UsingHardhat2PluginError constructor
+ *   3 = throwUsingHardhat2PluginError
+ *   4 = deprecated function
+ *   5 = actual caller (the plugin file)
+ *
+ * @returns {string|undefined} The shortened relative path of the caller file,
+ * or undefined if not found.
+ *
+ * @example
+ * If the stack trace is:
+ * // Error
+ * //     at getCallerRelativePath (src/internal/using-hardhat2-plugin-errors.ts:34:15)
+ * //     at UsingHardhat2PluginError.constructor (src/internal/using-hardhat2-plugin-errors.ts:7:3)
+ * //     at throwUsingHardhat2PluginError (src/internal/using-hardhat2-plugin-errors.ts:90:3)
+ * //     at deprecatedFunction (plugins/example-plugin/deprecated.js:50:10)
+ * //     at main (plugins/example-plugin/index.js:100:5)
+ * Calling getCallerRelativePath() returns 'plugins/example-plugin/index.js'
+ */
+export function getCallerRelativePath(depth: number = 5): string | undefined {
+  try {
+    const stack = new Error().stack;
+    if (stack === undefined) {
+      return undefined;
+    }
+
+    const lines = stack.split("\n");
+    const callerLine = lines[depth];
+    if (callerLine === undefined) {
+      return undefined;
+    }
+
+    /**
+     * Matches a single stack trace line:
+     *
+     * at FunctionName (path/to/file.ts:10:5)
+     * at path/to/file.ts:10:5
+     *
+     * Captures:
+     *  - group 1: file location (without line/column)
+     */
+    const STACK_TRACE_LINE_REGEX =
+      /^at (?:.+? \()?([^\(].*?)(?::\d+)?(?::\d+)?\)?$/;
+
+    const match = callerLine.trim().match(STACK_TRACE_LINE_REGEX);
+    if (match === null || match[1] === undefined) {
+      return undefined;
+    }
+
+    let filePath = match[1];
+
+    // Handle file:// URLs from ESM stack traces
+    if (filePath.startsWith("file://")) {
+      filePath = fileURLToPath(filePath);
+    }
+
+    return shortenPath(filePath);
+  } catch {
+    return undefined;
+  }
+}
+
+export function throwUsingHardhat2PluginError(): never {
+  /* eslint-disable-next-line no-restricted-syntax -- Intentionally throwing a
+    custom error here so that we always print the stack trace */
+  throw new UsingHardhat2PluginError();
+}

package/src/plugins.ts

@@ -1 +1,17 @@
 export { HardhatPluginError } from "@nomicfoundation/hardhat-errors";
+
+import { throwUsingHardhat2PluginError } from "./internal/using-hardhat2-plugin-errors.js";
+
+/**
+ * @deprecated This function is part of the Hardhat 2 plugin API.
+ */
+export function lazyFunction(..._args: any): any {
+  throwUsingHardhat2PluginError();
+}
+
+/**
+ * @deprecated This function is part of the Hardhat 2 plugin API.
+ */
+export function lazyObject(..._args: any): any {
+  throwUsingHardhat2PluginError();
+}

package/src/types/artifacts.ts

@@ -1,4 +1,5 @@
 import type { SolidityBuildInfo } from "./solidity/solidity-artifacts.js";
+import type { NonNeverKeys } from "./utils.js";
 
 /**
  * A map of bare contract names and fully qualified contract names to their
@@ -17,6 +18,37 @@ export type GetArtifactByName<ContractNameT extends string> =
     ? ArtifactMap[ContractNameT]
     : Artifact;
 
+/**
+ * A type that represents the contract names (bare and fully qualified) of all
+ * the artifacts that have been built in a project. This enables the
+ * autocomplete of the TS Language Server to list the actual contracts, without
+ * leading to a compilation error for general strings, so it doesn't fail
+ * before `hardhat build` is run.
+ *
+ * This is meant to be used in functions like this:
+ * @example
+ * ```
+ * function doSomething<ContractNameT extends ArtifactContractNames>(
+ *   contractName: ContractNameT,
+ *   ...
+ * ): DoSomethingReturnType<ContractNameT> {
+ * }
+ */
+export type ArtifactContractNames = keyof ArtifactMap extends never
+  ? string
+  : NonNeverKeys<ArtifactMap>;
+
+/**
+ * A type that represents a string that should match an artifact contract name,
+ * but it doesn't fail if the string is not a contract name. It's mostly used
+ * to offer autocompletion.
+ *
+ * @see {@link ArtifactContractNames}
+ */
+export type StringWithArtifactContractNamesAutocompletion =
+  | ArtifactContractNames
+  | (string & {});
+
 /**
  * The ArtifactManager is responsible for reading and writing artifacts from
  * the Hardhat build system.
@@ -28,13 +60,18 @@ export interface ArtifactManager {
    * @param contractNameOrFullyQualifiedName The name of the contract.
    *   It can be a contract bare contract name (e.g. "Token") if it's
    *   unique in your project, or a fully qualified contract name
-   *   (e.g. "contract/token.sol:Token") otherwise.
+   *   (e.g. "contract/token.sol:Token") otherwise. TypeScript's language server
+   *   autocompletes the names of the contracts that have already been built. If
+   *   your contract name isn't in the list, you can still use it, and/or run
+   *   `hardhat build` to get it in the list.
    *
    * @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.
    */
-  readArtifact<ContractNameT extends string>(
+  readArtifact<
+    ContractNameT extends StringWithArtifactContractNamesAutocompletion,
+  >(
     contractNameOrFullyQualifiedName: ContractNameT,
   ): Promise<GetArtifactByName<ContractNameT>>;
 
@@ -239,7 +276,7 @@ export interface LinkReferences {
  * is the id of the AST node that represents the variable.
  */
 export interface ImmutableReferences {
-  [immuatableId: string]: Array<{ start: number; length: number }>;
+  [immutableId: string]: Array<{ start: number; length: number }>;
 }
 
 /**

package/src/types/hre.ts

@@ -15,7 +15,7 @@ export interface HardhatRuntimeEnvironment {
     readonly hardhat: string;
     readonly edr: string;
   };
-  // These fields are defined using module agumentation despite being part of
+  // These fields are defined using module augmentation despite being part of
   // Hardhat's core:
   // readonly hooks: HookManager;
   // readonly tasks: TaskManager;

package/src/types/index.ts

@@ -0,0 +1,14 @@
+export * from "./arguments.js";
+export * from "./artifacts.js";
+export * from "./config.js";
+export * from "./global-options.js";
+export * from "./hooks.js";
+export * from "./hre.js";
+export * from "./network.js";
+export * from "./plugins.js";
+export * from "./providers.js";
+export * from "./solidity.js";
+export * from "./tasks.js";
+export * from "./test.js";
+export * from "./user-interruptions.js";
+export * from "./utils.js";

package/src/types/network.ts

@@ -10,7 +10,7 @@ import type { EthereumProvider } from "./providers.js";
 export type ChainType = GenericChainType | "l1" | "op";
 
 /**
- * The most generic chanin type.
+ * The most generic chain type.
  */
 export type GenericChainType = "generic";
 

package/src/types/plugins.ts

@@ -65,8 +65,8 @@ export interface HardhatPlugin {
    * returning an object with a handler for the `extendUserConfig` hook.
    *
    * You can define each factory in two ways:
-   *  - As an inline function.
-   *  - As a string with the path to a file that exports the factory as `default`.
+   * - As an inline function.
+   * - As a string with the path to a file that exports the factory as `default`.
    *
    * The first option should only be used for development. You MUST use the second
    * option for production.

package/src/types/solidity/build-system.ts

@@ -72,7 +72,7 @@ export type RunCompilationJobOptions = Pick<
  */
 export interface CompileBuildInfoOptions {
   /**
-   * If `true`, this option foces the build system to recompile the build info,
+   * If `true`, this option forces the build system to recompile the build info,
    * even if its output is cached.
    */
   force?: boolean;
@@ -84,26 +84,70 @@ export interface CompileBuildInfoOptions {
 }
 
 export enum CompilationJobCreationErrorReason {
-  NO_COMPATIBLE_SOLC_VERSION_FOUND = "NO_COMPATIBLE_SOLC_VERSION_FOUND",
+  /**
+   * The root file's own pragmas are incompatible with all configured compilers.
+   */
   NO_COMPATIBLE_SOLC_VERSION_WITH_ROOT = "NO_COMPATIBLE_SOLC_VERSION_WITH_ROOT",
-  INCOMPATIBLE_OVERRIDDEN_SOLC_VERSION = "INCOMPATIBLE_OVERRIDDEN_SOLC_VERSION",
+
+  /**
+   * A dependency's own pragmas are incompatible with all configured compilers.
+   */
+  NO_COMPATIBLE_SOLC_VERSION_WITH_DEPENDENCY = "NO_COMPATIBLE_SOLC_VERSION_WITH_DEPENDENCY",
+
+  /**
+   * Root and a transitive import path have contradictory pragmas (invalid range / empty intersection).
+   */
   IMPORT_OF_INCOMPATIBLE_FILE = "IMPORT_OF_INCOMPATIBLE_FILE",
+
+  /**
+   * Root and a transitive import path have a valid range but no configured compiler satisfies it.
+   */
+  NO_COMPATIBLE_SOLC_VERSION_FOR_TRANSITIVE_IMPORT_PATH = "NO_COMPATIBLE_SOLC_VERSION_FOR_TRANSITIVE_IMPORT_PATH",
+
+  /**
+   * The override version doesn't satisfy the root file's own pragmas.
+   */
+  INCOMPATIBLE_OVERRIDDEN_SOLC_VERSION = "INCOMPATIBLE_OVERRIDDEN_SOLC_VERSION",
+
+  /**
+   * A dependency's pragmas are incompatible with the override version.
+   */
+  OVERRIDDEN_SOLC_VERSION_INCOMPATIBLE_WITH_DEPENDENCY = "OVERRIDDEN_SOLC_VERSION_INCOMPATIBLE_WITH_DEPENDENCY",
+
+  /**
+   * Generic fallback — no single compiler works for root + all dependencies.
+   */
+  NO_COMPATIBLE_SOLC_VERSION_FOUND = "NO_COMPATIBLE_SOLC_VERSION_FOUND",
 }
 
 export interface BaseCompilationJobCreationError {
+  success: false;
   buildProfile: string;
   rootFilePath: string;
   formattedReason: string;
 }
 
-export interface CompilationJobCreationErrorNoCompatibleSolcVersionFound
+export interface CompilationJobCreationErrorNoCompatibleSolcVersionWithRoot
   extends BaseCompilationJobCreationError {
   reason: CompilationJobCreationErrorReason.NO_COMPATIBLE_SOLC_VERSION_WITH_ROOT;
 }
 
-export interface CompilationJobCreationErrorIncompatibleOverriddenSolcVersion
+export interface CompilationJobCreationErrorNoCompatibleSolcVersionWithDependency
   extends BaseCompilationJobCreationError {
-  reason: CompilationJobCreationErrorReason.INCOMPATIBLE_OVERRIDDEN_SOLC_VERSION;
+  reason: CompilationJobCreationErrorReason.NO_COMPATIBLE_SOLC_VERSION_WITH_DEPENDENCY;
+  incompatibleImportPath: string[];
+}
+
+export interface CompilationJobCreationErrorImportOfIncompatibleFile
+  extends BaseCompilationJobCreationError {
+  reason: CompilationJobCreationErrorReason.IMPORT_OF_INCOMPATIBLE_FILE;
+  incompatibleImportPath: string[];
+}
+
+export interface CompilationJobCreationErrorNoCompatibleSolcVersionForTransitiveImportPath
+  extends BaseCompilationJobCreationError {
+  reason: CompilationJobCreationErrorReason.NO_COMPATIBLE_SOLC_VERSION_FOR_TRANSITIVE_IMPORT_PATH;
+  incompatibleImportPath: string[];
 }
 
 export interface CompilationJobCreationErrorIncompatibleOverriddenSolcVersion
@@ -111,24 +155,25 @@ export interface CompilationJobCreationErrorIncompatibleOverriddenSolcVersion
   reason: CompilationJobCreationErrorReason.INCOMPATIBLE_OVERRIDDEN_SOLC_VERSION;
 }
 
-export interface CompilationJobCreationErrorIportOfIncompatibleFile
+export interface CompilationJobCreationErrorOverriddenSolcVersionIncompatibleWithDependency
   extends BaseCompilationJobCreationError {
-  reason: CompilationJobCreationErrorReason.IMPORT_OF_INCOMPATIBLE_FILE;
-  // The path of absolute files imported, starting from the root, that take you
-  // to the first file with an incompatible version pragma.
+  reason: CompilationJobCreationErrorReason.OVERRIDDEN_SOLC_VERSION_INCOMPATIBLE_WITH_DEPENDENCY;
   incompatibleImportPath: string[];
 }
 
-export interface NoCompatibleSolcVersionFound
+export interface CompilationJobCreationErrorNoCompatibleSolcVersionFound
   extends BaseCompilationJobCreationError {
   reason: CompilationJobCreationErrorReason.NO_COMPATIBLE_SOLC_VERSION_FOUND;
 }
 
 export type CompilationJobCreationError =
-  | CompilationJobCreationErrorNoCompatibleSolcVersionFound
-  | CompilationJobCreationErrorIportOfIncompatibleFile
+  | CompilationJobCreationErrorNoCompatibleSolcVersionWithRoot
+  | CompilationJobCreationErrorNoCompatibleSolcVersionWithDependency
+  | CompilationJobCreationErrorImportOfIncompatibleFile
+  | CompilationJobCreationErrorNoCompatibleSolcVersionForTransitiveImportPath
   | CompilationJobCreationErrorIncompatibleOverriddenSolcVersion
-  | NoCompatibleSolcVersionFound;
+  | CompilationJobCreationErrorOverriddenSolcVersionIncompatibleWithDependency
+  | CompilationJobCreationErrorNoCompatibleSolcVersionFound;
 
 /**
  * The restult of building a file.
@@ -174,6 +219,11 @@ export interface CacheHitInfo {
  * The keys in the maps of this interface are Root File Paths, which means either absolute paths or `npm:<package>/<file>` URIs.
  */
 export interface GetCompilationJobsResult {
+  /**
+   * A flag to distinguish between a successful and a failed result.
+   */
+  success: true;
+
   /**
    * Map from root file path to compilation job for files that need compilation.
    */
@@ -239,12 +289,23 @@ export interface SolidityBuildSystem {
    * @param options The options to use when building the files.
    * @returns An `Map` of the files to their build results, or an error if
    * there was a problem when trying to create the necessary compilation jobs.
+   * @see `isSuccessfulBuildResult` to check if the build result is successful.
    */
   build(
     rootFilePaths: string[],
     options?: BuildOptions,
   ): Promise<CompilationJobCreationError | Map<string, FileBuildResult>>;
 
+  /**
+   * Returns true if the given build result is successful.
+   *
+   * @param buildResult Result of the `build` method.
+   * @returns True if the build result is successful.
+   */
+  isSuccessfulBuildResult(
+    buildResult: CompilationJobCreationError | Map<string, FileBuildResult>,
+  ): buildResult is Map<string, FileBuildResult>;
+
   /**
    * Returns the CompilationJobs that would be used to build the provided files.
    *

package/src/types/solidity/errors.ts

@@ -91,6 +91,11 @@ export interface NpmRootFileOfUninstalledPackageError {
   type: RootResolutionErrorType.NPM_ROOT_FILE_OF_UNINSTALLED_PACKAGE;
   npmModule: string;
   installationName: string;
+  /**
+   * A boolean indicating if the Hardhat project has a foundry.toml file in its
+   * root.
+   */
+  projectHasFoundryToml?: boolean;
 }
 
 export interface NpmRootResolutionWithRemappingErrors {
@@ -109,6 +114,10 @@ export interface NpmRootFileWithIncorrectCasingError
   extends ResolvedFileReference {
   type: RootResolutionErrorType.NPM_ROOT_FILE_WITH_INCORRECT_CASING;
   npmModule: string;
+  /**
+   * The correct casing of the file, expressed as the relative fs path from the
+   * package's root, using forward slashes, and without a leading "./".
+   */
   correctCasing: string;
 }
 
@@ -216,6 +225,10 @@ export interface ImportInvalidCasingError extends ResolvedFileReference {
   type: ImportResolutionErrorType.IMPORT_INVALID_CASING;
   fromFsPath: string;
   importPath: string;
+  /**
+   * The correct casing of the file, expressed as the relative fs path from the
+   * package's root, using forward slashes, and without a leading "./".
+   */
   correctCasing: string;
 }
 
@@ -230,6 +243,11 @@ export interface ImportOfUninstalledPackageError {
   fromFsPath: string;
   importPath: string;
   installationName: string;
+  /**
+   * A boolean indicating weather the import is from a source file whose package
+   * has a foundry.toml file in its root.
+   */
+  importerPackageHasFoundryToml?: boolean;
 }
 
 export interface ImportWithRemappingErrorsError {
@@ -348,10 +366,14 @@ export interface ResolvedFileReference {
   //    package's input source name root, after applying the user remapping.
   //  - For an npm import, it's the npm-subpath. i.e. the module identifier
   //    without the package name.
+  //
+  // This never includes a leading "./".
   subpath: string;
 
   // The subpath after resolving package.exports
   //
   // Only present when actually using package.exports.
+  //
+  // This never includes a leading "./".
   packageExportsResolvedSubpath?: string;
 }

package/src/types/solidity/resolved-file.ts

@@ -3,7 +3,7 @@
  */
 export interface ResolvedNpmPackage {
   /**
-   * The name of the package, potentially scopde.
+   * The name of the package, potentially scoped.
    */
   name: string;
 
@@ -103,7 +103,7 @@ export interface NpmPackageResolvedFile {
 }
 
 /**
- * The resolult of resolving a file or import using a Resolver.
+ * The result of resolving a file or import using a Resolver.
  */
 export type ResolvedFile = ProjectResolvedFile | NpmPackageResolvedFile;