The Network Manager API

The Hardhat Runtime Environment comes with a NetworkManager object available as its network property.

This section has reference documentation to work with its APIs. To learn more about Network Management in general, read this explanation.

Importing the Network Manager

You can access the Network Manager by importing Hardhat:

script/example.ts

import hre from "hardhat";

const networkManager = hre.network;

Or you can import it directly:

script/example.ts

import { network } from "hardhat";

The NetworkManager object

The NetworkManager object only has two methods:

• network.connect(): To connect to remote networks and create local blockchain simulations.
• network.createServer(): To create a local blockchain simulation and expose it through an HTTP-based JSON-RPC server.

The majority of this documentation will focus on network.connect(), as network.createServer() can be considered a wrapper around it.

The network.connect() method

When you call the network.connect() method, Hardhat creates a new NetworkConnection object.

The connection can either be an HTTP Network Connection connected to an external node through JSON-RPC, or an in-process connection to a new EDR-based simulated blockchain. In either case, every connection you create is independent from one another.

Both types offer the same API, so you can easily swap between them.

Calling it without parameters

The simplest way to create a new NetworkConnection is without any parameter:

script/no-params-example.ts

import { network } from "hardhat";

const connection = await network.connect();
console.log(connection.networkName);

By default, this will create a NetworkConnection based on the "default" Network Config of your Hardhat configuration. This Network Config is always defined, and by default it has an edr-simulated type, so it creates a new blockchain simulation every time it’s called.

You can also control which Network Config is used when none is provided by using the network Global Option. For example, running that same script like this will use the localhost Network Config:

npm

npx hardhat run script/no-params-example.ts --network localhost

pnpm

pnpm hardhat run script/no-params-example.ts --network localhost

Yarn

yarn hardhat run script/no-params-example.ts --network localhost

Choosing a Network Config

You can also choose a Network Config by providing its name as a string, or as part of its options object:

script/with-name-example.ts

import { network } from "hardhat";

const connection = await network.connect("localhost");

const connectionWithOptions = await network.connect({ network: "localhost" });

Network Config overrides

When you use the second option from the ones shown above, you can also use an override parameter. When you use it, the Network Config is read from the HardhatUserConfig, and the provided values overridden. Then it goes through the config validation process and resolution, and if successful, its result is used to create the connection.

For example, this script creates a Network Connection with logging enabled, and mines a block, whose results are printed to the terminal:

script/with-overrides-example.ts

import { network } from "hardhat";

const { networkHelpers } = await network.connect({
  override: { loggingEnabled: true },
});

await networkHelpers.mine();

Providing a Chain Type option

You can also provide a chainType in the options object. For example:

import { network } from "hardhat";

const { viem } = await network.connect({
  network: "hardhatOp",
  chainType: "op",
});

When you do this, the NetworkConnection is created with op as its type parameter. This has several implications:

• If you are using a plugin with multichain support, like hardhat-viem, it can extend the type of the NetworkConnection<"op">, adding new functionality in the form of new fields and methods.
• Multichain plugins and HTTP Network Connections in general can also change how they behave at runtime. For example, estimating gas differently depending on the Chain Type you are using.
• Network Connections to simulated networks will change how they work, running a higher-fidelity simulation.

You can learn more about these concepts in the Multichain support explanation.

Defining a Chain Type in your Network Config

You can define a chainType property in each Network Config. For example:

hardhat.config.ts

// ... imports ...

export default defineConfig({
  // ... other config ...
  networks: {
    hardhatMainnet: {
      type: "edr-simulated",
      chainType: "l1",
    },
    // ... other networks ...
  },
});

When you do this, you get most of the benefits of providing it as an option, except for the type-level extensions that a plugin can provide.

If you provide a Chain Type both as an option and as part of your Network Config, Hardhat will validate that they’re the same.

The network.createServer() method

The network.createServer() method creates a local blockchain simulation and exposes it through an HTTP-based JSON-RPC server, similar to what hardhat node does.

Parameters

This method takes the same arguments as network.connect(), plus two additional optional parameters:

• hostname: The hostname of the network interface the server should use to listen for new connections. Defaults to "127.0.0.1", or "0.0.0.0" if running in a Docker container.
• port: The port to use for the HTTP server. If not provided, an unused random port will be assigned by the OS.

Return value

Calling await network.createServer() returns a JsonRpcServer object, which provides the following methods:

• listen(): Starts the server and returns the hostname and port being used.
• close(): Stops the server.
• afterClosed(): Returns a promise that resolves when the server has fully closed. Useful if close() is called from another async context.

To learn more about how to use this method, see the Running a local development node guide.

The NetworkConnection<ChainTypeT> object

The NetworkConnection returned by network.connect() provides the basic functionality to interact with the network, and can be extended through plugins.

To learn more about it, read this explanation.