feat: WarpModule with create()

.changeset/smart-dancers-type.md

@@ -0,0 +1,5 @@
+---
+'@hyperlane-xyz/sdk': minor
+---
+
+Add EvmWarpCrudModule with create() and update()

typescript/sdk/src/consts/testChains.ts

@@ -10,6 +10,7 @@ export enum TestChainName {
   test1 = 'test1',
   test2 = 'test2',
   test3 = 'test3',
+  test4 = 'test4',
 }
 
 export const testChains: Array<ChainName> = Object.values(TestChainName);
@@ -65,10 +66,24 @@ export const test3: ChainMetadata = {
   name: 'test3',
 };
 
+export const test4: ChainMetadata = {
+  ...test1,
+  blocks: {
+    confirmations: 1,
+    estimateBlockTime: 3,
+    reorgPeriod: 2,
+  },
+  chainId: 31337,
+  displayName: 'Test 4',
+  domainId: 31337,
+  name: 'test4',
+};
+
 export const testChainMetadata: ChainMap<ChainMetadata> = {
   test1,
   test2,
   test3,
+  test4,
 };
 
 export const testCosmosChain: ChainMetadata = {

typescript/sdk/src/deploy/schemas.ts

@@ -7,3 +7,11 @@ export const OwnerSchema = z.union([z.string(), AccountConfigSchema]);
 export const OwnableConfigSchema = z.object({
   owner: OwnerSchema,
 });
+
+export const ProxyFactoryFactoriesSchema = z.object({
+  staticMerkleRootMultisigIsmFactory: z.string(),
+  staticMessageIdMultisigIsmFactory: z.string(),
+  staticAggregationIsmFactory: z.string(),
+  staticAggregationHookFactory: z.string(),
+  domainRoutingIsmFactory: z.string(),
+});

typescript/sdk/src/hook/types.ts

@@ -19,6 +19,7 @@ export enum OnchainHookType {
 }
 
 export enum HookType {
+  ADDRESS = 'address',
   MERKLE_TREE = 'merkleTreeHook',
   INTERCHAIN_GAS_PAYMASTER = 'interchainGasPaymaster',
   AGGREGATION = 'aggregationHook',

typescript/sdk/src/ism/EvmIsmModule.ts

@@ -1,6 +1,6 @@
 import { Address, ProtocolType, rootLogger } from '@hyperlane-xyz/utils';
 
-import { HyperlaneContracts } from '../contracts/types.js';
+import { HyperlaneAddresses } from '../contracts/types.js';
 import {
   HyperlaneModule,
   HyperlaneModuleArgs,
@@ -11,79 +11,49 @@ import { MultiProvider } from '../providers/MultiProvider.js';
 import { EthersV5Transaction } from '../providers/ProviderType.js';
 import { ChainNameOrId } from '../types.js';
 
-import { EvmIsmCreator } from './EvmIsmCreator.js';
-import { EvmIsmReader } from './EvmIsmReader.js';
+import { DerivedIsmConfigWithAddress, EvmIsmReader } from './EvmIsmReader.js';
 import { IsmConfig } from './types.js';
 
 export class EvmIsmModule extends HyperlaneModule<
   ProtocolType.Ethereum,
   IsmConfig,
-  HyperlaneContracts<ProxyFactoryFactories> & {
+  HyperlaneAddresses<ProxyFactoryFactories> & {
     deployedIsm: Address;
   }
 > {
   protected logger = rootLogger.child({ module: 'EvmIsmModule' });
   protected reader: EvmIsmReader;
-  protected creator: EvmIsmCreator;
 
   protected constructor(
     protected readonly multiProvider: MultiProvider,
     protected readonly deployer: HyperlaneDeployer<any, any>,
     args: HyperlaneModuleArgs<
       IsmConfig,
-      HyperlaneContracts<ProxyFactoryFactories> & {
+      HyperlaneAddresses<ProxyFactoryFactories> & {
         deployedIsm: Address;
       }
     >,
   ) {
     super(args);
     this.reader = new EvmIsmReader(multiProvider, args.chain);
-    this.creator = new EvmIsmCreator(deployer, multiProvider, args.addresses);
   }
 
-  public async read(): Promise<IsmConfig> {
+  public async read(): Promise<DerivedIsmConfigWithAddress> {
     return await this.reader.deriveIsmConfig(this.args.addresses.deployedIsm);
   }
 
-  public async update(config: IsmConfig): Promise<EthersV5Transaction[]> {
+  public async update(_config: IsmConfig): Promise<EthersV5Transaction[]> {
     throw new Error('Method not implemented.');
-
-    const destination = this.multiProvider.getChainName(this.args.chain);
-    await this.creator.update({
-      destination,
-      config,
-      existingIsmAddress: this.args.addresses.deployedIsm,
-    });
-    return [];
   }
 
   // manually write static create function
-  public static async create({
-    chain,
-    config,
-    deployer,
-    factories,
-    multiProvider,
-  }: {
+  public static async create(_params: {
     chain: ChainNameOrId;
     config: IsmConfig;
     deployer: HyperlaneDeployer<any, any>;
-    factories: HyperlaneContracts<ProxyFactoryFactories>;
+    factories: HyperlaneAddresses<ProxyFactoryFactories>;
     multiProvider: MultiProvider;
   }): Promise<EvmIsmModule> {
-    const destination = multiProvider.getChainName(chain);
-    const ismCreator = new EvmIsmCreator(deployer, multiProvider, factories);
-    const deployedIsm = await ismCreator.deploy({
-      config,
-      destination,
-    });
-    return new EvmIsmModule(multiProvider, deployer, {
-      addresses: {
-        ...factories,
-        deployedIsm: deployedIsm.address,
-      },
-      chain,
-      config,
-    });
+    throw new Error('Method not implemented.');
   }
 }

typescript/sdk/src/ism/EvmIsmReader.ts

@@ -79,7 +79,6 @@ export class EvmIsmReader implements IsmReader {
       this.provider,
     );
     const moduleType: ModuleType = await ism.moduleType();
-
     switch (moduleType) {
       case ModuleType.UNUSED:
         throw new Error('UNUSED does not have a corresponding IsmType');

typescript/sdk/src/ism/HyperlaneIsmFactory.hardhat-test.ts

@@ -338,13 +338,13 @@ describe('HyperlaneIsmFactory', async () => {
       });
       const existingIsm = ism.address;
       const domainsBefore = await (ism as DomainRoutingIsm).domains();
-
       // deleting the domain and removing from multiprovider should unenroll the domain
       // NB: we'll deploy new multisigIsms for the domains bc of new factories but the routingIsm address should be the same because of existingIsmAddress
       delete exampleRoutingConfig.domains['test3'];
       multiProvider = multiProvider.intersect([
         TestChainName.test1,
-        'test2',
+        TestChainName.test2,
+        TestChainName.test4,
       ]).result;
       ismFactoryDeployer = new HyperlaneProxyFactoryDeployer(multiProvider);
       ismFactory = new HyperlaneIsmFactory(

typescript/sdk/src/ism/types.ts

@@ -1,5 +1,6 @@
 import {
   IAggregationIsm,
+  IInterchainSecurityModule,
   IMultisigIsm,
   IRoutingIsm,
   OPStackIsm,
@@ -28,6 +29,7 @@ export enum ModuleType {
 // this enum can be adjusted as per deployments necessary
 // meant for the deployer and checker
 export enum IsmType {
+  CUSTOM = 'custom',
   OP_STACK = 'opStackIsm',
   ROUTING = 'domainRoutingIsm',
   FALLBACK_ROUTING = 'defaultFallbackRoutingIsm',
@@ -55,6 +57,7 @@ export function ismTypeToModuleType(ismType: IsmType): ModuleType {
     case IsmType.OP_STACK:
     case IsmType.TEST_ISM:
     case IsmType.PAUSABLE:
+    case IsmType.CUSTOM:
     case IsmType.TRUSTED_RELAYER:
       return ModuleType.NULL;
   }
@@ -100,8 +103,14 @@ export type TrustedRelayerIsmConfig = {
   relayer: Address;
 };
 
+export type CustomIsmConfig = {
+  type: IsmType.CUSTOM;
+  address: Address;
+};
+
 export type IsmConfig =
-  | Address
+  | Address // @todo Remove after https://github.com/hyperlane-xyz/hyperlane-monorepo/issues/3773 is implemented
+  | CustomIsmConfig
   | RoutingIsmConfig
   | MultisigIsmConfig
   | AggregationIsmConfig
@@ -111,6 +120,7 @@ export type IsmConfig =
   | TrustedRelayerIsmConfig;
 
 export type DeployedIsmType = {
+  [IsmType.CUSTOM]: IInterchainSecurityModule;
   [IsmType.ROUTING]: IRoutingIsm;
   [IsmType.FALLBACK_ROUTING]: IRoutingIsm;
   [IsmType.AGGREGATION]: IAggregationIsm;

typescript/sdk/src/providers/ProviderType.ts

@@ -23,7 +23,7 @@ import type {
   TransactionReceipt as VTransactionReceipt,
 } from 'viem';
 
-import { ProtocolType } from '@hyperlane-xyz/utils';
+import { Annotated, ProtocolType } from '@hyperlane-xyz/utils';
 
 export enum ProviderType {
   EthersV5 = 'ethers-v5',
@@ -203,6 +203,23 @@ export interface EthersV5Transaction
   transaction: EV5Transaction;
 }
 
+export function createAnnotatedEthersV5Transaction(params: {
+  annotation: string;
+  chainId: number;
+  to: string;
+  data: string;
+}): Annotated<EthersV5Transaction> {
+  return {
+    annotation: params.annotation,
+    type: ProviderType.EthersV5,
+    transaction: {
+      chainId: params.chainId,
+      to: params.to,
+      data: params.data,
+    },
+  };
+}
+
 // export interface EthersV6Transaction extends TypedTransactionBase<Ev6Transaction> {
 //   type: ProviderType.EthersV6;
 //   contract: Ev6Transaction;

typescript/sdk/src/router/HyperlaneRouterChecker.ts

@@ -45,7 +45,7 @@ export class HyperlaneRouterChecker<
     const router = this.app.router(this.app.getContracts(chain));
 
     const checkMailboxClientProperty = async (
-      property: keyof MailboxClientConfig,
+      property: keyof Omit<MailboxClientConfig, 'ismFactoryAddresses'>,
       actual: string,
       violationType: ClientViolationType,
     ) => {

typescript/sdk/src/router/schemas.ts

@@ -1,6 +1,9 @@
 import { z } from 'zod';
 
-import { OwnableConfigSchema } from '../deploy/schemas.js';
+import {
+  OwnableConfigSchema,
+  ProxyFactoryFactoriesSchema,
+} from '../deploy/schemas.js';
 import { ZHash } from '../index.js';
 import { IsmConfigSchema } from '../ism/schemas.js';
 
@@ -12,6 +15,7 @@ export const MailboxClientConfigSchema = z.object({
   mailbox: ZHash,
   hook: ZHash.optional(),
   interchainSecurityModule: IsmConfigSchema.optional(),
+  ismFactoryAddresses: ProxyFactoryFactoriesSchema.optional(),
 });
 
 export const routerConfigSchema = MailboxClientConfigSchema.merge(

typescript/sdk/src/token/EvmERC20WarpModule.ts

@@ -0,0 +1,103 @@
+import { Address, ProtocolType, rootLogger } from '@hyperlane-xyz/utils';
+
+import { HyperlaneContracts } from '../contracts/types.js';
+import {
+  HyperlaneModule,
+  HyperlaneModuleArgs,
+} from '../core/AbstractHyperlaneModule.js';
+import { MultiProvider } from '../providers/MultiProvider.js';
+import { EthersV5Transaction } from '../providers/ProviderType.js';
+import { RouterConfig } from '../router/types.js';
+import { ChainMap, ChainNameOrId } from '../types.js';
+
+import {
+  DerivedTokenRouterConfig,
+  DerivedTokenType,
+  EvmERC20WarpRouteReader,
+} from './EvmERC20WarpRouteReader.js';
+import { TokenConfig } from './config.js';
+import { HypERC20Factories } from './contracts.js';
+import { HypERC20Deployer } from './deploy.js';
+
+export class EvmERC20WarpModule extends HyperlaneModule<
+  ProtocolType.Ethereum,
+  DerivedTokenRouterConfig,
+  HyperlaneContracts<HypERC20Factories> & {
+    deployedTokenRoute: Address;
+  }
+> {
+  protected logger = rootLogger.child({
+    module: 'EvmERC20WarpModule',
+  });
+  reader: EvmERC20WarpRouteReader;
+
+  constructor(
+    protected readonly multiProvider: MultiProvider,
+    args: HyperlaneModuleArgs<
+      DerivedTokenRouterConfig,
+      HyperlaneContracts<HypERC20Factories> & {
+        deployedTokenRoute: Address;
+      }
+    >,
+  ) {
+    super(args);
+
+    this.reader = new EvmERC20WarpRouteReader(multiProvider, args.chain);
+  }
+
+  /**
+   * Retrieves the token router configuration for the specified address.
+   *
+   * @param address - The address to derive the token router configuration from.
+   * @returns A promise that resolves to the token router configuration.
+   */
+  public async read(): Promise<DerivedTokenRouterConfig> {
+    return this.reader.deriveWarpRouteConfig(
+      this.args.addresses.deployedTokenRoute,
+    );
+  }
+
+  /**
+   * Updates the Warp Route contract with the provided configuration.
+   *
+   * @remark Currently only supports updating ISM or hook
+   *
+   * @param expectedConfig - The configuration for the token router to be updated.
+   * @returns An array of Ethereum transactions that were executed to update the contract, or an error if the update failed.
+   */
+  public async update(
+    expectedConfig: DerivedTokenRouterConfig,
+  ): Promise<EthersV5Transaction[]> {
+    throw Error('Not implemented');
+  }
+
+  /**
+   * Deploys the Warp Route
+   *
+   * @param chain - The chain to deploy the module on.
+   * @param config - The configuration for the token router.
+   * @param multiProvider - The multi-provider instance to use.
+   * @returns A new instance of the EvmERC20WarpHyperlaneModule.
+   */
+  public static async create(params: {
+    chain: ChainNameOrId;
+    config: DerivedTokenRouterConfig;
+    multiProvider: MultiProvider;
+  }): Promise<EvmERC20WarpModule> {
+    const { chain, config, multiProvider } = params;
+    const deployer = new HypERC20Deployer(multiProvider);
+    const deployedContracts = await deployer.deploy({
+      [chain]: config,
+    } as ChainMap<TokenConfig & RouterConfig>);
+
+    return new EvmERC20WarpModule(multiProvider, {
+      addresses: {
+        ...deployedContracts[chain],
+        deployedTokenRoute:
+          deployedContracts[chain][config.type as DerivedTokenType].address,
+      },
+      chain,
+      config,
+    });
+  }
+}