@nomicfoundation/hardhat-utils 3.0.0-next.0

package/src/global-dir.ts

@@ -0,0 +1,51 @@
+import { generatePaths, HARDHAT_PACKAGE_NAME } from "./internal/global-dir.js";
+
+import { ensureDir } from "@nomicfoundation/hardhat-utils/fs";
+
+/**
+ * Returns the configuration directory path for a given package (defaults to "hardhat").
+ * Ensures that the directory exists before returning the path.
+ *
+ * @param packageName The name of the package for which to generate paths. Defaults to "hardhat" if no package name is provided.
+ * @returns The path to the hardhat configuration directory.
+ * @throws FileSystemAccessError for any error.
+ */
+export async function getConfigDir(
+  packageName: string = HARDHAT_PACKAGE_NAME,
+): Promise<string> {
+  const { config } = await generatePaths(packageName);
+  await ensureDir(config);
+  return config;
+}
+
+/**
+ * Returns the cache directory path for a given package (defaults to "hardhat").
+ * Ensures that the directory exists before returning the path.
+ *
+ * @param packageName The name of the package for which to generate paths. Defaults to "hardhat" if no package name is provided.
+ * @returns The path to the hardhat cache directory.
+ * @throws FileSystemAccessError for any error.
+ */
+export async function getCacheDir(
+  packageName: string = HARDHAT_PACKAGE_NAME,
+): Promise<string> {
+  const { cache } = await generatePaths(packageName);
+  await ensureDir(cache);
+  return cache;
+}
+
+/**
+ * Returns the telemetry directory path for a given package (defaults to "hardhat").
+ * Ensures that the directory exists before returning the path.
+ *
+ * @param packageName The name of the package for which to generate paths. Defaults to "hardhat" if no package name is provided.
+ * @returns A promise that resolves to the path of the telemetry directory.
+ * @throws FileSystemAccessError for any error.
+ */
+export async function getTelemetryDir(
+  packageName: string = HARDHAT_PACKAGE_NAME,
+): Promise<string> {
+  const { data } = await generatePaths(packageName);
+  await ensureDir(data);
+  return data;
+}

package/src/hex.ts

@@ -0,0 +1,232 @@
+import { InvalidParameterError } from "./common-errors.js";
+import { padToEven } from "./internal/hex.js";
+
+export type PrefixedHexString = `0x${string}`;
+
+/**
+ * Converts a non-negative safe integer or bigint to a hexadecimal string.
+ *
+ * @param value The number to convert.
+ * @returns The hexadecimal representation of the number.
+ * @throws InvalidParameterError If the input is not a safe integer or is negative.
+ */
+export function numberToHexString(value: number | bigint): PrefixedHexString {
+  if (
+    value < 0 ||
+    (typeof value === "number" && !Number.isSafeInteger(value))
+  ) {
+    throw new InvalidParameterError(
+      `Expected a non-negative safe integer or bigint. Received: ${value}`,
+    );
+  }
+
+  return `0x${value.toString(16)}`;
+}
+
+/**
+ * Converts a hexadecimal string to a bigint. The string must be a valid
+ * hexadecimal string. The string may be prefixed with "0x" or not. The
+ * empty string is considered a valid hexadecimal string, so is the string
+ * "0x" and will be converted to 0.
+ *
+ * @param hexString The hexadecimal string to convert. It must be a valid
+ * hexadecimal string.
+ * @returns The bigint representation of the hexadecimal string.
+ * @throws InvalidParameterError If the input is not a hexadecimal string.
+ */
+export function hexStringToBigInt(hexString: string): bigint {
+  if (!isHexString(hexString)) {
+    throw new InvalidParameterError(
+      `Expected a valid hexadecimal string. Received: ${hexString}`,
+    );
+  }
+  // Prefix the string as it is required to make BigInt interpret it as a
+  // hexadecimal number.
+  let prefixedHexString = getPrefixedHexString(hexString);
+  // BigInt does not support "0x" as a valid hexadecimal number, so we need to
+  // add a zero after the prefix if the string is "0x".
+  prefixedHexString = prefixedHexString === "0x" ? "0x0" : prefixedHexString;
+
+  const bigInt = BigInt(prefixedHexString);
+
+  return bigInt;
+}
+
+/**
+ * Converts a hexadecimal string to a number. The string must be a valid
+ * hexadecimal string. The string may be prefixed with "0x" or not. The
+ * empty string is considered a valid hexadecimal string, so is the string
+ * "0x" and will be converted to 0.
+ *
+ * @param hexString The hexadecimal string to convert. It must be a valid
+ * hexadecimal string.
+ * @returns The number representation of the hexadecimal string.
+ * @throws InvalidParameterError If the input is not a hexadecimal string or the value exceeds the Number.MAX_SAFE_INTEGER limit.
+ */
+export function hexStringToNumber(hexString: string): number {
+  if (!isHexString(hexString)) {
+    throw new InvalidParameterError(
+      `Expected a valid hexadecimal string. Received: ${hexString}`,
+    );
+  }
+
+  // Prefix the string as it is required to make parseInt interpret it as a
+  // hexadecimal number.
+  let prefixedHexString = getPrefixedHexString(hexString);
+
+  // Handle the special case where the string is "0x".
+  prefixedHexString = prefixedHexString === "0x" ? "0x0" : prefixedHexString;
+
+  const numberValue = parseInt(prefixedHexString, 16);
+
+  if (numberValue > Number.MAX_SAFE_INTEGER) {
+    throw new InvalidParameterError(
+      `Value exceeds the safe integer limit. Received: ${hexString}`,
+    );
+  }
+
+  return numberValue;
+}
+
+/**
+ * Converts a Uint8Array to a hexadecimal string.
+ *
+ * @param bytes The bytes to convert.
+ * @returns PrefixedHexString The hexadecimal representation of the bytes.
+ */
+export function bytesToHexString(bytes: Uint8Array): PrefixedHexString {
+  return getPrefixedHexString(Buffer.from(bytes).toString("hex"));
+}
+
+/**
+ * Converts a hexadecimal string to a Uint8Array. The string must be a valid
+ * hexadecimal string. The string may be prefixed with "0x" or not. The empty
+ * string is considered a valid hexadecimal string, so is the string "0x" and
+ * will be converted to Uint8Array([0]).
+ *
+ * @param hexString The hexadecimal string to convert.
+ * @returns The byte representation of the hexadecimal string.
+ * @throws InvalidParameterError If the input is not a hexadecimal string.
+ */
+export function hexStringToBytes(hexString: string): Uint8Array {
+  if (!isHexString(hexString)) {
+    throw new InvalidParameterError(
+      `Expected a valid hexadecimal string. Received: ${hexString}`,
+    );
+  }
+
+  // Pad the hex string if it's odd, as Buffer.from will truncate it
+  // the last character if it's not a full byte.
+  // See: https://nodejs.org/api/buffer.html#buffers-and-character-encodings
+  const unprefixedHexString = getUnprefixedHexString(padToEven(hexString));
+  return Uint8Array.from(Buffer.from(unprefixedHexString, "hex"));
+}
+
+/**
+ * Normalizes and validates a string that represents a hexadecimal number.
+ * The normalization process includes trimming any leading or trailing
+ * whitespace, converting all characters to lowercase, and ensuring the string
+ * has a "0x" prefix. The validation process checks if the string is a valid
+ * hexadecimal string.
+ *
+ * @param hexString The hex string to normalize.
+ * @returns The normalized hexadecimal string.
+ */
+export function normalizeHexString(hexString: string): PrefixedHexString {
+  const normalizedHexString = hexString.trim().toLowerCase();
+
+  if (!isHexString(normalizedHexString)) {
+    throw new InvalidParameterError(
+      `Expected a valid hexadecimal string. Received: ${hexString}`,
+    );
+  }
+
+  return getPrefixedHexString(normalizedHexString);
+}
+
+/**
+ * Checks if a string starts with "0x" (case-insensitive).
+ * This function does not validate the input.
+ *
+ * @param hexString The string to check.
+ * @returns True if the string starts with "0x", false otherwise.
+ */
+export function isPrefixedHexString(
+  hexString: string,
+): hexString is PrefixedHexString {
+  return hexString.toLowerCase().startsWith("0x");
+}
+
+/**
+ * Removes the "0x" prefix from a hexadecimal string.
+ * If the string is not prefixed, it is returned as is.
+ * This function does not validate the input.
+ *
+ * @param hexString The hexadecimal string.
+ * @returns The hexadecimal string without the "0x" prefix.
+ */
+export function getUnprefixedHexString(hexString: string): string {
+  return isPrefixedHexString(hexString) ? hexString.substring(2) : hexString;
+}
+
+/**
+ * Adds the "0x" prefix to a hexadecimal string.
+ * If the string is already prefixed, it is returned as is.
+ * This function does not validate the input.
+ *
+ * @param hexString The hexadecimal string.
+ * @returns The hexadecimal string with the "0x" prefix.
+ */
+export function getPrefixedHexString(hexString: string): PrefixedHexString {
+  return isPrefixedHexString(hexString) ? hexString : `0x${hexString}`;
+}
+
+/**
+ * Checks if a value is a hexadecimal string. The string may be prefixed with
+ * "0x" or not. The empty string is considered a valid hexadecimal string, so
+ * is the string "0x".
+ *
+ * @param value The value to check.
+ * @returns True if the value is a hexadecimal string, false otherwise.
+ */
+export function isHexString(value: unknown): boolean {
+  return typeof value === "string" && /^(?:0x)?[0-9a-f]*$/i.test(value);
+}
+
+/**
+ * Removes leading zeros from a hexadecimal string, unless the string
+ * represents the number zero ("0x0").
+ * This function does not validate the input.
+ *
+ * @param hexString The hexadecimal string.
+ * @returns The hexadecimal string without leading zeros.
+ */
+export function unpadHexString(hexString: string): string {
+  const unprefixedHexString = getUnprefixedHexString(hexString);
+  const unpaddedHexString = unprefixedHexString.replace(/^0+/, "");
+  return unpaddedHexString === "" ? "0x0" : `0x${unpaddedHexString}`;
+}
+
+/**
+ * Pads a hexadecimal string with zeros on the left to a specified length, or
+ * truncates it from the left if it's too long.
+ * This function does not validate the input.
+ *
+ * @param hexString The hexadecimal string to pad.
+ * @param length The desired length of the hexadecimal string.
+ * @returns The padded hexadecimal string.
+ */
+export function setLengthLeft(
+  hexString: string,
+  length: number,
+): PrefixedHexString {
+  const unprefixedHexString = getUnprefixedHexString(hexString);
+
+  // if the string is longer than the desired length, truncate it
+  if (unprefixedHexString.length > length) {
+    return `0x${unprefixedHexString.slice(-length)}`;
+  }
+
+  const paddedHexString = unprefixedHexString.padStart(length, "0");
+  return `0x${paddedHexString}`;
+}

package/src/internal/bytecode.ts

@@ -0,0 +1,129 @@
+import type { PrefixedHexString } from "../hex.js";
+
+import {
+  AmbiguousLibraryNameError,
+  InvalidLibraryAddressError,
+  MissingLibrariesError,
+  OverlappingLibrariesError,
+  UnnecessaryLibraryError,
+} from "../errors/bytecode.js";
+import { isAddress } from "../eth.js";
+
+export interface Artifact {
+  bytecode: string;
+  linkReferences: {
+    [sourceName: string]: {
+      [libraryName: string]: Array<{ start: number; length: number }>;
+    };
+  };
+}
+
+export interface LibraryLink {
+  sourceName: string;
+  libraryName: string;
+  libraryFqn: string;
+  address: string;
+}
+
+export interface LibraryAddresses {
+  [contractName: string]: PrefixedHexString;
+}
+
+/**
+ * Check that the provided library addresses are valid Ethereum addresses.
+ * If any of them are not, an InvalidLibraryAddressError is thrown.
+ */
+export function checkProvidedLibraryAddresses(
+  providedLibraries: LibraryAddresses,
+): void {
+  const librariesWithInvalidAddresses: LibraryAddresses = {};
+  for (const [name, address] of Object.entries(providedLibraries)) {
+    if (!isAddress(address)) {
+      librariesWithInvalidAddresses[name] = address;
+    }
+  }
+
+  if (Object.keys(librariesWithInvalidAddresses).length === 0) {
+    return;
+  }
+
+  throw new InvalidLibraryAddressError(librariesWithInvalidAddresses);
+}
+
+/**
+ * Check that the provided libraries can't be resolved to multiple libraries, or
+ * that they are not needed by the contract. If any of these conditions are met,
+ * an AmbiguousLibraryNameError or an UnnecessaryLibraryError is thrown.
+ */
+export function checkAmbiguousOrUnnecessaryLinks(
+  providedLibraries: LibraryAddresses,
+  neededLibraries: LibraryLink[],
+): void {
+  const ambiguousLibraries: Record<string, LibraryLink[]> = {};
+  const unnecessaryLibraries: string[] = [];
+
+  for (const providedLibraryName of Object.keys(providedLibraries)) {
+    const matchingLibraries = neededLibraries.filter(
+      ({ libraryName, libraryFqn }) =>
+        libraryName === providedLibraryName ||
+        libraryFqn === providedLibraryName,
+    );
+
+    if (matchingLibraries.length > 1) {
+      ambiguousLibraries[providedLibraryName] = matchingLibraries;
+    } else if (matchingLibraries.length === 0) {
+      unnecessaryLibraries.push(providedLibraryName);
+    }
+  }
+
+  if (Object.keys(ambiguousLibraries).length > 0) {
+    throw new AmbiguousLibraryNameError(ambiguousLibraries);
+  }
+
+  if (unnecessaryLibraries.length > 0) {
+    throw new UnnecessaryLibraryError(unnecessaryLibraries);
+  }
+}
+
+/**
+ * Check that each library is only provided once, either by its name or its
+ * fully qualified name. If a library is provided more than once, an
+ * OverlappingLibrariesError is thrown.
+ */
+export function checkOverlappingLibraryNames(
+  providedLibraries: LibraryAddresses,
+  neededLibraries: LibraryLink[],
+): void {
+  const overlappingLibraries = neededLibraries
+    .filter(
+      ({ libraryName, libraryFqn }) =>
+        providedLibraries[libraryFqn] !== undefined &&
+        providedLibraries[libraryName] !== undefined,
+    )
+    .map(({ libraryFqn }) => libraryFqn);
+
+  if (overlappingLibraries.length === 0) {
+    return;
+  }
+
+  throw new OverlappingLibrariesError(overlappingLibraries);
+}
+
+/**
+ * Check if the needed libraries have all their addresses resolved. If an
+ * address is missing, it means that the user didn't provide it in the
+ * providedLibraries map. In that case, an MissingLibrariesError is thrown.
+ */
+export function checkMissingLibraryAddresses(
+  neededLibraries: LibraryLink[],
+): void {
+  const missingLibraries = neededLibraries
+    .filter(({ address }) => address === undefined)
+    .map(({ libraryFqn }) => libraryFqn);
+
+  if (missingLibraries.length === 0) {
+    return;
+  }
+
+  throw new MissingLibrariesError(missingLibraries);
+}

package/src/internal/eth.ts

@@ -0,0 +1,71 @@
+import { utf8StringToBytes } from "../bytes.js";
+import { keccak256 } from "../crypto.js";
+import { bytesToHexString, getUnprefixedHexString } from "../hex.js";
+
+class RandomBytesGenerator {
+  #nextValue: Uint8Array;
+
+  private constructor(nextValue: Uint8Array) {
+    this.#nextValue = nextValue;
+  }
+
+  public static async create(seed: string): Promise<RandomBytesGenerator> {
+    const nextValue = await keccak256(Buffer.from(seed));
+
+    return new RandomBytesGenerator(nextValue);
+  }
+
+  public async next(): Promise<Uint8Array> {
+    const valueToReturn = this.#nextValue;
+
+    this.#nextValue = await keccak256(this.#nextValue);
+
+    return valueToReturn;
+  }
+}
+
+let hashGenerator: RandomBytesGenerator | null = null;
+let addressGenerator: RandomBytesGenerator | null = null;
+
+export async function getHashGenerator(): Promise<RandomBytesGenerator> {
+  if (hashGenerator === null) {
+    hashGenerator = await RandomBytesGenerator.create("hashSeed");
+  }
+  return hashGenerator;
+}
+
+export async function getAddressGenerator(): Promise<RandomBytesGenerator> {
+  if (addressGenerator === null) {
+    addressGenerator = await RandomBytesGenerator.create("addressSeed");
+  }
+  return addressGenerator;
+}
+
+/**
+ * Checks if a value is an Ethereum address and if the checksum is valid.
+ * This method is a a an adaptation of the ethereumjs methods at this link:
+ * https://github.com/ethereumjs/ethereumjs-monorepo/blob/47f388bfeec553519d11259fee7e7161a77b29b2/packages/util/src/account.ts#L440-L478
+ * The main differences are:
+ * - the two methods have been merged into one
+ * - tha `eip1191ChainId` parameter has been removed.
+ * - the code has been modified to use the `hardhat-utils` methods
+ *
+ */
+export async function isValidChecksum(hexAddress: string): Promise<boolean> {
+  const address = getUnprefixedHexString(hexAddress).toLowerCase();
+
+  const bytes = utf8StringToBytes(address);
+
+  const hash = bytesToHexString(await keccak256(bytes)).slice(2);
+
+  let ret = "";
+  for (let i = 0; i < address.length; i++) {
+    if (parseInt(hash[i], 16) >= 8) {
+      ret += address[i].toUpperCase();
+    } else {
+      ret += address[i];
+    }
+  }
+
+  return `0x${ret}` === hexAddress;
+}

package/src/internal/global-dir.ts

@@ -0,0 +1,10 @@
+import type envPaths from "env-paths";
+
+export const HARDHAT_PACKAGE_NAME = "hardhat";
+
+export async function generatePaths(
+  packageName: string,
+): Promise<envPaths.Paths> {
+  const { default: envPaths } = await import("env-paths");
+  return envPaths(packageName);
+}

package/src/internal/hex.ts

@@ -0,0 +1,21 @@
+import {
+  getPrefixedHexString,
+  getUnprefixedHexString,
+  isPrefixedHexString,
+} from "../hex.js";
+
+export function padToEven(value: string): string {
+  const isPrefixed = isPrefixedHexString(value);
+  const unprefixed = getUnprefixedHexString(value);
+
+  let padded;
+  if (unprefixed.length === 0) {
+    // Pad the empty string with a single zero, as Buffer.from([]) will not
+    // interpret it correctly otherwise.
+    padded = "00";
+  } else {
+    padded = unprefixed.length % 2 === 0 ? unprefixed : `0${unprefixed}`;
+  }
+
+  return isPrefixed ? getPrefixedHexString(padded) : padded;
+}

package/src/internal/lang.ts

@@ -0,0 +1,12 @@
+import type rfdcT from "rfdc";
+
+let clone: ReturnType<typeof rfdcT> | null = null;
+export async function getDeepCloneFunction(): Promise<<T>(input: T) => T> {
+  const { default: rfdc } = await import("rfdc");
+
+  if (clone === null) {
+    clone = rfdc();
+  }
+
+  return clone;
+}

package/src/internal/package.ts

@@ -0,0 +1,15 @@
+import { fileURLToPath } from "node:url";
+
+export function getFilePath(filePathOrUrl: string): string | undefined {
+  if (filePathOrUrl.startsWith("file://")) {
+    try {
+      // This can throw on Windows if the url is malformed,
+      // so we catch it and return undefined
+      return fileURLToPath(filePathOrUrl);
+    } catch (_) {
+      return undefined;
+    }
+  }
+
+  return filePathOrUrl;
+}