Metadata-Version: 2.1
Name: simple-multicall-2
Version: 0.1.0
Summary: Simple Web3 multicall 2
Author: 
Author-email: 
License: MIT
Keywords: multicall,web3,multicall2
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Requires: Web3
Description-Content-Type: text/markdown
License-File: LICENSE

# Simple Web3 Multicall

A multicall for use with pure Web3.py library.
It uses MakerDao Multicall smart contract by default,
but also can use any custom multicall smart contract
that implements "tryBlockAndAggregate" function.

Main urge for developmenet such a package was when I was needed to use multicall in my project
based on Web3.py, but found only libraries which work with Brownie, not on pure Web3.py.

    pip install simple-multicall-2

## Package Content

- class Multicall - The main multicall class that executes a multicall itself.

- constants file makerdao_multicall - contains a default MakerDao multicall smart contract ABI and a dictionary of addresses of multicall contracts deployed on different chains.

### class Multicall

The main multicall class. Should be initialized by passing a Web3 instance with specified chain RPC provider.

Has two methods:

_call_ - executes a multicall

_create_call_ - prepare a tuple for a list of calls to be passed to a _call_ method

**Attributes**

_w3_ : Web3 class instanse

_chain_: str
The name of one of defined chains
where MakerDao Multicall smart contract is deployed.
Can be one of the followings

- 'mainnet'
- 'kovan'
- 'rinkeby'
- 'goerli'
- 'ropsten'
- 'xdai'
- 'polygon'
- 'mumbai'
- 'bsc-mainnet'
- 'bsc-testnet'

_custom_address_: str - An address of custom multicall smart contract.
If specified, MakerDao Multicall smart contract will be omited.

_custom_abi_: str - An ABI of custom multicall smart contract.
If omited, MakerDao Multicall smart contract ABI will be used.

**Methods**

_call()_ - Executes multicall for specified list of smart contracts functions.

Parameters:

calls: list(tuple) - list of tuples (target contract address, encoded function name with parameters)
Can be easy prepared via using Multicall.create_cal' method.

Returns:

tuple(block number, list(results)) for default MakerDao multicall. May vary for custom multicalls.

_create_call()_ - Prepares a tuple for passing to Multicall.call list.

Parameters:

contract: web3.eth.Contract - A web3.eth.Contract instance of a contract
that is to be called via multicall.

fn_name: str - The name of a contract function to be called.

args: list - a list of arguments to be passed to a called contract function.

Returns:

tuple(target contract address, encoded function name with parameters)

## Example

Multicall of three ERC20 tokens of a specified EthDev _address_.

Importing Web3

    >>> from web3 import Web3

Defining constants: ERC20 token ABI token mainnet addresses.

    # ERC20 ABI string is cropped for readability
    >>> ERC20_ABI = '[{"constant":true,"inputs":[],"name":"name", ...

    >>> USDT_ADDRESS = Web3.toChecksumAddress('0xdAC17F958D2ee523a2206206994597C13D831ec7')
    >>> USDC_ADDRESS = Web3.toChecksumAddress('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48')
    >>> BNB_ADDRESS = Web3.toChecksumAddress('0xB8c77482e45F1F44dE1745F52C74426C631bDD52')

Initializing web3 instance.

    >>> ETH_PROVIDER_URL = 'https://rpc.ankr.com/eth'
    >>> w3 = Web3(Web3.HTTPProvider(ETH_PROVIDER_URL))

Creating token Web3 contracts.

    >>> USDT = w3.eth.contract(address=USDT_ADDRESS, abi=ERC20_ABI)
    >>> USDC = w3.eth.contract(address=USDC_ADDRESS, abi=ERC20_ABI)
    >>> BNB = w3.eth.contract(address=BNB_ADDRESS, abi=ERC20_ABI)

Target user address.

    >>> address = '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'

Initializing Multicall for mainnet.

    >>> from simple_multicall import Multicall
    >>>
    >>> multicall = Multicall(w3, 'mainnet')

Creating a list of calls via 'Multicall.create_call()' method.

    >>> calls = [
    ...     multicall.create_call(USDT, 'balanceOf', [address]),
    ...     multicall.create_call(USDC, 'balanceOf', [address]),
    ...     multicall.create_call(BNB, 'balanceOf', [address])
    ... ]

Executing multicall.

    >>> result= multicall.call(false, calls)

    >>> result
    [15442332, [b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\
    x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00?D#\xde' b'\x00\x00\x00\x00\x00\
    x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\
    x00\x00\x00;\x9a\xf1\x10', b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x0
    0\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02HA>\xf1\xd3\xf2\x00\x00']]

Interpreting results.

    >>> print('Block number: ', result[0])
    Block number:  15442332

    >>> print('USDT: ', int(result[1][0].hex(), 16) / 10 ** 6)
    USDT:  1061.430238

    >>> print('USDC: ', int(result[1][1].hex(), 16) / 10 ** 6)
    USDC:  1000.01

    >>> print('BNB: ', int(result[1][2].hex(), 16) / 10 ** 18)
    BNB:  42.1
