feat(ignition): support maxBatchSize

.changeset/ignition-max-batch-size.md

@@ -0,0 +1,8 @@
+---
+# docs: https://github.com/NomicFoundation/hardhat-website/pull/315
+"@nomicfoundation/ignition-core": minor
+"@nomicfoundation/hardhat-ignition": minor
+"@nomicfoundation/hardhat-errors": patch
+---
+
+Add an optional `ignition.maxBatchSize` setting to split deployment batches while preserving dependency boundaries. Resume pending transactions in nonce order before starting new futures, including when reducing the batch limit between runs. The `batches` helper also accepts an optional maximum batch size.

packages/hardhat-errors/src/descriptors.ts

@@ -1794,6 +1794,14 @@ Please try again. If it persists, please open an issue in the Hardhat repository
         websiteDescription:
           "Hardhat Ignition needs to migrate the artifacts to the new format. Please run `npx hardhat ignition migrate {deploymentId}`",
       },
+      INVALID_MAX_BATCH_SIZE: {
+        number: 10003,
+        messageTemplate:
+          "Invalid maxBatchSize: {value}. Expected a positive safe integer.",
+        websiteTitle: "Invalid maximum batch size",
+        websiteDescription:
+          "The Ignition maxBatchSize option must be a positive safe integer. Omit it to leave the batch size unlimited.",
+      },
     },
     INTERNAL: {
       INTERNAL_ERROR: {

packages/hardhat-ignition/README.md

@@ -26,3 +26,20 @@ export default defineConfig({
 ## Usage
 
 To learn more about how to use Hardhat Ignition, check out the [Hardhat Ignition documentation](https://hardhat.org/ignition).
+
+### Limiting deployment batch size
+
+To limit the number of futures executed in each deployment batch, set `ignition.maxBatchSize` in your Hardhat configuration:
+
+```typescript
+export default defineConfig({
+  plugins: [hardhatIgnition],
+  ignition: {
+    maxBatchSize: 10,
+  },
+});
+```
+
+The value must be a positive safe integer. When omitted, Ignition keeps its existing dependency-based batches without a size limit. Each batch must finish successfully, including the required transaction confirmations, before the next batch starts. Splitting a batch preserves the boundaries between the original dependency batches.
+
+This limit counts futures, including operations that do not send transactions. When resuming a deployment, Ignition processes pending nonces before assigning new ones within each dependency batch. Reducing the limit does not cancel transactions that a previous run already submitted.

packages/hardhat-ignition/test/config.ts

@@ -1,4 +1,3 @@
-import type { KeyListOf } from "./test-helpers/type-helper.js";
 import type { HardhatConfig, NetworkConfig } from "hardhat/types/config";
 
 import { buildModule } from "@nomicfoundation/ignition-core";
@@ -41,6 +40,7 @@ describe("config", () => {
           blockPollingInterval: 100,
           timeBeforeBumpingFees: 60 * 1000,
           maxFeeBumps: 2,
+          maxBatchSize: 3,
           strategyConfig: {
             create2: {
               salt: "custom-salt",
@@ -68,6 +68,10 @@ describe("config", () => {
       assert.equal(loadedOptions.timeBeforeBumpingFees, 60 * 1000);
     });
 
+    it("should apply maxBatchSize", () => {
+      assert.equal(loadedOptions.maxBatchSize, 3);
+    });
+
     it("should apply maxFeeBumps", async function () {
       assert.equal(loadedOptions.maxFeeBumps, 2);
     });
@@ -119,18 +123,22 @@ describe("config", () => {
     });
 
     it("should only have known config", () => {
-      const configOptions: KeyListOf<HardhatConfig["ignition"]> = [
-        "blockPollingInterval",
-        "disableFeeBumping",
-        "maxFeeBumps",
-        "maxRetries",
-        "requiredConfirmations",
-        "retryInterval",
-        "strategyConfig",
-        "timeBeforeBumpingFees",
-      ];
-
-      assert.deepStrictEqual(Object.keys(loadedOptions).sort(), configOptions);
+      const configOptions: Record<keyof HardhatConfig["ignition"], true> = {
+        blockPollingInterval: true,
+        disableFeeBumping: true,
+        maxBatchSize: true,
+        maxFeeBumps: true,
+        maxRetries: true,
+        requiredConfirmations: true,
+        retryInterval: true,
+        strategyConfig: true,
+        timeBeforeBumpingFees: true,
+      };
+
+      assert.deepStrictEqual(
+        Object.keys(loadedOptions).sort(),
+        Object.keys(configOptions).sort(),
+      );
     });
   });