[gaohan1994]

• Because this PR includes a new feature, the change was previously discussed in an Issue or with someone from the team.
• Relevant regression and integration tests have been included.

---

Summary

Adds an optional ignition.maxBatchSize to limit the number of futures in each deployment batch. This addresses #7648, following the requirement and review discussion in #7670. Each dependency batch is split separately, and the next chunk starts only after the current chunk succeeds. Omitting the setting preserves the existing batch partitioning.

The public batches(module, maxBatchSize?) helper supports the same limit. Invalid values are rejected as HHE10003, including for empty modules. The setting must be a positive safe integer.

Resuming deployments

Execution chunks are formed after nonce synchronization. Synchronization can clear a nonce when the user has replaced a transaction; splitting before that step can put a newly assigned higher nonce ahead of a dropped transaction that still needs to be resent.

Pending transactions are explicitly ordered before new futures, then by case-normalized sender, nonce, and future ID. Normalizing the sort key keeps different address casing for the same account in nonce order; it does not change the sender stored in deployment state. This also fixes the existing sort helper's reliance on an uppercase sentinel address, which could sort before a lowercase sender. That ordering correction also applies when no batch limit is configured.

The batch initialization event reports the chunks actually executed. With a limit configured, it is emitted after RUN_START and nonce synchronization, but before the first BEGIN_NEXT_BATCH; the built-in event handler is covered by the deployment-task test. Tests cover confirmation barriers, failure stopping subsequent chunks, completed-deployment reruns, a newly added future sorting before a pending one, reversed ID/nonce order, reducing the limit on resume, mixed-case sender addresses for the same account, and a user-replaced transaction combined with a dropped transaction. A separate test executes the real ignition deploy task to verify global config propagation and the real event handler's batch list.

Scope

The limit counts futures, including futures that do not send transactions. It is not a network-wide pending-transaction cap, and lowering it does not cancel transactions already broadcast by an earlier run. It does not address the separate mempool error-reporting work in #7638.

Documentation and a changeset are included. Companion website documentation: NomicFoundation/hardhat-website#315 (also linked from the changeset frontmatter). Please publish it alongside the release containing this feature. The config-key coverage test now uses a Record instead of enumerating all key permutations, avoiding TypeScript memory exhaustion when adding the ninth option while retaining exhaustive key checking.

Validation

Validated with Node.js 22.22.3 and pnpm 12.9.1 (TERM=xterm-256color, color overrides unset):

• Root pnpm test passes across the workspace, including downstream Ignition ethers/viem plugins and the example project.
• Affected package tests: 1,057 passing, 11 existing pending (Ignition core: 786 unit + 48 integration; Hardhat Ignition: 185; hardhat-errors: 38).
• New regression scenarios were observed failing before the corresponding fixes and passing afterwards, including mixed-case dropped-transaction recovery.
• Root pnpm lint passes, including its full-workspace build prehook, package lint/type checks, API extraction, and script/workflow formatting checks.
• git diff --check passes.

An earlier full-suite attempt hit timeouts while downloading solc. After rerunning the compiler test and populating the local cache, the complete root test command passed without source changes.

Maintainer checklist

No peer dependency range change is requested: this optional configuration field and batching behavior do not consume new APIs from peer packages. If you agree, please apply the no peer bump needed label required by the repository check. The changeset covers the packages that implement and expose the setting.

[changeset-bot]

🦋 Changeset detected

Latest commit: f24257e

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

This PR includes changesets to release 3 packages

Name	Type
@nomicfoundation/ignition-core	Minor
@nomicfoundation/hardhat-ignition	Minor
@nomicfoundation/hardhat-errors	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