@heyanon/sdk 2.3.1 → 2.3.3

package/dist/blockchain/evm/utils/getUnwrapData.d.ts

@@ -1,3 +1,117 @@
 import { EvmChain } from '../../constants';
 import { TransactionParams } from '../types';
+/**
+ * Generates transaction data for unwrapping tokens (converting wrapped tokens back to native currency)
+ * @param chain - The EVM chain where the unwrap operation will occur
+ * @param amount - The amount of wrapped tokens to unwrap (in wei/smallest unit)
+ * @returns Transaction parameters for the unwrap operation
+ * @example
+ * ```typescript
+ * import { parseEther } from 'viem';
+ *
+ * // Basic unwrap operation
+ * const unwrapTxData = getUnwrapData(Chain.ETHEREUM, parseEther('1')); // Unwrap 1 WETH to ETH
+ * // Returns: { target: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', data: '0x...' }
+ *
+ * // Different chains with their wrapped tokens
+ * const unwrapWBNB = getUnwrapData(Chain.BSC, parseEther('0.5'));      // WBNB → BNB
+ * const unwrapWMATIC = getUnwrapData(Chain.POLYGON, parseEther('100')); // WPOL → POL
+ * const unwrapWAVAX = getUnwrapData(Chain.AVALANCHE, parseEther('10')); // WAVAX → AVAX
+ *
+ * // Use in adapter function
+ * async function unwrapTokens(chain: EvmChain, amount: string) {
+ *   const amountBigInt = parseEther(amount);
+ *   const unwrapData = getUnwrapData(chain, amountBigInt);
+ *
+ *   return await options.evm.sendTransactions({
+ *     transactions: [unwrapData]
+ *   });
+ * }
+ *
+ * // Complete unwrap workflow with balance check
+ * async function safeUnwrapTokens(chain: EvmChain, amount: bigint) {
+ *   const userAddress = await options.evm.getAddress();
+ *   const wrappedTokenAddress = getWrapAddress(chain);
+ *   const provider = options.evm.getProvider(getChainFromName(chain));
+ *
+ *   // Check user's wrapped token balance
+ *   const balance = await provider.readContract({
+ *     address: wrappedTokenAddress,
+ *     abi: WETH9Abi,
+ *     functionName: 'balanceOf',
+ *     args: [userAddress]
+ *   });
+ *
+ *   if (balance < amount) {
+ *     throw new Error(`Insufficient wrapped token balance. Have: ${balance}, Need: ${amount}`);
+ *   }
+ *
+ *   // Generate unwrap transaction
+ *   const unwrapData = getUnwrapData(chain, amount);
+ *
+ *   return await options.evm.sendTransactions({
+ *     transactions: [unwrapData]
+ *   });
+ * }
+ *
+ * // Batch unwrap on multiple chains
+ * async function batchUnwrapAcrossChains(
+ *   operations: Array<{ chain: EvmChain; amount: bigint }>
+ * ) {
+ *   const results = await Promise.allSettled(
+ *     operations.map(async ({ chain, amount }) => {
+ *       const unwrapData = getUnwrapData(chain, amount);
+ *
+ *       return {
+ *         chain,
+ *         amount,
+ *         transaction: await options.evm.sendTransactions({
+ *           transactions: [unwrapData]
+ *         })
+ *       };
+ *     })
+ *   );
+ *
+ *   return results.map((result, index) => ({
+ *     ...operations[index],
+ *     success: result.status === 'fulfilled',
+ *     result: result.status === 'fulfilled' ? result.value : result.reason
+ *   }));
+ * }
+ *
+ * // Use in DeFi yield withdrawal
+ * async function withdrawYieldAndUnwrap(chain: EvmChain, poolAddress: string) {
+ *   const transactions: TransactionParams[] = [];
+ *
+ *   // First, withdraw from yield farming pool (gets wrapped tokens)
+ *   transactions.push({
+ *     target: poolAddress,
+ *     data: encodeFunctionData({
+ *       abi: yieldPoolAbi,
+ *       functionName: 'withdraw',
+ *       args: [userStakedAmount]
+ *     })
+ *   });
+ *
+ *   // Then unwrap the received tokens to native currency
+ *   const unwrapData = getUnwrapData(chain, expectedWrappedAmount);
+ *   transactions.push(unwrapData);
+ *
+ *   return await options.evm.sendTransactions({ transactions });
+ * }
+ *
+ * // Gas estimation for unwrap operation
+ * async function estimateUnwrapGas(chain: EvmChain, amount: bigint) {
+ *   const unwrapData = getUnwrapData(chain, amount);
+ *   const provider = options.evm.getProvider(getChainFromName(chain));
+ *   const userAddress = await options.evm.getAddress();
+ *
+ *   return await provider.estimateGas({
+ *     account: userAddress,
+ *     to: unwrapData.target,
+ *     data: unwrapData.data
+ *   });
+ * }
+ * ```
+ */
 export declare function getUnwrapData(chain: EvmChain, amount: bigint): TransactionParams;

package/dist/blockchain/evm/utils/getWrapAddress.d.ts

@@ -1,3 +1,150 @@
 import { EvmChain } from '../../constants';
 import { Address } from 'viem';
+/**
+ * Retrieves the wrapped native token contract address for a specific EVM chain
+ * @param chain - The EVM chain to get the wrapped token address for
+ * @returns The contract address of the wrapped native token (WETH9-compatible)
+ * @throws {Error} When the chain doesn't have a configured wrapped token address
+ * @example
+ * ```typescript
+ * // Get wrapped token addresses for different chains
+ * const wethAddress = getWrapAddress(Chain.ETHEREUM);   // '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
+ * const wbnbAddress = getWrapAddress(Chain.BSC);        // '0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c'
+ * const wpolAddress = getWrapAddress(Chain.POLYGON);    // '0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270'
+ *
+ * // Use in token operations
+ * async function getWrappedTokenBalance(chain: EvmChain, userAddress: Address) {
+ *   const wrapAddress = getWrapAddress(chain);
+ *   const provider = options.evm.getProvider(getChainFromName(chain));
+ *
+ *   return await provider.readContract({
+ *     address: wrapAddress,
+ *     abi: erc20Abi,
+ *     functionName: 'balanceOf',
+ *     args: [userAddress]
+ *   });
+ * }
+ *
+ * // Check if token address is a wrapped native token
+ * function isWrappedNativeToken(chain: EvmChain, tokenAddress: Address): boolean {
+ *   try {
+ *     const wrapAddress = getWrapAddress(chain);
+ *     return wrapAddress.toLowerCase() === tokenAddress.toLowerCase();
+ *   } catch (error) {
+ *     return false;
+ *   }
+ * }
+ *
+ * // Use in DEX trading setup
+ * async function setupTokenSwap(
+ *   chain: EvmChain,
+ *   tokenIn: Address,
+ *   tokenOut: Address,
+ *   amountIn: bigint
+ * ) {
+ *   const transactions: TransactionParams[] = [];
+ *   const wrapAddress = getWrapAddress(chain);
+ *
+ *   // If input is native token, wrap it first
+ *   if (tokenIn === NATIVE_ADDRESS) {
+ *     const wrapData = getWrapData(chain, amountIn);
+ *     transactions.push(wrapData);
+ *     tokenIn = wrapAddress; // Update tokenIn to wrapped version
+ *   }
+ *
+ *   // Add swap transaction
+ *   transactions.push(buildSwapTransaction(tokenIn, tokenOut, amountIn));
+ *
+ *   // If output should be native, add unwrap transaction
+ *   if (tokenOut === NATIVE_ADDRESS) {
+ *     const unwrapData = getUnwrapData(chain, expectedAmountOut);
+ *     transactions.push(unwrapData);
+ *   }
+ *
+ *   return transactions;
+ * }
+ *
+ * // Get wrapped token info for UI display
+ * function getWrappedTokenInfo(chain: EvmChain) {
+ *   const address = getWrapAddress(chain);
+ *   const token = WETH9[chain];
+ *
+ *   return {
+ *     address,
+ *     name: token.name,
+ *     symbol: token.symbol,
+ *     decimals: token.decimals,
+ *     chainId: token.chainId
+ *   };
+ * }
+ *
+ * // Approve wrapped token for spending
+ * async function approveWrappedToken(
+ *   chain: EvmChain,
+ *   spender: Address,
+ *   amount: bigint
+ * ) {
+ *   const wrapAddress = getWrapAddress(chain);
+ *   const transactions: TransactionParams[] = [];
+ *
+ *   await checkToApprove({
+ *     args: {
+ *       account: await options.evm.getAddress(),
+ *       target: wrapAddress,
+ *       spender,
+ *       amount
+ *     },
+ *     provider: options.evm.getProvider(getChainFromName(chain)),
+ *     transactions
+ *   });
+ *
+ *   return transactions;
+ * }
+ *
+ * // Multi-chain wrapped token portfolio
+ * async function getWrappedTokenPortfolio(
+ *   chains: EvmChain[],
+ *   userAddress: Address
+ * ) {
+ *   const portfolio = await Promise.allSettled(
+ *     chains.map(async (chain) => {
+ *       try {
+ *         const wrapAddress = getWrapAddress(chain);
+ *         const provider = options.evm.getProvider(getChainFromName(chain));
+ *
+ *         const balance = await provider.readContract({
+ *           address: wrapAddress,
+ *           abi: erc20Abi,
+ *           functionName: 'balanceOf',
+ *           args: [userAddress]
+ *         });
+ *
+ *         return {
+ *           chain,
+ *           address: wrapAddress,
+ *           balance,
+ *           token: WETH9[chain]
+ *         };
+ *       } catch (error) {
+ *         throw new Error(`Failed to get wrapped token for ${chain}: ${error.message}`);
+ *       }
+ *     })
+ *   );
+ *
+ *   return portfolio
+ *     .filter((result): result is PromiseFulfilledResult<any> => result.status === 'fulfilled')
+ *     .map(result => result.value)
+ *     .filter(item => item.balance > 0n);
+ * }
+ *
+ * // Safe version that returns null instead of throwing
+ * function safeGetWrapAddress(chain: EvmChain): Address | null {
+ *   try {
+ *     return getWrapAddress(chain);
+ *   } catch (error) {
+ *     return null;
+ *   }
+ * }
+ * ```
+ */
 export declare function getWrapAddress(chain: EvmChain): Address;

package/dist/blockchain/evm/utils/getWrapData.d.ts

@@ -1,3 +1,192 @@
 import { TransactionParams } from '../types';
 import { EvmChain } from '../../constants';
+/**
+ * Generates transaction data for wrapping native currency into wrapped tokens (e.g., ETH → WETH)
+ * @param chain - The EVM chain where the wrap operation will occur
+ * @param amount - The amount of native currency to wrap (in wei/smallest unit)
+ * @returns Transaction parameters for the wrap operation including target, data, and value
+ * @example
+ * ```typescript
+ * import { parseEther } from 'viem';
+ *
+ * // Basic wrap operation
+ * const wrapTxData = getWrapData(Chain.ETHEREUM, parseEther('1')); // Wrap 1 ETH to WETH
+ * // Returns: {
+ * //   target: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
+ * //   data: '0xd0e30db0',
+ * //   value: 1000000000000000000n
+ * // }
+ *
+ * // Different chains with their native currencies
+ * const wrapBNB = getWrapData(Chain.BSC, parseEther('0.5'));      // BNB → WBNB
+ * const wrapMATIC = getWrapData(Chain.POLYGON, parseEther('100')); // POL → WPOL
+ * const wrapAVAX = getWrapData(Chain.AVALANCHE, parseEther('10')); // AVAX → WAVAX
+ *
+ * // Use in adapter function
+ * async function wrapNativeTokens(chain: EvmChain, amount: string) {
+ *   const amountBigInt = parseEther(amount);
+ *   const wrapData = getWrapData(chain, amountBigInt);
+ *
+ *   return await options.evm.sendTransactions({
+ *     transactions: [wrapData]
+ *   });
+ * }
+ *
+ * // Complete wrap workflow with balance check
+ * async function safeWrapTokens(chain: EvmChain, amount: bigint) {
+ *   const userAddress = await options.evm.getAddress();
+ *   const provider = options.evm.getProvider(getChainFromName(chain));
+ *
+ *   // Check user's native token balance
+ *   const balance = await provider.getBalance({ address: userAddress });
+ *
+ *   if (balance < amount) {
+ *     throw new Error(`Insufficient native token balance. Have: ${balance}, Need: ${amount}`);
+ *   }
+ *
+ *   // Generate wrap transaction
+ *   const wrapData = getWrapData(chain, amount);
+ *
+ *   return await options.evm.sendTransactions({
+ *     transactions: [wrapData]
+ *   });
+ * }
+ *
+ * // Use in DEX operations that require wrapped tokens
+ * async function wrapAndSwap(
+ *   chain: EvmChain,
+ *   amountIn: bigint,
+ *   tokenOut: Address,
+ *   minAmountOut: bigint
+ * ) {
+ *   const transactions: TransactionParams[] = [];
+ *
+ *   // First, wrap native currency
+ *   const wrapData = getWrapData(chain, amountIn);
+ *   transactions.push(wrapData);
+ *
+ *   // Then approve wrapped token for DEX
+ *   const wrapAddress = getWrapAddress(chain);
+ *   await checkToApprove({
+ *     args: {
+ *       account: await options.evm.getAddress(),
+ *       target: wrapAddress,
+ *       spender: DEX_ROUTER_ADDRESS,
+ *       amount: amountIn
+ *     },
+ *     provider: options.evm.getProvider(getChainFromName(chain)),
+ *     transactions
+ *   });
+ *
+ *   // Finally, execute swap
+ *   transactions.push({
+ *     target: DEX_ROUTER_ADDRESS,
+ *     data: encodeFunctionData({
+ *       abi: dexRouterAbi,
+ *       functionName: 'swapExactTokensForTokens',
+ *       args: [amountIn, minAmountOut, [wrapAddress, tokenOut], userAddress, deadline]
+ *     })
+ *   });
+ *
+ *   return await options.evm.sendTransactions({ transactions });
+ * }
+ *
+ * // Batch wrap operations across multiple chains
+ * async function batchWrapAcrossChains(
+ *   operations: Array<{ chain: EvmChain; amount: bigint }>
+ * ) {
+ *   const results = await Promise.allSettled(
+ *     operations.map(async ({ chain, amount }) => {
+ *       const wrapData = getWrapData(chain, amount);
+ *
+ *       return {
+ *         chain,
+ *         amount,
+ *         transaction: await options.evm.sendTransactions({
+ *           transactions: [wrapData]
+ *         })
+ *       };
+ *     })
+ *   );
+ *
+ *   return results.map((result, index) => ({
+ *     ...operations[index],
+ *     success: result.status === 'fulfilled',
+ *     result: result.status === 'fulfilled' ? result.value : result.reason
+ *   }));
+ * }
+ *
+ * // Use in yield farming setup
+ * async function wrapAndStake(
+ *   chain: EvmChain,
+ *   stakingPoolAddress: Address,
+ *   amount: bigint
+ * ) {
+ *   const transactions: TransactionParams[] = [];
+ *   const wrapAddress = getWrapAddress(chain);
+ *
+ *   // Wrap native currency
+ *   const wrapData = getWrapData(chain, amount);
+ *   transactions.push(wrapData);
+ *
+ *   // Approve wrapped token for staking pool
+ *   await checkToApprove({
+ *     args: {
+ *       account: await options.evm.getAddress(),
+ *       target: wrapAddress,
+ *       spender: stakingPoolAddress,
+ *       amount
+ *     },
+ *     provider: options.evm.getProvider(getChainFromName(chain)),
+ *     transactions
+ *   });
+ *
+ *   // Stake wrapped tokens
+ *   transactions.push({
+ *     target: stakingPoolAddress,
+ *     data: encodeFunctionData({
+ *       abi: stakingPoolAbi,
+ *       functionName: 'stake',
+ *       args: [amount]
+ *     })
+ *   });
+ *
+ *   return await options.evm.sendTransactions({ transactions });
+ * }
+ *
+ * // Gas estimation for wrap operation
+ * async function estimateWrapGas(chain: EvmChain, amount: bigint) {
+ *   const wrapData = getWrapData(chain, amount);
+ *   const provider = options.evm.getProvider(getChainFromName(chain));
+ *   const userAddress = await options.evm.getAddress();
+ *
+ *   return await provider.estimateGas({
+ *     account: userAddress,
+ *     to: wrapData.target,
+ *     data: wrapData.data,
+ *     value: wrapData.value
+ *   });
+ * }
+ *
+ * // Progressive wrap for large amounts
+ * async function progressiveWrap(
+ *   chain: EvmChain,
+ *   totalAmount: bigint,
+ *   batchSize: bigint = parseEther('10')
+ * ) {
+ *   const transactions: TransactionParams[] = [];
+ *   let remainingAmount = totalAmount;
+ *
+ *   while (remainingAmount > 0n) {
+ *     const currentBatch = remainingAmount > batchSize ? batchSize : remainingAmount;
+ *     const wrapData = getWrapData(chain, currentBatch);
+ *     transactions.push(wrapData);
+ *
+ *     remainingAmount -= currentBatch;
+ *   }
+ *
+ *   return await options.evm.sendTransactions({ transactions });
+ * }
+ * ```
+ */
 export declare function getWrapData(chain: EvmChain, amount: bigint): TransactionParams;

package/dist/blockchain/evm/utils/getWrappedNative.d.ts

@@ -1,3 +1,201 @@
 import { Token } from '@real-wagmi/sdk';
 import { EvmChain } from '../../constants/chains';
+/**
+ * Retrieves the wrapped native token object for a specific EVM chain
+ * @param chain - The EVM chain to get the wrapped native token for
+ * @returns Complete Token object with address, decimals, symbol, name, and chainId
+ * @throws {Error} When the chain doesn't have a configured wrapped native token
+ * @example
+ * ```typescript
+ * // Get wrapped native tokens for different chains
+ * const weth = getWrappedNative(Chain.ETHEREUM);
+ * console.log(weth);
+ * // Output: {
+ * //   chainId: 1,
+ * //   address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
+ * //   decimals: 18,
+ * //   symbol: 'WETH',
+ * //   name: 'Wrapped Ether'
+ * // }
+ *
+ * const wbnb = getWrappedNative(Chain.BSC);        // WBNB on BSC
+ * const wpol = getWrappedNative(Chain.POLYGON);    // WPOL on Polygon
+ * const wavax = getWrappedNative(Chain.AVALANCHE); // WAVAX on Avalanche
+ *
+ * // Use token properties in DeFi operations
+ * function formatTokenAmount(chain: EvmChain, amount: bigint): string {
+ *   const token = getWrappedNative(chain);
+ *   const formatted = formatUnits(amount, token.decimals);
+ *   return `${formatted} ${token.symbol}`;
+ * }
+ *
+ * // Create token pair for DEX operations
+ * function createTokenPair(chainA: EvmChain, chainB: EvmChain) {
+ *   const tokenA = getWrappedNative(chainA);
+ *   const tokenB = getWrappedNative(chainB);
+ *
+ *   return {
+ *     tokenA,
+ *     tokenB,
+ *     isValid: tokenA.chainId !== tokenB.chainId
+ *   };
+ * }
+ *
+ * // Use in liquidity pool operations
+ * async function addLiquidityWithWrappedNative(
+ *   chain: EvmChain,
+ *   otherToken: Token,
+ *   amountNative: bigint,
+ *   amountOther: bigint
+ * ) {
+ *   const wrappedNative = getWrappedNative(chain);
+ *
+ *   // First wrap native currency
+ *   const wrapData = getWrapData(chain, amountNative);
+ *
+ *   // Then add liquidity
+ *   const addLiquidityData = {
+ *     target: LP_ROUTER_ADDRESS,
+ *     data: encodeFunctionData({
+ *       abi: lpRouterAbi,
+ *       functionName: 'addLiquidity',
+ *       args: [
+ *         wrappedNative.address,
+ *         otherToken.address,
+ *         amountNative,
+ *         amountOther,
+ *         0n, // min amounts (should be calculated properly)
+ *         0n,
+ *         await options.evm.getAddress(),
+ *         Math.floor(Date.now() / 1000) + 3600 // deadline
+ *       ]
+ *     })
+ *   };
+ *
+ *   return await options.evm.sendTransactions({
+ *     transactions: [wrapData, addLiquidityData]
+ *   });
+ * }
+ *
+ * // Token validation and comparison
+ * function isWrappedNativeToken(chain: EvmChain, tokenAddress: string): boolean {
+ *   try {
+ *     const wrappedNative = getWrappedNative(chain);
+ *     return wrappedNative.address.toLowerCase() === tokenAddress.toLowerCase();
+ *   } catch (error) {
+ *     return false;
+ *   }
+ * }
+ *
+ * // Generate token list for UI
+ * function generateWrappedNativeTokenList(chains: EvmChain[]) {
+ *   return chains.map(chain => {
+ *     try {
+ *       const token = getWrappedNative(chain);
+ *       return {
+ *         ...token,
+ *         chainName: chain,
+ *         logoURI: `https://tokens.app/tokens/${token.chainId}/${token.address}.png`,
+ *         tags: ['wrapped', 'native']
+ *       };
+ *     } catch (error) {
+ *       return null;
+ *     }
+ *   }).filter(Boolean);
+ * }
+ *
+ * // Cross-chain token bridge preparation
+ * async function prepareBridgeTransaction(
+ *   sourceChain: EvmChain,
+ *   targetChain: EvmChain,
+ *   amount: bigint
+ * ) {
+ *   const sourceToken = getWrappedNative(sourceChain);
+ *   const targetToken = getWrappedNative(targetChain);
+ *
+ *   return {
+ *     source: {
+ *       chain: sourceChain,
+ *       token: sourceToken,
+ *       amount
+ *     },
+ *     target: {
+ *       chain: targetChain,
+ *       token: targetToken,
+ *       expectedAmount: amount // Simplified - should include bridge fees
+ *     },
+ *     bridgeConfig: {
+ *       sourceChainId: sourceToken.chainId,
+ *       targetChainId: targetToken.chainId,
+ *       tokenAddress: sourceToken.address
+ *     }
+ *   };
+ * }
+ *
+ * // Portfolio tracking with wrapped natives
+ * async function getWrappedNativePortfolio(
+ *   chains: EvmChain[],
+ *   userAddress: Address
+ * ) {
+ *   const portfolio = await Promise.allSettled(
+ *     chains.map(async (chain) => {
+ *       const token = getWrappedNative(chain);
+ *       const provider = options.evm.getProvider(token.chainId);
+ *
+ *       const balance = await provider.readContract({
+ *         address: token.address,
+ *         abi: erc20Abi,
+ *         functionName: 'balanceOf',
+ *         args: [userAddress]
+ *       });
+ *
+ *       return {
+ *         chain,
+ *         token,
+ *         balance,
+ *         formattedBalance: formatUnits(balance, token.decimals),
+ *         usdValue: await getTokenUSDValue(token, balance) // External price service
+ *       };
+ *     })
+ *   );
+ *
+ *   return portfolio
+ *     .filter((result): result is PromiseFulfilledResult<any> => result.status === 'fulfilled')
+ *     .map(result => result.value)
+ *     .filter(item => item.balance > 0n);
+ * }
+ *
+ * // DEX price comparison across chains
+ * async function compareWrappedNativePrices(chains: EvmChain[]) {
+ *   const priceData = await Promise.allSettled(
+ *     chains.map(async (chain) => {
+ *       const token = getWrappedNative(chain);
+ *       const price = await getDEXPrice(token); // External price fetching
+ *
+ *       return {
+ *         chain,
+ *         token: token.symbol,
+ *         address: token.address,
+ *         priceUSD: price,
+ *         chainId: token.chainId
+ *       };
+ *     })
+ *   );
+ *
+ *   return priceData
+ *     .filter((result): result is PromiseFulfilledResult<any> => result.status === 'fulfilled')
+ *     .map(result => result.value)
+ *     .sort((a, b) => b.priceUSD - a.priceUSD);
+ * }
+ *
+ * // Safe version that returns null instead of throwing
+ * function safeGetWrappedNative(chain: EvmChain): Token | null {
+ *   try {
+ *     return getWrappedNative(chain);
+ *   } catch (error) {
+ *     return null;
+ *   }
+ * }
+ * ```
+ */
 export declare function getWrappedNative(chain: EvmChain): Token;