fix(sdk): cache signers and simulate ISM deploy address (#8292)

Author: paulbalaji

.changeset/multiprovider-ism-factory.md

@@ -0,0 +1,5 @@
+---
+'@hyperlane-xyz/sdk': patch
+---
+
+MultiProvider was updated to cache connected signers for stable instance identity and route setProviders() through setProvider() for consistent signer reconnection. ISM factory now simulates deploy address via eth_call when getAddress() returns incorrect results. Defensive null assertions were added across MultiProvider methods. HyperlaneCore onDispatch errors are now caught and logged separately.

typescript/sdk/src/core/HyperlaneCore.ts

@@ -207,16 +207,31 @@ export class HyperlaneCore extends HyperlaneApp<CoreFactories> {
       mailbox.on<DispatchEvent>(
         mailbox.filters.Dispatch(),
         (_sender, _destination, _recipient, message, event) => {
-          const dispatched = HyperlaneCore.parseDispatchedMessage(message);
-
-          // add human readable chain names
-          dispatched.parsed.originChain = this.getOrigin(dispatched);
-          dispatched.parsed.destinationChain = this.getDestination(dispatched);
+          let dispatched: DispatchedMessage;
+          try {
+            dispatched = HyperlaneCore.parseDispatchedMessage(message);
+
+            // add human readable chain names
+            dispatched.parsed.originChain = this.getOrigin(dispatched);
+            dispatched.parsed.destinationChain =
+              this.getDestination(dispatched);
+          } catch (err: unknown) {
+            this.logger.error(
+              `Failed to parse dispatched message on ${originChain}`,
+              err instanceof Error ? err.message : String(err),
+            );
+            return;
+          }
 
           this.logger.info(
             `Observed message ${dispatched.id} on ${originChain} to ${dispatched.parsed.destinationChain}`,
           );
-          return handler(dispatched, event);
+          return handler(dispatched, event).catch((err: unknown) => {
+            this.logger.error(
+              `Error in dispatch handler on ${originChain}`,
+              err instanceof Error ? err.message : String(err),
+            );
+          });
         },
       );
     });
@@ -466,7 +481,10 @@ export class HyperlaneCore extends HyperlaneApp<CoreFactories> {
         this.multiProvider.tryGetChainName(parsed.origin) ?? undefined;
       const destinationChain =
         this.multiProvider.tryGetChainName(parsed.destination) ?? undefined;
-      return { parsed: { ...parsed, originChain, destinationChain }, ...other };
+      return {
+        parsed: { ...parsed, originChain, destinationChain },
+        ...other,
+      };
     });
   }
 

typescript/sdk/src/ism/HyperlaneIsmFactory.ts

@@ -630,7 +630,7 @@ export class HyperlaneIsmFactory extends HyperlaneApp<ProxyFactoryFactories> {
         receipt = await this.multiProvider.handleTx(destination, tx);
 
         // TODO: Break this out into a generalized function
-        const dispatchLogs = receipt.logs
+        const dispatchLogs = (receipt.logs ?? [])
           .map((log) => {
             try {
               return domainRoutingIsmFactory.interface.parseLog(log);
@@ -714,10 +714,22 @@ export class HyperlaneIsmFactory extends HyperlaneApp<ProxyFactoryFactories> {
   ): Promise<Address> {
     const sorted = [...values].sort();
 
-    const address = await factory['getAddress(address[],uint8)'](
+    const getAddressResult = await factory['getAddress(address[],uint8)'](
       sorted,
       threshold,
     );
+    const address =
+      (await this.previewFactoryDeployAddress(
+        chain,
+        factory,
+        'deploy(address[],uint8)',
+        [sorted, threshold],
+      )) ?? getAddressResult;
+    if (!eqAddress(address, getAddressResult)) {
+      logger.debug(
+        `Factory getAddress mismatch on ${chain}, using deploy simulation address ${address}`,
+      );
+    }
     const code = await this.multiProvider.getProvider(chain).getCode(address);
     if (code === '0x') {
       logger.debug(
@@ -756,10 +768,21 @@ export class HyperlaneIsmFactory extends HyperlaneApp<ProxyFactoryFactories> {
   ): Promise<Address> {
     const sorted = [...values].sort();
 
-    const address = await factory['getAddress((address,uint96)[],uint96)'](
-      sorted,
-      thresholdWeight,
-    );
+    const getAddressResult = await factory[
+      'getAddress((address,uint96)[],uint96)'
+    ](sorted, thresholdWeight);
+    const address =
+      (await this.previewFactoryDeployAddress(
+        chain,
+        factory,
+        'deploy((address,uint96)[],uint96)',
+        [sorted, thresholdWeight],
+      )) ?? getAddressResult;
+    if (!eqAddress(address, getAddressResult)) {
+      logger.debug(
+        `Weighted factory getAddress mismatch on ${chain}, using deploy simulation address ${address}`,
+      );
+    }
     const code = await this.multiProvider.getProvider(chain).getCode(address);
     if (code === '0x') {
       logger.debug(
@@ -790,4 +813,41 @@ export class HyperlaneIsmFactory extends HyperlaneApp<ProxyFactoryFactories> {
     }
     return address;
   }
+
+  private async previewFactoryDeployAddress(
+    chain: ChainName,
+    factory: {
+      address: string;
+      interface: {
+        encodeFunctionData(
+          functionName: string,
+          args?: readonly unknown[],
+        ): string;
+        decodeFunctionResult(functionName: string, data: string): unknown;
+      };
+    },
+    signature: string,
+    args: readonly unknown[],
+  ): Promise<Address | undefined> {
+    try {
+      const data = factory.interface.encodeFunctionData(signature, args);
+      const result = await this.multiProvider.getProvider(chain).call({
+        to: factory.address,
+        data,
+      });
+      const decoded = factory.interface.decodeFunctionResult(signature, result);
+      if (Array.isArray(decoded) && typeof decoded[0] === 'string') {
+        return decoded[0];
+      }
+      if (typeof decoded === 'string') {
+        return decoded;
+      }
+      return undefined;
+    } catch (e: unknown) {
+      this.logger.warn(
+        `Failed to preview factory deploy address on ${chain} (factory=${factory.address}, fn=${signature}): ${e instanceof Error ? e.message : String(e)}`,
+      );
+      return undefined;
+    }
+  }
 }

typescript/sdk/src/providers/MultiProvider.test.ts

@@ -249,4 +249,76 @@ describe('MultiProvider', () => {
       waitForBlockTagStub.restore();
     });
   });
+
+  describe('tryGetSigner', () => {
+    it('should cache the connected signer for subsequent calls', () => {
+      const chainMetadata = {
+        [TestChainName.test1]: test1,
+        [TestChainName.test2]: test2,
+      };
+      const mp = new MultiProvider(chainMetadata);
+
+      let connectCallCount = 0;
+      const mockProvider = {} as any;
+      const mockConnectedSigner = { provider: mockProvider } as any;
+      const mockSigner = {
+        provider: undefined,
+        connect: sinon.stub().callsFake(() => {
+          connectCallCount += 1;
+          return mockConnectedSigner;
+        }),
+      } as any;
+
+      mp.signers[TestChainName.test1] = mockSigner;
+      mp.providers[TestChainName.test1] = mockProvider;
+
+      // First call should connect and cache
+      const result1 = mp.tryGetSigner(TestChainName.test1);
+      expect(result1).to.equal(mockConnectedSigner);
+      expect(connectCallCount).to.equal(1);
+
+      // Second call should return cached signer without calling connect again
+      const result2 = mp.tryGetSigner(TestChainName.test1);
+      expect(result2).to.equal(mockConnectedSigner);
+      expect(connectCallCount).to.equal(1);
+    });
+
+    it('should not cache signer in shared-signer mode so provider swaps take effect', () => {
+      const chainMetadata = {
+        [TestChainName.test1]: test1,
+        [TestChainName.test2]: test2,
+      };
+      const mp = new MultiProvider(chainMetadata);
+
+      const oldProvider = {} as any;
+      const newProvider = {} as any;
+
+      let connectArg: any;
+      const mockSigner = {
+        provider: undefined,
+        connect: sinon.stub().callsFake((p: any) => {
+          connectArg = p;
+          return { provider: p, getAddress: () => '0x1' } as any;
+        }),
+      } as any;
+
+      // Use shared signer mode
+      mp.useSharedSigner = true;
+      mp.signers[TestChainName.test1] = mockSigner;
+      mp.providers[TestChainName.test1] = oldProvider;
+
+      // First call connects to old provider
+      const result1 = mp.tryGetSigner(TestChainName.test1);
+      expect(connectArg).to.equal(oldProvider);
+      expect(result1!.provider).to.equal(oldProvider);
+
+      // Swap provider — in shared mode, setProvider skips reconnection
+      mp.providers[TestChainName.test1] = newProvider;
+
+      // Second call should reconnect to new provider (not return stale cached signer)
+      const result2 = mp.tryGetSigner(TestChainName.test1);
+      expect(connectArg).to.equal(newProvider);
+      expect(result2!.provider).to.equal(newProvider);
+    });
+  });
 });

typescript/sdk/src/providers/MultiProvider.ts

@@ -20,6 +20,7 @@ import {
   Address,
   ProtocolType,
   addBufferToGasLimit,
+  assert,
   pick,
   rootLogger,
   timeout,
@@ -171,8 +172,20 @@ export class MultiProvider<MetaExt = {}> extends ChainMetadataManager<MetaExt> {
     const chainName = this.getChainName(chainNameOrId);
     this.providers[chainName] = provider;
     const signer = this.signers[chainName];
-    if (signer && signer.provider) {
-      this.setSigner(chainName, signer.connect(provider));
+    if (signer && signer.provider && !this.useSharedSigner) {
+      try {
+        this.setSigner(chainName, signer.connect(provider));
+      } catch (e: unknown) {
+        // JsonRpcSigner throws UNSUPPORTED_OPERATION for .connect();
+        // use a type guard instead of `as` cast to safely access .code
+        const code =
+          typeof e === 'object' && e !== null && 'code' in e
+            ? String((e as Record<string, unknown>).code)
+            : undefined;
+        if (code !== 'UNSUPPORTED_OPERATION') {
+          throw e;
+        }
+      }
     }
     return provider;
   }
@@ -183,8 +196,7 @@ export class MultiProvider<MetaExt = {}> extends ChainMetadataManager<MetaExt> {
    */
   setProviders(providers: ChainMap<Provider>): void {
     for (const chain of Object.keys(providers)) {
-      const chainName = this.getChainName(chain);
-      this.providers[chainName] = providers[chain];
+      this.setProvider(chain, providers[chain]);
     }
   }
 
@@ -201,7 +213,15 @@ export class MultiProvider<MetaExt = {}> extends ChainMetadataManager<MetaExt> {
     // Auto-connect the signer for convenience
     const provider = this.tryGetProvider(chainName);
     if (!provider) return signer;
-    return signer.connect(provider);
+    const connected = signer.connect(provider);
+    // Only cache when not using a shared signer. In shared-signer mode,
+    // caching pins the signer to this provider; setProvider() skips
+    // reconnection when useSharedSigner is true, so the cached signer
+    // would go stale after a provider swap.
+    if (!this.useSharedSigner) {
+      this.signers[chainName] = connected;
+    }
+    return connected;
   }
 
   /**
@@ -336,6 +356,7 @@ export class MultiProvider<MetaExt = {}> extends ChainMetadataManager<MetaExt> {
     rangeSize = this.getMaxBlockRange(chainNameOrId),
   ): Promise<{ fromBlock: number; toBlock: number }> {
     const toBlock = await this.getProvider(chainNameOrId).getBlock('latest');
+    assert(toBlock, `Unable to fetch latest block for ${chainNameOrId}`);
     const fromBlock = Math.max(toBlock.number - rangeSize, 0);
     return { fromBlock, toBlock: toBlock.number };
   }
@@ -395,6 +416,7 @@ export class MultiProvider<MetaExt = {}> extends ChainMetadataManager<MetaExt> {
         ...overrides,
       });
       // manually wait for deploy tx to be confirmed
+      assert(contract.deployTransaction, 'Deploy transaction missing');
       await this.handleTx(chainNameOrId, contract.deployTransaction);
     }
 
@@ -489,11 +511,13 @@ export class MultiProvider<MetaExt = {}> extends ChainMetadataManager<MetaExt> {
     this.logger.info(
       `Pending ${txUrl || response.hash} (wait(0) returned pending, waiting for initial inclusion)`,
     );
-    return timeout(
+    const inclusionReceipt = await timeout(
       response.wait(1),
       timeoutMs,
       `Timeout (${timeoutMs}ms) waiting for initial inclusion for tx ${response.hash}`,
     );
+    assert(inclusionReceipt, `Transaction ${response.hash} was not included`);
+    return inclusionReceipt;
   }
 
   /**
@@ -511,6 +535,11 @@ export class MultiProvider<MetaExt = {}> extends ChainMetadataManager<MetaExt> {
   ): Promise<ContractReceipt> {
     const provider = this.getProvider(chainNameOrId);
     const receipt = await response.wait(1); // Wait for initial inclusion
+    assert(receipt, `Transaction ${response.hash} was not included`);
+    assert(
+      typeof receipt.blockNumber === 'number',
+      `Receipt missing block number for tx ${response.hash}`,
+    );
     const txBlock = receipt.blockNumber;
 
     // Check if block tag is supported on first call

typescript/sdk/src/utils/HyperlaneReader.ts

@@ -21,8 +21,8 @@ export class HyperlaneReader {
    * @param level - The log level to set, e.g. 'debug', 'info', 'warn', 'error'.
    */
   protected setSmartProviderLogLevel(level: LevelWithSilentOrString): void {
-    if ('setLogLevel' in this.provider) {
-      (this.provider as HyperlaneSmartProvider).setLogLevel(level);
+    if (this.provider instanceof HyperlaneSmartProvider) {
+      this.provider.setLogLevel(level);
     }
   }
 }