diff --git a/STYLE.md b/STYLE.md
index 442ff09d..f930fccb 100644
--- a/STYLE.md
+++ b/STYLE.md
@@ -95,12 +95,12 @@ Examples:
Too cold/direct:
-- First, you'll add the `myAccount` property to the `NetworkConnection` object returned by `network.connect()`.
+- First, you'll add the `myAccount` property to the `NetworkConnection` object returned by `network.create()`.
Warm and conversational:
-- Let's start by adding a `myAccount` property to the `NetworkConnection` object returned by `network.connect()`.
-- The first step is adding the `myAccount` property to the `NetworkConnection` object returned by `network.connect()`.
+- Let's start by adding a `myAccount` property to the `NetworkConnection` object returned by `network.create()`.
+- The first step is adding the `myAccount` property to the `NetworkConnection` object returned by `network.create()`.
Note that this is really important, and key to our branding. We don't want our documentation to be perceived too cold/direct just to be slightly more concise.
diff --git a/package.json b/package.json
index ec00e89d..3b146f52 100644
--- a/package.json
+++ b/package.json
@@ -25,7 +25,7 @@
"@astrojs/vercel": "^8.2.8",
"@expressive-code/plugin-collapsible-sections": "^0.41.3",
"@expressive-code/plugin-line-numbers": "^0.41.3",
- "@nomicfoundation/hardhat-errors": "^3.0.8",
+ "@nomicfoundation/hardhat-errors": "^3.0.10",
"@types/tar-stream": "^3.1.4",
"astro": "^5.6.1",
"cspell": "^9.2.2",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a42e3023..7e71106d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -27,8 +27,8 @@ importers:
specifier: ^0.41.3
version: 0.41.3
'@nomicfoundation/hardhat-errors':
- specifier: ^3.0.8
- version: 3.0.8
+ specifier: ^3.0.10
+ version: 3.0.10
'@types/tar-stream':
specifier: ^3.1.4
version: 3.1.4
@@ -767,11 +767,11 @@ packages:
resolution: {integrity: sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==}
engines: {node: '>= 8'}
- '@nomicfoundation/hardhat-errors@3.0.8':
- resolution: {integrity: sha512-gHAZDYb0e5joq+WecgC3ciz5OcgqUBgK2zLQmNoKSn/I52h3SH1stxXsY4dcVsj0OY4ZksqIRhJDKskHC5DvTA==}
+ '@nomicfoundation/hardhat-errors@3.0.10':
+ resolution: {integrity: sha512-jfQ75/t21674cIQPbQmzRSY8YdusvQhKMsT+IGEoXlJuAzw+ngWsD7y7nHT8UKQ+liHWgMA+Am2843KwP0KtiA==}
- '@nomicfoundation/hardhat-utils@4.0.1':
- resolution: {integrity: sha512-9xxD6WXLn+kopd+hmF+XYcJJ38Gm06QmZxKf/fIJzlzs9FuNI6C7Lvdd4qHv8/3ReegIbpBCrzozaL2GISmNrA==}
+ '@nomicfoundation/hardhat-utils@4.0.2':
+ resolution: {integrity: sha512-6lK0+9ygB7wGDlu11DAmTuZxhnoGbyGZC2aRaKKehW0vDNTS9iT7GUimgVvlO3B23E/HwwRKOOLmSVPC4qmmQw==}
'@nomicfoundation/slang@1.2.0':
resolution: {integrity: sha512-+04Z1RHbbz0ldDbHKQFOzveCdI9Rd3TZZu7fno5hHy3OsqTo9UK5Jgqo68wMvRovCO99POv6oCEyO7+urGeN8Q==}
@@ -3783,13 +3783,13 @@ snapshots:
'@nodelib/fs.scandir': 2.1.5
fastq: 1.19.1
- '@nomicfoundation/hardhat-errors@3.0.8':
+ '@nomicfoundation/hardhat-errors@3.0.10':
dependencies:
- '@nomicfoundation/hardhat-utils': 4.0.1
+ '@nomicfoundation/hardhat-utils': 4.0.2
transitivePeerDependencies:
- supports-color
- '@nomicfoundation/hardhat-utils@4.0.1':
+ '@nomicfoundation/hardhat-utils@4.0.2':
dependencies:
'@streamparser/json-node': 0.0.22
debug: 4.4.3
diff --git a/src/content/docs/docs/explanations/edr-simulated-networks.mdx b/src/content/docs/docs/explanations/edr-simulated-networks.mdx
index dd359079..e52d56da 100644
--- a/src/content/docs/docs/explanations/edr-simulated-networks.mdx
+++ b/src/content/docs/docs/explanations/edr-simulated-networks.mdx
@@ -20,7 +20,7 @@ Unlike connecting to a remote node through JSON-RPC, simulated networks give you
The only difference between a blockchain simulated by EDR and a production one is that EDR requires no consensus mechanism or peer-to-peer network, as it's run by a single process each time.
-When you call `await network.connect()` with a Network Config of type `edr-simulated`, Hardhat creates a new, independent blockchain simulation. Each simulation is isolated, so you can create multiple simulations simultaneously without them interfering with each other.
+When you call `await network.create()` with a Network Config of type `edr-simulated`, Hardhat creates a new, independent blockchain simulation. Each simulation is isolated, so you can create multiple simulations simultaneously without them interfering with each other.
## How to use simulated networks
@@ -33,7 +33,7 @@ When you run your tests or scripts, Hardhat automatically creates an in-process
```ts
import { network } from "hardhat";
-const connection = await network.connect();
+const connection = await network.create();
```
This creates a new blockchain simulation based on the Network Config specified in your configuration file or via the `--network` flag.
diff --git a/src/content/docs/docs/explanations/global-options.mdx b/src/content/docs/docs/explanations/global-options.mdx
index ad62cbfb..9d24b3e5 100644
--- a/src/content/docs/docs/explanations/global-options.mdx
+++ b/src/content/docs/docs/explanations/global-options.mdx
@@ -11,7 +11,7 @@ Global Options are options that Hardhat can receive and are available across all
They are different from Hardhat Task options and arguments in that they are meant to control the functionality of Hardhat itself, and not that of a single task.
-For example, `--network` is a global option that controls the default value that `network.connect()` uses when no network config name is provided.
+For example, `--network` is a global option that controls the default value that `network.create()` uses when no network config name is provided.
Plugins can define their own Global Options, so the complete list depends on your setup. To see all available options, run:
diff --git a/src/content/docs/docs/explanations/multichain-support.mdx b/src/content/docs/docs/explanations/multichain-support.mdx
index 69310790..535b3944 100644
--- a/src/content/docs/docs/explanations/multichain-support.mdx
+++ b/src/content/docs/docs/explanations/multichain-support.mdx
@@ -53,7 +53,7 @@ When you connect to a network using the [Network Manager](/docs/reference/networ
// scripts/example-op.ts
import { network } from "hardhat";
-const { viem } = await network.connect({
+const { viem } = await network.create({
network: "hardhatOp",
chainType: "op",
});
@@ -68,7 +68,7 @@ const l1Gas = await publicClient.estimateL1Gas({
The network simulation will be created using the `op` Chain Type and its simulation will be stricter.
-Moreover, the Chain Type information will be available to network-related plugins, both at runtime and at type-level. This allows them to modify their behavior and the result of `network.connect()` depending on the Chain Type, potentially adding more functionality.
+Moreover, the Chain Type information will be available to network-related plugins, both at runtime and at type-level. This allows them to modify their behavior and the result of `network.create()` depending on the Chain Type, potentially adding more functionality.
For example, the method highlighted in the snippet above is only available when you're using the `op` Chain Type.
diff --git a/src/content/docs/docs/explanations/network-management.mdx b/src/content/docs/docs/explanations/network-management.mdx
index 263ea00d..98ddaf52 100644
--- a/src/content/docs/docs/explanations/network-management.mdx
+++ b/src/content/docs/docs/explanations/network-management.mdx
@@ -69,14 +69,14 @@ This object allows you to create network connections. You can do it like this:
```ts
import { network } from "hardhat";
-const networkConnection = await network.connect();
+const networkConnection = await network.create();
```
By default, it creates a `NetworkConnection` using the Network Config called `default`, which is always present. You can choose a different fallback Network Config name by using the `network` [Global Option](/docs/explanations/global-options), like this:
-Every time you call `network.connect()` a new independent `NetworkConnection` object is created:
+Every time you call `network.create()` a new independent `NetworkConnection` object is created:
- If the Network Config is of type `"http"`, the JSON-RPC server in the `url` setting will be used. No synchronization between two HTTP Network Connections is performed by Hardhat, either at the HTTP layer or at the protocol layer (e.g. when handling account nonces).
@@ -86,19 +86,21 @@ Every time you call `network.connect()` a new independent `NetworkConnection` ob
This document makes a distinction between blockchain and Network Config, their names, Network Connection, and creating a Network Connection, to be precise in its explanations.
In practice, most people will simplify this vocabulary and just say that, for example, running the command above connected to the network mainnet. Using "connect" interchangeably with creating a Network Connection, and the network name with the blockchain they intend to connect to.
+
+If you want to reuse the same connection across different parts of your code, you can use `network.getOrCreate()` instead. It returns an existing connection if one was previously created with the same network name and chain type.
:::
### Using an explicit Network Config
-You can also create a connection using an explicit Network Config, and not just relying on `--network`. This is done by providing parameters to `network.connect()`:
+You can also create a connection using an explicit Network Config, and not just relying on `--network`. This is done by providing parameters to `network.create()`:
```ts
-const mainnetConnection = await network.connect("mainnet");
+const mainnetConnection = await network.create("mainnet");
-const simulatedConnection = await network.connect("simulatedNetwork");
+const simulatedConnection = await network.create("simulatedNetwork");
// Creating a second simulated blockchain
-const anotherSimulated = await network.connect("simulatedNetwork");
+const anotherSimulated = await network.create("simulatedNetwork");
```
### Cleaning up your Network Connections
@@ -111,7 +113,7 @@ await networkConnection.close();
## The `NetworkConnection` object
-The result of calling `await network.connect()` is a `NetworkConnection` object.
+The result of calling `await network.create()` is a `NetworkConnection` object.
By default, they have the basics to interact with a blockchain:
@@ -135,7 +137,7 @@ For example, if you use the [`@nomicfoundation/hardhat-toolbox-viem`](/docs/plug
The idiomatic way to use the Network Connection fields is by creating them like this:
```ts
-const { viem, networkHelpers, ignition } = await network.connect();
+const { viem, networkHelpers, ignition } = await network.create();
```
:::
diff --git a/src/content/docs/docs/guides/deployment/using-scripts.mdx b/src/content/docs/docs/guides/deployment/using-scripts.mdx
index 19d77421..41093dd2 100644
--- a/src/content/docs/docs/guides/deployment/using-scripts.mdx
+++ b/src/content/docs/docs/guides/deployment/using-scripts.mdx
@@ -22,7 +22,7 @@ To build a deployment script using viem, create the `scripts/deploy-counter.ts`
// scripts/deploy-counter.ts
import { network } from "hardhat";
-const { viem, networkName } = await network.connect();
+const { viem, networkName } = await network.create();
const client = await viem.getPublicClient();
console.log(`Deploying Counter to ${networkName}...`);
@@ -48,7 +48,7 @@ To build a deployment script using ethers, create the `scripts/deploy-counter.ts
// scripts/deploy-counter.ts
import { network } from "hardhat";
-const { ethers, networkName } = await network.connect();
+const { ethers, networkName } = await network.create();
console.log(`Deploying Counter to ${networkName}...`);
diff --git a/src/content/docs/docs/guides/forking.mdx b/src/content/docs/docs/guides/forking.mdx
index 9fb635b1..2e080121 100644
--- a/src/content/docs/docs/guides/forking.mdx
+++ b/src/content/docs/docs/guides/forking.mdx
@@ -55,13 +55,13 @@ import { network } from "hardhat";
describe("Example", function () {
it("should use the forked network", async function () {
- const { viem } = await network.connect("mainnetFork");
+ const { viem } = await network.create("mainnetFork");
// This test uses the forked Mainnet network
});
it("should use the default network", async function () {
- const { viem } = await network.connect();
+ const { viem } = await network.create();
// This test uses the default local network
});
diff --git a/src/content/docs/docs/guides/hardhat-console.mdx b/src/content/docs/docs/guides/hardhat-console.mdx
index c179b493..15eabbc0 100644
--- a/src/content/docs/docs/guides/hardhat-console.mdx
+++ b/src/content/docs/docs/guides/hardhat-console.mdx
@@ -22,7 +22,7 @@ The `console` task starts a [Node.js REPL](https://nodejs.org/en/learn/command-l
Here's an example where you deploy a contract and interact with it:
```
-> const { viem } = await network.connect()
+> const { viem } = await network.create()
> const counter = await viem.deployContract("Counter")
> await counter.write.inc()
> await counter.read.x()
@@ -37,7 +37,7 @@ To skip compilation before starting the console, pass the `--no-compile` flag:
The `console` task accepts an optional list of positional arguments. Each argument you provide will be executed as a command immediately after the REPL starts, letting you run a series of commands automatically:
-
+
Make sure to wrap each command in quotes to avoid issues with your shell interpreting special characters.
@@ -66,7 +66,7 @@ export default defineConfig({
// tasks/my-console.ts
export default function myConsoleTask(_, hre) {
return hre.tasks.getTask("console").run({
- commands: ["const { viem } = await network.connect();"],
+ commands: ["const { viem } = await network.create();"],
});
}
```
diff --git a/src/content/docs/docs/guides/hardhat-node.mdx b/src/content/docs/docs/guides/hardhat-node.mdx
index eef6fe5c..93430230 100644
--- a/src/content/docs/docs/guides/hardhat-node.mdx
+++ b/src/content/docs/docs/guides/hardhat-node.mdx
@@ -15,7 +15,7 @@ Suppose you have a script that sends 1 ETH from the first local account to the z
// my-script.ts
import { network } from "hardhat";
-const { viem } = await network.connect();
+const { viem } = await network.create();
const publicClient = await viem.getPublicClient();
const [wallet] = await viem.getWalletClients();
diff --git a/src/content/docs/docs/guides/testing/using-ethers.mdx b/src/content/docs/docs/guides/testing/using-ethers.mdx
index bc7c81c2..00b3773f 100644
--- a/src/content/docs/docs/guides/testing/using-ethers.mdx
+++ b/src/content/docs/docs/guides/testing/using-ethers.mdx
@@ -88,7 +88,7 @@ Make sure your `test/Counter.ts` file looks like this:
import { expect } from "chai";
import hre from "hardhat";
-const { ethers, networkHelpers } = await hre.network.connect();
+const { ethers, networkHelpers } = await hre.network.create();
describe("Counter", function () {
it("Should emit the Increment event when calling the inc() function", async function () {
@@ -104,11 +104,11 @@ First, we import the things we're going to use:
- The [`expect`](https://www.chaijs.com/api/bdd/) function from `chai` to write our assertions
- The [Hardhat Runtime Environment](/docs/explanations/hardhat-runtime-environment), or `hre`, which exposes all of Hardhat's functionality
-Then, we call `hre.network.connect()` to create a new local simulation of an Ethereum blockchain to run our test on. It returns an object with an instance of `ethers` and `networkHelpers` already connected to that simulation.
+Then, we call `hre.network.create()` to create a new local simulation of an Ethereum blockchain to run our test on. It returns an object with an instance of `ethers` and `networkHelpers` already connected to that simulation.
After that, we use the `describe` and `it` functions, which are global Mocha functions used to define and group your tests. You can read more about Mocha [here](https://mochajs.org/#getting-started).
-The test itself is what's inside the callback argument to the `it` function. First, we deploy our `Counter` contract using the `ethers` instance returned by our `hre.network.connect()` call.
+The test itself is what's inside the callback argument to the `it` function. First, we deploy our `Counter` contract using the `ethers` instance returned by our `hre.network.create()` call.
Finally, we call the `inc()` function of the contract and assert that the `Increment` event is emitted with the correct argument. The `.to.emit` matcher is provided by the [`hardhat-ethers-chai-matchers`](/docs/plugins/hardhat-ethers-chai-matchers) plugin.
@@ -172,7 +172,7 @@ With these changes, our previous test will still pass because by default the con
import { expect } from "chai";
import hre from "hardhat";
-const { ethers, networkHelpers } = await hre.network.connect();
+const { ethers, networkHelpers } = await hre.network.create();
describe("Counter", function () {
it("Should emit the Increment event when calling the inc() function", async function () {
@@ -231,7 +231,7 @@ The tests we have written run on a simulated network that behaves like Ethereum
One way to test on a different kind of chain is to pass a `chainType` option when creating your Network Connection:
```ts
-const { ethers } = await hre.network.connect({
+const { ethers } = await hre.network.create({
chainType: "op",
});
```
@@ -274,7 +274,7 @@ This is what our tests look like when a fixture is used:
import { expect } from "chai";
import { network } from "hardhat";
-const { ethers, networkHelpers } = await network.connect();
+const { ethers, networkHelpers } = await network.create();
describe("Counter", function () {
async function deployCounterFixture() {
diff --git a/src/content/docs/docs/guides/testing/using-viem.mdx b/src/content/docs/docs/guides/testing/using-viem.mdx
index b040e080..8f27e894 100644
--- a/src/content/docs/docs/guides/testing/using-viem.mdx
+++ b/src/content/docs/docs/guides/testing/using-viem.mdx
@@ -94,7 +94,7 @@ Make sure your `test/Counter.ts` file looks like this:
import { describe, it } from "node:test";
import hre from "hardhat";
-const { viem, networkHelpers } = await hre.network.connect();
+const { viem, networkHelpers } = await hre.network.create();
describe("Counter", function () {
it("Should emit the Increment event when calling the inc() function", async function () {
@@ -115,11 +115,11 @@ First, we import the things we're going to use:
- The `describe` and `it` functions from `node:test` to define and group your tests
- The [Hardhat Runtime Environment](/docs/explanations/hardhat-runtime-environment), or `hre`, which exposes all of Hardhat's functionality
-Then, we call `hre.network.connect()` to create a new local simulation of an Ethereum blockchain to run our test on. It returns an object with instances of `viem` and `networkHelpers` already connected to that simulation.
+Then, we call `hre.network.create()` to create a new local simulation of an Ethereum blockchain to run our test on. It returns an object with instances of `viem` and `networkHelpers` already connected to that simulation.
After that, we use the `describe` and `it` functions to build your tests. You can read more about the Node.js test runner [here](https://nodejs.org/api/test.html). If you're used to Mocha, it's mostly backwards compatible, but faster and with no dependencies.
-The test itself is what's inside the callback argument to the `it` function. First, we deploy our `Counter` contract using the `viem` instance returned by our `hre.network.connect()` call.
+The test itself is what's inside the callback argument to the `it` function. First, we deploy our `Counter` contract using the `viem` instance returned by our `hre.network.create()` call.
Finally, we call the `inc()` function of the contract and assert that the `Increment` event is emitted with the correct argument. The `viem.assertions.emitWithArgs` helper is provided by the [`hardhat-viem-assertions`](/docs/plugins/hardhat-viem-assertions) plugin.
@@ -183,7 +183,7 @@ However, we should also add a test to check that calling `inc()` from a non-owne
import { describe, it } from "node:test";
import hre from "hardhat";
-const { viem, networkHelpers } = await hre.network.connect();
+const { viem, networkHelpers } = await hre.network.create();
describe("Counter", function () {
it("Should emit the Increment event when calling the inc() function", async function () {
@@ -256,7 +256,7 @@ The tests we have written run on a simulated network that behaves like Ethereum
One way to test on a different kind of chain is to pass a `chainType` option when creating your Network Connection:
```ts
-const { viem } = await hre.network.connect({
+const { viem } = await hre.network.create({
chainType: "op",
});
```
@@ -297,7 +297,7 @@ This is what our tests look like when a fixture is used:
import { describe, it } from "node:test";
import { network } from "hardhat";
-const { viem, networkHelpers } = await network.connect();
+const { viem, networkHelpers } = await network.create();
describe("Counter", function () {
async function deployCounterFixture() {
@@ -348,13 +348,13 @@ The fixture function can return anything you want, and `loadFixture` will return
## Using `viem` and `hardhat-viem` in the same file
-The `viem` object that you get from calling `network.connect()` only includes the functionality added by `hardhat-viem`. To use viem's own functionality, import it from the `viem` module:
+The `viem` object that you get from calling `network.create()` only includes the functionality added by `hardhat-viem`. To use viem's own functionality, import it from the `viem` module:
```ts
import { keccak256 } from "viem";
import { network } from "hardhat";
-const { viem } = await network.connect();
+const { viem } = await network.create();
```
Keep in mind that you can get a name clash if you use a namespace import:
@@ -364,13 +364,13 @@ import * as viem from "viem";
import { network } from "hardhat";
// this is an error because viem is already declared
-const { viem } = await network.connect();
+const { viem } = await network.create();
```
One way to work around this problem is to use a different name for the Hardhat viem object:
```ts
-const { viem: hhViem } = await network.connect();
+const { viem: hhViem } = await network.create();
const publicClient = await hhViem.getPublicClient();
```
diff --git a/src/content/docs/docs/guides/writing-scripts.mdx b/src/content/docs/docs/guides/writing-scripts.mdx
index c22394dd..22d759d3 100644
--- a/src/content/docs/docs/guides/writing-scripts.mdx
+++ b/src/content/docs/docs/guides/writing-scripts.mdx
@@ -25,7 +25,7 @@ Let's try this out. Create a new directory called `scripts` in your project's ro
// scripts/accounts.ts
import hre from "hardhat";
-const { provider } = await hre.network.connect();
+const { provider } = await hre.network.create();
const accounts = await provider.request({ method: "eth_accounts" });
if (accounts !== null) {
diff --git a/src/content/docs/docs/guides/writing-tasks.mdx b/src/content/docs/docs/guides/writing-tasks.mdx
index ea09419e..7cb07639 100644
--- a/src/content/docs/docs/guides/writing-tasks.mdx
+++ b/src/content/docs/docs/guides/writing-tasks.mdx
@@ -38,7 +38,7 @@ export default async function (
taskArguments: AccountTaskArguments,
hre: HardhatRuntimeEnvironment,
) {
- const { provider } = await hre.network.connect();
+ const { provider } = await hre.network.create();
console.log(await provider.request({ method: "eth_accounts" }));
}
```
@@ -77,7 +77,7 @@ import { defineConfig, task } from "hardhat/config";
const printAccounts = task("accounts", "Print the accounts")
.setInlineAction(async (taskArguments, hre) => {
- const { provider } = await hre.network.connect();
+ const { provider } = await hre.network.create();
console.log(await provider.request({ method: "eth_accounts" }));
})
.build();
@@ -135,7 +135,7 @@ export default async function (
_taskArguments: AccountTaskArguments,
hre: HardhatRuntimeEnvironment,
): Promise> {
- const { provider } = await hre.network.connect();
+ const { provider } = await hre.network.create();
const accounts = await provider.request({ method: "eth_accounts" });
if (accounts.length === 0) {
diff --git a/src/content/docs/docs/migrate-from-hardhat2/guides/mocha-tests.mdx b/src/content/docs/docs/migrate-from-hardhat2/guides/mocha-tests.mdx
index d1dd665d..1b22e676 100644
--- a/src/content/docs/docs/migrate-from-hardhat2/guides/mocha-tests.mdx
+++ b/src/content/docs/docs/migrate-from-hardhat2/guides/mocha-tests.mdx
@@ -82,7 +82,7 @@ You now have to create a network connection first:
```ts
describe("suite", function () {
it("some test", async function () {
- const { provider } = await hre.network.connect();
+ const { provider } = await hre.network.create();
const blockNumber = await provider.send("eth_blockNumber");
});
});
@@ -91,7 +91,7 @@ describe("suite", function () {
Most of the time, you'll want to use the same provider for multiple tests. If you're using ESM syntax, you can use top-level await and define it as a shared variable:
```ts
-const { provider } = await hre.network.connect();
+const { provider } = await hre.network.create();
describe("suite", function () {
it("some test", async function () {
@@ -107,7 +107,7 @@ let provider;
describe("suite", function () {
before(async function () {
- ({ provider } = await hre.network.connect());
+ ({ provider } = await hre.network.create());
});
it("some test", async function () {
@@ -138,7 +138,7 @@ import hre from "hardhat";
describe("suite", function () {
let ethers;
before(async function () {
- ({ ethers } = await hre.network.connect());
+ ({ ethers } = await hre.network.create());
});
it("some test", async function () {
@@ -164,7 +164,7 @@ The `@nomicfoundation/hardhat-network-helpers` package is now a plugin. Instead
```ts
import { network } from "hardhat";
-const { networkHelpers } = await network.connect();
+const { networkHelpers } = await network.create();
await networkHelpers.mine(5);
```
diff --git a/src/content/docs/docs/migrate-from-hardhat2/index.mdx b/src/content/docs/docs/migrate-from-hardhat2/index.mdx
index c434baea..dd097a29 100644
--- a/src/content/docs/docs/migrate-from-hardhat2/index.mdx
+++ b/src/content/docs/docs/migrate-from-hardhat2/index.mdx
@@ -196,7 +196,7 @@ import { defineConfig, task } from "hardhat/config";
const printAccounts = task("accounts", "Print the accounts")
.setInlineAction(async (taskArguments, hre) => {
- const { provider } = await hre.network.connect();
+ const { provider } = await hre.network.create();
console.log(await provider.request({ method: "eth_accounts" }));
})
.build();
diff --git a/src/content/docs/docs/plugin-development/explanations/hooks.mdx b/src/content/docs/docs/plugin-development/explanations/hooks.mdx
index 343f4ffd..3a737d01 100644
--- a/src/content/docs/docs/plugin-development/explanations/hooks.mdx
+++ b/src/content/docs/docs/plugin-development/explanations/hooks.mdx
@@ -13,7 +13,7 @@ Hooks are extension points that allow you to introduce custom logic to the execu
Different workflows of Hardhat define their own Hooks. When we build a piece of functionality that a plugin may want to customize, we define a Hook and run it. That is, instead of just implementing the default behavior, we add an extension point and use the normal behavior as default.
-For example, there's a `NetworkHooks#newConnection` Hook that allows you to customize the behavior of `network.connect()`.
+For example, there's a `NetworkHooks#newConnection` Hook that allows you to customize the behavior of `network.create()`.
Plugins can define their own Hooks too, so they can also be extensible.
diff --git a/src/content/docs/docs/plugin-development/explanations/lifecycle.mdx b/src/content/docs/docs/plugin-development/explanations/lifecycle.mdx
index e7fcc4e7..ea33e5b3 100644
--- a/src/content/docs/docs/plugin-development/explanations/lifecycle.mdx
+++ b/src/content/docs/docs/plugin-development/explanations/lifecycle.mdx
@@ -247,7 +247,7 @@ Example of an inline action:
```ts
task("accounts", "Print the accounts")
.setInlineAction(async (taskArguments, hre) => {
- const { provider } = await hre.network.connect();
+ const { provider } = await hre.network.create();
console.log(await provider.request({ method: "eth_accounts" }));
})
.build();
diff --git a/src/content/docs/docs/plugin-development/tutorial/index.mdx b/src/content/docs/docs/plugin-development/tutorial/index.mdx
index bd94f0ff..d57d5392 100644
--- a/src/content/docs/docs/plugin-development/tutorial/index.mdx
+++ b/src/content/docs/docs/plugin-development/tutorial/index.mdx
@@ -15,14 +15,14 @@ You also need to create a new repository based on the [Hardhat 3 plugin template
## Your first Hardhat 3 plugin
-Let's create a plugin that lets users pick an account for each network in their config and store it as `myAccount` in the `NetworkConnection` object returned by `network.connect()`. We'll also define a task to print that account's address.
+Let's create a plugin that lets users pick an account for each network in their config and store it as `myAccount` in the `NetworkConnection` object returned by `network.create()`. We'll also define a task to print that account's address.
Your plugin will let users write:
```ts
import { network } from "hardhat";
-const { myAccount } = await network.connect();
+const { myAccount } = await network.create();
console.log("My account is:", myAccount);
```
@@ -34,7 +34,7 @@ pnpm hardhat my-account --network networkName
By implementing this plugin, you'll learn to:
-1. Extend the `NetworkConnection` objects returned by `network.connect()`.
+1. Extend the `NetworkConnection` objects returned by `network.create()`.
2. Extend the Hardhat Config System, adding custom validation and resolution logic.
3. Add a task that builds on these features.
diff --git a/src/content/docs/docs/plugin-development/tutorial/network-connection.mdx b/src/content/docs/docs/plugin-development/tutorial/network-connection.mdx
index 1116503d..567dc740 100644
--- a/src/content/docs/docs/plugin-development/tutorial/network-connection.mdx
+++ b/src/content/docs/docs/plugin-development/tutorial/network-connection.mdx
@@ -5,7 +5,7 @@ sidebar:
order: 2
---
-Let's start by adding the `myAccount` property to the `NetworkConnection` object returned by `network.connect()`.
+Let's start by adding the `myAccount` property to the `NetworkConnection` object returned by `network.create()`.
## Defining a network Hook Handler
@@ -43,7 +43,7 @@ export default async (): Promise> => {
};
```
-The `newConnection` function above is a Hook Handler. Hardhat calls it every time a new network connection is created with `network.connect()`.
+The `newConnection` function above is a Hook Handler. Hardhat calls it every time a new network connection is created with `network.create()`.
Within this function, we first call `next` to call any other Hook Handler, or the default behavior of Hardhat. It returns the `NetworkConnection` object.
@@ -106,7 +106,7 @@ Create the file `packages/example-project/scripts/my-account-example.ts` with th
```ts
import { network } from "hardhat";
-const connection = await network.connect();
+const connection = await network.create();
console.log("connection.myAccount:", connection.myAccount);
```
diff --git a/src/content/docs/docs/plugin-development/tutorial/task.mdx b/src/content/docs/docs/plugin-development/tutorial/task.mdx
index 8e2249ca..40bc7594 100644
--- a/src/content/docs/docs/plugin-development/tutorial/task.mdx
+++ b/src/content/docs/docs/plugin-development/tutorial/task.mdx
@@ -64,7 +64,7 @@ export default async function (
taskArguments: MyAccountTaskArguments,
hre: HardhatRuntimeEnvironment,
) {
- const conn = await hre.network.connect();
+ const conn = await hre.network.create();
console.log(taskArguments.title);
console.log(conn.myAccount);
}
diff --git a/src/content/docs/docs/plugin-development/tutorial/testing.mdx b/src/content/docs/docs/plugin-development/tutorial/testing.mdx
index 617ac097..10315734 100644
--- a/src/content/docs/docs/plugin-development/tutorial/testing.mdx
+++ b/src/content/docs/docs/plugin-development/tutorial/testing.mdx
@@ -23,7 +23,7 @@ describe("myAccount initialization on network connection", () => {
it("should initialize the myAccount field on the network connection", async () => {
const hre = await createFixtureProjectHRE("base-project");
- const connection = await hre.network.connect();
+ const connection = await hre.network.create();
const accounts: string[] = await connection.provider.request({
method: "eth_accounts",
});
@@ -58,7 +58,7 @@ it("should throw a plugin error if the myAccountIndex is too high with respect t
await assert.rejects(
async () => {
- await hre.network.connect("withMyAccountIndexTooHigh");
+ await hre.network.create("withMyAccountIndexTooHigh");
},
HardhatPluginError, // Import it from "hardhat/plugins"
"hardhat-plugin-template: Invalid index 100000 for myAccount when connecting to network withMyAccountIndexTooHigh",
diff --git a/src/content/docs/docs/reference/edr-simulated-networks.mdx b/src/content/docs/docs/reference/edr-simulated-networks.mdx
index a3a62c43..e097c94b 100644
--- a/src/content/docs/docs/reference/edr-simulated-networks.mdx
+++ b/src/content/docs/docs/reference/edr-simulated-networks.mdx
@@ -214,7 +214,7 @@ If you disable both automine and interval mining, transactions will accumulate i
// scripts/manual-mining.ts
import { network } from "hardhat";
-const { networkHelpers } = await network.connect();
+const { networkHelpers } = await network.create();
await networkHelpers.mine();
```
diff --git a/src/content/docs/docs/reference/network-manager.mdx b/src/content/docs/docs/reference/network-manager.mdx
index f42755bd..15fcfcf8 100644
--- a/src/content/docs/docs/reference/network-manager.mdx
+++ b/src/content/docs/docs/reference/network-manager.mdx
@@ -33,16 +33,21 @@ import { network } from "hardhat";
## The `NetworkManager` object
-The `NetworkManager` object only has two methods:
+The `NetworkManager` object has these methods:
-- `network.connect()`: To connect to remote networks and create local blockchain simulations.
+- `network.create()`: To create connections to remote networks and local blockchain simulations.
+- `network.getOrCreate()`: Like `network.create()`, but returns an existing connection if one was previously created with the same network name and chain type.
- `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 majority of this documentation will focus on `network.create()`, as `network.createServer()` can be considered a wrapper around it.
-### The `network.connect()` method
+:::caution
+`network.connect()` is deprecated and will be removed in a future version. Use `network.create()` or `network.getOrCreate()` instead.
+:::
-When you call the `network.connect()` method, Hardhat creates a new `NetworkConnection` object.
+### The `network.create()` method
+
+When you call the `network.create()` 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.
@@ -56,7 +61,7 @@ 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();
+const connection = await network.create();
console.log(connection.networkName);
```
@@ -74,9 +79,9 @@ You can also choose a Network Config by providing its name as a string, or as pa
// script/with-name-example.ts
import { network } from "hardhat";
-const connection = await network.connect("localhost");
+const connection = await network.create("localhost");
-const connectionWithOptions = await network.connect({ network: "localhost" });
+const connectionWithOptions = await network.create({ network: "localhost" });
```
#### Network Config overrides
@@ -89,7 +94,7 @@ For example, this script creates a Network Connection with logging enabled, and
// script/with-overrides-example.ts
import { network } from "hardhat";
-const { networkHelpers } = await network.connect({
+const { networkHelpers } = await network.create({
override: { loggingEnabled: true },
});
@@ -103,7 +108,7 @@ You can also provide a `chainType` in the options object. For example:
```ts
import { network } from "hardhat";
-const { viem } = await network.connect({
+const { viem } = await network.create({
network: "hardhatOp",
chainType: "op",
});
@@ -139,11 +144,11 @@ export default defineConfig({
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, the one provided in the `network.connect()` options will take precedence, and chain-type-dependent fields like `hardfork` will be re-resolved accordingly.
+If you provide a Chain Type both as an option and as part of your Network Config, the one provided in the `network.create()` options will take precedence, and chain-type-dependent fields like `hardfork` will be re-resolved accordingly.
##### Changing the default Chain Type
-By default, the default Chain Type that's used when neither a Network Config nor the `network.connect()` options provide one is `generic`.
+By default, the default Chain Type that's used when neither a Network Config nor the `network.create()` options provide one is `generic`.
You can customize this with a [Type Extension](/docs/plugin-development/explanations/type-extensions), and a config value. Like this:
@@ -175,7 +180,7 @@ When you do that, the default Chain Type will be updated both at type-level and
// scripts/example-op.ts
import { network } from "hardhat";
-const { viem } = await network.connect();
+const { viem } = await network.create();
const publicClient = await viem.getPublicClient();
const l1Gas = await publicClient.estimateL1Gas({
@@ -191,13 +196,33 @@ You can run it with:
+### The `network.getOrCreate()` method
+
+The `network.getOrCreate()` method works like `network.create()`, but returns an existing connection if one was previously created with the same network name and chain type, instead of always creating a new one.
+
+This is useful when you want to share a single connection across different parts of your code without having to pass it around manually.
+
+```ts
+import { network } from "hardhat";
+
+// Creates a new connection the first time
+const connection1 = await network.getOrCreate("mainnet");
+
+// Returns the same connection
+const connection2 = await network.getOrCreate("mainnet");
+
+// connection1 === connection2
+```
+
+`network.getOrCreate()` takes the same parameters as `network.create()`, except that the `override` option is not supported.
+
### 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:
+This method takes the same arguments as `network.create()`, 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.
@@ -214,6 +239,6 @@ To learn more about how to use this method, see the [Running a local development
## The `NetworkConnection` object
-The `NetworkConnection` returned by `network.connect()` provides the basic functionality to interact with the network, and can be extended through plugins.
+The `NetworkConnection` returned by `network.create()` provides the basic functionality to interact with the network, and can be extended through plugins.
To learn more about it, read [this explanation](/docs/explanations/network-management#the-networkconnection-object).
diff --git a/src/content/docs/docs/tutorial/typescript-tests.mdx b/src/content/docs/docs/tutorial/typescript-tests.mdx
index ba104acd..58c3ea95 100644
--- a/src/content/docs/docs/tutorial/typescript-tests.mdx
+++ b/src/content/docs/docs/tutorial/typescript-tests.mdx
@@ -19,7 +19,7 @@ import { describe, it } from "node:test";
import { network } from "hardhat";
describe("Counter", async function () {
- const { viem } = await network.connect();
+ const { viem } = await network.create();
const publicClient = await viem.getPublicClient();
it("The sum of the Increment events should match the current value", async function () {
@@ -64,7 +64,7 @@ Run the TypeScript tests:
Besides being written in TypeScript, there are two important differences between these tests and the Solidity tests you wrote earlier:
- TypeScript tests use a test runner from the TypeScript ecosystem. Hardhat works with any test runner. In this case, you're using the built-in [`node:test`](https://nodejs.org/api/test.html) module.
-- While Solidity tests run directly on the EVM, TypeScript tests run on a locally simulated network. Each time a test calls `network.connect()`, it gets a fresh blockchain state, and any changes made during the test are discarded at the end. This is useful for integration tests, where you want a more realistic environment with proper blocks and transactions.
+- While Solidity tests run directly on the EVM, TypeScript tests run on a locally simulated network. Each time a test calls `network.create()`, it gets a fresh blockchain state, and any changes made during the test are discarded at the end. This is useful for integration tests, where you want a more realistic environment with proper blocks and transactions.
You can run both Solidity and TypeScript tests together by using the main `test` task:
diff --git a/src/content/docs/ignition/docs/guides/deploy.mdx b/src/content/docs/ignition/docs/guides/deploy.mdx
index d6b076c9..32fb1db0 100644
--- a/src/content/docs/ignition/docs/guides/deploy.mdx
+++ b/src/content/docs/ignition/docs/guides/deploy.mdx
@@ -93,7 +93,7 @@ import path from "path";
import ApolloModule from "../ignition/modules/Apollo.js";
async function main() {
- const connection = await hre.network.connect();
+ const connection = await hre.network.create();
const { apollo } = await connection.ignition.deploy(ApolloModule, {
// This must be an absolute path to your parameters JSON file
parameters: path.resolve(
diff --git a/src/content/docs/ignition/docs/guides/ethers.mdx b/src/content/docs/ignition/docs/guides/ethers.mdx
index 678c4eba..ce8c72cc 100644
--- a/src/content/docs/ignition/docs/guides/ethers.mdx
+++ b/src/content/docs/ignition/docs/guides/ethers.mdx
@@ -64,7 +64,7 @@ const ApolloModule = buildModule("Apollo", (m) => {
});
it("should have named the rocket Saturn V", async function () {
- const connection = await hre.network.connect();
+ const connection = await hre.network.create();
const { apollo } = await connection.ignition.deploy(ApolloModule);
assert.equal(await apollo.getFunction("name")(), "Saturn V");
@@ -80,7 +80,7 @@ The `ignition.deploy` method will default to using the first account in the `acc
You can change this by passing a `defaultSender` within the options object as a second argument to the `deploy` method:
```ts
-const connection = await hre.network.connect();
+const connection = await hre.network.create();
const [first, second] = await connection.ethers.getSigners();
const result = await connection.ignition.deploy(ApolloModule, {
diff --git a/src/content/docs/ignition/docs/guides/scripts.mdx b/src/content/docs/ignition/docs/guides/scripts.mdx
index f49ca805..6700ae79 100644
--- a/src/content/docs/ignition/docs/guides/scripts.mdx
+++ b/src/content/docs/ignition/docs/guides/scripts.mdx
@@ -25,7 +25,7 @@ import hre from "hardhat";
import ApolloModule from "../ignition/modules/Apollo.js";
async function main() {
- const connection = await hre.network.connect();
+ const connection = await hre.network.create();
const { apollo } = await connection.ignition.deploy(ApolloModule);
// or `apollo.getAddress()` if you're using Ethers.js
@@ -71,7 +71,7 @@ async function getRocketNameFromAPI() {
async function main() {
const rocketName = await getRocketNameFromAPI();
- const connection = await hre.network.connect();
+ const connection = await hre.network.create();
const { apollo } = await connection.ignition.deploy(ApolloModule, {
parameters: { Apollo: { rocketName } },
});
diff --git a/src/content/docs/ignition/docs/guides/tests.mdx b/src/content/docs/ignition/docs/guides/tests.mdx
index cab16eef..63f07987 100644
--- a/src/content/docs/ignition/docs/guides/tests.mdx
+++ b/src/content/docs/ignition/docs/guides/tests.mdx
@@ -35,7 +35,7 @@ const CounterModule = buildModule("Counter", (m) => {
});
it("should set the start count to 0 by default", async function () {
- const { ignition } = await network.connect();
+ const { ignition } = await network.create();
const { counter } = await ignition.deploy(CounterModule);
assert.equal(await counter.read.count(), 0);
@@ -55,7 +55,7 @@ import assert from "node:assert/strict";
import { it } from "node:test";
it("should allow setting the start count for new counters", async function () {
- const { ignition } = await network.connect();
+ const { ignition } = await network.create();
const { counter } = await ignition.deploy(CounterModule, {
parameters: {
Counter: {
@@ -79,12 +79,12 @@ import assert from "node:assert/strict";
import { it } from "node:test";
async function deployCounterModuleFixture() {
- const { ignition } = await network.connect();
+ const { ignition } = await network.create();
return ignition.deploy(CounterModule);
}
it("should set the start count to 0 by default", async function () {
- const { networkHelpers } = await network.connect();
+ const { networkHelpers } = await network.create();
const { counter } = await networkHelpers.loadFixture(
deployCounterModuleFixture,
);
@@ -100,7 +100,7 @@ The `ignition.deploy` method will default to using the first account in Hardhat
You can change this by passing a `defaultSender` within the options object as a second argument to the `deploy` method:
```ts
-const connection = await network.connect();
+const connection = await network.create();
const [first, second] = await connection.viem.getWalletClients();
const result = await connection.ignition.deploy(CounterModule, {
diff --git a/src/content/docs/ignition/docs/guides/upgradeable-proxies.mdx b/src/content/docs/ignition/docs/guides/upgradeable-proxies.mdx
index 2e59e783..affdc350 100644
--- a/src/content/docs/ignition/docs/guides/upgradeable-proxies.mdx
+++ b/src/content/docs/ignition/docs/guides/upgradeable-proxies.mdx
@@ -227,7 +227,7 @@ import DemoModule from "../ignition/modules/ProxyModule.js";
import UpgradeModule from "../ignition/modules/UpgradeModule.js";
describe("Demo Proxy", async function () {
- const { ignition, viem } = await hre.network.connect();
+ const { ignition, viem } = await hre.network.create();
describe("Proxy interaction", function () {
it("Should be usable via proxy", async function () {