feat(widgets): make chain search menu metadata-first friendly (#8637)

Author: paulbalaji

.changeset/fast-pumpkins-trade.md

@@ -0,0 +1,5 @@
+---
+'@hyperlane-xyz/widgets': patch
+---
+
+Made `ChainSearchMenu` fit metadata-first consumers better by lazy-loading the chain-details drilldown, and hardened `ChainAddMenu` validation against duplicate `chainId` and effective `domainId` conflicts across merged base and override metadata.

.changeset/neat-birds-care.md

@@ -0,0 +1,5 @@
+---
+'@hyperlane-xyz/sdk': patch
+---
+
+Added shared chain ID normalization helpers under the existing `metadata/*` subpath so metadata-first consumers can reuse the same chain ID and effective domain ID validation logic as the SDK resolver.

typescript/sdk/src/metadata/ChainMetadataResolver.ts

@@ -3,6 +3,7 @@ import { assert, isNullish } from '@hyperlane-xyz/utils';
 import type { ChainMap, ChainNameOrId } from '../types.js';
 
 import type { ChainMetadata } from './chainMetadataTypes.js';
+import { tryNormalizeNumericChainId } from './chainIdUtils.js';
 
 export interface ChainMetadataResolver<MetaExt = {}> {
   metadata: ChainMap<ChainMetadata<MetaExt>>;
@@ -90,17 +91,3 @@ export function createChainMetadataResolver<MetaExt = {}>(
     tryGetProtocol: (chain) => tryGetChainMetadata(chain)?.protocol ?? null,
   };
 }
-
-function tryNormalizeNumericChainId(chainId: string | number) {
-  if (typeof chainId === 'number') {
-    return Number.isSafeInteger(chainId) ? chainId : null;
-  }
-
-  if (!/^\d+$/.test(chainId)) return null;
-
-  const numericChainId = Number(chainId);
-  if (!Number.isSafeInteger(numericChainId)) return null;
-  if (String(numericChainId) !== chainId) return null;
-
-  return numericChainId;
-}

typescript/sdk/src/metadata/chainIdUtils.test.ts

@@ -0,0 +1,59 @@
+import { expect } from 'chai';
+
+import {
+  areChainIdsEqual,
+  getEffectiveDomainId,
+  tryNormalizeNumericChainId,
+} from './chainIdUtils.js';
+
+describe(tryNormalizeNumericChainId.name, () => {
+  it('accepts safe integer numbers', () => {
+    expect(tryNormalizeNumericChainId(0)).to.equal(0);
+    expect(tryNormalizeNumericChainId(123)).to.equal(123);
+  });
+
+  it('accepts canonical numeric strings', () => {
+    expect(tryNormalizeNumericChainId('0')).to.equal(0);
+    expect(tryNormalizeNumericChainId('123')).to.equal(123);
+  });
+
+  it('rejects non-canonical or invalid inputs', () => {
+    expect(tryNormalizeNumericChainId('00123')).to.equal(null);
+    expect(tryNormalizeNumericChainId('cosmoshub-4')).to.equal(null);
+    expect(tryNormalizeNumericChainId(1.5)).to.equal(null);
+    expect(tryNormalizeNumericChainId(Number.MAX_SAFE_INTEGER + 1)).to.equal(
+      null,
+    );
+  });
+});
+
+describe(areChainIdsEqual.name, () => {
+  it('matches exact values and canonical numeric aliases', () => {
+    expect(areChainIdsEqual(123, 123)).to.equal(true);
+    expect(areChainIdsEqual('123', 123)).to.equal(true);
+  });
+
+  it('rejects nullish and non-matching values', () => {
+    expect(areChainIdsEqual(undefined, 123)).to.equal(false);
+    expect(areChainIdsEqual(null, '123')).to.equal(false);
+    expect(areChainIdsEqual(5, 10)).to.equal(false);
+    expect(areChainIdsEqual('5', 10)).to.equal(false);
+    expect(areChainIdsEqual('00123', 123)).to.equal(false);
+    expect(areChainIdsEqual('cosmoshub-4', 4)).to.equal(false);
+  });
+});
+
+describe(getEffectiveDomainId.name, () => {
+  it('prefers explicit domain ids', () => {
+    expect(getEffectiveDomainId({ chainId: 1, domainId: 999 })).to.equal(999);
+  });
+
+  it('falls back to normalized chain ids when domain id is absent', () => {
+    expect(getEffectiveDomainId({ chainId: 123 })).to.equal(123);
+    expect(getEffectiveDomainId({ chainId: '123' })).to.equal(123);
+  });
+
+  it('returns null for non-numeric fallback chain ids', () => {
+    expect(getEffectiveDomainId({ chainId: 'cosmoshub-4' })).to.equal(null);
+  });
+});

typescript/sdk/src/metadata/chainIdUtils.ts

@@ -0,0 +1,47 @@
+import { isNullish } from '@hyperlane-xyz/utils';
+
+import type { ChainMetadata } from './chainMetadataTypes.js';
+
+// Decimal-only canonical chain IDs. Rejects hex, prefixed values, and mixed IDs
+// like cosmoshub-4 so those never alias to numeric domain lookups.
+const NUMERIC_CHAIN_ID_REGEX = /^\d+$/;
+
+export function tryNormalizeNumericChainId(
+  chainId: string | number,
+): number | null {
+  if (typeof chainId === 'number') {
+    return Number.isSafeInteger(chainId) ? chainId : null;
+  }
+
+  if (!NUMERIC_CHAIN_ID_REGEX.test(chainId)) return null;
+
+  const numericChainId = Number(chainId);
+  if (!Number.isSafeInteger(numericChainId)) return null;
+  if (String(numericChainId) !== chainId) return null;
+
+  return numericChainId;
+}
+
+export function areChainIdsEqual(
+  left: ChainMetadata['chainId'] | null | undefined,
+  right: ChainMetadata['chainId'] | null | undefined,
+): boolean {
+  if (isNullish(left) || isNullish(right)) return false;
+
+  if (left === right) return true;
+
+  const leftNumeric = tryNormalizeNumericChainId(left);
+  const rightNumeric = tryNormalizeNumericChainId(right);
+  return leftNumeric !== null && leftNumeric === rightNumeric;
+}
+
+export function getEffectiveDomainId(metadata: {
+  chainId: ChainMetadata['chainId'];
+  domainId?: ChainMetadata['domainId'] | null;
+}): number | null {
+  if (!isNullish(metadata.domainId)) {
+    return metadata.domainId;
+  }
+
+  return tryNormalizeNumericChainId(metadata.chainId);
+}

typescript/widgets/src/chains/ChainAddMenu.tsx

@@ -1,11 +1,16 @@
 import { clsx } from 'clsx';
-import React, { useState } from 'react';
+import React, { useMemo, useState } from 'react';
 
 import { DEFAULT_GITHUB_REGISTRY } from '@hyperlane-xyz/registry';
 import {
   ChainMetadata,
   ChainMetadataSchema,
+  mergeChainMetadataMap,
 } from '@hyperlane-xyz/sdk/metadata/chainMetadataTypes';
+import {
+  areChainIdsEqual,
+  getEffectiveDomainId,
+} from '@hyperlane-xyz/sdk/metadata/chainIdUtils';
 import type { ChainMap } from '@hyperlane-xyz/sdk/types';
 import {
   Result,
@@ -82,14 +87,18 @@ function Form({
 }: ChainAddMenuProps) {
   const [textInput, setTextInput] = useState('');
   const [error, setError] = useState<any>(null);
+  const existingChainMetadata = useMemo(
+    () => mergeChainMetadataMap(chainMetadata, overrideChainMetadata),
+    [chainMetadata, overrideChainMetadata],
+  );
 
   const onChangeInput = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
     setTextInput(e.target.value);
     setError(null);
   };
 
   const onClickAdd = () => {
-    const result = tryParseMetadataInput(textInput, chainMetadata);
+    const result = tryParseMetadataInput(textInput, existingChainMetadata);
     if (result.success) {
       onChangeOverrideMetadata({
         ...overrideChainMetadata,
@@ -149,14 +158,27 @@ function tryParseMetadataInput(
   }
 
   const newMetadata = result.data as ChainMetadata;
+  const chainId = newMetadata.chainId;
+  const effectiveDomainId = getEffectiveDomainId(newMetadata);
 
   if (existingChainMetadata[newMetadata.name]) {
     return failure('name is already in use by another chain');
   }
 
+  // The resolver can tolerate ambiguous duplicate chainId aliases, but local
+  // add-chain UX rejects them to avoid persisting ambiguous metadata entries.
+  if (
+    Object.entries(existingChainMetadata).some(([, metadata]) =>
+      areChainIdsEqual(metadata.chainId, chainId),
+    )
+  ) {
+    return failure('chainId is already in use by another chain');
+  }
+
   if (
-    Object.values(existingChainMetadata).some(
-      (metadata) => metadata.domainId === newMetadata.domainId,
+    effectiveDomainId !== null &&
+    Object.entries(existingChainMetadata).some(
+      ([, metadata]) => getEffectiveDomainId(metadata) === effectiveDomainId,
     )
   ) {
     return failure('domainId is already in use by another chain');

typescript/widgets/src/chains/ChainSearchMenu.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback, useMemo, useState } from 'react';
+import React, { Suspense, lazy, useCallback, useMemo, useState } from 'react';
 
 import {
   mergeChainMetadataMap,
@@ -16,9 +16,14 @@ import {
 import { SegmentedControl } from '../components/SegmentedControl.js';
 
 import { ChainAddMenu } from './ChainAddMenu.js';
-import { ChainDetailsMenu } from './ChainDetailsMenu.js';
 import { ChainLogo } from './ChainLogo.js';
 
+const ChainDetailsMenu = lazy(() =>
+  import('./ChainDetailsMenu.js').then((mod) => ({
+    default: mod.ChainDetailsMenu,
+  })),
+);
+
 export enum ChainSortByOption {
   Name = 'name',
   ChainId = 'chain id',
@@ -119,18 +124,26 @@ export function ChainSearchMenu({
     };
 
     return (
-      <ChainDetailsMenu
-        chainMetadata={chainMetadata[drilldownChain]}
-        overrideChainMetadata={overrideChainMetadata?.[drilldownChain]}
-        onChangeOverrideMetadata={(o) =>
-          onChangeOverrideMetadata({
-            ...overrideChainMetadata,
-            [drilldownChain]: o,
-          })
+      <Suspense
+        fallback={
+          <div className="htw-py-8 htw-text-center htw-text-sm htw-text-gray-500">
+            Loading chain details...
+          </div>
         }
-        onClickBack={() => setDrilldownChain(undefined)}
-        onRemoveChain={isLocalOverrideChain ? onRemoveChain : undefined}
-      />
+      >
+        <ChainDetailsMenu
+          chainMetadata={chainMetadata[drilldownChain]}
+          overrideChainMetadata={overrideChainMetadata?.[drilldownChain]}
+          onChangeOverrideMetadata={(o) =>
+            onChangeOverrideMetadata({
+              ...overrideChainMetadata,
+              [drilldownChain]: o,
+            })
+          }
+          onClickBack={() => setDrilldownChain(undefined)}
+          onRemoveChain={isLocalOverrideChain ? onRemoveChain : undefined}
+        />
+      </Suspense>
     );
   }