feat(sdk): use routing ISM setBatch/removeBatch when available

paulbalaji · paulbalaji · commit e2c6a517d5cb · 2026-04-22T18:31:07.000+01:00
Adds a PACKAGE_VERSION gate on the target routing ISM. When it reports
&gt;= 11.4.0 (where setBatch/removeBatch were introduced), consolidate
enrollments and unenrollments into chunked setBatch/removeBatch txs
sized by domainRoutingInitializationSize(destination). Older ISMs fall
back to per-domain set()/remove() loops.

Applies to three paths:
- Reconfigure-existing-ISM enrollments and unenrollments
- Post-initializer follow-on enrollments on new DomainRoutingIsm /
  IncrementalDomainRoutingIsm deploys
- DefaultFallbackRoutingIsm new deploys (initialize with initial batch
  + setBatch remainder, matching the sharding already done on the
  proxy-factory path)
diff --git a/.changeset/routing-ism-batch-sdk.md b/.changeset/routing-ism-batch-sdk.md
@@ -0,0 +1,5 @@
+---
+'@hyperlane-xyz/sdk': minor
+---
+
+Wired `HyperlaneIsmFactory` to use the routing ISM `setBatch` and `removeBatch` functions added in `@hyperlane-xyz/core` 11.4.0. Enrollments and unenrollments are now consolidated into chunked batched transactions sized by the per-chain `domainRoutingInitializationSize`, avoiding one tx per domain on low-capacity chains (citrea, shibarium, tempo, etc.). Version-gated via `PACKAGE_VERSION()` on the target routing ISM, with a per-domain fallback for older deployed ISMs.
diff --git a/typescript/sdk/src/ism/HyperlaneIsmFactory.ts b/typescript/sdk/src/ism/HyperlaneIsmFactory.ts
@@ -31,6 +31,7 @@ import {
   TrustedRelayerIsm__factory,
   ZKSyncArtifact,
 } from '@hyperlane-xyz/core';
+
 import {
   Address,
   Domain,
@@ -84,6 +85,31 @@ const ismFactories = {
   [IsmType.CCIP]: new CCIPIsm__factory(),
 };
 
+// First @hyperlane-xyz/core version with setBatch/removeBatch on
+// DomainRoutingIsm. Routing ISMs at or above this version let the SDK
+// consolidate per-domain txs into chunked setBatch/removeBatch calls;
+// older ISMs fall back to the per-domain loop.
+const ROUTING_ISM_BATCH_MIN_VERSION = { major: 11, minor: 4 };
+
+const routingIsmSupportsBatch = async (
+  address: Address,
+  provider: ethers.providers.Provider,
+): Promise<boolean> => {
+  try {
+    const version = await DomainRoutingIsm__factory.connect(
+      address,
+      provider,
+    ).PACKAGE_VERSION();
+    const [major, minor] = version.split('.').map((n) => Number.parseInt(n));
+    if (!Number.isFinite(major) || !Number.isFinite(minor)) return false;
+    if (major > ROUTING_ISM_BATCH_MIN_VERSION.major) return true;
+    if (major < ROUTING_ISM_BATCH_MIN_VERSION.major) return false;
+    return minor >= ROUTING_ISM_BATCH_MIN_VERSION.minor;
+  } catch {
+    return false;
+  }
+};
+
 const domainRoutingInitializationSize = (destination: ChainName) => {
   if (destination === 'tempo') {
     return 30;
@@ -541,7 +567,14 @@ export class HyperlaneIsmFactory extends HyperlaneApp<ProxyFactoryFactories> {
         existingIsmAddress,
         this.multiProvider.getSigner(destination),
       );
+      const batchSize = domainRoutingInitializationSize(destination);
+      const supportsBatch = await routingIsmSupportsBatch(
+        existingIsmAddress,
+        provider,
+      );
+
       // deploying all the ISMs which have to be updated
+      const enrollAddresses: Address[] = [];
       for (const originDomain of delta.domainsToEnroll) {
         const origin = this.multiProvider.getChainName(originDomain); // already filtered to only include domains in the multiprovider
         logger.debug(
@@ -554,20 +587,46 @@ export class HyperlaneIsmFactory extends HyperlaneApp<ProxyFactoryFactories> {
           mailbox,
         });
         isms[originDomain] = ism.address;
-        const tx = await routingIsm.set(
-          originDomain,
-          isms[originDomain],
+        enrollAddresses.push(ism.address);
+      }
+      if (supportsBatch) {
+        await this.setDomainsBatched(
+          routingIsm,
+          delta.domainsToEnroll,
+          enrollAddresses,
+          batchSize,
           overrides,
+          destination,
+          logger,
         );
-        await this.multiProvider.handleTx(destination, tx);
+      } else {
+        for (let i = 0; i < delta.domainsToEnroll.length; i++) {
+          const tx = await routingIsm.set(
+            delta.domainsToEnroll[i],
+            enrollAddresses[i],
+            overrides,
+          );
+          await this.multiProvider.handleTx(destination, tx);
+        }
       }
       // unenrolling domains if needed
-      for (const originDomain of delta.domainsToUnenroll) {
-        logger.debug(
-          `Unenrolling originDomain ${originDomain} from preexisting routing ISM at ${existingIsmAddress}...`,
+      if (supportsBatch && delta.domainsToUnenroll.length > 0) {
+        await this.removeDomainsBatched(
+          routingIsm,
+          delta.domainsToUnenroll,
+          batchSize,
+          overrides,
+          destination,
+          logger,
         );
-        const tx = await routingIsm.remove(originDomain, overrides);
-        await this.multiProvider.handleTx(destination, tx);
+      } else {
+        for (const originDomain of delta.domainsToUnenroll) {
+          logger.debug(
+            `Unenrolling originDomain ${originDomain} from preexisting routing ISM at ${existingIsmAddress}...`,
+          );
+          const tx = await routingIsm.remove(originDomain, overrides);
+          await this.multiProvider.handleTx(destination, tx);
+        }
       }
       // transfer ownership if needed
       if (delta.owner) {
@@ -603,16 +662,50 @@ export class HyperlaneIsmFactory extends HyperlaneApp<ProxyFactoryFactories> {
           await getZKSyncArtifactByContractName(config.type),
         );
         // TODO: Should verify contract here
-        logger.debug('Initialising fallback routing ISM ...');
+        const batchSize = domainRoutingInitializationSize(destination);
+        const initialBatchSize = Math.min(batchSize, safeConfigDomains.length);
+        const initialDomains = safeConfigDomains.slice(0, initialBatchSize);
+        const initialAddresses = submoduleAddresses.slice(0, initialBatchSize);
+        logger.debug(
+          `Initialising fallback routing ISM with ${initialBatchSize} domains on ${destination}`,
+        );
         receipt = await this.multiProvider.handleTx(
           destination,
           routingIsm['initialize(address,uint32[],address[])'](
             config.owner,
-            safeConfigDomains,
-            submoduleAddresses,
+            initialDomains,
+            initialAddresses,
             overrides,
           ),
         );
+        const remainingDomains = safeConfigDomains.slice(initialBatchSize);
+        const remainingAddresses = submoduleAddresses.slice(initialBatchSize);
+        if (remainingDomains.length > 0) {
+          const supportsBatch = await routingIsmSupportsBatch(
+            routingIsm.address,
+            provider,
+          );
+          if (supportsBatch) {
+            await this.setDomainsBatched(
+              routingIsm,
+              remainingDomains,
+              remainingAddresses,
+              batchSize,
+              overrides,
+              destination,
+              logger,
+            );
+          } else {
+            for (let i = 0; i < remainingDomains.length; i++) {
+              const tx = await routingIsm.set(
+                remainingDomains[i],
+                remainingAddresses[i],
+                overrides,
+              );
+              await this.multiProvider.handleTx(destination, tx);
+            }
+          }
+        }
       } else {
         // deploying new domain routing ISM
         const owner = config.owner;
@@ -704,27 +797,47 @@ export class HyperlaneIsmFactory extends HyperlaneApp<ProxyFactoryFactories> {
 
         // Enroll remaining domains and addresses
         // If all domains are enrolled already, this is a no-op
-        for (let i = initialBatchSize; i < safeConfigDomains.length; i++) {
-          const estimatedGas = await routingIsm.estimateGas.set(
-            safeConfigDomains[i],
-            submoduleAddresses[i],
-            overrides,
-          );
-          const chainName = this.multiProvider.getChainName(
-            safeConfigDomains[i],
-          );
-          this.logger.debug(
-            `Enrolling ${chainName} (${safeConfigDomains[i]}) ISM at ${submoduleAddresses[i]} on Domain Routing ISM ${moduleAddress}`,
-          );
-          const enrollTx = await routingIsm.set(
-            safeConfigDomains[i],
-            submoduleAddresses[i],
-            {
-              gasLimit: addBufferToGasLimit(estimatedGas, 15),
-              ...overrides,
-            },
+        const remainingDomains = safeConfigDomains.slice(initialBatchSize);
+        const remainingAddresses = submoduleAddresses.slice(initialBatchSize);
+        if (remainingDomains.length > 0) {
+          const supportsBatch = await routingIsmSupportsBatch(
+            moduleAddress,
+            provider,
           );
-          await this.multiProvider.handleTx(destination, enrollTx);
+          if (supportsBatch) {
+            await this.setDomainsBatched(
+              routingIsm,
+              remainingDomains,
+              remainingAddresses,
+              batchSize,
+              overrides,
+              destination,
+              logger,
+            );
+          } else {
+            for (let i = 0; i < remainingDomains.length; i++) {
+              const estimatedGas = await routingIsm.estimateGas.set(
+                remainingDomains[i],
+                remainingAddresses[i],
+                overrides,
+              );
+              const chainName = this.multiProvider.getChainName(
+                remainingDomains[i],
+              );
+              this.logger.debug(
+                `Enrolling ${chainName} (${remainingDomains[i]}) ISM at ${remainingAddresses[i]} on Domain Routing ISM ${moduleAddress}`,
+              );
+              const enrollTx = await routingIsm.set(
+                remainingDomains[i],
+                remainingAddresses[i],
+                {
+                  gasLimit: addBufferToGasLimit(estimatedGas, 15),
+                  ...overrides,
+                },
+              );
+              await this.multiProvider.handleTx(destination, enrollTx);
+            }
+          }
         }
 
         // Transfer ownership after all enrollments are complete, unless the
@@ -746,6 +859,66 @@ export class HyperlaneIsmFactory extends HyperlaneApp<ProxyFactoryFactories> {
     return routingIsm;
   }
 
+  private async setDomainsBatched(
+    routingIsm:
+      | DomainRoutingIsm
+      | IncrementalDomainRoutingIsm
+      | DefaultFallbackRoutingIsm,
+    domains: number[],
+    addresses: Address[],
+    batchSize: number,
+    overrides: ethers.Overrides,
+    destination: ChainName,
+    logger: Logger,
+  ): Promise<void> {
+    for (let i = 0; i < domains.length; i += batchSize) {
+      const chunk = domains.slice(i, i + batchSize).map((domain, j) => ({
+        domain,
+        module: addresses[i + j],
+      }));
+      logger.debug(
+        `setBatch enrolling ${chunk.length} domains on routing ISM ${routingIsm.address} (${destination})`,
+      );
+      const estimatedGas = await routingIsm.estimateGas.setBatch(
+        chunk,
+        overrides,
+      );
+      const tx = await routingIsm.setBatch(chunk, {
+        gasLimit: addBufferToGasLimit(estimatedGas, 15),
+        ...overrides,
+      });
+      await this.multiProvider.handleTx(destination, tx);
+    }
+  }
+
+  private async removeDomainsBatched(
+    routingIsm:
+      | DomainRoutingIsm
+      | IncrementalDomainRoutingIsm
+      | DefaultFallbackRoutingIsm,
+    domains: number[],
+    batchSize: number,
+    overrides: ethers.Overrides,
+    destination: ChainName,
+    logger: Logger,
+  ): Promise<void> {
+    for (let i = 0; i < domains.length; i += batchSize) {
+      const chunk = domains.slice(i, i + batchSize);
+      logger.debug(
+        `removeBatch unenrolling ${chunk.length} domains on routing ISM ${routingIsm.address} (${destination})`,
+      );
+      const estimatedGas = await routingIsm.estimateGas.removeBatch(
+        chunk,
+        overrides,
+      );
+      const tx = await routingIsm.removeBatch(chunk, {
+        gasLimit: addBufferToGasLimit(estimatedGas, 15),
+        ...overrides,
+      });
+      await this.multiProvider.handleTx(destination, tx);
+    }
+  }
+
   protected async deployAggregationIsm(params: {
     destination: ChainName;
     config: AggregationIsmConfig;

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@hyperlane-xyz/sdk': minor
 +---
++
 +Wired `HyperlaneIsmFactory` to use the routing ISM `setBatch` and `removeBatch` functions added in `@hyperlane-xyz/core` 11.4.0. Enrollments and unenrollments are now consolidated into chunked batched transactions sized by the per-chain `domainRoutingInitializationSize`, avoiding one tx per domain on low-capacity chains (citrea, shibarium, tempo, etc.). Version-gated via `PACKAGE_VERSION()` on the target routing ISM, with a per-domain fallback for older deployed ISMs.