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

Author: alcuadrado

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

pnpm-lock.yaml

@@ -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/edr-simulated-networks.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/global-options.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/multichain-support.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/explanations/network-management.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/deployment/using-scripts.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/forking.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();"],
   });
 }
 ```