@nomicfoundation/hardhat-utils 3.0.0-next.0

package/dist/src/synchronization.js

@@ -0,0 +1,107 @@
+// Logic explanation: the fs.writeFile function, when used with the wx+ flag, performs an atomic operation to create a file.
+// If multiple processes try to create the same file simultaneously, only one will succeed.
+// This logic can be utilized to implement a mutex.
+// ATTENTION: in the current implementation, there's still a risk of two processes running simultaneously.
+// For example, if processA has locked the mutex and is running, processB will wait.
+// During this wait, processB continuously checks the elapsed time since the mutex lock file was created.
+// If an excessive amount of time has passed, processB will assume ownership of the mutex to avoid stale locks.
+// However, there's a possibility that processB might take ownership because the mutex creation file is outdated, even though processA is still running
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import debug from "debug";
+import { ensureError } from "./error.js";
+import { FileSystemAccessError } from "./errors/fs.js";
+import { sleep } from "./lang.js";
+const log = debug("hardhat:util:multi-process-mutex");
+const DEFAULT_MAX_MUTEX_LIFESPAN_IN_MS = 60000;
+const MUTEX_LOOP_WAITING_TIME_IN_MS = 100;
+export class MultiProcessMutex {
+    #mutexFilePath;
+    #mutexLifespanInMs;
+    constructor(mutexName, maxMutexLifespanInMs) {
+        log(`Creating mutex with name '${mutexName}'`);
+        this.#mutexFilePath = path.join(os.tmpdir(), `${mutexName}.txt`);
+        this.#mutexLifespanInMs =
+            maxMutexLifespanInMs ?? DEFAULT_MAX_MUTEX_LIFESPAN_IN_MS;
+    }
+    async use(f) {
+        log(`Starting mutex process with mutex file '${this.#mutexFilePath}'`);
+        while (true) {
+            if (await this.#tryToAcquireMutex()) {
+                // Mutex has been acquired
+                return this.#executeFunctionAndReleaseMutex(f);
+            }
+            // Mutex not acquired
+            if (this.#isMutexFileTooOld()) {
+                // If the mutex file is too old, it likely indicates a stale lock, so the file should be removed
+                log(`Current mutex file is too old, removing it at path '${this.#mutexFilePath}'`);
+                this.#deleteMutexFile();
+            }
+            else {
+                // wait
+                await sleep(MUTEX_LOOP_WAITING_TIME_IN_MS / 1000);
+            }
+        }
+    }
+    async #tryToAcquireMutex() {
+        try {
+            // Create a file only if it does not exist
+            fs.writeFileSync(this.#mutexFilePath, "", { flag: "wx+" });
+            return true;
+        }
+        catch (e) {
+            ensureError(e);
+            if (e.code === "EEXIST") {
+                // File already exists, so the mutex is already acquired
+                return false;
+            }
+            throw new FileSystemAccessError(e.message, e);
+        }
+    }
+    async #executeFunctionAndReleaseMutex(f) {
+        log(`Mutex acquired at path '${this.#mutexFilePath}'`);
+        try {
+            return await f();
+        }
+        finally {
+            // Release the mutex
+            log(`Mutex released at path '${this.#mutexFilePath}'`);
+            this.#deleteMutexFile();
+            log(`Mutex released at path '${this.#mutexFilePath}'`);
+        }
+    }
+    #isMutexFileTooOld() {
+        let fileStat;
+        try {
+            fileStat = fs.statSync(this.#mutexFilePath);
+        }
+        catch (e) {
+            ensureError(e);
+            if (e.code === "ENOENT") {
+                // The file might have been deleted by another process while this function was trying to access it.
+                return false;
+            }
+            throw new FileSystemAccessError(e.message, e);
+        }
+        const now = new Date();
+        const fileDate = new Date(fileStat.ctime);
+        const diff = now.getTime() - fileDate.getTime();
+        return diff > this.#mutexLifespanInMs;
+    }
+    #deleteMutexFile() {
+        try {
+            log(`Deleting mutex file at path '${this.#mutexFilePath}'`);
+            fs.unlinkSync(this.#mutexFilePath);
+        }
+        catch (e) {
+            ensureError(e);
+            if (e.code === "ENOENT") {
+                // The file might have been deleted by another process while this function was trying to access it.
+                return;
+            }
+            throw new FileSystemAccessError(e.message, e);
+        }
+    }
+}
+//# sourceMappingURL=synchronization.js.map

package/dist/src/synchronization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"synchronization.js","sourceRoot":"","sources":["../../src/synchronization.ts"],"names":[],"mappings":"AAAA,4HAA4H;AAC5H,2FAA2F;AAC3F,mDAAmD;AACnD,0GAA0G;AAC1G,oFAAoF;AACpF,yGAAyG;AACzG,+GAA+G;AAC/G,uJAAuJ;AAEvJ,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAElC,MAAM,GAAG,GAAG,KAAK,CAAC,kCAAkC,CAAC,CAAC;AACtD,MAAM,gCAAgC,GAAG,KAAK,CAAC;AAC/C,MAAM,6BAA6B,GAAG,GAAG,CAAC;AAE1C,MAAM,OAAO,iBAAiB;IACnB,cAAc,CAAS;IACvB,kBAAkB,CAAS;IAEpC,YAAY,SAAiB,EAAE,oBAA6B;QAC1D,GAAG,CAAC,6BAA6B,SAAS,GAAG,CAAC,CAAC;QAE/C,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,GAAG,SAAS,MAAM,CAAC,CAAC;QACjE,IAAI,CAAC,kBAAkB;YACrB,oBAAoB,IAAI,gCAAgC,CAAC;IAC7D,CAAC;IAEM,KAAK,CAAC,GAAG,CAAI,CAAmB;QACrC,GAAG,CAAC,2CAA2C,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;QAEvE,OAAO,IAAI,EAAE,CAAC;YACZ,IAAI,MAAM,IAAI,CAAC,kBAAkB,EAAE,EAAE,CAAC;gBACpC,0BAA0B;gBAC1B,OAAO,IAAI,CAAC,+BAA+B,CAAC,CAAC,CAAC,CAAC;YACjD,CAAC;YAED,qBAAqB;YACrB,IAAI,IAAI,CAAC,kBAAkB,EAAE,EAAE,CAAC;gBAC9B,gGAAgG;gBAChG,GAAG,CACD,uDAAuD,IAAI,CAAC,cAAc,GAAG,CAC9E,CAAC;gBACF,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC1B,CAAC;iBAAM,CAAC;gBACN,OAAO;gBACP,MAAM,KAAK,CAAC,6BAA6B,GAAG,IAAI,CAAC,CAAC;YACpD,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,CAAC,kBAAkB;QACtB,IAAI,CAAC;YACH,0CAA0C;YAC1C,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YAC3D,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,WAAW,CAAwB,CAAC,CAAC,CAAC;YAEtC,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACxB,wDAAwD;gBACxD,OAAO,KAAK,CAAC;YACf,CAAC;YAED,MAAM,IAAI,qBAAqB,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,+BAA+B,CAAI,CAAmB;QAC1D,GAAG,CAAC,2BAA2B,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;QAEvD,IAAI,CAAC;YACH,OAAO,MAAM,CAAC,EAAE,CAAC;QACnB,CAAC;gBAAS,CAAC;YACT,oBAAoB;YACpB,GAAG,CAAC,2BAA2B,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;YACvD,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACxB,GAAG,CAAC,2BAA2B,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;IAED,kBAAkB;QAChB,IAAI,QAAQ,CAAC;QACb,IAAI,CAAC;YACH,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC9C,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,WAAW,CAAwB,CAAC,CAAC,CAAC;YAEtC,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACxB,mGAAmG;gBACnG,OAAO,KAAK,CAAC;YACf,CAAC;YAED,MAAM,IAAI,qBAAqB,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAChD,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC1C,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAC;QAEhD,OAAO,IAAI,GAAG,IAAI,CAAC,kBAAkB,CAAC;IACxC,CAAC;IAED,gBAAgB;QACd,IAAI,CAAC;YACH,GAAG,CAAC,gCAAgC,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;YAC5D,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,WAAW,CAAwB,CAAC,CAAC,CAAC;YAEtC,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACxB,mGAAmG;gBACnG,OAAO;YACT,CAAC;YAED,MAAM,IAAI,qBAAqB,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;CACF"}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@nomicfoundation/hardhat-utils",
+  "version": "3.0.0-next.0",
+  "description": "Utilities for Hardhat and its plugins",
+  "homepage": "https://github.com/nomicfoundation/hardhat/tree/v-next/v-next/hardhat-utils",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NomicFoundation/hardhat",
+    "directory": "v-next/hardhat-utils"
+  },
+  "author": "Nomic Foundation",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./bigint": "./dist/src/bigint.js",
+    "./bytecode": "./dist/src/bytecode.js",
+    "./bytes": "./dist/src/bytes.js",
+    "./ci": "./dist/src/ci.js",
+    "./common-errors": "./dist/src/common-errors.js",
+    "./crypto": "./dist/src/crypto.js",
+    "./date": "./dist/src/date.js",
+    "./debug": "./dist/src/debug.js",
+    "./error": "./dist/src/error.js",
+    "./eth": "./dist/src/eth.js",
+    "./fs": "./dist/src/fs.js",
+    "./global-dir": "./dist/src/global-dir.js",
+    "./hex": "./dist/src/hex.js",
+    "./lang": "./dist/src/lang.js",
+    "./number": "./dist/src/number.js",
+    "./package": "./dist/src/package.js",
+    "./path": "./dist/src/path.js",
+    "./request": "./dist/src/request.js",
+    "./string": "./dist/src/string.js",
+    "./stream": "./dist/src/stream.js",
+    "./subprocess": "./dist/src/subprocess.js",
+    "./synchronization": "./dist/src/synchronization.js"
+  },
+  "keywords": [
+    "ethereum",
+    "smart-contracts",
+    "hardhat"
+  ],
+  "files": [
+    "dist/src/",
+    "src/",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@eslint-community/eslint-plugin-eslint-comments": "^4.3.0",
+    "@nomicfoundation/hardhat-node-test-reporter": "^3.0.0-next.0",
+    "@types/bn.js": "^5.1.5",
+    "@types/debug": "^4.1.7",
+    "@types/node": "^20.14.9",
+    "@typescript-eslint/eslint-plugin": "^7.7.1",
+    "@typescript-eslint/parser": "^7.7.1",
+    "eslint": "8.57.0",
+    "eslint-config-prettier": "9.1.0",
+    "eslint-import-resolver-typescript": "^3.6.1",
+    "eslint-plugin-import": "2.29.1",
+    "eslint-plugin-no-only-tests": "3.1.0",
+    "expect-type": "^0.19.0",
+    "prettier": "3.2.5",
+    "rimraf": "^5.0.5",
+    "tsx": "^4.19.3",
+    "typescript": "~5.5.0",
+    "typescript-eslint": "7.7.1"
+  },
+  "dependencies": {
+    "debug": "^4.3.2",
+    "env-paths": "^2.2.0",
+    "ethereum-cryptography": "^2.2.1",
+    "fast-equals": "^5.0.1",
+    "rfdc": "^1.3.1",
+    "undici": "^6.16.1"
+  },
+  "scripts": {
+    "lint": "pnpm prettier --check && pnpm eslint",
+    "lint:fix": "pnpm prettier --write && pnpm eslint --fix",
+    "eslint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "prettier": "prettier \"**/*.{ts,js,md,json}\"",
+    "test": "node --import tsx/esm --test --test-reporter=@nomicfoundation/hardhat-node-test-reporter \"test/*.ts\" \"test/!(fixture-projects|helpers)/**/*.ts\"",
+    "test:only": "node --import tsx/esm --test --test-only --test-reporter=@nomicfoundation/hardhat-node-test-reporter \"test/*.ts\" \"test/!(fixture-projects|helpers)/**/*.ts\"",
+    "pretest": "pnpm build",
+    "pretest:only": "pnpm build",
+    "build": "tsc --build .",
+    "clean": "rimraf dist"
+  }
+}

package/src/bigint.ts

@@ -0,0 +1,61 @@
+import { InvalidParameterError } from "./common-errors.js";
+import { unreachable } from "./error.js";
+
+/**
+ * Returns the minimum of two bigints.
+ *
+ * @param x The first number to compare.
+ * @param y The second number to compare.
+ * @returns The smaller of the two numbers.
+ */
+export function min(x: bigint, y: bigint): bigint {
+  return x < y ? x : y;
+}
+
+/**
+ * Returns the maximum of two bigints.
+ *
+ * @param x The first number to compare.
+ * @param y The second number to compare.
+ * @returns The larger of the two numbers.
+ */
+export function max(x: bigint, y: bigint): bigint {
+  return x > y ? x : y;
+}
+
+/**
+ * Converts a value to a bigint.
+ *
+ * This function supports several types of input:
+ * - `number`: Must be an integer and a safe integer. If it's not, an error is thrown.
+ * - `bigint`: Returned as is.
+ * - `string`: Converted to a bigint using the BigInt constructor.
+ *
+ * If the input is of an unsupported type, an error is thrown.
+ *
+ * @param value The value to convert to a bigint.
+ * @returns The input value converted to a bigint.
+ * @throws InvalidParameterError If the input value cannot be converted to a bigint.
+ */
+export function toBigInt(value: number | string | bigint): bigint {
+  switch (typeof value) {
+    case "number":
+      if (!Number.isInteger(value)) {
+        throw new InvalidParameterError(`${value} is not an integer`);
+      }
+      if (!Number.isSafeInteger(value)) {
+        throw new InvalidParameterError(
+          `Integer ${value} is unsafe. Consider using ${value}n instead. For more details, see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger`,
+        );
+      }
+    // `break;` intentionally omitted. fallthrough desired.
+    case "string":
+    case "bigint":
+      return BigInt(value);
+    default:
+      unreachable(
+        value,
+        new InvalidParameterError(`Unsupported type: ${typeof value}`),
+      );
+  }
+}

package/src/bytecode.ts

@@ -0,0 +1,90 @@
+import type { PrefixedHexString } from "./hex.js";
+import type {
+  Artifact,
+  LibraryAddresses,
+  LibraryLink,
+} from "./internal/bytecode.js";
+
+import { getPrefixedHexString, getUnprefixedHexString } from "./hex.js";
+import {
+  checkAmbiguousOrUnnecessaryLinks,
+  checkMissingLibraryAddresses,
+  checkOverlappingLibraryNames,
+  checkProvidedLibraryAddresses,
+} from "./internal/bytecode.js";
+
+/**
+ * Resolves the linked bytecode for a given contract artifact by substituting
+ * the required library placeholders within the bytecode with the provided
+ * library addresses.
+ *
+ * @param artifact The contract artifact containing the bytecode and link references.
+ * @param providedLibraries An object containing library names as keys and their addresses as values.
+ * @returns The linked bytecode with all required libraries correctly linked.
+ * @throws InvalidLibraryAddressError If any provided library address is invalid.
+ * @throws AmbiguousLibraryNameError If any provided library name matches multiple needed libraries.
+ * @throws UnnecessaryLibraryError If any provided library name is not needed by the contract.
+ * @throws OverlappingLibrariesError If any library is provided more than once.
+ * @throws MissingLibrariesError If any needed library address is missing.
+ */
+export function resolveLinkedBytecode(
+  artifact: Artifact,
+  providedLibraries: LibraryAddresses,
+): PrefixedHexString {
+  checkProvidedLibraryAddresses(providedLibraries);
+
+  const neededLibraries: LibraryLink[] = [];
+  for (const [sourceName, sourceLibraries] of Object.entries(
+    artifact.linkReferences,
+  )) {
+    for (const libraryName of Object.keys(sourceLibraries)) {
+      const libraryFqn = `${sourceName}:${libraryName}`;
+      const address =
+        providedLibraries[libraryFqn] ?? providedLibraries[libraryName];
+
+      neededLibraries.push({
+        sourceName,
+        libraryName,
+        libraryFqn,
+        address,
+      });
+    }
+  }
+
+  checkAmbiguousOrUnnecessaryLinks(providedLibraries, neededLibraries);
+  checkOverlappingLibraryNames(providedLibraries, neededLibraries);
+  checkMissingLibraryAddresses(neededLibraries);
+
+  return linkBytecode(artifact, neededLibraries);
+}
+
+/**
+ * Links the bytecode of a contract artifact with the provided library addresses.
+ * This function does not perform any validation on the provided libraries.
+ *
+ * @param artifact The contract artifact containing the bytecode and link references.
+ * @param libraries An array of LibraryLink objects representing the libraries to be linked.
+ * @returns The linked bytecode with all provided libraries correctly linked.
+ */
+export function linkBytecode(
+  artifact: Artifact,
+  libraries: LibraryLink[],
+): PrefixedHexString {
+  const { bytecode, linkReferences } = artifact;
+  let linkedBytecode = bytecode;
+
+  for (const { sourceName, libraryName, address } of libraries) {
+    const contractLinkReferences =
+      linkReferences[sourceName]?.[libraryName] ?? [];
+    const unprefixedAddress = getUnprefixedHexString(address);
+
+    for (const { start, length } of contractLinkReferences) {
+      linkedBytecode =
+        linkedBytecode.substring(0, 2 + start * 2) +
+        unprefixedAddress +
+        linkedBytecode.substring(2 + (start + length) * 2);
+    }
+  }
+
+  return getPrefixedHexString(linkedBytecode);
+}

package/src/bytes.ts

@@ -0,0 +1,51 @@
+/**
+ * Checks if a value is an instance of Uint8Array.
+ *
+ * @param value The value to check.
+ * @returns True if the value is a Uint8Array, false otherwise.
+ */
+export function isBytes(value: unknown): value is Uint8Array {
+  return value instanceof Uint8Array;
+}
+
+/**
+ * Pads a Uint8Array with zeros on the left to a specified length, or truncates
+ * it from the left if it's too long.
+ *
+ * @param bytes The Uint8Array to pad or truncate.
+ * @param length The desired length of the Uint8Array.
+ * @returns The padded or truncated Uint8Array.
+ */
+export function setLengthLeft(bytes: Uint8Array, length: number): Uint8Array {
+  if (bytes.length < length) {
+    const padded = new Uint8Array(length);
+    padded.set(bytes, length - bytes.length);
+    return padded;
+  }
+
+  return bytes.subarray(-length);
+}
+
+/**
+ * Checks if two Uint8Arrays are equal.
+ *
+ * @param x The first Uint8Array to compare.
+ * @param y The second Uint8Array to compare.
+ * @returns True if the Uint8Arrays are equal, false otherwise.
+ */
+export function equalsBytes(x: Uint8Array, y: Uint8Array): boolean {
+  return x.length === y.length && x.every((xVal, i) => xVal === y[i]);
+}
+
+/**
+ * Converts a UTF-8 encoded string into a byte array.
+ *
+ * @param utf8String The UTF-8 encoded string to convert to bytes.
+ * @returns A Uint8Array representing the byte sequence of the input UTF-8 string.
+ */
+export function utf8StringToBytes(utf8String: string): Uint8Array {
+  return new TextEncoder().encode(utf8String);
+}
+
+export { bytesToBigInt, bytesToNumber, numberToBytes } from "./number.js";
+export { bytesToHexString, hexStringToBytes } from "./hex.js";

package/src/ci.ts

@@ -0,0 +1,19 @@
+/**
+ * Checks whether the current process is running in a CI environment.
+ *
+ * @returns True if the current process is running in a CI environment.
+ */
+export function isCi(): boolean {
+  const env = process.env;
+
+  return (
+    env.GITHUB_ACTIONS !== undefined || // GitHub Actions
+    env.NOW !== undefined || // Vercel Now
+    env.DEPLOYMENT_ID !== undefined || // Vercel Now
+    env.CODEBUILD_BUILD_NUMBER !== undefined || // AWS CodeBuild
+    env.CI !== undefined || // Travis CI, CircleCI, Cirrus CI, GitLab CI, Appveyor, CodeShip, dsari
+    env.CONTINUOUS_INTEGRATION !== undefined || // Travis CI, Cirrus CI
+    env.BUILD_NUMBER !== undefined || // Jenkins, TeamCity
+    env.RUN_ID !== undefined // TaskCluster, dsari
+  );
+}

package/src/common-errors.ts

@@ -0,0 +1,7 @@
+import { CustomError } from "./error.js";
+
+export class InvalidParameterError extends CustomError {
+  constructor(message: string, cause?: Error) {
+    super(message, cause);
+  }
+}

package/src/crypto.ts

@@ -0,0 +1,35 @@
+import { keccak256 as keccak256Impl } from "ethereum-cryptography/keccak";
+
+/**
+ * Computes the Keccak-256 hash of the input bytes.
+ *
+ * @param bytes The input bytes to hash.
+ * @returns The Keccak-256 hash of the input bytes.
+ */
+export async function keccak256(bytes: Uint8Array): Promise<Uint8Array> {
+  return keccak256Impl(bytes);
+}
+
+/**
+ * Creates a non-cryptographic hash-based identifier for the given input.
+ *
+ * This function is primarily intended for generating unique identifiers from
+ * a given input string.
+ * It uses the SHA-1 hash algorithm, which is not cryptographically secure, but
+ * is sufficient for this use case as long as the input is not generated by an
+ * attacker.
+ *
+ * Note: The exact algorithm used (SHA-1) is not crucial for the function's
+ * purpose of generating unique identifiers, and could be replaced if needed.
+ *
+ * @param data The input string to be hashed.
+ * @returns The SHA-1 hash of the input string, represented as a
+ * hexadecimal string.
+ */
+export async function createNonCryptographicHashId(
+  data: string,
+): Promise<string> {
+  const message = new TextEncoder().encode(data);
+  const buffer = await crypto.subtle.digest("SHA-1", message);
+  return Buffer.from(buffer).toString("hex");
+}

package/src/date.ts

@@ -0,0 +1,28 @@
+/**
+ * Converts a string, number, or Date object to a Unix timestamp (seconds since the Unix Epoch).
+ *
+ * @param value The string to convert.
+ * @returns The Unix timestamp.
+ */
+export function toSeconds(value: string | number | Date): number {
+  return Math.floor(new Date(value).getTime() / 1000);
+}
+
+/**
+ * Converts a Unix timestamp to a Date object.
+ *
+ * @param timestamp The Unix timestamp to convert.
+ * @returns The Date object.
+ */
+export function secondsToDate(timestamp: number): Date {
+  return new Date(timestamp * 1000);
+}
+
+/**
+ * Gets the current Unix timestamp (seconds since the Unix Epoch).
+ *
+ * @returns The current Unix timestamp.
+ */
+export function now(): number {
+  return Math.floor(Date.now() / 1000);
+}

package/src/debug.ts

@@ -0,0 +1,38 @@
+import debugLib from "debug";
+
+/**
+ * A simple decorator that adds debug logging for when a method is entered and exited.
+ *
+ * This decorator is meant to be used for debugging purposes only. It should not be committed in runtime code.
+ *
+ * Example usage:
+ *
+ * ```
+ * class MyClass {
+ *   @withDebugLogs("MyClass:exampleClassMethod")
+ *   public function exampleClassMethod(...)
+ * }
+ * ```
+ */
+export function withDebugLogs<This, Args extends any[], Return>(
+  tag: string = "",
+) {
+  return function actualDecorator(
+    originalMethod: (this: This, ...args: Args) => Return,
+    _context: ClassMethodDecoratorContext<
+      This,
+      (this: This, ...args: Args) => Return
+    >,
+  ): (this: This, ...args: Args) => Return {
+    const log = debugLib(`hardhat:dev:core${tag === "" ? "" : `:${tag}`}`);
+
+    function replacementMethod(this: This, ...args: Args): Return {
+      log(`Entering method with args:`, args);
+      const result = originalMethod.call(this, ...args);
+      log(`Exiting method.`);
+      return result;
+    }
+
+    return replacementMethod;
+  };
+}

package/src/error.ts

@@ -0,0 +1,105 @@
+/**
+ * Abstract custom error class, which inherits from the built-in Error class,
+ * making sure that the standard errror properties are set, and the stack trace
+ * is not polluted with the custom error class' code.
+ *
+ * This class supports the `cause` property, which can be used to pass the
+ * original error that caused the custom error to be thrown. Note that it needs
+ * to be an instance of the built-in Error class, or a subclass of it. See `ensureError`
+ * for a convinient way of using it.
+ *
+ * @example
+ * ```ts
+ * class MyCustomError extends CustomError {
+ * }
+ *
+ * try {
+ *   mayThrow();
+ * } catch (error) {
+ *   ensureError(error);
+ *   throw new MyCustomError('Something went wrong', error);
+ * }
+ * ```
+ */
+export abstract class CustomError extends Error {
+  public override stack!: string;
+
+  constructor(message: string, cause?: Error) {
+    super(message, cause !== undefined ? { cause } : undefined);
+    this.name = this.constructor.name;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * Ensures that the provided value is an instance of an error.
+ *
+ * @example
+ * This function is meant to be used in a catch block to ensure that you caught the right error.
+ *
+ * ```ts
+ * // Ensuring that you got an Error
+ * try {
+ *   mayThrow();
+ * } catch (error) {
+ *   ensureError(error);
+ *   console.err(error.message);
+ * }
+ *
+ * // Ensuring that you got a specific error
+ * try {
+ *   mayThrow();
+ * } catch (error) {
+ *   ensureError(error, MyError);
+ *   console.err(error.myMessage());
+ * }
+ * ```
+ *
+ * @param thrown The value to check.
+ * @param ErrorType The error type to check against.
+ * @throws The value if its not an instance of the specified error type.
+ */
+export function ensureError<ErrorT extends Error>(
+  thrown: unknown,
+  ErrorType?: new (...args: any[]) => ErrorT,
+): asserts thrown is ErrorT {
+  if (ErrorType === undefined) {
+    if (thrown instanceof Error) {
+      return;
+    }
+
+    throw thrown;
+  }
+
+  if (thrown instanceof ErrorType) {
+    return;
+  }
+
+  throw thrown;
+}
+
+/**
+ * Throws an error for an unreachable code path. This function is typically
+ * used in a default case of a switch statement where all possible values of
+ * the switched variable should be handled in other cases. If the default case
+ * is reached, it means that an unexpected value was encountered, so an error
+ * is thrown.
+ *
+ * Note: The `@typescript-eslint/switch-exhaustiveness-check` rule checks for
+ * exhaustiveness in switch statements by comparing the types of the switch
+ * expression and the case clauses. However, it only works with union types and
+ * enum types. If you're switching on the result of the `typeof` operator or
+ * any other expression that doesn't return a union type or an enum type, this
+ * rule cannot enforce exhaustiveness. In such cases, you can use this function
+ * in the default case to ensure that an error is thrown if an unexpected value
+ * is encountered.
+ *
+ * @param _value The unexpected value. This parameter is unused and is only for
+ * the purpose of type checking.
+ * @param error The error to throw.
+ * @returns This function never returns normally. It always throws an error.
+ * @throws Will throw an error when called.
+ */
+export function unreachable(_value: never, error: Error): never {
+  throw error;
+}