Add getOrCreate to network API

.changeset/fast-bees-smash.md

@@ -0,0 +1,5 @@
+---
+"hardhat": minor
+---
+
+Add `getOrCreate` to the network API

.changeset/purple-forks-write.md

@@ -0,0 +1,19 @@
+---
+"@nomicfoundation/hardhat-ethers-chai-matchers": patch
+"@nomicfoundation/hardhat-toolbox-mocha-ethers": patch
+"@nomicfoundation/hardhat-ignition-ethers": patch
+"@nomicfoundation/hardhat-network-helpers": patch
+"@nomicfoundation/hardhat-viem-assertions": patch
+"@nomicfoundation/hardhat-ignition-viem": patch
+"@nomicfoundation/hardhat-toolbox-viem": patch
+"@nomicfoundation/hardhat-ignition": patch
+"@nomicfoundation/hardhat-errors": patch
+"@nomicfoundation/hardhat-ethers": patch
+"@nomicfoundation/hardhat-ledger": patch
+"@nomicfoundation/hardhat-verify": patch
+"@nomicfoundation/ignition-core": patch
+"@nomicfoundation/hardhat-viem": patch
+"hardhat": patch
+---
+
+Deprecate the `hre.network.connect()` method in favour of `hre.network.create()`, exactly the same method but more clearly indicating that it will create a new connection.

.peer-bumps.json

@@ -21,6 +21,66 @@
       "package": "@nomicfoundation/hardhat-ignition-ethers",
       "peer": "@nomicfoundation/hardhat-ignition",
       "reason": "The usage of the new `getUserInterruptionsHandlers` helper from `@nomicfoundation/hardhat-ignition/helpers`"
+    },
+    {
+      "package": "@nomicfoundation/hardhat-ignition",
+      "peer": "hardhat",
+      "reason": "Switched from deprecated `hre.network.connect()` to new `hre.network.create()` in deploy, track-tx, transactions, and verify tasks"
+    },
+    {
+      "package": "@nomicfoundation/hardhat-verify",
+      "peer": "hardhat",
+      "reason": "Switched from deprecated `network.connect()` to new `network.create()` in verification logic and updated API docs"
+    },
+    {
+      "package": "@nomicfoundation/hardhat-ethers-chai-matchers",
+      "peer": "hardhat",
+      "reason": "Conservative bump for `connect()` deprecation and `create()`/`getOrCreate()` network API changes"
+    },
+    {
+      "package": "@nomicfoundation/hardhat-toolbox-mocha-ethers",
+      "peer": "hardhat",
+      "reason": "Conservative bump for `connect()` deprecation and `create()`/`getOrCreate()` network API changes"
+    },
+    {
+      "package": "@nomicfoundation/hardhat-ignition-ethers",
+      "peer": "hardhat",
+      "reason": "Conservative bump for `connect()` deprecation and `create()`/`getOrCreate()` network API changes"
+    },
+    {
+      "package": "@nomicfoundation/hardhat-network-helpers",
+      "peer": "hardhat",
+      "reason": "Conservative bump for `connect()` deprecation and `create()`/`getOrCreate()` network API changes"
+    },
+    {
+      "package": "@nomicfoundation/hardhat-viem-assertions",
+      "peer": "hardhat",
+      "reason": "Conservative bump for `connect()` deprecation and `create()`/`getOrCreate()` network API changes"
+    },
+    {
+      "package": "@nomicfoundation/hardhat-ignition-viem",
+      "peer": "hardhat",
+      "reason": "Conservative bump for `connect()` deprecation and `create()`/`getOrCreate()` network API changes"
+    },
+    {
+      "package": "@nomicfoundation/hardhat-toolbox-viem",
+      "peer": "hardhat",
+      "reason": "Conservative bump for `connect()` deprecation and `create()`/`getOrCreate()` network API changes"
+    },
+    {
+      "package": "@nomicfoundation/hardhat-ethers",
+      "peer": "hardhat",
+      "reason": "Conservative bump for `connect()` deprecation and `create()`/`getOrCreate()` network API changes"
+    },
+    {
+      "package": "@nomicfoundation/hardhat-ledger",
+      "peer": "hardhat",
+      "reason": "Conservative bump for `connect()` deprecation and `create()`/`getOrCreate()` network API changes"
+    },
+    {
+      "package": "@nomicfoundation/hardhat-viem",
+      "peer": "hardhat",
+      "reason": "Conservative bump for `connect()` deprecation and `create()`/`getOrCreate()` network API changes"
     }
   ]
 }

packages/example-project/hardhat.config.ts

@@ -94,7 +94,7 @@ const printConfig = task("config", "Print the config")
 const printAccounts = task("accounts", "Print the accounts")
   .setAction(async () => ({
     default: async ({}, hre) => {
-      const { provider } = await hre.network.connect();
+      const { provider } = await hre.network.create();
       console.log(await provider.request({ method: "eth_accounts" }));
     },
   }))

packages/example-project/scripts/demo-trace-output.ts

@@ -23,8 +23,8 @@ import hre from "hardhat";
 // ═══════════════════════════════════════════════════════════════════════
 //  Setup: two connections to two independent EDR-simulated networks
 // ═══════════════════════════════════════════════════════════════════════
-const connA = await hre.network.connect("default");
-const connB = await hre.network.connect("node");
+const connA = await hre.network.create("default");
+const connB = await hre.network.create("node");
 
 const [counterA, counterB, revertContract] = await Promise.all([
   connA.viem.deployContract("Counter", []),

packages/example-project/scripts/deploy-rocket-from-script.ts

@@ -2,7 +2,7 @@ import hre from "hardhat";
 
 import apolloModule from "../ignition/modules/Apollo.js";
 
-const { ignition } = await hre.network.connect();
+const { ignition } = await hre.network.create();
 
 const { apollo } = await ignition.deploy(apolloModule);
 

packages/example-project/scripts/hardhat-ethers.ts

@@ -5,7 +5,7 @@
 
 import hre from "hardhat";
 
-const { ethers } = await hre.network.connect();
+const { ethers } = await hre.network.create();
 
 // ethers functionalities
 ethers.isAddress("0x1234567890123456789012345678901234567890");

packages/example-project/scripts/ledger.ts

@@ -3,7 +3,7 @@ import assert from "node:assert";
 
 const BALANCE_TO_SEND = 1000000000000000000n;
 
-const { provider, ethers } = await hre.network.connect("edrOp");
+const { provider, ethers } = await hre.network.create("edrOp");
 
 const signers = await ethers.getSigners();
 

packages/example-project/scripts/network-helpers.ts

@@ -5,6 +5,6 @@
 
 import hre from "hardhat";
 
-const { networkHelpers } = await hre.network.connect();
+const { networkHelpers } = await hre.network.create();
 
 await networkHelpers.mine();

packages/example-project/scripts/send-op-tx-viem.ts

@@ -3,7 +3,7 @@ import { network } from "hardhat";
 async function sendL2Transaction(networkConfigName: string) {
   console.log("Sending transaction using network", networkConfigName);
 
-  const { viem, networkConfig } = await network.connect({
+  const { viem, networkConfig } = await network.create({
     network: networkConfigName,
     chainType: "op",
   });

packages/example-project/scripts/send-op-tx.ts

@@ -1,6 +1,6 @@
 import { network } from "hardhat";
 
-const { provider } = await network.connect({
+const { provider } = await network.create({
   network: "op",
   chainType: "op",
 });

packages/example-project/scripts/viem-plugin-example.ts

@@ -3,7 +3,7 @@ import { parseEther } from "viem";
 
 async function testL2Extensions() {
   // This network connection has access to an optimism-specific viem api
-  const optimism = await hre.network.connect({
+  const optimism = await hre.network.create({
     network: "localhost",
     chainType: "op",
   });
@@ -12,7 +12,7 @@ async function testL2Extensions() {
   console.log("L1 base fee:", l1BaseFee);
 
   // This one doesn't
-  const mainnet = await hre.network.connect({
+  const mainnet = await hre.network.create({
     network: "localhost",
     chainType: "l1",
   });
@@ -26,7 +26,7 @@ async function testL2Extensions() {
 }
 
 async function testClients() {
-  const networkConnection = await hre.network.connect();
+  const networkConnection = await hre.network.create();
 
   const publicClient = await networkConnection.viem.getPublicClient();
   const [fromWalletClient, toWalletClient] =
@@ -72,7 +72,7 @@ async function testClients() {
 }
 
 async function testContracts() {
-  const networkConnection = await hre.network.connect();
+  const networkConnection = await hre.network.create();
   const counter = await networkConnection.viem.deployContract("Counter");
 
   console.log("Deployed contract at address", counter.address);

packages/example-project/test/mocha/mocha-test.ts

@@ -15,7 +15,7 @@ describe("Mocha test", () => {
 
 describe("Mocha test with chai-matchers", () => {
   before(async () => {
-    await hre.network.connect();
+    await hre.network.create();
   });
 
   it("should import variables from the chai-matchers package", () => {
@@ -30,7 +30,7 @@ describe("Mocha test with chai-matchers", () => {
 
 describe("Rocket test", () => {
   it("should launch the Apollo 11 rocket", async () => {
-    const connection = await hre.network.connect();
+    const connection = await hre.network.create();
 
     const Rocket = await connection.ethers.getContractFactory("Rocket");
     const rocket = await Rocket.deploy("Apollo 11");
@@ -43,7 +43,7 @@ describe("Rocket test", () => {
 
 describe("Matchers without automining", () => {
   it("emit should wait for the tx to be mined", async () => {
-    const { ethers, provider } = await hre.network.connect();
+    const { ethers, provider } = await hre.network.create();
 
     const Rocket = await ethers.getContractFactory("Rocket");
     const rocket = await Rocket.deploy("Apollo 11");
@@ -62,7 +62,7 @@ describe("Matchers without automining", () => {
   });
 
   it("revert should wait for the tx to be mined", async () => {
-    const { ethers, provider } = await hre.network.connect();
+    const { ethers, provider } = await hre.network.create();
 
     const FailingContract = await ethers.getContractFactory("FailingContract");
     const failing = await FailingContract.deploy();

packages/example-project/test/node/example-test-of-assertions.ts

@@ -2,7 +2,7 @@ import { describe, it, before } from "node:test";
 import hre from "hardhat";
 import { ContractReturnType } from "@nomicfoundation/hardhat-viem/types";
 
-const { viem } = await hre.network.connect();
+const { viem } = await hre.network.create();
 
 describe("Example EDR based test", () => {
   describe("revert", () => {

packages/example-project/test/node/example-test.ts

@@ -4,7 +4,7 @@ import hre from "hardhat";
 
 describe("Example EDR based test", () => {
   it("should work get the block number from the EDR Network", async () => {
-    const connection = await hre.network.connect();
+    const connection = await hre.network.create();
 
     const blockNumberAtStart = await connection.provider.request({
       method: "eth_blockNumber",
@@ -24,7 +24,7 @@ describe("Example EDR based test", () => {
   });
 
   it("should show stack traces when a transaction reverts", async () => {
-    const connection = await hre.network.connect();
+    const connection = await hre.network.create();
 
     const Revert = await connection.ethers.getContractFactory("Revert");
     const revert = await Revert.deploy();

packages/hardhat-errors/src/descriptors.ts

@@ -1067,7 +1067,7 @@ Try using another mnemonic or deriving less keys.`,
         messageTemplate: "The provider has been closed.",
         websiteTitle: "Provider closed",
         websiteDescription:
-          "The provider your are trying to use has been closed. Please create a new one using hre.network.connect() and try again.",
+          "The provider you are trying to use has been closed. Please create a new one using hre.network.create() and try again.",
       },
       INCOMPATIBLE_EIP7702_FIELDS: {
         number: 723,
@@ -2232,7 +2232,7 @@ Please ensure you're using one of the supported networks.`,
 To resolve this, make sure to add an account to the specified network in the Hardhat config. Alternatively, you can set a custom wallet client by passing it as a parameter in the relevant function:
 
 \`\`\`ts
-const networkConnection = await hre.network.connect(...);
+const networkConnection = await hre.network.create(...);
 const walletClient = await networkConnection.viem.getWalletClient(address);
 
 await networkConnection.viem.deployContract(contractName, constructorArgs, { walletClient });

packages/hardhat-ethers-chai-matchers/README.md

@@ -33,7 +33,7 @@ Here is an example of using the `emit` matcher:
 import { expect } from "chai";
 import { network } from "hardhat";
 
-const { ethers } = await network.connect();
+const { ethers } = await network.create();
 
 it("some test", async function () {
   const contract = await ethers.deployContract("SomeContract");

packages/hardhat-ethers-chai-matchers/test/helpers/helpers.ts

@@ -21,7 +21,7 @@ export async function initEnvironment(_artifactsPath: string): Promise<{
 
   await hre.tasks.getTask("build").run({ force: false });
 
-  const { ethers, provider } = await hre.network.connect();
+  const { ethers, provider } = await hre.network.create();
 
   return { provider, ethers };
 }

packages/hardhat-ethers-chai-matchers/test/index.ts

@@ -15,7 +15,7 @@ describe("hardhat-ethers-chai-matchers plugin correctly initialized", () => {
 
     const hre = await createHardhatRuntimeEnvironment(hardhatConfig.default);
 
-    await hre.network.connect();
+    await hre.network.create();
 
     const result = await hre.tasks.getTask(["test", "mocha"]).run({
       testFiles: ["./test/test.ts"],

packages/hardhat-ethers-chai-matchers/test/multi-network-connections.ts

@@ -37,11 +37,11 @@ describe("handle multiple connections", () => {
       },
     });
 
-    ({ ethers } = await hre.network.connect({
+    ({ ethers } = await hre.network.create({
       network: "test1",
     }));
 
-    ({ ethers: ethers2 } = await hre.network.connect({
+    ({ ethers: ethers2 } = await hre.network.create({
       network: "test2",
     }));
   });

packages/hardhat-ethers/README.md

@@ -30,7 +30,7 @@ This plugin adds an `ethers` property to each network connection:
 ```ts
 import { network } from "hardhat";
 
-const { ethers } = await network.connect();
+const { ethers } = await network.create();
 
 const counter = await ethers.deployContract("Counter");
 await counter.inc();
@@ -41,7 +41,7 @@ This object has the same API as [ethers.js](https://docs.ethers.org/), with some
 
 ### Provider
 
-The plugin adds a `provider` property to the `ethers` object: an [ethers.js provider](https://docs.ethers.org/v6/single-page/#api_providers__Provider) connected to the network selected by `network.connect()`.
+The plugin adds a `provider` property to the `ethers` object: an [ethers.js provider](https://docs.ethers.org/v6/single-page/#api_providers__Provider) connected to the network selected by `network.create()`.
 
 ```ts
 const blockNumber = await ethers.provider.getBlockNumber();
@@ -84,10 +84,10 @@ An [ethers.js provider](https://docs.ethers.org/v6/single-page/#api_providers__P
 
 ```ts
 // the network selected with --network option if specified, or the default network otherwise
-const { ethers } = await network.connect();
+const { ethers } = await network.create();
 
 // a specific network from the config
-const { ethers } = await network.connect("mainnet");
+const { ethers } = await network.create("mainnet");
 ```
 
 ### `deployContract`

packages/hardhat-ethers/test/helpers/helpers.ts

@@ -30,7 +30,7 @@ export async function initializeTestEthers(
   const network =
     config.networks?.localhost !== undefined ? "localhost" : "default";
 
-  const connection = await hre.network.connect(network);
+  const connection = await hre.network.create(network);
 
   const provider = connection.provider;
   const networkName = connection.networkName;

packages/hardhat-ethers/test/index.ts

@@ -18,7 +18,7 @@ describe("hardhat-ethers plugin initialization", () => {
       plugins: [hardhatEthersPlugin],
     });
 
-    ({ ethers } = await hre.network.connect());
+    ({ ethers } = await hre.network.create());
   });
 
   it("should correctly set up ethers functionalities", async () => {

packages/hardhat-ignition-ethers/README.md

@@ -31,7 +31,7 @@ This plugin adds an `ignition` property to each network connection:
 import { network } from "hardhat";
 import Counter from "../ignition/modules/Counter.js";
 
-const { ignition } = await network.connect();
+const { ignition } = await network.create();
 const { counter } = await ignition.deploy(Counter);
 
 await counter.inc();

packages/hardhat-ignition-ethers/test/ignition-helper-exclusivity.ts

@@ -50,7 +50,7 @@ describe("ignition helper mutual exclusivity", () => {
           plugins: [fakeHardhatIgnitionViemPlugin, hardhatIgnitionEthersPlugin],
         });
 
-        return hre.network.connect();
+        return hre.network.create();
       },
       HardhatError.ERRORS.IGNITION.INTERNAL
         .ONLY_ONE_IGNITION_EXTENSION_PLUGIN_ALLOWED,

packages/hardhat-ignition-ethers/test/test-helpers/create-hre.ts

@@ -10,7 +10,7 @@ import hardhatIgnitionEthers from "../../src/index.js";
 
 export async function createConnection(): Promise<NetworkConnection> {
   const hre = await createHre();
-  const connection = await hre.network.connect();
+  const connection = await hre.network.create();
 
   await connection.provider.request({
     method: "evm_setAutomine",