Struct ethers_contract::Multicall
source · pub struct Multicall<M> {
pub contract: MulticallContract<M>,
pub version: MulticallVersion,
pub legacy: bool,
pub block: Option<BlockId>,
pub state: Option<State>,
/* private fields */
}
providers
and abigen
only.Expand description
A Multicall is an abstraction for sending batched calls/transactions to the Ethereum blockchain.
It stores an instance of the Multicall
smart contract
and the user provided list of transactions to be called or executed on chain.
Multicall
can be instantiated asynchronously from the chain ID of the provided client using
new
or synchronously by providing a chain ID in new_with_chain
. This, by default, uses
constants::MULTICALL_ADDRESS
, but can be overridden by providing Some(address)
.
A list of all the supported chains is available here
.
Set the contract’s version by using version
.
The block
number can be provided for the call by using block
.
Transactions default to EIP1559
. This can be changed by using legacy
.
Build on the Multicall
instance by adding calls using add_call
and call or broadcast them
all at once by using call
and send
respectively.
§Example
Using Multicall (version 1):
use ethers_core::{
abi::Abi,
types::{Address, H256, U256},
};
use ethers_contract::{Contract, Multicall, MulticallVersion};
use ethers_providers::{Middleware, Http, Provider, PendingTransaction};
use std::{convert::TryFrom, sync::Arc};
// this is a dummy address used for illustration purposes
let address = "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee".parse::<Address>()?;
// (ugly way to write the ABI inline, you can otherwise read it from a file)
let abi: Abi = serde_json::from_str(r#"[{"inputs":[{"internalType":"string","name":"value","type":"string"}],"stateMutability":"nonpayable","type":"constructor"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"address","name":"author","type":"address"},{"indexed":true,"internalType":"address","name":"oldAuthor","type":"address"},{"indexed":false,"internalType":"string","name":"oldValue","type":"string"},{"indexed":false,"internalType":"string","name":"newValue","type":"string"}],"name":"ValueChanged","type":"event"},{"inputs":[],"name":"getValue","outputs":[{"internalType":"string","name":"","type":"string"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"lastSender","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"string","name":"value","type":"string"}],"name":"setValue","outputs":[],"stateMutability":"nonpayable","type":"function"}]"#)?;
// connect to the network
let client = Provider::<Http>::try_from("http://localhost:8545")?;
// create the contract object. This will be used to construct the calls for multicall
let client = Arc::new(client);
let contract = Contract::<Provider<Http>>::new(address, abi, client.clone());
// note that these [`ContractCall`]s are futures, and need to be `.await`ed to resolve.
// But we will let `Multicall` to take care of that for us
let first_call = contract.method::<_, String>("getValue", ())?;
let second_call = contract.method::<_, Address>("lastSender", ())?;
// Since this example connects to a known chain, we need not provide an address for
// the Multicall contract and we set that to `None`. If you wish to provide the address
// for the Multicall contract, you can pass the `Some(multicall_addr)` argument.
// Construction of the `Multicall` instance follows the builder pattern:
let mut multicall = Multicall::new(client.clone(), None).await?;
multicall
.add_call(first_call, false)
.add_call(second_call, false);
// `await`ing on the `call` method lets us fetch the return values of both the above calls
// in one single RPC call
let return_data: (String, Address) = multicall.call().await?;
// the same `Multicall` instance can be re-used to do a different batch of transactions.
// Say we wish to broadcast (send) a couple of transactions via the Multicall contract.
let first_broadcast = contract.method::<_, H256>("setValue", "some value".to_owned())?;
let second_broadcast = contract.method::<_, H256>("setValue", "new value".to_owned())?;
multicall
.clear_calls()
.add_call(first_broadcast, false)
.add_call(second_broadcast, false);
// `await`ing the `send` method waits for the transaction to be broadcast, which also
// returns the transaction hash
let tx_receipt = multicall.send().await?.await.expect("tx dropped");
// you can also query ETH balances of multiple addresses
let address_1 = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa".parse::<Address>()?;
let address_2 = "ffffffffffffffffffffffffffffffffffffffff".parse::<Address>()?;
multicall
.clear_calls()
.add_get_eth_balance(address_1, false)
.add_get_eth_balance(address_2, false);
let balances: (U256, U256) = multicall.call().await?;
Fields§
§contract: MulticallContract<M>
The Multicall contract interface.
version: MulticallVersion
The version of which methods to use when making the contract call.
legacy: bool
Whether to use a legacy or a EIP-1559 transaction.
block: Option<BlockId>
The block
field of the Multicall aggregate call.
state: Option<State>
The state overrides of the Multicall aggregate
Implementations§
source§impl<M: Middleware> Multicall<M>
impl<M: Middleware> Multicall<M>
sourcepub async fn new(
client: impl Into<Arc<M>>,
address: Option<Address>
) -> Result<Self, MulticallError<M>>
pub async fn new( client: impl Into<Arc<M>>, address: Option<Address> ) -> Result<Self, MulticallError<M>>
Creates a new Multicall instance from the provided client. If provided with an address
,
it instantiates the Multicall contract with that address, otherwise it defaults to
constants::MULTICALL_ADDRESS
.
§Errors
Returns a error::MulticallError
if the provider returns an error while getting
network_version
.
§Panics
If a None
address is provided and the client’s network is
not supported.
sourcepub fn new_with_chain_id(
client: impl Into<Arc<M>>,
address: Option<Address>,
chain_id: Option<impl Into<u64>>
) -> Result<Self, MulticallError<M>>
pub fn new_with_chain_id( client: impl Into<Arc<M>>, address: Option<Address>, chain_id: Option<impl Into<u64>> ) -> Result<Self, MulticallError<M>>
Creates a new Multicall instance synchronously from the provided client and address or chain ID. Uses the default multicall address if no address is provided.
§Errors
Returns a error::MulticallError
if the provided chain_id is not in the
supported networks.
§Panics
If neither an address or chain_id are provided. Since this is not an async function, it will
not be able to query net_version
to check if it is supported by the default multicall
address. Use new(client, None).await instead.
sourcepub fn version(self, version: MulticallVersion) -> Self
pub fn version(self, version: MulticallVersion) -> Self
Changes which functions to use when making the contract call. The default is 3. Version differences (adapted from here):
-
Multicall (v1): This is the recommended version for simple calls. The original contract containing an aggregate method to batch calls. Each call returns only the return data and none are allowed to fail.
-
Multicall2 (v2): The same as Multicall, but provides additional methods that allow either all or no calls within the batch to fail. Included for backward compatibility. Use v3 to allow failure on a per-call basis.
-
Multicall3 (v3): This is the recommended version for allowing failing calls. It’s cheaper to use (so you can fit more calls into a single request), and it adds an aggregate3 method so you can specify whether calls are allowed to fail on a per-call basis.
Note: all these versions are available in the same contract address
(constants::MULTICALL_ADDRESS
) so changing version just changes the methods used,
not the contract address.
sourcepub fn block(self, block: impl Into<BlockNumber>) -> Self
pub fn block(self, block: impl Into<BlockNumber>) -> Self
Sets the block
field of the Multicall aggregate call.
sourcepub fn state(self, state: State) -> Self
pub fn state(self, state: State) -> Self
Sets the overriding state
of the Multicall aggregate call.
sourcepub fn add_call<D: Detokenize>(
&mut self,
call: ContractCall<M, D>,
allow_failure: bool
) -> &mut Self
pub fn add_call<D: Detokenize>( &mut self, call: ContractCall<M, D>, allow_failure: bool ) -> &mut Self
Appends a call
to the list of calls of the Multicall instance.
Version specific details:
1
:allow_failure
is ignored.>=2
:allow_failure
specifies whether or not this call is allowed to revert in the multicall.3
: Transaction values are used when broadcasting transactions withsend
, otherwise they are always ignored.
sourcepub fn add_calls<D: Detokenize>(
&mut self,
allow_failure: bool,
calls: impl IntoIterator<Item = ContractCall<M, D>>
) -> &mut Self
pub fn add_calls<D: Detokenize>( &mut self, allow_failure: bool, calls: impl IntoIterator<Item = ContractCall<M, D>> ) -> &mut Self
Appends multiple call
s to the list of calls of the Multicall instance.
See add_call
for more details.
sourcepub fn add_get_block_hash(&mut self, block_number: impl Into<U256>) -> &mut Self
pub fn add_get_block_hash(&mut self, block_number: impl Into<U256>) -> &mut Self
Appends a call
to the list of calls of the Multicall instance for querying the block hash
of a given block number.
Note: this call will return 0 if block_number
is not one of the most recent 256 blocks.
(Reference)
sourcepub fn add_get_block_number(&mut self) -> &mut Self
pub fn add_get_block_number(&mut self) -> &mut Self
Appends a call
to the list of calls of the Multicall instance for querying the current
block number.
sourcepub fn add_get_current_block_coinbase(&mut self) -> &mut Self
pub fn add_get_current_block_coinbase(&mut self) -> &mut Self
Appends a call
to the list of calls of the Multicall instance for querying the current
block coinbase address.
sourcepub fn add_get_current_block_difficulty(&mut self) -> &mut Self
pub fn add_get_current_block_difficulty(&mut self) -> &mut Self
Appends a call
to the list of calls of the Multicall instance for querying the current
block difficulty.
Note: in a post-merge environment, the return value of this call will be the output of the randomness beacon provided by the beacon chain. (Reference)
sourcepub fn add_get_current_block_gas_limit(&mut self) -> &mut Self
pub fn add_get_current_block_gas_limit(&mut self) -> &mut Self
Appends a call
to the list of calls of the Multicall instance for querying the current
block gas limit.
sourcepub fn add_get_current_block_timestamp(&mut self) -> &mut Self
pub fn add_get_current_block_timestamp(&mut self) -> &mut Self
Appends a call
to the list of calls of the Multicall instance for querying the current
block timestamp.
sourcepub fn add_get_eth_balance(
&mut self,
address: impl Into<Address>,
allow_failure: bool
) -> &mut Self
pub fn add_get_eth_balance( &mut self, address: impl Into<Address>, allow_failure: bool ) -> &mut Self
Appends a call
to the list of calls of the Multicall instance for querying the ETH
balance of an address.
sourcepub fn add_get_last_block_hash(&mut self) -> &mut Self
pub fn add_get_last_block_hash(&mut self) -> &mut Self
Appends a call
to the list of calls of the Multicall instance for querying the last
block hash.
sourcepub fn add_get_basefee(&mut self, allow_failure: bool) -> &mut Self
pub fn add_get_basefee(&mut self, allow_failure: bool) -> &mut Self
Appends a call
to the list of calls of the Multicall instance for querying the current
block base fee.
Note: this call will fail if the chain that it is called on does not implement the BASEFEE opcode.
sourcepub fn add_get_chain_id(&mut self) -> &mut Self
pub fn add_get_chain_id(&mut self) -> &mut Self
Appends a call
to the list of calls of the Multicall instance for querying the chain id.
sourcepub fn clear_calls(&mut self) -> &mut Self
pub fn clear_calls(&mut self) -> &mut Self
Clears the batch of calls from the Multicall instance. Re-use the already instantiated Multicall to send a different batch of transactions or do another aggregate query.
§Examples
let mut multicall = Multicall::new(client, None).await?;
multicall
.add_call(broadcast_1, false)
.add_call(broadcast_2, false);
let _tx_receipt = multicall.send().await?.await.expect("tx dropped");
multicall
.clear_calls()
.add_call(call_1, false)
.add_call(call_2, false);
// Version 1:
let return_data: (String, Address) = multicall.call().await?;
// Version 2 and above (each call returns also the success status as the first element):
let return_data: ((bool, String), (bool, Address)) = multicall.call().await?;
sourcepub async fn call<T: Tokenizable>(&self) -> Result<T, MulticallError<M>>
pub async fn call<T: Tokenizable>(&self) -> Result<T, MulticallError<M>>
Queries the Ethereum blockchain using eth_call
, but via the Multicall contract.
For handling calls that have the same result type, see call_array
.
For handling each call’s result individually, see call_raw
.
§Errors
Returns a error::MulticallError
if there are any errors in the RPC call or while
detokenizing the tokens back to the expected return type.
Returns an error if any call failed, even if allow_failure
was set, or if the return data
was empty.
§Examples
The return type must be annotated as a tuple when calling this method:
// If the Solidity function calls has the following return types:
// 1. `returns (uint256)`
// 2. `returns (string, address)`
// 3. `returns (bool)`
let result: (U256, (String, Address), bool) = multicall.call().await?;
// or using the turbofish syntax:
let result = multicall.call::<(U256, (String, Address), bool)>().await?;
sourcepub async fn call_array<T: Tokenizable>(
&self
) -> Result<Vec<T>, MulticallError<M>>
pub async fn call_array<T: Tokenizable>( &self ) -> Result<Vec<T>, MulticallError<M>>
Queries the Ethereum blockchain using eth_call
, but via the Multicall contract, assuming
that every call returns same type.
§Errors
Returns a error::MulticallError
if there are any errors in the RPC call or while
detokenizing the tokens back to the expected return type.
Returns an error if any call failed, even if allow_failure
was set, or if the return data
was empty.
§Examples
The return type must be annotated while calling this method:
// If the all Solidity function calls `returns (uint256)`:
let result: Vec<U256> = multicall.call_array().await?;
sourcepub async fn call_raw(
&self
) -> Result<Vec<StdResult<Token, Bytes>>, MulticallError<M>>
pub async fn call_raw( &self ) -> Result<Vec<StdResult<Token, Bytes>>, MulticallError<M>>
Queries the Ethereum blockchain using eth_call
, but via the Multicall contract.
Returns a vector of Result<Token, Bytes>
for each call added to the Multicall:
Err(Bytes)
if the individual call failed while allowed or the return data was empty,
Ok(Token)
otherwise.
If the Multicall version is 1, this will always be a vector of Ok
.
§Errors
Returns a error::MulticallError
if there are any errors in the RPC call.
§Examples
// The consumer of the API is responsible for detokenizing the results
let tokens = multicall.call_raw().await?;
sourcepub async fn send(
&self
) -> Result<PendingTransaction<'_, M::Provider>, MulticallError<M>>
pub async fn send( &self ) -> Result<PendingTransaction<'_, M::Provider>, MulticallError<M>>
Signs and broadcasts a batch of transactions by using the Multicall contract as proxy, returning the pending transaction.
Note: this method will broadcast a transaction from an account, meaning it must have sufficient funds for gas and transaction value.
§Errors
Returns a error::MulticallError
if there are any errors in the RPC call.
§Examples
let tx_hash = multicall.send().await?;