MulticallLibraryV2

The MulticallLibraryV2 provides efficient batch execution of multiple function calls in a single transaction, optimized for gas efficiency and error handling.

Overview

MulticallLibraryV2 enables developers to execute multiple contract calls atomically, reducing gas costs and improving user experience by bundling operations together.

Library Interface

library MulticallLibraryV2 {
    struct Call {
        address target;
        bytes callData;
        uint256 gasLimit;
    }
    
    struct CallWithValue {
        address target;
        bytes callData;
        uint256 value;
        uint256 gasLimit;
    }
    
    struct Result {
        bool success;
        bytes returnData;
        uint256 gasUsed;
    }
    
    function multicall(Call[] memory calls) external returns (Result[] memory results);
    function multicallWithValue(CallWithValue[] memory calls) external payable returns (Result[] memory results);
    function tryMulticall(Call[] memory calls) external returns (Result[] memory results);
    function aggregate(Call[] memory calls) external returns (uint256 blockNumber, bytes[] memory returnData);
}

Core Functions

multicall

Executes multiple calls and reverts if any call fails.

function multicall(Call[] memory calls) external returns (Result[] memory results)

Parameters:

calls: Array of Call structs containing target addresses and call data

Returns:

results: Array of Result structs with success status, return data, and gas used

Example:

MulticallLibraryV2.Call[] memory calls = new MulticallLibraryV2.Call[](2);

calls[0] = MulticallLibraryV2.Call({
    target: tokenAddress,
    callData: abi.encodeWithSignature("transfer(address,uint256)", recipient, amount),
    gasLimit: 100000
});

calls[1] = MulticallLibraryV2.Call({
    target: stakingAddress,
    callData: abi.encodeWithSignature("stake(uint256)", amount),
    gasLimit: 150000
});

MulticallLibraryV2.Result[] memory results = MulticallLibraryV2.multicall(calls);

multicallWithValue

Executes multiple calls with ETH value, reverting if any call fails.

function multicallWithValue(CallWithValue[] memory calls) external payable returns (Result[] memory results)

Parameters:

calls: Array of CallWithValue structs including ETH value for each call

Returns:

results: Array of Result structs with execution details

Example:

MulticallLibraryV2.CallWithValue[] memory calls = new MulticallLibraryV2.CallWithValue[](2);

calls[0] = MulticallLibraryV2.CallWithValue({
    target: wethAddress,
    callData: abi.encodeWithSignature("deposit()"),
    value: 1 ether,
    gasLimit: 50000
});

calls[1] = MulticallLibraryV2.CallWithValue({
    target: dexAddress,
    callData: abi.encodeWithSignature("swap(address,address,uint256)", tokenA, tokenB, amount),
    value: 0,
    gasLimit: 200000
});

MulticallLibraryV2.Result[] memory results = MulticallLibraryV2.multicallWithValue{value: 1 ether}(calls);

tryMulticall

Executes multiple calls without reverting on individual call failures.

function tryMulticall(Call[] memory calls) external returns (Result[] memory results)

Parameters:

calls: Array of Call structs to execute

Returns:

results: Array of Result structs, including failed calls

Example:

MulticallLibraryV2.Call[] memory calls = new MulticallLibraryV2.Call[](3);

// Some calls might fail, but execution continues
calls[0] = MulticallLibraryV2.Call({
    target: tokenA,
    callData: abi.encodeWithSignature("transfer(address,uint256)", recipient, amount1),
    gasLimit: 100000
});

calls[1] = MulticallLibraryV2.Call({
    target: tokenB,
    callData: abi.encodeWithSignature("transfer(address,uint256)", recipient, amount2),
    gasLimit: 100000
});

calls[2] = MulticallLibraryV2.Call({
    target: invalidAddress, // This might fail
    callData: abi.encodeWithSignature("someFunction()"),
    gasLimit: 50000
});

MulticallLibraryV2.Result[] memory results = MulticallLibraryV2.tryMulticall(calls);

// Check individual results
for (uint i = 0; i < results.length; i++) {
    if (results[i].success) {
        // Handle successful call
    } else {
        // Handle failed call
        string memory error = abi.decode(results[i].returnData, (string));
    }
}

aggregate

Legacy function for basic multicall aggregation.

function aggregate(Call[] memory calls) external returns (uint256 blockNumber, bytes[] memory returnData)

Parameters:

calls: Array of Call structs to execute

Returns:

blockNumber: Current block number
returnData: Array of return data from each call

Advanced Usage Patterns

1. DeFi Batch Operations

contract DeFiBatchOperations {
    using MulticallLibraryV2 for MulticallLibraryV2.Call[];
    
    function swapAndStake(
        address tokenIn,
        address tokenOut,
        uint256 amountIn,
        address dexRouter,
        address stakingContract
    ) external {
        MulticallLibraryV2.Call[] memory calls = new MulticallLibraryV2.Call[](3);
        
        // 1. Approve token for DEX
        calls[0] = MulticallLibraryV2.Call({
            target: tokenIn,
            callData: abi.encodeWithSignature("approve(address,uint256)", dexRouter, amountIn),
            gasLimit: 50000
        });
        
        // 2. Swap tokens
        calls[1] = MulticallLibraryV2.Call({
            target: dexRouter,
            callData: abi.encodeWithSignature(
                "swapExactTokensForTokens(uint256,uint256,address[],address,uint256)",
                amountIn,
                0, // Accept any amount of tokens out
                getPath(tokenIn, tokenOut),
                address(this),
                block.timestamp + 300
            ),
            gasLimit: 200000
        });
        
        // 3. Stake received tokens
        calls[2] = MulticallLibraryV2.Call({
            target: stakingContract,
            callData: abi.encodeWithSignature("stakeAll()"),
            gasLimit: 150000
        });
        
        MulticallLibraryV2.Result[] memory results = MulticallLibraryV2.multicall(calls);
        
        // Verify all operations succeeded
        for (uint i = 0; i < results.length; i++) {
            require(results[i].success, "Batch operation failed");
        }
    }
}

2. NFT Batch Minting

contract NFTBatchMinter {
    function batchMint(
        address nftContract,
        address[] memory recipients,
        uint256[] memory tokenIds
    ) external {
        require(recipients.length == tokenIds.length, "Array length mismatch");
        
        MulticallLibraryV2.Call[] memory calls = new MulticallLibraryV2.Call[](recipients.length);
        
        for (uint i = 0; i < recipients.length; i++) {
            calls[i] = MulticallLibraryV2.Call({
                target: nftContract,
                callData: abi.encodeWithSignature(
                    "mint(address,uint256)",
                    recipients[i],
                    tokenIds[i]
                ),
                gasLimit: 100000
            });
        }
        
        MulticallLibraryV2.Result[] memory results = MulticallLibraryV2.multicall(calls);
        
        uint256 successCount = 0;
        for (uint i = 0; i < results.length; i++) {
            if (results[i].success) {
                successCount++;
            }
        }
        
        emit BatchMintCompleted(successCount, recipients.length);
    }
}

3. Cross-Chain Batch Operations

contract CrossChainBatchOps {
    IIXFIGateway public gateway;
    
    function batchCrossChainCalls(
        string[] memory destinationChains,
        address[] memory targetContracts,
        bytes[] memory payloads
    ) external {
        require(
            destinationChains.length == targetContracts.length &&
            targetContracts.length == payloads.length,
            "Array length mismatch"
        );
        
        MulticallLibraryV2.Call[] memory calls = new MulticallLibraryV2.Call[](destinationChains.length);
        
        for (uint i = 0; i < destinationChains.length; i++) {
            calls[i] = MulticallLibraryV2.Call({
                target: address(gateway),
                callData: abi.encodeWithSignature(
                    "callContract(string,string,bytes)",
                    destinationChains[i],
                    Strings.toHexString(uint160(targetContracts[i]), 20),
                    payloads[i]
                ),
                gasLimit: 200000
            });
        }
        
        MulticallLibraryV2.Result[] memory results = MulticallLibraryV2.tryMulticall(calls);
        
        emit BatchCrossChainCompleted(results);
    }
}

Gas Optimization Features

Dynamic Gas Limit Adjustment

library GasOptimizedMulticall {
    function optimizedMulticall(
        MulticallLibraryV2.Call[] memory calls,
        uint256 baseGasPerCall
    ) external returns (MulticallLibraryV2.Result[] memory results) {
        results = new MulticallLibraryV2.Result[](calls.length);
        
        for (uint256 i = 0; i < calls.length; i++) {
            uint256 gasStart = gasleft();
            
            // Adjust gas limit based on remaining gas
            uint256 adjustedGasLimit = calls[i].gasLimit;
            if (gasStart < calls[i].gasLimit + baseGasPerCall) {
                adjustedGasLimit = gasStart - baseGasPerCall;
            }
            
            (bool success, bytes memory returnData) = calls[i].target.call{
                gas: adjustedGasLimit
            }(calls[i].callData);
            
            uint256 gasUsed = gasStart - gasleft();
            
            results[i] = MulticallLibraryV2.Result({
                success: success,
                returnData: returnData,
                gasUsed: gasUsed
            });
            
            if (!success && calls[i].gasLimit == adjustedGasLimit) {
                // If call failed and we used full gas limit, revert
                revert("Multicall failed");
            }
        }
        
        return results;
    }
}

Gas Estimation

contract MulticallGasEstimator {
    function estimateMulticallGas(
        MulticallLibraryV2.Call[] memory calls
    ) external returns (uint256[] memory gasEstimates) {
        gasEstimates = new uint256[](calls.length);
        
        for (uint256 i = 0; i < calls.length; i++) {
            try this.estimateSingleCall(calls[i]) returns (uint256 estimate) {
                gasEstimates[i] = estimate;
            } catch {
                gasEstimates[i] = calls[i].gasLimit; // Fallback to provided limit
            }
        }
        
        return gasEstimates;
    }
    
    function estimateSingleCall(
        MulticallLibraryV2.Call memory call
    ) external returns (uint256) {
        return ITargetContract(call.target).estimateGas(call.callData);
    }
}

Error Handling

Custom Error Types

library MulticallErrors {
    error CallFailed(uint256 callIndex, address target, bytes callData, bytes reason);
    error InsufficientGas(uint256 callIndex, uint256 required, uint256 available);
    error InvalidCallData(uint256 callIndex, bytes callData);
    error TargetNotContract(uint256 callIndex, address target);
}

Enhanced Error Reporting

contract EnhancedMulticall {
    using MulticallLibraryV2 for MulticallLibraryV2.Call[];
    
    function safeMulticall(
        MulticallLibraryV2.Call[] memory calls
    ) external returns (MulticallLibraryV2.Result[] memory results) {
        results = new MulticallLibraryV2.Result[](calls.length);
        
        for (uint256 i = 0; i < calls.length; i++) {
            // Validate target is a contract
            if (calls[i].target.code.length == 0) {
                revert MulticallErrors.TargetNotContract(i, calls[i].target);
            }
            
            // Check gas availability
            if (gasleft() < calls[i].gasLimit + 5000) {
                revert MulticallErrors.InsufficientGas(i, calls[i].gasLimit, gasleft());
            }
            
            uint256 gasStart = gasleft();
            
            (bool success, bytes memory returnData) = calls[i].target.call{
                gas: calls[i].gasLimit
            }(calls[i].callData);
            
            uint256 gasUsed = gasStart - gasleft();
            
            results[i] = MulticallLibraryV2.Result({
                success: success,
                returnData: returnData,
                gasUsed: gasUsed
            });
            
            if (!success) {
                revert MulticallErrors.CallFailed(i, calls[i].target, calls[i].callData, returnData);
            }
        }
        
        return results;
    }
}

Security Considerations

Reentrancy Protection

contract ReentrancyProtectedMulticall {
    bool private locked;
    
    modifier nonReentrant() {
        require(!locked, "Reentrant call");
        locked = true;
        _;
        locked = false;
    }
    
    function secureMulticall(
        MulticallLibraryV2.Call[] memory calls
    ) external nonReentrant returns (MulticallLibraryV2.Result[] memory) {
        return MulticallLibraryV2.multicall(calls);
    }
}

Access Control

contract AccessControlledMulticall {
    mapping(address => bool) public authorized;
    mapping(address => bool) public allowedTargets;
    
    modifier onlyAuthorized() {
        require(authorized[msg.sender], "Not authorized");
        _;
    }
    
    function authorizedMulticall(
        MulticallLibraryV2.Call[] memory calls
    ) external onlyAuthorized returns (MulticallLibraryV2.Result[] memory) {
        // Validate all targets are allowed
        for (uint256 i = 0; i < calls.length; i++) {
            require(allowedTargets[calls[i].target], "Target not allowed");
        }
        
        return MulticallLibraryV2.multicall(calls);
    }
}

Integration Examples

Frontend JavaScript

class MulticallManager {
    constructor(contractAddress, provider) {
        this.contract = new ethers.Contract(contractAddress, multicallABI, provider);
    }

    async prepareCalls(operations) {
        const calls = [];
        
        for (const op of operations) {
            const target = op.contract.address || op.contract.target;
            const callData = op.contract.interface.encodeFunctionData(op.method, op.args);
            
            calls.push({
                target: target,
                callData: callData,
                gasLimit: op.gasLimit || 200000
            });
        }
        
        return calls;
    }

    async executeMulticall(calls, options = {}) {
        try {
            const tx = await this.contract.multicall(calls, {
                gasLimit: options.gasLimit || 1000000,
                gasPrice: options.gasPrice
            });
            
            const receipt = await tx.wait();
            return this.parseResults(receipt);
        } catch (error) {
            console.error('Multicall failed:', error);
            throw error;
        }
    }

    async estimateGas(calls) {
        try {
            return await this.contract.estimateGas.multicall(calls);
        } catch (error) {
            console.error('Gas estimation failed:', error);
            return BigInt(1000000); // Fallback
        }
    }

    parseResults(receipt) {
        const results = [];
        
        // Parse MulticallExecuted events
        const events = receipt.logs.filter(log => 
            log.topics[0] === ethers.id("MulticallExecuted(uint256,bool,bytes)")
        );
        
        for (const event of events) {
            const decoded = ethers.AbiCoder.defaultAbiCoder().decode(
                ['uint256', 'bool', 'bytes'],
                event.data
            );
            
            results.push({
                callIndex: decoded[0],
                success: decoded[1],
                returnData: decoded[2]
            });
        }
        
        return results;
    }
}

React Hook

import { useState, useCallback } from 'react';
import { useContract, useSigner } from 'wagmi';

export function useMulticall(contractAddress) {
    const { data: signer } = useSigner();
    const [isLoading, setIsLoading] = useState(false);
    const [error, setError] = useState(null);

    const multicallContract = useContract({
        address: contractAddress,
        abi: multicallABI,
        signerOrProvider: signer
    });

    const executeBatch = useCallback(async (operations) => {
        if (!multicallContract) return;

        setIsLoading(true);
        setError(null);

        try {
            const manager = new MulticallManager(contractAddress, signer.provider);
            const calls = await manager.prepareCalls(operations);
            
            const gasEstimate = await manager.estimateGas(calls);
            const results = await manager.executeMulticall(calls, {
                gasLimit: gasEstimate * 110n / 100n // 10% buffer
            });

            return results;
        } catch (err) {
            setError(err.message);
            throw err;
        } finally {
            setIsLoading(false);
        }
    }, [multicallContract, contractAddress, signer]);

    return {
        executeBatch,
        isLoading,
        error
    };
}

Performance Metrics

Operation Type

Gas Savings

Execution Time

Max Batch Size

Token Transfers

60-80%

40-60% faster

50-100 calls

NFT Operations

50-70%

30-50% faster

20-50 calls

DeFi Interactions

40-60%

50-70% faster

10-30 calls

Cross-Chain Calls

30-50%

60-80% faster

5-20 calls

Best Practices

1. Gas Optimization

Set appropriate gas limits for each call
Use tryMulticall for non-critical operations
Batch similar operations together
Monitor gas usage patterns

2. Error Handling

Always check individual call results
Implement proper fallback mechanisms
Use descriptive error messages
Log failed operations for debugging

3. Security

Validate all target addresses
Implement access controls where needed
Use reentrancy protection
Audit multicall implementations

4. User Experience

Provide clear transaction previews
Show individual operation status
Implement retry mechanisms
Optimize for mobile gas limits

Resources

PreviousCrossChainAggregator NextQuoteLibrary

Last updated 5 months ago

hashtagOverview

hashtagLibrary Interface

hashtagCore Functions

hashtagmulticall

hashtagmulticallWithValue

hashtagtryMulticall

hashtagaggregate

hashtagAdvanced Usage Patterns

hashtag1. DeFi Batch Operations

hashtag2. NFT Batch Minting

hashtag3. Cross-Chain Batch Operations

hashtagGas Optimization Features

hashtagDynamic Gas Limit Adjustment

hashtagGas Estimation

hashtagError Handling

hashtagCustom Error Types

hashtagEnhanced Error Reporting

hashtagSecurity Considerations

hashtagReentrancy Protection

hashtagAccess Control

hashtagIntegration Examples

hashtagFrontend JavaScript

hashtagReact Hook

hashtagPerformance Metrics

hashtagBest Practices

hashtag1. Gas Optimization

hashtag2. Error Handling

hashtag3. Security

hashtag4. User Experience

hashtagResources

Overview

Library Interface

Core Functions

multicall

multicallWithValue

tryMulticall

aggregate

Advanced Usage Patterns

1. DeFi Batch Operations

2. NFT Batch Minting

3. Cross-Chain Batch Operations

Gas Optimization Features

Dynamic Gas Limit Adjustment

Gas Estimation

Error Handling

Custom Error Types

Enhanced Error Reporting

Security Considerations

Reentrancy Protection

Access Control

Integration Examples

Frontend JavaScript

React Hook

Performance Metrics

Best Practices

1. Gas Optimization

2. Error Handling

3. Security

4. User Experience

Resources