Multicall
Multicall allows you to aggregate multiple contract reads into a single JSON-RPC request, and execute multiple state-changing calls in a single transaction on the FVM.
Multicall3
Multicall3 is a powerful tool that offers batch contract calls to smart contracts on the Filecoin Virtual Machine (FVM).
Multicall3 is deployed on over 100 chains at 0xcA11bde05977b3631167028862bE2a173976CA11
. A sortable, searchable list of all chains it's deployed on can be found here.
The multicall3 ABI can be downloaded or copied to the clipboard in various formats, including:
Solidity interface.
JSON ABI, prettified.
JSON ABI, minified.
ethers.js human readable ABI.
viem human readable ABI.
Alternatively, you can:
Download the ABI from the releases page.
Copy the ABI from Etherscan.
Install Foundry and run
cast interface 0xcA11bde05977b3631167028862bE2a173976CA11
.
Contract address
Multicall has the same, precomputed address for all of the networks it is deployed on.
0xcA11bde05977b3631167028862bE2a173976CA11
✔️
❌
0xcA11bde05977b3631167028862bE2a173976CA11
❌
✔️
Usage
To use Multicall3 to send batch contract read/write to your smart contract, you will need to:
Obtain the Multicall3 contract address for the network you're using (Filecoin mainnet or Calibration testnet).
Get the Multicall3 ABI, which can be downloaded or copied from various sources mentioned above.
Create an instance of the Multicall3 contract using a web3 library like ethers.js or viem.
Prepare your batch calls, including the target contract addresses, function selectors, and input data.
Use the appropriate Multicall3 method (e.g.,
aggregate3
for multiple calls) to execute your batch operations.Process the returned data from the Multicall3 contract.
The steps above differ slightly for integrations using smart contracts, where steps 2 and 3 are replaced with:
Import the Multicall3 interface in your smart contract.
Create a function that interacts with the Multicall3 contract using the imported interface.
Many libraries and tools such as ethers-rs, viem, and ape have native Multicall3 integration which can be used in your projects directly. To learn how to use Multicall3 with these tools, check out Multicall3 examples folder
Batching Contract Reads
Batching contract reads, one of the most common use cases, allows a single eth_call
JSON RPC request to return the results of multiple contract function calls. It has many benefits:
Reduced JSON RPC Requests: Multicall reduces the number of separate JSON RPC requests that need to be sent. This is particularly useful when using remote nodes, such as GLIF. By aggregating multiple contract reads into a single JSON-RPC request, Multicall (1) reduces RPC usage and therefore costs, and (2) reduces the number of round trips between the client and the node, which can significantly improve performance
Consistent Data from the Same Block: Multicall guarantees that all values returned are from the same block. This ensures data consistency and reliability, as all the read operations are performed on the same state of the blockchain.
Detection of Stale Data: Multicall enables the block number or timestamp to be returned with the read data. This feature helps in detecting stale data, as developers can compare the block number or timestamp with the current state of the blockchain to ensure the data is up-to-date.
When directly interacting with the Multicall3 contract to batch calls, you'll typically use the aggregate3
method. This method allows you to execute multiple contract calls in a single transaction. Here's an explanation of how it works, along with examples:
Solidity Implementation: The
aggregate3
method is implemented in the Multicall3 contract like this:Example of sending multicalls to this smart contract: Here's an example using ethers.js to interact with the Multicall3 contract:
This example demonstrates how to use Multicall3 to batch multiple balanceOf
calls for an ERC20 token in a single transaction, significantly reducing the number of separate RPC calls needed.
Batch Contract Writes
When using Multicall3, it's crucial to understand two key aspects: the behavior of msg.sender
in calls versus delegatecalls, and the risks associated with msg.value
in multicalls.
In FVM, there are two types of accounts: Externally Owned Accounts (EOAs) controlled by private keys, and Contract Accounts controlled by code. The msg.sender
value during contract execution depends on whether a CALL or DELEGATECALL opcode is used. CALL changes the execution context, while DELEGATECALL preserves it.
For EOAs, which can only use CALL, Multicall3's address becomes the msg.sender
for subsequent calls. This limits its usefulness from EOAs to scenarios where msg.sender
is irrelevant. However, contract wallets or other contracts can use either CALL or DELEGATECALL, with the latter preserving the original msg.sender
.
The handling of msg.value
in multicalls requires caution. Since msg.value
doesn't change with delegatecalls, relying on it within a multicall can lead to security vulnerabilities. To learn more about this, see here and here.
Hints
Lotus FEVM RPC supports Ethereum batch transactions. The key difference between multicall
and batch transactions is that multicall
aggregates multiple RPC requests into a single call, while batch transactions are simply an array of transactions executed sequentially but sent in one request. For more details, please refer to the Ethereum documentation.
Last updated