Replace connect() with create() and getOrCreate()

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.
 

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",

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.

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:
 

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.
 

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:
 
 <Run command="hardhat --network mainnet" />
 
-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();
 ```
 
 :::

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}...`);
 

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
   });

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:
 
-<Run command='hardhat console "const { viem } = await network.connect();" />' />
+<Run command='hardhat console "const { viem } = await network.create();"' />
 
 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();"],
   });
 }
 ```

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();
 

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() {

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();
 ```

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) {