feat(sdk): add warpRouteId for token disambiguation in WarpCore (#8335)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: Xaroz

.changeset/warp-route-id-disambiguation.md

@@ -0,0 +1,5 @@
+---
+"@hyperlane-xyz/sdk": minor
+---
+
+Added optional `warpRouteId` field to TokenConfigSchema for disambiguating tokens that share the same addressOrDenom on the same chain (e.g. M0 Portal tokens). When present, WarpCore.FromConfig uses it during connection resolution to ensure tokens connect only within their own warp route.

typescript/sdk/src/token/IToken.ts

@@ -52,6 +52,13 @@ export const TokenConfigSchema = z.object({
     .optional()
     .describe('The CoinGecko id of the token, used for price lookups'),
   scale: ZUint.lt(256).optional().describe('The scaling factor of the token'),
+  warpRouteId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      'Unique warp route identifier, used to disambiguate tokens that share the same addressOrDenom on the same chain (e.g. M0 Portal tokens)',
+    ),
 });
 
 export type TokenArgs = Omit<

typescript/sdk/src/warp/WarpCore.ts

@@ -113,9 +113,13 @@ export class WarpCore {
         const { chainName, addressOrDenom } = parseTokenConnectionId(
           connection.token,
         );
+        // If token1 has a warpRouteId, token2 must share it — disambiguates
+        // tokens at the same address (e.g. M0 Portal: mUSD, wM, USDSC)
         const token2 = tokens.find(
           (t) =>
-            t.chainName === chainName && t.addressOrDenom === addressOrDenom,
+            t.chainName === chainName &&
+            t.addressOrDenom === addressOrDenom &&
+            (!token1.warpRouteId || t.warpRouteId === token1.warpRouteId),
         );
         assert(
           token2,