hardhat 3.16.0 → 3.17.0

package/src/internal/builtin-plugins/network-manager/request-handlers/handlers/gas/multiplied-gas-estimation.ts

@@ -1,27 +1,48 @@
 import type { EthereumProvider } from "../../../../../../types/providers.js";
 
 import { assertHardhatInvariant } from "@nomicfoundation/hardhat-errors";
+import { min } from "@nomicfoundation/hardhat-utils/bigint";
 import { ensureError } from "@nomicfoundation/hardhat-utils/error";
 import {
   hexStringToNumber,
   numberToHexString,
 } from "@nomicfoundation/hardhat-utils/hex";
 
+import { InternalCallOutOfGasError } from "../../../provider-errors.js";
+
+/**
+ * The fraction of the observed block gas limit that gets cached and used as the
+ * gas limit ceiling. The cached value is deliberately lower than what the
+ * latest block reported, to leave room for the block gas limit varying
+ * slightly between blocks after we cached it.
+ */
+export const BLOCK_GAS_LIMIT_SAFETY_FACTOR = 0.95;
+
 /**
  * This class handles gas estimation for transactions by applying a multiplier to the estimated gas value.
  * It requests a gas estimation from the provider and multiplies it by a predefined gas multiplier, ensuring the gas does not exceed the block's gas limit.
- * If an execution error occurs, the method returns the block's gas limit instead.
- * The block gas limit is cached after the first retrieval to optimize performance.
+ * If the estimation fails because an internal call runs out of gas regardless of the gas limit, the method returns the fallback gas limit, capped to the current block gas limit on networks that enforce one, or rethrows when no fallback gas limit is known.
+ * If any other error whose message contains "execution error" occurs, the method returns the capped block gas limit instead. Every other error is rethrown.
+ * The capped block gas limit is the latest block's gas limit scaled by `BLOCK_GAS_LIMIT_SAFETY_FACTOR`, cached after the first retrieval to optimize performance, except when capping the fallback gas limit, which reads the pending block's unscaled one.
  */
 export abstract class MultipliedGasEstimation {
   readonly #provider: EthereumProvider;
   readonly #gasMultiplier: number;
+  readonly #fallbackGas: bigint | undefined;
+  readonly #isBlockGasLimitEnforced: () => boolean;
 
   #blockGasLimit: number | undefined;
 
-  constructor(provider: EthereumProvider, gasMultiplier: number) {
+  constructor(
+    provider: EthereumProvider,
+    gasMultiplier: number,
+    fallbackGas?: bigint,
+    isBlockGasLimitEnforced: () => boolean = () => true,
+  ) {
     this.#provider = provider;
     this.#gasMultiplier = gasMultiplier;
+    this.#fallbackGas = fallbackGas;
+    this.#isBlockGasLimitEnforced = isBlockGasLimitEnforced;
   }
 
   protected async getMultipliedGasEstimation(params: any[]): Promise<string> {
@@ -52,6 +73,34 @@ export abstract class MultipliedGasEstimation {
     } catch (error) {
       ensureError(error);
 
+      // We fall back instead of failing the transaction, because the user
+      // never asked for this estimation. The fallback is the gas limit the
+      // network itself uses for requests with no gas field. Connections that
+      // don't expose it (e.g. an http connection to a `hardhat node` server)
+      // get no fallback, and the estimation error reaches the user instead of
+      // a guessed limit that may not suit the remote network: the error names
+      // both remedies, an explicit gas limit or the topLevelSuccess mode.
+      //
+      // The cap reads the pending block's limit fresh rather than the cache:
+      // evm_setBlockGasLimit may have lowered it, and only the pending block
+      // reflects that before the next block is mined.
+      //
+      // Networks that don't enforce a block gas limit are exempt: their
+      // headers still report one, so capping would shrink the fallback to a
+      // limit nothing rejects it for.
+      if (
+        error instanceof InternalCallOutOfGasError &&
+        this.#fallbackGas !== undefined
+      ) {
+        if (!this.#isBlockGasLimitEnforced()) {
+          return numberToHexString(this.#fallbackGas);
+        }
+
+        const blockGasLimit = BigInt(await this.#fetchBlockGasLimit("pending"));
+
+        return numberToHexString(min(this.#fallbackGas, blockGasLimit));
+      }
+
       if (error.message.toLowerCase().includes("execution error")) {
         const blockGasLimitTmp = await this.#getBlockGasLimit();
         return numberToHexString(blockGasLimitTmp);
@@ -63,25 +112,31 @@ export abstract class MultipliedGasEstimation {
 
   async #getBlockGasLimit(): Promise<number> {
     if (this.#blockGasLimit === undefined) {
-      const latestBlock = await this.#provider.request({
-        method: "eth_getBlockByNumber",
-        params: ["latest", false],
-      });
-
-      assertHardhatInvariant(
-        typeof latestBlock === "object" &&
-          latestBlock !== null &&
-          "gasLimit" in latestBlock &&
-          typeof latestBlock.gasLimit === "string",
-        "latestBlock should have a gasLimit",
-      );
-
-      const fetchedGasLimit = hexStringToNumber(latestBlock.gasLimit);
+      const fetchedGasLimit = await this.#fetchBlockGasLimit("latest");
 
       // We store a lower value in case the gas limit varies slightly
-      this.#blockGasLimit = Math.floor(fetchedGasLimit * 0.95);
+      this.#blockGasLimit = Math.floor(
+        fetchedGasLimit * BLOCK_GAS_LIMIT_SAFETY_FACTOR,
+      );
     }
 
     return this.#blockGasLimit;
   }
+
+  async #fetchBlockGasLimit(blockTag: "latest" | "pending"): Promise<number> {
+    const block = await this.#provider.request({
+      method: "eth_getBlockByNumber",
+      params: [blockTag, false],
+    });
+
+    assertHardhatInvariant(
+      typeof block === "object" &&
+        block !== null &&
+        "gasLimit" in block &&
+        typeof block.gasLimit === "string",
+      `the ${blockTag} block should have a gasLimit`,
+    );
+
+    return hexStringToNumber(block.gasLimit);
+  }
 }

package/src/internal/builtin-plugins/network-manager/request-handlers/handlers-array.ts

@@ -63,10 +63,34 @@ export async function createHandlersArray<
   }
 
   if (networkConfig.gas === undefined || networkConfig.gas === "auto") {
+    // On EDR networks, if the gas estimation fails because an internal call
+    // runs out of gas regardless of the gas limit, we fall back to the same
+    // default transaction gas limit that the network uses for requests
+    // without a gas field. The EdrProvider exposes the exact value it was
+    // configured with, so the fallback always matches the provider's actual
+    // default. Providers that don't expose it (e.g. HTTP connections) get no
+    // fallback, and the handler surfaces the estimation error instead of
+    // guessing a limit that may not suit the remote network.
+    const provider = networkConnection.provider;
+    const fallbackGas =
+      "defaultTransactionGasLimit" in provider &&
+      typeof provider.defaultTransactionGasLimit === "bigint"
+        ? provider.defaultTransactionGasLimit
+        : undefined;
+
+    // The fallback only gets capped on networks that enforce a block gas
+    // limit. Read lazily, as enforcement can turn on at runtime; providers
+    // that don't report it are conservatively assumed to enforce one.
+    const isBlockGasLimitEnforced = () =>
+      !("isBlockGasLimitEnforced" in provider) ||
+      provider.isBlockGasLimitEnforced !== false;
+
     requestHandlers.push(
       new AutomaticGasHandler(
         networkConnection.provider,
         networkConfig.gasMultiplier,
+        fallbackGas,
+        isBlockGasLimitEnforced,
       ),
     );
   } else {

package/src/internal/builtin-plugins/network-manager/type-extensions/config.ts

@@ -110,6 +110,7 @@ declare module "../../../../types/config.js" {
     blockGasLimit?: number | bigint | false;
     coinbase?: string;
     forking?: EdrNetworkForkingUserConfig;
+    gasEstimationMode?: "topLevelSuccess" | "noInternalOutOfGas";
     hardfork?: string;
     initialBaseFeePerGas?: number | bigint;
     initialDate?: string | Date;
@@ -253,6 +254,7 @@ declare module "../../../../types/config.js" {
     blockGasLimit?: bigint | false;
     coinbase: Uint8Array;
     forking?: EdrNetworkForkingConfig;
+    gasEstimationMode: "topLevelSuccess" | "noInternalOutOfGas";
     hardfork: string;
     initialBaseFeePerGas?: bigint;
     initialDate: string | Date;

package/src/internal/builtin-plugins/network-manager/type-validation.ts

@@ -319,6 +319,12 @@ const edrNetworkUserConfigSchema = z.object({
   blockGasLimit: z.optional(gasLimitWithDisableUserConfigSchema),
   coinbase: z.optional(z.string()),
   forking: z.optional(edrNetworkForkingUserConfigSchema),
+  gasEstimationMode: z.optional(
+    unionType(
+      [z.literal("topLevelSuccess"), z.literal("noInternalOutOfGas")],
+      "Expected 'topLevelSuccess' or 'noInternalOutOfGas'",
+    ),
+  ),
   hardfork: z.optional(z.string()),
   initialBaseFeePerGas: z.optional(gasUnitUserConfigSchema),
   initialDate: z.optional(

package/src/internal/builtin-plugins/node/json-rpc/handler.ts

@@ -256,6 +256,7 @@ const _handleError = (error: Error): JsonRpcResponse => {
   // that would be lost when wrapped in InternalError below.
   const txHash = extractTxHash(error);
   const returnData = extractReturnData(error);
+  const reason = extractErrorReason(error);
 
   // Check if this is a revert error (code 3) matching the geth/anvil convention.
   const isRevertError =
@@ -271,9 +272,12 @@ const _handleError = (error: Error): JsonRpcResponse => {
 
   // Revert errors (code 3): return raw hex to match the geth/anvil convention
   // that viem/ethers/web3.js rely on. Other errors keep the wrapper for diagnostics.
+  // `reason` is the discriminator clients use to recognize specific failures
+  // (e.g. "InternalCallOutOfGas") once the error class itself is lost to
+  // serialization, so it must survive it.
   const data: unknown = isRevertError
     ? returnData
-    : { message: error.message, txHash, data: returnData };
+    : { message: error.message, txHash, data: returnData, reason };
 
   const response: FailedJsonRpcResponse = {
     jsonrpc: "2.0",
@@ -318,3 +322,13 @@ function extractReturnData(error: Error): string | undefined {
     return error.data.data;
   }
 }
+
+function extractErrorReason(error: Error): string | undefined {
+  if (
+    "data" in error &&
+    isObject(error.data) &&
+    typeof error.data.reason === "string"
+  ) {
+    return error.data.reason;
+  }
+}

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

@@ -32,11 +32,23 @@ export function formatInlineConfigErrors(
         return `- ${sourceName}: ${formatInlineConfigSourceProblem(error.problem)}`;
       }
 
-      return `- ${sourceName}:${error.line}: ${error.contract}.${error.function}: ${formatInlineConfigDirectiveProblem(error.problem)}`;
+      return `- ${sourceName}:${error.line}: ${formatDirectiveOrigin(error.contract, error.function)}: ${formatInlineConfigDirectiveProblem(error.problem)}`;
     })
     .join("\n");
 }
 
+/**
+ * Names where a directive was found: `Contract.testFn` for a function-level
+ * directive, and just `Contract` for a contract-level one, which EDR reports
+ * without a function.
+ */
+function formatDirectiveOrigin(
+  contract: string,
+  functionName: string | undefined,
+): string {
+  return functionName === undefined ? contract : `${contract}.${functionName}`;
+}
+
 function formatInlineConfigDirectiveProblem(
   problem: InlineConfigDirectiveProblem,
 ): string {
@@ -65,6 +77,6 @@ function formatInlineConfigSourceProblem(
     case "InlineConfigSourceFileNotFound":
       return `the source file could not be read at "${problem.path}": ${problem.reason}`;
     case "InlineConfigDirectiveLocation":
-      return `a directive of ${problem.contract}.${problem.function} could not be located: ${problem.reason}`;
+      return `a directive of ${formatDirectiveOrigin(problem.contract, problem.function)} could not be located: ${problem.reason}`;
   }
 }

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

@@ -32,6 +32,13 @@ abstract class BaseResolvedConfigurationVariable implements ResolvedConfiguratio
 
   protected abstract _getRawValue(): Promise<string>;
 
+  /**
+   * A description of this variable, used to identify it in error messages.
+   *
+   * Resolved values may be secrets, so they must never be included in errors.
+   */
+  protected abstract _getDescription(): string;
+
   constructor(public readonly format: string) {
     assertHardhatInvariant(
       this.format.includes(CONFIGURATION_VARIABLE_MARKER),
@@ -57,9 +64,10 @@ abstract class BaseResolvedConfigurationVariable implements ResolvedConfiguratio
       new URL(value);
       return value;
     } catch (_error) {
-      throw new HardhatError(HardhatError.ERRORS.CORE.GENERAL.INVALID_URL, {
-        url: value,
-      });
+      throw new HardhatError(
+        HardhatError.ERRORS.CORE.GENERAL.INVALID_CONFIG_VARIABLE_URL,
+        { configVariable: this._getDescription() },
+      );
     }
   }
 
@@ -69,9 +77,10 @@ abstract class BaseResolvedConfigurationVariable implements ResolvedConfiguratio
     try {
       return BigInt(value);
     } catch (_error) {
-      throw new HardhatError(HardhatError.ERRORS.CORE.GENERAL.INVALID_BIGINT, {
-        value,
-      });
+      throw new HardhatError(
+        HardhatError.ERRORS.CORE.GENERAL.INVALID_CONFIG_VARIABLE_BIGINT,
+        { configVariable: this._getDescription() },
+      );
     }
   }
 
@@ -81,10 +90,8 @@ abstract class BaseResolvedConfigurationVariable implements ResolvedConfiguratio
       return normalizeHexString(value);
     } catch {
       throw new HardhatError(
-        HardhatError.ERRORS.CORE.GENERAL.INVALID_HEX_STRING,
-        {
-          value,
-        },
+        HardhatError.ERRORS.CORE.GENERAL.INVALID_CONFIG_VARIABLE_HEX_STRING,
+        { configVariable: this._getDescription() },
       );
     }
   }
@@ -112,6 +119,10 @@ export class LazyResolvedConfigurationVariable extends BaseResolvedConfiguration
     }
   }
 
+  protected _getDescription(): string {
+    return `the configuration variable "${this.name}"`;
+  }
+
   protected async _getRawValue(): Promise<string> {
     // Env vars take precedence over every configurationVariables plugin hook
     // (e.g. keystore). Skip the hook chain entirely when the env var is set so
@@ -157,6 +168,10 @@ export class FixedValueConfigurationVariable extends BaseResolvedConfigurationVa
     this.#value = value;
   }
 
+  protected _getDescription(): string {
+    return "an inline configuration value";
+  }
+
   protected async _getRawValue(): Promise<string> {
     return this.#value;
   }

package/src/internal/edr/exports.ts

@@ -0,0 +1 @@
+export { keccak256 } from "@nomicfoundation/edr";

package/templates/01-node-test-runner-viem/package.json

@@ -5,7 +5,7 @@
   "description": "A TypeScript Hardhat project using Node Test Runner and Viem",
   "type": "module",
   "devDependencies": {
-    "hardhat": "workspace:^3.16.0",
+    "hardhat": "workspace:^3.17.0",
     "@nomicfoundation/hardhat-toolbox-viem": "workspace:^5.0.7",
     "@nomicfoundation/hardhat-ignition": "workspace:^3.1.8",
     "@types/node": "^22.8.5",

package/templates/02-mocha-ethers/package.json

@@ -5,9 +5,9 @@
   "description": "A TypeScript Hardhat project using Mocha and Ethers.js",
   "type": "module",
   "devDependencies": {
-    "hardhat": "workspace:^3.16.0",
+    "hardhat": "workspace:^3.17.0",
     "@nomicfoundation/hardhat-toolbox-mocha-ethers": "workspace:^3.0.7",
-    "@nomicfoundation/hardhat-ethers": "workspace:^4.0.15",
+    "@nomicfoundation/hardhat-ethers": "workspace:^4.1.0",
     "@nomicfoundation/hardhat-ignition": "workspace:^3.1.8",
     "@types/chai": "^5.2.3",
     "@types/chai-as-promised": "^8.0.1",

package/templates/03-minimal/package.json

@@ -5,7 +5,7 @@
   "description": "A minimal Hardhat project",
   "type": "module",
   "devDependencies": {
-    "hardhat": "workspace:^3.16.0",
+    "hardhat": "workspace:^3.17.0",
     "@types/node": "^22.8.5",
     "typescript": "~6.0.3"
   }