@nomicfoundation/hardhat-utils 3.0.0-next.0

package/src/errors/bytecode.ts

@@ -0,0 +1,75 @@
+import type { LibraryAddresses, LibraryLink } from "../internal/bytecode.js";
+
+import { CustomError } from "../error.js";
+
+export class InvalidLibraryAddressError extends CustomError {
+  constructor(libraries: LibraryAddresses) {
+    const formattedLibraries = Object.entries(libraries)
+      .map(([libraryName, address]) => `\t* "${libraryName}": "${address}"`)
+      .join("\n");
+
+    super(`The following libraries have invalid addresses:
+${formattedLibraries}
+
+Please provide valid Ethereum addresses for these libraries.`);
+  }
+}
+
+export class AmbiguousLibraryNameError extends CustomError {
+  constructor(libraries: Record<string, LibraryLink[]>) {
+    const formattedLibraries = Object.entries(libraries)
+      .map(
+        ([providedLibraryName, matchingLibraries]) =>
+          `\t* "${providedLibraryName}":\n${matchingLibraries
+            .map(({ libraryFqn }) => `\t\t* "${libraryFqn}"`)
+            .join("\n")}`,
+      )
+      .join("\n");
+
+    super(`The following libraries may resolve to multiple libraries:
+${formattedLibraries}
+
+Please provide the fully qualified name for these libraries.`);
+  }
+}
+
+export class UnnecessaryLibraryError extends CustomError {
+  constructor(libraries: string[]) {
+    const formattedLibraries = libraries
+      .map((libraryName) => `\t* "${libraryName}"`)
+      .join("\n");
+
+    super(`The following libraries are not referenced by the contract:
+${formattedLibraries}
+
+Please provide only the libraries that are needed.`);
+  }
+}
+
+export class OverlappingLibrariesError extends CustomError {
+  constructor(libraries: string[]) {
+    const formattedLibraries = libraries
+      .map((libraryFqn) => `\t* "${libraryFqn}"`)
+      .join("\n");
+
+    super(`The following libraries are provided more than once:
+${formattedLibraries}
+
+Please ensure that each library is provided only once, either by its name or its fully qualified name.`);
+  }
+}
+
+export class MissingLibrariesError extends CustomError {
+  constructor(libraries: string[]) {
+    const formattedLibraries = libraries
+      .map((libraryFqn) => `\t* "${libraryFqn}"`)
+      .join("\n");
+
+    super(
+      `The following libraries are missing:
+${formattedLibraries}
+
+Please provide all the required libraries.`,
+    );
+  }
+}

package/src/errors/fs.ts

@@ -0,0 +1,47 @@
+import { CustomError } from "../error.js";
+
+// We use this error to encapsulate any other error possibly thrown by node's
+// fs apis, as sometimes their errors don't have stack traces.
+export class FileSystemAccessError extends CustomError {}
+
+export class FileNotFoundError extends CustomError {
+  constructor(filePath: string, cause?: Error) {
+    super(`File ${filePath} not found`, cause);
+  }
+}
+
+export class FileAlreadyExistsError extends CustomError {
+  constructor(filePath: string, cause?: Error) {
+    super(`File ${filePath} already exists`, cause);
+  }
+}
+
+export class InvalidFileFormatError extends CustomError {
+  constructor(filePath: string, cause: Error) {
+    super(`Invalid file format: ${filePath}`, cause);
+  }
+}
+
+export class JsonSerializationError extends CustomError {
+  constructor(filePath: string, cause: Error) {
+    super(`Error serializing JSON file ${filePath}`, cause);
+  }
+}
+
+export class NotADirectoryError extends CustomError {
+  constructor(filePath: string, cause: Error) {
+    super(`Path ${filePath} is not a directory`, cause);
+  }
+}
+
+export class IsDirectoryError extends CustomError {
+  constructor(filePath: string, cause: Error) {
+    super(`Path ${filePath} is a directory`, cause);
+  }
+}
+
+export class DirectoryNotEmptyError extends CustomError {
+  constructor(filePath: string, cause: Error) {
+    super(`Directory ${filePath} is not empty`, cause);
+  }
+}

package/src/errors/package.ts

@@ -0,0 +1,13 @@
+import { CustomError } from "../error.js";
+
+export class PackageJsonNotFoundError extends CustomError {
+  constructor(filePathOrUrl: string, cause?: Error) {
+    super(`No package.json found for ${filePathOrUrl}`, cause);
+  }
+}
+
+export class PackageJsonReadError extends CustomError {
+  constructor(packageJsonPath: string, cause?: Error) {
+    super(`Failed to read package.json at ${packageJsonPath}`, cause);
+  }
+}

package/src/errors/request.ts

@@ -0,0 +1,84 @@
+import type UndiciT from "undici";
+
+import { CustomError } from "../error.js";
+import { sanitizeUrl } from "../internal/request.js";
+import { isObject } from "../lang.js";
+
+export class RequestError extends CustomError {
+  constructor(url: string, type: UndiciT.Dispatcher.HttpMethod, cause?: Error) {
+    super(`Failed to make ${type} request to ${sanitizeUrl(url)}`, cause);
+  }
+}
+
+export class DownloadError extends CustomError {
+  constructor(url: string, cause?: Error) {
+    super(`Failed to download file from ${sanitizeUrl(url)}`, cause);
+  }
+}
+
+export class DispatcherError extends CustomError {
+  constructor(message: string, cause?: Error) {
+    super(`Failed to create dispatcher: ${message}`, cause);
+  }
+}
+
+export class RequestTimeoutError extends CustomError {
+  constructor(url: string, cause?: Error) {
+    super(`Request to ${sanitizeUrl(url)} timed out`, cause);
+  }
+}
+
+export class ConnectionRefusedError extends CustomError {
+  constructor(url: string, cause?: Error) {
+    super(`Connection to ${sanitizeUrl(url)} was refused`, cause);
+  }
+}
+
+export class ResponseStatusCodeError extends CustomError {
+  public readonly statusCode: number;
+  public readonly headers:
+    | string[]
+    | Record<string, string | string[] | undefined>
+    | null;
+  public readonly body: null | Record<string, any> | string;
+
+  constructor(url: string, cause: Error) {
+    super(`Received an unexpected status code from ${sanitizeUrl(url)}`, cause);
+    this.statusCode =
+      "statusCode" in cause && typeof cause.statusCode === "number"
+        ? cause.statusCode
+        : -1;
+    this.headers = this.#extractHeaders(cause);
+    this.body = "body" in cause && isObject(cause.body) ? cause.body : null;
+  }
+
+  #extractHeaders(
+    cause: Error,
+  ): string[] | Record<string, string | string[] | undefined> | null {
+    if ("headers" in cause) {
+      const headers = cause.headers;
+      if (Array.isArray(headers)) {
+        return headers;
+      } else if (this.#isValidHeaders(headers)) {
+        return headers;
+      }
+    }
+    return null;
+  }
+
+  #isValidHeaders(
+    headers: unknown,
+  ): headers is Record<string, string | string[] | undefined> {
+    if (!isObject(headers)) {
+      return false;
+    }
+
+    return Object.values(headers).every(
+      (header) =>
+        typeof header === "string" ||
+        (Array.isArray(header) &&
+          header.every((item: unknown) => typeof item === "string")) ||
+        header === undefined,
+    );
+  }
+}

package/src/errors/subprocess.ts

@@ -0,0 +1,17 @@
+import { CustomError } from "../error.js";
+
+export class SubprocessFileNotFoundError extends CustomError {
+  constructor(filePath: string) {
+    super(
+      `Cannot find the subprocess file to execute, invalid file path: ${filePath}`,
+    );
+  }
+}
+
+export class SubprocessPathIsDirectoryError extends CustomError {
+  constructor(path: string) {
+    super(
+      `The provided path is a directory, only files are accepted. Path: ${path}`,
+    );
+  }
+}

package/src/eth.ts

@@ -0,0 +1,91 @@
+import type { PrefixedHexString } from "./hex.js";
+
+import { bytesToHexString, numberToHexString, setLengthLeft } from "./hex.js";
+import {
+  getAddressGenerator,
+  getHashGenerator,
+  isValidChecksum,
+} from "./internal/eth.js";
+
+/**
+ * Checks if a value is an Ethereum address.
+ *
+ * @param value The value to check.
+ * @returns True if the value is an Ethereum address, false otherwise.
+ */
+export function isAddress(value: unknown): value is PrefixedHexString {
+  return typeof value === "string" && /^0x[0-9a-f]{40}$/i.test(value);
+}
+
+/**
+ * Checks if a value is an Ethereum address and if the checksum is valid.
+ *
+ * @param value The value to check.
+ * @returns True if the value is an Ethereum address with a valid checksum, false otherwise.
+ */
+export async function isValidChecksumAddress(value: unknown): Promise<boolean> {
+  return isAddress(value) && isValidChecksum(value);
+}
+
+/**
+ * Checks if a value is an Ethereum hash.
+ *
+ * @param value The value to check.
+ * @returns True if the value is an Ethereum hash, false otherwise.
+ */
+export function isHash(value: unknown): value is PrefixedHexString {
+  return typeof value === "string" && /^0x[0-9a-f]{64}$/i.test(value);
+}
+
+/**
+ * Converts a number to a hexadecimal string with a length of 32 bytes.
+ *
+ * @param value The number to convert.
+ * @returns The hexadecimal representation of the number padded to 32 bytes.
+ * @throws InvalidParameterError If the input is not a safe integer or is negative.
+ */
+export function toEvmWord(value: bigint | number): PrefixedHexString {
+  return setLengthLeft(numberToHexString(value), 64);
+}
+
+/**
+ * Generates a pseudo-random sequence of hash bytes.
+ *
+ * @returns A pseudo-random sequence of hash bytes.
+ */
+export async function generateHashBytes(): Promise<Uint8Array> {
+  const hashGenerator = await getHashGenerator();
+  return hashGenerator.next();
+}
+
+/**
+ * Generates a pseudo-random hash.
+ *
+ * @returns A pseudo-random hash.
+ */
+export async function randomHash(): Promise<PrefixedHexString> {
+  const hashBytes = await generateHashBytes();
+  return bytesToHexString(hashBytes);
+}
+
+/**
+ * Generates a pseudo-random sequence of hash bytes that can be used as an
+ * address.
+ *
+ * @returns A pseudo-random sequence of hash bytes.
+ */
+export async function generateAddressBytes(): Promise<Uint8Array> {
+  const addressGenerator = await getAddressGenerator();
+  const hashBytes = await addressGenerator.next();
+  return hashBytes.slice(0, 20);
+}
+
+/**
+ * Generates a pseudo-random address.
+ *
+ * @returns A pseudo-random address.
+ */
+export async function randomAddress(): Promise<PrefixedHexString> {
+  const addressBytes = await generateAddressBytes();
+  return bytesToHexString(addressBytes);
+}