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

Adds a PACKAGE_VERSION gate on the target routing ISM. When it reports
>= 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)

Author: paulbalaji

.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.

typescript/sdk/src/ism/HyperlaneIsmFactory.ts

@@ -1,3 +1,4 @@
+import { compareVersions } from 'compare-versions';
 import { ethers } from 'ethers';
 import { Logger } from 'pino';
 
@@ -31,6 +32,7 @@ import {
   TrustedRelayerIsm__factory,
   ZKSyncArtifact,
 } from '@hyperlane-xyz/core';
+
 import {
   Address,
   Domain,
@@ -84,6 +86,32 @@ const ismFactories = {
   [IsmType.CCIP]: new CCIPIsm__factory(),
 };
 
+type RoutingIsmContract =
+  | DomainRoutingIsm
+  | IncrementalDomainRoutingIsm
+  | DefaultFallbackRoutingIsm;
+
+// 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 = '11.4.0';
+
+const routingIsmSupportsBatch = async (
+  address: Address,
+  provider: ethers.providers.Provider,
+): Promise<boolean> => {
+  try {
+    const version = await DomainRoutingIsm__factory.connect(
+      address,
+      provider,
+    ).PACKAGE_VERSION();
+    return compareVersions(version, ROUTING_ISM_BATCH_MIN_VERSION) >= 0;
+  } catch {
+    return false;
+  }
+};
+
 const domainRoutingInitializationSize = (destination: ChainName) => {
   if (destination === 'tempo') {
     return 30;
@@ -541,7 +569,10 @@ export class HyperlaneIsmFactory extends HyperlaneApp<ProxyFactoryFactories> {
         existingIsmAddress,
         this.multiProvider.getSigner(destination),
       );
+      const batchSize = domainRoutingInitializationSize(destination);
+
       // 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,21 +585,25 @@ export class HyperlaneIsmFactory extends HyperlaneApp<ProxyFactoryFactories> {
           mailbox,
         });
         isms[originDomain] = ism.address;
-        const tx = await routingIsm.set(
-          originDomain,
-          isms[originDomain],
-          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}...`,
-        );
-        const tx = await routingIsm.remove(originDomain, overrides);
-        await this.multiProvider.handleTx(destination, tx);
+        enrollAddresses.push(ism.address);
       }
+      await this.enrollDomains({
+        routingIsm,
+        domains: delta.domainsToEnroll,
+        addresses: enrollAddresses,
+        batchSize,
+        overrides,
+        destination,
+        logger,
+      });
+      await this.unenrollDomains({
+        routingIsm,
+        domains: delta.domainsToUnenroll,
+        batchSize,
+        overrides,
+        destination,
+        logger,
+      });
       // transfer ownership if needed
       if (delta.owner) {
         logger.debug(`Transferring ownership of routing ISM...`);
@@ -603,16 +638,31 @@ 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,
           ),
         );
+        await this.enrollDomains({
+          routingIsm,
+          domains: safeConfigDomains.slice(initialBatchSize),
+          addresses: submoduleAddresses.slice(initialBatchSize),
+          batchSize,
+          overrides,
+          destination,
+          logger,
+        });
       } else {
         // deploying new domain routing ISM
         const owner = config.owner;
@@ -704,28 +754,15 @@ 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,
-            },
-          );
-          await this.multiProvider.handleTx(destination, enrollTx);
-        }
+        await this.enrollDomains({
+          routingIsm,
+          domains: safeConfigDomains.slice(initialBatchSize),
+          addresses: submoduleAddresses.slice(initialBatchSize),
+          batchSize,
+          overrides,
+          destination,
+          logger,
+        });
 
         // Transfer ownership after all enrollments are complete, unless the
         // signer is already the target owner (common for self-owned deploys).
@@ -746,6 +783,173 @@ export class HyperlaneIsmFactory extends HyperlaneApp<ProxyFactoryFactories> {
     return routingIsm;
   }
 
+  /**
+   * Enroll a set of (domain, ISM address) pairs on a routing ISM. Uses
+   * `setBatch` chunked by `batchSize` when the deployed ISM is at a
+   * `@hyperlane-xyz/core` version that supports it; otherwise falls back
+   * to a per-domain `set` loop.
+   */
+  private async enrollDomains(params: {
+    routingIsm: RoutingIsmContract;
+    domains: number[];
+    addresses: Address[];
+    batchSize: number;
+    overrides: ethers.Overrides;
+    destination: ChainName;
+    logger: Logger;
+  }): Promise<void> {
+    if (params.domains.length === 0) return;
+    const provider = this.multiProvider.getProvider(params.destination);
+    const supportsBatch = await routingIsmSupportsBatch(
+      params.routingIsm.address,
+      provider,
+    );
+    return supportsBatch
+      ? this.setDomainsBatched(params)
+      : this.setDomainsPerDomain(params);
+  }
+
+  /**
+   * Unenroll a set of domains from a routing ISM. Uses `removeBatch`
+   * chunked by `batchSize` when supported; otherwise falls back to a
+   * per-domain `remove` loop.
+   */
+  private async unenrollDomains(params: {
+    routingIsm: RoutingIsmContract;
+    domains: number[];
+    batchSize: number;
+    overrides: ethers.Overrides;
+    destination: ChainName;
+    logger: Logger;
+  }): Promise<void> {
+    if (params.domains.length === 0) return;
+    const provider = this.multiProvider.getProvider(params.destination);
+    const supportsBatch = await routingIsmSupportsBatch(
+      params.routingIsm.address,
+      provider,
+    );
+    return supportsBatch
+      ? this.removeDomainsBatched(params)
+      : this.removeDomainsPerDomain(params);
+  }
+
+  private async setDomainsBatched(params: {
+    routingIsm: RoutingIsmContract;
+    domains: number[];
+    addresses: Address[];
+    batchSize: number;
+    overrides: ethers.Overrides;
+    destination: ChainName;
+    logger: Logger;
+  }): Promise<void> {
+    const {
+      routingIsm,
+      domains,
+      addresses,
+      batchSize,
+      overrides,
+      destination,
+      logger,
+    } = params;
+    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 setDomainsPerDomain(params: {
+    routingIsm: RoutingIsmContract;
+    domains: number[];
+    addresses: Address[];
+    overrides: ethers.Overrides;
+    destination: ChainName;
+    logger: Logger;
+  }): Promise<void> {
+    const { routingIsm, domains, addresses, overrides, destination, logger } =
+      params;
+    for (let i = 0; i < domains.length; i++) {
+      const chainName = this.multiProvider.getChainName(domains[i]);
+      logger.debug(
+        `Enrolling ${chainName} (${domains[i]}) ISM at ${addresses[i]} on routing ISM ${routingIsm.address}`,
+      );
+      const estimatedGas = await routingIsm.estimateGas.set(
+        domains[i],
+        addresses[i],
+        overrides,
+      );
+      const tx = await routingIsm.set(domains[i], addresses[i], {
+        gasLimit: addBufferToGasLimit(estimatedGas, 15),
+        ...overrides,
+      });
+      await this.multiProvider.handleTx(destination, tx);
+    }
+  }
+
+  private async removeDomainsBatched(params: {
+    routingIsm: RoutingIsmContract;
+    domains: number[];
+    batchSize: number;
+    overrides: ethers.Overrides;
+    destination: ChainName;
+    logger: Logger;
+  }): Promise<void> {
+    const { routingIsm, domains, batchSize, overrides, destination, logger } =
+      params;
+    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);
+    }
+  }
+
+  private async removeDomainsPerDomain(params: {
+    routingIsm: RoutingIsmContract;
+    domains: number[];
+    overrides: ethers.Overrides;
+    destination: ChainName;
+    logger: Logger;
+  }): Promise<void> {
+    const { routingIsm, domains, overrides, destination, logger } = params;
+    for (const domain of domains) {
+      logger.debug(
+        `Unenrolling domain ${domain} from routing ISM ${routingIsm.address}`,
+      );
+      const estimatedGas = await routingIsm.estimateGas.remove(
+        domain,
+        overrides,
+      );
+      const tx = await routingIsm.remove(domain, {
+        gasLimit: addBufferToGasLimit(estimatedGas, 15),
+        ...overrides,
+      });
+      await this.multiProvider.handleTx(destination, tx);
+    }
+  }
+
   protected async deployAggregationIsm(params: {
     destination: ChainName;
     config: AggregationIsmConfig;