hardhat 3.3.0 → 3.4.1

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

@@ -1,5 +1,6 @@
 import type {
   ContractGasStatsJson,
+  DeploymentGasStatsJsonEntry,
   GasAnalyticsManager,
   GasMeasurement,
   GasStatsJson,
@@ -10,7 +11,10 @@ import type { TableItem } from "@nomicfoundation/hardhat-utils/format";
 import crypto from "node:crypto";
 import path from "node:path";
 
-import { HardhatError } from "@nomicfoundation/hardhat-errors";
+import {
+  HardhatError,
+  assertHardhatInvariant,
+} from "@nomicfoundation/hardhat-errors";
 import { formatTable } from "@nomicfoundation/hardhat-utils/format";
 import {
   ensureDir,
@@ -27,12 +31,27 @@ import debug from "debug";
 
 import { parseFullyQualifiedName } from "../../../utils/contract-names.js";
 
+import {
+  avg,
+  getDisplayKey,
+  getFunctionName,
+  getProxyLabel,
+  getUserFqn,
+  makeGroupKey,
+  median,
+} from "./helpers/utils.js";
+
 const gasStatsLog = debug(
   "hardhat:core:gas-analytics:gas-analytics-manager:gas-stats",
 );
 
+interface DeploymentGasStats extends GasStats {
+  runtimeSize: number;
+}
+
 interface ContractGasStats {
-  deployment?: GasStats;
+  proxyChain: string[];
+  deployment?: DeploymentGasStats;
   functions: Map<
     string, // function name or signature (if overloaded)
     GasStats
@@ -52,7 +71,9 @@ interface GasStats {
 type GasMeasurementsByContract = Map<string, ContractGasMeasurements>;
 
 interface ContractGasMeasurements {
+  proxyChain: string[];
   deployments: number[];
+  deploymentRuntimeSize?: number;
   functions: Map<
     string, // functionSig
     number[]
@@ -170,18 +191,25 @@ export class GasAnalyticsManagerImplementation implements GasAnalyticsManager {
     const gasStatsByContract: GasStatsByContract = new Map();
     const measurementsByContract = this._aggregateGasMeasurements();
 
-    for (const [contractFqn, measurements] of measurementsByContract) {
+    for (const [groupKey, measurements] of measurementsByContract) {
       const contractGasStats: ContractGasStats = {
+        proxyChain: measurements.proxyChain,
         functions: new Map(),
       };
 
       if (measurements.deployments.length > 0) {
+        assertHardhatInvariant(
+          measurements.deploymentRuntimeSize !== undefined,
+          "deploymentRuntimeSize must be set when deployments exist",
+        );
+
         contractGasStats.deployment = {
           min: Math.min(...measurements.deployments),
           max: Math.max(...measurements.deployments),
           avg: Math.round(avg(measurements.deployments)),
           median: Math.round(median(measurements.deployments)),
           count: measurements.deployments.length,
+          runtimeSize: measurements.deploymentRuntimeSize,
         };
       }
 
@@ -207,7 +235,20 @@ export class GasAnalyticsManagerImplementation implements GasAnalyticsManager {
         );
       }
 
-      gasStatsByContract.set(contractFqn, contractGasStats);
+      gasStatsByContract.set(groupKey, contractGasStats);
+    }
+
+    // Duplicate deployment stats from direct-call groups to proxied groups
+    for (const [groupKey, stats] of gasStatsByContract) {
+      if (stats.proxyChain.length > 0 && stats.deployment === undefined) {
+        // Extract contractFqn from the groupKey (everything before the first \0)
+        const contractFqn = groupKey.split("\0")[0];
+        const directKey = makeGroupKey(contractFqn, []);
+        const directStats = gasStatsByContract.get(directKey);
+        if (directStats?.deployment !== undefined) {
+          stats.deployment = directStats.deployment;
+        }
+      }
     }
 
     return gasStatsByContract;
@@ -220,22 +261,28 @@ export class GasAnalyticsManagerImplementation implements GasAnalyticsManager {
     const measurementsByContract: GasMeasurementsByContract = new Map();
 
     for (const currentMeasurement of this.gasMeasurements) {
-      let contractMeasurements = measurementsByContract.get(
-        currentMeasurement.contractFqn,
-      );
+      const proxyChain =
+        currentMeasurement.type === "function"
+          ? currentMeasurement.proxyChain
+          : [];
+      const groupKey = makeGroupKey(currentMeasurement.contractFqn, proxyChain);
+
+      let contractMeasurements = measurementsByContract.get(groupKey);
       if (contractMeasurements === undefined) {
         contractMeasurements = {
+          proxyChain,
           deployments: [],
           functions: new Map(),
         };
-        measurementsByContract.set(
-          currentMeasurement.contractFqn,
-          contractMeasurements,
-        );
+        measurementsByContract.set(groupKey, contractMeasurements);
       }
 
       if (currentMeasurement.type === "deployment") {
         contractMeasurements.deployments.push(currentMeasurement.gas);
+        if (contractMeasurements.deploymentRuntimeSize === undefined) {
+          contractMeasurements.deploymentRuntimeSize =
+            currentMeasurement.runtimeSize;
+        }
       } else {
         let measurements = contractMeasurements.functions.get(
           currentMeasurement.functionSig,
@@ -267,15 +314,16 @@ export class GasAnalyticsManagerImplementation implements GasAnalyticsManager {
       rows.push({ type: "title", text: chalk.bold("Gas Usage Statistics") });
     }
 
-    // Sort contracts alphabetically for consistent output
-    const sortedContracts = [...gasStatsByContract.entries()].sort(([a], [b]) =>
-      a.localeCompare(b),
-    );
-
-    for (const [contractFqn, contractGasStats] of sortedContracts) {
+    const sortedContracts = getSortedContractEntries(gasStatsByContract);
+    for (const {
+      userFqn,
+      proxyLabel,
+      stats: contractGasStats,
+    } of sortedContracts) {
       rows.push({
         type: "section-header",
-        text: chalk.cyan.bold(getUserFqn(contractFqn)),
+        text: chalk.cyan.bold(userFqn),
+        subtitle: proxyLabel !== undefined ? chalk.cyan(proxyLabel) : undefined,
       });
 
       if (contractGasStats.functions.size > 0) {
@@ -337,6 +385,13 @@ export class GasAnalyticsManagerImplementation implements GasAnalyticsManager {
             `${contractGasStats.deployment.count}`,
           ],
         });
+        rows.push({
+          type: "header",
+          cells: [
+            chalk.yellow("Bytecode size"),
+            `${contractGasStats.deployment.runtimeSize}`,
+          ],
+        });
       }
     }
 
@@ -349,19 +404,13 @@ export class GasAnalyticsManagerImplementation implements GasAnalyticsManager {
   public _generateGasStatsJson(
     gasStatsByContract: GasStatsByContract,
   ): GasStatsJson {
-    const sortedContracts = [...gasStatsByContract.entries()]
-      .map(([internalFqn, stats]) => ({
-        userFqn: getUserFqn(internalFqn),
-        stats,
-      }))
-      .sort((a, b) => a.userFqn.localeCompare(b.userFqn));
-
+    const sortedContracts = getSortedContractEntries(gasStatsByContract);
     const contracts: Record<string, ContractGasStatsJson> = {};
 
-    for (const { userFqn, stats } of sortedContracts) {
+    for (const { userFqn, displayKey, stats } of sortedContracts) {
       const { sourceName, contractName } = parseFullyQualifiedName(userFqn);
 
-      const deployment: GasStatsJsonEntry | null =
+      const deployment: DeploymentGasStatsJsonEntry | null =
         stats.deployment !== undefined ? { ...stats.deployment } : null;
 
       let functions: Record<string, GasStatsJsonEntry> | null = null;
@@ -377,44 +426,34 @@ export class GasAnalyticsManagerImplementation implements GasAnalyticsManager {
         functions = Object.fromEntries(sortedFunctions);
       }
 
-      contracts[userFqn] = { sourceName, contractName, deployment, functions };
+      contracts[displayKey] = {
+        sourceName,
+        contractName,
+        proxyChain: stats.proxyChain.map(getUserFqn),
+        deployment,
+        functions,
+      };
     }
 
     return { contracts };
   }
 }
 
-export function avg(values: number[]): number {
-  return values.reduce((a, c) => a + c, 0) / values.length;
-}
-
-export function median(values: number[]): number {
-  const sorted = [...values].sort((a, b) => a - b);
-  const mid = Math.floor(sorted.length / 2);
-
-  return sorted.length % 2 === 1
-    ? sorted[mid]
-    : (sorted[mid - 1] + sorted[mid]) / 2;
-}
-
-export function getUserFqn(inputFqn: string): string {
-  if (inputFqn.startsWith("project/")) {
-    return inputFqn.slice("project/".length);
-  }
-
-  if (inputFqn.startsWith("npm/")) {
-    const withoutPrefix = inputFqn.slice("npm/".length);
-    // Match "<pkg>@<version>/<rest>", where <pkg> may be scoped (@scope/pkg)
-    const match = withoutPrefix.match(/^(@?[^@/]+(?:\/[^@/]+)*)@[^/]+\/(.*)$/);
-    if (match !== null) {
-      return `${match[1]}/${match[2]}`;
-    }
-    return withoutPrefix;
-  }
-
-  return inputFqn;
-}
-
-export function getFunctionName(signature: string): string {
-  return signature.split("(")[0];
+function getSortedContractEntries(
+  gasStatsByContract: GasStatsByContract,
+): Array<{
+  userFqn: string;
+  displayKey: string;
+  proxyLabel: string | undefined;
+  stats: ContractGasStats;
+}> {
+  return [...gasStatsByContract.entries()]
+    .map(([groupKey, stats]) => {
+      const contractFqn = groupKey.split("\0")[0];
+      const userFqn = getUserFqn(contractFqn);
+      const displayKey = getDisplayKey(userFqn, stats.proxyChain);
+      const proxyLabel = getProxyLabel(stats.proxyChain);
+      return { userFqn, displayKey, proxyLabel, stats };
+    })
+    .sort((a, b) => a.displayKey.localeCompare(b.displayKey));
 }

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

@@ -0,0 +1,31 @@
+import type { HookContext } from "../../../../types/hooks.js";
+import type { HardhatRuntimeEnvironment } from "../../../../types/hre.js";
+import type { GasAnalyticsManager } from "../types.js";
+
+import { assertHardhatInvariant } from "@nomicfoundation/hardhat-errors";
+
+import { HardhatRuntimeEnvironmentImplementation } from "../../../core/hre.js";
+import { GasAnalyticsManagerImplementation } from "../gas-analytics-manager.js";
+
+export function getGasAnalyticsManager(
+  hookContextOrHre: HookContext | HardhatRuntimeEnvironment,
+): GasAnalyticsManager {
+  assertHardhatInvariant(
+    "_gasAnalytics" in hookContextOrHre &&
+      hookContextOrHre._gasAnalytics instanceof
+        GasAnalyticsManagerImplementation,
+    "Expected _gasAnalytics to be an instance of GasAnalyticsManagerImplementation",
+  );
+  return hookContextOrHre._gasAnalytics;
+}
+
+export function setGasAnalyticsManager(
+  hre: HardhatRuntimeEnvironment,
+  gasAnalyticsManager: GasAnalyticsManager,
+): void {
+  assertHardhatInvariant(
+    hre instanceof HardhatRuntimeEnvironmentImplementation,
+    "Expected HRE to be an instance of HardhatRuntimeEnvironmentImplementation",
+  );
+  hre._gasAnalytics = gasAnalyticsManager;
+}

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

@@ -0,0 +1,37 @@
+import type { HardhatRuntimeEnvironment } from "../../../../types/hre.js";
+
+import {
+  testRunDone,
+  testRunStart,
+  testWorkerDone,
+} from "../hook-handlers/test.js";
+
+/**
+ * The following helpers are kept for backward compatibility with older versions
+ * of test runner plugins (hardhat-mocha, hardhat-node-test-runner) that import
+ * from "hardhat/internal/gas-analytics".
+ */
+
+let cachedHre: HardhatRuntimeEnvironment | undefined;
+async function getHre(): Promise<HardhatRuntimeEnvironment> {
+  if (cachedHre === undefined) {
+    const { default: hre } = await import("../../../../index.js");
+    cachedHre = hre;
+  }
+  return cachedHre;
+}
+
+export async function markTestRunStart(id: string): Promise<void> {
+  const hre = await getHre();
+  await testRunStart(hre, id);
+}
+
+export async function markTestWorkerDone(id: string): Promise<void> {
+  const hre = await getHre();
+  await testWorkerDone(hre, id);
+}
+
+export async function markTestRunDone(id: string): Promise<void> {
+  const hre = await getHre();
+  await testRunDone(hre, id);
+}

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

@@ -0,0 +1,112 @@
+import chalk from "chalk";
+
+/**
+ * Converts an internal FQN (e.g. `"project/contracts/Foo.sol:Foo"` or
+ * `"npm/@oz/contracts@5.0.0/token/ERC20.sol:ERC20"`) to its user-friendly
+ * form by stripping the `project/` prefix or npm version segment.
+ */
+export function getUserFqn(inputFqn: string): string {
+  if (inputFqn.startsWith("project/")) {
+    return inputFqn.slice("project/".length);
+  }
+
+  if (inputFqn.startsWith("npm/")) {
+    const withoutPrefix = inputFqn.slice("npm/".length);
+    // Match "<pkg>@<version>/<rest>", where <pkg> may be scoped (@scope/pkg)
+    const match = withoutPrefix.match(/^(@?[^@/]+(?:\/[^@/]+)*)@[^/]+\/(.*)$/);
+    if (match !== null) {
+      return `${match[1]}/${match[2]}`;
+    }
+    return withoutPrefix;
+  }
+
+  return inputFqn;
+}
+
+/**
+ * Extracts the function name from a Solidity function signature
+ * (e.g. `"transfer(address,uint256)"` → `"transfer"`).
+ */
+export function getFunctionName(signature: string): string {
+  return signature.split("(")[0];
+}
+
+/**
+ * Builds a deterministic string key for grouping gas measurements by
+ * (contractFqn, proxyChain). Uses null-byte separators to avoid collisions.
+ */
+export function makeGroupKey(
+  contractFqn: string,
+  proxyChain: string[],
+): string {
+  if (proxyChain.length === 0) {
+    return contractFqn;
+  }
+  return contractFqn + "\0" + proxyChain.join("\0");
+}
+
+/**
+ * Returns a human-readable proxy label like `"(via Proxy2 → Proxy)"`,
+ * or `undefined` for direct calls. Strips the last element (the
+ * implementation) and converts internal FQNs to user-friendly format.
+ */
+export function getProxyLabel(proxyChain: string[]): string | undefined {
+  const proxies = proxyChain.slice(0, -1).map(getUserFqn);
+  if (proxies.length === 0) {
+    return undefined;
+  }
+  return `(via ${proxies.join(" → ")})`;
+}
+
+/**
+ * Returns a display key for a contract entry, appending the proxy label
+ * when the call went through a proxy chain. Used for table headers and
+ * JSON object keys.
+ */
+export function getDisplayKey(userFqn: string, proxyChain: string[]): string {
+  const label = getProxyLabel(proxyChain);
+  if (label === undefined) {
+    return userFqn;
+  }
+  return `${userFqn} ${label}`;
+}
+
+export function avg(values: number[]): number {
+  return values.reduce((a, c) => a + c, 0) / values.length;
+}
+
+export function median(values: number[]): number {
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+
+  return sorted.length % 2 === 1
+    ? sorted[mid]
+    : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+export function formatSectionHeader(
+  sectionName: string,
+  {
+    changedLength,
+    addedLength,
+    removedLength,
+  }: {
+    changedLength: number;
+    addedLength: number;
+    removedLength: number;
+  },
+): string {
+  const parts: string[] = [];
+
+  if (changedLength > 0) {
+    parts.push(`${changedLength} changed`);
+  }
+  if (addedLength > 0) {
+    parts.push(`${addedLength} added`);
+  }
+  if (removedLength > 0) {
+    parts.push(`${removedLength} removed`);
+  }
+
+  return `${sectionName}: ${chalk.gray(parts.join(", "))}`;
+}

package/src/internal/builtin-plugins/gas-analytics/hook-handlers/hre.ts

@@ -1,7 +1,7 @@
 import type { HardhatRuntimeEnvironmentHooks } from "../../../../types/hooks.js";
 
 import { GasAnalyticsManagerImplementation } from "../gas-analytics-manager.js";
-import { setGasAnalyticsManager } from "../helpers.js";
+import { setGasAnalyticsManager } from "../helpers/accessors.js";
 
 export default async (): Promise<Partial<HardhatRuntimeEnvironmentHooks>> => ({
   created: async (context, hre) => {

package/src/internal/builtin-plugins/gas-analytics/hook-handlers/test.ts

@@ -1,6 +1,6 @@
 import type { HookContext, TestHooks } from "../../../../types/hooks.js";
 
-import { getGasAnalyticsManager } from "../helpers.js";
+import { getGasAnalyticsManager } from "../helpers/accessors.js";
 
 export default async (): Promise<Partial<TestHooks>> => ({
   onTestRunStart: async (context, id, next) => {

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

@@ -22,7 +22,7 @@ const hardhatPlugin: HardhatPlugin = {
         default: async (args, _hre, runSuper) => {
           // We don't need to do anything here, as the test task will forward
           // the arguments to its subtasks.
-          return runSuper(args);
+          return await runSuper(args);
         },
       }))
       .build(),
@@ -35,7 +35,9 @@ const hardhatPlugin: HardhatPlugin = {
         name: "snapshotCheck",
         description: "Check the snapshots match the stored values",
       })
-      .setAction(async () => import("./tasks/solidity-test/task-action.js"))
+      .setAction(
+        async () => await import("./tasks/solidity-test/task-action.js"),
+      )
       .build(),
   ],
   globalOptions: [

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

@@ -18,8 +18,7 @@ import {
   parseFullyQualifiedName,
 } from "../../../utils/contract-names.js";
 
-import { getUserFqn } from "./gas-analytics-manager.js";
-import { formatSectionHeader } from "./helpers.js";
+import { formatSectionHeader, getUserFqn } from "./helpers/utils.js";
 
 export const SNAPSHOT_CHEATCODES_DIR = "snapshots";
 

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

@@ -9,6 +9,13 @@ export interface GasStatsJsonEntry {
   count: number;
 }
 
+/**
+ * Gas statistics for a deployment, including bytecode size.
+ */
+export interface DeploymentGasStatsJsonEntry extends GasStatsJsonEntry {
+  runtimeSize: number;
+}
+
 /**
  * Gas statistics for a single contract in the JSON output.
  * `deployment` is null when the contract was never deployed during the test run
@@ -18,7 +25,8 @@ export interface GasStatsJsonEntry {
 export interface ContractGasStatsJson {
   sourceName: string;
   contractName: string;
-  deployment: GasStatsJsonEntry | null;
+  proxyChain: string[];
+  deployment: DeploymentGasStatsJsonEntry | null;
   functions: Record<string, GasStatsJsonEntry> | null;
 }
 
@@ -39,11 +47,12 @@ interface BaseGasMeasurement {
 interface FunctionGasMeasurement extends BaseGasMeasurement {
   type: "function";
   functionSig: string;
+  proxyChain: string[];
 }
 
 interface DeploymentGasMeasurement extends BaseGasMeasurement {
   type: "deployment";
-  size: number;
+  runtimeSize: number;
 }
 
 export type GasMeasurement = FunctionGasMeasurement | DeploymentGasMeasurement;

package/src/internal/builtin-plugins/network-manager/edr/edr-provider.ts

@@ -36,7 +36,7 @@ import { numberToHexString } from "@nomicfoundation/hardhat-utils/hex";
 import { deepEqual } from "@nomicfoundation/hardhat-utils/lang";
 import debug from "debug";
 
-import { sendErrorTelemetry } from "../../../cli/telemetry/sentry/reporter.js";
+import { sendErrorTelemetry } from "../../../cli/telemetry/error-reporter/reporter.js";
 import { EDR_NETWORK_REVERT_SNAPSHOT_EVENT } from "../../../constants.js";
 import { hardhatChainTypeToEdrChainType } from "../../../edr/chain-type.js";
 import { getGlobalEdrContext } from "../../../edr/context.js";
@@ -87,7 +87,7 @@ export const DEFAULT_EDR_NETWORK_HD_ACCOUNTS_CONFIG_PARAMS: EdrNetworkDefaultHDA
 export async function isDefaultEdrNetworkHDAccountsConfig(
   accounts: EdrNetworkHDAccountsConfig,
 ): Promise<boolean> {
-  return deepEqual(
+  return await deepEqual(
     {
       ...accounts,
       mnemonic: await accounts.mnemonic.get(),
@@ -325,7 +325,7 @@ export class EdrProvider extends BaseProvider {
         typeof jsonRpcResponse.result === "string",
         "Invalid client version response",
       );
-      return clientVersion(jsonRpcResponse.result);
+      return await clientVersion(jsonRpcResponse.result);
     } else {
       return jsonRpcResponse.result;
     }
@@ -496,7 +496,7 @@ export class EdrProvider extends BaseProvider {
       throw new UnknownError(error.message, error);
     }
 
-    return this.#handleEdrResponse(
+    return await this.#handleEdrResponse(
       edrResponse,
       request.method,
       Array.isArray(request.params) ? request.params : undefined,

package/src/internal/builtin-plugins/network-manager/edr/genesis-state.ts

@@ -79,7 +79,7 @@ export async function getGenesisStateAndOwnedAccounts(
     return cached;
   }
 
-  return genesisStateAndAccountsCacheMutex.exclusiveRun(async () => {
+  return await genesisStateAndAccountsCacheMutex.exclusiveRun(async () => {
     // We need to check again inside the mutex callback in case another async
     // operation initialized it while we were waiting to acquire the mutex
     const cachedAfterWaiting = genesisStateAndAccountsCache

package/src/internal/builtin-plugins/network-manager/edr/stack-traces/solidity-stack-trace.ts

@@ -25,10 +25,12 @@ import type {
   InternalFunctionCallStackEntry,
   ContractCallRunOutOfGasError,
   CheatcodeErrorStackTraceEntry,
+  CheatcodeErrorDetails,
 } from "@nomicfoundation/edr";
 
 import {
   StackTraceEntryType,
+  CheatcodeErrorCode,
   stackTraceEntryTypeToString,
   FALLBACK_FUNCTION_NAME,
   RECEIVE_FUNCTION_NAME,
@@ -42,6 +44,7 @@ import {
 export {
   SourceReference,
   StackTraceEntryType,
+  CheatcodeErrorCode,
   stackTraceEntryTypeToString,
   FALLBACK_FUNCTION_NAME,
   RECEIVE_FUNCTION_NAME,
@@ -77,6 +80,7 @@ export type {
   ContractTooLargeErrorStackTraceEntry,
   InternalFunctionCallStackEntry,
   ContractCallRunOutOfGasError,
+  CheatcodeErrorDetails,
 };
 
 export type SolidityStackTraceEntry =

package/src/internal/builtin-plugins/network-manager/edr/stack-traces/stack-trace-solidity-errors.ts

@@ -9,8 +9,11 @@ import { assertHardhatInvariant } from "@nomicfoundation/hardhat-errors";
 import { bytesToHexString } from "@nomicfoundation/hardhat-utils/bytes";
 import { panicErrorCodeToMessage } from "@nomicfoundation/hardhat-utils/panic-errors";
 
+import { REVERT_ERROR_CODE } from "../../revert-error-code.js";
+
 import {
   StackTraceEntryType,
+  CheatcodeErrorCode,
   CONSTRUCTOR_FUNCTION_NAME,
   PRECOMPILE_FUNCTION_NAME,
   UNKNOWN_FUNCTION_NAME,
@@ -266,9 +269,25 @@ function getMessageFromLastStackTraceEntry(
       return `VM Exception while processing transaction: ${panicMessage}`;
 
     case StackTraceEntryType.CUSTOM_ERROR:
-    case StackTraceEntryType.CHEATCODE_ERROR:
       return `VM Exception while processing transaction: ${stackTraceEntry.message}`;
 
+    case StackTraceEntryType.CHEATCODE_ERROR: {
+      let message = stackTraceEntry.message;
+
+      if (stackTraceEntry.details !== undefined) {
+        switch (stackTraceEntry.details.code) {
+          case CheatcodeErrorCode.UnsupportedCheatcode:
+            message = `Cheatcode '${stackTraceEntry.details.cheatcode}' is not supported by Hardhat.`;
+            break;
+          case CheatcodeErrorCode.MissingCheatcode:
+            message = `Cheatcode '${stackTraceEntry.details.cheatcode}' is not yet available in this version of Hardhat.`;
+            break;
+        }
+      }
+
+      return `VM Exception while processing transaction: ${message}`;
+    }
+
     case StackTraceEntryType.OTHER_EXECUTION_ERROR:
       // TODO: What if there was returnData?
       return `Transaction reverted and Hardhat couldn't infer the reason.`;
@@ -293,11 +312,15 @@ function getMessageFromLastStackTraceEntry(
 }
 
 /**
- * Note: This error class MUST NOT extend ProviderError, as libraries use the
- * code property to detect if they are dealing with a JSON-RPC error, and take
- * control of errors.
+ * Note: This error class does not extend ProviderError because it carries
+ * Solidity-specific data (stackTrace) that ProviderError does not model.
+ * It does carry `code = 3` to match the de facto standard used by geth and
+ * anvil for execution revert errors, allowing libraries like viem to
+ * properly detect and handle revert errors via the error cause chain.
  **/
 export class SolidityError extends Error {
+  public readonly code: number = REVERT_ERROR_CODE;
+
   constructor(
     message: string,
     public readonly stackTrace: SolidityStackTrace,
@@ -305,6 +328,7 @@ export class SolidityError extends Error {
     public readonly transactionHash?: string,
   ) {
     super(message);
+    this.name = "SolidityError";
 
     Object.defineProperty(this, Symbol.for("nodejs.util.inspect.custom"), {
       value: () =>