pub struct Multicall<M> {
    pub contract: MulticallContract<M>,
    pub version: MulticallVersion,
    pub legacy: bool,
    pub block: Option<BlockId>,
    pub state: Option<State>,
    /* private fields */
}
Available on crate features 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>

source

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.

source

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.

source

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.

source

pub fn legacy(self) -> Self

Makes a legacy transaction instead of an EIP-1559 one.

source

pub fn block(self, block: impl Into<BlockNumber>) -> Self

Sets the block field of the Multicall aggregate call.

source

pub fn state(self, state: State) -> Self

Sets the overriding state of the Multicall aggregate call.

source

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 with send, otherwise they are always ignored.
source

pub fn add_calls<D: Detokenize>( &mut self, allow_failure: bool, calls: impl IntoIterator<Item = ContractCall<M, D>> ) -> &mut Self

Appends multiple calls to the list of calls of the Multicall instance.

See add_call for more details.

source

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)

source

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.

source

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.

source

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)

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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?;
source

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?;
source

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?;
source

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?;
source

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?;

Trait Implementations§

source§

impl<M> Clone for Multicall<M>

source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl<M> Debug for Multicall<M>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl<'a, M: Middleware> RawCall<'a> for Multicall<M>

source§

fn block(self, id: BlockId) -> Self

Sets the block number to execute against
source§

fn state(self, state: &'a State) -> Self

Sets the state override set. Note that not all client implementations will support this as a parameter.
source§

fn map<F>(self, f: F) -> Map<Self, F>
where Self: Sized,

Maps a closure f over the result of .awaiting this call

Auto Trait Implementations§

§

impl<M> RefUnwindSafe for Multicall<M>
where M: RefUnwindSafe,

§

impl<M> Send for Multicall<M>
where M: Sync + Send,

§

impl<M> Sync for Multicall<M>
where M: Sync + Send,

§

impl<M> Unpin for Multicall<M>
where M: Unpin,

§

impl<M> UnwindSafe for Multicall<M>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

impl<T> JsonSchemaMaybe for T