feat(provider-sdk): add crossCollateral warp token type (#8380)

Author: xeno097

.changeset/cross-collateral-provider-types.md

@@ -0,0 +1,9 @@
+---
+"@hyperlane-xyz/provider-sdk": minor
+"@hyperlane-xyz/sealevel-sdk": patch
+"@hyperlane-xyz/radix-sdk": patch
+"@hyperlane-xyz/cosmos-sdk": patch
+"@hyperlane-xyz/aleo-sdk": patch
+---
+
+Added `crossCollateral` warp token type to the provider-sdk type system. All protocol SDK artifact managers were updated to handle the new type in their exhaustive switches.

typescript/aleo-sdk/src/warp/warp-artifact-manager.ts

@@ -75,6 +75,9 @@ export class AleoWarpArtifactManager implements IRawWarpArtifactManager {
           this.aleoClient,
           this.onChainArtifactManagers,
         ),
+      crossCollateral: () => {
+        throw new Error('Cross-collateral tokens are not supported on Aleo');
+      },
     };
 
     return readers[type]();
@@ -108,6 +111,9 @@ export class AleoWarpArtifactManager implements IRawWarpArtifactManager {
           signer,
           this.onChainArtifactManagers,
         ),
+      crossCollateral: () => {
+        throw new Error('Cross-collateral tokens are not supported on Aleo');
+      },
     };
 
     return writers[type]();

typescript/cosmos-sdk/src/warp/warp-artifact-manager.ts

@@ -98,6 +98,9 @@ export class CosmosWarpArtifactManager implements IRawWarpArtifactManager {
       native: () => {
         throw new Error('Native tokens are not supported on Cosmos');
       },
+      crossCollateral: () => {
+        throw new Error('Cross-collateral tokens are not supported on Cosmos');
+      },
     };
 
     return readers[type]();
@@ -143,6 +146,9 @@ export class CosmosWarpArtifactManager implements IRawWarpArtifactManager {
       native: () => {
         throw new Error('Native tokens are not supported on Cosmos');
       },
+      crossCollateral: () => {
+        throw new Error('Cross-collateral tokens are not supported on Cosmos');
+      },
     };
 
     return writers[type]();

typescript/provider-sdk/src/warp.ts

@@ -38,6 +38,7 @@ export const TokenType = {
   synthetic: 'synthetic',
   collateral: 'collateral',
   native: 'native',
+  crossCollateral: 'crossCollateral',
 } as const;
 
 export type TokenType = (typeof TokenType)[keyof typeof TokenType];
@@ -72,10 +73,17 @@ export interface NativeWarpConfig extends BaseWarpConfig {
   type: 'native';
 }
 
+export interface CrossCollateralWarpConfig extends BaseWarpConfig {
+  type: 'crossCollateral';
+  token: string;
+  crossCollateralRouters?: Record<string, string[]>;
+}
+
 export type WarpConfig =
   | CollateralWarpConfig
   | SyntheticWarpConfig
-  | NativeWarpConfig;
+  | NativeWarpConfig
+  | CrossCollateralWarpConfig;
 
 export interface BaseDerivedWarpConfig {
   owner: string;
@@ -107,10 +115,20 @@ export interface DerivedNativeWarpConfig extends BaseDerivedWarpConfig {
   type: 'native';
 }
 
+export interface DerivedCrossCollateralWarpConfig extends BaseDerivedWarpConfig {
+  type: 'crossCollateral';
+  token: string;
+  name?: string;
+  symbol?: string;
+  decimals?: number;
+  crossCollateralRouters: Record<string, string[]>;
+}
+
 export type DerivedWarpConfig =
   | DerivedCollateralWarpConfig
   | DerivedSyntheticWarpConfig
-  | DerivedNativeWarpConfig;
+  | DerivedNativeWarpConfig
+  | DerivedCrossCollateralWarpConfig;
 
 export type WarpRouteAddresses = {
   deployedTokenRoute: string;
@@ -157,10 +175,17 @@ export interface NativeWarpArtifactConfig extends BaseWarpArtifactConfig {
   type: typeof TokenType.native;
 }
 
+export interface CrossCollateralWarpArtifactConfig extends BaseWarpArtifactConfig {
+  type: typeof TokenType.crossCollateral;
+  token: string;
+  crossCollateralRouters: Record<number, Set<string>>;
+}
+
 export interface WarpArtifactConfigs {
   collateral: CollateralWarpArtifactConfig;
   synthetic: SyntheticWarpArtifactConfig;
   native: NativeWarpArtifactConfig;
+  crossCollateral: CrossCollateralWarpArtifactConfig;
 }
 
 export type WarpType = keyof WarpArtifactConfigs;
@@ -198,10 +223,14 @@ export type RawSyntheticWarpArtifactConfig =
 export type RawNativeWarpArtifactConfig =
   ConfigOnChain<NativeWarpArtifactConfig>;
 
+export type RawCrossCollateralWarpArtifactConfig =
+  ConfigOnChain<CrossCollateralWarpArtifactConfig>;
+
 export interface RawWarpArtifactConfigs {
   collateral: RawCollateralWarpArtifactConfig;
   synthetic: RawSyntheticWarpArtifactConfig;
   native: RawNativeWarpArtifactConfig;
+  crossCollateral: RawCrossCollateralWarpArtifactConfig;
 }
 
 /**
@@ -382,6 +411,21 @@ export function warpConfigToArtifact(
         },
       };
 
+    case 'crossCollateral':
+      return {
+        artifactState: ArtifactState.NEW,
+        config: {
+          ...baseArtifactConfig,
+          type: 'crossCollateral',
+          token: config.token,
+          crossCollateralRouters: convertCrossCollateralRoutersToArtifact(
+            config.crossCollateralRouters,
+            chainLookup,
+            logger,
+          ),
+        },
+      };
+
     default: {
       const invalidConfig: never = config;
       throw new Error(
@@ -496,6 +540,16 @@ export function warpArtifactToDerivedConfig(
         type: TokenType.native,
       };
 
+    case 'crossCollateral':
+      return {
+        ...baseDerivedConfig,
+        type: TokenType.crossCollateral,
+        token: config.token,
+        crossCollateralRouters: convertCrossCollateralRoutersToDerived(
+          config.crossCollateralRouters,
+          chainLookup,
+        ),
+      };
     default: {
       const invalidConfig: never = config;
       throw new Error(
@@ -505,6 +559,46 @@ export function warpArtifactToDerivedConfig(
   }
 }
 
+// Cross-Collateral Router Utilities
+
+function convertCrossCollateralRoutersToArtifact(
+  crossCollateralRouters: Record<string, string[]> | undefined,
+  chainLookup: ChainLookup,
+  logger?: Logger,
+): Record<number, Set<string>> {
+  const result: Record<number, Set<string>> = {};
+  if (!crossCollateralRouters) return result;
+
+  for (const [chainName, routers] of Object.entries(crossCollateralRouters)) {
+    const domainId = chainLookup.getDomainId(chainName);
+    if (isNullish(domainId)) {
+      logger?.warn(
+        `Skipping cross-collateral routers for unknown chain: ${chainName}. ` +
+          `Chain not found in chain lookup.`,
+      );
+      continue;
+    }
+    result[domainId] = new Set(routers);
+  }
+  return result;
+}
+
+function convertCrossCollateralRoutersToDerived(
+  crossCollateralRouters: Record<number, Set<string>>,
+  chainLookup: ChainLookup,
+): Record<string, string[]> {
+  const result: Record<string, string[]> = {};
+
+  for (const [domainIdStr, routers] of Object.entries(crossCollateralRouters)) {
+    const domainId = parseInt(domainIdStr);
+    const chainName = chainLookup.getChainName(domainId);
+    if (!chainName) continue;
+    result[chainName] = Array.from(routers);
+  }
+
+  return result;
+}
+
 // Warp Router Update Utilities
 
 export interface WarpRouterDiff {

typescript/radix-sdk/src/warp/warp-artifact-manager.ts

@@ -63,6 +63,9 @@ export class RadixWarpArtifactManager implements IRawWarpArtifactManager {
       native: () => {
         throw new Error('Native tokens are not supported on Radix');
       },
+      crossCollateral: () => {
+        throw new Error('Cross-collateral tokens are not supported on Radix');
+      },
     };
 
     return readers[type]();
@@ -87,6 +90,9 @@ export class RadixWarpArtifactManager implements IRawWarpArtifactManager {
       native: () => {
         throw new Error('Native tokens are not supported on Radix');
       },
+      crossCollateral: () => {
+        throw new Error('Cross-collateral tokens are not supported on Radix');
+      },
     };
 
     return writers[type]();

typescript/svm-sdk/src/warp/warp-artifact-manager.ts

@@ -53,6 +53,9 @@ export class SvmWarpArtifactManager implements IRawWarpArtifactManager {
       native: () => new SvmNativeTokenReader(this.rpc),
       synthetic: () => new SvmSyntheticTokenReader(this.rpc),
       collateral: () => new SvmCollateralTokenReader(this.rpc),
+      crossCollateral: () => {
+        throw new Error('Cross-collateral tokens are not yet supported on SVM');
+      },
     };
 
     return readers[type]();
@@ -99,6 +102,9 @@ export class SvmWarpArtifactManager implements IRawWarpArtifactManager {
           this.rpc,
           signer,
         ),
+      crossCollateral: () => {
+        throw new Error('Cross-collateral tokens are not yet supported on SVM');
+      },
     };
 
     return writers[type]();