Add receipt-wait option for hardhat-ethers signer

[mmv08]

• Because this PR includes a bug fix, relevant tests have been included.
• Because this PR includes a new feature, the change was previously discussed on an Issue or with someone from the team.

---

Motivation

HardhatEthersSigner.sendTransaction currently mirrors ethers' JsonRpcSigner: after eth_sendTransaction, it polls eth_getTransactionByHash and resolves once the transaction is visible to the node. It does not wait for a receipt.

That behavior is correct as the default because it preserves ethers-compatible pending-transaction semantics. Some Hardhat tests and user code intentionally rely on receiving a TransactionResponse before the transaction is mined, especially when automining is disabled.

At the same time, many existing Hardhat test suites were authored against Hardhat's in-process network, where eth_sendTransaction effectively behaves synchronously because the transaction is mined before the call returns. When those suites are pointed at external nodes such as anvil, geth, or reth, a common pattern becomes racy:

await contract.stateChangingMethod();
const value = await contract.read();

On external RPC nodes, eth_sendTransaction can return after mempool insertion but before mining, so the read may observe pre-transaction state. This makes otherwise useful cross-client or fork-based test runs fail for reasons unrelated to contract behavior.

What Changed

This PR adds an opt-in, per-network hardhat-ethers configuration option:

networks: {
  anvil: {
    type: "http",
    url: "http://127.0.0.1:8545",
    ethers: {
      waitForTransactionReceipts: true,
    },
  },
}

When enabled for a network, HardhatEthersSigner.sendTransaction still returns the same TransactionResponse, but only after provider.waitForTransaction(hash) has observed a receipt.

Why This Is Safe

• The default remains false, so existing ethers-compatible behavior is unchanged.
• The option is scoped per network, so users can enable it only for external-node compatibility runs.
• The implementation is contained within @nomicfoundation/hardhat-ethers; it does not change Hardhat core or the network manager.
• The signer waits through provider.waitForTransaction(hash) instead of transactionResponse.wait(). This is intentional: TransactionResponse.wait() throws for status === 0 receipts, but callers and chai matchers still need the response so they can inspect reverted transactions themselves.
• Existing pending-transaction workflows remain covered by tests that assert the default behavior does not wait for a receipt.

Testing

From packages/hardhat-ethers:

pnpm lint
pnpm build
node --import tsx/esm --test --test-reporter=@nomicfoundation/hardhat-node-test-reporter "test/contracts.ts" "test/error-messages.ts" "test/gas-price.ts" "test/hardhat-ethers-provider.ts" "test/hardhat-ethers-signer.ts" "test/index.ts" "test/network-config.ts" "test/no-accounts.ts" "test/plugin-functionalities.ts" "test/provider-events.ts" "test/revert-error-cause.ts" "test/transactions.ts"

Result: 266 passing, 2 skipped.

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[changeset-bot]

🦋 Changeset detected

Latest commit: f2fb897

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

This PR includes changesets to release 1 package

Name	Type
@nomicfoundation/hardhat-ethers	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

Adds an opt-in hardhat-ethers per-network config flag to make HardhatEthersSigner.sendTransaction wait until the transaction receipt is available before resolving, improving reliability for test suites running against external RPC nodes (where eth_sendTransaction may return before mining).

Changes:

• Introduces networks.<name>.ethers.waitForTransactionReceipts config option (default false) with validation + resolution into the resolved network config.
• Updates HardhatEthersSigner.sendTransaction to optionally waitForTransaction(hash) after the transaction becomes queryable by hash.
• Adds documentation and tests covering default (no receipt wait) vs configured (receipt wait) behavior.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/hardhat-ethers/test/transactions.ts	Adds tests asserting default pending semantics vs receipt-wait behavior when configured.
packages/hardhat-ethers/test/helpers/helpers.ts	Ensures the plugin (and its config hook) is loaded in test HRE initialization.
packages/hardhat-ethers/src/type-extensions.ts	Extends Hardhat network config typings with the new ethers.waitForTransactionReceipts option.
packages/hardhat-ethers/src/internal/signers/signers.ts	Implements optional receipt-wait behavior in sendTransaction.
packages/hardhat-ethers/src/internal/hook-handlers/config.ts	Adds config hook to validate and resolve the new network-scoped option.
packages/hardhat-ethers/src/index.ts	Registers the new config hook handler for the plugin.
packages/hardhat-ethers/README.md	Documents the new configuration option and its intended use-case.
.changeset/hardhat-ethers-wait-for-receipts.md	Declares a patch release for the new option.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.