@heyanon/sdk 2.3.2 → 2.3.4

package/dist/blockchain/evm/types.d.ts

@@ -1,29 +1,302 @@
 import { Abi, Address, Hex } from 'viem';
+/**
+ * Parameters for an EVM transaction
+ * @interface TransactionParams
+ * @example
+ * ```typescript
+ * // ERC20 token transfer
+ * const transferTx: TransactionParams = {
+ *   target: '0xA0b86a33E6417e4681831442Ff7Bd6c25b5d9C7a', // USDC contract
+ *   data: encodeFunctionData({
+ *     abi: erc20Abi,
+ *     functionName: 'transfer',
+ *     args: ['0x742d35Cc6634C0532925a3b8D4C2CA1c1DfF0bE8', parseUnits('100', 6)]
+ *   })
+ * };
+ *
+ * // Native token transfer
+ * const nativeTx: TransactionParams = {
+ *   target: '0x742d35Cc6634C0532925a3b8D4C2CA1c1DfF0bE8',
+ *   data: '0x',
+ *   value: parseEther('1') // 1 ETH
+ * };
+ *
+ * // Contract interaction with gas limit
+ * const contractTx: TransactionParams = {
+ *   target: '0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984', // UNI contract
+ *   data: encodeFunctionData({
+ *     abi: uniswapAbi,
+ *     functionName: 'swapExactTokensForTokens',
+ *     args: [amountIn, amountOutMin, path, to, deadline]
+ *   }),
+ *   gas: 200000n // Custom gas limit
+ * };
+ * ```
+ */
 export interface TransactionParams {
+    /** Contract or recipient address */
     readonly target: Address;
+    /** Encoded function call data or '0x' for simple transfers */
     readonly data: Hex;
+    /** Amount of native currency to send (optional) */
     readonly value?: bigint;
+    /** Gas limit for the transaction (optional) */
     readonly gas?: bigint;
 }
+/**
+ * Data returned for each executed transaction
+ * @interface TransactionReturnData
+ * @example
+ * ```typescript
+ * // Successful transaction result
+ * const successData: TransactionReturnData = {
+ *   message: "Transaction confirmed",
+ *   hash: "0x1234567890abcdef..."
+ * };
+ *
+ * // Failed transaction result
+ * const failedData: TransactionReturnData = {
+ *   message: "Transaction failed: insufficient gas",
+ *   hash: "0xabcdef1234567890..."
+ * };
+ * ```
+ */
 export interface TransactionReturnData {
+    /** Status message or error description */
     readonly message: string;
+    /** Transaction hash on the blockchain */
     readonly hash: Hex;
 }
+/**
+ * Complete result of transaction execution containing all transaction results
+ * @interface TransactionReturn
+ * @example
+ * ```typescript
+ * // Batch transaction result
+ * const batchResult: TransactionReturn = {
+ *   data: [
+ *     {
+ *       message: "Approval confirmed",
+ *       hash: "0x1111..."
+ *     },
+ *     {
+ *       message: "Swap completed",
+ *       hash: "0x2222..."
+ *     }
+ *   ]
+ * };
+ *
+ * // Single transaction result
+ * const singleResult: TransactionReturn = {
+ *   data: [{
+ *     message: "Transfer successful",
+ *     hash: "0x3333..."
+ *   }]
+ * };
+ *
+ * // Process results
+ * batchResult.data.forEach((tx, index) => {
+ *   console.log(`Transaction ${index + 1}: ${tx.message} - ${tx.hash}`);
+ * });
+ * ```
+ */
 export interface TransactionReturn {
+    /** Array of transaction results */
     readonly data: TransactionReturnData[];
 }
+/**
+ * Properties for sending one or multiple transactions
+ * @interface SendTransactionProps
+ * @example
+ * ```typescript
+ * // Single transaction
+ * const singleTxProps: SendTransactionProps = {
+ *   chainId: 1, // Ethereum mainnet
+ *   account: '0x742d35Cc6634C0532925a3b8D4C2CA1c1DfF0bE8',
+ *   transactions: [{
+ *     target: '0xA0b86a33E6417e4681831442Ff7Bd6c25b5d9C7a',
+ *     data: encodeFunctionData({
+ *       abi: erc20Abi,
+ *       functionName: 'transfer',
+ *       args: [recipient, amount]
+ *     })
+ *   }]
+ * };
+ *
+ * // Batch transactions (approve + swap)
+ * const batchTxProps: SendTransactionProps = {
+ *   chainId: 137, // Polygon
+ *   account: userAddress,
+ *   transactions: [
+ *     {
+ *       target: tokenAddress,
+ *       data: encodeFunctionData({
+ *         abi: erc20Abi,
+ *         functionName: 'approve',
+ *         args: [spenderAddress, amount]
+ *       })
+ *     },
+ *     {
+ *       target: dexRouterAddress,
+ *       data: encodeFunctionData({
+ *         abi: dexRouterAbi,
+ *         functionName: 'swapExactTokensForTokens',
+ *         args: [amountIn, amountOutMin, path, userAddress, deadline]
+ *       })
+ *     }
+ *   ]
+ * };
+ *
+ * // Usage in adapter function
+ * const result = await options.evm.sendTransactions(batchTxProps);
+ * ```
+ */
 export interface SendTransactionProps {
+    /** Chain ID where transactions will be executed */
     readonly chainId: number;
+    /** Account address that will execute the transactions */
     readonly account: Address;
+    /** Array of transactions to execute */
     readonly transactions: TransactionParams[];
 }
+/**
+ * Properties for deploying a smart contract
+ * @interface ContractProps
+ * @example
+ * ```typescript
+ * // ERC20 token deployment
+ * const tokenContract: ContractProps = {
+ *   abi: [
+ *     {
+ *       "inputs": [
+ *         {"name": "_name", "type": "string"},
+ *         {"name": "_symbol", "type": "string"},
+ *         {"name": "_totalSupply", "type": "uint256"}
+ *       ],
+ *       "stateMutability": "nonpayable",
+ *       "type": "constructor"
+ *     }
+ *   ],
+ *   bytecode: "0x608060405234801561001057600080fd5b50...",
+ *   args: ["MyToken", "MTK", parseUnits("1000000", 18)]
+ * };
+ *
+ * // Simple contract without constructor arguments
+ * const simpleContract: ContractProps = {
+ *   abi: contractAbi,
+ *   bytecode: "0x608060405234801561001057600080fd5b50..."
+ * };
+ *
+ * // Multi-signature wallet deployment
+ * const multisigContract: ContractProps = {
+ *   abi: multisigAbi,
+ *   bytecode: multisigBytecode,
+ *   args: [
+ *     ['0x1111...', '0x2222...', '0x3333...'], // owners
+ *     2 // required confirmations
+ *   ]
+ * };
+ * ```
+ */
 export interface ContractProps {
+    /** Contract ABI (Application Binary Interface) */
     readonly abi: Abi | any[];
+    /** Contract bytecode for deployment */
     readonly bytecode: Hex;
+    /** Constructor arguments (optional) */
     readonly args?: any[];
 }
+/**
+ * Properties for deploying one or multiple smart contracts
+ * @interface DeployContractProps
+ * @example
+ * ```typescript
+ * // Single contract deployment
+ * const deployProps: DeployContractProps = {
+ *   chainId: 1, // Ethereum mainnet
+ *   account: '0x742d35Cc6634C0532925a3b8D4C2CA1c1DfF0bE8',
+ *   contracts: [{
+ *     abi: erc20Abi,
+ *     bytecode: erc20Bytecode,
+ *     args: ["MyToken", "MTK", parseUnits("1000000", 18)]
+ *   }]
+ * };
+ *
+ * // Multiple contract deployment (factory pattern)
+ * const factoryDeployProps: DeployContractProps = {
+ *   chainId: 137, // Polygon
+ *   account: deployerAddress,
+ *   contracts: [
+ *     {
+ *       abi: factoryAbi,
+ *       bytecode: factoryBytecode,
+ *       args: [feeRecipient, defaultFee]
+ *     },
+ *     {
+ *       abi: implementationAbi,
+ *       bytecode: implementationBytecode,
+ *       args: []
+ *     }
+ *   ]
+ * };
+ *
+ * // DeFi protocol deployment
+ * const defiProtocolDeploy: DeployContractProps = {
+ *   chainId: 42161, // Arbitrum
+ *   account: protocolDeployer,
+ *   contracts: [
+ *     {
+ *       abi: vaultAbi,
+ *       bytecode: vaultBytecode,
+ *       args: [underlyingToken, "Yield Vault", "YV"]
+ *     },
+ *     {
+ *       abi: strategyAbi,
+ *       bytecode: strategyBytecode,
+ *       args: [vaultAddress, farmingPoolAddress]
+ *     },
+ *     {
+ *       abi: governanceAbi,
+ *       bytecode: governanceBytecode,
+ *       args: [governanceToken, votingDelay, votingPeriod]
+ *     }
+ *   ]
+ * };
+ *
+ * // Usage in adapter function
+ * async function deployContracts(deployProps: DeployContractProps) {
+ *   const deployedAddresses = await options.evm.deployContracts(deployProps);
+ *
+ *   deployedAddresses.forEach((address, index) => {
+ *     console.log(`Contract ${index + 1} deployed at: ${address}`);
+ *   });
+ *
+ *   return deployedAddresses;
+ * }
+ *
+ * // Contract verification helper
+ * function prepareContractVerification(
+ *   deployProps: DeployContractProps,
+ *   deployedAddresses: Address[]
+ * ) {
+ *   return deployProps.contracts.map((contract, index) => ({
+ *     address: deployedAddresses[index],
+ *     contractName: `Contract${index + 1}`,
+ *     sourceCode: getSourceCodeFromBytecode(contract.bytecode),
+ *     abi: JSON.stringify(contract.abi),
+ *     constructorArgs: contract.args ? encodeAbiParameters(
+ *       getConstructorInputs(contract.abi),
+ *       contract.args
+ *     ) : undefined
+ *   }));
+ * }
+ * ```
+ */
 export interface DeployContractProps {
+    /** Chain ID where contracts will be deployed */
     readonly chainId: number;
+    /** Account address that will deploy the contracts */
     readonly account: Address;
+    /** Array of contracts to deploy */
     readonly contracts: ContractProps[];
 }

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

@@ -1,14 +1,100 @@
 import { Address, PublicClient } from 'viem';
 import { TransactionParams } from '../types';
+/**
+ * Properties for checking and preparing token approval transactions
+ * @interface Props
+ */
 interface Props {
+    /** Approval parameters */
     readonly args: {
+        /** Account address that owns the tokens */
         readonly account: Address;
+        /** Token contract address */
         readonly target: Address;
+        /** Address that will be approved to spend tokens */
         readonly spender: Address;
+        /** Amount of tokens to approve */
         readonly amount: bigint;
     };
+    /** Ethereum provider for reading contract state */
     readonly provider: PublicClient;
+    /** Transaction array to append approval transactions to */
     readonly transactions: TransactionParams[];
 }
+/**
+ * Checks current token allowance and prepares approval transactions if needed
+ * @param props - The approval check parameters
+ * @description Handles special cases like USDT that require zero allowance before setting new approval
+ * @example
+ * ```typescript
+ * // Basic usage in a swap function
+ * async function prepareSwapTransactions() {
+ *   const transactions: TransactionParams[] = [];
+ *
+ *   await checkToApprove({
+ *     args: {
+ *       account: '0x742d35Cc6634C0532925a3b8D4C2CA1c1DfF0bE8',
+ *       target: '0xA0b86a33E6417e4681831442Ff7Bd6c25b5d9C7a', // USDC
+ *       spender: '0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D', // Uniswap V2 Router
+ *       amount: parseUnits('100', 6) // 100 USDC
+ *     },
+ *     provider: publicClient,
+ *     transactions
+ *   });
+ *
+ *   // Add swap transaction
+ *   transactions.push({
+ *     target: routerAddress,
+ *     data: swapCalldata
+ *   });
+ *
+ *   return transactions;
+ * }
+ *
+ * // Example with USDT (requires zero allowance)
+ * async function approveUSDT() {
+ *   const transactions: TransactionParams[] = [];
+ *
+ *   await checkToApprove({
+ *     args: {
+ *       account: userAddress,
+ *       target: '0xdAC17F958D2ee523a2206206994597C13D831ec7', // USDT
+ *       spender: spenderAddress,
+ *       amount: parseUnits('50', 6)
+ *     },
+ *     provider: ethereumProvider,
+ *     transactions
+ *   });
+ *
+ *   // Will generate two transactions for USDT:
+ *   // 1. approve(spender, 0) - reset to zero
+ *   // 2. approve(spender, amount) - set new allowance
+ * }
+ *
+ * // Integration with adapter function
+ * async function executeSwap(tokenIn: Address, tokenOut: Address, amountIn: bigint) {
+ *   const transactions: TransactionParams[] = [];
+ *
+ *   // Check and prepare approval if needed
+ *   if (tokenIn !== NATIVE_ADDRESS) {
+ *     await checkToApprove({
+ *       args: {
+ *         account: await options.evm.getAddress(),
+ *         target: tokenIn,
+ *         spender: DEX_ROUTER_ADDRESS,
+ *         amount: amountIn
+ *       },
+ *       provider: options.evm.getProvider(chainId),
+ *       transactions
+ *     });
+ *   }
+ *
+ *   // Add swap transaction
+ *   transactions.push(buildSwapTransaction(tokenIn, tokenOut, amountIn));
+ *
+ *   return await options.evm.sendTransactions({ transactions });
+ * }
+ * ```
+ */
 export declare function checkToApprove({ args, transactions, provider }: Props): Promise<void>;
 export {};

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

@@ -1,2 +1,83 @@
 import { EvmChain } from '../../constants';
+/**
+ * Converts an EVM chain name to its corresponding numeric chain ID
+ * @param chain - The EVM chain name
+ * @returns The numeric chain ID for the specified chain
+ * @throws {Error} When the chain name is not supported
+ * @example
+ * ```typescript
+ * // Get chain IDs for different networks
+ * const ethereumId = getChainFromName(Chain.ETHEREUM); // 1
+ * const polygonId = getChainFromName(Chain.POLYGON);   // 137
+ * const baseId = getChainFromName(Chain.BASE);         // 8453
+ *
+ * // Use in provider configuration
+ * function createProvider(chain: EvmChain) {
+ *   const chainId = getChainFromName(chain);
+ *   return new PublicClient({
+ *     chain: { id: chainId, name: chain },
+ *     transport: http(getRpcUrl(chainId))
+ *   });
+ * }
+ *
+ * // Validate and switch wallet chain
+ * async function switchWalletChain(targetChain: EvmChain) {
+ *   try {
+ *     const chainId = getChainFromName(targetChain);
+ *
+ *     await window.ethereum.request({
+ *       method: 'wallet_switchEthereumChain',
+ *       params: [{ chainId: `0x${chainId.toString(16)}` }]
+ *     });
+ *
+ *     console.log(`Switched to ${targetChain} (Chain ID: ${chainId})`);
+ *   } catch (error) {
+ *     console.error(`Failed to switch to ${targetChain}:`, error);
+ *   }
+ * }
+ *
+ * // Use in multi-chain adapter function
+ * async function getTokenBalance(chain: EvmChain, tokenAddress: string, userAddress: string) {
+ *   const chainId = getChainFromName(chain);
+ *   const provider = options.evm.getProvider(chainId);
+ *
+ *   return await provider.readContract({
+ *     address: tokenAddress,
+ *     abi: erc20Abi,
+ *     functionName: 'balanceOf',
+ *     args: [userAddress]
+ *   });
+ * }
+ *
+ * // Error handling example
+ * function safeGetChainId(chain: string): number | null {
+ *   try {
+ *     return getChainFromName(chain as EvmChain);
+ *   } catch (error) {
+ *     console.warn(`Unsupported chain: ${chain}`);
+ *     return null;
+ *   }
+ * }
+ *
+ * // Batch operations across multiple chains
+ * async function getMultiChainData(chains: EvmChain[]) {
+ *   const results = await Promise.allSettled(
+ *     chains.map(async (chain) => {
+ *       const chainId = getChainFromName(chain);
+ *       const provider = options.evm.getProvider(chainId);
+ *
+ *       return {
+ *         chain,
+ *         chainId,
+ *         blockNumber: await provider.getBlockNumber()
+ *       };
+ *     })
+ *   );
+ *
+ *   return results
+ *     .filter((result): result is PromiseFulfilledResult<any> => result.status === 'fulfilled')
+ *     .map(result => result.value);
+ * }
+ * ```
+ */
 export declare function getChainFromName(chain: EvmChain): number;

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

@@ -1 +1,115 @@
+/**
+ * Converts a numeric chain ID to its corresponding EVM chain name
+ * @param chainId - The numeric chain ID to convert
+ * @returns The chain name corresponding to the provided chain ID
+ * @throws {Error} When the chain ID is not supported
+ * @example
+ * ```typescript
+ * // Get chain names from IDs
+ * const ethereumName = getChainName(1);      // 'ethereum'
+ * const polygonName = getChainName(137);     // 'polygon'
+ * const baseName = getChainName(8453);       // 'base'
+ *
+ * // Handle wallet chain changes
+ * window.ethereum.on('chainChanged', (chainId: string) => {
+ *   try {
+ *     const decimalChainId = parseInt(chainId, 16);
+ *     const chainName = getChainName(decimalChainId);
+ *     console.log(`Switched to ${chainName} (Chain ID: ${decimalChainId})`);
+ *
+ *     // Update UI or reload data for new chain
+ *     updateUIForChain(chainName);
+ *   } catch (error) {
+ *     console.warn(`Unsupported chain ID: ${chainId}`);
+ *     showUnsupportedChainWarning();
+ *   }
+ * });
+ *
+ * // Validate user's current chain
+ * async function validateCurrentChain() {
+ *   const chainId = await window.ethereum.request({ method: 'eth_chainId' });
+ *   const decimalChainId = parseInt(chainId, 16);
+ *
+ *   try {
+ *     const chainName = getChainName(decimalChainId);
+ *     return { supported: true, chainName, chainId: decimalChainId };
+ *   } catch (error) {
+ *     return { supported: false, chainId: decimalChainId };
+ *   }
+ * }
+ *
+ * // Display user-friendly chain information
+ * function formatChainInfo(chainId: number) {
+ *   try {
+ *     const chainName = getChainName(chainId);
+ *     const displayNames = {
+ *       ethereum: 'Ethereum Mainnet',
+ *       polygon: 'Polygon',
+ *       bsc: 'Binance Smart Chain',
+ *       arbitrum: 'Arbitrum One',
+ *       base: 'Base',
+ *       optimism: 'Optimism'
+ *     };
+ *
+ *     return {
+ *       name: chainName,
+ *       displayName: displayNames[chainName] || chainName,
+ *       chainId
+ *     };
+ *   } catch (error) {
+ *     return {
+ *       name: 'unknown',
+ *       displayName: `Unknown Chain (${chainId})`,
+ *       chainId
+ *     };
+ *   }
+ * }
+ *
+ * // Use in multi-chain token tracking
+ * async function getTokenInfo(tokenAddress: string, chainId: number) {
+ *   try {
+ *     const chainName = getChainName(chainId);
+ *     const provider = options.evm.getProvider(chainId);
+ *
+ *     const [name, symbol, decimals] = await Promise.all([
+ *       provider.readContract({
+ *         address: tokenAddress,
+ *         abi: erc20Abi,
+ *         functionName: 'name'
+ *       }),
+ *       provider.readContract({
+ *         address: tokenAddress,
+ *         abi: erc20Abi,
+ *         functionName: 'symbol'
+ *       }),
+ *       provider.readContract({
+ *         address: tokenAddress,
+ *         abi: erc20Abi,
+ *         functionName: 'decimals'
+ *       })
+ *     ]);
+ *
+ *     return {
+ *       chain: chainName,
+ *       chainId,
+ *       address: tokenAddress,
+ *       name,
+ *       symbol,
+ *       decimals
+ *     };
+ *   } catch (error) {
+ *     throw new Error(`Failed to get token info on chain ${chainId}: ${error.message}`);
+ *   }
+ * }
+ *
+ * // Safe version that returns null instead of throwing
+ * function safeGetChainName(chainId: number): string | null {
+ *   try {
+ *     return getChainName(chainId);
+ *   } catch (error) {
+ *     return null;
+ *   }
+ * }
+ * ```
+ */
 export declare function getChainName(chainId: number): string;