Add getOrCreate to network API by kanej · Pull Request #8116 · NomicFoundation/hardhat

kanej · 2026-04-08T16:53:11Z

To improve clarity around the lifetime of connections we are altering the Network API by:

Renaming hre.network.connect(...) to hre.network.create(..) for clarity
Retaining the existing hre.network.connect(...) but marking it as deprecated
Adding hre.network.getOrCreate(...) to support singleton use cases

A deprecation warning will be shown once per hre instance via Node's process.emitWarning on usage of connect.

New API

export interface NetworkManager {
  /**
   * Creates a new network connection based on the provided parameters.
   *
   * @param networkOrParams The network name or connection parameters. When
   * omitted, the default network is used.
   *
   * @returns A new {@link NetworkConnection} for the specified network.
   */
  create<ChainTypeT extends ChainType | string = DefaultChainType>(
    networkOrParams?: NetworkConnectionParams<ChainTypeT> | string,
  ): Promise<NetworkConnection<ChainTypeT>>;

  /**
   * Creates a new network connection based on the provided parameters.
   *
   * @deprecated Use {@link NetworkManager.create} or
   * {@link NetworkManager.getOrCreate} instead.
   *
   * - {@link NetworkManager.create} always creates a new network instance.
   * - {@link NetworkManager.getOrCreate} returns an existing instance if one exists.
   *
   * `connect` will be removed in a future version of Hardhat.
   *
   * @param networkOrParams The network name or connection parameters. When
   * omitted, the default network is used.
   *
   * @returns A new {@link NetworkConnection} for the specified network.
   */
  connect<ChainTypeT extends ChainType | string = DefaultChainType>(
    networkOrParams?: NetworkConnectionParams<ChainTypeT> | string,
  ): Promise<NetworkConnection<ChainTypeT>>;

  /**
   * Returns an existing network connection if one was previously created
   * with the same network name and chain type. Creates a new one otherwise.
   *
   * @param networkOrParams The network name or connection parameters. When
   * omitted, the default network is used. Overrides are not supported.
   *
   * @returns A {@link NetworkConnection} for the specified network, cached
   * by network name and chain type.
   */
  getOrCreate<ChainTypeT extends ChainType | string = DefaultChainType>(
    networkOrParams?: CachedNetworkConnectionParams<ChainTypeT> | string,
  ): Promise<NetworkConnection<ChainTypeT>>;
}

Deprecation warning

Calls to connect are recorded and a deprecation warning printed at the end:

  Example EDR based test
    ✔ should work get the block number from the EDR Network (10691ms)
    ✔ should show stack traces when a transaction reverts (106ms)

  Other example test
    ✔ should have the example task


46 passing (30 solidity, 7 mocha, 9 nodejs)

WARNING: hre.network.connect() is deprecated and will be removed in a future version. Use hre.network.create() or hre.network.getOrCreate() instead.

Note

The warning is only shown if the default hre instance is used.

Review

Note

Review a commit at a time

This PR affects many files as we have switched the default usage in docs and examples from hre.network.connect() to hre.network.create(). This change is mainly a mechanical refactor, and is captured in the first commit.

Docs PR

Update network API references to include create and createOrGet hardhat-website#249

TODO

Is the lifetime of the cache acceptable
Look at the signature on createOrGet, can it be brought into line with create
Review requirement for logging if connect used

In the network API we rename `hre.network.connect()` to `hre.network.create()`. This commit is a mechanical rename using refactoring and search and replace.

changeset-bot · 2026-04-08T16:53:17Z

🦋 Changeset detected

Latest commit: bb81d75

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 15 packages

Name	Type
hardhat	Minor
@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

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Copilot

Pull request overview

This PR updates Hardhat’s network API to make connection lifetimes clearer by introducing hre.network.create(...), deprecating (but retaining) hre.network.connect(...), and adding hre.network.getOrCreate(...) for singleton-style cached connections. It also mechanically updates internal code, tests, templates, and package READMEs to prefer create().

Changes:

Add NetworkManager.create(...) and NetworkManager.getOrCreate(...) and mark connect(...) as deprecated in types.
Implement create/getOrCreate in NetworkManagerImplementation, with caching keyed by network name + chain type.
Replace most usages of connect() with create() across tests, templates, examples, and documentation.

Reviewed changes

Copilot reviewed 73 out of 73 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/ignition-core/test-integrations/helpers/create-hre.ts	Update helper to use `hre.network.create()`
packages/hardhat/test/internal/builtin-plugins/node/json-rpc/server.ts	Update test to use `hre.network.create()`
packages/hardhat/test/internal/builtin-plugins/network-manager/request-handlers/e2e.ts	Update e2e tests to use `hre.network.create()`
packages/hardhat/test/internal/builtin-plugins/network-manager/network-manager.ts	Update tests for `create()` and add coverage for `connect/getOrCreate`
packages/hardhat/test/internal/builtin-plugins/network-manager/edr/edr-provider.ts	Update tests to use `hre.network.create()`
packages/hardhat/templates/hardhat-3/02-mocha-ethers/test/Counter.ts	Template: switch to `network.create()`
packages/hardhat/templates/hardhat-3/02-mocha-ethers/scripts/send-op-tx.ts	Template: switch to `network.create()`
packages/hardhat/templates/hardhat-3/01-node-test-runner-viem/test/Counter.ts	Template: switch to `network.create()`
packages/hardhat/templates/hardhat-3/01-node-test-runner-viem/scripts/send-op-tx.ts	Template: switch to `network.create()`
packages/hardhat/src/types/network.ts	Add `create/getOrCreate` typings + deprecate `connect`
packages/hardhat/src/internal/builtin-plugins/node/task-action.ts	Switch node task initialization to `hre.network.create()`
packages/hardhat/src/internal/builtin-plugins/network-manager/network-manager.ts	Implement `create`, `connect` alias, and `getOrCreate` cache
packages/hardhat/src/internal/builtin-plugins/network-manager/hook-handlers/hre.ts	Expose `create/getOrCreate` on `hre.network` and rewire `connect`
packages/hardhat-viem/test/hook-handlers/network.ts	Update to use `hre.network.create()`
packages/hardhat-viem/test/contracts.ts	Update to use `hre.network.create()`
packages/hardhat-viem/test/clients.ts	Update to use `hre.network.create()`
packages/hardhat-viem/README.md	Docs: switch examples to `network.create()`
packages/hardhat-viem-assertions/test/internal/assertions/revert/revert.ts	Update to use `hre.network.create()`
packages/hardhat-viem-assertions/test/internal/assertions/revert/revert-with.ts	Update to use `hre.network.create()`
packages/hardhat-viem-assertions/test/internal/assertions/revert/revert-with-custom-error.ts	Update to use `hre.network.create()`
packages/hardhat-viem-assertions/test/internal/assertions/revert/revert-with-custom-error-with-args.ts	Update to use `hre.network.create()`
packages/hardhat-viem-assertions/test/internal/assertions/emit/emit.ts	Update to use `hre.network.create()`
packages/hardhat-viem-assertions/test/internal/assertions/emit/emit-with-args.ts	Update to use `hre.network.create()`
packages/hardhat-viem-assertions/test/internal/assertions/balances-have-changed.ts	Update to use `hre.network.create()`
packages/hardhat-viem-assertions/README.md	Docs: switch examples to `hre.network.create()`
packages/hardhat-verify/test/verification.ts	Update tests to use `hre.network.create()`
packages/hardhat-verify/test/hook-handlers/network.ts	Update tests to use `hre.network.create()`
packages/hardhat-verify/src/internal/verification.ts	Switch verification logic to `network.create()`
packages/hardhat-verify/src/internal/etherscan.types.ts	Update doc comments to reference `network.create()`
packages/hardhat-verify/README.md	Docs: switch examples to `hre.network.create()`
packages/hardhat-toolbox-viem/test/fixture-projects/toolbox/scripts/script.ts	Fixture: switch to `network.create()`
packages/hardhat-toolbox-mocha-ethers/test/fixture-projects/toolbox/scripts/script.ts	Fixture: switch to `network.create()`
packages/hardhat-network-helpers/test/index.ts	Update tests to use `hre.network.create()`
packages/hardhat-network-helpers/test/helpers/helpers.ts	Update helper to use `hre.network.create()`
packages/hardhat-network-helpers/src/types.ts	Update API docs/examples to use `hre.network.create()`
packages/hardhat-network-helpers/README.md	Docs: switch examples to `network.create()`
packages/hardhat-ledger/test/integration.ts	Update tests to use `hre.network.create()` (and fix var typo)
packages/hardhat-ledger/README.md	Docs: switch examples to `hre.network.create()`
packages/hardhat-ignition/test/test-helpers/use-ignition-project.ts	Update tests/helpers to use `hre.network.create()`
packages/hardhat-ignition/test/test-helpers/create-hre.ts	Update helper to use `hre.network.create()`
packages/hardhat-ignition/src/internal/tasks/verify.ts	Switch ignition task to `hre.network.create()`
packages/hardhat-ignition/src/internal/tasks/transactions.ts	Switch ignition task to `hre.network.create()`
packages/hardhat-ignition/src/internal/tasks/track-tx.ts	Switch ignition task to `hre.network.create()`
packages/hardhat-ignition/src/internal/tasks/deploy.ts	Switch ignition task to `hre.network.create()`
packages/hardhat-ignition-viem/test/test-helpers/create-hre.ts	Update helper to use `hre.network.create()`
packages/hardhat-ignition-viem/test/ignition-helper-exclusivity.ts	Update test to use `hre.network.create()`
packages/hardhat-ignition-viem/README.md	Docs: switch examples to `network.create()`
packages/hardhat-ignition-ethers/test/test-helpers/create-hre.ts	Update helper to use `hre.network.create()`
packages/hardhat-ignition-ethers/test/ignition-helper-exclusivity.ts	Update test to use `hre.network.create()`
packages/hardhat-ignition-ethers/README.md	Docs: switch examples to `network.create()`
packages/hardhat-ethers/test/index.ts	Update tests to use `hre.network.create()`
packages/hardhat-ethers/test/helpers/helpers.ts	Update helpers to use `hre.network.create()`
packages/hardhat-ethers/README.md	Docs: switch examples to `network.create()`
packages/hardhat-ethers-chai-matchers/test/multi-network-connections.ts	Update tests to use `hre.network.create()`
packages/hardhat-ethers-chai-matchers/test/index.ts	Update tests to use `hre.network.create()`
packages/hardhat-ethers-chai-matchers/test/helpers/helpers.ts	Update helpers to use `hre.network.create()`
packages/hardhat-ethers-chai-matchers/README.md	Docs: switch examples to `network.create()`
packages/hardhat-errors/src/descriptors.ts	Fix typo + update guidance to `hre.network.create()`
packages/example-project/test/node/example-test.ts	Example tests: switch to `hre.network.create()`
packages/example-project/test/node/example-test-of-assertions.ts	Example tests: switch to `hre.network.create()`
packages/example-project/test/mocha/mocha-test.ts	Example tests: switch to `hre.network.create()`
packages/example-project/scripts/viem-plugin-example.ts	Example script: switch to `hre.network.create()`
packages/example-project/scripts/send-op-tx.ts	Example script: switch to `network.create()`
packages/example-project/scripts/send-op-tx-viem.ts	Example script: switch to `network.create()`
packages/example-project/scripts/network-helpers.ts	Example script: switch to `hre.network.create()`
packages/example-project/scripts/ledger.ts	Example script: switch to `hre.network.create()`
packages/example-project/scripts/hardhat-ethers.ts	Example script: switch to `hre.network.create()`
packages/example-project/scripts/deploy-rocket-from-script.ts	Example script: switch to `hre.network.create()`
packages/example-project/scripts/demo-trace-output.ts	Example script: switch to `hre.network.create()`
packages/example-project/hardhat.config.ts	Example task: switch to `hre.network.create()`
.peer-bumps.json	Record peer bump reasons due to API usage changes
.changeset/purple-forks-write.md	Changeset: deprecate `connect()` in favor of `create()`
.changeset/fast-bees-smash.md	Changeset: add `getOrCreate` as a minor change

Add the `connect` method back the the network manager API, exactly matching the old connect (that has now been renamed to `create`). Add a deprecation warning to the method. The method is a pass through alias to `create`. A test has been added as a simple regression to check that connect is passing through to create.

This is a caching api providing singleton semantics for the same network name and chain type. The API matches `create` except that overrides are banned (as this would break the caching). The signature types enforce this along with a runtime check.

Most updates are to docs or readmes, requiring a changeset for release but not a peer depenency bump. The two exceptions are Ignition, which uses the new create API during deployment (among other things), and `hardhat-verify` which creates a connection to get a network name.

Copilot

Pull request overview

Copilot reviewed 73 out of 73 changed files in this pull request and generated 2 comments.

Copilot · 2026-04-08T18:43:57Z

+export interface CachedNetworkConnectionParams<
+  ChainTypeT extends ChainType | string = DefaultChainType,
+> extends NetworkConnectionParams<ChainTypeT> {
+  override?: never;
+}


CachedNetworkConnectionParams extends NetworkConnectionParams and sets override?: never, but without exactOptionalPropertyTypes this still permits override: undefined (and in general doesn’t strongly prevent an override key from being passed), which can lead to a surprising runtime error in getOrCreate when callers accidentally include the key. Consider defining CachedNetworkConnectionParams without inheriting override (e.g. omit the field entirely) so excess-property checks reliably flag override in object literals.

I am happy either way on this one. The inheritance is to avoid the two types drifting, but if there is a practical advantage to duplicating the type we can take that approach.

alcuadrado · 2026-04-09T13:50:49Z

+"hardhat": minor
+---
+
+Add `getOrCreate` to the network API


Suggested change

Add `getOrCreate` to the network API

Add `create` and `getOrCreate` to the network API

maybe?

I split out the create changeset into .changeset/purple-forks-write.md, so it could get a more detailed explanation.

alcuadrado · 2026-04-09T14:02:18Z

      "reason": "The usage of the new `getUserInterruptionsHandlers` helper from `@nomicfoundation/hardhat-ignition/helpers`"
+    },
+    {
+      "package": "@nomicfoundation/hardhat-ignition",


I think this needs all the packages that have hardhat as a peer, no just the top-level ones.

I mean, all the packages in this PR

Most of the packages that are touched here are because of updates to documentation e.g. their README.md had a reference to hre.network.connect.
I am happy to add them as the least risky approach.

I see. I didn't notice that. I think it still makes sense to play safe and bump it.

I have added in the extra bumps.

Copilot

Pull request overview

Copilot reviewed 74 out of 74 changed files in this pull request and generated 4 comments.

kanej · 2026-04-09T17:54:59Z

@alcuadrado I switched to a deprecation console warning from main as discussed: 02d3a74

It will print the warning once at the end, but only if you used connect in the in default hre instance:

  Example EDR based test
    ✔ should work get the block number from the EDR Network (10691ms)
    ✔ should show stack traces when a transaction reverts (106ms)

  Other example test
    ✔ should have the example task


46 passing (30 solidity, 7 mocha, 9 nodejs)

WARNING: hre.network.connect() is deprecated and will be removed in a future version. Use hre.network.create() or hre.network.getOrCreate() instead.

feat: rename connect to create in network API

c96f10a

In the network API we rename `hre.network.connect()` to `hre.network.create()`. This commit is a mechanical rename using refactoring and search and replace.

Copilot AI review requested due to automatic review settings April 8, 2026 16:53

Copilot started reviewing on behalf of kanej April 8, 2026 16:53 View session

Copilot AI reviewed Apr 8, 2026

View reviewed changes

Comment thread packages/hardhat/src/internal/builtin-plugins/network-manager/network-manager.ts

Comment thread packages/hardhat/src/internal/builtin-plugins/network-manager/hook-handlers/hre.ts

kanej commented Apr 8, 2026

View reviewed changes

Comment thread packages/hardhat/src/internal/builtin-plugins/network-manager/network-manager.ts

kanej force-pushed the feat/get-or-create branch from 9b81e61 to 447969c Compare April 8, 2026 18:24

kanej commented Apr 8, 2026

View reviewed changes

Comment thread packages/hardhat/src/internal/builtin-plugins/network-manager/network-manager.ts Outdated

kanej commented Apr 8, 2026

View reviewed changes

Comment thread packages/hardhat/src/internal/builtin-plugins/network-manager/network-manager.ts Outdated

kanej added 3 commits April 8, 2026 18:39

feat: add getOrCreate to network API

0920de0

This is a caching api providing singleton semantics for the same network name and chain type. The API matches `create` except that overrides are banned (as this would break the caching). The signature types enforce this along with a runtime check.

kanej force-pushed the feat/get-or-create branch from 447969c to 88787e1 Compare April 8, 2026 18:39

Copilot AI review requested due to automatic review settings April 8, 2026 18:39

Copilot started reviewing on behalf of kanej April 8, 2026 18:40 View session

Copilot AI reviewed Apr 8, 2026

View reviewed changes

kanej requested a review from alcuadrado April 8, 2026 18:51

alcuadrado reviewed Apr 9, 2026

View reviewed changes

kanej added 2 commits April 9, 2026 17:13

display connect deprecation warning at end

02d3a74

chore: conservatively update peer bumps

bb81d75

Copilot AI review requested due to automatic review settings April 9, 2026 17:45

Copilot started reviewing on behalf of kanej April 9, 2026 17:45 View session

Copilot AI reviewed Apr 9, 2026

View reviewed changes

kanej requested a review from alcuadrado April 9, 2026 17:55

alcuadrado approved these changes Apr 9, 2026

View reviewed changes

alcuadrado added this pull request to the merge queue Apr 10, 2026

Merged via the queue into main with commit 48d01ae Apr 10, 2026
262 checks passed

alcuadrado deleted the feat/get-or-create branch April 10, 2026 17:37

github-actions Bot mentioned this pull request Apr 10, 2026

Version Packages (v3) #8099

Merged

	Add `getOrCreate` to the network API
	Add `create` and `getOrCreate` to the network API

Conversation

kanej commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

New API

Deprecation warning

Review

Docs PR

TODO

Uh oh!

changeset-bot Bot commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kanej commented Apr 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kanej commented Apr 8, 2026 •

edited

Loading

changeset-bot Bot commented Apr 8, 2026 •

edited

Loading