hardhat 2.18.3 → 2.19.0

package/src/builtin-tasks/vars.ts

@@ -0,0 +1,54 @@
+import { HardhatError } from "../internal/core/errors";
+import { scope } from "../internal/core/config/config-env";
+import { ERRORS } from "../internal/core/errors-list";
+
+const varsScope = scope("vars", "Manage your configuration variables");
+
+varsScope
+  .task("set", "Set the value of a configuration variable")
+  .addPositionalParam("var", "The name of the variable")
+  .addOptionalPositionalParam(
+    "value",
+    "The value to store. Omit to be prompted for it."
+  )
+  .setAction(async () => {
+    throw new HardhatError(ERRORS.VARS.ONLY_MANAGED_IN_CLI);
+  });
+
+varsScope
+  .task("get", "Get the value of a configuration variable")
+  .addPositionalParam("var", "The name of the variable")
+  .setAction(async () => {
+    throw new HardhatError(ERRORS.VARS.ONLY_MANAGED_IN_CLI);
+  });
+
+varsScope
+  .task("list", "List all the configuration variables")
+  .setAction(async () => {
+    throw new HardhatError(ERRORS.VARS.ONLY_MANAGED_IN_CLI);
+  });
+
+varsScope
+  .task("delete", "Delete a configuration variable")
+  .addPositionalParam("var", "The name of the variable")
+  .setAction(async () => {
+    throw new HardhatError(ERRORS.VARS.ONLY_MANAGED_IN_CLI);
+  });
+
+varsScope
+  .task(
+    "path",
+    "Show the path of the file where all the configuration variables are stored"
+  )
+  .setAction(async () => {
+    throw new HardhatError(ERRORS.VARS.ONLY_MANAGED_IN_CLI);
+  });
+
+varsScope
+  .task(
+    "setup",
+    "Show how to setup the configuration variables used by this project"
+  )
+  .setAction(async () => {
+    throw new HardhatError(ERRORS.VARS.ONLY_MANAGED_IN_CLI);
+  });

package/src/internal/cli/cli.ts

@@ -1,7 +1,6 @@
 import chalk from "chalk";
 import debug from "debug";
 import "source-map-support/register";
-
 import {
   TASK_COMPILE,
   TASK_HELP,
@@ -50,6 +49,7 @@ import {
   installHardhatVSCode,
   isHardhatVSCodeInstalled,
 } from "./hardhat-vscode-installation";
+import { handleVars } from "./vars";
 
 const log = debug("hardhat:core:cli");
 
@@ -212,6 +212,10 @@ async function main() {
 
     const ctx = HardhatContext.createHardhatContext();
 
+    if (scopeOrTaskName === "vars" && allUnparsedCLAs.length > 1) {
+      process.exit(await handleVars(allUnparsedCLAs, hardhatArguments.config));
+    }
+
     const { resolvedConfig, userConfig } = loadConfigAndTasks(
       hardhatArguments,
       {

package/src/internal/cli/vars.ts

@@ -0,0 +1,301 @@
+import chalk from "chalk";
+import debug from "debug";
+import { HardhatError, assertHardhatInvariant } from "../core/errors";
+import { ERRORS } from "../core/errors-list";
+import { HardhatContext } from "../context";
+import { VarsManagerSetup } from "../core/vars/vars-manager-setup";
+import {
+  importCsjOrEsModule,
+  resolveConfigPath,
+} from "../core/config/config-loading";
+import { getVarsFilePath } from "../util/global-dir";
+import { ArgumentsParser } from "./ArgumentsParser";
+import { emoji } from "./emoji";
+
+const log = debug("hardhat:cli:vars");
+
+export async function handleVars(
+  allUnparsedCLAs: string[],
+  configPath: string | undefined
+): Promise<number> {
+  const { taskDefinition, taskArguments } =
+    await getTaskDefinitionAndTaskArguments(allUnparsedCLAs);
+
+  switch (taskDefinition.name) {
+    case "set":
+      return set(taskArguments.var, taskArguments.value);
+    case "get":
+      return get(taskArguments.var);
+    case "list":
+      return list();
+    case "delete":
+      return del(taskArguments.var);
+    case "path":
+      return path();
+    case "setup":
+      return setup(configPath);
+    default:
+      console.error(chalk.red(`Invalid task '${taskDefinition.name}'`));
+      return 1; // Error code
+  }
+}
+
+async function set(key: string, value?: string): Promise<number> {
+  const varsManager = HardhatContext.getHardhatContext().varsManager;
+
+  varsManager.validateKey(key);
+
+  varsManager.set(key, value ?? (await getVarValue()));
+
+  if (process.stdout.isTTY) {
+    console.warn(
+      `The configuration variable has been stored in ${varsManager.getStoragePath()}`
+    );
+  }
+
+  return 0;
+}
+
+function get(key: string): number {
+  const value = HardhatContext.getHardhatContext().varsManager.get(key);
+
+  if (value !== undefined) {
+    console.log(value);
+    return 0;
+  }
+
+  console.warn(
+    chalk.yellow(
+      `The configuration variable '${key}' is not set in ${HardhatContext.getHardhatContext().varsManager.getStoragePath()}`
+    )
+  );
+  return 1;
+}
+
+function list(): number {
+  const keys = HardhatContext.getHardhatContext().varsManager.list();
+  const varsStoragePath =
+    HardhatContext.getHardhatContext().varsManager.getStoragePath();
+
+  if (keys.length > 0) {
+    keys.forEach((k) => console.log(k));
+
+    if (process.stdout.isTTY) {
+      console.warn(
+        `\nAll configuration variables are stored in ${varsStoragePath}`
+      );
+    }
+  } else {
+    if (process.stdout.isTTY) {
+      console.warn(
+        chalk.yellow(
+          `There are no configuration variables stored in ${varsStoragePath}`
+        )
+      );
+    }
+  }
+
+  return 0;
+}
+
+function del(key: string): number {
+  const varsStoragePath =
+    HardhatContext.getHardhatContext().varsManager.getStoragePath();
+
+  if (HardhatContext.getHardhatContext().varsManager.delete(key)) {
+    if (process.stdout.isTTY) {
+      console.warn(
+        `The configuration variable was deleted from ${varsStoragePath}`
+      );
+    }
+    return 0;
+  }
+
+  console.warn(
+    chalk.yellow(
+      `There is no configuration variable '${key}' to delete from ${varsStoragePath}`
+    )
+  );
+
+  return 1;
+}
+
+function path() {
+  console.log(HardhatContext.getHardhatContext().varsManager.getStoragePath());
+  return 0;
+}
+
+function setup(configPath: string | undefined) {
+  log("Switching to SetupVarsManager to collect vars");
+
+  const varsManagerSetup = new VarsManagerSetup(getVarsFilePath());
+
+  HardhatContext.getHardhatContext().varsManager = varsManagerSetup;
+
+  try {
+    log("Loading config and tasks to trigger vars collection");
+    loadConfigFile(configPath);
+  } catch (err: any) {
+    console.error(
+      chalk.red(
+        "There is an error in your Hardhat configuration file. Please double check it.\n"
+      )
+    );
+
+    // eslint-disable-next-line @nomicfoundation/hardhat-internal-rules/only-hardhat-error
+    throw err;
+  }
+
+  listVarsToSetup(varsManagerSetup);
+
+  return 0;
+}
+
+// The code below duplicates a section from the 'loadConfigAndTasks' function.
+// While we could have refactored the 'config-loading.ts' module to make this logic reusable,
+// it would have added complexity and potentially made the code harder to understand.
+function loadConfigFile(configPath: string | undefined) {
+  const configEnv = require(`../core/config/config-env`);
+
+  // Load all the functions and objects exported by the 'config-env' file in a global scope
+  const globalAsAny: any = global;
+  Object.entries(configEnv).forEach(
+    ([key, value]) => (globalAsAny[key] = value)
+  );
+
+  const resolvedConfigPath = resolveConfigPath(configPath);
+  importCsjOrEsModule(resolvedConfigPath);
+}
+
+async function getVarValue(): Promise<string> {
+  const { default: enquirer } = await import("enquirer");
+
+  const response: { value: string } = await enquirer.prompt({
+    type: "password",
+    name: "value",
+    message: "Enter value:",
+  });
+
+  return response.value;
+}
+
+function listVarsToSetup(varsManagerSetup: VarsManagerSetup) {
+  const HH_SET_COMMAND = "npx hardhat vars set";
+
+  const requiredKeysToSet = varsManagerSetup.getRequiredVarsToSet();
+  const optionalKeysToSet = varsManagerSetup.getOptionalVarsToSet();
+
+  if (requiredKeysToSet.length === 0 && optionalKeysToSet.length === 0) {
+    console.log(
+      chalk.green(
+        "There are no configuration variables that need to be set for this project"
+      )
+    );
+    console.log();
+    printAlreadySetKeys(varsManagerSetup);
+    return;
+  }
+
+  if (requiredKeysToSet.length > 0) {
+    console.log(
+      chalk.bold(
+        `${emoji("❗ ")}The following configuration variables need to be set:\n`
+      )
+    );
+    console.log(
+      requiredKeysToSet.map((k) => `  ${HH_SET_COMMAND} ${k}`).join("\n")
+    );
+    console.log();
+  }
+
+  if (optionalKeysToSet.length > 0) {
+    console.log(
+      chalk.bold(
+        `${emoji("💡 ")}The following configuration variables are optional:\n`
+      )
+    );
+    console.log(
+      optionalKeysToSet.map((k) => `  ${HH_SET_COMMAND} ${k}`).join("\n")
+    );
+    console.log();
+  }
+
+  printAlreadySetKeys(varsManagerSetup);
+}
+
+function printAlreadySetKeys(varsManagerSetup: VarsManagerSetup) {
+  const requiredKeysAlreadySet = varsManagerSetup.getRequiredVarsAlreadySet();
+  const optionalKeysAlreadySet = varsManagerSetup.getOptionalVarsAlreadySet();
+  const envVars = varsManagerSetup.getEnvVars();
+
+  if (
+    requiredKeysAlreadySet.length === 0 &&
+    optionalKeysAlreadySet.length === 0 &&
+    envVars.length === 0
+  ) {
+    return;
+  }
+
+  console.log(
+    `${chalk.bold(`${emoji("✔️  ")}Configuration variables already set:`)}`
+  );
+  console.log();
+
+  if (requiredKeysAlreadySet.length > 0) {
+    console.log("  Mandatory:");
+    console.log(requiredKeysAlreadySet.map((x) => `    ${x}`).join("\n"));
+    console.log();
+  }
+
+  if (optionalKeysAlreadySet.length > 0) {
+    console.log("  Optional:");
+    console.log(optionalKeysAlreadySet.map((x) => `    ${x}`).join("\n"));
+    console.log();
+  }
+
+  if (envVars.length > 0) {
+    console.log("  Set via environment variables:");
+    console.log(envVars.map((x) => `    ${x}`).join("\n"));
+    console.log();
+  }
+}
+
+async function getTaskDefinitionAndTaskArguments(allUnparsedCLAs: string[]) {
+  const ctx = HardhatContext.getHardhatContext();
+  ctx.setConfigLoadingAsStarted();
+  require("../../builtin-tasks/vars");
+  ctx.setConfigLoadingAsFinished();
+
+  const argumentsParser = new ArgumentsParser();
+
+  const taskDefinitions = ctx.tasksDSL.getTaskDefinitions();
+  const scopesDefinitions = ctx.tasksDSL.getScopesDefinitions();
+
+  const { scopeName, taskName, unparsedCLAs } =
+    argumentsParser.parseScopeAndTaskNames(
+      allUnparsedCLAs,
+      taskDefinitions,
+      scopesDefinitions
+    );
+
+  assertHardhatInvariant(
+    scopeName === "vars",
+    "This function should only be called to handle tasks under the 'vars' scope"
+  );
+
+  const taskDefinition = ctx.tasksDSL.getTaskDefinition(scopeName, taskName);
+
+  if (taskDefinition === undefined) {
+    throw new HardhatError(ERRORS.ARGUMENTS.UNRECOGNIZED_SCOPED_TASK, {
+      scope: scopeName,
+      task: taskName,
+    });
+  }
+
+  const taskArguments = argumentsParser.parseTaskArguments(
+    taskDefinition,
+    unparsedCLAs
+  );
+
+  return { taskDefinition, taskArguments };
+}

package/src/internal/context.ts

@@ -8,7 +8,10 @@ import {
 
 import { assertHardhatInvariant, HardhatError } from "./core/errors";
 import { ERRORS } from "./core/errors-list";
+import { VarsManagerSetup } from "./core/vars/vars-manager-setup";
+import { VarsManager } from "./core/vars/vars-manager";
 import { TasksDSL } from "./core/tasks/dsl";
+import { getVarsFilePath } from "./util/global-dir";
 import { getRequireCachedFiles } from "./util/platform";
 
 export type GlobalWithHardhatContext = typeof global & {
@@ -16,6 +19,10 @@ export type GlobalWithHardhatContext = typeof global & {
 };
 
 export class HardhatContext {
+  constructor() {
+    this.varsManager = new VarsManager(getVarsFilePath());
+  }
+
   public static isCreated(): boolean {
     const globalWithHardhatContext = global as GlobalWithHardhatContext;
     return globalWithHardhatContext.__hardhatContext !== undefined;
@@ -49,6 +56,7 @@ export class HardhatContext {
   public readonly environmentExtenders: EnvironmentExtender[] = [];
   public environment?: HardhatRuntimeEnvironment;
   public readonly providerExtenders: ProviderExtender[] = [];
+  public varsManager: VarsManager | VarsManagerSetup;
 
   public readonly configExtenders: ConfigExtender[] = [];
 

package/src/internal/core/config/config-env.ts

@@ -9,6 +9,8 @@ import {
   TaskArguments,
 } from "../../../types";
 import { HardhatContext } from "../../context";
+import { HardhatError } from "../errors";
+import { ERRORS } from "../errors-list";
 import * as argumentTypes from "../params/argumentTypes";
 
 /**
@@ -173,3 +175,55 @@ export function experimentalAddHardhatNetworkMessageTraceHook(
   const ctx = HardhatContext.getHardhatContext();
   ctx.experimentalHardhatNetworkMessageTraceHooks.push(hook);
 }
+
+/**
+ * This object provides methods to interact with the configuration variables.
+ */
+export const vars = {
+  has: hasVar,
+  get: getVar,
+};
+
+/**
+ * Checks if a configuration variable exists.
+ *
+ * @remarks
+ * This method, when used during setup (via `npx hardhat vars setup`), will mark the variable as optional.
+ *
+ * @param varName - The name of the variable to check.
+ *
+ * @returns `true` if the variable exists, `false` otherwise.
+ */
+function hasVar(varName: string): boolean {
+  // varsManager will be an instance of VarsManager or VarsManagerSetup depending on the context (vars setup mode or not)
+  return HardhatContext.getHardhatContext().varsManager.has(varName, true);
+}
+
+/**
+ * Gets the value of the given configuration variable.
+ *
+ * @remarks
+ * This method, when used during setup (via `npx hardhat vars setup`), will mark the variable as required,
+ * unless a default value is provided.
+ *
+ * @param varName - The name of the variable to retrieve.
+ * @param [defaultValue] - An optional default value to return if the variable does not exist.
+ *
+ * @returns The value of the configuration variable if it exists, or the default value if provided.
+ *
+ * @throws HH1201 if the variable does not exist and no default value is set.
+ */
+function getVar(varName: string, defaultValue?: string): string {
+  // varsManager will be an instance of VarsManager or VarsManagerSetup depending on the context (vars setup mode or not)
+  const value = HardhatContext.getHardhatContext().varsManager.get(
+    varName,
+    defaultValue,
+    true
+  );
+
+  if (value !== undefined) return value;
+
+  throw new HardhatError(ERRORS.VARS.VALUE_NOT_FOUND_FOR_VAR, {
+    value: varName,
+  });
+}

package/src/internal/core/config/config-loading.ts

@@ -25,7 +25,7 @@ import { DEFAULT_SOLC_VERSION } from "./default-config";
 
 const log = debug("hardhat:core:config");
 
-function importCsjOrEsModule(filePath: string): any {
+export function importCsjOrEsModule(filePath: string): any {
   try {
     const imported = require(filePath);
     return imported.default !== undefined ? imported.default : imported;

package/src/internal/core/errors-list.ts

@@ -41,6 +41,7 @@ export const ERROR_RANGES: {
   INTERNAL: { min: 900, max: 999, title: "Internal Hardhat errors" },
   SOURCE_NAMES: { min: 1000, max: 1099, title: "Source name errors" },
   CONTRACT_NAMES: { min: 1100, max: 1199, title: "Contract name errors" },
+  VARS: { min: 1200, max: 1299, title: "Connfiguration variables errors" },
 };
 
 export const ERRORS = {
@@ -643,7 +644,7 @@ Please double check your task definitions.`,
   ARGUMENTS: {
     INVALID_ENV_VAR_VALUE: {
       number: 300,
-      message: "Invalid environment variable %varName%'s value: %value%",
+      message: "Invalid environment variable '%varName%' with value: '%value%'",
       title: "Invalid environment variable value",
       description: `You are setting one of Hardhat's arguments using an environment variable, but it has an incorrect value.
 
@@ -1298,6 +1299,43 @@ A fully qualified name should look like file.sol:Contract`,
       shouldBeReported: false,
     },
   },
+  VARS: {
+    ONLY_MANAGED_IN_CLI: {
+      number: 1200,
+      title: "Configuration variables can only be managed from the CLI",
+      message:
+        "Configuration variables can only be managed from the CLI. They cannot be modified programmatically.",
+      description: `Configuration variables can only be managed from the CLI. They cannot be modified programmatically.`,
+      shouldBeReported: false,
+    },
+    VALUE_NOT_FOUND_FOR_VAR: {
+      number: 1201,
+      title: "Configuration variable is not set",
+      message:
+        "Cannot find a value for the configuration variable '%value%'. Use 'npx hardhat vars set %value%' to set it or 'npx hardhat vars setup' to list all the configuration variables used by this project.",
+      description: `Cannot find a value for a mandatory configuration variable.
+
+Use 'npx hardhat vars set VAR' to set it or 'npx hardhat vars setup' to list all the configuration variables used by this project.`,
+      shouldBeReported: false,
+    },
+    INVALID_CONFIG_VAR_NAME: {
+      number: 1202,
+      title: "Invalid name for a configuration variable",
+      message:
+        "Invalid name for a configuration variable: '%value%'. Configuration variables can only have alphanumeric characters and underscores, and they cannot start with a number.",
+      description: `Invalid name for a configuration variable.
+
+Configuration variables can only have alphanumeric characters and underscores, and they cannot start with a number.`,
+      shouldBeReported: false,
+    },
+    INVALID_EMPTY_VALUE: {
+      number: 1203,
+      title: "Invalid empty value for configuration variable",
+      message: "A configuration variable cannot have an empty value.",
+      description: "A configuration variable cannot have an empty value.",
+      shouldBeReported: false,
+    },
+  },
 };
 
 /**

package/src/internal/core/tasks/builtin-tasks.ts

@@ -6,4 +6,5 @@ import "../../../builtin-tasks/flatten";
 import "../../../builtin-tasks/help";
 import "../../../builtin-tasks/node";
 import "../../../builtin-tasks/run";
+import "../../../builtin-tasks/vars";
 import "../../../builtin-tasks/test";

package/src/internal/core/vars/vars-manager-setup.ts

@@ -0,0 +1,124 @@
+import debug from "debug";
+import { VarsManager } from "./vars-manager";
+
+const log = debug("hardhat:core:vars:varsManagerSetup");
+
+/**
+ * This class is ONLY used when collecting the required and optional vars that have to be filled by the user
+ */
+export class VarsManagerSetup extends VarsManager {
+  private readonly _getVarsAlreadySet: Set<string>;
+  private readonly _hasVarsAlreadySet: Set<string>;
+  private readonly _getVarsWithDefaultValueAlreadySet: Set<string>;
+
+  private readonly _getVarsToSet: Set<string>;
+  private readonly _hasVarsToSet: Set<string>;
+  private readonly _getVarsWithDefaultValueToSet: Set<string>;
+
+  constructor(varsFilePath: string) {
+    log("Creating a new instance of VarsManagerSetup");
+
+    super(varsFilePath);
+
+    this._getVarsAlreadySet = new Set();
+    this._hasVarsAlreadySet = new Set();
+    this._getVarsWithDefaultValueAlreadySet = new Set();
+
+    this._getVarsToSet = new Set();
+    this._hasVarsToSet = new Set();
+    this._getVarsWithDefaultValueToSet = new Set();
+  }
+
+  // Checks if the key exists, and updates sets accordingly.
+  // Ignore the parameter 'includeEnvs' defined in the parent class because during setup env vars are ignored.
+  public has(key: string): boolean {
+    log(`function 'has' called with key '${key}'`);
+
+    const hasKey = super.has(key);
+
+    if (hasKey) {
+      this._hasVarsAlreadySet.add(key);
+    } else {
+      this._hasVarsToSet.add(key);
+    }
+
+    return hasKey;
+  }
+
+  // Gets the value for the provided key, and updates sets accordingly.
+  // Ignore the parameter 'includeEnvs' defined in the parent class because during setup env vars are ignored.
+  public get(key: string, defaultValue?: string): string {
+    log(`function 'get' called with key '${key}'`);
+
+    const varAlreadySet = super.has(key);
+
+    if (varAlreadySet) {
+      if (defaultValue !== undefined) {
+        this._getVarsWithDefaultValueAlreadySet.add(key);
+      } else {
+        this._getVarsAlreadySet.add(key);
+      }
+    } else {
+      if (defaultValue !== undefined) {
+        this._getVarsWithDefaultValueToSet.add(key);
+      } else {
+        this._getVarsToSet.add(key);
+      }
+    }
+
+    // Do not return undefined to avoid throwing an error
+    return super.get(key, defaultValue) ?? "";
+  }
+
+  public getRequiredVarsAlreadySet(): string[] {
+    return this._getRequired(this._getVarsAlreadySet, this._hasVarsAlreadySet);
+  }
+
+  public getOptionalVarsAlreadySet(): string[] {
+    return this._getOptionals(
+      this._getVarsAlreadySet,
+      this._hasVarsAlreadySet,
+      this._getVarsWithDefaultValueAlreadySet
+    );
+  }
+
+  public getRequiredVarsToSet(): string[] {
+    return this._getRequired(this._getVarsToSet, this._hasVarsToSet);
+  }
+
+  public getOptionalVarsToSet(): string[] {
+    return this._getOptionals(
+      this._getVarsToSet,
+      this._hasVarsToSet,
+      this._getVarsWithDefaultValueToSet
+    );
+  }
+
+  // How to calculate required and optional variables:
+  //
+  // G = get function
+  // H = has function
+  // GD = get function with default value
+  //
+  // optional variables = H + (GD - G)
+  // required variables = G - H
+  private _getRequired(getVars: Set<string>, hasVars: Set<string>): string[] {
+    return Array.from(getVars).filter((k) => !hasVars.has(k));
+  }
+
+  private _getOptionals(
+    getVars: Set<string>,
+    hasVars: Set<string>,
+    getVarsWithDefault: Set<string>
+  ): string[] {
+    const result = new Set(hasVars);
+
+    for (const k of getVarsWithDefault) {
+      if (!getVars.has(k)) {
+        result.add(k);
+      }
+    }
+
+    return Array.from(result);
+  }
+}