Add support for extending providers

.changeset/mean-crews-wait.md

@@ -0,0 +1,5 @@
+---
+"hardhat": patch
+---
+
+Added support for extending the network provider

config/eslint/eslintrc.js

@@ -79,6 +79,12 @@ module.exports = {
         format: ["camelCase", "UPPER_CASE"],
         leadingUnderscore: "allow",
       },
+      {
+        selector: ["classProperty"],
+        modifiers: ["private"],
+        format: ["camelCase", "UPPER_CASE"],
+        leadingUnderscore: "require",
+      },
       {
         selector: "enumMember",
         format: ["UPPER_CASE"],

docs/src/content/hardhat-runner/docs/advanced/building-plugins.md

@@ -47,6 +47,60 @@ Hello, Hardhat!
 
 This is literally all it takes to put together a plugin for Hardhat. Now `hi` is available to be used in the Hardhat console, your tasks, tests and other plugins.
 
+## Extending the Hardhat provider
+
+Next, we can take a look at how to add features on top of the default provider offered by Hardhat, found on `hre.network.provider`. Doing this, any extra functionality you add will be available everywhere, just as it would if you extend the [Hardhat Runtime Environment](#extending-the-hardhat-runtime-environment).
+
+The Hardhat provider is configured through a queue of extension functions that you can add to by using the `extendProvider()` function. It receives one parameter which is a callback to be executed after first call to `hre.network.provider.request()` is made. This happens only once. If `extendProvider` is called multiple times, its callbacks will be executed in order, and Hardhat will wait on each one to finish before executing the next one. Returning an entirely new provider is possible but not advisable.
+
+It's important to keep in mind that after all callbacks are executed, the provider will be wrapped by Hardhat one last time so it's backwards compatible with old non-standard implementations. This boils down to adding both `send` and `sendAsync` methods, which defer to the main `request`. Lastly, each callback added is `async`, so we should be careful when adding any functionality that might take a long time to resolve.
+
+For example, adding the following to `hardhat.config.js`:
+
+```js
+import { ProviderWrapper } from 'hardhat/plugins'
+
+class FixedGasProvider extends ProviderWrapper {
+  constructor(
+    public readonly gasPrice,
+    protected readonly _wrappedProvider
+  ) {
+    super(_wrappedProvider);
+  }
+
+  public async request(args) {
+    if (args.method === "eth_estimateGas") {
+      return this.gasPrice;
+    } else if (args.method === "eth_sendTransaction") {
+      const params = this._getParams(args);
+      const tx = params[0];
+
+      // let's pretend that EIP-1559 never happened
+      tx.gasPrice = this.gasPrice;
+    }
+
+    return this._wrappedProvider.request(args);
+  }
+}
+
+extendProvider(async (provider, config, network) => {
+  // We fix the gas price to be set by the config or to a random high value
+  const gasPrice = config.fixedGasPrice || "0x1000000"
+  const newProvider = new FixedGasProvider(gasPrice, provider);
+  return newProvider;
+});
+```
+
+Will make the `hre` provider use that gas price value everywhere it's used:
+
+```js
+task("request", async (args, hre) => {
+  await hre.network.request(/*{ method arguments }*/); // this will run FixedGasProvider's request method above
+});
+
+module.exports = {};
+```
+
 ## Using the Hardhat TypeScript plugin boilerplate
 
 For a complete example of a plugin you can take a look at the [Hardhat TypeScript plugin boilerplate project](https://github.com/NomicFoundation/hardhat-ts-plugin-boilerplate/).

packages/hardhat-core/src/builtin-tasks/node.ts

@@ -109,13 +109,10 @@ subtask(TASK_NODE_GET_PROVIDER)
       let provider = network.provider;
 
       if (network.name !== HARDHAT_NETWORK_NAME) {
-        const networkConfig = config.networks[HARDHAT_NETWORK_NAME];
-
         log(`Creating hardhat provider for JSON-RPC server`);
-        provider = createProvider(
+        provider = await createProvider(
+          config,
           HARDHAT_NETWORK_NAME,
-          networkConfig,
-          config.paths,
           artifacts
         );
       }

packages/hardhat-core/src/internal/cli/cli.ts

@@ -228,7 +228,8 @@ async function main() {
       Reporter.setEnabled(true);
     }
 
-    const envExtenders = ctx.extendersManager.getExtenders();
+    const envExtenders = ctx.environmentExtenders;
+    const providerExtenders = ctx.providerExtenders;
     const taskDefinitions = ctx.tasksDSL.getTaskDefinitions();
 
     const [abortAnalytics, hitPromise] = await analytics.sendTaskHit(taskName);
@@ -266,7 +267,8 @@ async function main() {
       taskDefinitions,
       envExtenders,
       ctx.experimentalHardhatNetworkMessageTraceHooks,
-      userConfig
+      userConfig,
+      providerExtenders
     );
 
     ctx.setHardhatRuntimeEnvironment(env);

packages/hardhat-core/src/internal/context.ts

@@ -1,10 +1,11 @@
 import {
   ConfigExtender,
+  EnvironmentExtender,
   ExperimentalHardhatNetworkMessageTraceHook,
   HardhatRuntimeEnvironment,
+  ProviderExtender,
 } from "../types";
 
-import { ExtenderManager } from "./core/config/extenders";
 import { assertHardhatInvariant, HardhatError } from "./core/errors";
 import { ERRORS } from "./core/errors-list";
 import { TasksDSL } from "./core/tasks/dsl";
@@ -45,8 +46,10 @@ export class HardhatContext {
   }
 
   public readonly tasksDSL = new TasksDSL();
-  public readonly extendersManager = new ExtenderManager();
+  public readonly environmentExtenders: EnvironmentExtender[] = [];
   public environment?: HardhatRuntimeEnvironment;
+  public readonly providerExtenders: ProviderExtender[] = [];
+
   public readonly configExtenders: ConfigExtender[] = [];
 
   // NOTE: This is experimental and will be removed. Please contact our team if

packages/hardhat-core/src/internal/core/config/config-env.ts

@@ -4,6 +4,7 @@ import {
   ConfigurableTaskDefinition,
   EnvironmentExtender,
   ExperimentalHardhatNetworkMessageTraceHook,
+  ProviderExtender,
   TaskArguments,
 } from "../../../types";
 import { HardhatContext } from "../../context";
@@ -126,15 +127,33 @@ export const types = argumentTypes;
  */
 export function extendEnvironment(extender: EnvironmentExtender) {
   const ctx = HardhatContext.getHardhatContext();
-  const extenderManager = ctx.extendersManager;
-  extenderManager.add(extender);
+  ctx.environmentExtenders.push(extender);
 }
 
+/**
+ * Register a config extender what will be run after the
+ * Hardhat Runtime Environment is initialized.
+ *
+ * @param extender A function that receives the resolved config
+ * to be modified and the config provided by the user
+ */
 export function extendConfig(extender: ConfigExtender) {
   const ctx = HardhatContext.getHardhatContext();
   ctx.configExtenders.push(extender);
 }
 
+/**
+ * Register a provider extender what will be run after the
+ * Hardhat Runtime Environment is initialized.
+ *
+ * @param extender A function that receives the current provider
+ * and returns a new one.
+ */
+export function extendProvider(extender: ProviderExtender) {
+  const ctx = HardhatContext.getHardhatContext();
+  ctx.providerExtenders.push(extender);
+}
+
 // NOTE: This is experimental and will be removed. Please contact our team
 // if you are planning to use it.
 export function experimentalAddHardhatNetworkMessageTraceHook(

packages/hardhat-core/src/internal/core/errors-list.ts

@@ -269,6 +269,15 @@ Rename the file to use the .cjs to fix this problem.`,
       description: `Your project is an ESM project (you have "type": "module" set in your package.json) and you are trying to initialize a TypeScript project. This is not supported yet.`,
       shouldBeReported: false,
     },
+    UNINITIALIZED_PROVIDER: {
+      number: 21,
+      message:
+        "You tried to access an uninitialized provider. To initialize the provider, make sure you first call `.init()` or any method that hits a node like request, send or sendAsync.",
+      title: "Uninitialized provider",
+      description: `You tried to access an uninitialized provider. This is most likely caused by using the internal wrapped provider directly before using it to send a request or initializing it.
+To initialize the provider, make sure you first call \`.init()\` or any method that hits a node like request, send or sendAsync.`,
+      shouldBeReported: true,
+    },
   },
   NETWORK: {
     CONFIG_NOT_FOUND: {

packages/hardhat-core/src/internal/core/providers/construction.ts

@@ -3,12 +3,13 @@ import type {
   BoundExperimentalHardhatNetworkMessageTraceHook,
   EIP1193Provider,
   EthereumProvider,
+  HardhatConfig,
   HardhatNetworkConfig,
   HDAccountsUserConfig,
   HttpNetworkAccountsUserConfig,
   HttpNetworkConfig,
   NetworkConfig,
-  ProjectPathsConfig,
+  ProviderExtender,
 } from "../../../types";
 
 import type {
@@ -46,14 +47,16 @@ function importProvider<ModuleT, ProviderNameT extends keyof ModuleT>(
   return mod[name];
 }
 
-export function createProvider(
+export async function createProvider(
+  config: HardhatConfig,
   networkName: string,
-  networkConfig: NetworkConfig,
-  paths?: ProjectPathsConfig,
   artifacts?: Artifacts,
-  experimentalHardhatNetworkMessageTraceHooks: BoundExperimentalHardhatNetworkMessageTraceHook[] = []
-): EthereumProvider {
+  experimentalHardhatNetworkMessageTraceHooks: BoundExperimentalHardhatNetworkMessageTraceHook[] = [],
+  extenders: ProviderExtender[] = []
+): Promise<EthereumProvider> {
   let eip1193Provider: EIP1193Provider;
+  const networkConfig = config.networks[networkName];
+  const paths = config.paths;
 
   if (networkName === HARDHAT_NETWORK_NAME) {
     const hardhatNetConfig = networkConfig as HardhatNetworkConfig;
@@ -132,7 +135,11 @@ export function createProvider(
     );
   }
 
-  const wrappedProvider = applyProviderWrappers(eip1193Provider, networkConfig);
+  let wrappedProvider = applyProviderWrappers(eip1193Provider, networkConfig);
+
+  for (const extender of extenders) {
+    wrappedProvider = await extender(wrappedProvider, config, networkName);
+  }
 
   const BackwardsCompatibilityProviderAdapter = importProvider<
     typeof import("./backwards-compatibility"),