feat: WarpModule with create()

.changeset/five-baboons-smoke.md

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

typescript/cli/src/config/ism.ts

@@ -73,6 +73,7 @@ const ISM_TYPE_DESCRIPTIONS: Record<IsmType, string> = {
     'ISM where you can deliver messages without any validation (WARNING: only for testing, do not use in production)',
   [IsmType.OP_STACK]: '',
   [IsmType.PAUSABLE]: '',
+  [IsmType.CUSTOM]: '',
 };
 
 export async function createIsmConfig(

typescript/sdk/src/hook/types.ts

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

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

@@ -353,13 +353,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

@@ -2,6 +2,7 @@ import { z } from 'zod';
 
 import {
   IAggregationIsm,
+  IInterchainSecurityModule,
   IMultisigIsm,
   IRoutingIsm,
   OPStackIsm,
@@ -39,6 +40,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',
@@ -73,6 +75,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;
   }
@@ -111,6 +114,7 @@ export type AggregationIsmConfig = {
 export type IsmConfig = z.infer<typeof IsmConfigSchema>;
 
 export type DeployedIsmType = {
+  [IsmType.CUSTOM]: IInterchainSecurityModule;
   [IsmType.ROUTING]: IRoutingIsm;
   [IsmType.FALLBACK_ROUTING]: IRoutingIsm;
   [IsmType.AGGREGATION]: IAggregationIsm;

typescript/sdk/src/token/EvmERC20WarpModule.hardhat-test.ts

@@ -0,0 +1,203 @@
+import { SignerWithAddress } from '@nomiclabs/hardhat-ethers/signers.js';
+import { expect } from 'chai';
+import { constants } from 'ethers';
+import hre from 'hardhat';
+
+import {
+  ERC20Test,
+  ERC20Test__factory,
+  ERC4626Test__factory,
+  GasRouter,
+  HypERC20CollateralVaultDeposit__factory,
+  HypERC20__factory,
+  HypNative__factory,
+  Mailbox,
+  Mailbox__factory,
+} from '@hyperlane-xyz/core';
+import {
+  HyperlaneContractsMap,
+  RouterConfig,
+  TestChainName,
+} from '@hyperlane-xyz/sdk';
+
+import { TestCoreApp } from '../core/TestCoreApp.js';
+import { TestCoreDeployer } from '../core/TestCoreDeployer.js';
+import { HyperlaneProxyFactoryDeployer } from '../deploy/HyperlaneProxyFactoryDeployer.js';
+import { ProxyFactoryFactories } from '../deploy/contracts.js';
+import { HyperlaneIsmFactory } from '../ism/HyperlaneIsmFactory.js';
+import { MultiProvider } from '../providers/MultiProvider.js';
+import { ChainMap } from '../types.js';
+
+import { EvmERC20WarpModule } from './EvmERC20WarpModule.js';
+import { TokenType } from './config.js';
+import { TokenRouterConfig } from './schemas.js';
+
+describe('EvmERC20WarpHyperlaneModule', async () => {
+  const TOKEN_NAME = 'fake';
+  const TOKEN_SUPPLY = '100000000000000000000';
+  const TOKEN_DECIMALS = 18;
+  const chain = TestChainName.test4;
+  let mailbox: Mailbox;
+  let hookAddress: string;
+  let ismFactory: HyperlaneIsmFactory;
+  let factories: HyperlaneContractsMap<ProxyFactoryFactories>;
+  let erc20Factory: ERC20Test__factory;
+  let token: ERC20Test;
+  let signer: SignerWithAddress;
+  let multiProvider: MultiProvider;
+  let coreApp: TestCoreApp;
+  let routerConfigMap: ChainMap<RouterConfig>;
+  let baseConfig: RouterConfig;
+
+  async function validateCoreValues(deployedToken: GasRouter) {
+    expect(await deployedToken.mailbox()).to.equal(mailbox.address);
+    expect(await deployedToken.hook()).to.equal(hookAddress);
+    expect(await deployedToken.interchainSecurityModule()).to.equal(
+      constants.AddressZero,
+    );
+    expect(await deployedToken.owner()).to.equal(signer.address);
+  }
+  before(async () => {
+    [signer] = await hre.ethers.getSigners();
+    multiProvider = MultiProvider.createTestMultiProvider({ signer });
+    const ismFactoryDeployer = new HyperlaneProxyFactoryDeployer(multiProvider);
+    factories = await ismFactoryDeployer.deploy(
+      multiProvider.mapKnownChains(() => ({})),
+    );
+    ismFactory = new HyperlaneIsmFactory(factories, multiProvider);
+    coreApp = await new TestCoreDeployer(multiProvider, ismFactory).deployApp();
+    routerConfigMap = coreApp.getRouterConfig(signer.address);
+
+    erc20Factory = new ERC20Test__factory(signer);
+    token = await erc20Factory.deploy(
+      TOKEN_NAME,
+      TOKEN_NAME,
+      TOKEN_SUPPLY,
+      TOKEN_DECIMALS,
+    );
+
+    baseConfig = routerConfigMap[chain];
+
+    mailbox = Mailbox__factory.connect(baseConfig.mailbox, signer);
+    hookAddress = await mailbox.defaultHook();
+  });
+
+  it('should create with a a collateral config', async () => {
+    const config = {
+      ...baseConfig,
+      type: TokenType.collateral,
+      token: token.address,
+      hook: hookAddress,
+    };
+
+    // Deploy using WarpModule
+    const evmERC20WarpModule = await EvmERC20WarpModule.create({
+      chain,
+      config,
+      multiProvider,
+    });
+
+    // Let's derive it's onchain token type
+    const { collateral } = evmERC20WarpModule.serialize();
+    const tokenType: TokenType =
+      await evmERC20WarpModule.reader.deriveTokenType(collateral);
+    expect(tokenType).to.equal(TokenType.collateral);
+  });
+
+  it('should create with a collateral vault config', async () => {
+    const vaultFactory = new ERC4626Test__factory(signer);
+    const vault = await vaultFactory.deploy(
+      token.address,
+      TOKEN_NAME,
+      TOKEN_NAME,
+    );
+    const config = {
+      type: TokenType.collateralVault,
+      token: vault.address,
+      hook: hookAddress,
+      ...baseConfig,
+    };
+
+    // Deploy using WarpModule
+    const evmERC20WarpModule = await EvmERC20WarpModule.create({
+      chain,
+      config,
+      multiProvider,
+    });
+
+    // Let's derive it's onchain token type
+    const { collateralVault: collateralVaultAddr } =
+      evmERC20WarpModule.serialize();
+    const tokenType: TokenType =
+      await evmERC20WarpModule.reader.deriveTokenType(collateralVaultAddr);
+    expect(tokenType).to.equal(TokenType.collateralVault);
+
+    // Validate onchain token values
+    const collateralVault = HypERC20CollateralVaultDeposit__factory.connect(
+      collateralVaultAddr,
+      signer,
+    );
+    await validateCoreValues(collateralVault);
+    expect(await collateralVault.vault()).to.equal(vault.address);
+    expect(await collateralVault.wrappedToken()).to.equal(token.address);
+  });
+
+  it('should create with a a synthetic config', async () => {
+    const config = {
+      type: TokenType.synthetic,
+      token: token.address,
+      hook: hookAddress,
+      name: TOKEN_NAME,
+      symbol: TOKEN_NAME,
+      decimals: TOKEN_DECIMALS,
+      totalSupply: TOKEN_SUPPLY,
+      ...baseConfig,
+    };
+
+    // Deploy using WarpModule
+    const evmERC20WarpModule = await EvmERC20WarpModule.create({
+      chain,
+      config,
+      multiProvider,
+    });
+
+    // Let's derive it's onchain token type
+    const { synthetic: syntheticAddr } = evmERC20WarpModule.serialize();
+    const tokenType: TokenType =
+      await evmERC20WarpModule.reader.deriveTokenType(syntheticAddr);
+    expect(tokenType).to.equal(TokenType.synthetic);
+
+    // Validate onchain token values
+    const synthetic = HypERC20__factory.connect(syntheticAddr, signer);
+    await validateCoreValues(synthetic);
+    expect(await synthetic.name()).to.equal(TOKEN_NAME);
+    expect(await synthetic.symbol()).to.equal(TOKEN_NAME);
+    expect(await synthetic.decimals()).to.equal(TOKEN_DECIMALS);
+    expect(await synthetic.totalSupply()).to.equal(TOKEN_SUPPLY);
+  });
+
+  it('should create with a a native config', async () => {
+    const config = {
+      type: TokenType.native,
+      hook: hookAddress,
+      ...baseConfig,
+    } as TokenRouterConfig;
+
+    // Deploy using WarpModule
+    const evmERC20WarpModule = await EvmERC20WarpModule.create({
+      chain,
+      config,
+      multiProvider,
+    });
+
+    // Let's derive it's onchain token type
+    const { native: nativeAddr } = evmERC20WarpModule.serialize();
+    const tokenType: TokenType =
+      await evmERC20WarpModule.reader.deriveTokenType(nativeAddr);
+    expect(tokenType).to.equal(TokenType.native);
+
+    // Validate onchain token values
+    const native = HypNative__factory.connect(nativeAddr, signer);
+    await validateCoreValues(native);
+  });
+});

typescript/sdk/src/token/EvmERC20WarpModule.ts

@@ -0,0 +1,97 @@
+import { Address, ProtocolType, rootLogger } from '@hyperlane-xyz/utils';
+
+import { serializeContracts } from '../contracts/contracts.js';
+import { HyperlaneAddresses } from '../contracts/types.js';
+import {
+  HyperlaneModule,
+  HyperlaneModuleParams,
+} from '../core/AbstractHyperlaneModule.js';
+import { MultiProvider } from '../providers/MultiProvider.js';
+import { AnnotatedEV5Transaction } from '../providers/ProviderType.js';
+import { ChainNameOrId } from '../types.js';
+
+import { EvmERC20WarpRouteReader } from './EvmERC20WarpRouteReader.js';
+import { HypERC20Factories } from './contracts.js';
+import { HypERC20Deployer } from './deploy.js';
+import { TokenRouterConfig } from './schemas.js';
+
+export class EvmERC20WarpModule extends HyperlaneModule<
+  ProtocolType.Ethereum,
+  TokenRouterConfig,
+  HyperlaneAddresses<HypERC20Factories> & {
+    deployedTokenRoute: Address;
+  }
+> {
+  protected logger = rootLogger.child({
+    module: 'EvmERC20WarpModule',
+  });
+  reader: EvmERC20WarpRouteReader;
+
+  constructor(
+    protected readonly multiProvider: MultiProvider,
+    args: HyperlaneModuleParams<
+      TokenRouterConfig,
+      HyperlaneAddresses<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<TokenRouterConfig> {
+    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: TokenRouterConfig,
+  ): Promise<AnnotatedEV5Transaction[]> {
+    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: TokenRouterConfig;
+    multiProvider: MultiProvider;
+  }): Promise<EvmERC20WarpModule> {
+    const { chain, config, multiProvider } = params;
+    const chainName = multiProvider.getChainName(chain);
+    const deployer = new HypERC20Deployer(multiProvider);
+    const deployedContracts = await deployer.deployContracts(chainName, config);
+
+    return new EvmERC20WarpModule(multiProvider, {
+      addresses: {
+        ...serializeContracts(deployedContracts),
+        deployedTokenRoute: deployedContracts[config.type].address,
+      },
+      chain,
+      config,
+    });
+  }
+}