ape-ethereum

ape-ethereum.multicall

class ape_ethereum.multicall.BaseMulticall(address: AddressType = '0xcA11bde05977b3631167028862bE2a173976CA11', supported_chains: list[int] | None = None)

Bases: ManagerAccessMixin

add(call: ContractMethodHandler, *args, allowFailure: bool = True, value: int = 0) → BaseMulticall

Adds a call to the Multicall session object.

Raises:

InvalidOption – If one of the kwarg modifiers is not able to be used.

Parameters:

  • call (ContractMethodHandler) – The method to call.

  • *args – The arguments to invoke the method with.

  • allowFailure (bool) – Whether the call is allowed to fail.

  • value (int) – The amount of ether to forward with the call.

Returns:

returns itself

to emulate a builder pattern.

Return type:

BaseMulticall

classmethod inject() → ModuleType

Create the multicall module contract on-chain, so we can use it. Must use a provider that supports debug_setCode.

Usage example:

from ape_ethereum import multicall

@pytest.fixture(scope="session")
def use_multicall():
    # NOTE: use this fixture any test where you want to use a multicall
    return multicall.BaseMulticall.inject()
class ape_ethereum.multicall.Call(address: AddressType = '0xcA11bde05977b3631167028862bE2a173976CA11', supported_chains: list[int] | None = None)

Bases: BaseMulticall

Create a sequence of calls to execute at once using eth_call via the Multicall3 contract.

Usage example:

from ape_ethereum import multicall

call = multicall.Call()
call.add(contract.myMethod, *call_args)
call.add(contract.myMethod, *call_args)
...  # Add as many calls as desired
call.add(contract.myMethod, *call_args)
a, b, ..., z = call()  # Performs multicall
# or, using a builder pattern:
call = multicall.Call()
    .add(contract.myMethod, *call_args)
    .add(contract.myMethod, *call_args)
    ...  # Add as many calls as desired
    .add(contract.myMethod, *call_args)
a, b, ..., z = call()  # Performs multicall
__call__(**call_kwargs) → Iterator[Any]

Perform the Multicall call. This call will trigger again every time the Call object is called.

Raises:

UnsupportedChainError – If there is not an instance of Multicall3 deployed on the current chain at the expected address.

Parameters:

**call_kwargs – the kwargs to pass through to the call handler.

Returns:

the sequence of values produced by performing each call stored

by this instance.

Return type:

Iterator[Any]

add(call: ContractMethodHandler, *args, **kwargs)

Adds a call to the Multicall session object.

Raises:

InvalidOption – If one of the kwarg modifiers is not able to be used.

Parameters:

  • call (ContractMethodHandler) – The method to call.

  • *args – The arguments to invoke the method with.

  • allowFailure (bool) – Whether the call is allowed to fail.

  • value (int) – The amount of ether to forward with the call.

Returns:

returns itself

to emulate a builder pattern.

Return type:

BaseMulticall

as_transaction(**txn_kwargs) → TransactionAPI

Encode the Multicall transaction as a TransactionAPI object, but do not execute it.

Returns:

TransactionAPI

class ape_ethereum.multicall.Transaction(address: AddressType = '0xcA11bde05977b3631167028862bE2a173976CA11', supported_chains: list[int] | None = None)

Bases: BaseMulticall

Create a sequence of calls to execute at once using eth_sendTransaction via the Multicall3 contract.

Usage example:

from ape_ethereum.multicall import Transaction

txn = Transaction()
txn.add(contract.myMethod, *call_args)
txn.add(contract.myMethod, *call_args)
...  # Add as many calls as desired to execute
txn.add(contract.myMethod, *call_args)
a, b, ..., z = txn(sender=my_signer).return_data  # Sends the multicall transaction
# or, using a builder pattern:
txn = Transaction()
    .add(contract.myMethod, *call_args)
    .add(contract.myMethod, *call_args)
    ...  # Add as many calls as desired to execute
    .add(contract.myMethod, *call_args)
a, b, ..., z = txn(sender=my_signer).return_data  # Sends the multicall transaction
__call__(**txn_kwargs) → ReceiptAPI

Execute the Multicall transaction. The transaction will broadcast again every time the Transaction object is called.

Raises:

UnsupportedChain – If there is not an instance of Multicall3 deployed on the current chain at the expected address.

Parameters:

**txn_kwargs – the kwargs to pass through to the transaction handler.

Returns:

ReceiptAPI

as_transaction(**txn_kwargs) → TransactionAPI

Encode the Multicall transaction as a TransactionAPI object, but do not execute it.

Returns:

TransactionAPI