hardhat 3.12.0 → 3.13.0

package/dist/src/types/config.d.ts

@@ -7,6 +7,17 @@ export interface ConfigurationVariable {
     _type: "ConfigurationVariable";
     name: string;
     format?: string;
+    /**
+     * An optional fallback value, used only when the variable can't be resolved
+     * from any other source (e.g. an environment variable or the keystore).
+     *
+     * By default, the value is resolved from the environment variable first, then
+     * any plugin source (like hardhat-keystore), and finally this default. Plugins
+     * can customize this, but the built-in resolver and bundled plugins follow this
+     * order. If none of them provide a value and no default is set, resolving the
+     * variable throws.
+     */
+    default?: string;
 }
 /**
  * A resolved configuration variable.

package/dist/src/types/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,qCAAqC,CAAC;AAE7C;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,uBAAuB,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,KAAK,EAAE,+BAA+B,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEvB;;;;;OAKG;IACH,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1B;;;;;OAKG;IACH,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE7B;;;;OAIG;IACH,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,MAAM,6BAA6B,GAAG,CAC1C,gBAAgB,EAAE,qBAAqB,GAAG,MAAM,KAC7C,6BAA6B,CAAC;AAEnC;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,qBAAqB,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,sBAAsB,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,qBAAqB,CAAC;CACrD;AAED;;GAEG;AAGH,MAAM,WAAW,mBAAmB;CAAG;AAEvC;;GAEG;AAGH,MAAM,WAAW,qBAAqB;CAAG;AAEzC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,kBAAkB,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED;;GAEG;AAGH,MAAM,WAAW,eAAe;CAAG;AAEnC;;GAEG;AAGH,MAAM,WAAW,iBAAiB;CAAG"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,qCAAqC,CAAC;AAE7C;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,uBAAuB,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,KAAK,EAAE,+BAA+B,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEvB;;;;;OAKG;IACH,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1B;;;;;OAKG;IACH,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE7B;;;;OAIG;IACH,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,MAAM,6BAA6B,GAAG,CAC1C,gBAAgB,EAAE,qBAAqB,GAAG,MAAM,KAC7C,6BAA6B,CAAC;AAEnC;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,qBAAqB,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,sBAAsB,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,qBAAqB,CAAC;CACrD;AAED;;GAEG;AAGH,MAAM,WAAW,mBAAmB;CAAG;AAEvC;;GAEG;AAGH,MAAM,WAAW,qBAAqB;CAAG;AAEzC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,kBAAkB,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED;;GAEG;AAGH,MAAM,WAAW,eAAe;CAAG;AAEnC;;GAEG;AAGH,MAAM,WAAW,iBAAiB;CAAG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hardhat",
-  "version": "3.12.0",
+  "version": "3.13.0",
   "description": "Hardhat is an extensible developer tool that helps smart contract developers increase productivity by reliably bringing together the tools they want.",
   "homepage": "https://hardhat.org",
   "repository": {

package/src/internal/builtin-plugins/gas-analytics/function-gas-snapshots.ts

@@ -17,7 +17,11 @@ import {
   parseFullyQualifiedName,
 } from "../../../utils/contract-names.js";
 
-import { formatSectionHeader, getUserFqn } from "./helpers/utils.js";
+import {
+  formatSectionHeader,
+  getUserFqn,
+  isWithinTolerance,
+} from "./helpers/utils.js";
 
 export const FUNCTION_GAS_SNAPSHOTS_FILE = ".gas-snapshot";
 
@@ -49,6 +53,10 @@ export interface FunctionGasSnapshotComparison {
   added: FunctionGasSnapshot[];
   removed: FunctionGasSnapshot[];
   changed: FunctionGasSnapshotChange[];
+  // Diffs within the allowed tolerance: they don't fail the check. They are
+  // included in the result for programmatic inspection, but are not shown in
+  // the default console output.
+  tolerated: FunctionGasSnapshotChange[];
 }
 
 export interface FunctionGasSnapshotChange {
@@ -242,6 +250,7 @@ export function parseFunctionGasSnapshots(
 export function compareFunctionGasSnapshots(
   previousSnapshots: FunctionGasSnapshot[],
   currentSnapshots: FunctionGasSnapshotWithMetadata[],
+  tolerance: number,
 ): FunctionGasSnapshotComparison {
   const previousSnapshotsMap = new Map(
     previousSnapshots.map((s) => [
@@ -252,6 +261,7 @@ export function compareFunctionGasSnapshots(
 
   const added: FunctionGasSnapshot[] = [];
   const changed: FunctionGasSnapshotChange[] = [];
+  const tolerated: FunctionGasSnapshotChange[] = [];
 
   for (const current of currentSnapshots) {
     const key = `${current.contractNameOrFqn}#${current.functionSig}`;
@@ -278,7 +288,7 @@ export function compareFunctionGasSnapshots(
           ? current.gasUsage.gas
           : current.gasUsage.medianGas;
 
-      changed.push({
+      const change: FunctionGasSnapshotChange = {
         contractNameOrFqn: current.contractNameOrFqn,
         functionSig: current.functionSig,
         kind: currentKind,
@@ -287,14 +297,23 @@ export function compareFunctionGasSnapshots(
         runs:
           currentKind === "fuzz" ? Number(current.gasUsage.runs) : undefined,
         source: current.metadata.source,
-      });
+      };
+
+      if (
+        tolerance > 0 &&
+        isWithinTolerance(change.expected, change.actual, tolerance)
+      ) {
+        tolerated.push(change);
+      } else {
+        changed.push(change);
+      }
     }
     previousSnapshotsMap.delete(key);
   }
 
   const removed = Array.from(previousSnapshotsMap.values());
 
-  return { added, removed, changed };
+  return { added, removed, changed, tolerated };
 }
 
 export function hasGasUsageChanged(
@@ -315,6 +334,7 @@ export function hasGasUsageChanged(
 export async function checkFunctionGasSnapshots(
   basePath: string,
   suiteResults: SuiteResult[],
+  tolerance: number,
 ): Promise<FunctionGasSnapshotCheckResult> {
   const functionGasSnapshots = extractFunctionGasSnapshots(suiteResults);
 
@@ -332,6 +352,7 @@ export async function checkFunctionGasSnapshots(
           added: [],
           removed: [],
           changed: [],
+          tolerated: [],
         },
         noBaseline,
       };
@@ -343,6 +364,7 @@ export async function checkFunctionGasSnapshots(
   const comparison = compareFunctionGasSnapshots(
     previousFunctionGasSnapshots,
     functionGasSnapshots,
+    tolerance,
   );
 
   return {

package/src/internal/builtin-plugins/gas-analytics/helpers/utils.ts

@@ -84,6 +84,21 @@ export function median(values: number[]): number {
     : (sorted[mid - 1] + sorted[mid]) / 2;
 }
 
+/**
+ * Whether `actual` drifted from `expected` by at most `tolerance` percent.
+ * Cross-multiplied instead of `(diff / expected) * 100 <= tolerance` to
+ * avoid floating-point errors from the division (e.g. `(49 / 700) * 100`
+ * is `7.000000000000001`, which would fail a tolerance of exactly 7).
+ */
+export function isWithinTolerance(
+  expected: number,
+  actual: number,
+  tolerance: number,
+): boolean {
+  const diff = Math.abs(actual - expected);
+  return diff * 100 <= tolerance * Math.abs(expected);
+}
+
 export function formatSectionHeader(
   sectionName: string,
   {

package/src/internal/builtin-plugins/gas-analytics/index.ts

@@ -19,6 +19,13 @@ const hardhatPlugin: HardhatPlugin = definePlugin({
         description:
           "Check the snapshots match the stored values (Solidity tests only)",
       })
+      .addOption({
+        name: "tolerance",
+        description:
+          "Allowed drift percentage for --snapshot-check (Solidity tests only)",
+        type: ArgumentType.FLOAT,
+        defaultValue: 0,
+      })
       .setAction(async () => ({
         default: async (args, _hre, runSuper) => {
           // We don't need to do anything here, as the test task will forward
@@ -36,6 +43,12 @@ const hardhatPlugin: HardhatPlugin = definePlugin({
         name: "snapshotCheck",
         description: "Check the snapshots match the stored values",
       })
+      .addOption({
+        name: "tolerance",
+        description: "Allowed drift percentage for --snapshot-check",
+        type: ArgumentType.FLOAT,
+        defaultValue: 0,
+      })
       .setAction(
         async () => await import("./tasks/solidity-test/task-action.js"),
       )

package/src/internal/builtin-plugins/gas-analytics/snapshot-cheatcodes.ts

@@ -20,7 +20,11 @@ import {
   parseFullyQualifiedName,
 } from "../../../utils/contract-names.js";
 
-import { formatSectionHeader, getUserFqn } from "./helpers/utils.js";
+import {
+  formatSectionHeader,
+  getUserFqn,
+  isWithinTolerance,
+} from "./helpers/utils.js";
 
 export const SNAPSHOT_CHEATCODES_DIR = "snapshots";
 
@@ -73,6 +77,10 @@ export interface SnapshotCheatcodesComparison {
   added: SnapshotCheatcode[];
   removed: SnapshotCheatcode[];
   changed: SnapshotCheatcodeChange[];
+  // Diffs within the allowed tolerance: they don't fail the check. They are
+  // included in the result for programmatic inspection, but are not shown in
+  // the default console output.
+  tolerated: SnapshotCheatcodeChange[];
 }
 
 export interface SnapshotCheatcodesCheckResult {
@@ -295,10 +303,12 @@ export function stringifySnapshotCheatcodes(
 export function compareSnapshotCheatcodes(
   previousSnapshotsMap: SnapshotCheatcodesMap,
   currentSnapshotsMap: SnapshotCheatcodesWithMetadataMap,
+  tolerance: number,
 ): SnapshotCheatcodesComparison {
   const added: SnapshotCheatcode[] = [];
   const removed: SnapshotCheatcode[] = [];
   const changed: SnapshotCheatcodeChange[] = [];
+  const tolerated: SnapshotCheatcodeChange[] = [];
   const seenPreviousEntries = new Set<string>();
 
   for (const [group, currentSnapshots] of currentSnapshotsMap) {
@@ -316,13 +326,27 @@ export function compareSnapshotCheatcodes(
         seenPreviousEntries.add(key);
         const previousValue = previousSnapshots[name];
         if (previousValue !== currentEntry.value) {
-          changed.push({
+          const change: SnapshotCheatcodeChange = {
             group,
             name,
             expected: Number(previousValue),
             actual: Number(currentEntry.value),
             source: currentEntry.metadata.source,
-          });
+          };
+
+          // The tolerance only applies when both values are strictly numeric;
+          // otherwise the exact string comparison stands. Snapshot cheatcode
+          // values can be arbitrary strings, unlike function gas snapshots.
+          if (
+            tolerance > 0 &&
+            isStrictlyNumeric(previousValue) &&
+            isStrictlyNumeric(currentEntry.value) &&
+            isWithinTolerance(change.expected, change.actual, tolerance)
+          ) {
+            tolerated.push(change);
+          } else {
+            changed.push(change);
+          }
         }
       }
     }
@@ -347,12 +371,21 @@ export function compareSnapshotCheatcodes(
     added: added.sort(sortByKey),
     removed: removed.sort(sortByKey),
     changed: changed.sort(sortByKey),
+    tolerated: tolerated.sort(sortByKey),
   };
 }
 
+// The emptiness check is needed because `Number("")` is `0`, so a bare
+// `Number.isFinite(Number(value))` would treat empty/whitespace values as
+// numeric.
+function isStrictlyNumeric(value: string): boolean {
+  return value.trim() !== "" && Number.isFinite(Number(value));
+}
+
 export async function checkSnapshotCheatcodes(
   basePath: string,
   suiteResults: SuiteResult[],
+  tolerance: number,
 ): Promise<SnapshotCheatcodesCheckResult> {
   const { snapshotCheatcodes, renamedGroups } = sanitizeSnapshotCheatcodes(
     extractSnapshotCheatcodes(suiteResults),
@@ -372,6 +405,7 @@ export async function checkSnapshotCheatcodes(
           added: [],
           removed: [],
           changed: [],
+          tolerated: [],
         },
         noBaseline,
         renamedGroups,
@@ -384,6 +418,7 @@ export async function checkSnapshotCheatcodes(
   const comparison = compareSnapshotCheatcodes(
     previousSnapshotCheatcodes,
     snapshotCheatcodes,
+    tolerance,
   );
 
   return {

package/src/internal/builtin-plugins/gas-analytics/tasks/solidity-test/task-action.ts

@@ -31,6 +31,7 @@ import {
 interface GasAnalyticsTestActionArguments {
   snapshot: boolean;
   snapshotCheck: boolean;
+  tolerance: number;
   // Forwarded from the base `test solidity` task; used to detect scoped runs.
   grep?: string;
   grepExclude?: string;
@@ -50,6 +51,30 @@ export interface SnapshotCheckResult {
 const runSolidityTests: TaskOverrideActionFunction<
   GasAnalyticsTestActionArguments
 > = async (args, hre, runSuper) => {
+  // Validate the flags before runSuper: it runs the entire test suite, and a
+  // usage error should fail immediately, not after a potentially long run.
+  if (args.snapshot && args.snapshotCheck) {
+    throw new HardhatError(
+      HardhatError.ERRORS.CORE.SOLIDITY_TESTS.MUTUALLY_EXCLUSIVE_SNAPSHOT_FLAGS,
+    );
+  }
+
+  // Unreachable from the CLI (the FLOAT parser rejects negative/non-numeric
+  // values), but programmatic `task.run({ tolerance })` only validates
+  // `typeof === "number"`.
+  if (args.tolerance < 0 || !Number.isFinite(args.tolerance)) {
+    throw new HardhatError(
+      HardhatError.ERRORS.CORE.SOLIDITY_TESTS.INVALID_SNAPSHOT_TOLERANCE,
+      { value: args.tolerance },
+    );
+  }
+
+  if (args.tolerance !== 0 && !args.snapshotCheck) {
+    throw new HardhatError(
+      HardhatError.ERRORS.CORE.SOLIDITY_TESTS.SNAPSHOT_TOLERANCE_REQUIRES_CHECK,
+    );
+  }
+
   const superResult: Result<SolidityTestRunResult, SolidityTestRunResult> =
     await runSuper(args);
   const testsPassed = superResult.success;
@@ -59,12 +84,6 @@ const runSolidityTests: TaskOverrideActionFunction<
   const suiteResults = solidityTestRunResult.suiteResults;
   const rootPath = hre.config.paths.root;
 
-  if (args.snapshot && args.snapshotCheck) {
-    throw new HardhatError(
-      HardhatError.ERRORS.CORE.SOLIDITY_TESTS.MUTUALLY_EXCLUSIVE_SNAPSHOT_FLAGS,
-    );
-  }
-
   let snapshotCheckPassed = true;
   if (args.snapshot) {
     const snapshotResult = await handleSnapshot(
@@ -77,6 +96,7 @@ const runSolidityTests: TaskOverrideActionFunction<
     const snapshotCheckResult = await handleSnapshotCheck(
       rootPath,
       suiteResults,
+      args.tolerance,
     );
     logSnapshotCheckResult(
       snapshotCheckResult,
@@ -156,14 +176,17 @@ export function logSnapshotResult(
 export async function handleSnapshotCheck(
   basePath: string,
   suiteResults: SuiteResult[],
+  tolerance: number,
 ): Promise<SnapshotCheckResult> {
   const functionGasSnapshotsCheck = await checkFunctionGasSnapshots(
     basePath,
     suiteResults,
+    tolerance,
   );
   const snapshotCheatcodesCheck = await checkSnapshotCheatcodes(
     basePath,
     suiteResults,
+    tolerance,
   );
 
   return {

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

@@ -426,7 +426,11 @@ function refineEdrNetworkUserConfig(
       }
 
       const interval = network.mining?.interval;
-      if (typeof interval === "number" || Array.isArray(interval)) {
+      // A scalar `interval: 0` disables interval mining entirely, so this validation is not appropriate
+      if (
+        (typeof interval === "number" && interval !== 0) ||
+        Array.isArray(interval)
+      ) {
         const minInterval =
           typeof interval === "number" ? interval : Math.min(...interval);
         if (

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

@@ -22,7 +22,10 @@ import {
 import { toBigInt } from "@nomicfoundation/hardhat-utils/bigint";
 import { hexStringToBytes } from "@nomicfoundation/hardhat-utils/hex";
 
-import { DEFAULT_VERBOSITY, OPTIMISM_CHAIN_TYPE } from "../../constants.js";
+import {
+  ALWAYS_COLLECT_STACK_TRACES_VERBOSITY,
+  OPTIMISM_CHAIN_TYPE,
+} from "../../constants.js";
 import { resolveHardfork } from "../network-manager/config-resolution.js";
 import { hardhatHardforkToEdrSpecId } from "../network-manager/edr/utils/convert-to-edr.js";
 import { warnIfExperimentalHardfork } from "../network-manager/edr/utils/hardfork.js";
@@ -139,7 +142,8 @@ export async function solidityTestConfigToSolidityTestRunnerConfigArgs({
     }
   }
 
-  const shouldAlwaysCollectStackTraces = verbosity > DEFAULT_VERBOSITY;
+  const shouldAlwaysCollectStackTraces =
+    verbosity >= ALWAYS_COLLECT_STACK_TRACES_VERBOSITY;
 
   return {
     projectRoot,

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

@@ -10,6 +10,7 @@ import { styleText } from "node:util";
 import { bytesToHexString } from "@nomicfoundation/hardhat-utils/hex";
 
 import { sendErrorTelemetry } from "../../cli/telemetry/error-reporter/reporter.js";
+import { ALWAYS_COLLECT_STACK_TRACES_VERBOSITY } from "../../constants.js";
 import { SolidityTestStackTraceGenerationError } from "../network-manager/edr/stack-traces/stack-trace-generation-errors.js";
 import { encodeStackTraceEntry } from "../network-manager/edr/stack-traces/stack-trace-solidity-errors.js";
 import { formatTraces } from "../network-manager/edr/utils/trace-formatters.js";
@@ -17,6 +18,8 @@ import { formatTraces } from "../network-manager/edr/utils/trace-formatters.js";
 import { formatArtifactId } from "./formatters.js";
 import { getMessageFromLastStackTraceEntry } from "./stack-trace-solidity-errors.js";
 
+const RERUN_VERBOSITY_HINT = `Try rerunning your tests with -${"v".repeat(ALWAYS_COLLECT_STACK_TRACES_VERBOSITY)} or above.`;
+
 class Indenter {
   #indentation: number;
 
@@ -305,17 +308,13 @@ export async function* testReporter(
             yield* output(
               indenter.t`Stack Trace Warning: ${colorize("grey", "The test is not safe to replay because a fork url without a fork block number was provided.")}\n`,
             );
-            yield* output(
-              indenter.t`Try rerunning your tests with -vvv or above.\n`,
-            );
+            yield* output(indenter.t`${RERUN_VERBOSITY_HINT}\n`);
           }
           if (stackTrace.impureCheatcodes.length > 0) {
             yield* output(
               indenter.t`Stack Trace Warning: ${colorize("grey", `The test is not safe to replay because it uses impure cheatcodes: ${stackTrace.impureCheatcodes.join(", ")}`)}\n`,
             );
-            yield* output(
-              indenter.t`Try rerunning your tests with -vvv or above.\n`,
-            );
+            yield* output(indenter.t`${RERUN_VERBOSITY_HINT}\n`);
           }
           break;
         case "HeuristicFailed":

package/src/internal/cli/{error-handler.ts → error-handling/error-handler.ts}

@@ -1,4 +1,4 @@
-import type * as ClassifierT from "./telemetry/error-classification/classifier.js";
+import type * as ClassifierT from "../telemetry/error-classification/classifier.js";
 
 import { styleText } from "node:util";
 
@@ -7,7 +7,9 @@ import {
   HardhatPluginError,
 } from "@nomicfoundation/hardhat-errors";
 
-import { HARDHAT_NAME, HARDHAT_WEBSITE_URL } from "../constants.js";
+import { HARDHAT_NAME, HARDHAT_WEBSITE_URL } from "../../constants.js";
+
+import { detectNativeBindingFailure } from "./native-binding-error.js";
 
 // The classifier may import many unrelated things top-level to do its job, so
 // we load it lazily.
@@ -165,9 +167,24 @@ async function getErrorWithCategory(error: Error): Promise<ErrorWithCategory> {
     };
   }
 
+  const nativeBindingFailure = detectNativeBindingFailure(error);
+  if (nativeBindingFailure !== undefined) {
+    return {
+      category: ErrorCategory.HARDHAT,
+      categorizedError: new HardhatError(
+        HardhatError.ERRORS.CORE.GENERAL.NATIVE_BINDING_LOAD_FAILED,
+        {
+          parentPackage: nativeBindingFailure.parentPackage,
+          missingPackage: nativeBindingFailure.missingPackage,
+        },
+        error,
+      ),
+    };
+  }
+
   if (classifierModule === undefined) {
     classifierModule =
-      await import("./telemetry/error-classification/classifier.js");
+      await import("../telemetry/error-classification/classifier.js");
   }
 
   // Pass `ignoreDevelopmentTimeFilter=true` so the migration footer also shows

package/src/internal/cli/error-handling/native-binding-error.ts

@@ -0,0 +1,78 @@
+/**
+ * The platform triple that napi-rs appends to the platform package name, e.g.
+ * `@nomicfoundation/edr-linux-x64-gnu`, `@scope/pkg-darwin-arm64`.
+ */
+const PLATFORM_SUFFIX_REGEX =
+  /-(?:android|darwin|freebsd|linux|win32)-(?:arm|arm64|ia32|x64|riscv64|ppc64|s390x)(?:-(?:gnu|musl|msvc|eabi|gnueabihf))?$/;
+
+/**
+ * Matches both the CJS (`Cannot find module 'x'`) and ESM
+ * (`Cannot find package 'x' imported from y`) forms.
+ */
+const MISSING_MODULE_REGEX = /Cannot find (?:module|package) '([^']+)'/g;
+
+/**
+ * The packages Hardhat itself ships a native binding for.
+ */
+const HARDHAT_NATIVE_BINDING_PACKAGES = [
+  "@nomicfoundation/edr",
+  "@nomicfoundation/solidity-analyzer",
+];
+
+export interface NativeBindingFailure {
+  /** The package whose loader failed, e.g. `@nomicfoundation/edr`. */
+  parentPackage: string;
+  /** The platform package that couldn't be found. */
+  missingPackage: string;
+}
+
+/**
+ * Detect whether a given error is a napi-rs native binding load failure.
+ *
+ * Packages like `@nomicfoundation/edr` and `@nomicfoundation/solidity-analyzer`
+ * ship one prebuilt binary per platform in a separate package, and their
+ * generated loader `require`s the one matching the current platform. When that
+ * package is missing from the installation the loader throws at import time, so
+ * the failure surfaces as an opaque `MODULE_NOT_FOUND` from deep inside
+ * `node_modules`.
+ */
+export function detectNativeBindingFailure(
+  error: Error,
+): NativeBindingFailure | undefined {
+  const chain = errorChain(error);
+
+  // Some link in the chain names the missing platform package.
+  for (const chainedError of chain) {
+    for (const match of chainedError.message.matchAll(MISSING_MODULE_REGEX)) {
+      const moduleName = match[1];
+
+      if (!PLATFORM_SUFFIX_REGEX.test(moduleName)) {
+        continue;
+      }
+
+      const parentPackage = moduleName.replace(PLATFORM_SUFFIX_REGEX, "");
+
+      if (!HARDHAT_NATIVE_BINDING_PACKAGES.includes(parentPackage)) {
+        continue;
+      }
+
+      return { missingPackage: moduleName, parentPackage };
+    }
+  }
+
+  return undefined;
+}
+
+function errorChain(error: Error): Error[] {
+  const chain: Error[] = [];
+  const seen = new Set<unknown>();
+  let current: unknown = error;
+
+  while (current instanceof Error && !seen.has(current)) {
+    seen.add(current);
+    chain.push(current);
+    current = current.cause;
+  }
+
+  return chain;
+}

package/src/internal/cli/hhu.ts

@@ -19,7 +19,7 @@ import { globalFlag } from "../core/config.js";
 import { TaskManagerImplementation } from "../core/tasks/task-manager.js";
 import { getHardhatVersion } from "../utils/package.js";
 
-import { printErrorMessages } from "./error-handler.js";
+import { printErrorMessages } from "./error-handling/error-handler.js";
 import { getGlobalHelpString } from "./help/get-global-help-string.js";
 import { getHelpString } from "./help/get-help-string.js";
 import {

package/src/internal/cli/main.ts

@@ -28,7 +28,7 @@ import { warnAboutUnusedLoadedPlugins } from "../core/plugins/unused-plugins-war
 import { setGlobalHardhatRuntimeEnvironment } from "../global-hre-instance.js";
 import { createHardhatRuntimeEnvironment } from "../hre-initialization.js";
 
-import { printErrorMessages } from "./error-handler.js";
+import { printErrorMessages } from "./error-handling/error-handler.js";
 import { getGlobalHelpString } from "./help/get-global-help-string.js";
 import { getHelpString } from "./help/get-help-string.js";
 import {

package/src/internal/constants.ts

@@ -11,3 +11,14 @@ export const OPTIMISM_CHAIN_TYPE = "op";
 export const DEFAULT_NETWORK_NAME = "default";
 
 export const DEFAULT_VERBOSITY = 2;
+
+/**
+ * The verbosity level (`-vvvvv`) at and above which stack traces are always
+ * collected. Below it, stack traces are produced by re-running the failing
+ * test with tracing enabled — much cheaper, but tests with non-deterministic
+ * side effects (impure cheatcodes, a fork pinned to `latest`) can't be
+ * replayed and report an `UnsafeToReplay` warning instead. Always-on
+ * collection records step traces for every test, which balloons memory on
+ * large suites, so it's reserved for the highest verbosity.
+ */
+export const ALWAYS_COLLECT_STACK_TRACES_VERBOSITY = 5;

package/src/internal/core/config.ts

@@ -23,11 +23,33 @@ import {
 
 /**
  * Creates a configuration variable, which will be fetched at runtime.
+ *
+ * The second argument is an options object with an optional `format` (a
+ * template that must include the `{variable}` marker) and an optional
+ * `default` value. The default is used as a fallback when the variable can't
+ * be resolved from any other source (see {@link ConfigurationVariable.default}).
  */
 export function configVariable(
   name: string,
-  format: string = CONFIGURATION_VARIABLE_MARKER,
+  options?: { format?: string; default?: string },
+): ConfigurationVariable;
+/**
+ * @deprecated Passing the `format` as a string is deprecated. Pass an options
+ * object instead: `configVariable(name, { format })`.
+ */
+export function configVariable(
+  name: string,
+  format: string,
+): ConfigurationVariable;
+export function configVariable(
+  name: string,
+  formatOrOptions: string | { format?: string; default?: string } = {},
 ): ConfigurationVariable {
+  const { format = CONFIGURATION_VARIABLE_MARKER, default: defaultValue } =
+    typeof formatOrOptions === "string"
+      ? { format: formatOrOptions }
+      : formatOrOptions;
+
   if (!format.includes(CONFIGURATION_VARIABLE_MARKER)) {
     throw new HardhatError(
       HardhatError.ERRORS.CORE.GENERAL
@@ -35,7 +57,18 @@ export function configVariable(
       { format, marker: CONFIGURATION_VARIABLE_MARKER },
     );
   }
-  return { _type: "ConfigurationVariable", name, format };
+
+  const configurationVariable: ConfigurationVariable = {
+    _type: "ConfigurationVariable",
+    name,
+    format,
+  };
+
+  if (defaultValue !== undefined) {
+    configurationVariable.default = defaultValue;
+  }
+
+  return configurationVariable;
 }
 
 /**

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

@@ -131,7 +131,9 @@ export class LazyResolvedConfigurationVariable extends BaseResolvedConfiguration
           "fetchValue",
           [this.#variable],
           async (_context, v) => {
-            const value = process.env[v.name];
+            // Fall back to the default only when the env var is unset. An empty
+            // string still takes precedence
+            const value = process.env[v.name] ?? v.default;
 
             if (typeof value !== "string") {
               throw new HardhatError(