@nomicfoundation/hardhat-utils 3.0.3 → 3.0.4

package/dist/src/panic-errors.d.ts

@@ -1,2 +1,15 @@
+/**
+ * Converts a Solidity panic error code into a human-readable revert message.
+ *
+ * Solidity defines a set of standardized panic codes (0x01, 0x11, etc.)
+ * that represent specific runtime errors (e.g. arithmetic overflow).
+ * This function looks up the corresponding reason string and formats it
+ * into a message similar to what clients like Hardhat or ethers.js display.
+ *
+ * @param errorCode The panic error code returned by the EVM as a bigint.
+ * @returns A formatted message string:
+ * - `"reverted with panic code <hex> (<reason>)"` if the code is recognized.
+ * - `"reverted with unknown panic code <hex>"` if the code is not recognized.
+ */
 export declare function panicErrorCodeToMessage(errorCode: bigint): string;
 //# sourceMappingURL=panic-errors.d.ts.map

package/dist/src/panic-errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"panic-errors.d.ts","sourceRoot":"","sources":["../../src/panic-errors.ts"],"names":[],"mappings":"AAEA,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQjE"}
+{"version":3,"file":"panic-errors.d.ts","sourceRoot":"","sources":["../../src/panic-errors.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQjE"}

package/dist/src/panic-errors.js

@@ -1,4 +1,18 @@
 import { numberToHexString } from "./hex.js";
+import { panicErrorCodeToReason } from "./internal/panic-errors.js";
+/**
+ * Converts a Solidity panic error code into a human-readable revert message.
+ *
+ * Solidity defines a set of standardized panic codes (0x01, 0x11, etc.)
+ * that represent specific runtime errors (e.g. arithmetic overflow).
+ * This function looks up the corresponding reason string and formats it
+ * into a message similar to what clients like Hardhat or ethers.js display.
+ *
+ * @param errorCode The panic error code returned by the EVM as a bigint.
+ * @returns A formatted message string:
+ * - `"reverted with panic code <hex> (<reason>)"` if the code is recognized.
+ * - `"reverted with unknown panic code <hex>"` if the code is not recognized.
+ */
 export function panicErrorCodeToMessage(errorCode) {
     const reason = panicErrorCodeToReason(errorCode);
     if (reason !== undefined) {
@@ -6,27 +20,4 @@ export function panicErrorCodeToMessage(errorCode) {
     }
     return `reverted with unknown panic code ${numberToHexString(errorCode)}`;
 }
-function panicErrorCodeToReason(errorCode) {
-    // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- we are only covering some of the integer range
-    switch (errorCode) {
-        case 0x1n:
-            return "Assertion error";
-        case 0x11n:
-            return "Arithmetic operation overflowed outside of an unchecked block";
-        case 0x12n:
-            return "Division or modulo division by zero";
-        case 0x21n:
-            return "Tried to convert a value into an enum, but the value was too big or negative";
-        case 0x22n:
-            return "Incorrectly encoded storage byte array";
-        case 0x31n:
-            return ".pop() was called on an empty array";
-        case 0x32n:
-            return "Array accessed at an out-of-bounds or negative index";
-        case 0x41n:
-            return "Too much memory was allocated, or an array was created that is too large";
-        case 0x51n:
-            return "Called a zero-initialized variable of internal function type";
-    }
-}
 //# sourceMappingURL=panic-errors.js.map

package/dist/src/panic-errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"panic-errors.js","sourceRoot":"","sources":["../../src/panic-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE7C,MAAM,UAAU,uBAAuB,CAAC,SAAiB;IACvD,MAAM,MAAM,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAEjD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,4BAA4B,iBAAiB,CAAC,SAAS,CAAC,KAAK,MAAM,GAAG,CAAC;IAChF,CAAC;IAED,OAAO,oCAAoC,iBAAiB,CAAC,SAAS,CAAC,EAAE,CAAC;AAC5E,CAAC;AAED,SAAS,sBAAsB,CAAC,SAAiB;IAC/C,4HAA4H;IAC5H,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,IAAI;YACP,OAAO,iBAAiB,CAAC;QAC3B,KAAK,KAAK;YACR,OAAO,+DAA+D,CAAC;QACzE,KAAK,KAAK;YACR,OAAO,qCAAqC,CAAC;QAC/C,KAAK,KAAK;YACR,OAAO,8EAA8E,CAAC;QACxF,KAAK,KAAK;YACR,OAAO,wCAAwC,CAAC;QAClD,KAAK,KAAK;YACR,OAAO,qCAAqC,CAAC;QAC/C,KAAK,KAAK;YACR,OAAO,sDAAsD,CAAC;QAChE,KAAK,KAAK;YACR,OAAO,0EAA0E,CAAC;QACpF,KAAK,KAAK;YACR,OAAO,8DAA8D,CAAC;IAC1E,CAAC;AACH,CAAC"}
+{"version":3,"file":"panic-errors.js","sourceRoot":"","sources":["../../src/panic-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAEpE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,uBAAuB,CAAC,SAAiB;IACvD,MAAM,MAAM,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAEjD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,4BAA4B,iBAAiB,CAAC,SAAS,CAAC,KAAK,MAAM,GAAG,CAAC;IAChF,CAAC;IAED,OAAO,oCAAoC,iBAAiB,CAAC,SAAS,CAAC,EAAE,CAAC;AAC5E,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomicfoundation/hardhat-utils",
-  "version": "3.0.3",
+  "version": "3.0.4",
   "description": "Utilities for Hardhat and its plugins",
   "homepage": "https://github.com/nomicfoundation/hardhat/tree/v-next/v-next/hardhat-utils",
   "repository": {
@@ -23,6 +23,7 @@
     "./env": "./dist/src/env.js",
     "./error": "./dist/src/error.js",
     "./eth": "./dist/src/eth.js",
+    "./format": "./dist/src/format.js",
     "./fs": "./dist/src/fs.js",
     "./global-dir": "./dist/src/global-dir.js",
     "./hex": "./dist/src/hex.js",

package/src/format.ts

@@ -0,0 +1,267 @@
+import {
+  getColumnWidths,
+  getContentWidth,
+  getHeadingWidth,
+  getStringWidth,
+  renderContentLine,
+  renderHeaderOpen,
+  renderRowSeparator,
+  renderSectionClose,
+} from "./internal/format.js";
+
+export type TableRow = string[];
+export interface TableDivider {
+  type: "divider";
+}
+export type TableItem = TableRow | TableDivider;
+
+export const divider: TableDivider = { type: "divider" };
+
+/**
+ * Formats an array of rows and dividers into a table string.
+ *
+ * @param items An array of table rows (string arrays) and dividers.
+ * Dividers are objects with type: "divider" and will be rendered as table dividers.
+ * @returns The formatted table as a string, ready to be rendered.
+ *
+ * @example
+ * ```ts
+ * formatTable([
+ *   ["Name", "Age"],
+ *   divider,
+ *   ["Alice", "30"],
+ *   ["Bob", "25"],
+ *   divider,
+ *   ["Average", "27.5"]
+ * ]);
+ *
+ * // =>
+ * // | Name    | Age  |
+ * // | ------- | ---- |
+ * // | Alice   | 30   |
+ * // | Bob     | 25   |
+ * // | ------- | ---- |
+ * // | Average | 27.5 |
+ * ```
+ */
+export function formatTable(items: TableItem[]): string {
+  const widths: number[] = [];
+  const dataRows: string[][] = [];
+
+  for (const item of items) {
+    if (Array.isArray(item)) {
+      dataRows.push([...item]);
+    }
+  }
+
+  // Calculate maximum width for each column
+  for (const row of dataRows) {
+    for (let i = 0; i < row.length; i++) {
+      while (i >= widths.length) {
+        widths.push(0);
+      }
+      widths[i] = Math.max(widths[i], getStringWidth(row[i]));
+    }
+  }
+
+  const dividerRow = widths.map((width) => "-".repeat(width));
+  const outputRows: string[][] = [];
+
+  for (const item of items) {
+    if (Array.isArray(item)) {
+      const row = [...item];
+      // Pad the row to match the number of columns
+      while (row.length < widths.length) {
+        row.push("");
+      }
+      outputRows.push(row);
+    } else {
+      outputRows.push([...dividerRow]);
+    }
+  }
+
+  outputRows.forEach((row) => {
+    for (let i = 0; i < row.length; i++) {
+      const displayWidth = getStringWidth(row[i]);
+      const actualLength = row[i].length;
+      // Adjust padding to account for difference between display width and actual length
+      row[i] = row[i].padEnd(widths[i] + actualLength - displayWidth);
+    }
+  });
+
+  return outputRows.map((row) => `| ${row.join(" | ")} |`).join("\n");
+}
+
+export interface TableTitleV2 {
+  type: "title";
+  text: string;
+}
+
+export interface TableSectionHeaderV2 {
+  type: "section-header";
+  text: string;
+}
+
+export interface TableHeaderV2 {
+  type: "header";
+  cells: string[];
+}
+
+export interface TableRowV2 {
+  type: "row";
+  cells: string[];
+}
+
+export type TableItemV2 =
+  | TableTitleV2
+  | TableSectionHeaderV2
+  | TableHeaderV2
+  | TableRowV2;
+
+/**
+ * Formats an array of titles, section headers, headers, and rows into a table
+ * string with box-drawing characters.
+ *
+ * Features:
+ * - Titles are centered in a standalone box with double borders (╔═╗)
+ * - Section headers group related content with automatic closing
+ * - Headers and rows can have different numbers of cells
+ * - Rows with fewer cells than max columns are handled with special rendering
+ *
+ * @param items An array of table items (titles, section headers, headers, and rows).
+ * Sections are automatically closed when a new section-header or title appears, or
+ * at the end of the table.
+ * @returns The formatted table as a string, ready to be rendered.
+ *
+ * @example
+ * ```ts
+ * formatTableV2([
+ *   { type: "title", text: "My Table" },
+ *   { type: "section-header", text: "User Data" },
+ *   { type: "header", cells: ["Name", "Age", "City"] },
+ *   { type: "row", cells: ["Alice", "30", "NYC"] },
+ *   { type: "row", cells: ["Bob", "25", "LA"] },
+ *   { type: "section-header", text: "Summary" },
+ *   { type: "header", cells: ["Total", "Count"] },
+ *   { type: "row", cells: ["55", "2"] }
+ * ]);
+ *
+ * // =>
+ * // ╔═══════════════════╗
+ * // ║     My Table      ║
+ * // ╚═══════════════════╝
+ * // ╔═══════════════════╗
+ * // ║ User Data         ║
+ * // ╟───────┬─────┬─────╢
+ * // ║ Name  │ Age │ City║
+ * // ╟───────┼─────┼─────╢
+ * // ║ Alice │ 30  │ NYC ║
+ * // ╟───────┼─────┼─────╢
+ * // ║ Bob   │ 25  │ LA  ║
+ * // ╚═══════╧═════╧═════╝
+ * // ╔═══════════════════╗
+ * // ║ Summary           ║
+ * // ╟───────┬───────────╢
+ * // ║ Total │ Count     ║
+ * // ╟───────┼───────────╢
+ * // ║ 55    │ 2         ║
+ * // ╚═══════╧═══════════╝
+ * ```
+ */
+export function formatTableV2(items: TableItemV2[]): string {
+  if (items.length === 0) {
+    return "";
+  }
+
+  const columnWidths = getColumnWidths(items);
+  const contentWidth = getContentWidth(columnWidths);
+  const headingWidth = getHeadingWidth(items);
+
+  // If heading is wider than content, expand last column to fit
+  if (headingWidth > contentWidth && columnWidths.length > 0) {
+    const extraSpace = headingWidth - contentWidth;
+    columnWidths[columnWidths.length - 1] += extraSpace;
+  }
+
+  const tableWidth = Math.max(contentWidth, headingWidth);
+
+  const lines: string[] = [];
+  let previousCellCount = 0; // Keep track of previous row/header cell count
+  let inSection = false;
+
+  for (let i = 0; i < items.length; i++) {
+    const [previous, current] = [items[i - 1], items[i]];
+
+    if (current.type === "title") {
+      if (inSection) {
+        lines.push(renderSectionClose(columnWidths, previousCellCount));
+        inSection = false;
+      }
+
+      lines.push("╔" + "═".repeat(tableWidth) + "╗");
+      const titleDisplayWidth = getStringWidth(current.text);
+      const titleActualLength = current.text.length;
+      const centeredTitle = current.text
+        .padStart(
+          (tableWidth + titleDisplayWidth) / 2 +
+            (titleActualLength - titleDisplayWidth),
+        )
+        .padEnd(tableWidth + (titleActualLength - titleDisplayWidth));
+      lines.push("║" + centeredTitle + "║");
+      lines.push("╚" + "═".repeat(tableWidth) + "╝");
+    } else if (current.type === "section-header") {
+      if (inSection) {
+        lines.push(renderSectionClose(columnWidths, previousCellCount));
+      }
+
+      lines.push("╔" + "═".repeat(tableWidth) + "╗");
+      const headerDisplayWidth = getStringWidth(current.text);
+      const headerActualLength = current.text.length;
+      const paddedHeader = current.text.padEnd(
+        tableWidth - 2 + (headerActualLength - headerDisplayWidth),
+      );
+      lines.push("║ " + paddedHeader + " ║");
+      inSection = true;
+    } else if (current.type === "header") {
+      const currentCellCount = current.cells.length;
+      const innerJoiner =
+        previous !== undefined && previous.type === "section-header"
+          ? "┬"
+          : "┼";
+      const needsTransition =
+        previous !== undefined &&
+        previous.type !== "section-header" &&
+        currentCellCount < previousCellCount;
+
+      lines.push(
+        renderHeaderOpen(
+          columnWidths,
+          currentCellCount,
+          innerJoiner,
+          needsTransition,
+        ),
+      );
+      lines.push(
+        renderContentLine(current.cells, columnWidths, currentCellCount),
+      );
+      previousCellCount = currentCellCount;
+    } else if (current.type === "row") {
+      const currentCellCount = current.cells.length;
+
+      // Only add separator if previous wasn't a row
+      if (previous === undefined || previous.type !== "row") {
+        lines.push(renderRowSeparator(columnWidths, currentCellCount));
+      }
+      lines.push(
+        renderContentLine(current.cells, columnWidths, currentCellCount),
+      );
+      previousCellCount = currentCellCount;
+    }
+  }
+
+  if (inSection) {
+    lines.push(renderSectionClose(columnWidths, previousCellCount));
+  }
+
+  return lines.join("\n");
+}

package/src/internal/format.ts

@@ -0,0 +1,260 @@
+import type { TableItemV2 } from "../format.js";
+
+/**
+ * Calculate the display width of a string by removing ANSI escape codes.
+ *
+ * NOTE: This implementation only removes basic ANSI color/style codes and may
+ * not handle all escape sequences (e.g., cursor movement, complex control
+ * sequences).
+ */
+export function getStringWidth(str: string): number {
+  // Remove ANSI escape codes if present
+  const stripped = str.replace(/\u001b\[[0-9;]*m/g, "");
+  return stripped.length;
+}
+
+/**
+ * Calculates the minimum width needed by each column in the table
+ * to fit its content (accounting for ANSI color codes).
+ */
+export function getColumnWidths(items: TableItemV2[]): number[] {
+  const columnWidths: number[] = [];
+
+  for (const item of items) {
+    if (item.type === "row" || item.type === "header") {
+      item.cells.forEach((cell, i) => {
+        columnWidths[i] = Math.max(columnWidths[i] ?? 0, getStringWidth(cell));
+      });
+    }
+  }
+
+  return columnWidths;
+}
+
+/**
+ * Calculates the inner width needed to fit the rows and headers
+ * (excludes borders, which are added during rendering).
+ *
+ * Each column is padded by 1 space on each side, and columns are
+ * separated by " │ " (3 spaces).
+ */
+export function getContentWidth(columnWidths: number[]): number {
+  return (
+    columnWidths.reduce((sum, w) => sum + w, 0) +
+    (columnWidths.length - 1) * 3 +
+    2
+  );
+}
+
+/**
+ * Calculates the inner width needed to fit titles and section headers
+ * (excludes borders, which are added during rendering).
+ *
+ * Each title/header is padded by 1 space on each side.
+ * Accounts for ANSI color codes.
+ */
+export function getHeadingWidth(items: TableItemV2[]): number {
+  let headingWidth = 0;
+  for (const item of items) {
+    if (item.type === "section-header" || item.type === "title") {
+      headingWidth = Math.max(headingWidth, getStringWidth(item.text) + 2);
+    }
+  }
+  return headingWidth;
+}
+
+/**
+ * Calculates the width needed for unused columns when a row/header has fewer
+ * cells than the total column count (e.g., if table has 6 columns but row
+ * only has 2 cells, calculates space for the remaining 4 columns).
+ */
+export function getUnusedColumnsWidth(
+  columnWidths: number[],
+  previousCellCount: number,
+): number {
+  const remainingWidths = columnWidths.slice(previousCellCount);
+  return remainingWidths.reduce((sum, w) => sum + w + 3, 0) - 3;
+}
+
+/**
+ * Renders a horizontal rule segment by repeating a character for each column
+ * with padding, joined by a separator (e.g., "─────┼─────┼─────").
+ */
+export function renderRuleSegment(
+  columnWidths: number[],
+  char: string,
+  joiner: string,
+): string {
+  return columnWidths.map((w) => char.repeat(w + 2)).join(joiner);
+}
+
+/**
+ * Renders a complete horizontal rule with left and right borders
+ * (e.g., "╟─────┼─────┼─────╢").
+ */
+export function renderHorizontalRule(
+  leftBorder: string,
+  columnWidths: number[],
+  char: string,
+  joiner: string,
+  rightBorder: string,
+): string {
+  return (
+    leftBorder + renderRuleSegment(columnWidths, char, joiner) + rightBorder
+  );
+}
+
+/**
+ * Renders a content line containing cells from either a header or row.
+ *
+ * Handles two cases:
+ * - Full width: When all columns are used, cells are separated by " │ " and
+ *   line ends with " ║" (e.g., "║ cell1 │ cell2 │ cell3 ║")
+ * - Short line: When fewer columns are used, active cells are followed by
+ *   " │ " and empty space, ending with "║" (e.g., "║ cell1 │ cell2 │       ║")
+ *
+ * Accounts for ANSI color codes when padding cells.
+ */
+export function renderContentLine(
+  cells: string[],
+  columnWidths: number[],
+  currentCellCount: number,
+): string {
+  if (currentCellCount === columnWidths.length) {
+    return (
+      "║ " +
+      cells
+        .map((cell, j) => {
+          const displayWidth = getStringWidth(cell);
+          const actualLength = cell.length;
+          // Adjust padding to account for ANSI escape codes
+          return cell.padEnd(columnWidths[j] + actualLength - displayWidth);
+        })
+        .join(" │ ") +
+      " ║"
+    );
+  } else {
+    const usedWidths = columnWidths.slice(0, currentCellCount);
+    const remainingWidth = getUnusedColumnsWidth(
+      columnWidths,
+      currentCellCount,
+    );
+    return (
+      "║ " +
+      cells
+        .map((cell, j) => {
+          const displayWidth = getStringWidth(cell);
+          const actualLength = cell.length;
+          // Adjust padding to account for ANSI escape codes
+          return cell.padEnd(usedWidths[j] + actualLength - displayWidth);
+        })
+        .join(" │ ") +
+      " │ " +
+      " ".repeat(remainingWidth + 1) +
+      "║"
+    );
+  }
+}
+
+/**
+ * Renders the horizontal rule that appears above a header row.
+ *
+ * Handles three cases:
+ * - Transition rule: When going from more columns to fewer, shows ┴ marks
+ *   where columns collapse (e.g., "╟───┼───┼───┴───┴───╢")
+ * - Full width: When header uses all columns (e.g., "╟───┬───┬───╢" or "╟───┼───┼───╢")
+ * - Short header: When header uses fewer columns than max (e.g., "╟───┬─────────╢")
+ *
+ * The innerJoiner determines the separator character: ┬ after section-header, ┼ otherwise.
+ */
+export function renderHeaderOpen(
+  columnWidths: number[],
+  currentCellCount: number,
+  innerJoiner: string,
+  needsTransition: boolean,
+): string {
+  if (needsTransition) {
+    const usedWidths = columnWidths.slice(0, currentCellCount);
+    const collapsingWidths = columnWidths.slice(currentCellCount);
+    return (
+      "╟" +
+      renderRuleSegment(usedWidths, "─", "┼") +
+      "┼" +
+      renderRuleSegment(collapsingWidths, "─", "┴") +
+      "╢"
+    );
+  } else if (currentCellCount === columnWidths.length) {
+    return renderHorizontalRule("╟", columnWidths, "─", innerJoiner, "╢");
+  } else {
+    const usedWidths = columnWidths.slice(0, currentCellCount);
+    const remainingWidth = getUnusedColumnsWidth(
+      columnWidths,
+      currentCellCount,
+    );
+    return (
+      "╟" +
+      renderRuleSegment(usedWidths, "─", innerJoiner) +
+      innerJoiner +
+      "─".repeat(remainingWidth + 2) +
+      "╢"
+    );
+  }
+}
+
+/**
+ * Renders the horizontal rule that appears above a row.
+ *
+ * Handles two cases:
+ * - Full width: When row uses all columns, renders with ┼ joiners and
+ *   ends with ╢ (e.g., "╟───┼───┼───╢")
+ * - Short row: When row uses fewer columns, renders active columns with
+ *   ┼ joiners, ends with ┤, then fills remaining space and ends with ║
+ *   (e.g., "╟───┼───┤         ║")
+ */
+export function renderRowSeparator(
+  columnWidths: number[],
+  currentCellCount: number,
+): string {
+  if (currentCellCount === columnWidths.length) {
+    return renderHorizontalRule("╟", columnWidths, "─", "┼", "╢");
+  } else {
+    // Short row - ends with ┤ instead of ╢
+    const usedWidths = columnWidths.slice(0, currentCellCount);
+    const remainingWidth = getUnusedColumnsWidth(
+      columnWidths,
+      currentCellCount,
+    );
+    return (
+      "╟" +
+      renderRuleSegment(usedWidths, "─", "┼") +
+      "┤" +
+      " ".repeat(remainingWidth + 2) +
+      "║"
+    );
+  }
+}
+
+/**
+ * Renders the section's bottom border, placing ╧ marks under column
+ * separators where the last row/header had cells (e.g., if the last row
+ * looked like "║ a │ b │       ║", the bottom border would be
+ *             "╚═══╧═══╧═══════╝").
+ */
+export function renderSectionClose(
+  columnWidths: number[],
+  previousCellCount: number,
+): string {
+  if (previousCellCount === columnWidths.length) {
+    return renderHorizontalRule("╚", columnWidths, "═", "╧", "╝");
+  } else {
+    const usedWidths = columnWidths.slice(0, previousCellCount);
+    const unusedWidth = getUnusedColumnsWidth(columnWidths, previousCellCount);
+    return (
+      "╚" +
+      renderRuleSegment(usedWidths, "═", "╧") +
+      "╧" +
+      renderRuleSegment([unusedWidth], "═", "") +
+      "╝"
+    );
+  }
+}

package/src/internal/panic-errors.ts

@@ -0,0 +1,23 @@
+export function panicErrorCodeToReason(errorCode: bigint): string | undefined {
+  // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- we are only covering some of the integer range
+  switch (errorCode) {
+    case 0x1n:
+      return "Assertion error";
+    case 0x11n:
+      return "Arithmetic operation overflowed outside of an unchecked block";
+    case 0x12n:
+      return "Division or modulo division by zero";
+    case 0x21n:
+      return "Tried to convert a value into an enum, but the value was too big or negative";
+    case 0x22n:
+      return "Incorrectly encoded storage byte array";
+    case 0x31n:
+      return ".pop() was called on an empty array";
+    case 0x32n:
+      return "Array accessed at an out-of-bounds or negative index";
+    case 0x41n:
+      return "Too much memory was allocated, or an array was created that is too large";
+    case 0x51n:
+      return "Called a zero-initialized variable of internal function type";
+  }
+}

package/src/panic-errors.ts

@@ -1,5 +1,19 @@
 import { numberToHexString } from "./hex.js";
+import { panicErrorCodeToReason } from "./internal/panic-errors.js";
 
+/**
+ * Converts a Solidity panic error code into a human-readable revert message.
+ *
+ * Solidity defines a set of standardized panic codes (0x01, 0x11, etc.)
+ * that represent specific runtime errors (e.g. arithmetic overflow).
+ * This function looks up the corresponding reason string and formats it
+ * into a message similar to what clients like Hardhat or ethers.js display.
+ *
+ * @param errorCode The panic error code returned by the EVM as a bigint.
+ * @returns A formatted message string:
+ * - `"reverted with panic code <hex> (<reason>)"` if the code is recognized.
+ * - `"reverted with unknown panic code <hex>"` if the code is not recognized.
+ */
 export function panicErrorCodeToMessage(errorCode: bigint): string {
   const reason = panicErrorCodeToReason(errorCode);
 
@@ -9,27 +23,3 @@ export function panicErrorCodeToMessage(errorCode: bigint): string {
 
   return `reverted with unknown panic code ${numberToHexString(errorCode)}`;
 }
-
-function panicErrorCodeToReason(errorCode: bigint): string | undefined {
-  // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- we are only covering some of the integer range
-  switch (errorCode) {
-    case 0x1n:
-      return "Assertion error";
-    case 0x11n:
-      return "Arithmetic operation overflowed outside of an unchecked block";
-    case 0x12n:
-      return "Division or modulo division by zero";
-    case 0x21n:
-      return "Tried to convert a value into an enum, but the value was too big or negative";
-    case 0x22n:
-      return "Incorrectly encoded storage byte array";
-    case 0x31n:
-      return ".pop() was called on an empty array";
-    case 0x32n:
-      return "Array accessed at an out-of-bounds or negative index";
-    case 0x41n:
-      return "Too much memory was allocated, or an array was created that is too large";
-    case 0x51n:
-      return "Called a zero-initialized variable of internal function type";
-  }
-}