Contracts

Smart contracts are programs deployed to the Ethereum network. See the ethereum.org docs for a proper introduction.

Interacting with deployed contracts

In order to use an existing contract, you’ll need its deployed address and its ABI. Both can be found using block explorers, like Etherscan. Once you instantiate a contract instance, you can read data and execute transactions.

# Configure w3, e.g., w3 = Web3(...)
address = '0x1f9840a85d5aF5bf1D1762F925BDADdC4201F988'
abi = '[{"inputs":[{"internalType":"address","name":"account","type":"address"},{"internalType":"address","name":"minter_","type":"address"},...'
contract_instance = w3.eth.contract(address=address, abi=abi)

# read state:
contract_instance.functions.storedValue().call()
# 42

# update state:
tx_hash = contract_instance.functions.updateValue(43).transact()

Contract Deployment Example

To run this example, you will need to install a few extra features:

The sandbox node provided by eth-tester. You can install it with:

$ pip install -U "web3[tester]"

py-solc-x. This is the supported route to installing the solidity compiler solc. You can install it with:

$ pip install py-solc-x

After py-solc-x is installed, you will need to install a version of solc. You can install the latest version via a new REPL with:

>>> from solcx import install_solc
>>> install_solc(version='latest')

You should now be set up to compile and deploy a contract.

The following example runs through these steps:

Compile Solidity contract into bytecode and an ABI
Initialize a Contract instance
Deploy the contract using the Contract instance to initiate a transaction
Interact with the contract functions using the Contract instance

>>> from web3 import Web3
>>> from solcx import compile_source

# Solidity source code
>>> compiled_sol = compile_source(
...     '''
...     pragma solidity >0.5.0;
...
...     contract Greeter {
...         string public greeting;
...
...         constructor() public {
...             greeting = 'Hello';
...         }
...
...         function setGreeting(string memory _greeting) public {
...             greeting = _greeting;
...         }
...
...         function greet() view public returns (string memory) {
...             return greeting;
...         }
...     }
...     ''',
...     output_values=['abi', 'bin']
... )

# retrieve the contract interface
>>> contract_id, contract_interface = compiled_sol.popitem()

# get bytecode / bin
>>> bytecode = contract_interface['bin']

# get abi
>>> abi = contract_interface['abi']

# web3.py instance
>>> w3 = Web3(Web3.EthereumTesterProvider())

# set pre-funded account as sender
>>> w3.eth.default_account = w3.eth.accounts[0]

>>> Greeter = w3.eth.contract(abi=abi, bytecode=bytecode)

# Submit the transaction that deploys the contract
>>> tx_hash = Greeter.constructor().transact()

# Wait for the transaction to be mined, and get the transaction receipt
>>> tx_receipt = w3.eth.wait_for_transaction_receipt(tx_hash)

>>> greeter = w3.eth.contract(
...     address=tx_receipt.contractAddress,
...     abi=abi
... )

>>> greeter.functions.greet().call()
'Hello'

>>> tx_hash = greeter.functions.setGreeting('Nihao').transact()
>>> tx_receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
>>> greeter.functions.greet().call()
'Nihao'

Contract Factories

These factories are not intended to be initialized directly. Instead, create contract objects using the w3.eth.contract() method. By default, the contract factory is Contract.

class web3.contract.Contract(address)

Contract provides a default interface for deploying and interacting with Ethereum smart contracts.

The address parameter can be a hex address or an ENS name, like mycontract.eth.

Properties

Each Contract Factory exposes the following properties.

Contract.address: The hexadecimal encoded 20-byte address of the contract, or an ENS name. May be None if not provided during factory creation.

Contract.abi

The contract abi, or Application Binary Interface, specifies how a contract can be interacted with. Without an abi, the contract cannot be decoded. The abi enables the Contract instance to expose functions and events as object properties.

For further details, see the Solidity ABI specification.

Contract.bytecode: The contract bytecode string. May be None if not provided during factory creation.

Contract.bytecode_runtime: The runtime part of the contract bytecode string. May be None if not provided during factory creation.

Contract.decode_tuples

If a Tuple/Struct is returned by a contract function, this flag defines whether to apply the field names from the ABI to the returned data. If False, the returned value will be a normal Python Tuple. If True, the returned value will be a Python NamedTuple of the class ABIDecodedNamedTuple.

NamedTuples have some restrictions regarding field names. web3.py sets NamedTuple’s rename=True, so disallowed field names may be different than expected. See the Python docs for more information.

Defaults to False if not provided during factory creation.

Contract.functions: This provides access to contract functions as attributes. For example: myContract.functions.MyMethod(). The exposed contract functions are classes of the type ContractFunction.

Contract.events: This provides access to contract events as attributes. For example: myContract.events.MyEvent(). The exposed contract events are classes of the type ContractEvent.

Methods

Each Contract Factory exposes the following methods.

classmethod Contract.constructor(*args, **kwargs).transact(transaction=None)

Construct and deploy a contract by sending a new public transaction.

If provided transaction should be a dictionary conforming to the web3.eth.send_transaction(transaction) method. This value may not contain the keys data or to.

If the contract takes constructor parameters they should be provided as positional arguments or keyword arguments.

If any of the arguments specified in the ABI are an address type, they will accept ENS names.

If a gas value is not provided, then the gas value for the deployment transaction will be created using the web3.eth.estimate_gas() method.

Returns the transaction hash for the deploy transaction.

>>> deploy_txn = token_contract.constructor(web3.eth.accounts[0], 12345).transact()
>>> txn_receipt = web3.eth.get_transaction_receipt(deploy_txn)
>>> txn_receipt['contractAddress']
'0x4c0883a69102937d6231471b5dbb6204fe5129617082792ae468d01a3f362318'

classmethod Contract.constructor(*args, **kwargs).estimate_gas(transaction=None, block_identifier=None)

Estimate gas for constructing and deploying the contract.

This method behaves the same as the Contract.constructor(*args, **kwargs).transact() method, with transaction details being passed into the end portion of the function call, and function arguments being passed into the first portion.

The block_identifier parameter is passed directly to the call at the end portion of the function call.

Returns the amount of gas consumed which can be used as a gas estimate for executing this transaction publicly.

Returns the gas needed to deploy the contract.

>>> token_contract.constructor(web3.eth.accounts[0], 12345).estimate_gas()
12563

classmethod Contract.constructor(*args, **kwargs).build_transaction(transaction=None)

Construct the contract deploy transaction bytecode data.

If the contract takes constructor parameters they should be provided as positional arguments or keyword arguments.

If any of the args specified in the ABI are an address type, they will accept ENS names.

Returns the transaction dictionary that you can pass to send_transaction method.

>>> transaction = {
'gasPrice': w3.eth.gas_price,
'chainId': None
}
>>> contract_data = token_contract.constructor(web3.eth.accounts[0], 12345).build_transaction(transaction)
>>> web3.eth.send_transaction(contract_data)

classmethod Contract.events.your_event_name.create_filter(from_block=None, to_block='latest', argument_filters={}, topics=[])

Creates a new event filter, an instance of web3.utils.filters.LogFilter.

from_block is a mandatory field. Defines the starting block (exclusive) filter block range. It can be either the starting block number, or ‘latest’ for the last mined block, or ‘pending’ for unmined transactions. In the case of from_block, ‘latest’ and ‘pending’ set the ‘latest’ or ‘pending’ block as a static value for the starting filter block.
to_block optional. Defaults to ‘latest’. Defines the ending block (inclusive) in the filter block range. Special values ‘latest’ and ‘pending’ set a dynamic range that always includes the ‘latest’ or ‘pending’ blocks for the filter’s upper block range.
address optional. Defaults to the contract address. The filter matches the event logs emanating from address.
argument_filters, optional. Expects a dictionary of argument names and values. When provided event logs are filtered for the event argument values. Event arguments can be both indexed or unindexed. Indexed values will be translated to their corresponding topic arguments. Unindexed arguments will be filtered using a regular expression.
topics optional, accepts the standard JSON-RPC topics argument. See the JSON-RPC documentation for eth_newFilter more information on the topics parameters.

classmethod Contract.events.your_event_name.build_filter()

Creates a EventFilterBuilder instance with the event abi, and the contract address if called from a deployed contract instance. The EventFilterBuilder provides a convenient way to construct the filter parameters with value checking against the event abi. It allows for defining multiple match values or of single values through the match_any and match_single methods.

filter_builder = myContract.events.myEvent.build_filter()
filter_builder.from_block = "latest"
filter_builder.args.clientID.match_any(1, 2, 3, 4)
filter_builder.args.region.match_single("UK")
filter_instance = filter_builder.deploy()

The deploy method returns a web3.utils.filters.LogFilter instance from the filter parameters generated by the filter builder. Defining multiple match values for array arguments can be accomplished easily with the filter builder:

filter_builder = myContract.events.myEvent.build_filter()
filter_builder.args.clientGroups.match_any((1, 3, 5,), (2, 3, 5), (1, 2, 3))

The filter builder blocks already defined filter parameters from being changed.

filter_builder = my_contract.events.myEvent.build_filter()
filter_builder.from_block = "latest"
filter_builder.from_block = 0  # raises a ValueError

classmethod Contract.encode_abi(fn_name, args=None, kwargs=None, data=None)

Encodes the arguments using the Ethereum ABI for the contract function that matches the given fn_name and arguments args. The data parameter defaults to the function selector.

>>> contract.encode_abi(fn_name="register", args=["rainbows", 10])
"0xea87152b0000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000087261696e626f7773000000000000000000000000000000000000000000000000"

classmethod Contract.all_functions()

Returns a list of all the functions present in a Contract where every function is an instance of ContractFunction.

>>> contract.all_functions()
[<Function identity(uint256,bool)>, <Function identity(int256,bool)>]

classmethod Contract.get_function_by_signature(signature)

Searches for a distinct function with matching signature. Returns an instance of ContractFunction upon finding a match. Raises Web3ValueError if no match is found.

>>> contract.get_function_by_signature('identity(uint256,bool)')
<Function identity(uint256,bool)>

classmethod Contract.find_functions_by_name(name)

Searches for all function with matching name. Returns a list of matching functions where every function is an instance of ContractFunction. Returns an empty list when no match is found.

>>> contract.find_functions_by_name('identity')
[<Function identity(uint256,bool)>, <Function identity(int256,bool)>]

classmethod Contract.get_function_by_name(name)

Searches for a distinct function with matching name. Returns an instance of ContractFunction upon finding a match. Raises Web3ValueError if no match is found or if multiple matches are found.

>>> contract.get_function_by_name('unique_name')
<Function unique_name(uint256)>

classmethod Contract.get_function_by_selector(selector)

Searches for a distinct function with matching selector. The selector can be a hexadecimal string, bytes or int. Returns an instance of ContractFunction upon finding a match. Raises Web3ValueError if no match is found.

>>> contract.get_function_by_selector('0xac37eebb')
<Function identity(uint256)'>
>>> contract.get_function_by_selector(b'\xac7\xee\xbb')
<Function identity(uint256)'>
>>> contract.get_function_by_selector(0xac37eebb)
<Function identity(uint256)'>

classmethod Contract.find_functions_by_args(*args)

Searches for all function with matching args. Returns a list of matching functions where every function is an instance of ContractFunction. Returns an empty list when no match is found.

>>> contract.find_functions_by_args(1, True)
[<Function identity(uint256,bool)>, <Function identity(int256,bool)>]

classmethod Contract.get_function_by_args(*args)

Searches for a distinct function with matching args. Returns an instance of ContractFunction upon finding a match. Raises ValueError if no match is found or if multiple matches are found.

>>> contract.get_function_by_args(1)
<Function unique_func_with_args(uint256)>

Note

Contract methods all_functions, get_function_by_signature, find_functions_by_name, get_function_by_name, get_function_by_selector, find_functions_by_args and get_function_by_args can only be used when abi is provided to the contract.

Note

web3.py rejects the initialization of contracts that have more than one function with the same selector or signature. eg. blockHashAddendsInexpansible(uint256) and blockHashAskewLimitary(uint256) have the same selector value equal to 0x00000000. A contract containing both of these functions will be rejected.

Disabling Strict Checks for Bytes Types

By default, web3 is strict when it comes to hex and bytes values, as of v6. If an abi specifies a byte size, but the value that gets passed in is not the specified size, web3 will invalidate the value. For example, if an abi specifies a type of bytes4, web3 will invalidate the following values:

Invalid byte and hex strings with strict (default) bytes4 type checking
Input	Reason
`''`	Needs to be prefixed with a “0x” to be interpreted as an empty hex string
`2`	Wrong type
`'ah'`	String is not valid hex
`'1234'`	Needs to either be a bytestring (b’1234’) or be a hex value of the right size, prefixed with 0x (in this case: ‘0x31323334’)
`b''`	Needs to have exactly 4 bytes
`b'ab'`	Needs to have exactly 4 bytes
`'0xab'`	Needs to have exactly 4 bytes
`'0x6162636464'`	Needs to have exactly 4 bytes

However, you may want to be less strict with acceptable values for bytes types. This may prove useful if you trust that values coming through are what they are meant to be with respect to the ABI. In this case, the automatic padding might be convenient for inferred types. For this, you can set the w3.strict_bytes_type_checking() flag to False, which is available on the Web3 instance. A Web3 instance which has this flag set to False will have a less strict set of rules on which values are accepted. A bytes type will allow values as a hex string, a bytestring, or a regular Python string that can be decoded as a hex. 0x-prefixed hex strings are also not required.

A Python string that is not prefixed with 0x is valid.

A bytestring whose length is less than the specified byte size is valid.

Valid byte and hex strings for a non-strict bytes4 type
Input	Normalizes to
`''`	`b'\x00\x00\x00\x00'`
`'0x'`	`b'\x00\x00\x00\x00'`
`b''`	`b'\x00\x00\x00\x00'`
`b'ab'`	`b'ab\x00\x00'`
`'0xab'`	`b'\xab\x00\x00\x00'`
`'1234'`	`b'\x124\x00\x00'`
`'0x61626364'`	`b'abcd'`
`'1234'`	`b'1234'`

Taking the following contract code as an example:

>>> #  pragma solidity >=0.4.22 <0.6.0;
...
... #   contract ArraysContract {
... #      bytes2[] public bytes2Value;

... #      constructor(bytes2[] memory _bytes2Value) public {
... #          bytes2Value = _bytes2Value;
... #      }

... #      function setBytes2Value(bytes2[] memory _bytes2Value) public {
... #          bytes2Value = _bytes2Value;
... #      }

... #      function getBytes2Value() public view returns (bytes2[] memory) {
... #          return bytes2Value;
... #      }
... #  }

>>> # abi = "..."
>>> # bytecode = "6080..."

>>> arrays_contract_instance = w3.eth.contract(abi=abi, bytecode=bytecode)

>>> tx_hash = arrays_contract_instance.constructor([b'bb']).transact()
>>> tx_receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
>>> arrays_contract = w3.eth.contract(
...     address=tx_receipt.contractAddress,
...     abi=abi
... )
>>> arrays_contract.functions.getBytes2Value().call()
[b'bb']

>>> # set value with appropriate byte size
>>> arrays_contract.functions.setBytes2Value([b'aa']).transact({'gas': 420000, "maxPriorityFeePerGas": 10 ** 9, "maxFeePerGas": 10 ** 9})
HexBytes('0xcb95151142ea56dbf2753d70388aef202a7bb5a1e323d448bc19f1d2e1fe3dc9')
>>> # check value
>>> arrays_contract.functions.getBytes2Value().call()
[b'aa']

>>> # trying to set value without appropriate size (bytes2) is not valid
>>> arrays_contract.functions.setBytes2Value([b'b']).transact()
Traceback (most recent call last):
   ...
web3.exceptions.MismatchedABI:
Could not identify the intended function with name
>>> # check value is still b'aa'
>>> arrays_contract.functions.getBytes2Value().call()
[b'aa']

>>> # disabling strict byte checking...
>>> w3.strict_bytes_type_checking = False

>>> tx_hash = arrays_contract_instance.constructor([b'b']).transact()
>>> tx_receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
>>> arrays_contract = w3.eth.contract(
...     address=tx_receipt.contractAddress,
...     abi=abi
... )
>>> # check value is zero-padded... i.e. b'b\x00'
>>> arrays_contract.functions.getBytes2Value().call()
[b'b\x00']

>>> # set the flag back to True
>>> w3.strict_bytes_type_checking = True

>>> arrays_contract.functions.setBytes2Value([b'a']).transact()
Traceback (most recent call last):
   ...
web3.exceptions.MismatchedABI:
Could not identify the intended function with name

Contract Functions

class web3.contract.ContractFunction

The named functions exposed through the Contract.functions property are of the ContractFunction type. This class is not to be used directly, but instead through Contract.functions.

For example:

myContract = web3.eth.contract(address=contract_address, abi=contract_abi)
twentyone = myContract.functions.multiply7(3).call()

If you have the function name in a variable, you might prefer this alternative:

func_to_call = 'multiply7'
contract_func = myContract.functions[func_to_call]
twentyone = contract_func(3).call()

ContractFunction provides methods to interact with contract functions. Positional and keyword arguments supplied to the contract function subclass will be used to find the contract function by signature, and forwarded to the contract function when applicable.

EIP-3668 introduced support for the OffchainLookup revert / CCIP Read support. CCIP Read is set to True for calls by default, as recommended in EIP-3668. This is done via a global global_ccip_read_enabled flag on the provider. If raising the OffchainLookup revert is preferred for a specific call, the ccip_read_enabled flag on the call may be set to False.

>>> # raises the revert instead of handling the offchain lookup
>>> myContract.functions.revertsWithOffchainLookup(myData).call(ccip_read_enabled=False)
*** web3.exceptions.OffchainLookup

Disabling CCIP Read support can be useful if a transaction needs to be sent to the callback function. In such cases, “preflighting” with an eth_call, handling the OffchainLookup, and sending the data via a transaction may be necessary. See CCIP Read support for offchain lookup in the examples section for how to preflight a transaction with a contract call.

Similarly, if CCIP Read is globally set to False via the global_ccip_read_enabled flag on the provider, it may be enabled on a per-call basis - overriding the global flag. This ensures only explicitly enabled calls will handle the OffchainLookup revert appropriately.

>>> # global flag set to `False`
>>> w3.provider.global_ccip_read_enabled = False

>>> # does not raise the revert since explicitly enabled on the call:
>>> response = myContract.functions.revertsWithOffchainLookup(myData).call(ccip_read_enabled=True)

If the function called results in a revert error, a ContractLogicError will be raised. If there is an error message with the error, web3.py attempts to parse the message that comes back and return it to the user as the error string. As of v6.3.0, the raw data is also returned and can be accessed via the data attribute on ContractLogicError.

Methods

ContractFunction.transact(transaction)

Execute the specified function by sending a new public transaction.

Refer to the following invocation:

myContract.functions.myMethod(*args, **kwargs).transact(transaction)

The first portion of the function call myMethod(*args, **kwargs) selects the appropriate contract function based on the name and provided argument. Arguments can be provided as positional arguments, keyword arguments, or a mix of the two.

The end portion of this function call transact(transaction) takes a single parameter which should be a python dictionary conforming to the same format as the web3.eth.send_transaction(transaction) method. This dictionary may not contain the keys data.

If any of the args or kwargs specified in the ABI are an address type, they will accept ENS names.

If a gas value is not provided, then the gas value for the method transaction will be created using the web3.eth.estimate_gas() method.

Returns the transaction hash.

>>> token_contract.functions.transfer(web3.eth.accounts[1], 12345).transact()
"0x4e3a3754410177e6937ef1f84bba68ea139e8d1a2258c5f85db9f1cd715a1bdd"

ContractFunction.call(transaction, block_identifier='latest')

Call a contract function, executing the transaction locally using the eth_call API. This will not create a new public transaction.

Refer to the following invocation:

myContract.functions.myMethod(*args, **kwargs).call(transaction)

This method behaves the same as the ContractFunction.transact() method, with transaction details being passed into the end portion of the function call, and function arguments being passed into the first portion.

Returns the return value of the executed function.

>>> my_contract.functions.multiply7(3).call()
21
>>> token_contract.functions.myBalance().call({'from': web3.eth.accounts[0]})
12345  # the token balance for `web3.eth.accounts[0]`
>>> token_contract.functions.myBalance().call({'from': web3.eth.accounts[1]})
54321  # the token balance for the account `web3.eth.accounts[1]`

You can call the method at a historical block using block_identifier. Some examples:

# You can call your contract method at a block number:
>>> token_contract.functions.myBalance().call(block_identifier=10)

# or a number of blocks back from pending,
# in this case, the block just before the latest block:
>>> token_contract.functions.myBalance().call(block_identifier=-2)

# or a block hash:
>>> token_contract.functions.myBalance().call(block_identifier='0x4ff4a38b278ab49f7739d3a4ed4e12714386a9fdf72192f2e8f7da7822f10b4d')
>>> token_contract.functions.myBalance().call(block_identifier=b'O\xf4\xa3\x8b\'\x8a\xb4\x9fw9\xd3\xa4\xedN\x12qC\x86\xa9\xfd\xf7!\x92\xf2\xe8\xf7\xdax"\xf1\x0bM')

# Latest is the default, so this is redundant:
>>> token_contract.functions.myBalance().call(block_identifier='latest')

# You can check the state after your pending transactions (if supported by your node):
>>> token_contract.functions.myBalance().call(block_identifier='pending')

Passing the block_identifier parameter for past block numbers requires that your Ethereum API node is running in the more expensive archive node mode. Normally synced Ethereum nodes will fail with a “missing trie node” error, because Ethereum node may have purged the past state from its database. More information about archival nodes here.

ContractFunction.estimate_gas(transaction, block_identifier=None)

Call a contract function, executing the transaction locally using the eth_call API. This will not create a new public transaction.

Refer to the following invocation:

myContract.functions.myMethod(*args, **kwargs).estimate_gas(transaction)

This method behaves the same as the ContractFunction.transact() method, with transaction details being passed into the end portion of the function call, and function arguments being passed into the first portion.

Returns the amount of gas consumed which can be used as a gas estimate for executing this transaction publicly.

>>> my_contract.functions.multiply7(3).estimate_gas()
42650

Note

The parameter block_identifier is not enabled in geth nodes, hence passing a value of block_identifier when connected to a geth nodes would result in an error like: ValueError: {'code': -32602, 'message': 'too many arguments, want at most 1'}

ContractFunction.build_transaction(transaction)

Builds a transaction dictionary based on the contract function call specified.

Refer to the following invocation:

myContract.functions.myMethod(*args, **kwargs).build_transaction(transaction)

This method behaves the same as the Contract.transact() method, with transaction details being passed into the end portion of the function call, and function arguments being passed into the first portion.

Note

nonce is not returned as part of the transaction dictionary unless it is specified in the first portion of the function call:

>>> math_contract.functions.increment(5).build_transaction({'nonce': 10})

You may use getTransactionCount() to get the current nonce for an account. Therefore a shortcut for producing a transaction dictionary with nonce included looks like:

>>> math_contract.functions.increment(5).build_transaction({'nonce': web3.eth.get_transaction_count('0xF5...')})

Returns a transaction dictionary. This transaction dictionary can then be sent using send_transaction().

Additionally, the dictionary may be used for offline transaction signing using sign_transaction().

>>> math_contract.functions.increment(5).build_transaction({'maxFeePerGas': 2000000000, 'maxPriorityFeePerGas': 1000000000})
{
    'to': '0x582AC4D8929f58c217d4a52aDD361AE470a8a4cD',
    'data': '0x7cf5dab00000000000000000000000000000000000000000000000000000000000000005',
    'value': 0,
    'gas': 43242,
    'maxFeePerGas': 2000000000,
    'maxPriorityFeePerGas': 1000000000,
    'chainId': 1
}

Fallback Function

The Contract Factory also offers an API to interact with the fallback function, which supports four methods like normal functions:

Contract.fallback.call(transaction): Call fallback function, executing the transaction locally using the eth_call API. This will not create a new public transaction.

Contract.fallback.estimate_gas(transaction): Call fallback function and return the gas estimation.

Contract.fallback.transact(transaction): Execute fallback function by sending a new public transaction.

Contract.fallback.build_transaction(transaction): Builds a transaction dictionary based on the contract fallback function call.

Events

class web3.contract.ContractEvents

The named events exposed through the Contract.events property are of the ContractEvents type. This class is not to be used directly, but instead through Contract.events.

For example:

myContract = web3.eth.contract(address=contract_address, abi=contract_abi)
tx_hash = myContract.functions.myFunction().transact()
receipt = web3.eth.get_transaction_receipt(tx_hash)
myContract.events.myEvent().process_receipt(receipt)

ContractEvent provides methods to interact with contract events. Positional and keyword arguments supplied to the contract event subclass will be used to find the contract event by signature.

ContractEvents.myEvent(*args, **kwargs).get_logs(from_block=None, to_block="latest", block_hash=None, argument_filters={})

Fetches all logs for a given event within the specified block range or block hash.

Returns a list of decoded event logs sorted by logIndex.

argument_filters is an optional dictionary argument that can be used to filter for logs where the event’s argument values match the values provided in the dictionary. The keys must match the event argument names as they exist in the ABI. The values can either be a single value or a list of values to match against. If a list is provided, the logs will be filtered for any logs that match any of the values in the list. Indexed arguments are filtered pre-call by building specific topics to filter for. Non-indexed arguments are filtered by the library after the logs are fetched from the node.
my_contract = web3.eth.contract(address=contract_address, abi=contract_abi)

# get ``myEvent`` logs from block 1337 to block 2337 where the value for the
# event argument "eventArg1" is either 1, 2, or 3
my_contract.events.myEvent().get_logs(
    argument_filters={"eventArg1": [1, 2, 3]},
    from_block=1337,
    to_block=2337,
)

ContractEvents.myEvent(*args, **kwargs).process_receipt(transaction_receipt, errors=WARN)

Extracts the pertinent logs from a transaction receipt.

If there are no errors, process_receipt returns a tuple of Event Log Objects, emitted from the event (e.g. myEvent), with decoded output.

>>> tx_hash = contract.functions.myFunction(12345).transact({'to':contract_address})
>>> tx_receipt = w3.eth.get_transaction_receipt(tx_hash)
>>> rich_logs = contract.events.myEvent().process_receipt(tx_receipt)
>>> rich_logs[0]['args']
{'myArg': 12345}

If there are errors, the logs will be handled differently depending on the flag that is passed in:

WARN (default) - logs a warning to the console for the log that has an error, and discards the log. Returns any logs that are able to be processed.

STRICT - stops all processing and raises the error encountered.

IGNORE - returns any raw logs that raised an error with an added “errors” field, along with any other logs were able to be processed.

DISCARD - silently discards any logs that have errors, and returns processed logs that don’t have errors.

An event log error flag needs to be imported from web3/logs.py.

>>> tx_hash = contract.functions.myFunction(12345).transact({'to':contract_address})
>>> tx_receipt = w3.eth.get_transaction_receipt(tx_hash)
>>> processed_logs = contract.events.myEvent().process_receipt(tx_receipt)
>>> processed_logs
(
   AttributeDict({
       'args': AttributeDict({}),
       'event': 'myEvent',
       'logIndex': 0,
       'transactionIndex': 0,
       'transactionHash': HexBytes('0xfb95ccb6ab39e19821fb339dee33e7afe2545527725b61c64490a5613f8d11fa'),
       'address': '0xF2E246BB76DF876Cef8b38ae84130F4F55De395b',
       'blockHash': HexBytes('0xd74c3e8bdb19337987b987aee0fa48ed43f8f2318edfc84e3a8643e009592a68'),
       'blockNumber': 3
   })
)


# Or, if there were errors encountered during processing:
>>> from web3.logs import STRICT, IGNORE, DISCARD, WARN
>>> processed_logs = contract.events.myEvent().process_receipt(tx_receipt, errors=IGNORE)
>>> processed_logs
(
    AttributeDict({
        'type': 'mined',
        'logIndex': 0,
        'transactionIndex': 0,
        'transactionHash': HexBytes('0x01682095d5abb0270d11a31139b9a1f410b363c84add467004e728ec831bd529'),
        'blockHash': HexBytes('0x92abf9325a3959a911a2581e9ea36cba3060d8b293b50e5738ff959feb95258a'),
        'blockNumber': 5,
        'address': '0xF2E246BB76DF876Cef8b38ae84130F4F55De395b',
        'data': '0x0000000000000000000000000000000000000000000000000000000000003039',
        'topics': [
            HexBytes('0xf70fe689e290d8ce2b2a388ac28db36fbb0e16a6d89c6804c461f65a1b40bb15')
        ],
        'errors': LogTopicError('Expected 1 log topics.  Got 0')})
   })
)
>>> processed_logs = contract.events.myEvent().process_receipt(tx_receipt, errors=DISCARD)
>>> assert processed_logs == ()
True

ContractEvents.myEvent(*args, **kwargs).process_log(log)

Similar to process_receipt, but only processes one log at a time, instead of a whole transaction receipt. Will return a single Event Log Object if there are no errors encountered during processing. If an error is encountered during processing, it will be raised.

>>> tx_hash = contract.functions.myFunction(12345).transact({'to':contract_address})
>>> tx_receipt = w3.eth.get_transaction_receipt(tx_hash)
>>> log_to_process = tx_receipt['logs'][0]
>>> processed_log = contract.events.myEvent().process_log(log_to_process)
>>> processed_log
AttributeDict({
    'args': AttributeDict({}),
    'event': 'myEvent',
    'logIndex': 0,
    'transactionIndex': 0,
    'transactionHash': HexBytes('0xfb95ccb6ab39e19821fb339dee33e7afe2545527725b61c64490a5613f8d11fa'),
    'address': '0xF2E246BB76DF876Cef8b38ae84130F4F55De395b',
    'blockHash': HexBytes('0xd74c3e8bdb19337987b987aee0fa48ed43f8f2318edfc84e3a8643e009592a68'),
    'blockNumber': 3
})

Event Log Object

The Event Log Object is a python dictionary with the following keys:

args: Dictionary - The arguments coming from the event.

event: String - The event name.

logIndex: Number - integer of the log index position in the block.

transactionIndex: Number - integer of the transactions index position log was created from.

transactionHash: String, 32 Bytes - hash of the transactions this log was created from.

address: String, 32 Bytes - address from which this log originated.

blockHash: String, 32 Bytes - hash of the block where this log was in. null when it’s pending.

blockNumber: Number - the block number where this log was in. null when it’s pending.

>>> transfer_filter = my_token_contract.events.Transfer.create_filter(from_block="0x0", argument_filters={'from': '0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf'})
>>> transfer_filter.get_new_entries()
[AttributeDict({'args': AttributeDict({'from': '0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf',
 'to': '0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf',
 'value': 10}),
 'event': 'Transfer',
 'logIndex': 0,
 'transactionIndex': 0,
 'transactionHash': HexBytes('0x9da859237e7259832b913d51cb128c8d73d1866056f7a41b52003c953e749678'),
 'address': '0xF2E246BB76DF876Cef8b38ae84130F4F55De395b',
 'blockHash': HexBytes('...'),
 'blockNumber': 2})]
>>> transfer_filter.get_new_entries()
[]
>>> tx_hash = contract.functions.transfer(alice, 10).transact({'gas': 899000, 'gasPrice': 1000000000})
>>> tx_receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
>>> transfer_filter.get_new_entries()
[AttributeDict({'args': AttributeDict({'from': '0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf',
 'to': '0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf',
 'value': 10}),
 'event': 'Transfer',
 'logIndex': 0,
 'transactionIndex': 0,
 'transactionHash': HexBytes('...'),
 'address': '0xF2E246BB76DF876Cef8b38ae84130F4F55De395b',
 'blockHash': HexBytes('...'),
 'blockNumber': 3})]
>>> transfer_filter.get_all_entries()
[AttributeDict({'args': AttributeDict({'from': '0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf',
 'to': '0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf',
 'value': 10}),
 'event': 'Transfer',
 'logIndex': 0,
 'transactionIndex': 0,
 'transactionHash': HexBytes('...'),
 'address': '0xF2E246BB76DF876Cef8b38ae84130F4F55De395b',
 'blockHash': HexBytes('...'),
 'blockNumber': 2}),
 AttributeDict({'args': AttributeDict({'from': '0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf',
 'to': '0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf',
 'value': 10}),
 'event': 'Transfer',
 'logIndex': 0,
 'transactionIndex': 0,
 'transactionHash': HexBytes('...'),
 'address': '0xF2E246BB76DF876Cef8b38ae84130F4F55De395b',
 'blockHash': HexBytes('...'),
 'blockNumber': 3})]

Utils

classmethod Contract.decode_function_input(data)

Decodes the transaction data used to invoke a smart contract function, and returns ContractFunction and decoded parameters as dict.

>>> transaction = w3.eth.get_transaction('0x5798fbc45e3b63832abc4984b0f3574a13545f415dd672cd8540cd71f735db56')
>>> transaction.input
'0x612e45a3000000000000000000000000b656b2a9c3b2416437a811e07466ca712f5a5b5a000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000c000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000093a80000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000116c6f6e656c792c20736f206c6f6e656c7900000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000'
>>> contract.decode_function_input(transaction.input)
(<Function newProposal(address,uint256,string,bytes,uint256,bool)>,
 {'_recipient': '0xB656b2a9c3b2416437A811e07466cA712F5a5b5a',
  '_amount': 0,
  '_description': b'lonely, so lonely',
  '_transactionData': b'',
  '_debatingPeriod': 604800,
  '_newCurator': True})

ContractCaller

class web3.contract.ContractCaller

The ContractCaller class provides an API to call functions in a contract. This class is not to be used directly, but instead through Contract.caller.

There are a number of different ways to invoke the ContractCaller.

For example:

>>> myContract = w3.eth.contract(address=address, abi=ABI)
>>> twentyone = myContract.caller.multiply7(3)
>>> twentyone
21

It can also be invoked using parentheses:

>>> twentyone = myContract.caller().multiply7(3)
>>> twentyone
21

And a transaction dictionary, with or without the transaction keyword. You can also optionally include a block identifier. For example:

>>> from_address = w3.eth.accounts[1]
>>> twentyone = myContract.caller({'from': from_address}).multiply7(3)
>>> twentyone
21
>>> twentyone = myContract.caller(transaction={'from': from_address}).multiply7(3)
>>> twentyone
21
>>> twentyone = myContract.caller(block_identifier='latest').multiply7(3)
>>> twentyone
21

Like ContractFunction, ContractCaller provides methods to interact with contract functions. Positional and keyword arguments supplied to the contract caller subclass will be used to find the contract function by signature, and forwarded to the contract function when applicable.

Examples

Working with an ERC-20 Token Contract

Most fungible tokens on the Ethereum blockchain conform to the ERC-20 standard. This section of the guide covers interacting with an existing token contract which conforms to this standard.

In this guide we will interact with an existing token contract that we have already deployed to a local testing chain. This guide assumes:

An existing token contract at a known address.
Access to the proper ABI for the given contract.
A web3.main.Web3 instance connected to a provider with an unlocked account which can send transactions.

Creating the contract factory

First we need to create a contract instance with the address of our token contract and the ERC-20 ABI.

>>> contract = w3.eth.contract(contract_address, abi=ABI)
>>> contract.address
'0xF2E246BB76DF876Cef8b38ae84130F4F55De395b'

Querying token metadata

Each token will have a total supply which represents the total number of tokens in circulation. In this example we’ve initialized the token contract to have 1 million tokens. Since this token contract is setup to have 18 decimal places, the raw total supply returned by the contract is going to have 18 additional decimal places.

>>> contract.functions.name().call()
'TestToken'
>>> contract.functions.symbol().call()
'TEST'
>>> decimals = contract.functions.decimals().call()
>>> decimals
18
>>> DECIMALS = 10 ** decimals
>>> contract.functions.totalSupply().call() // DECIMALS
1000000

Query account balances

Next we can query some account balances using the contract’s balanceOf function. The token contract we are using starts with a single account which we’ll refer to as alice holding all of the tokens.

>>> alice = '0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf'
>>> bob = '0x2B5AD5c4795c026514f8317c7a215E218DcCD6cF'
>>> raw_balance = contract.functions.balanceOf(alice).call()
>>> raw_balance
1000000000000000000000000
>>> raw_balance // DECIMALS
1000000
>>> contract.functions.balanceOf(bob).call()
0

Sending tokens

Next we can transfer some tokens from alice to bob using the contract’s transfer function.

>>> tx_hash = contract.functions.transfer(bob, 100).transact({'from': alice})
>>> tx_receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
>>> contract.functions.balanceOf(alice).call()
999999999999999999999900
>>> contract.functions.balanceOf(bob).call()
100

Creating an approval for external transfers

Alice could also approve someone else to spend tokens from her account using the approve function. We can also query how many tokens we’re approved to spend using the allowance function.

>>> contract.functions.allowance(alice, bob).call()
0
>>> tx_hash = contract.functions.approve(bob, 200).transact({'from': alice})
>>> tx_receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
>>> contract.functions.allowance(alice, bob).call()
200

Performing an external transfer

When someone has an allowance they can transfer those tokens using the transferFrom function.

>>> contract.functions.allowance(alice, bob).call()
200
>>> contract.functions.balanceOf(bob).call()
100
>>> tx_hash = contract.functions.transferFrom(alice, bob, 75).transact({'from': bob})
>>> tx_receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
>>> contract.functions.allowance(alice, bob).call()
125
>>> contract.functions.balanceOf(bob).call()
175

Using a struct as a function argument

web3.py accepts struct arguments as dictionaries. This format also supports nested structs. Let’s take a look at a quick example. Given the following Solidity contract:

contract Example {
  address addr;

  struct S1 {
    address a1;
    address a2;
  }

  struct S2 {
    bytes32 b1;
    bytes32 b2;
  }

  struct X {
    S1 s1;
    S2 s2;
    address[] users;
  }

  function update(X memory x) public {
    addr = x.s1.a2;
  }

  function retrieve() public view returns (address) {
    return addr;
  }
}

You can interact with the web3.py contract API as follows:

# deploy or lookup the deployed contract, then:

>>> deployed_contract.functions.retrieve().call()
'0x0000000000000000000000000000000000000000'

>>> deployed_contract.functions.update({'s1': ['0x0000000000000000000000000000000000000001', '0x0000000000000000000000000000000000000002'], 's2': [b'0'*32, b'1'*32], 'users': []}).transact()

>>> deployed_contract.functions.retrieve().call()
'0x0000000000000000000000000000000000000002'

Invoke Ambiguous Contract Functions

Below is an example of a contract that has multiple functions of the same name, and the arguments are ambiguous. You can use the Contract.get_function_by_signature() method to reference the intended function and call it with the correct arguments.

>>> contract_source_code = """
pragma solidity ^0.8.24;
contract AmbiguousDuo {
  function identity(uint256 input, bool uselessFlag) public pure returns (uint256) {
    return input;
  }
  function identity(int256 input, bool uselessFlag) public pure returns (int256) {
    return input;
  }
}
"""
# fast forward all the steps of compiling and deploying the contract.
>>> ambiguous_contract.functions.identity(1, True) # raises Web3ValidationError

>>> identity_func = ambiguous_contract.get_function_by_signature('identity(uint256,bool)')
>>> identity_func(1, True)
<Function identity(uint256,bool) bound to (1, True)>
>>> identity_func(1, True).call()
1

CCIP Read support for offchain lookup

Contract calls support CCIP Read by default, via a ccip_read_enabled flag on the call and, more globally, a global_ccip_read_enabled flag on the provider. The following should work by default without raising an OffchainLookup and instead handling it appropriately as per the specification outlined in EIP-3668.

myContract.functions.revertsWithOffchainLookup(myData).call()

If the offchain lookup requires the user to send a transaction rather than make a call, this may be handled appropriately in the following way:

from web3 import Web3, WebSocketProvider
from web3.utils import handle_offchain_lookup

w3 = Web3(WebSocketProvider(...))

myContract = w3.eth.contract(address=...)
myData = b'data for offchain lookup function call'

# preflight with an `eth_call` and handle the exception
try:
    myContract.functions.revertsWithOffchainLookup(myData).call(ccip_read_enabled=False)
except OffchainLookup as ocl:
    tx = {'to': myContract.address, 'from': my_account}
    data_for_callback_function = handle_offchain_lookup(ocl.payload)
    tx['data'] = data_for_callback_function

    # send the built transaction with `eth_sendTransaction` or sign and send with `eth_sendRawTransaction`
    tx_hash = w3.eth.send_transaction(tx)

Contract Unit Tests in Python

Here is an example of how one can use the pytest framework in python, web3.py, eth-tester, and PyEVM to perform unit tests entirely in python without any additional need for a full featured ethereum node/client. To install needed dependencies you can use the pinned extra for eth_tester in web3 and pytest:

$ pip install web3[tester] pytest

Once you have an environment set up for testing, you can then write your tests like so:

# of how to write unit tests with web3.py
import pytest

import pytest_asyncio

from web3 import (
    AsyncWeb3,
    EthereumTesterProvider,
    Web3,
)
from web3.providers.eth_tester.main import (
    AsyncEthereumTesterProvider,
)


@pytest.fixture
def tester_provider():
    return EthereumTesterProvider()


@pytest.fixture
def eth_tester(tester_provider):
    return tester_provider.ethereum_tester


@pytest.fixture
def w3(tester_provider):
    return Web3(tester_provider)


@pytest.fixture
def foo_contract(eth_tester, w3):
    # For simplicity of this example we statically define the
    # contract code here. You might read your contracts from a
    # file, or something else to test with in your own code
    #
    # pragma solidity^0.5.3;
    #
    # contract Foo {
    #
    #     string public bar;
    #     event barred(string _bar);
    #
    #     constructor() public {
    #         bar = "hello world";
    #     }
    #
    #     function setBar(string memory _bar) public {
    #         bar = _bar;
    #         emit barred(_bar);
    #     }
    #
    # }

    deploy_address = eth_tester.get_accounts()[0]

    abi = """[{"anonymous":false,"inputs":[{"indexed":false,"name":"_bar","type":"string"}],"name":"barred","type":"event"},{"constant":false,"inputs":[{"name":"_bar","type":"string"}],"name":"setBar","outputs":[],"payable":false,"stateMutability":"nonpayable","type":"function"},{"inputs":[],"payable":false,"stateMutability":"nonpayable","type":"constructor"},{"constant":true,"inputs":[],"name":"bar","outputs":[{"name":"","type":"string"}],"payable":false,"stateMutability":"view","type":"function"}]"""  # noqa: E501
    # This bytecode is the output of compiling with
    # solc version:0.5.3+commit.10d17f24.Emscripten.clang
    bytecode = """608060405234801561001057600080fd5b506040805190810160405280600b81526020017f68656c6c6f20776f726c640000000000000000000000000000000000000000008152506000908051906020019061005c929190610062565b50610107565b828054600181600116156101000203166002900490600052602060002090601f016020900481019282601f106100a357805160ff19168380011785556100d1565b828001600101855582156100d1579182015b828111156100d05782518255916020019190600101906100b5565b5b5090506100de91906100e2565b5090565b61010491905b808211156101005760008160009055506001016100e8565b5090565b90565b6103bb806101166000396000f3fe608060405234801561001057600080fd5b5060043610610053576000357c01000000000000000000000000000000000000000000000000000000009004806397bc14aa14610058578063febb0f7e14610113575b600080fd5b6101116004803603602081101561006e57600080fd5b810190808035906020019064010000000081111561008b57600080fd5b82018360208201111561009d57600080fd5b803590602001918460018302840111640100000000831117156100bf57600080fd5b91908080601f016020809104026020016040519081016040528093929190818152602001838380828437600081840152601f19601f820116905080830192505050505050509192919290505050610196565b005b61011b61024c565b6040518080602001828103825283818151815260200191508051906020019080838360005b8381101561015b578082015181840152602081019050610140565b50505050905090810190601f1680156101885780820380516001836020036101000a031916815260200191505b509250505060405180910390f35b80600090805190602001906101ac9291906102ea565b507f5f71ad82e16f082de5ff496b140e2fbc8621eeb37b36d59b185c3f1364bbd529816040518080602001828103825283818151815260200191508051906020019080838360005b8381101561020f5780820151818401526020810190506101f4565b50505050905090810190601f16801561023c5780820380516001836020036101000a031916815260200191505b509250505060405180910390a150565b60008054600181600116156101000203166002900480601f0160208091040260200160405190810160405280929190818152602001828054600181600116156101000203166002900480156102e25780601f106102b7576101008083540402835291602001916102e2565b820191906000526020600020905b8154815290600101906020018083116102c557829003601f168201915b505050505081565b828054600181600116156101000203166002900490600052602060002090601f016020900481019282601f1061032b57805160ff1916838001178555610359565b82800160010185558215610359579182015b8281111561035857825182559160200191906001019061033d565b5b509050610366919061036a565b5090565b61038c91905b80821115610388576000816000905550600101610370565b5090565b9056fea165627a7a72305820ae6ca683d45ee8a71bba45caee29e4815147cd308f772c853a20dfe08214dbb50029"""  # noqa: E501

    # Create our contract class.
    FooContract = w3.eth.contract(abi=abi, bytecode=bytecode)
    # issue a transaction to deploy the contract.
    tx_hash = FooContract.constructor().transact(
        {
            "from": deploy_address,
        }
    )
    # wait for the transaction to be mined
    tx_receipt = w3.eth.wait_for_transaction_receipt(tx_hash, 180)
    # instantiate and return an instance of our contract.
    return FooContract(tx_receipt.contractAddress)


def test_initial_greeting(foo_contract):
    hw = foo_contract.caller.bar()
    assert hw == "hello world"


def test_can_update_greeting(w3, foo_contract):
    # send transaction that updates the greeting
    tx_hash = foo_contract.functions.setBar("testing contracts is easy").transact(
        {
            "from": w3.eth.accounts[1],
        }
    )
    w3.eth.wait_for_transaction_receipt(tx_hash, 180)

    # verify that the contract is now using the updated greeting
    hw = foo_contract.caller.bar()
    assert hw == "testing contracts is easy"


def test_updating_greeting_emits_event(w3, foo_contract):
    # send transaction that updates the greeting
    tx_hash = foo_contract.functions.setBar("testing contracts is easy").transact(
        {
            "from": w3.eth.accounts[1],
        }
    )
    receipt = w3.eth.wait_for_transaction_receipt(tx_hash, 180)

    # get all of the `barred` logs for the contract
    logs = foo_contract.events.barred.get_logs()
    assert len(logs) == 1

    # verify that the log's data matches the expected value
    event = logs[0]
    assert event.blockHash == receipt.blockHash
    assert event.args._bar == "testing contracts is easy"


@pytest.fixture
def async_eth_tester():
    return AsyncEthereumTesterProvider().ethereum_tester


@pytest_asyncio.fixture()
async def async_w3():
    async_w3 = AsyncWeb3(AsyncEthereumTesterProvider())
    accounts = await async_w3.eth.accounts
    async_w3.eth.default_account = accounts[0]
    return async_w3


@pytest_asyncio.fixture()
async def async_foo_contract(async_w3):
    # For simplicity of this example we statically define the
    # contract code here. You might read your contracts from a
    # file, or something else to test with in your own code
    #
    # pragma solidity^0.5.3;
    #
    # contract Foo {
    #
    #     string public bar;
    #     event barred(string _bar);
    #
    #     constructor() public {
    #         bar = "hello world";
    #     }
    #
    #     function setBar(string memory _bar) public {
    #         bar = _bar;
    #         emit barred(_bar);
    #     }
    #
    # }

    abi = """[{"anonymous":false,"inputs":[{"indexed":false,"name":"_bar","type":"string"}],"name":"barred","type":"event"},{"constant":false,"inputs":[{"name":"_bar","type":"string"}],"name":"setBar","outputs":[],"payable":false,"stateMutability":"nonpayable","type":"function"},{"inputs":[],"payable":false,"stateMutability":"nonpayable","type":"constructor"},{"constant":true,"inputs":[],"name":"bar","outputs":[{"name":"","type":"string"}],"payable":false,"stateMutability":"view","type":"function"}]"""  # noqa: E501
    # This bytecode is the output of compiling with
    # solc version:0.5.3+commit.10d17f24.Emscripten.clang
    bytecode = """608060405234801561001057600080fd5b506040805190810160405280600b81526020017f68656c6c6f20776f726c640000000000000000000000000000000000000000008152506000908051906020019061005c929190610062565b50610107565b828054600181600116156101000203166002900490600052602060002090601f016020900481019282601f106100a357805160ff19168380011785556100d1565b828001600101855582156100d1579182015b828111156100d05782518255916020019190600101906100b5565b5b5090506100de91906100e2565b5090565b61010491905b808211156101005760008160009055506001016100e8565b5090565b90565b6103bb806101166000396000f3fe608060405234801561001057600080fd5b5060043610610053576000357c01000000000000000000000000000000000000000000000000000000009004806397bc14aa14610058578063febb0f7e14610113575b600080fd5b6101116004803603602081101561006e57600080fd5b810190808035906020019064010000000081111561008b57600080fd5b82018360208201111561009d57600080fd5b803590602001918460018302840111640100000000831117156100bf57600080fd5b91908080601f016020809104026020016040519081016040528093929190818152602001838380828437600081840152601f19601f820116905080830192505050505050509192919290505050610196565b005b61011b61024c565b6040518080602001828103825283818151815260200191508051906020019080838360005b8381101561015b578082015181840152602081019050610140565b50505050905090810190601f1680156101885780820380516001836020036101000a031916815260200191505b509250505060405180910390f35b80600090805190602001906101ac9291906102ea565b507f5f71ad82e16f082de5ff496b140e2fbc8621eeb37b36d59b185c3f1364bbd529816040518080602001828103825283818151815260200191508051906020019080838360005b8381101561020f5780820151818401526020810190506101f4565b50505050905090810190601f16801561023c5780820380516001836020036101000a031916815260200191505b509250505060405180910390a150565b60008054600181600116156101000203166002900480601f0160208091040260200160405190810160405280929190818152602001828054600181600116156101000203166002900480156102e25780601f106102b7576101008083540402835291602001916102e2565b820191906000526020600020905b8154815290600101906020018083116102c557829003601f168201915b505050505081565b828054600181600116156101000203166002900490600052602060002090601f016020900481019282601f1061032b57805160ff1916838001178555610359565b82800160010185558215610359579182015b8281111561035857825182559160200191906001019061033d565b5b509050610366919061036a565b5090565b61038c91905b80821115610388576000816000905550600101610370565b5090565b9056fea165627a7a72305820ae6ca683d45ee8a71bba45caee29e4815147cd308f772c853a20dfe08214dbb50029"""  # noqa: E501

    # Create our contract class.
    FooContract = async_w3.eth.contract(abi=abi, bytecode=bytecode)
    # issue a transaction to deploy the contract.
    tx_hash = await FooContract.constructor().transact(
        {
            "from": async_w3.eth.default_account,
        }
    )
    # wait for the transaction to be mined
    tx_receipt = await async_w3.eth.wait_for_transaction_receipt(tx_hash, 180)
    # instantiate and return an instance of our contract.
    return FooContract(tx_receipt["contractAddress"])


@pytest.mark.asyncio
async def test_async_initial_greeting(async_foo_contract):
    hw = await async_foo_contract.caller.bar()
    assert hw == "hello world"


@pytest.mark.asyncio
async def test_async_can_update_greeting(async_w3, async_foo_contract):
    tx_hash = await async_foo_contract.functions.setBar(
        "testing contracts is easy",
    ).transact(
        {
            "from": async_w3.eth.default_account,
        }
    )
    await async_w3.eth.wait_for_transaction_receipt(tx_hash, 180)

    # verify that the contract is now using the updated greeting
    hw = await async_foo_contract.caller.bar()
    assert hw == "testing contracts is easy"


@pytest.mark.asyncio
async def test_async_updating_greeting_emits_event(async_w3, async_foo_contract):
    # send transaction that updates the greeting
    tx_hash = await async_foo_contract.functions.setBar(
        "testing contracts is easy",
    ).transact(
        {
            "from": async_w3.eth.default_account,
        }
    )
    receipt = await async_w3.eth.wait_for_transaction_receipt(tx_hash, 180)

    # get all of the `barred` logs for the contract
    logs = await async_foo_contract.events.barred.get_logs()
    assert len(logs) == 1

    # verify that the log's data matches the expected value
    event = logs[0]
    assert event.blockHash == receipt.blockHash
    assert event.args._bar == "testing contracts is easy"