hardhat 3.9.0 → 3.9.1

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

@@ -64,7 +64,7 @@ export interface FunctionGasSnapshotChange {
 export interface FunctionGasSnapshotCheckResult {
   passed: boolean;
   comparison: FunctionGasSnapshotComparison;
-  written: boolean;
+  noBaseline: boolean;
 }
 
 export function getFunctionGasSnapshotsPath(basePath: string): string {
@@ -323,16 +323,17 @@ export async function checkFunctionGasSnapshots(
     previousFunctionGasSnapshots = await readFunctionGasSnapshots(basePath);
   } catch (error) {
     if (error instanceof FileNotFoundError) {
-      await writeFunctionGasSnapshots(basePath, functionGasSnapshots);
-
+      // Running a check without a stored snapshot is a mistake: fail so it's
+      // caught, but only when this run actually produced something to check.
+      const noBaseline = functionGasSnapshots.length > 0;
       return {
-        passed: true,
+        passed: !noBaseline,
         comparison: {
           added: [],
           removed: [],
           changed: [],
         },
-        written: true,
+        noBaseline,
       };
     }
 
@@ -344,59 +345,54 @@ export async function checkFunctionGasSnapshots(
     functionGasSnapshots,
   );
 
-  // Update snapshots when functions are added or removed (but not changed)
-  const hasAddedOrRemoved =
-    comparison.added.length > 0 || comparison.removed.length > 0;
-  if (comparison.changed.length === 0 && hasAddedOrRemoved) {
-    await writeFunctionGasSnapshots(basePath, functionGasSnapshots);
-  }
-
   return {
     passed: comparison.changed.length === 0,
     comparison,
-    written: hasAddedOrRemoved,
+    noBaseline: false,
   };
 }
 
 export function logFunctionGasSnapshotsSection(
   result: FunctionGasSnapshotCheckResult,
   logger: typeof console.log = console.log,
+  isFiltered = false,
 ): void {
-  const { comparison, written } = result;
+  const { comparison, noBaseline } = result;
   const changedLength = comparison.changed.length;
-  const addedLength = comparison.added.length;
-  const removedLength = comparison.removed.length;
   const hasChanges = changedLength > 0;
+  // On a filtered run (--grep or specific files), added and missing snapshots
+  // are mostly artifacts of the filter rather than real differences, so we
+  // don't report them.
+  const addedLength = isFiltered ? 0 : comparison.added.length;
+  const removedLength = isFiltered ? 0 : comparison.removed.length;
   const hasAdded = addedLength > 0;
   const hasRemoved = removedLength > 0;
   const hasAnyDifferences = hasChanges || hasAdded || hasRemoved;
-  const isFirstTimeWrite = written && !hasAnyDifferences;
 
   // Nothing to report
-  if (!isFirstTimeWrite && !hasAnyDifferences) {
+  if (!noBaseline && !hasAnyDifferences) {
     return;
   }
 
-  logger(
-    formatSectionHeader("Function gas snapshots", {
-      changedLength,
-      addedLength,
-      removedLength,
-    }),
-  );
-
-  if (isFirstTimeWrite) {
-    logger();
+  if (noBaseline) {
     logger(
       styleText(
-        "green",
-        "  No existing snapshots found. Function gas snapshots written successfully",
+        "yellow",
+        "Function gas snapshots: no snapshot found. Run your tests with --snapshot to create one.",
       ),
     );
     logger();
     return;
   }
 
+  logger(
+    formatSectionHeader("Function gas snapshots", {
+      changedLength,
+      addedLength,
+      removedLength,
+    }),
+  );
+
   if (hasChanges) {
     logger();
     printFunctionGasSnapshotChanges(comparison.changed, logger);
@@ -404,7 +400,9 @@ export function logFunctionGasSnapshotsSection(
 
   if (hasAdded) {
     logger();
-    logger(`  Added ${comparison.added.length} function(s):`);
+    logger(
+      `  ${comparison.added.length} function(s) produced by this run are not in the snapshot:`,
+    );
     const addedLines = stringifyFunctionGasSnapshots(comparison.added).split(
       "\n",
     );
@@ -415,7 +413,9 @@ export function logFunctionGasSnapshotsSection(
 
   if (hasRemoved) {
     logger();
-    logger(`  Removed ${comparison.removed.length} function(s):`);
+    logger(
+      `  ${comparison.removed.length} stored function(s) were not produced by this run:`,
+    );
     const removedLines = stringifyFunctionGasSnapshots(
       comparison.removed,
     ).split("\n");

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

@@ -78,7 +78,7 @@ export interface SnapshotCheatcodesComparison {
 export interface SnapshotCheatcodesCheckResult {
   passed: boolean;
   comparison: SnapshotCheatcodesComparison;
-  written: boolean;
+  noBaseline: boolean;
   renamedGroups: RenamedSnapshotGroup[];
 }
 
@@ -363,20 +363,17 @@ export async function checkSnapshotCheatcodes(
     previousSnapshotCheatcodes = await readSnapshotCheatcodes(basePath);
   } catch (error) {
     if (error instanceof FileNotFoundError) {
-      // Only write if there are cheatcodes to save
-      const written = snapshotCheatcodes.size > 0;
-      if (written) {
-        await writeSnapshotCheatcodes(basePath, snapshotCheatcodes);
-      }
-
+      // Running a check without stored snapshots is a mistake: fail so it's
+      // caught, but only when this run actually produced something to check.
+      const noBaseline = snapshotCheatcodes.size > 0;
       return {
-        passed: true,
+        passed: !noBaseline,
         comparison: {
           added: [],
           removed: [],
           changed: [],
         },
-        written,
+        noBaseline,
         renamedGroups,
       };
     }
@@ -389,17 +386,10 @@ export async function checkSnapshotCheatcodes(
     snapshotCheatcodes,
   );
 
-  // Update snapshots when functions are added or removed (but not changed)
-  const hasAddedOrRemoved =
-    comparison.added.length > 0 || comparison.removed.length > 0;
-  if (comparison.changed.length === 0 && hasAddedOrRemoved) {
-    await writeSnapshotCheatcodes(basePath, snapshotCheatcodes);
-  }
-
   return {
     passed: comparison.changed.length === 0,
     comparison,
-    written: hasAddedOrRemoved,
+    noBaseline: false,
     renamedGroups,
   };
 }
@@ -407,42 +397,44 @@ export async function checkSnapshotCheatcodes(
 export function logSnapshotCheatcodesSection(
   result: SnapshotCheatcodesCheckResult,
   logger: typeof console.log = console.log,
+  isFiltered = false,
 ): void {
-  const { comparison, written } = result;
+  const { comparison, noBaseline } = result;
   const changedLength = comparison.changed.length;
-  const addedLength = comparison.added.length;
-  const removedLength = comparison.removed.length;
   const hasChanges = changedLength > 0;
+  // On a filtered run (--grep or specific files), added and missing snapshots
+  // are mostly artifacts of the filter rather than real differences, so we
+  // don't report them.
+  const addedLength = isFiltered ? 0 : comparison.added.length;
+  const removedLength = isFiltered ? 0 : comparison.removed.length;
   const hasAdded = addedLength > 0;
   const hasRemoved = removedLength > 0;
   const hasAnyDifferences = hasChanges || hasAdded || hasRemoved;
-  const isFirstTimeWrite = written && !hasAnyDifferences;
 
   // Nothing to report
-  if (!isFirstTimeWrite && !hasAnyDifferences) {
+  if (!noBaseline && !hasAnyDifferences) {
     return;
   }
 
-  logger(
-    formatSectionHeader("Snapshot cheatcodes", {
-      changedLength,
-      addedLength,
-      removedLength,
-    }),
-  );
-
-  if (isFirstTimeWrite) {
-    logger();
+  if (noBaseline) {
     logger(
       styleText(
-        "green",
-        "  No existing snapshots found. Snapshot cheatcodes written successfully",
+        "yellow",
+        "Snapshot cheatcodes: no snapshots found. Run your tests with --snapshot to create one.",
       ),
     );
     logger();
     return;
   }
 
+  logger(
+    formatSectionHeader("Snapshot cheatcodes", {
+      changedLength,
+      addedLength,
+      removedLength,
+    }),
+  );
+
   if (hasChanges) {
     logger();
     printSnapshotCheatcodeChanges(comparison.changed, logger);
@@ -450,7 +442,9 @@ export function logSnapshotCheatcodesSection(
 
   if (hasAdded) {
     logger();
-    logger(`  Added ${comparison.added.length} snapshot(s):`);
+    logger(
+      `  ${comparison.added.length} snapshot(s) produced by this run are not in the snapshot:`,
+    );
     const addedLines = stringifySnapshotCheatcodes(comparison.added).split(
       "\n",
     );
@@ -461,7 +455,9 @@ export function logSnapshotCheatcodesSection(
 
   if (hasRemoved) {
     logger();
-    logger(`  Removed ${comparison.removed.length} snapshot(s):`);
+    logger(
+      `  ${comparison.removed.length} stored snapshot(s) were not produced by this run:`,
+    );
     const removedLines = stringifySnapshotCheatcodes(comparison.removed).split(
       "\n",
     );

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

@@ -31,6 +31,9 @@ import {
 interface GasAnalyticsTestActionArguments {
   snapshot: boolean;
   snapshotCheck: boolean;
+  // Forwarded from the base `test solidity` task; used to detect scoped runs.
+  grep?: string;
+  testFiles?: string[];
 }
 
 export interface SnapshotResult {
@@ -74,7 +77,11 @@ const runSolidityTests: TaskOverrideActionFunction<
       rootPath,
       suiteResults,
     );
-    logSnapshotCheckResult(snapshotCheckResult);
+    // On a scoped run, added/missing snapshots are expected, so don't report
+    // them (they'd be noise from the filter, not real differences).
+    const isFiltered =
+      args.grep !== undefined || (args.testFiles?.length ?? 0) > 0;
+    logSnapshotCheckResult(snapshotCheckResult, console.log, isFiltered);
     snapshotCheckPassed =
       snapshotCheckResult.functionGasSnapshotsCheck.passed &&
       snapshotCheckResult.snapshotCheatcodesCheck.passed;
@@ -141,6 +148,7 @@ export async function handleSnapshotCheck(
 export function logSnapshotCheckResult(
   { functionGasSnapshotsCheck, snapshotCheatcodesCheck }: SnapshotCheckResult,
   logger: typeof console.log = console.log,
+  isFiltered = false,
 ): void {
   logger(
     functionGasSnapshotsCheck.passed && snapshotCheatcodesCheck.passed
@@ -148,23 +156,28 @@ export function logSnapshotCheckResult(
       : styleText("red", "Snapshot check failed"),
   );
 
+  // On a filtered run, added/removed aren't reported, so they don't count
+  // towards a section having output (which drives the spacing below).
+  const showAddedRemoved = !isFiltered;
   const functionGasHasOutput =
-    functionGasSnapshotsCheck.written ||
+    functionGasSnapshotsCheck.noBaseline ||
     functionGasSnapshotsCheck.comparison.changed.length > 0 ||
-    functionGasSnapshotsCheck.comparison.added.length > 0 ||
-    functionGasSnapshotsCheck.comparison.removed.length > 0;
+    (showAddedRemoved &&
+      (functionGasSnapshotsCheck.comparison.added.length > 0 ||
+        functionGasSnapshotsCheck.comparison.removed.length > 0));
   const snapshotCheatcodesHasOutput =
-    snapshotCheatcodesCheck.written ||
+    snapshotCheatcodesCheck.noBaseline ||
     snapshotCheatcodesCheck.comparison.changed.length > 0 ||
-    snapshotCheatcodesCheck.comparison.added.length > 0 ||
-    snapshotCheatcodesCheck.comparison.removed.length > 0;
+    (showAddedRemoved &&
+      (snapshotCheatcodesCheck.comparison.added.length > 0 ||
+        snapshotCheatcodesCheck.comparison.removed.length > 0));
 
   // Add an extra newline if function gas snapshots have output
   if (functionGasHasOutput) {
     logger();
   }
 
-  logFunctionGasSnapshotsSection(functionGasSnapshotsCheck, logger);
+  logFunctionGasSnapshotsSection(functionGasSnapshotsCheck, logger, isFiltered);
 
   // Add an extra newline if only snapshot cheatcodes have output
   // (logFunctionGasSnapshotsSection adds one if it has output)
@@ -172,7 +185,7 @@ export function logSnapshotCheckResult(
     logger();
   }
 
-  logSnapshotCheatcodesSection(snapshotCheatcodesCheck, logger);
+  logSnapshotCheatcodesSection(snapshotCheatcodesCheck, logger, isFiltered);
 
   // Add an extra newline if only the rename warnings have output
   // (logSnapshotCheatcodesSection adds one if it has output)

package/src/internal/builtin-plugins/hhu/index.ts

@@ -0,0 +1,13 @@
+import type { HardhatPlugin } from "../../../types/plugins.js";
+
+import { definePlugin } from "../../../plugins.js";
+
+import { generateTasks } from "./tasks/index.js";
+
+const hardhatPlugin: HardhatPlugin = definePlugin({
+  id: "builtin:hhu",
+  tasks: generateTasks({ prefixWithUtils: true }),
+  npmPackage: "hardhat",
+});
+
+export default hardhatPlugin;

package/src/internal/builtin-plugins/hhu/tasks/constants/index.ts

@@ -0,0 +1,18 @@
+import type { UtilsTaskDefinition } from "../../types.js";
+
+import { emptyTask, task } from "../../../../core/config.js";
+import { buildUtilsTask } from "../utils-task.js";
+
+export function constants(prefix: string[]): UtilsTaskDefinition[] {
+  const constantsTask = emptyTask(
+    [...prefix, "constants"],
+    "Commonly used Ethereum constants",
+  ).build();
+
+  const zeroAddressTask = buildUtilsTask(
+    task([...prefix, "constants", "zero-address"], "Print the zero address"),
+    async () => await import("./zero-address.js"),
+  );
+
+  return [constantsTask, zeroAddressTask];
+}

package/src/internal/builtin-plugins/hhu/tasks/constants/zero-address.ts

@@ -0,0 +1,9 @@
+import type { NewUtilsTaskActionFunction } from "../../types.js";
+
+const zeroAddress = "0x0000000000000000000000000000000000000000";
+
+const zeroAddressAction: NewUtilsTaskActionFunction = async () => {
+  console.log(zeroAddress);
+};
+
+export default zeroAddressAction;

package/src/internal/builtin-plugins/hhu/tasks/convert/index.ts

@@ -0,0 +1,40 @@
+import type { UtilsTaskDefinition } from "../../types.js";
+
+import { ArgumentType } from "../../../../../types/arguments.js";
+import { emptyTask, task } from "../../../../core/config.js";
+import { buildUtilsTask } from "../utils-task.js";
+
+export function convert(prefix: string[]): UtilsTaskDefinition[] {
+  const convertTask = emptyTask(
+    [...prefix, "convert"],
+    "Convert values between common Ethereum representations",
+  ).build();
+
+  const padTask = buildUtilsTask(
+    task(
+      [...prefix, "convert", "pad"],
+      "Pad a hex string to a given byte length",
+    )
+      .addPositionalArgument({
+        name: "value",
+        description: "The hex string to pad",
+      })
+      .addOption({
+        name: "length",
+        description: "The target length, in bytes",
+        type: ArgumentType.INT,
+        defaultValue: 32,
+      })
+      .addFlag({
+        name: "left",
+        description: "Pad to the left (default)",
+      })
+      .addFlag({
+        name: "right",
+        description: "Pad to the right",
+      }),
+    async () => await import("./pad.js"),
+  );
+
+  return [convertTask, padTask];
+}

package/src/internal/builtin-plugins/hhu/tasks/convert/pad.ts

@@ -0,0 +1,61 @@
+import type { NewUtilsTaskActionFunction } from "../../types.js";
+
+import { HardhatError } from "@nomicfoundation/hardhat-errors";
+import {
+  getUnprefixedHexString,
+  isHexString,
+} from "@nomicfoundation/hardhat-utils/hex";
+
+interface PadActionArguments {
+  value: string;
+  length: number;
+  left: boolean;
+  right: boolean;
+}
+
+const padAction: NewUtilsTaskActionFunction<PadActionArguments> = async ({
+  value,
+  length,
+  left,
+  right,
+}) => {
+  if (left && right) {
+    throw new HardhatError(
+      HardhatError.ERRORS.CORE.ARGUMENTS.MUTUALLY_EXCLUSIVE_OPTIONS,
+      { optionA: "left", optionB: "right" },
+    );
+  }
+
+  if (length < 0) {
+    throw new HardhatError(HardhatError.ERRORS.CORE.ARGUMENTS.INVALID_VALUE, {
+      value: length,
+      name: "length",
+      reason: "it must be a non-negative integer",
+    });
+  }
+
+  if (!isHexString(value)) {
+    throw new HardhatError(
+      HardhatError.ERRORS.CORE.GENERAL.INVALID_HEX_STRING,
+      { value },
+    );
+  }
+
+  const unprefixedHexString = getUnprefixedHexString(value);
+
+  if (unprefixedHexString.length > length * 2) {
+    throw new HardhatError(HardhatError.ERRORS.CORE.ARGUMENTS.INVALID_VALUE, {
+      value,
+      name: "value",
+      reason: `it's longer than the target length of ${length} bytes`,
+    });
+  }
+
+  const paddedHexString = right
+    ? unprefixedHexString.padEnd(length * 2, "0")
+    : unprefixedHexString.padStart(length * 2, "0");
+
+  console.log(`0x${paddedHexString}`);
+};
+
+export default padAction;

package/src/internal/builtin-plugins/hhu/tasks/fetch/block-number.ts

@@ -0,0 +1,28 @@
+import type { NewUtilsTaskActionFunction } from "../../types.js";
+
+import { assertHardhatInvariant } from "@nomicfoundation/hardhat-errors";
+import { hexStringToBigInt } from "@nomicfoundation/hardhat-utils/hex";
+
+const fetchBlockNumberAction: NewUtilsTaskActionFunction = async (
+  _taskArguments,
+  hre,
+) => {
+  const connection = await hre.network.create();
+
+  try {
+    const blockNumber = await connection.provider.request({
+      method: "eth_blockNumber",
+    });
+
+    assertHardhatInvariant(
+      typeof blockNumber === "string",
+      "eth_blockNumber should return a string",
+    );
+
+    console.log(hexStringToBigInt(blockNumber).toString());
+  } finally {
+    await connection.close();
+  }
+};
+
+export default fetchBlockNumberAction;

package/src/internal/builtin-plugins/hhu/tasks/fetch/index.ts

@@ -0,0 +1,18 @@
+import type { UtilsTaskDefinition } from "../../types.js";
+
+import { emptyTask, task } from "../../../../core/config.js";
+import { buildUtilsTask } from "../utils-task.js";
+
+export function fetch(prefix: string[]): UtilsTaskDefinition[] {
+  const fetchTask = emptyTask(
+    [...prefix, "fetch"],
+    "Fetch on-chain data",
+  ).build();
+
+  const blockNumberTask = buildUtilsTask(
+    task([...prefix, "fetch", "block-number"], "Print the latest block number"),
+    async () => await import("./block-number.js"),
+  );
+
+  return [fetchTask, blockNumberTask];
+}

package/src/internal/builtin-plugins/hhu/tasks/index.ts

@@ -0,0 +1,36 @@
+import type { UtilsTaskDefinition } from "../types.js";
+
+import { emptyTask } from "../../../core/config.js";
+
+import { constants } from "./constants/index.js";
+import { convert } from "./convert/index.js";
+import { fetch } from "./fetch/index.js";
+
+export interface GenerateTasksOptions {
+  /**
+   * Whether to nest every task under a top-level `utils` task. Used by the
+   * Hardhat CLI (`hardhat utils constants ...`) but not by the standalone hhu
+   * binary (`hhu constants ...`).
+   */
+  prefixWithUtils: boolean;
+}
+
+/**
+ * The category builders that contribute the utils tasks. Each one receives the
+ * id prefix to nest its tasks under and returns its task definitions. Adding a
+ * new category is a single entry here.
+ */
+const CATEGORIES = [constants, convert, fetch];
+
+export function generateTasks(
+  options: GenerateTasksOptions,
+): UtilsTaskDefinition[] {
+  const prefix = options.prefixWithUtils ? ["utils"] : [];
+
+  return [
+    ...(prefix.length > 0
+      ? [emptyTask(prefix, "Utilities for common Ethereum tasks").build()]
+      : []),
+    ...CATEGORIES.flatMap((category) => category(prefix)),
+  ];
+}

package/src/internal/builtin-plugins/hhu/tasks/utils-task.ts

@@ -0,0 +1,29 @@
+import type {
+  LazyActionObject,
+  NewTaskDefinitionBuilder,
+  TaskArguments,
+} from "../../../../types/tasks.js";
+import type {
+  NewUtilsTaskActionFunction,
+  NewUtilsTaskDefinition,
+} from "../types.js";
+
+/**
+ * Builds a utils task from a configured task builder and a lazily-loaded action.
+ *
+ * The standard builder's `setAction`/`build` are hardcoded to
+ * `NewTaskActionFunction`, so it can't produce a `NewUtilsTaskDefinition` on its
+ * own. This helper requires the action to be a `NewUtilsTaskActionFunction`
+ * (rejecting wider actions at the call site), which is what makes re-narrowing
+ * the built definition sound.
+ */
+export function buildUtilsTask<TaskArgumentsT extends TaskArguments>(
+  builder: NewTaskDefinitionBuilder<TaskArgumentsT>,
+  action: LazyActionObject<NewUtilsTaskActionFunction<TaskArgumentsT>>,
+): NewUtilsTaskDefinition {
+  // The narrower action is assignable to the builder's `NewTaskActionFunction`,
+  // and since `action` is statically a `NewUtilsTaskActionFunction`, re-narrowing
+  // the result is safe.
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- see above
+  return builder.setAction(action).build() as NewUtilsTaskDefinition;
+}

package/src/internal/builtin-plugins/hhu/types.ts

@@ -0,0 +1,57 @@
+import type { HardhatRuntimeEnvironment } from "../../../types/hre.js";
+import type { NetworkManager } from "../../../types/network.js";
+import type {
+  BaseTaskDefinition,
+  EmptyTaskDefinition,
+  LazyActionObject,
+  TaskArguments,
+} from "../../../types/tasks.js";
+
+/**
+ * The subset of the HRE that utils tasks are allowed to use.
+ *
+ * It is narrowed to what the hhu binary can provide without always creating
+ * a real HRE.
+ */
+export interface UtilsHardhatRuntimeEnvironment {
+  network: Pick<NetworkManager, "create">;
+}
+
+/**
+ * The fake HRE that the hhu binary builds so it can parse and run utils without
+ * creating a real one. It's the surface utils actions use
+ * ({@link UtilsHardhatRuntimeEnvironment}) plus the `config` that
+ * `TaskManagerImplementation` needs to build the task map.
+ */
+export interface FakeHhuHardhatRuntimeEnvironment
+  extends UtilsHardhatRuntimeEnvironment {
+  config: Pick<HardhatRuntimeEnvironment["config"], "tasks" | "plugins">;
+}
+
+/**
+ * The type of a utils task's action function.
+ *
+ * It mirrors `NewTaskActionFunction`, but the HRE passed as the second argument
+ * is narrowed to `UtilsHardhatRuntimeEnvironment` so that utils tasks only
+ * depend on the small surface that both the Hardhat CLI and the hhu binary can
+ * provide.
+ */
+export type NewUtilsTaskActionFunction<
+  TaskArgumentsT extends TaskArguments = TaskArguments,
+> = (taskArguments: TaskArgumentsT, hre: UtilsHardhatRuntimeEnvironment) => any;
+
+/**
+ * The definition of a utils task.
+ *
+ * It mirrors `NewTaskDefinition`, but narrows that action to a
+ * `NewUtilsTaskActionFunction`.
+ */
+export type NewUtilsTaskDefinition = BaseTaskDefinition & {
+  action: LazyActionObject<NewUtilsTaskActionFunction>;
+};
+
+/**
+ * The subset of `TaskDefinition` that utils tasks produce: either an empty task
+ * (a namespace placeholder) or a utils task. Override tasks are not supported.
+ */
+export type UtilsTaskDefinition = EmptyTaskDefinition | NewUtilsTaskDefinition;