Multicall

This is the package for high-weight optimized calls to blockchain nodes

Installation

Node

npm install @1inch/multicall

Yarn

yarn add @1inch/multicall

Onchain addresses

• Ethereum mainnet: 0x8d035edd8e09c3283463dade67cc0d49d6868063
• BSC mainnet: 0x804708de7af615085203fa2b18eae59c5738e2a9
• Polygon mainnet: 0x0196e8a9455a90d392b46df8560c867e7df40b34
• Arbitrum One: 0x11DEE30E710B8d4a8630392781Cc3c0046365d4c
• Gnosis Chain: 0xE295aD71242373C37C5FdA7B57F26f9eA1088AFe
• Avalanche: 0xC4A8B7e29E3C8ec560cd4945c1cF3461a85a148d
• Fantom: 0xA31bB36c5164B165f9c36955EA4CcBaB42B3B28E
• Optimism: 0xE295aD71242373C37C5FdA7B57F26f9eA1088AFe
• Base: 0x138ce40d675f9a23e4d6127a8600308cf7a93381
• Aurora: 0xa0446d8804611944f1b527ecd37d7dcbe442caba
• zkSync Era: 0xae1f66df155c611c15a23f31acf5a9bf1b87907e
• Klaytn: 0xa31bb36c5164b165f9c36955ea4ccbab42b3b28e

Motivation

The MultiCall contract is designed to execute multiple view calls at one time.
For example, you have a list of tokens, and you need to get balances for all the items on that list.

Let's try to do it in the most obvious way:

const provider = new Web3ProviderConnector(new Web3('...'));
const walletAddress = '0x1111111111111111111111111111111111111111';

const tokens = [
    '0x6b175474e89094c44da98b954eedeac495271d0f',
    '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
    '0xdac17f958d2ee523a2206206994597c13d831ec7'
];

const contractCalls = tokens.map((tokenAddress) => {
    const callData = provider.contractEncodeABI(
        ERC20ABI,
        tokenAddress,
        'balanceOf',
        [walletAddress]
    );

    return provider.ethCall(
        tokenAddress,
        callData
    );
});

const balances = await Promise.all(contractCalls);

The downside to this solution is that you make as many requests for a contract as you have tokens on the list.
And if the list is large enough, you will create a significant load on the provider.

Simple MultiCall

A multiCallService.callByChunks() contract takes a list of requests, splits them into chunks and calls the provider in batches.

Default params

• maxChunkSize: 100
• retriesLimit: 3
• blockNumber: 'latest'

Example:

const provider = new Web3ProviderConnector(new Web3('...'));
const walletAddress = '0x1111111111111111111111111111111111111111';
const contractAddress = '0x8d035edd8e09c3283463dade67cc0d49d6868063';
const multiCallService = new MultiCallService(provider, contractAddress);

const tokens = [
    '0x6b175474e89094c44da98b954eedeac495271d0f',
    '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
    '0xdac17f958d2ee523a2206206994597c13d831ec7'
];

// The parameters are optional, if not specified, the default will be used
const params: MultiCallParams = {
    chunkSize: 100,
    retriesLimit: 3,
    blockNumber: 'latest'
};

const callDatas = tokens.map((tokenAddress) => {
    return {
        to: tokenAddress,
        data: provider.contractEncodeABI(
            ERC20ABI,
            tokenAddress,
            'balanceOf',
            [walletAddress]
        )
    };
});

const balances = await multiCallService.callByChunks(callDatas, params);

Got better! Instead of making a separate request to the provider for each item, we group them into butches and make much fewer requests.

Note: If the call to this method exceeds the gas limit, then the entire request will be reverted.

MultiCall by gas limit

Problem:
The point is that the node has a limit for gas per call of the contract.
And it may happen that by making a simple MultiCall we will not meet this limit.
If the gas limit on the node is large enough, we may face a time limit on the execution of the contract method.

In total, there are 2 restrictions on a node:

• by gas
• by time

To avoid these limitations, there is a more advanced method:
multiCallService.callByGasLimit()

Default params

• maxChunkSize: 500
• retriesLimit: 3
• blockNumber: 'latest'
• gasBuffer: 3000000
• maxGasLimit: 150000000

Example:

const contractAddress = '0x8d035edd8e09c3283463dade67cc0d49d6868063';
const provider = new Web3ProviderConnector(new Web3('...'));

const gasLimitService = new GasLimitService(provider, contractAddress);
const multiCallService = new MultiCallService(provider, contractAddress);

const balanceOfGasUsage = 30_000;

const tokens = [
    '0x6b175474e89094c44da98b954eedeac495271d0f',
    '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
    '0xdac17f958d2ee523a2206206994597c13d831ec7'
];

const requests: MultiCallRequest[] = tokens.map((tokenAddress) => {
    return {
        to: tokenAddress,
        data: provider.contractEncodeABI(
            ERC20ABI,
            tokenAddress,
            'balanceOf',
            [walletAddress]
        ),
        gas: balanceOfGasUsage
    };
});

const gasLimit: number = await gasLimitService.calculateGasLimit();

// The parameters are optional, if not specified, the default will be used
const params: MultiCallParams = {
    maxChunkSize: 500,
    retriesLimit: 3,
    blockNumber: 'latest',
    gasBuffer: 100_000
};

const response = await multiCallService.callByGasLimit(
    requests,
    gasLimit,
    params
);

The idea is that we request the gas limit from the node and split the requests into chunks regarding this limit.
Accordingly, we must set the gas limit for each request.

It is noteworthy that if suddenly the request does not fit into the gas limit, the entire request will not be reverted, and the request will return the results of those calls that fit into the gas limit.

If the call to the contract all the same does not fit into the gas limit, then the callByGasLimit() will automatically re-request those elements that have not been fulfilled.

You can see a more detailed description of the library's work in the diagrams below.

GasLimitService

This service is used to correctly calculate the gas limit for calling a MultiCall.
The basic formula for calculating the limit is as follows:

const gasLimitForMultiCall = Math.min(gasLimitFromNode, maxGasLimit) - gasBuffer;

Where:
gasLimitFromNode - is the gas limit taken from the node
maxGasLimit - limiter on top, in case the gas limit from the node is too large (may cause timeout)
gasBuffer - is some safe buffer that allows you to avoid crossing the limit in case of unforeseen situations

Example:

const gasLimitForMultiCall = (Math.min(12_000_000, 40_000_000)) - 100_000; // 11_990_000

We believe that the multicall call should fit into 11_990_000 gas.

Default params:

• gasBuffer: 3000000
• maxGasLimit: 150000000

Params for GasLimitService.calculateGasLimit() are optional, if not specified, then gas limit will be requested from the node and the default params will be used.

Example:

const contractAddress = '0x8d035edd8e09c3283463dade67cc0d49d6868063';
const provider = new Web3ProviderConnector(new Web3('...'));

const gasLimitService = new GasLimitService(provider, contractAddress);

const gasLimit: number = await gasLimitService.calculateGasLimit();

Alternatively, you can specify your own parameters:

const contractAddress = '0x8d035edd8e09c3283463dade67cc0d49d6868063';
const provider = new Web3ProviderConnector(new Web3('...'));

const gasLimitService = new GasLimitService(provider, contractAddress);

// 190_000
const gasLimit: number = await gasLimitService.calculateGasLimit({
    gasLimit: 200_000,
    maxGasLimit: 200_000,
    gasBuffer: 10_000,
    
});

Contract code

---

Algorithm activity diagram

---

Algorithm visualization