feat: add support for any collateral token to fundkey script (#7253)

Author: xeno097

.changeset/four-paws-whisper.md

@@ -0,0 +1,5 @@
+---
+"@hyperlane-xyz/sdk": minor
+---
+
+Implemented the getMetadata method on native token adapters and fixed the populateTransferTx method for SVM token adapters when the receiver does not have a created associated token account

typescript/infra/scripts/funding/fund-wallet-from-deployer-key.ts

@@ -1,30 +1,32 @@
-import { ethers } from 'ethers';
-import { formatUnits, parseUnits } from 'ethers/lib/utils.js';
+import { formatUnits } from 'ethers/lib/utils.js';
 import { format } from 'util';
 
 import {
+  ChainMap,
   ChainName,
   CoinGeckoTokenPriceGetter,
+  ITokenAdapter,
   MultiProtocolSignerSignerAccountInfo,
+  PROTOCOL_TO_DEFAULT_PROVIDER_TYPE,
   ProtocolTypedTransaction,
-  TOKEN_STANDARD_TO_PROVIDER_TYPE,
   Token,
   TransferParams,
+  getCollateralTokenAdapter,
   getSignerForChain,
 } from '@hyperlane-xyz/sdk';
 import {
   Address,
   ProtocolType,
   assert,
   rootLogger,
-  strip0x,
   toWei,
 } from '@hyperlane-xyz/utils';
 
 import { Contexts } from '../../config/contexts.js';
 import { getDeployerKey } from '../../src/agents/key-utils.js';
 import { getCoinGeckoApiKey } from '../../src/coingecko/utils.js';
 import { EnvironmentConfig } from '../../src/config/environment.js';
+import { tokens as knownInfraTokens } from '../../src/config/warp.js';
 import { assertChain } from '../../src/utils/utils.js';
 import { getAgentConfig, getArgs } from '../agent-utils.js';
 import { getEnvironmentConfig } from '../core-utils.js';
@@ -43,6 +45,26 @@ const logger = rootLogger.child({
  */
 const MAX_FUNDING_AMOUNT_IN_USD = 1000;
 
+const enum TokenFundingType {
+  native = 'native',
+  non_native = 'non_native',
+}
+
+type TokenToFundInfo =
+  | {
+      type: TokenFundingType.native;
+      amount: number;
+      recipientAddress: Address;
+      tokenDecimals?: number;
+    }
+  | {
+      type: TokenFundingType.non_native;
+      tokenAddress: Address;
+      amount: number;
+      recipientAddress: Address;
+      tokenDecimals?: number;
+    };
+
 async function main() {
   const argv = await getArgs()
     .string('recipient')
@@ -64,30 +86,112 @@ async function main() {
     .demandOption('chain')
     .coerce('chain', assertChain)
 
+    .string('symbol')
+    .alias('s', 'symbol')
+    .describe(
+      'symbol',
+      'Token symbol for the token to send in this transfer. If the token is not known provide the token address with the --token flag instead',
+    )
+    .conflicts('symbol', 'token')
+
+    .string('token')
+    .alias('t', 'token')
+    .describe(
+      'token',
+      'Optional token address for the token that should be funded. The native token will be used if no address is provided',
+    )
+    .conflicts('token', 'symbol')
+
+    .string('decimals')
+    .alias('d', 'decimals')
+    .describe(
+      'decimals',
+      'Optional token decimals used to format the amount into its native denomination if the token metadata cannot be derived on chain',
+    )
+
     .boolean('dry-run')
     .describe('dry-run', 'Simulate the transaction without sending')
     .default('dry-run', false).argv;
 
   const config = getEnvironmentConfig(argv.environment);
-  const { recipient, amount, chain, dryRun } = argv;
+  const { recipient, amount, chain, dryRun, token, decimals, symbol } = argv;
 
   logger.info(
     {
       recipient,
       amount,
       chain,
       dryRun,
+      token: token ?? 'native token',
     },
     'Starting funding operation',
   );
 
+  assert(chain, 'Chain is required');
+
+  let tokenToFundInfo: TokenToFundInfo;
+  if (symbol) {
+    const registry = await config.getRegistry();
+
+    const warpRoutes = await registry.getWarpRoutes();
+    const knownTokenAddresses: ChainMap<Record<string, string>> = {};
+    Object.values(warpRoutes).forEach(({ tokens }) =>
+      tokens.forEach((tokenConfig) => {
+        if (!tokenConfig.collateralAddressOrDenom) {
+          return;
+        }
+
+        const knownTokensForCurrentChain =
+          (knownInfraTokens as Record<ChainName, Record<string, string>>)[
+            tokenConfig.chainName
+          ] ?? {};
+
+        knownTokenAddresses[tokenConfig.chainName] ??= {};
+        knownTokenAddresses[tokenConfig.chainName][
+          tokenConfig.symbol.toLowerCase()
+        ] =
+          // Default to the address in the infra mapping if one exists
+          knownTokensForCurrentChain[tokenConfig.symbol.toLowerCase()] ??
+          tokenConfig.collateralAddressOrDenom;
+      }),
+    );
+
+    const tokenAddress = knownTokenAddresses[chain]?.[symbol.toLowerCase()];
+    assert(
+      tokenAddress,
+      `An address was not found for token with symbol "${symbol}" on chain "${chain}". Please provide the token address instead`,
+    );
+
+    tokenToFundInfo = {
+      amount: parseFloat(amount),
+      recipientAddress: recipient,
+      tokenAddress,
+      type: TokenFundingType.non_native,
+      tokenDecimals: decimals ? parseInt(decimals) : undefined,
+    };
+  } else if (token) {
+    tokenToFundInfo = {
+      type: TokenFundingType.non_native,
+      amount: parseFloat(amount),
+      recipientAddress: recipient,
+      tokenAddress: token,
+      tokenDecimals: decimals ? parseInt(decimals) : undefined,
+    };
+  } else {
+    tokenToFundInfo = {
+      type: TokenFundingType.native,
+      amount: parseFloat(amount),
+      recipientAddress: recipient,
+      tokenDecimals: decimals ? parseInt(decimals) : undefined,
+    };
+  }
+
   try {
     await fundAccount({
       config,
-      chainName: chain!,
-      recipientAddress: recipient,
-      amount,
+      chainName: chain,
       dryRun,
+      fundInfo: tokenToFundInfo,
     });
 
     logger.info('Funding operation completed successfully');
@@ -108,18 +212,18 @@ async function main() {
 interface FundingParams {
   config: EnvironmentConfig;
   chainName: ChainName;
-  recipientAddress: Address;
-  amount: string;
+  fundInfo: TokenToFundInfo;
   dryRun: boolean;
 }
 
 async function fundAccount({
   config,
   chainName,
-  recipientAddress,
-  amount,
   dryRun,
+  fundInfo,
 }: FundingParams): Promise<void> {
+  const { amount, recipientAddress, tokenDecimals } = fundInfo;
+
   const multiProtocolProvider = await config.getMultiProtocolProvider();
 
   const chainMetadata = multiProtocolProvider.getChainMetadata(chainName);
@@ -128,6 +232,7 @@ async function fundAccount({
   const fundingLogger = logger.child({
     chainName,
     protocol,
+    type: fundInfo.type,
   });
 
   const tokenPriceGetter = new CoinGeckoTokenPriceGetter({
@@ -137,29 +242,78 @@ async function fundAccount({
 
   let tokenPrice;
   try {
-    tokenPrice = await tokenPriceGetter.getTokenPrice(chainName);
+    if (fundInfo.type === TokenFundingType.non_native) {
+      tokenPrice = await tokenPriceGetter.fetchPriceDataByContractAddress(
+        chainName,
+        fundInfo.tokenAddress,
+      );
+    } else {
+      tokenPrice = await tokenPriceGetter.getTokenPrice(chainName);
+    }
   } catch (err) {
     fundingLogger.error(
-      { chainName, err },
-      `Failed to get native token price for ${chainName}, falling back to 1usd`,
+      { err },
+      `Failed to get token price for ${chainName}, falling back to 1usd`,
     );
     tokenPrice = 1;
   }
-  const fundingAmountInUsd = parseFloat(amount) * tokenPrice;
+  const fundingAmountInUsd = amount * tokenPrice;
 
   if (fundingAmountInUsd > MAX_FUNDING_AMOUNT_IN_USD) {
     throw new Error(
       `Funding amount in USD exceeds max funding amount. Max: ${MAX_FUNDING_AMOUNT_IN_USD}. Got: ${fundingAmountInUsd}`,
     );
   }
 
-  // Create token instance
-  const token = Token.FromChainMetadataNativeToken(chainMetadata);
-  const adapter = token.getAdapter(multiProtocolProvider);
+  // Create adapter instance
+  let adapter: ITokenAdapter<unknown>;
+  if (fundInfo.type === TokenFundingType.non_native) {
+    adapter = getCollateralTokenAdapter({
+      chainName,
+      multiProvider: multiProtocolProvider,
+      tokenAddress: fundInfo.tokenAddress,
+    });
+  } else {
+    const tokenInstance = Token.FromChainMetadataNativeToken(chainMetadata);
+    adapter = tokenInstance.getAdapter(multiProtocolProvider);
+  }
 
-  // Get signer
-  fundingLogger.info('Retrieved signer info');
+  let tokenMetadata: {
+    name: string;
+    symbol: string;
+    decimals: number;
+  };
+  try {
+    const { name, symbol, decimals } = await adapter.getMetadata();
+    assert(
+      decimals,
+      `Expected decimals for ${fundInfo.type} token funding of ${fundInfo.type === TokenFundingType.non_native ? fundInfo.tokenAddress : ''} on chain "${chainName}" to be defined`,
+    );
 
+    tokenMetadata = {
+      name,
+      symbol,
+      decimals,
+    };
+  } catch (err) {
+    fundingLogger.error(
+      { err },
+      `Failed to get token metadata for ${chainName}`,
+    );
+
+    assert(
+      tokenDecimals,
+      `tokenDecimals is required as the token metadata can't be derived on chain`,
+    );
+
+    tokenMetadata = {
+      name: 'NAME NOT SPECIFIED',
+      symbol: 'SYMBOL NOT SPECIFIED',
+      decimals: tokenDecimals,
+    };
+  }
+
+  // Get signer
   const agentConfig = getAgentConfig(Contexts.Hyperlane, config.environment);
   const privateKeyAgent = getDeployerKey(agentConfig, chainName);
 
@@ -193,11 +347,6 @@ async function fundAccount({
     multiProtocolProvider,
   );
 
-  fundingLogger.info(
-    { chainName, protocol },
-    'Performing pre transaction checks',
-  );
-
   // Check balance before transfer
   const fromAddress = await signer.address();
   const currentBalance = await adapter.getBalance(fromAddress);
@@ -206,13 +355,13 @@ async function fundAccount({
     {
       fromAddress,
       currentBalance: currentBalance.toString(),
-      symbol: token.symbol,
+      symbol: tokenMetadata.symbol,
     },
-    'Current sender balance',
+    'Retrieved signer balance info',
   );
 
   // Convert amount to wei/smallest unit
-  const decimals = token.decimals;
+  const decimals = tokenMetadata.decimals;
   const weiAmount = BigInt(toWei(amount, decimals));
 
   fundingLogger.info(
@@ -227,7 +376,7 @@ async function fundAccount({
   // Check if we have sufficient balance
   if (currentBalance < weiAmount) {
     throw new Error(
-      `Insufficient balance. Have: ${formatUnits(currentBalance, decimals)} ${token.symbol}, Need: ${amount} ${token.symbol}`,
+      `Insufficient balance. Have: ${formatUnits(currentBalance.toString(), decimals)} ${tokenMetadata.symbol}, Need: ${amount} ${tokenMetadata.symbol}`,
     );
   }
 
@@ -238,22 +387,22 @@ async function fundAccount({
     fromAccountOwner: fromAddress,
   };
 
-  fundingLogger.info(
-    {
-      transferParams,
-      dryRun,
-    },
-    'Preparing transfer transaction',
-  );
-
   // Execute the transfer
   const transferTx = await adapter.populateTransferTx(transferParams);
 
   const protocolTypedTx = {
     transaction: transferTx,
-    type: TOKEN_STANDARD_TO_PROVIDER_TYPE[token.standard],
+    type: PROTOCOL_TO_DEFAULT_PROVIDER_TYPE[protocol],
   } as ProtocolTypedTransaction<typeof protocol>;
 
+  fundingLogger.info(
+    {
+      transferParams,
+      dryRun,
+    },
+    'Prepared transfer transaction data',
+  );
+
   if (dryRun) {
     fundingLogger.info('DRY RUN: Would execute transfer with above parameters');
     return;
@@ -272,9 +421,9 @@ async function fundAccount({
   fundingLogger.info(
     {
       transactionHash,
-      senderNewBalance: formatUnits(newBalance, decimals),
-      recipientBalance: formatUnits(recipientBalance, decimals),
-      symbol: token.symbol,
+      senderNewBalance: formatUnits(newBalance.toString(), decimals),
+      recipientBalance: formatUnits(recipientBalance.toString(), decimals),
+      symbol: tokenMetadata.symbol,
     },
     'Transfer completed successfully',
   );