hardhat 3.2.0 → 3.4.0

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/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/accounts/derive-private-keys.ts

@@ -1,6 +1,15 @@
+import type * as Bip39T from "ethereum-cryptography/bip39";
+import type { HDKey as HDKeyT } from "ethereum-cryptography/hdkey";
+
 import { HardhatError } from "@nomicfoundation/hardhat-errors";
 import { bytesToHexString } from "@nomicfoundation/hardhat-utils/bytes";
 
+// ethereum-cryptography/bip39 is known to be slow to load, so we lazy load it
+let mnemonicToSeedSync: typeof Bip39T.mnemonicToSeedSync | undefined;
+
+// ethereum-cryptography/hdkey is known to be slow to load, so we lazy load it
+let HDKey: typeof HDKeyT | undefined;
+
 const HD_PATH_REGEX = /^m(:?\/\d+'?)+\/?$/;
 
 export async function derivePrivateKeys(
@@ -47,13 +56,26 @@ async function deriveKeyFromMnemonicAndPath(
   hdPath: string,
   passphrase: string,
 ): Promise<string | undefined> {
-  const { mnemonicToSeedSync } = await import("ethereum-cryptography/bip39");
-  const { HDKey } = await import("ethereum-cryptography/hdkey");
-
   // NOTE: If mnemonic has space or newline at the beginning or end, it will be trimmed.
   // This is because mnemonic containing them may generate different private keys.
   const trimmedMnemonic = mnemonic.trim();
 
+  if (mnemonicToSeedSync === undefined) {
+    const { mnemonicToSeedSync: importedMnemonicToSeedSync } = await import(
+      "ethereum-cryptography/bip39"
+    );
+
+    mnemonicToSeedSync = importedMnemonicToSeedSync;
+  }
+
+  if (HDKey === undefined) {
+    const { HDKey: ImportedHDKey } = await import(
+      "ethereum-cryptography/hdkey"
+    );
+
+    HDKey = ImportedHDKey;
+  }
+
   const seed = mnemonicToSeedSync(trimmedMnemonic, passphrase);
 
   const masterKey = HDKey.fromMasterSeed(seed);

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

@@ -15,23 +15,17 @@ import type {
 import type { RequireField } from "../../../../types/utils.js";
 import type { DefaultHDAccountsConfigParams } from "../accounts/constants.js";
 import type { JsonRpcRequestWrapperFunction } from "../network-manager.js";
+import type { TraceOutputManager } from "./utils/trace-output.js";
 import type {
   SubscriptionEvent,
   Response,
   Provider,
   ProviderConfig,
   TracingConfigWithBuffers,
-  AccountOverride,
   GasReportConfig,
 } from "@nomicfoundation/edr";
 
-import {
-  opGenesisState,
-  opHardforkFromString,
-  l1GenesisState,
-  l1HardforkFromString,
-  ContractDecoder,
-} from "@nomicfoundation/edr";
+import { ContractDecoder, IncludeTraces } from "@nomicfoundation/edr";
 import {
   assertHardhatInvariant,
   HardhatError,
@@ -41,14 +35,9 @@ import { ensureError } from "@nomicfoundation/hardhat-utils/error";
 import { numberToHexString } from "@nomicfoundation/hardhat-utils/hex";
 import { deepEqual } from "@nomicfoundation/hardhat-utils/lang";
 import debug from "debug";
-import { hexToBytes } from "ethereum-cryptography/utils";
-import { addr } from "micro-eth-signer";
 
 import { sendErrorTelemetry } from "../../../cli/telemetry/sentry/reporter.js";
-import {
-  EDR_NETWORK_REVERT_SNAPSHOT_EVENT,
-  OPTIMISM_CHAIN_TYPE,
-} from "../../../constants.js";
+import { EDR_NETWORK_REVERT_SNAPSHOT_EVENT } from "../../../constants.js";
 import { hardhatChainTypeToEdrChainType } from "../../../edr/chain-type.js";
 import { getGlobalEdrContext } from "../../../edr/context.js";
 import { DEFAULT_HD_ACCOUNTS_CONFIG_PARAMS } from "../accounts/constants.js";
@@ -60,6 +49,7 @@ import {
   UnknownError,
 } from "../provider-errors.js";
 
+import { getGenesisStateAndOwnedAccounts } from "./genesis-state.js";
 import { EdrProviderStackTraceGenerationError } from "./stack-traces/stack-trace-generation-errors.js";
 import { createSolidityErrorWithStackTrace } from "./stack-traces/stack-trace-solidity-errors.js";
 import { isEdrProviderErrorData } from "./type-validation.js";
@@ -69,7 +59,6 @@ import {
   hardhatMiningIntervalToEdrMiningInterval,
   hardhatMempoolOrderToEdrMineOrdering,
   hardhatHardforkToEdrSpecId,
-  hardhatAccountsToEdrOwnedAccounts,
   hardhatForkingConfigToEdrForkConfig,
 } from "./utils/convert-to-edr.js";
 import { printLine, replaceLastLine } from "./utils/logger.js";
@@ -135,10 +124,14 @@ interface EdrProviderConfig {
   chainDescriptors: ChainDescriptorsConfig;
   networkConfig: RequireField<EdrNetworkConfig, "chainType">;
   loggerConfig?: LoggerConfig;
-  tracingConfig?: TracingConfigWithBuffers;
+  contractDecoder: ContractDecoder;
   jsonRpcRequestWrapper?: JsonRpcRequestWrapperFunction;
   coverageConfig?: CoverageConfig;
   gasReportConfig?: GasReportConfig;
+  includeCallTraces?: IncludeTraces;
+  connectionId: number;
+  networkName: string;
+  verbosity: number;
 }
 
 export class EdrProvider extends BaseProvider {
@@ -146,6 +139,13 @@ export class EdrProvider extends BaseProvider {
 
   #provider: Provider | undefined;
   #nextRequestId = 1;
+  readonly #traceOutput: TraceOutputManager | undefined;
+
+  public static async createContractDecoder(
+    tracingConfig: TracingConfigWithBuffers,
+  ): Promise<ContractDecoder> {
+    return ContractDecoder.withContracts(tracingConfig);
+  }
 
   /**
    * Creates a new instance of `EdrProvider`.
@@ -154,10 +154,14 @@ export class EdrProvider extends BaseProvider {
     chainDescriptors,
     networkConfig,
     loggerConfig = { enabled: false },
-    tracingConfig = {},
+    contractDecoder,
     jsonRpcRequestWrapper,
     coverageConfig,
     gasReportConfig,
+    includeCallTraces,
+    verbosity,
+    connectionId,
+    networkName,
   }: EdrProviderConfig): Promise<EdrProvider> {
     const printLineFn = loggerConfig.printLineFn ?? printLine;
     const replaceLastLineFn = loggerConfig.replaceLastLineFn ?? replaceLastLine;
@@ -167,15 +171,18 @@ export class EdrProvider extends BaseProvider {
       coverageConfig,
       gasReportConfig,
       chainDescriptors,
+      includeCallTraces,
     );
 
     let edrProvider: EdrProvider;
 
+    // We use a WeakRef to the provider to prevent the subscriptionCallback
+    // below from creating a cycle and leaking the provider.
+    let edrProviderWeakRef: WeakRef<EdrProvider> | undefined;
+
     // We need to catch errors here, as the provider creation can panic unexpectedly,
     // and we want to make sure such a crash is propagated as a ProviderError.
     try {
-      const contractDecoder = ContractDecoder.withContracts(tracingConfig);
-
       const context = await getGlobalEdrContext();
       const provider = await context.createProvider(
         hardhatChainTypeToEdrChainType(networkConfig.chainType),
@@ -199,13 +206,38 @@ export class EdrProvider extends BaseProvider {
         },
         {
           subscriptionCallback: (event: SubscriptionEvent) => {
-            edrProvider.onSubscriptionEvent(event);
+            const deferredProvider = edrProviderWeakRef?.deref();
+            if (deferredProvider !== undefined) {
+              deferredProvider.onSubscriptionEvent(event);
+            }
           },
         },
         contractDecoder,
       );
 
-      edrProvider = new EdrProvider(provider, jsonRpcRequestWrapper);
+      const tracesEnabled =
+        includeCallTraces !== undefined &&
+        includeCallTraces !== IncludeTraces.None;
+
+      let traceOutput: TraceOutputManager | undefined;
+      if (tracesEnabled) {
+        const { TraceOutputManager: TraceOutputManagerImpl } = await import(
+          "./utils/trace-output.js"
+        );
+        traceOutput = new TraceOutputManagerImpl(
+          printLineFn,
+          connectionId,
+          networkName,
+          verbosity,
+        );
+      }
+
+      edrProvider = new EdrProvider(
+        provider,
+        traceOutput,
+        jsonRpcRequestWrapper,
+      );
+      edrProviderWeakRef = new WeakRef(edrProvider);
     } catch (error) {
       ensureError(error);
 
@@ -225,12 +257,22 @@ export class EdrProvider extends BaseProvider {
    */
   private constructor(
     provider: Provider,
+    traceOutput: TraceOutputManager | undefined,
     jsonRpcRequestWrapper?: JsonRpcRequestWrapperFunction,
   ) {
     super();
 
     this.#provider = provider;
+    this.#traceOutput = traceOutput;
     this.#jsonRpcRequestWrapper = jsonRpcRequestWrapper;
+
+    // After a snapshot revert, the same transactions may run again.
+    // Reset traced hashes so their traces are printed a second time.
+    if (this.#traceOutput !== undefined) {
+      this.on(EDR_NETWORK_REVERT_SNAPSHOT_EVENT, () => {
+        this.#traceOutput?.clearTracedHashes();
+      });
+    }
   }
 
   public async request(
@@ -290,8 +332,10 @@ export class EdrProvider extends BaseProvider {
   }
 
   public async close(): Promise<void> {
+    this.removeAllListeners();
     // Clear the provider reference to help with garbage collection
     this.#provider = undefined;
+    this.#traceOutput?.clearTracedHashes();
   }
 
   public async addCompilationResult(
@@ -312,8 +356,11 @@ export class EdrProvider extends BaseProvider {
 
   async #handleEdrResponse(
     edrResponse: Response,
+    method: string,
+    params?: unknown[],
   ): Promise<SuccessfulJsonRpcResponse> {
     let jsonRpcResponse: JsonRpcResponse;
+    let txHash: string | undefined;
 
     if (typeof edrResponse.data === "string") {
       jsonRpcResponse = JSON.parse(edrResponse.data);
@@ -325,6 +372,12 @@ export class EdrProvider extends BaseProvider {
       const responseError = jsonRpcResponse.error;
       let error;
 
+      // Grab the tx hash so trace deduplication can recognize this transaction later
+      const errorData = responseError.data;
+      if (isEdrProviderErrorData(errorData)) {
+        txHash = errorData.transactionHash;
+      }
+
       const stackTrace = edrResponse.stackTrace();
 
       if (stackTrace?.kind === "StackTrace") {
@@ -365,11 +418,33 @@ export class EdrProvider extends BaseProvider {
         error.data = responseError.data;
       }
 
+      this.#traceOutput?.outputCallTraces(edrResponse, method, txHash, true);
+
       /* eslint-disable-next-line no-restricted-syntax -- we may throw
       non-Hardhat errors inside of an EthereumProvider */
       throw error;
     }
 
+    if (this.#traceOutput !== undefined) {
+      // Output call traces for successful responses. The tx hash is resolved
+      // from the response/params so the trace manager can deduplicate.
+
+      if (
+        method === "eth_sendTransaction" ||
+        method === "eth_sendRawTransaction"
+      ) {
+        txHash =
+          typeof jsonRpcResponse.result === "string"
+            ? jsonRpcResponse.result
+            : undefined;
+      } else if (method === "eth_getTransactionReceipt") {
+        // params[0] is the tx hash being queried — used to dedup receipt polling
+        txHash = typeof params?.[0] === "string" ? params[0] : undefined;
+      }
+
+      this.#traceOutput.outputCallTraces(edrResponse, method, txHash, false);
+    }
+
     return jsonRpcResponse;
   }
 
@@ -421,7 +496,11 @@ export class EdrProvider extends BaseProvider {
       throw new UnknownError(error.message, error);
     }
 
-    return this.#handleEdrResponse(edrResponse);
+    return this.#handleEdrResponse(
+      edrResponse,
+      request.method,
+      Array.isArray(request.params) ? request.params : undefined,
+    );
   }
 }
 
@@ -430,49 +509,20 @@ export async function getProviderConfig(
   coverageConfig: CoverageConfig | undefined,
   gasReportConfig: GasReportConfig | undefined,
   chainDescriptors: ChainDescriptorsConfig,
+  includeCallTraces?: IncludeTraces,
 ): Promise<ProviderConfig> {
   const specId = hardhatHardforkToEdrSpecId(
     networkConfig.hardfork,
     networkConfig.chainType,
   );
 
-  const ownedAccounts = await hardhatAccountsToEdrOwnedAccounts(
+  const { genesisState, ownedAccounts } = await getGenesisStateAndOwnedAccounts(
     networkConfig.accounts,
+    networkConfig.forking,
+    networkConfig.chainType,
+    specId,
   );
 
-  const genesisState: Map<Uint8Array, AccountOverride> = new Map(
-    ownedAccounts.map(({ secretKey, balance }) => {
-      const address = hexToBytes(addr.fromPrivateKey(secretKey));
-      const accountOverride: AccountOverride = {
-        address,
-        balance: BigInt(balance),
-        code: new Uint8Array(), // Empty account code, removing potential delegation code when forking
-      };
-
-      return [address, accountOverride];
-    }),
-  );
-
-  const chainGenesisState =
-    networkConfig.forking !== undefined
-      ? [] // TODO: Add support for overriding remote fork state when the local fork is different
-      : networkConfig.chainType === OPTIMISM_CHAIN_TYPE
-        ? opGenesisState(opHardforkFromString(specId))
-        : l1GenesisState(l1HardforkFromString(specId));
-
-  for (const account of chainGenesisState) {
-    const existingOverride = genesisState.get(account.address);
-    if (existingOverride !== undefined) {
-      // Favor the genesis state specified by the user
-      account.balance = account.balance ?? existingOverride.balance;
-      account.nonce = account.nonce ?? existingOverride.nonce;
-      account.code = account.code ?? existingOverride.code;
-      account.storage = account.storage ?? existingOverride.storage;
-    } else {
-      genesisState.set(account.address, account);
-    }
-  }
-
   return {
     allowBlocksWithSameTimestamp: networkConfig.allowBlocksWithSameTimestamp,
     allowUnlimitedContractSize: networkConfig.allowUnlimitedContractSize,
@@ -506,6 +556,7 @@ export async function getProviderConfig(
     observability: {
       codeCoverage: coverageConfig,
       gasReport: gasReportConfig,
+      includeCallTraces,
     },
     ownedAccounts: ownedAccounts.map((account) => account.secretKey),
     precompileOverrides: [],