@deserialize/multi-vm-wallet 1.2.21 → 1.2.22

package/utils/evm/transaction.utils.ts

@@ -0,0 +1,824 @@
+import {
+    type PublicClient,
+    type Address,
+    type Hex,
+    isHex,
+    parseAbi,
+    decodeFunctionData,
+    getContract,
+} from 'viem';
+
+// ============================================================================
+// Types & Constants
+// ============================================================================
+
+/**
+ * Enum representing different transaction types
+ */
+export enum TransactionType {
+    // Token operations
+    tokenMethodApprove = 'approve',
+    tokenMethodSetApprovalForAll = 'setApprovalForAll',
+    tokenMethodTransfer = 'transfer',
+    tokenMethodTransferFrom = 'transferFrom',
+    tokenMethodIncreaseAllowance = 'increaseAllowance',
+    tokenMethodSafeTransferFrom = 'safeTransferFrom',
+
+    // Contract operations
+    contractInteraction = 'contractInteraction',
+    deployContract = 'deployContract',
+
+    // Simple transfers
+    simpleSend = 'simpleSend',
+
+    // Special operations
+    cancel = 'cancel',
+    retry = 'retry',
+    swap = 'swap',
+}
+
+/**
+ * Enum representing asset types
+ */
+export enum AssetType {
+    native = 'NATIVE',
+    token = 'TOKEN',
+    NFT = 'NFT',
+    unknown = 'UNKNOWN',
+}
+
+/**
+ * Enum representing token standards
+ */
+export enum TokenStandard {
+    ERC20 = 'ERC20',
+    ERC721 = 'ERC721',
+    ERC1155 = 'ERC1155',
+    none = 'none',
+}
+
+/**
+ * Transaction parameters interface
+ */
+export interface TransactionParams {
+    from: Address;
+    to?: Address;
+    value?: bigint | string;
+    data?: Hex;
+    gas?: bigint | string;
+    gasPrice?: bigint | string;
+    maxFeePerGas?: bigint | string;
+    maxPriorityFeePerGas?: bigint | string;
+    nonce?: number;
+}
+
+/**
+ * Transaction metadata interface
+ */
+export interface TransactionMeta {
+    type?: TransactionType;
+    txParams: TransactionParams;
+    dappSuggestedGasFees?: {
+        gasPrice?: bigint | string;
+        maxFeePerGas?: bigint | string;
+        maxPriorityFeePerGas?: bigint | string;
+    };
+}
+
+/**
+ * Result of transaction type inference
+ */
+export interface InferTransactionTypeResult {
+    type: TransactionType;
+    contractCode: Hex | null;
+}
+
+/**
+ * Parsed approval transaction data
+ */
+export interface ParsedApprovalData {
+    amountOrTokenId?: bigint;
+    isApproveAll?: boolean;
+    isRevokeAll?: boolean;
+    name: string;
+    tokenAddress?: Address;
+    spender?: Address;
+}
+
+/**
+ * Token details interface
+ */
+export interface TokenDetails {
+    decimals?: number;
+    balance?: bigint;
+    symbol?: string;
+    standard?: TokenStandard;
+}
+
+// ============================================================================
+// ABIs
+// ============================================================================
+
+/**
+ * ERC20 token ABI (essential methods only)
+ */
+const ERC20_ABI = parseAbi([
+    'function approve(address spender, uint256 amount) returns (bool)',
+    'function transfer(address to, uint256 amount) returns (bool)',
+    'function transferFrom(address from, address to, uint256 amount) returns (bool)',
+    'function increaseAllowance(address spender, uint256 addedValue) returns (bool)',
+    'function decreaseAllowance(address spender, uint256 subtractedValue) returns (bool)',
+    'function decimals() view returns (uint8)',
+    'function symbol() view returns (string)',
+    'function balanceOf(address account) view returns (uint256)',
+]);
+
+/**
+ * ERC721 token ABI (essential methods only)
+ */
+const ERC721_ABI = parseAbi([
+    'function approve(address to, uint256 tokenId)',
+    'function setApprovalForAll(address operator, bool approved)',
+    'function transferFrom(address from, address to, uint256 tokenId)',
+    'function safeTransferFrom(address from, address to, uint256 tokenId)',
+    'function safeTransferFrom(address from, address to, uint256 tokenId, bytes data)',
+    'function supportsInterface(bytes4 interfaceId) view returns (bool)',
+]);
+
+/**
+ * ERC1155 token ABI (essential methods only)
+ */
+const ERC1155_ABI = parseAbi([
+    'function setApprovalForAll(address operator, bool approved)',
+    'function safeTransferFrom(address from, address to, uint256 id, uint256 amount, bytes data)',
+    'function safeBatchTransferFrom(address from, address to, uint256[] ids, uint256[] amounts, bytes data)',
+    'function supportsInterface(bytes4 interfaceId) view returns (bool)',
+]);
+
+/**
+ * USDC (Fiat Token V2) specific methods
+ */
+const FIAT_TOKEN_V2_ABI = parseAbi([
+    'function increaseAllowance(address spender, uint256 increment) returns (bool)',
+    'function decreaseAllowance(address spender, uint256 decrement) returns (bool)',
+]);
+
+/**
+ * Permit2 contract ABI
+ */
+const PERMIT2_ABI = parseAbi([
+    'function approve(address token, address spender, uint160 amount, uint48 expiration)',
+]);
+
+/**
+ * List of transaction types that can be inferred from transaction data
+ */
+const INFERRABLE_TRANSACTION_TYPES: TransactionType[] = [
+    TransactionType.tokenMethodApprove,
+    TransactionType.tokenMethodSetApprovalForAll,
+    TransactionType.tokenMethodTransfer,
+    TransactionType.tokenMethodTransferFrom,
+    TransactionType.tokenMethodIncreaseAllowance,
+    TransactionType.contractInteraction,
+    TransactionType.simpleSend,
+];
+
+/**
+ * List of approval method names
+ */
+const APPROVAL_METHOD_NAMES = [
+    'approve',
+    'setApprovalForAll',
+    'increaseAllowance',
+    'decreaseAllowance',
+];
+
+/**
+ * Interface IDs for token standards (EIP-165)
+ */
+const INTERFACE_IDS = {
+    ERC721: '0x80ac58cd',
+    ERC1155: '0xd9b67a26',
+    ERC165: '0x01ffc9a7',
+};
+
+// ============================================================================
+// Gas Fee Utilities
+// ============================================================================
+
+/**
+ * Determines if a transaction uses EIP-1559 gas fields
+ * 
+ * EIP-1559 transactions use maxFeePerGas and maxPriorityFeePerGas instead of gasPrice
+ * 
+ * @param transactionMeta - Transaction metadata to check
+ * @returns True if transaction uses valid EIP-1559 fields
+ * 
+ * @example
+ * ```typescript
+ * const isEIP1559 = isEIP1559Transaction({
+ *   txParams: {
+ *     maxFeePerGas: '0x59682f00',
+ *     maxPriorityFeePerGas: '0x3b9aca00'
+ *   }
+ * });
+ * ```
+ */
+export function isEIP1559Transaction(transactionMeta: TransactionMeta): boolean {
+    const { maxFeePerGas, maxPriorityFeePerGas } = transactionMeta.txParams;
+    return (
+        isHex(String(maxFeePerGas ?? '')) &&
+        isHex(String(maxPriorityFeePerGas ?? ''))
+    );
+}
+
+/**
+ * Determines if a transaction uses legacy gas fields (gasPrice)
+ * 
+ * Legacy transactions use gasPrice instead of EIP-1559 fields
+ * 
+ * @param transactionMeta - Transaction metadata to check
+ * @returns True if transaction uses valid legacy gas fields
+ * 
+ * @example
+ * ```typescript
+ * const isLegacy = isLegacyTransaction({
+ *   txParams: {
+ *     gasPrice: '0x3b9aca00'
+ *   }
+ * });
+ * ```
+ */
+export function isLegacyTransaction(transactionMeta: TransactionMeta): boolean {
+    const { maxFeePerGas, maxPriorityFeePerGas, gasPrice } = transactionMeta.txParams;
+    return (
+        typeof maxFeePerGas === 'undefined' &&
+        typeof maxPriorityFeePerGas === 'undefined' &&
+        (typeof gasPrice === 'undefined' || isHex(String(gasPrice)))
+    );
+}
+
+/**
+ * Checks if transaction gas fees match dApp suggested fees
+ * 
+ * Useful for determining if the user has modified the dApp's suggested gas fees
+ * 
+ * @param transactionMeta - Transaction metadata to check
+ * @returns True if txParams match dappSuggestedGasFees
+ * 
+ * @example
+ * ```typescript
+ * const isUnmodified = txParamsAreDappSuggested({
+ *   txParams: { gasPrice: '0x3b9aca00' },
+ *   dappSuggestedGasFees: { gasPrice: '0x3b9aca00' }
+ * });
+ * ```
+ */
+export function txParamsAreDappSuggested(transactionMeta: TransactionMeta): boolean {
+    const { gasPrice, maxPriorityFeePerGas, maxFeePerGas } = transactionMeta.txParams;
+    const suggested = transactionMeta.dappSuggestedGasFees;
+
+    if (!suggested) return false;
+
+    return Boolean(
+        (gasPrice && gasPrice === suggested.gasPrice) ||
+        (maxPriorityFeePerGas &&
+            maxFeePerGas &&
+            suggested.maxPriorityFeePerGas === maxPriorityFeePerGas &&
+            suggested.maxFeePerGas === maxFeePerGas)
+    );
+}
+
+// ============================================================================
+// Transaction Data Parsing
+// ============================================================================
+
+/**
+ * Attempts to decode transaction data using standard token ABIs
+ * 
+ * Tries to decode the data against ERC20, ERC721, ERC1155, USDC, and Permit2 ABIs
+ * 
+ * @param data - Encoded transaction data
+ * @returns Decoded function data or undefined if decoding fails
+ * 
+ * @example
+ * ```typescript
+ * const parsed = parseStandardTokenTransactionData('0xa9059cbb...');
+ * if (parsed) {
+ *   console.log('Function:', parsed.functionName);
+ *   console.log('Args:', parsed.args);
+ * }
+ * ```
+ */
+export function parseStandardTokenTransactionData(data: Hex) {
+    const abis = [
+        ERC20_ABI,
+        ERC721_ABI,
+        ERC1155_ABI,
+        FIAT_TOKEN_V2_ABI,
+        PERMIT2_ABI,
+    ];
+
+    for (const abi of abis) {
+        try {
+            return decodeFunctionData({ abi, data });
+        } catch {
+            // Continue to next ABI
+        }
+    }
+
+    return undefined;
+}
+
+/**
+ * Checks if transaction has meaningful data
+ * 
+ * @param transactionData - Transaction data field
+ * @returns True if data exists and is not empty
+ * 
+ * @example
+ * ```typescript
+ * hasTransactionData('0x') // false
+ * hasTransactionData('0xa9059cbb...') // true
+ * ```
+ */
+export function hasTransactionData(transactionData?: Hex): boolean {
+    return Boolean(
+        transactionData?.length && transactionData.toLowerCase() !== '0x'
+    );
+}
+
+/**
+ * Parses approval transaction data to extract relevant information
+ * 
+ * Supports:
+ * - ERC20: approve, increaseAllowance
+ * - ERC721/ERC1155: setApprovalForAll
+ * - Permit2: approve
+ * - USDC: increaseAllowance
+ * 
+ * @param data - Transaction data to parse
+ * @returns Parsed approval data or undefined if not an approval transaction
+ * 
+ * @example
+ * ```typescript
+ * const approval = parseApprovalTransactionData('0x095ea7b3...');
+ * if (approval) {
+ *   console.log('Spender:', approval.spender);
+ *   console.log('Amount:', approval.amountOrTokenId);
+ *   console.log('Is approval for all?', approval.isApproveAll);
+ * }
+ * ```
+ */
+export function parseApprovalTransactionData(data: Hex): ParsedApprovalData | undefined {
+    const decoded = parseStandardTokenTransactionData(data);
+
+    if (!decoded) return undefined;
+
+    const { functionName, args } = decoded;
+
+    if (!functionName || !APPROVAL_METHOD_NAMES.includes(functionName)) {
+        return undefined;
+    }
+
+    // Extract amount or token ID based on function
+    const rawAmountOrTokenId =
+        (args as any)?._value ?? // ERC-20 approve
+        (args as any)?.increment ?? // Fiat Token V2 increaseAllowance
+        (args as any)?.amount ?? // Permit2 approve
+        (args as any)?.addedValue; // ERC-20 increaseAllowance
+
+    const amountOrTokenId = rawAmountOrTokenId
+        ? BigInt(rawAmountOrTokenId.toString())
+        : undefined;
+
+    // Extract spender address
+    const spender =
+        (args as any)?.spender ??
+        (args as any)?._spender ??
+        (args as any)?.[0];
+
+    // Check if it's an approval for all (ERC721/ERC1155)
+    const isApproveAll =
+        functionName === 'setApprovalForAll' && (args as any)?._approved === true;
+    const isRevokeAll =
+        functionName === 'setApprovalForAll' && (args as any)?._approved === false;
+
+    // Extract token address for Permit2
+    const tokenAddress =
+        functionName === 'approve' ? (args as any)?.token : undefined;
+
+    return {
+        amountOrTokenId,
+        isApproveAll,
+        isRevokeAll,
+        name: functionName,
+        tokenAddress,
+        spender,
+    };
+}
+
+// ============================================================================
+// Contract Utilities
+// ============================================================================
+
+/**
+ * Reads an address to determine if it's a contract
+ * 
+ * @param client - Viem public client
+ * @param address - Address to check
+ * @returns Contract code and whether it's a contract address
+ * 
+ * @example
+ * ```typescript
+ * const { isContractAddress, contractCode } = await readAddressAsContract(
+ *   client,
+ *   '0x...'
+ * );
+ * ```
+ */
+export async function readAddressAsContract(
+    client: PublicClient,
+    address: Address
+): Promise<{ isContractAddress: boolean; contractCode: Hex | null }> {
+    try {
+        const code = await client.getCode({ address });
+        const isContract = Boolean(code && code !== '0x' && code !== '0x0');
+
+        return {
+            isContractAddress: isContract,
+            contractCode: code || null,
+        };
+    } catch (error) {
+        console.error('Error reading contract code:', error);
+        return {
+            isContractAddress: false,
+            contractCode: null,
+        };
+    }
+}
+
+/**
+ * Determines the token standard by checking EIP-165 interface support
+ * 
+ * @param client - Viem public client
+ * @param address - Token contract address
+ * @returns Token standard (ERC721, ERC1155, ERC20, or none)
+ * 
+ * @example
+ * ```typescript
+ * const standard = await getTokenStandard(client, '0x...');
+ * console.log('Token standard:', standard); // 'ERC721'
+ * ```
+ */
+export async function getTokenStandard(
+    client: PublicClient,
+    address: Address
+): Promise<TokenStandard> {
+    // Try ERC165 supportsInterface for ERC721/ERC1155
+    try {
+        const contract = getContract({
+            address,
+            abi: parseAbi(['function supportsInterface(bytes4) view returns (bool)']),
+            client,
+        });
+
+        // Check ERC721
+        const isERC721 = await contract.read.supportsInterface([INTERFACE_IDS.ERC721 as Hex]);
+        if (isERC721) return TokenStandard.ERC721;
+
+        // Check ERC1155
+        const isERC1155 = await contract.read.supportsInterface([INTERFACE_IDS.ERC1155 as Hex]);
+        if (isERC1155) return TokenStandard.ERC1155;
+    } catch {
+        // Not ERC721/ERC1155, try ERC20
+    }
+
+    // Try ERC20 by checking for decimals function
+    try {
+        const contract = getContract({
+            address,
+            abi: parseAbi(['function decimals() view returns (uint8)']),
+            client,
+        });
+
+        await contract.read.decimals();
+        return TokenStandard.ERC20;
+    } catch {
+        // Not a recognized token standard
+    }
+
+    return TokenStandard.none;
+}
+
+/**
+ * Gets token details including standard, decimals, symbol, and balance
+ * 
+ * @param client - Viem public client
+ * @param address - Token contract address
+ * @param holderAddress - Optional address to check balance for
+ * @returns Token details
+ * 
+ * @example
+ * ```typescript
+ * const details = await getTokenStandardAndDetails(
+ *   client,
+ *   '0x...', // token address
+ *   '0x...'  // holder address
+ * );
+ * console.log(details.symbol, details.decimals, details.balance);
+ * ```
+ */
+export async function getTokenStandardAndDetails(
+    client: PublicClient,
+    address: Address,
+    holderAddress?: Address
+): Promise<TokenDetails> {
+    const standard = await getTokenStandard(client, address);
+
+    if (standard === TokenStandard.none) {
+        return { standard };
+    }
+
+    const details: TokenDetails = { standard };
+
+    // Get ERC20 details
+    if (standard === TokenStandard.ERC20) {
+        try {
+            const contract = getContract({
+                address,
+                abi: ERC20_ABI,
+                client,
+            });
+
+            const [decimals, symbol, balance] = await Promise.all([
+                contract.read.decimals().catch(() => undefined),
+                contract.read.symbol().catch(() => undefined),
+                holderAddress
+                    ? contract.read.balanceOf([holderAddress]).catch(() => undefined)
+                    : Promise.resolve(undefined),
+            ]);
+
+            details.decimals = decimals;
+            details.symbol = symbol;
+            details.balance = balance;
+        } catch (error) {
+            console.error('Error fetching ERC20 details:', error);
+        }
+    }
+
+    return details;
+}
+
+// ============================================================================
+// Transaction Type Determination
+// ============================================================================
+
+/**
+ * Determines the type of transaction by analyzing its parameters
+ * 
+ * This function analyzes the transaction to determine if it's:
+ * - A contract deployment
+ * - A token transfer/approval
+ * - A contract interaction
+ * - A simple ETH transfer
+ * 
+ * @param txParams - Transaction parameters
+ * @param client - Viem public client
+ * @returns Transaction type and contract code
+ * 
+ * @example
+ * ```typescript
+ * const result = await determineTransactionType(
+ *   {
+ *     from: '0x...',
+ *     to: '0x...',
+ *     data: '0xa9059cbb...'
+ *   },
+ *   client
+ * );
+ * console.log('Transaction type:', result.type);
+ * ```
+ */
+export async function determineTransactionType(
+    txParams: TransactionParams,
+    client: PublicClient
+): Promise<InferTransactionTypeResult> {
+    const { data, to, value } = txParams;
+
+    // Contract deployment (no 'to' address)
+    if (data && !to) {
+        return {
+            type: TransactionType.deployContract,
+            contractCode: null,
+        };
+    }
+
+    // Check if 'to' is a contract
+    if (to) {
+        const { contractCode, isContractAddress } = await readAddressAsContract(client, to);
+
+        if (isContractAddress) {
+            const hasValue = value && BigInt(value) !== 0n;
+
+            // Try to parse the transaction data
+            let functionName = '';
+            try {
+                const parsed = data ? parseStandardTokenTransactionData(data) : undefined;
+                if (parsed?.functionName) {
+                    functionName = parsed.functionName;
+                }
+            } catch (error) {
+                console.debug('Failed to parse transaction data:', error);
+            }
+
+            // Check if it's a known token method
+            const tokenMethodName = [
+                TransactionType.tokenMethodApprove,
+                TransactionType.tokenMethodSetApprovalForAll,
+                TransactionType.tokenMethodTransfer,
+                TransactionType.tokenMethodTransferFrom,
+                TransactionType.tokenMethodIncreaseAllowance,
+                TransactionType.tokenMethodSafeTransferFrom,
+            ].find((methodName) =>
+                methodName.toLowerCase() === functionName.toLowerCase()
+            );
+
+            // Return token method if found and no ETH value
+            if (data && tokenMethodName && !hasValue) {
+                return {
+                    type: tokenMethodName,
+                    contractCode,
+                };
+            }
+
+            // Otherwise it's a general contract interaction
+            return {
+                type: TransactionType.contractInteraction,
+                contractCode,
+            };
+        }
+    }
+
+    // Simple ETH transfer
+    return {
+        type: TransactionType.simpleSend,
+        contractCode: null,
+    };
+}
+
+/**
+ * Determines the asset type and token standard for a transaction
+ * 
+ * This function analyzes the transaction to determine what type of asset
+ * is being transferred and what standard it follows (if applicable)
+ * 
+ * @param txMeta - Transaction metadata
+ * @param client - Viem public client
+ * @returns Asset type and token standard
+ * 
+ * @example
+ * ```typescript
+ * const { assetType, tokenStandard } = await determineTransactionAssetType(
+ *   txMeta,
+ *   client
+ * );
+ * 
+ * if (assetType === AssetType.token) {
+ *   console.log('ERC20 token transfer');
+ * }
+ * ```
+ */
+export async function determineTransactionAssetType(
+    txMeta: TransactionMeta,
+    client: PublicClient
+): Promise<{
+    assetType: AssetType;
+    tokenStandard: TokenStandard;
+}> {
+    // Use existing type if it's already inferrable
+    let inferrableType = txMeta.type;
+
+    if (txMeta.type && !INFERRABLE_TRANSACTION_TYPES.includes(txMeta.type)) {
+        // Get an inferrable type for special transactions (like swaps)
+        const result = await determineTransactionType(txMeta.txParams, client);
+        inferrableType = result.type;
+    }
+
+    // Check if it's a token method
+    const isTokenMethod = [
+        TransactionType.tokenMethodApprove,
+        TransactionType.tokenMethodSetApprovalForAll,
+        TransactionType.tokenMethodTransfer,
+        TransactionType.tokenMethodTransferFrom,
+        TransactionType.tokenMethodIncreaseAllowance,
+    ].includes(inferrableType as TransactionType);
+
+    // Try to get token standard for token methods or contract interactions
+    if (isTokenMethod || inferrableType === TransactionType.contractInteraction) {
+        if (txMeta.txParams.to) {
+            try {
+                const details = await getTokenStandardAndDetails(
+                    client,
+                    txMeta.txParams.to
+                );
+
+                if (details.standard && details.standard !== TokenStandard.none) {
+                    return {
+                        assetType:
+                            details.standard === TokenStandard.ERC20
+                                ? AssetType.token
+                                : AssetType.NFT,
+                        tokenStandard: details.standard,
+                    };
+                }
+            } catch {
+                // Failed to get token details, continue
+            }
+        }
+    }
+
+    // Contract interaction with unknown asset type
+    if (inferrableType === TransactionType.contractInteraction) {
+        return {
+            assetType: AssetType.unknown,
+            tokenStandard: TokenStandard.none,
+        };
+    }
+
+    // Native ETH transfer
+    return {
+        assetType: AssetType.native,
+        tokenStandard: TokenStandard.none,
+    };
+}
+
+// ============================================================================
+// Typed Data Parsing
+// ============================================================================
+
+/**
+ * Regex to extract large number values from typed data messages
+ * Handles cases where JSON.parse would lose precision
+ */
+const REGEX_MESSAGE_VALUE_LARGE = /"message"\s*:\s*\{[^}]*"value"\s*:\s*(\d{15,})/u;
+
+/**
+ * Extracts large number value from a stringified message
+ * 
+ * @param dataToParse - Stringified data to parse
+ * @returns Extracted large number or undefined
+ */
+function extractLargeMessageValue(dataToParse: string): string | undefined {
+    if (typeof dataToParse !== 'string') {
+        return undefined;
+    }
+    return dataToParse.match(REGEX_MESSAGE_VALUE_LARGE)?.[1];
+}
+
+/**
+ * Parses typed data message while preserving large number precision
+ * 
+ * JSON.parse can lose precision for numbers > Number.MAX_SAFE_INTEGER
+ * This function extracts large values and preserves them as strings
+ * 
+ * @param dataToParse - Data to parse (object or string)
+ * @returns Parsed data with preserved precision
+ * 
+ * @example
+ * ```typescript
+ * const parsed = parseTypedDataMessage(signatureRequest.data);
+ * console.log(parsed.message.value); // Preserved as string
+ * ```
+ */
+export function parseTypedDataMessage(
+    dataToParse: object | string | number | boolean
+): any {
+    const result =
+        typeof dataToParse === 'object'
+            ? dataToParse
+            : JSON.parse(String(dataToParse));
+
+    const messageValue = extractLargeMessageValue(String(dataToParse));
+
+    if (result.message?.value) {
+        result.message.value = messageValue || String(result.message.value);
+    }
+
+    return result;
+}
+
+// ============================================================================
+// Helper Utilities
+// ============================================================================
+
+/**
+ * Case-insensitive string comparison
+ * 
+ * @param str1 - First string
+ * @param str2 - Second string
+ * @returns True if strings are equal (case-insensitive)
+ */
+export function isEqualCaseInsensitive(str1: string, str2: string): boolean {
+    return str1.toLowerCase() === str2.toLowerCase();
+}