Network API

The network package holds classes for interacting with the Ethereum blockchain. This is the most extensive package within Brownie and contains the majority of the user-facing functionality.

brownie.network.main

The main module contains methods for connecting to or disconnecting from the network. All of these methods are available directly from brownie.network.

main.connect(network=None, launch_rpc=True)

Connects to a network.

• network: The network to connect to. If None, connects to the default network as specified in the config file.

• launch_rpc: If True and the configuration for this network includes test_rpc settings, attempts to launch or attach to a local RPC client.

Calling this method is favored over calling web3.connect and rpc.launch or rpc.attach individually.

>>> from brownie import network
>>> network.connect('development')

main.disconnect(kill_rpc=True)

Disconnects from the network.

The Web3 provider is cleared, the active network is set to None and the local RPC client is terminated if it was launched as a child process.

>>> from brownie import network
>>> network.disconnect()

main.is_connected() → bool

Returns True if the Web3 object is connected to the network.

>>> from brownie import network
>>> network.is_connected()
True

main.show_active()

Returns the name of the network that is currently active, or None if not connected.

>>> from brownie import network
>>> network.show_active()
'development'

main.gas_limit(*args)

Gets and optionally sets the default gas limit.

• If no argument is given, the current default is displayed.

• If an integer value is given, this will be the default gas limit.

• If set to "auto", the gas limit is determined automatically via web3.eth.estimate_gas.

Returns False if the gas limit is set automatically, or an int if it is set to a fixed value.

>>> from brownie import network
>>> network.gas_limit()
False
>>> network.gas_limit(6700000)
6700000
>>> network.gas_limit("auto")
False

main.gas_buffer(*args)

Gets and optionally sets the default gas buffer.

• If no argument is given, the current default is displayed.

• If an integer or float value is given, this will be the default gas buffer.

• If None is given, the gas buffer is set to 1 (disabled).

>>> from brownie import network
>>> network.gas_buffer()
1.1
>>> network.gas_buffer(1.25)
1.25
>>> network.gas_buffer(None)
1

main.gas_price(*args)

Gets and optionally sets the default gas price.

• If an integer value is given, this will be the default gas price.

• If set to "auto", the gas price is determined automatically via web3.eth.gas_price.

Returns False if the gas price is set automatically, or an int if it is set to a fixed value.

>>> from brownie import network
>>> network.gas_price()
False
>>> network.gas_price(10000000000)
10000000000
>>> network.gas_price("1.2 gwei")
1200000000
>>> network.gas_price("auto")
False

main.max_fee(*args)

Gets and optionally sets the default max fee per gas.

• If an integer value is given, this will be the default max fee.

• If set to None or False, transactions will instead default to using a legacy-style gas_price.

>>> from brownie import network
>>> network.max_fee()
None
>>> network.max_fee(10000000000)
10000000000
>>> network.max_fee("45 gwei")
45000000000

main.priority_fee(*args)

Gets and optionally sets the default max priority fee per gas.

• If an integer value is given, this will be the default priority fee.

• If set to "auto", the fee is determined automatically via web3.eth.max_priority_fee.

• If set to None or False, transactions will instead default to using a legacy-style gas_price.

>>> from brownie import network
>>> network.priority_fee()
None
>>> network.priority_fee(4000000000)
4000000000
>>> network.priority_fee("2 gwei")
2000000000

brownie.network.account

The account module holds classes for interacting with Ethereum accounts for which you control the private key.

Classes in this module are not meant to be instantiated directly. The Accounts container is available as accounts (or just a) and will create each Account automatically during initialization. Add more accounts using Accounts.add.

Accounts

class brownie.network.account.Accounts

List-like Singleton container that holds all of the available accounts as Account or LocalAccount objects. When printed it will display as a list.

>>> from brownie.network import accounts
>>> accounts
[<Account object '0x7Ebaa12c5d1EE7fD498b51d4F9278DC45f8D627A'>, <Account object '0x186f79d227f5D819ACAB0C529031036D11E0a000'>, <Account object '0xC53c27492193518FE9eBff00fd3CBEB6c434Cf8b'>, <Account object '0x2929AF7BBCde235035ED72029c81b71935c49e94'>, <Account object '0xb93538FEb07b3B8433BD394594cA3744f7ee2dF1'>, <Account object '0x1E563DBB05A10367c51A751DF61167dE99A4d0A7'>, <Account object '0xa0942deAc0885096D8400D3369dc4a2dde12875b'>, <Account object '0xf427a9eC1d510D77f4cEe4CF352545071387B2e6'>, <Account object '0x2308D528e4930EFB4aF30793A3F17295a0EFa886'>, <Account object '0x2fb37EB570B1eE8Eda736c1BD1E82748Ec3d0Bf1'>]
>>> dir(accounts)
[add, at, clear, load, remove]

Accounts Attributes

Accounts.default

Default account that is used for deploying contracts. Initially set to None.

Note that the default account used to send contract transactions is the one that deployed the contract, not accounts.default.

>>> accounts.default = accounts[1]

Accounts Methods

classmethod Accounts.add(private_key=None)

Creates a new LocalAccount with private key private_key, appends it to the container, and returns the new account instance.

>>> accounts.add('8fa2fdfb89003176a16b707fc860d0881da0d1d8248af210df12d37860996fb2')
<Account object '0xc1826925377b4103cC92DeeCDF6F96A03142F37a'>

When no private key is given a new one is randomly generated. A seed phrase for the account is also printed to the console.

>>> accounts.add()
mnemonic: 'buffalo cinnamon glory chalk require inform strike ginger crop sell hidden cart'
<LocalAccount '0xf293C5E0b22802Bf5DCef3FB8112EaA4cA54fcCF'>

classmethod Accounts.at(address, force=False)

Given an address as a string, returns the corresponding Account or LocalAccount from the container. If force=True, returns and adds the account even if it is not found in the container. Use this if an account is unlocked by external means.

>>> accounts.at('0xc1826925377b4103cC92DeeCDF6F96A03142F37a')
<Account object '0xc1826925377b4103cC92DeeCDF6F96A03142F37a'>

classmethod Accounts.clear()

Empties the container.

>>> accounts.clear()

classmethod Accounts.from_mnemonic(mnemonic, count=1, offset=0)

Generates one or more LocalAccount objects from a seed phrase.

• mnemonic : Space-separated list of BIP39 mnemonic seed words

• count : The number of LocalAccount objects to create

• offset : The initial account index to create accounts from

If count is greater than 1, a list of LocalAccount objects are returned.

>>> a.from_mnemonic('buffalo cinnamon glory chalk require inform strike ginger crop sell hidden cart')
<LocalAccount '0xf293C5E0b22802Bf5DCef3FB8112EaA4cA54fcCF'>

classmethod Accounts.load(filename=None)

Decrypts a keystore file and returns a LocalAccount object.

Brownie will first attempt to find the keystore file as a path relative to the loaded project. If not found, it will look in the brownie/data/accounts folder within the Brownie package.

If filename is None, returns a list of available keystores in brownie/data/accounts.

>>> accounts.load()
['my_account']
>>> accounts.load('my_account')
Enter the password for this account:
<LocalAccount object '0xa9c2DD830DfFE8934fEb0A93BAbcb6e823e1FF05'>

classmethod Accounts.remove(address)

Removes an address from the container. The address may be given as a string or an Account instance.

>>> accounts.remove('0xc1826925377b4103cC92DeeCDF6F96A03142F37a')

classmethod Accounts.connect_to_clef(uri=None, timeout=120)

Connect to clef and add unlocked accounts to the container as ClefAccount objects.

Clef is an account signing utility packaged with Geth, which can be used to interact with hardware wallets in Brownie. Before calling this function, Clef must be running and unlocked in another command prompt.

• uri: IPC path or http url to use to connect to clef. If None, uses clef’s default IPC path on Unix systems or http://localhost:8550/ on Windows.

• timeout: The number of seconds to wait for clef to respond to a request before raising a TimeoutError.

>>> accounts
[]
>>> accounts.connect_to_clef()
>>> accounts
[<ClefAccount object '0x716E8419F2926d6AcE07442675F476ace972C580'>]

classmethod Accounts.disconnect_from_clef()

Disconnect from Clef.

Removes all ClefAccount objects from the container.

Accounts Internal Methods

classmethod Accounts._reset()

Called by state._notify_registry when the local chain has been reset. All Account objects are recreated.

classmethod Accounts._revert(height)

Called by state._notify_registry when the local chain has been reverted to a block height greater than zero. Adjusts Account object nonce values.

Account

class brownie.network.account.Account

An ethereum address that you control the private key for, and so can send transactions from. Generated automatically from web3.eth.accounts and stored in the Accounts container.

>>> accounts[0]
<Account object '0x7Ebaa12c5d1EE7fD498b51d4F9278DC45f8D627A'>
>>> dir(accounts[0])
[address, balance, deploy, estimate_gas, nonce, transfer]

Account Attributes

Account.address

The public address of the account. Viewable by printing the class, you do not need to call this attribute directly.

>>> accounts[0].address
'0x7Ebaa12c5d1EE7fD498b51d4F9278DC45f8D627A'

Account.gas_used

The cumulative gas amount paid for transactions from this account.

>>> accounts[0].gas_used
21000

Account.nonce

The current nonce of the address.

>>> accounts[0].nonce
1

Account Methods

classmethod Account.balance()

Returns the current balance at the address, in Wei.

>>> accounts[0].balance()
100000000000000000000
>>> accounts[0].balance() == "100 ether"
True

classmethod Account.deploy(contract, *args, amount=None, gas_limit=None, gas_price=None, max_fee=None, priority_fee=None, nonce=None, required_confs=1, allow_revert=False, silent=False, publish_source=False)

Deploys a contract.

• contract: A ContractContainer instance of the contract to be deployed.

• *args: Contract constructor arguments.

• amount: Amount of ether to send with the transaction. The given value is converted to Wei.

• gas_limit: Gas limit for the transaction. The given value is converted to Wei. If none is given, the price is set using web3.eth.estimate_gas.

• gas_buffer: A multiplier applied to web3.eth.estimate_gas when setting gas limit automatically. gas_limit and gas_buffer cannot be given at the same time.

• gas_price: Gas price for legacy transaction. The given value is converted to Wei. If none is given, the price is set using web3.eth.gas_price.

• max_fee: Max fee per gas of dynamic fee transaction.

• priority_fee: Max priority fee per gas of dynamic fee transaction.

• nonce: Nonce for the transaction. If none is given, the nonce is set using web3.eth.get_transaction_count while also considering any pending transactions of the Account.

• required_confs: The required confirmations before the TransactionReceipt is processed. If none is given, defaults to 1 confirmation. If 0 is given, immediately returns a pending TransactionReceipt instead of a Contract instance, while waiting for a confirmation in a separate thread.

• allow_revert: When True, forces the deployment of a contract, even if a revert reason is detected.

• silent: When True, suppresses any console output for the deployment.

• publish_source: When True, attempts to verify the source code on etherscan.io.

Returns a Contract instance upon success. If the transaction reverts or you do not wait for a confirmation, a TransactionReceipt is returned instead.

>>> Token
[]
>>> t = accounts[0].deploy(Token, "Test Token", "TST", 18, "1000 ether")

Transaction sent: 0x2e3cab83342edda14141714ced002e1326ecd8cded4cd0cf14b2f037b690b976
Transaction confirmed - block: 1   gas spent: 594186
Contract deployed at: 0x5419710735c2D6c3e4db8F30EF2d361F70a4b380
<Token Contract object '0x5419710735c2D6c3e4db8F30EF2d361F70a4b380'>
>>>
>>> t
<Token Contract object '0x5419710735c2D6c3e4db8F30EF2d361F70a4b380'>
>>> Token
[<Token Contract object '0x5419710735c2D6c3e4db8F30EF2d361F70a4b380'>]
>>> Token[0]
<Token Contract object '0x5419710735c2D6c3e4db8F30EF2d361F70a4b380'>

classmethod Account.estimate_gas(to=None, amount=0, gas_price=None, data='')

Estimates the gas required to perform a transaction. Raises a func:VirtualMachineError <brownie.exceptions.VirtualMachineError> if the transaction would revert.

The returned value is given as an int denominated in wei.

• to: Recipient address. Can be an Account instance or string.

• amount: Amount of ether to send. The given value is converted to Wei.

• gas_price: Gas price of the transaction.

• data: Transaction data hexstring.

>>> accounts[0].estimate_gas(accounts[1], "1 ether")
21000

classmethod Account.get_deployment_address(nonce=None)

Return the address where a contract will be deployed from this account, if the deployment transaction uses the given nonce.

If nonce is None, the nonce of the next transaction is used.

>>> accounts[0].get_deployment_address()
'0xd495633B90a237de510B4375c442C0469D3C161C'

classmethod Account.transfer(self, to=None, amount=0, gas_limit=None, gas_price=None, max_fee=None, priority_fee=None, data=None, nonce=None, required_confs=1, allow_revert=None, silent=False)

Broadcasts a transaction from this account.

• to: Recipient address. Can be an Account instance or string.

• amount: Amount of ether to send. The given value is converted to Wei.

• gas_limit: Gas limit for the transaction. The given value is converted to Wei. If none is given, the price is set using web3.eth.estimate_gas.

• gas_buffer: A multiplier applied to web3.eth.estimate_gas when setting gas limit automatically. gas_limit and gas_buffer cannot be given at the same time.

• gas_price: Gas price for legacy transaction. The given value is converted to Wei. If none is given, the price is set using web3.eth.gas_price.

• max_fee: Max fee per gas of dynamic fee transaction.

• priority_fee: Max priority fee per gas of dynamic fee transaction.

• data: Transaction data hexstring.

• nonce: Nonce for the transaction. If none is given, the nonce is set using web3.eth.get_transaction_count while also considering any pending transactions of the Account.

• required_confs: The required confirmations before the TransactionReceipt is processed. If none is given, defaults to 1 confirmation. If 0 is given, immediately returns a pending TransactionReceipt, while waiting for a confirmation in a separate thread.

• allow_revert: Boolean indicating whether the transaction should be broadcasted when it is expected to revert. If not set, the default behaviour is to allow reverting transactions in development and disallow them in a live environment.

• silent: Toggles console verbosity. If True is given, suppresses all console output for this transaction.

Returns a TransactionReceipt instance.

>>> accounts[0].transfer(accounts[1], "1 ether")

Transaction sent: 0x0173aa6938c3a5e50b6dc7b4d38e16dab40811ab4e00e55f3e0d8be8491c7852
Transaction confirmed - block: 1   gas used: 21000 (100.00%)
<Transaction object '0x0173aa6938c3a5e50b6dc7b4d38e16dab40811ab4e00e55f3e0d8be8491c7852'>

You can also deploy contracts by omitting the to field. Note that deploying with this method does not automatically create a Contract object.

>>> deployment_bytecode = "0x6103f056600035601c52740100..."
>>> accounts[0].transfer(data=deployment_bytecode)
Transaction sent: 0x2b33315f7f9ec86d27112ea6dffb69b6eea1e582d4b6352245c0ac8e614fe06f
  Gas price: 0.0 gwei   Gas limit: 6721975
  Transaction confirmed - Block: 1   Gas used: 268460 (3.99%)
  UnknownContract deployed at: 0x3194cBDC3dbcd3E11a07892e7bA5c3394048Cc87
<Transaction '0x2b33315f7f9ec86d27112ea6dffb69b6eea1e582d4b6352245c0ac8e614fe06f'>

LocalAccount

class brownie.network.account.LocalAccount

Functionally identical to Account. The only difference is that a LocalAccount is one where the private key was directly inputted, and so is not found in web3.eth.accounts.

Note

Resetting the RPC client will delete all LocalAccount objects from the Account container.

>>> accounts.add()
<LocalAccount object '0x716E8419F2926d6AcE07442675F476ace972C580'>
>>> accounts[-1]
<LocalAccount object '0x716E8419F2926d6AcE07442675F476ace972C580'>

LocalAccount Attributes

LocalAccount.public_key

The local account’s public key as a string.

>>> accounts[-1].public_key
'0x34b51e2913f5771acdddea7d353404f844b02a39ad4003c08afaa729993c43e890181327beaf352d81424cd277f4badc55be789a2817ea097bc82ea4801fee5b'

LocalAccount.private_key

The local account’s private key as a string.

>>> accounts[-1].private_key
'0xd289bec8d9ad145aead13911b5bbf01936cbcd0efa0e26d5524b5ad54a61aeb8'

LocalAccount Methods

classmethod LocalAccount.save(filename, overwrite=False)

Saves the account’s private key in an encrypto keystore file.

If the filename does not include a folder, the keystore is saved in the brownie/data/accounts folder within the Brownie package.

Returns the absolute path to the keystore file, as a string.

>>> accounts[-1].save('my_account')
Enter the password to encrypt this account with:
/python3.6/site-packages/brownie/data/accounts/my_account.json
>>>
>>> accounts[-1].save('~/my_account.json')
Enter the password to encrypt this account with:
/home/computer/my_account.json

ClefAccount

class brownie.network.account.ClefAccount

Functionally identical to Account. A ClefAccount object is used for accounts that have been unlocked via clef, and where signing of transactions is handled externally from brownie. This is useful for hardware wallets.

>>> accounts
[]
>>> accounts.connect_to_clef()
>>> accounts
[<ClefAccount object '0x716E8419F2926d6AcE07442675F476ace972C580'>]

PublicKeyAccount

class brownie.network.account.PublicKeyAccount

Object for interacting with an Ethereum account where you do not control the private key. Can be used to check balances or to send ether to that address.

>>> from brownie.network.account import PublicKeyAccount
>>> pub = PublicKeyAccount("0x14b0Ed2a7C4cC60DD8F676AE44D0831d3c9b2a9E")
<PublicKeyAccount object '0x14b0Ed2a7C4cC60DD8F676AE44D0831d3c9b2a9E'>

Along with regular addresses, PublicKeyAccount objects can be instantiated using ENS domain names. The returned object will have the resolved address.

>>> PublicKeyAccount("ens.snakecharmers.eth")
<PublicKeyAccount object '0x808B53bF4D70A24bA5cb720D37A4835621A9df00'>

classmethod PublicKeyAccount.balance()

Returns the current balance at the address, in Wei.

>>> pub.balance()
1000000000000000000

PublicKeyAccount.nonce

The current nonce of the address.

>>> accounts[0].nonce
0

brownie.network.alert

The alert module is used to set up notifications and callbacks based on state changes in the blockchain.

Alert

Alerts and callbacks are handled by creating instances of the Alert class.

class brownie.network.alert.Alert(fn, args=None, kwargs=None, delay=2, msg=None, callback=None, repeat=False)

An alert object. It is active immediately upon creation of the instance.

• fn: A callable to check for the state change.

• args: Arguments to supply to the callable.

• kwargs: Keyword arguments to supply to the callable.

• delay: Number of seconds to wait between checking for changes.

• msg: String to display upon change. The string will have .format(initial_value, new_value) applied before displaying.

• callback: A callback function to call upon a change in value. It should accept two arguments, the initial value and the new value.

• repeat: If False, the alert will terminate after the first time it first. if True, it will continue to fire with each change until it is stopped via Alert.stop(). If an int value is given, it will fire a total of n+1 times before terminating.

Alerts are non-blocking, threading is used to monitor changes. Once an alert has finished running it cannot be restarted.

A basic example of an alert, watching for a changed balance:

>>> from brownie.network.alert import Alert
>>> Alert(accounts[1].balance, msg="Account 1 balance has changed from {} to {}")
<brownie.network.alert.Alert object at 0x7f9fd25d55f8>

>>> alert.show()
[<brownie.network.alert.Alert object at 0x7f9fd25d55f8>]
>>> accounts[2].transfer(accounts[1], "1 ether")

Transaction sent: 0x912d6ac704e7aaac01be159a4a36bbea0dc0646edb205af95b6a7d20945a2fd2
Transaction confirmed - block: 1   gas spent: 21000
<Transaction object '0x912d6ac704e7aaac01be159a4a36bbea0dc0646edb205af95b6a7d20945a2fd2'>
ALERT: Account 1 balance has changed from 100000000000000000000 to 101000000000000000000

This example uses the alert’s callback function to perform a token transfer, and sets a second alert to watch for the transfer:

>>> alert.new(accounts[3].balance, msg="Account 3 balance has changed from {} to {}")
<brownie.network.alert.Alert object at 0x7fc743e415f8>

>>> def on_receive(old_value, new_value):
...     accounts[2].transfer(accounts[3], new_value-old_value)

>>> alert.new(accounts[2].balance, callback=on_receive)
<brownie.network.alert.Alert object at 0x7fc743e55cf8>
>>> accounts[1].transfer(accounts[2],"1 ether")

Transaction sent: 0xbd1bade3862f181359f32dac02ffd1d145fdfefc99103ca0e3d28ffc7071a9eb
Transaction confirmed - block: 1   gas spent: 21000
<Transaction object '0xbd1bade3862f181359f32dac02ffd1d145fdfefc99103ca0e3d28ffc7071a9eb'>

Transaction sent: 0x8fcd15e38eed0a5c9d3d807d593b0ea508ba5abc892428eb2e0bb0b8f7dc3083
Transaction confirmed - block: 2   gas spent: 21000
ALERT: Account 3 balance has changed from 100000000000000000000 to 101000000000000000000

classmethod Alert.is_alive()

Returns a boolean indicating if an alert is currently running.

>>> a.is_alive()
True

classmethod Alert.wait(timeout=None)

Blocks until an alert has completed firing or the timeout value is reached. Similar to Thread.join().

>>> a.wait()

classmethod Alert.stop(wait=True)

Stops the alert.

>>> alert_list = alert.show()
[<brownie.network.alert.Alert object at 0x7f9fd25d55f8>]
>>> alert_list[0].stop()
>>> alert.show()
[]

Module Methods

alert.new(fn, args=[], kwargs={}, delay=0.5, msg=None, callback=None, repeat=False)

Alias for creating a new Alert instance.

>>> from brownie import alert
>>> alert.new(accounts[3].balance, msg="Account 3 balance has changed from {} to {}")
<brownie.network.alert.Alert object at 0x7fc743e415f8>

alert.show()

Returns a list of all currently active alerts.

>>> alert.show()
[<brownie.network.alert.Alert object at 0x7f9fd25d55f8>]

alert.stop_all()

Stops all currently active alerts.

>>> alert.show()
[<brownie.network.alert.Alert object at 0x7f9fd25d55f8>]
>>> alert.stop_all()
>>> alert.show()
[]

brownie.network.contract

The contract module contains classes for deploying and interacting with smart contracts.

When a project is loaded, Brownie automatically creates ContractContainer instances from on the files in the contracts/ folder. New ProjectContract instances are created via methods in the container.

If you wish to interact with a contract outside of a project where only the ABI is available, use the Contract class.

Arguments supplied to calls or transaction methods are converted using the methods outlined in the convert module.

Note

On networks where persistence is enabled, ProjectContract instances will remain between sessions. Use ContractContainer.remove to delete these objects when they are no longer needed. See the documentation on persistence for more information.

ContractContainer

class brownie.network.contract.ContractContainer

A list-like container class that holds all ProjectContract instances of the same type, and is used to deploy new instances of that contract.

>>> Token
[]
>>> dir(Token)
[abi, at, bytecode, deploy, remove, signatures, topics, tx]

ContractContainer Attributes

ContractContainer.abi

The ABI of the contract.

>>> Token.abi
[{'constant': True, 'inputs': [], 'name': 'name', 'outputs': [{'name': '', 'type': 'string'}], 'payable': False, 'stateMutability': 'view', 'type': 'function'}, {'constant': False, 'inputs': [{'name': '_spender', 'type': 'address'}, {'name': '_value', 'type': 'uint256'}], 'name': 'approve', 'outputs': [{'name': '', 'type': 'bool'}], 'payable': False, 'stateMutability': 'nonpayable', 'type': 'function'}, ... ]

ContractContainer.bytecode

The bytecode of the contract, without any applied constructor arguments.

>>> Token.bytecode
'608060405234801561001057600080fd5b506040516107873803806107878339810160409081528151602080840151928401516060850151928501805190959490940193909291610055916000918701906100d0565b5082516100699060019060208601906100d0565b50600282905560038190553360008181526004602090815 ...

ContractContainer.signatures

A dictionary of bytes4 signatures for each contract method.

If you have a signature and need to find the method name, use ContractContainer.get_method.

>>> Token.signatures
{
    'allowance': "0xdd62ed3e",
    'approve': "0x095ea7b3",
    'balanceOf': "0x70a08231",
    'decimals': "0x313ce567",
    'name': "0x06fdde03",
    'symbol': "0x95d89b41",
    'totalSupply': "0x18160ddd",
    'transfer': "0xa9059cbb",
    'transferFrom': "0x23b872dd"
}
>>> Token.signatures.keys()
dict_keys(['name', 'approve', 'totalSupply', 'transferFrom', 'decimals', 'balanceOf', 'symbol', 'transfer', 'allowance'])
>>> Token.signatures['transfer']
0xa9059cbb

ContractContainer.topics

A dict of bytes32 topics for each contract event.

>>> Token.topics
{
    'Approval': "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
    'Transfer': "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
}
>>> Token.topics.keys()
dict_keys(['Transfer', 'Approval'])
>>> Token.topics['Transfer']
0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef

ContractContainer Methods

classmethod ContractContainer.deploy(*args, publish_source=False)

Deploys the contract.

• *args: Contract constructor arguments.

• publish_source: When True, attempts to verify the source code on etherscan.io.

You can optionally include a dict of transaction parameters as the final argument. If you omit this or do not specify a 'from' value, the transaction will be sent from the same address that deployed the contract.

If the contract requires a library, the most recently deployed one will be used. If the required library has not been deployed yet an UndeployedLibrary <brownie.exceptions.UndeployedLibrary> exception is raised.

Returns a ProjectContract object upon success.

In the console if the transaction reverts or you do not wait for a confirmation, a TransactionReceipt is returned instead.

>>> Token
[]
>>> Token.deploy
<ContractConstructor object 'Token.constructor(string,string,uint256,uint256)'>
>>> t = Token.deploy("Test Token", "TST", 18, "1000 ether", {'from': accounts[1]})

Transaction sent: 0x2e3cab83342edda14141714ced002e1326ecd8cded4cd0cf14b2f037b690b976
Transaction confirmed - block: 1   gas spent: 594186
Contract deployed at: 0x5419710735c2D6c3e4db8F30EF2d361F70a4b380
<Token Contract object '0x5419710735c2D6c3e4db8F30EF2d361F70a4b380'>
>>>
>>> t
<Token Contract object '0x5419710735c2D6c3e4db8F30EF2d361F70a4b380'>
>>> Token
[<Token Contract object '0x5419710735c2D6c3e4db8F30EF2d361F70a4b380'>]
>>> Token[0]
<Token Contract object '0x5419710735c2D6c3e4db8F30EF2d361F70a4b380'>

classmethod ContractContainer.at(address, owner=None)

Returns a new Contract or ProjectContract object. The object is also appended to the container.

• address: Address where the contract is deployed.

• owner: Account instance to set as the contract owner. If transactions to the contract do not specify a 'from' value, they will be sent from this account.

This method compares the bytecode at the given address with the deployment bytecode for the given ContractContainer. A ProjectContract is returned if the bytecodes match, a Contract otherwise.

Raises ContractNotFound if there is no code at the given address.

>>> Token
[<Token Contract object '0x79447c97b6543F6eFBC91613C655977806CB18b0'>]
>>> Token.at('0x79447c97b6543F6eFBC91613C655977806CB18b0')
<Token Contract object '0x79447c97b6543F6eFBC91613C655977806CB18b0'>
>>> Token.at('0xefb1336a2E6B5dfD83D4f3a8F3D2f85b7bfb61DC')
File "brownie/lib/console.py", line 82, in _run
    exec('_result = ' + cmd, self.__dict__, local_)
File "<string>", line 1, in <module>
File "brownie/lib/components/contract.py", line 121, in at
    raise ValueError("No contract deployed at {}".format(address))
ValueError: No contract deployed at 0xefb1336a2E6B5dfD83D4f3a8F3D2f85b7bfb61DC

classmethod ContractContainer.publish_source(contract, silent=False)

Verifies the source code on etherscan.io for a Project Contract belonging to the container.

• contract: The Project Contract you intend to verify

• silent: When True, suppresses all console output of the call.

classmethod ContractContainer.decode_input(calldata)

Given the call data of a transaction, returns the function signature as a string and the decoded input arguments.

Raises ValueError if the call data cannot be decoded.

>>> Token.decode_input('0xa9059cbb0000000000000000000000009dc9431ccccd2c73f0a2f68dc69a4a527ab5d8090000000000000000000000000000000000000000000000000000000000002710')
("transfer(address,uint256)", ['0x9DC9431CcCCD2C73F0a2F68Dc69A4a527aB5d809', 10000])

classmethod ContractContainer.get_method(calldata)

Given the call data of a transaction, returns the name of the contract method as a string.

>>> tx = Token[0].transfer(accounts[1], 1000)

Transaction sent: 0xc1fe0c7c8fd08736718aa9106662a635102604ea6db4b63a319e43474de0b420
Token.transfer confirmed - block: 3   gas used: 35985 (26.46%)
<Transaction object '0xc1fe0c7c8fd08736718aa9106662a635102604ea6db4b63a319e43474de0b420'>
>>> tx.input
0xa9059cbb00000000000000000000000066ace0365c25329a407002d22908e25adeacb9bb00000000000000000000000000000000000000000000000000000000000003e8
>>> Token.get_method(tx.input)
transfer

classmethod ContractContainer.remove(address)

Removes a contract instance from the container.

>>> Token
[<Token Contract object '0x79447c97b6543F6eFBC91613C655977806CB18b0'>]
>>> Token.remove('0x79447c97b6543F6eFBC91613C655977806CB18b0')
>>> Token
[]

ContractContainer Internal Methods

classmethod ContractContainer._reset()

Called by state._notify_registry when the local chain has been reset. All Contract objects are removed from the container and marked as reverted.

classmethod ContractContainer._revert(height)

Called by state._notify_registry when the local chain has been reverted to a block height greater than zero. Any Contract objects that no longer exist are removed from the container and marked as reverted.

Contract and ProjectContract

Contract and ProjectContract are both used to call or send transactions to smart contracts.

• Contract objects are instantiated directly. They are used for interaction with already-deployed contracts that exist outside of a project.

• ProjectContract objects are created by calls to ContractContainer.deploy. Because they are compiled and deployed directly by Brownie, they provide greater debugging capability.

These classes have identical APIs.

class brownie.network.contract.Contract(address_or_alias, owner=None)

A deployed contract that is not part of a Brownie project.

• address_or_alias: Address of the contract.

• owner: An optional Account instance. If given, transactions to the contract are sent broadcasted from this account by default.

>>> from brownie import Contract
>>> Contract("0x79447c97b6543F6eFBC91613C655977806CB18b0")
<Token Contract object '0x79447c97b6543F6eFBC91613C655977806CB18b0'>

class brownie.network.contract.ProjectContract

A deployed contract that is part of an active Brownie project. Along with making calls and transactions, this object allows access to Brownie’s full range of debugging and testing capability.

>>> Token[0]
<Token Contract object '0x79447c97b6543F6eFBC91613C655977806CB18b0'>
>>> dir(Token[0])
[abi, allowance, approve, balance, balanceOf, bytecode, decimals, name, signatures, symbol, topics, totalSupply, transfer, transferFrom, tx]

Contract Classmethods

New Contract objects are created with one of the following class methods.

classmethod Contract.from_abi(name, address, abi, owner=None)

Create a new Contract object from an address and an ABI.

• name: The name of the contract.

• address: Address of the contract.

• abi: ABI of the contract. Required unless a manifest_uri is given.

• owner: An optional Account instance. If given, transactions to the contract are sent broadcasted from this account by default.

Creating a Contract from an ABI will allow you to call or send transactions to the contract, but functionality such as debugging will not be available.

>>> from brownie import Contract
>>> Contract.from_abi("Token", "0x79447c97b6543F6eFBC91613C655977806CB18b0", abi)
<Token Contract object '0x79447c97b6543F6eFBC91613C655977806CB18b0'>

classmethod Contract.from_ethpm(name, manifest_uri, address=None, owner=None)

Create a new Contract object from an ethPM manifest.

• name: The name of the contract. Must be present within the manifest.

• manifest_uri: EthPM registry manifest uri.

• address: Address of the contract. Only Required if more than one deployment named name is included in the manifest.

• owner: An optional Account instance. If given, transactions to the contract are sent broadcasted from this account by default.

>>> from brownie import network, Contract
>>> network.connect('mainnet')
>>> Contract("DSToken", manifest_uri="ethpm://erc20.snakecharmers.eth:1/dai-dai@1.0.0")
<DSToken Contract object '0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359'>

classmethod Contract.from_explorer(address, as_proxy_for=None, owner=None)

Create a new Contract object from source code fetched from a block explorer such as EtherScan or Blockscout.

• address: Address of the contract.

• as_proxy_for: Address of the implementation contract, if address is a proxy contract. The generated object sends transactions to address, but uses the ABI and NatSpec of as_proxy_for. This field is only required when the block explorer API does not provide an implementation address.

• owner: An optional Account instance. If given, transactions to the contract are sent broadcasted from this account by default.

If the deployed bytecode was generated using a compatible compiler version, Brownie will attempt to recompile it locally. If successful, most debugging functionality will be available.

>>> Contract.from_explorer("0x6b175474e89094c44da98b954eedeac495271d0f")
Fetching source of 0x6B175474E89094C44Da98b954EedeAC495271d0F from api.etherscan.io...
<Dai Contract '0x6B175474E89094C44Da98b954EedeAC495271d0F'>

Contract Attributes

Contract.alias

User-defined alias applied to this Contract object. Can be used to quickly restore the object in future sessions.

>>> Token.alias
'mytoken'

Contract.bytecode

The bytecode of the deployed contract, including constructor arguments.

>>> Token[0].bytecode
'6080604052600436106100985763ffffffff7c010000000000000000000000000000000000000000000000000000000060003504166306fdde03811461009d578063095ea7b31461012757806318160ddd1461015f57806323b872dd14610186578063313ce567146101b057806370a08231146101c557806395d89b41...

Contract.tx

The TransactionReceipt of the transaction that deployed the contract. If the contract was not deployed during this instance of brownie, it will be None.

>>> Token[0].tx
<Transaction object '0xcede03c7e06d2b4878438b08cd0cf4515942b3ba06b3cfd7019681d18bb8902c'>

Contract.events

The ContractEvents instance linked to the deployed contract.

>>> Token[0].events
<brownie.network.contract.ContractEvents object at 0x000001CF03C8BB50>

Contract Methods

classmethod Contract.balance()

Returns the current balance at the contract address, in Wei.

>>> Token[0].balance
0

classmethod Contract.set_alias(alias)

Apply a unique alias this object. The alias can be used to restore the object in future sessions.

• alias: An alias to apply, given as a string. If None, any existing alias is removed.

Raises ValueError if the given alias is invalid or already in use on another contract.

>>> Token.set_alias('mytoken')

>>> Token.alias
'mytoken'

Contract Internal Attributes

Contract._reverted

Boolean. Once set to to True, any attempt to interact with the object raises a ContractNotFound exception. Set as a result of a call to state._notify_registry.

ContractEvents

ContractEvents is used to interact with the events of a Contract or a ProjectContract.

class brownie.network.contract.ContractEvents(contract=brownie.network.contract.Contract)

ContractEvents instances allows you to : subscribe to, listen for or retrieve the different events of a contract. This class inherits from the web3.py ContractEvents class.

ContractEvents Classmethods

classmethod ContractEvents.subscribe(event_name, callback, delay=2.0)

Subscribe to the contract event whose name matches the event_name parameter.

• event_name: Name of the event to subscribe to. Must match the exact event name.

• callback: Function called whenever an event matching ‘event_name’ occurs, it must take one and only one argument which will be the event log receipt.

• delay: Delay in seconds between each check for new events matching ‘event_name’.

New events are detected and callbacks instructions are executed in sub-threads.

Each time a new event of this type is detected, creates a new sub-thread to run the callback function passing the event logs as parameter.

classmethod ContractEvents.get_sequence(from_block, to_block=None, event_type=None)

Retrieves events emitted by the contract between two blocks.

• from_block: The block from which to search for events that have occurred.

• to_block: The block on which to stop searching for events. Defaults to None

• event_type: Type or name of the event to be searched between the specified blocks. Defaults to None.

If to_block is not specified, retrieves events between from_block and the latest mined block.

The event_type parameter can either be a string containing the name of the event to search for or the event type itself (using your_contract.events.your_event_name)

If event_type is not passed as parameter, retrieves all contract events between the two blocks.

classmethod ContractEvents.listen(event_name, timeout=0)

Creates a listening Coroutine object ending whenever an event matching ‘event_name’ occurs. If timeout is superior to zero and no event matching ‘event_name’ has occured, the Coroutine ends when the timeout is reached.

• event_name: Name of the event to be listened to.

• timeout: Timeout value in seconds. Defaults to 0.

The Coroutine return value is an AttributeDict filled with the following fields :

• ‘event_data’ (AttributeDict): The event log receipt that was caught. If no event was caught, evaluates to None

• ‘timed_out’ (bool): False if the event did not timeout, else True

If the ‘timeout’ parameter is not passed or is inferior or equal to 0, the Coroutine listens until an event occurs.

ContractEvents Attributes

ContractEvents.linked_contract

The Contract object from which the ContractEvents instance is reading the events.

>>> tester
<BrownieTester Contract '0x3194cBDC3dbcd3E11a07892e7bA5c3394048Cc87'>
>>> tester.events.linked_contract
<BrownieTester Contract '0x3194cBDC3dbcd3E11a07892e7bA5c3394048Cc87'>

ContractCall

class brownie.network.contract.ContractCall(*args, block_identifier=None, override=None)

Calls a non state-changing contract method without broadcasting a transaction, and returns the result. args must match the required inputs for the method.

• args: Input arguments for the call. The expected inputs are shown in the method’s __repr__ value.

• block_identifier: A block number or hash that the call is executed at. If None, the latest block is used. Raises ValueError if this value is too far in the past and you are not using an archival node.

• override: A mapping from addresses to balance, nonce, code, state, stateDiff overrides for the context of the call.

Inputs and return values are formatted via methods in the convert module. Multiple values are returned inside a ReturnValue.

>>> Token[0].allowance
<ContractCall object 'allowance(address,address)'>
>>> Token[0].allowance(accounts[0], accounts[2])
0

For override see ContractTx.call docs.

ContractCall Attributes

ContractCall.abi

The contract ABI specific to this method.

>>> Token[0].allowance.abi
{
    'constant': True,
    'inputs': [{'name': '_owner', 'type': 'address'}, {'name': '_spender', 'type': 'address'}],
    'name': "allowance",
    'outputs': [{'name': '', 'type': 'uint256'}],
    'payable': False,
    'stateMutability': "view",
    'type': "function"
}

ContractCall.signature

The bytes4 signature of this method.

>>> Token[0].allowance.signature
'0xdd62ed3e'

ContractCall Methods

classmethod ContractCall.info()

Display NatSpec documentation documentation for the given method.

>>> Token[0].allowance.info()
allowance(address _owner, address _spender)
  @dev Function to check the amount of tokens than an owner
       allowed to a spender.
  @param _owner address The address which owns the funds.
  @param _spender address The address which will spend the funds.
  @return A uint specifying the amount of tokens still available
          for the spender.

classmethod ContractCall.transact(*args)

Sends a transaction to the method and returns a TransactionReceipt.

>>> tx = Token[0].allowance.transact(accounts[0], accounts[2])

Transaction sent: 0xc4f3a0addfe1e475c2466f30c750ca7a60450132b07102af610d8d56f170046b
Token.allowance confirmed - block: 2   gas used: 24972 (19.98%)
<Transaction object '0xc4f3a0addfe1e475c2466f30c750ca7a60450132b07102af610d8d56f170046b'>
>>> tx.return_value
0

ContractTx

class brownie.network.contract.ContractTx(*args)

Broadcasts a transaction to a potentially state-changing contract method. Returns a TransactionReceipt.

The given args must match the required inputs for the method. The expected inputs are shown in the method’s __repr__ value.

Inputs are formatted via methods in the convert module.

You can optionally include a dict of transaction parameters as the final argument. If you omit this or do not specify a 'from' value, the transaction will be sent from the same address that deployed the contract.

>>> Token[0].transfer
<ContractTx object 'transfer(address,uint256)'>
>>> Token[0].transfer(accounts[1], 100000, {'from':accounts[0]})

Transaction sent: 0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0
Transaction confirmed - block: 2   gas spent: 51049
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>

ContractTx Attributes

ContractTx.abi

The contract ABI specific to this method.

>>> Token[0].transfer.abi
{
    'constant': False,
    'inputs': [{'name': '_to', 'type': 'address'}, {'name': '_value', 'type': 'uint256'}],
    'name': "transfer",
    'outputs': [{'name': '', 'type': 'bool'}],
    'payable': False,
    'stateMutability': "nonpayable",
    'type': "function"
}

ContractTx.signature

The bytes4 signature of this method.

>>> Token[0].transfer.signature
'0xa9059cbb'

ContractTx Methods

classmethod ContractTx.call(*args, block_identifier=None, override=None)

Calls the contract method without broadcasting a transaction, and returns the result.

• args: Input arguments for the call. The expected inputs are shown in the method’s __repr__ value.

• block_identifier: A block number or hash that the call is executed at. If None, the latest block is used. Raises ValueError if this value is too far in the past and you are not using an archival node.

• override: A mapping from addresses to balance, nonce, code, state, stateDiff overrides for the context of the call.

Inputs and return values are formatted via methods in the convert module. Multiple values are returned inside a ReturnValue.

>>> Token[0].transfer.call(accounts[2], 10000, {'from': accounts[0]})
True

The override argument allows replacing balance, nonce and code associated with an address, as well as overwriting individual storage slot value. See Geth docs for more details.

For example, you can query an exchange rate of an imbalanced Curve pool if it had a different A parameter:

>>> for A in [300, 1000, 2000]:
        override = {
            "0x5a6A4D54456819380173272A5E8E9B9904BdF41B": {
                "stateDiff": {
                    "0x0000000000000000000000000000000000000000000000000000000000000009": hex(A * 100),
                }
            }
        }
        result = pool.get_dy_underlying(0, 1, 1e18, override=override)
        print(A, result.to("ether"))

300 0.884657790783695579
1000 0.961374099348799411
2000 0.979998831913646748

classmethod ContractTx.decode_input(hexstr)

Decodes hexstring input data for this method.

>>>  Token[0].transfer.decode_input("0xa9059cbb0000000000000000000000000d36bdba474b5b442310a5bfb989903020249bba00000000000000000000000000000000000000000000000000000000000003e8")
("0xd36bdba474b5b442310a5bfb989903020249bba", 1000)

classmethod ContractTx.decode_output(hexstr)

Decodes raw hexstring data returned by this method.

>>>  Token[0].balanceOf.decode_output("0x00000000000000000000000000000000000000000000003635c9adc5dea00000")
1000000000000000000000

classmethod ContractTx.encode_input(*args)

Returns a hexstring of ABI calldata that can be used to call the method with the given arguments.

>>> calldata = Token[0].transfer.encode_input(accounts[1], 1000)
0xa9059cbb0000000000000000000000000d36bdba474b5b442310a5bfb989903020249bba00000000000000000000000000000000000000000000000000000000000003e8
>>> accounts[0].transfer(Token[0], 0, data=calldata)

Transaction sent: 0x8dbf15878104571669f9843c18afc40529305ddb842f94522094454dcde22186
Token.transfer confirmed - block: 2   gas used: 50985 (100.00%)
<Transaction object '0x8dbf15878104571669f9843c18afc40529305ddb842f94522094454dcde22186'>

classmethod ContractTx.info()

Display NatSpec documentation documentation for the given method.

>>> Token[0].transfer.info()
transfer(address _to, uint256 _value)
  @dev transfer token for a specified address
  @param _to The address to transfer to.
  @param _value The amount to be transferred.

OverloadedMethod

class brownie.network.contract.OverloadedMethod(address, name, owner)

When a contract uses overloaded function names, the ContractTx or ContractCall objects are stored inside a dict-like OverloadedMethod container.

>>> erc223 = ERC223Token[0]
>>> erc223.transfer
<OverloadedMethod object 'ERC223Token.transfer'>

Individual methods are mapped to keys that correspond to the function input types. Input types can be given as a single comma-seperated string or a tuple of strings. uint and uint256 are equivalent.

>>> erc223.transfer['address,uint']
<ContractTx object 'transfer(address,uint256)'>

>>> erc223.transfer['address', 'uint256', 'uint256']
<ContractTx object 'transfer(address,uint256,uint256)'>

When a contract only contains one method with the given name and number of arguements, OverloadedMethod may be called directly. When more than one method is present, a ValueError is raised.

>>> erc223.transfer(accounts[0], "1 ether")
Transaction sent: 0x8dbf15878104571669f9843c18afc40529305ddb842f94522094454dcde22186
ERC223.transfer confirmed - block: 2   gas used: 50985 (100.00%)
<Transaction object '0x8dbf15878104571669f9843c18afc40529305ddb842f94522094454dcde22186'>

InterfaceContainer

class brownie.network.contract.InterfaceContainer

Container class that provides access to interfaces within a project.

This object is created and populated with InterfaceConstructor objects when a Brownie project is opened. It is available as interface within the console and as a pytest fixture.

>>> interface
<brownie.network.contract.InterfaceContainer object at 0x7fa239bf0d30>

InterfaceConstructor

class brownie.network.contract.InterfaceConstructor(address, owner=None)

Constructor to create Contract objects from a project interface.

• address_or_alias: Address of the deployed contract.

• owner: An optional Account instance. If given, transactions to the contract are sent broadcasted from this account by default.

When a project is loaded, an InterfaceConstructor is generated from each interface file within the interfaces/ folder of the project. These objects are stored as InterfaceContainer members.

>>> interface.Dai
<InterfaceConstructor 'Dai'>

>>> interface.Dai("0x6B175474E89094C44Da98b954EedeAC495271d0F")
<Dai Contract object '0x6B175474E89094C44Da98b954EedeAC495271d0F'>

InterfaceConstructor Attributes

InterfaceConstructor.abi

The interface ABI as a dict.

brownie.network.event

The event module contains classes and methods related to decoding transaction event logs. It is largely a wrapper around eth-event.

Brownie stores encrypted event topics in brownie/data/topics.json. The JSON file is loaded when this module is imported.

EventDict

class brownie.network.event.EventDict

Hybrid container type that works as a dict and a list. Base class, used to hold all events that are fired in a transaction.

When accessing events inside the object:

• If the key is given as an integer, events are handled as a list in the order that they fired. An _EventItem is returned for the specific event that fired at the given position.

• If the key is given as a string, an _EventItem is returned that contains all the events with the given name.

>>> tx
<Transaction object '0xf1806643c21a69fcfa29187ea4d817fb82c880bcd7beee444ef34ea3b207cebe'>
>>> tx.events
{
    'CountryModified': [
        {
            'country': 1,
            'limits': (0, 0, 0, 0, 0, 0, 0, 0),
            'minrating': 1,
            'permitted': True
        },
            'country': 2,
            'limits': (0, 0, 0, 0, 0, 0, 0, 0),
            'minrating': 1,
            'permitted': True
        }
    ],
    'MultiSigCallApproved': {
        'callHash': "0x0013ae2e37373648c5161d81ca78d84e599f6207ad689693d6e5938c3ae4031d",
        'caller': "0xf9c1fd2f0452fa1c60b15f29ca3250dfcb1081b9"
    }
}
>>> tx.events['CountryModified']
[
    {
        'country': 1,
        'limits': (0, 0, 0, 0, 0, 0, 0, 0),
        'minrating': 1,
        'permitted': True
    },
        'country': 2,
        'limits': (0, 0, 0, 0, 0, 0, 0, 0),
        'minrating': 1,
        'permitted': True
    }
]
>>> tx.events[0]
{
    'callHash': "0x0013ae2e37373648c5161d81ca78d84e599f6207ad689693d6e5938c3ae4031d",
    'caller': "0xf9c1fd2f0452fa1c60b15f29ca3250dfcb1081b9"
}

classmethod EventDict.count(name)

Returns the number of events that fired with the given name.

>>> tx.events.count('CountryModified')
2

classmethod EventDict.items()

Returns a set-like object providing a view on the object’s items.

classmethod EventDict.keys()

Returns a set-like object providing a view on the object’s keys.

classmethod EventDict.values()

Returns an object providing a view on the object’s values.

EventWatcher

class brownie.network.event.EventWatcher

Singleton used to set callbacks on user-specified events.

This class uses multiple threads:

• The main thread (original process) starts a sub-thread and can be used to add callback instructions on events occurrences.

• The sub-thread looks for new events among the ones with callback instructions.

• When a new event is found, creates a new thread to run the callback instructions passing the event data as parameter.

classmethod EventWatcher.add_event_callback(event, callback, delay=2.0, repeat=True)

Adds a callback instruction for the specified event.

• event: The ContractEvent instance to watch for.

• callback: The function to be called when a new event is detected. It MUST take one and only one parameter, which will be the event data.

• delay: The delay between each check for new event (s). Defaults to 2.

• repeat: Wether to repeat the callback or not (if False, the callback instructions will only be called the first time events are detected). Defaults to True.

If the function is called with the same event more than once, the delay between each check for this event will take the minimum value between the already set delay and the one passed as parameter.

This function raises a TypeError if the callback parameter is not a callable object.

classmethod EventWatcher.stop(wait=True)

Sends the instruction to stop to the running threads.

This function does not reset the instance to its initial state.

If that is your goal, check the EventWatcher.reset method.

• wait: Wether to wait for threads to join within the function. Defaults to True.

classmethod EventWatcher.reset()

Uses the EventWatcher.stop function to stop the running threads.

After stopping, resets the instance to its default state.

Internal Classes and Methods

_EventItem

class brownie.network.event._EventItem

Hybrid container type that works as a dict and a list. Represents one or more events with the same name that were fired in a transaction.

Instances of this class are created by EventDict, it is not intended to be instantiated directly.

When accessing events inside the object:

• If the key is given as an integer, events are handled as a list in the order that they fired. An _EventItem is returned for the specific event that fired at the given position.

• If the key is given as a string, _EventItem assumes that you wish to access the first event contained within the object. event['value'] is equivalent to event[0]['value'].

All values within the object are formatted by methods outlined in the convert module.

>>> event = tx.events['CountryModified']
<Transaction object '0xf1806643c21a69fcfa29187ea4d817fb82c880bcd7beee444ef34ea3b207cebe'>
>>> event
[
    {
        'country': 1,
        'limits': (0, 0, 0, 0, 0, 0, 0, 0),
        'minrating': 1,
        'permitted': True
    },
        'country': 2,
        'limits': (0, 0, 0, 0, 0, 0, 0, 0),
        'minrating': 1,
        'permitted': True
    }
]
>>> event[0]
{
    'country': 1,
    'limits': (0, 0, 0, 0, 0, 0, 0, 0),
    'minrating': 1,
    'permitted': True
}
>>> event['country']
1
>>> event[1]['country']
2

_EventItem.name

The name of the event(s) contained within this object.

>>> tx.events[2].name
CountryModified

_EventItem.address

The address where the event was fired. If the object contains multiple events, this value is set to None.

>>> tx.events[2].address
"0x2d72c1598537bcf4a4af97668b3a24e68b7d0cc5"

_EventItem.pos

A tuple giving the absolute position of each event contained within this object.

>>> event.pos
(1, 2)
>>> event[1].pos
(2,)
>>> tx.events[2] == event[1]
True

classmethod _EventItem.items()

Returns a set-like object providing a view on the items in the first event within this object.

classmethod _EventItem.keys()

Returns a set-like object providing a view on the keys in the first event within this object.

classmethod _EventItem.values()

Returns an object providing a view on the values in the first event within this object.

Internal Methods

brownie.network.event._get_topics(abi)

Generates encoded topics from the given ABI, merges them with those already known in topics.json, and returns a dictioary in the form of {'Name': "encoded topic hexstring"}.

>>> from brownie.network.event import _get_topics
>>> abi = [{'name': 'Approval', 'anonymous': False, 'type': 'event', 'inputs': [{'name': 'owner', 'type': 'address', 'indexed': True}, {'name': 'spender', 'type': 'address', 'indexed': True}, {'name': 'value', 'type': 'uint256', 'indexed': False}]}, {'name': 'Transfer', 'anonymous': False, 'type': 'event', 'inputs': [{'name': 'from', 'type': 'address', 'indexed': True}, {'name': 'to', 'type': 'address', 'indexed': True}, {'name': 'value', 'type': 'uint256', 'indexed': False}]}]
>>> _get_topics(abi)
{'Transfer': '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef', 'Approval': '0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925'}

brownie.network.event._decode_logs(logs)

Given an array of logs as returned by eth_getLogs or eth_getTransactionReceipt RPC calls, returns an EventDict.

>>> from brownie.network.event import _decode_logs
>>> tx = Token[0].transfer(accounts[1], 100)

Transaction sent: 0xfefc3b7d912ed438b312414fb31d94ff757970f4d2e74dd0950d5c58cc23fdb1
Token.transfer confirmed - block: 2   gas used: 50993 (33.77%)
<Transaction object '0xfefc3b7d912ed438b312414fb31d94ff757970f4d2e74dd0950d5c58cc23fdb1'>
>>> e = _decode_logs(tx.logs)
>>> repr(e)
<brownie.types.types.EventDict object at 0x7feed74aebe0>
>>> e
{
    'Transfer': {
        'from': "0x1ce57af3672a16b1d919aeb095130ab288ca7456",
        'to': "0x2d72c1598537bcf4a4af97668b3a24e68b7d0cc5",
        'value': 100
    }
}

brownie.network.event._decode_trace(trace)

Given the structLog from a debug_traceTransaction RPC call, returns an EventDict.

>>> from brownie.network.event import _decode_trace
>>> tx = Token[0].transfer(accounts[2], 1000, {'from': accounts[3]})

Transaction sent: 0xc6365b065492ea69ad3cbe26039a45a68b2e9ab9d29c2ff7d5d9162970b176cd
Token.transfer confirmed (Insufficient Balance) - block: 2   gas used: 23602 (19.10%)
<Transaction object '0xc6365b065492ea69ad3cbe26039a45a68b2e9ab9d29c2ff7d5d9162970b176cd'>
>>> e = _decode_trace(tx.trace)
>>> repr(e)
<brownie.types.types.EventDict object at 0x7feed74aebe0>
>>> e
{}

brownie.network.gas

The gas module contains gas strategy classes, as well as abstract base classes for building your own gas strategies.

Gas Strategies

class brownie.network.gas.strategies.ExponentialScalingStrategy(initial_gas_price, max_gas_price, time_duration=30)

Time based scaling strategy for exponential gas price increase.

The gas price for each subsequent transaction is calculated as the previous price multiplied by 1.1 ** n where n is the number of transactions that have been broadcast. In this way the price increase starts gradually and ramps up until confirmation.

• initial_gas_price: The initial gas price to use in the first transaction

• max_gas_price: The maximum gas price to use

• time_duration: Number of seconds between transactions

>>> from brownie.network.gas.strategies import ExponentialScalingStrategy
>>> gas_strategy = ExponentialScalingStrategy("10 gwei", "50 gwei")

>>> accounts[0].transfer(accounts[1], "1 ether", gas_price=gas_strategy)

class brownie.network.gas.strategies.GasNowStrategy(speed='fast')

Gas strategy for determing a price using the GasNow API.

• speed: The gas price to use based on the API call. Options are rapid, fast, standard and slow.

>>> from brownie.network.gas.strategies import GasNowStrategy
>>> gas_strategy = GasNowStrategy("fast")

>>> accounts[0].transfer(accounts[1], "1 ether", gas_price=gas_strategy)

class brownie.network.gas.strategies.GasNowScalingStrategy(initial_speed='standard', max_speed='rapid', increment=1.125, block_duration=2)

Block based scaling gas strategy using the GasNow API.

• initial_speed: The initial gas price to use when broadcasting the first transaction. Options are rapid, fast, standard and slow.

• max_speed: The maximum gas price to use when replacing the transaction. Options are rapid, fast, standard and slow.

• increment: A multiplier applied to the most recently used gas price in order to determine the new gas price. If the incremented value is less than or equal to the current max_speed rate, a new transaction is broadcasted. If the current rate for initial_speed is greater than the incremented rate, it is used instead.

• block_duration: The number of blocks to wait between broadcasting new transactions.

>>> from brownie.network.gas.strategies import GasNowScalingStrategy
>>> gas_strategy = GasNowScalingStrategy("standard", increment=1.125, block_duration=2)

>>> accounts[0].transfer(accounts[1], "1 ether", gas_price=gas_strategy)

class brownie.network.gas.strategies.GethMempoolStrategy(position=500, graphql_endpoint=None, block_duration=2)

Block based scaling gas strategy using Geth’s GraphQL interface.

In order to use this strategy you must be connecting via a Geth node with GraphQL enabled.

The yielded gas price is determined by sorting transactions in the mempool according to gas price, and returning the price of the transaction at position. This is the same technique used by the GasNow API.

• A position of 200 or less usually places a transaction within the mining block.

• A position of 500 usually places a transaction within the 2nd pending block.

>>> from brownie.network.gas.strategies import GethMempoolStrategy
>>> gas_strategy = GethMempoolStrategy(200)

>>> accounts[0].transfer(accounts[1], "1 ether", gas_price=gas_strategy)

class brownie.network.gas.strategies.LinearScalingStrategy(initial_gas_price, max_gas_price, increment=1.125, time_duration=30)

Time based scaling strategy for linear gas price increase.

• initial_gas_price: The initial gas price to use in the first transaction

• max_gas_price: The maximum gas price to use

• increment: Multiplier applied to the previous gas price in order to determine the new gas price

• time_duration: Number of seconds between transactions

>>> from brownie.network.gas.strategies import LinearScalingStrategy
>>> gas_strategy = LinearScalingStrategy("10 gwei", "50 gwei", 1.1)

>>> accounts[0].transfer(accounts[1], "1 ether", gas_price=gas_strategy)

Gas Strategy ABCs

Abstract base classes for building your own gas strategies.

Simple Strategies

class brownie.network.gas.bases.SimpleGasStrategy

Abstract base class for simple gas strategies.

Simple gas strategies are called once to provide a dynamically genreated gas price at the time a transaction is broadcasted. Transactions using simple gas strategies are not automatically rebroadcasted.

Simple Strategy Abstract Methods

To implement a simple gas strategy, subclass SimpleGasStrategy and include the following method:

SimpleGasStrategy.get_gas_price(self) → int:

Return the gas price for a transaction.

Scaling Strategies

class brownie.network.gas.bases.BlockGasStrategy(duration=2)

Abstract base class for block-based gas strategies.

Block gas strategies are called every duration blocks and can be used to automatically rebroadcast a pending transaction with a higher gas price.

class brownie.network.gas.bases.TimeGasStrategy(duration=30)

Abstract base class for time-based gas strategies.

Time gas strategies are called every duration seconds and can be used to automatically rebroadcast a pending transaction with a higher gas price.

Scaling Strategy Abstract Methods

To implement a scaling strategy, subclass one of the above ABCs and implement the following generator function:

BlockGasStrategy.get_gas_price(self) → Generator[int]:

Generator function that yields a new gas price each time it is called.

The produced generator is called every duration seconds while a transaction is still pending. Each call must yield a new gas price as an integer. If the newly yielded value is at least 10% higher than the current gas price, the transaction is rebroadcasted with the new gas price.

brownie.network.multicall

The multicall module contains the Multicall context manager, which allows for the batching of multiple constant contract function calls via Multicall2.

Note

The Multicall context manager is not meant to be instantiated, and instead should be used via brownie.multicall

Multicall

class brownie.network.multicall.Multicall(address=None, block_identifier=None)

Instances of Multicall allow for the batching of constant contract function calls through a modified version of the standard Brownie call API.

The only syntatic difference between a multicall and a standard brownie contract function call is the final argument for a multicall, is a dictionary with the from key being the instance of Multicall being used.

Features:

1. Lazy fetching of results

2. Auto-deployment on development networks (on first use).

3. Uses multicall2 key in network-config as pre-defined multicall contract address

4. Can specify/modify block number to make calls at particular block heights

5. Calls which fail return None instead of causing all calls to fail

>>> import brownie
>>> from brownie import Contract
>>> addr_provider = Contract("0x0000000022D53366457F9d5E68Ec105046FC4383")
>>> registry = Contract(addr_provider.get_registry())
>>> with brownie.multicall:
...     pool_count = registry.pool_count.call()  # standard call, no batching
...     pools = [registry.pool_list(i) for i in range(pool_count)]  # batched
...     gauges = [registry.get_gauges(pool) for pool in pools]  # batched
... print(*zip(pools, gauges), sep="\n")

Multicall Attributes

Multicall.address

The deployed Multicall2 contract address used for batching calls.

>>> brownie.multicall.address
0x5BA1e12693Dc8F9c48aAD8770482f4739bEeD696
>>> brownie.multicall(address="0xc8E51042792d7405184DfCa245F2d27B94D013b6").address
0xc8E51042792d7405184DfCa245F2d27B94D013b6

Multicall.block_number

The block height which call results are aggregated from.

Note

Multicall relies on an instance of Multicall2 being available for aggregating results. If you set the block_height before the Multicall2 instance you are using was deployed a ContractNotFound error will be raised.

>>> with brownie.multicall(block_identifier=12733683):
...     brownie.multicall.block_number
12733683

Multicall Methods

classmethod Multicall.deploy()

Deploys an instance of Multicall2, especially useful when creating fixtures for testing.

>>> multicall2 = brownie.multicall.deploy({"from": alice})
<Multicall2 Contract object '0x5419710735c2D6c3e4db8F30EF2d361F70a4b380'>

classmethod Multicall.flush()

Flushes the current queue of pending calls, especially useful for preventing OOG errors from occuring when querying large amounts of data.

>>> results = []
>>> long_list_of_addresses = [...]
>>> token = Contract(...)
>>> with brownie.multicall:
...     for i, addr in enumerate(long_list_of_addresses):
...         if i % 1_000:
...             brownie.multicall.flush()
...         results.append(token.balanceOf(addr))

Multicall Internal Attributes

Multicall._contract

The contract instance of Multicall2 used to query data

Multicall._pending_calls

List of proxy objects representing calls to be made. While pending, these calls contain the data necessary to make an aggregate call with multicall and also decode the result.

brownie.network.state

The state module contains classes to record transactions and contracts as they occur on the blockchain.

Classes in state are not meant to be instantiated directly. TxHistory and Chain objects are available as history and chain in the console and as pytest fixtures.

TxHistory

class brownie.network.state.TxHistory

List-like Singleton container that contains TransactionReceipt objects. Whenever a transaction is broadcast, the TransactionReceipt is automatically added.

>>> from brownie.network.state import TxHistory
>>> history = TxHistory()
>>> history
[]
>>> dir(history)
[copy, from_sender, of_address, to_receiver]

TxHistory Attributes

TxHistory.gas_profile

A dict that tracks gas cost statistics for contract function calls over time.

>>> history.gas_profile
{
    'Token.constructor': {
        'avg': 742912,
        'count': 1,
        'high': 742912,
        'low': 742912
    },
    'Token.transfer': {
        'avg': 43535,
        'count': 2,
        'high': 51035,
        'low': 36035
    }
}

TxHistory Methods

classmethod TxHistory.copy()

Returns a shallow copy of the object as a list.

>>> history
[<Transaction object '0xe803698b0ade1598c594b2c73ad6a656560a4a4292cc7211b53ffda4a1dbfbe8'>]
>>> c = history.copy()
>>> c
[<Transaction object '0xe803698b0ade1598c594b2c73ad6a656560a4a4292cc7211b53ffda4a1dbfbe8'>]
>>> type(c)
<class 'list'>

classmethod TxHistory.filter(key=None, **kwargs)

Return a filtered list of transactions.

Each keyword argument corresponds to a TransactionReceipt attribute. Only transactions where every attributes matches the given value are returned.

>>> history.filter(sender=accounts[0], value="1 ether")
[<Transaction object '0xe803698b0ade1598c594b2c73ad6a656560a4a4292cc7211b53ffda4a1dbfbe8'>]

You can also use key to provide a function or lambda. It should receive one argument, a TransactionReceipt, and return a boolean indicating if the object is to be included in the result.

>>> history.filter(key=lambda k: k.nonce < 2)
[<Transaction '0x03569ee152b04ba5b55c2bf05f99f7ec153db715acfe0c1600f144ded58f31fe'>, <Transaction '0x42193c0ff7007c6e2a5e5572a3c6b5706cd133d21e30e5826add3d971134504c'>]

classmethod TxHistory.from_sender(account)

Returns a list of transactions where the sender is Account.

>>> history.from_sender(accounts[1])
[<Transaction object '0xe803698b0ade1598c594b2c73ad6a656560a4a4292cc7211b53ffda4a1dbfbe8'>]

classmethod TxHistory.to_receiver(account)

Returns a list of transactions where the receiver is Account.

>>> history.to_receiver(accounts[2])
[<Transaction object '0xe803698b0ade1598c594b2c73ad6a656560a4a4292cc7211b53ffda4a1dbfbe8'>]

classmethod TxHistory.of_address(account)

Returns a list of transactions where Account is the sender or receiver.

>>> history.of_address(accounts[1])
[<Transaction object '0xe803698b0ade1598c594b2c73ad6a656560a4a4292cc7211b53ffda4a1dbfbe8'>]

classmethod TxHistory.wait(key=None, **kwargs)

Wait for pending transactions to confirm.

This method iterates over a list of transactions generated by TxHistory.filter, waiting until each transaction has confirmed. If no arguments are given, all transactions within the container are used.

TxHistory Internal Methods

classmethod TxHistory._reset()

Called by state._notify_registry when the local chain has been reset. All TransactionReceipt objects are removed from the container.

classmethod TxHistory._revert(height)

Called by state._notify_registry when the local chain has been reverted to a block height greater than zero. Any TransactionReceipt objects that no longer exist are removed from the container.

Chain

class brownie.network.state.Chain

List-like Singleton used to access chain information and perform actions such as snapshotting, rewinds and time travel.

>>> from brownie.network.state import Chain
>>> chain = Chain()
>>> chain
<Chain object (chainid=1, height=10451202)>

You can use list indexing the access specific blocks. For negative index values, the block returned is relative to the most recently mined block. For example, chain[-1] returns the most recently mined block.

>>> web3.eth.block_number
10451202

>>> len(chain)
10451203  # always +1 to the current block number, because the first block is zero

>>> chain[0] == web3.eth.get_block(0)
True

>>> chain[-1] == web3.eth.get_block('latest')
True

Chain Attributes

Chain.height

The current block height.

>>> chain.height
10451202

Chain.id

The chain ID value for the active network. Returns None if no chain ID is available.

>>> chain.id
1

Chain Methods

Chain.get_transaction(txid)

Return a TransactionReceipt object for the given transaction hash.

This function is non-blocking. Pending transaction return immediately.

Raises TransactionNotFound if the transaction does not exist.

>>> chain.get_transaction(0xf598d43ef34a48478f3bb0ad969c6735f416902c4eb1eb18ebebe0fca786105e)
<Transaction '0xf598d43ef34a48478f3bb0ad969c6735f416902c4eb1eb18ebebe0fca786105e'>

Chain.new_blocks(height_buffer, poll_interval)

Generator for iterating over new blocks.

height_buffer: The number of blocks behind “latest” to return. A higher value means more delayed results but less likelihood of uncles. poll_interval: Maximum interval between querying for a new block, if the height has not changed. Set this lower to detect uncles more frequently.

count = 0
for block in chain.new_blocks():
    print(block.number)
    count += 1
    if count == 5:
        break

Chain.time()

Return the current epoch time in the RPC as an integer.

>>> chain.time()
1550189043

Chain.sleep(seconds)

Advance the RPC time. You can only advance the time by whole seconds.

>>> chain.time()
1550189043
>>> chain.sleep(100)
>>> chain.time()
1550189143

Chain.mine(blocks=1, timestamp=None, timedelta=None)

Mine one or more empty blocks.

• blocks: Number of blocks to mine

• timestamp: Timestamp of the final block being mined. If multiple blocks are mined, they will be mined at equal intervals starting from chain.time and ending at timestamp.

• timedelta: Timedelta for the final block to be mined. If given, the final block will have a timestamp of chain.time() + timedelta.

Returns the block height after all new blocks have been mined.

>>> web3.eth.block_number
0
>>> chain.mine()
1
>>> chain.mine(3)
4

Chain.snapshot()

Create a snapshot at the current block height.

>>> chain.snapshot()

Chain.revert()

Revert the blockchain to the latest snapshot. Raises ValueError if no snapshot has been taken.

>>> chain.snapshot()
>>> accounts[0].balance()
100000000000000000000
>>> accounts[0].transfer(accounts[1], "10 ether")

Transaction sent: 0xd5d3b40eb298dfc48721807935eda48d03916a3f48b51f20bcded372113e1dca
Transaction confirmed - block: 5   gas used: 21000 (100.00%)
<Transaction object '0xd5d3b40eb298dfc48721807935eda48d03916a3f48b51f20bcded372113e1dca'>
>>> accounts[0].balance()
89999580000000000000
>>> chain.revert()
4
>>> accounts[0].balance()
100000000000000000000

Chain.reset()

Reset the local environment to the initial state when Brownie was loaded. This action is performed using a snapshot - it is NOT equivalent to calling rpc.kill and then rpc.launch.

Returns the block height after resetting.

>>> chain.reset()
0

Chain.undo(num=1)

Undo one or more recent transactions.

• num: Number of transactions to undo

Once undone, a transaction can be repeated using Chain.redo. Calling Chain.snapshot or Chain.revert clears the undo buffer.

Returns the block height after all undo actions are complete.

>>> web3.eth.block_number
3
>>> chain.undo()
2

Chain.redo(num=1)

Redo one or more recently undone transactions.

• num: Number of transactions to redo

Returns the block height after all redo actions are complete.

>>> web3.eth.block_number
2
>>> chain.redo()
Transaction sent: 0x8c166b66b356ad7f5c58337973b89950f03105cdae896ac66f16cdd4fc395d05
  Gas price: 0.0 gwei   Gas limit: 6721975
  Transaction confirmed - Block: 3   Gas used: 21000 (0.31%)

3

Internal Methods

The internal methods in the state module are used for tracking and adjusting the contents of various container objects when the local RPC network is reverted or reset.

brownie.network.state._revert_register(obj)

Registers an object to be called whenever the local RPC is reset or reverted. Objects that register must include _revert and _reset methods in order to receive these callbacks.

brownie.network.state._notify_registry(height)

Calls each registered object’s _revert or _reset method after the local state has been reverted.

brownie.network.state._add_contract(contract)

Adds a Contract or ProjectContract object to the global contract record.

brownie.network.state._find_contract(address)

Given an address, returns the related Contract or ProjectContract object. If none exists, returns None.

This function is used internally by Brownie to locate a ProjectContract when the project it belongs to is unknown.

brownie.network.state._remove_contract(contract)

Removes a Contract or ProjectContract object to the global contract record.

brownie.network.state._get_current_dependencies()

Returns a list of the names of all currently deployed contracts, and of every contract that these contracts are dependent upon.

Used during testing to determine which contracts must change before a test needs to be re-run.

brownie.network.rpc

The rpc module contains the Rpc class, which is used to interact with ganache-cli when running a local RPC environment.

Note

Account balances, contract containers and transaction history are automatically modified when the local RPC is terminated, reset or reverted.

Rpc

class brownie.network.rpc.Rpc

Singleton object for interacting with ganache-cli when running a local RPC environment. When using the console or writing tests, an instance of this class is available as rpc.

>>> from brownie import rpc
>>> rpc
<lib.components.eth.Rpc object at 0x7ffb7cbab048>
>>> dir(rpc)
[is_active, kill, launch, mine, reset, revert, sleep, snapshot, time]

Rpc Methods

classmethod Rpc.launch(cmd)

Launches the local RPC client as a subprocess. cmd is the command string requiried to run it.

If the process cannot load successfully, raises brownie.RPCProcessError.

If a provider has been set in Web3 but is unable to connect after launching, raises RPCConnectionError.

>>> rpc.launch('ganache-cli')
Launching 'ganache-cli'...

classmethod Rpc.attach(laddr)

Attaches to an already running RPC client.

laddr: Address that the client is listening at. Can be supplied as a string "http://127.0.0.1:8545" or tuple ("127.0.0.1", 8545).

Raises a ProcessLookupError if the process cannot be found.

>>> rpc.attach('http://127.0.0.1:8545')

classmethod Rpc.kill(exc=True)

Kills the RPC subprocess. Raises SystemError if exc is True and the RPC is not currently active.

>>> rpc.kill()
Terminating local RPC client...

Note

Brownie registers this method with the atexit module. It is not necessary to explicitly kill Rpc before terminating a script or console session.

classmethod Rpc.is_active()

Returns a boolean indicating if the RPC process is currently active.

>>> rpc.is_active()
False
>>> rpc.launch()
>>> rpc.is_active()
True

classmethod Rpc.is_child()

Returns a boolean indicating if the RPC process is a child process of Brownie. If the RPC is not currently active, returns False.

>>> rpc.is_child()
True

classmethod Rpc.evm_version()

Returns the currently active EVM version as a string.

>>> rpc.evm_version()
'istanbul'

classmethod Rpc.evm_compatible(version)

Returns a boolean indicating if the given version is compatible with the currently active EVM version.

>>> rpc.evm_compatible('byzantium')
True

brownie.network.transaction

The transaction module contains the TransactionReceipt class and related internal methods.

TransactionReceipt

class brownie.network.transaction.TransactionReceipt

An instance of this class is returned whenever a transaction is broadcasted. When printed in the console, the transaction hash will appear yellow if the transaction is still pending or red if the transaction caused the EVM to revert.

Many of the attributes return None while the transaction is still pending.

>>> tx = Token[0].transfer
<ContractTx object 'transfer(address,uint256)'>
>>> Token[0].transfer(accounts[1], 100000, {'from':accounts[0]})

Transaction sent: 0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0
Transaction confirmed - block: 2   gas spent: 51049
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> dir(tx)
[block_number, call_trace, contract_address, contract_name, error, events, fn_name, gas_limit, gas_price, gas_used, info, input, logs, nonce, receiver, sender, status, txid, txindex, value]

TransactionReceipt Attributes

TransactionReceipt.block_number

The block height at which the transaction confirmed.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.block_number
2

TransactionReceipt.confirmations

The number of blocks mined since the transaction was confirmed, including the block the transaction was mined in: block_height - tx.block_number + 1.

>>> tx
<Transaction '0x8c166b66b356ad7f5c58337973b89950f03105cdae896ac66f16cdd4fc395d05'>
>>> tx.confirmations
11

TransactionReceipt.contract_address

The address of the contract deployed in this transaction, if the transaction was a deployment.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.contract_address
None

For contracts deployed as the result of calling another contract, see TransactionReceipt.new_contracts.

TransactionReceipt.contract_name

The name of the contract that was called or deployed in this transaction.

>>> tx
<Transaction object '0xcdd07c6235bf093e1f30ac393d844550362ebb9b314b7029667538bfaf849749'>
>>> tx.contract_name
Token

TransactionReceipt.dev_revert_msg

The developer revert comment returned when a transaction causes the EVM to revert, if any.

>>> tx
<Transaction object '0xd9e0fb1bd6532f6aec972fc8aef806a8d8b894349cf5c82c487335625db8d0ef'>
>>> tx.dev_revert_msg
'dev: is four'

TransactionReceipt.events

An EventDict of decoded event logs for this transaction.

Note

If you are connected to an RPC client that allows for debug_traceTransaction, event data is still available when the transaction reverts.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.events
{
    'Transfer': {
        'from': "0x94dd96c7e6012c927537cd789c48c42a1d1f790d",
        'to': "0xc45272e89a23d1a15a24041bce7bc295e79f2d13",
        'value': 100000
    }
}

TransactionReceipt.fn_name

The name of the function called by the transaction.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.fn_name
'transfer'

TransactionReceipt.gas_limit

The gas limit of the transaction, in wei as an int.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.gas_limit
150921

TransactionReceipt.gas_price

The effective gas price of the transaction, in wei as an int.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.gas_price
2000000000

TransactionReceipt.gas_used

The amount of gas consumed by the transaction, in wei as an int.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.gas_used
51049

TransactionReceipt.input

The complete calldata of the transaction as a hexstring.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.input
'0xa9059cbb00000000000000000000000031d504908351d2d87f3d6111f491f0b52757b592000000000000000000000000000000000000000000000000000000000000000a'

TransactionReceipt.internal_transfers

A list of all internal ether transfers that occurred during the transaction. Transfers are sequenced in the order they took place, and represented as dictionaries containing the following fields:

• from: Sender address

• to: Receiver address

• value: Amount of ether that was transferred in Wei

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.internal_transfers
[
    {
        "from": "0x79447c97b6543F6eFBC91613C655977806CB18b0",
        "to": "0x21b42413bA931038f35e7A5224FaDb065d297Ba3",
        "value": 100
    }
]

TransactionReceipt.logs

The raw event logs for the transaction. Not available if the transaction reverts.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.logs
[AttributeDict({'logIndex': 0, 'transactionIndex': 0, 'transactionHash': HexBytes('0xa8afb59a850adff32548c65041ec253eb64e1154042b2e01e2cd8cddb02eb94f'), 'blockHash': HexBytes('0x0b93b4cf230c9ef92b990de9cd62611447d83d396f1b13204d26d28bd949543a'), 'blockNumber': 6, 'address': '0x79447c97b6543F6eFBC91613C655977806CB18b0', 'data': '0x0000000000000000000000006b5132740b834674c3277aafa2c27898cbe740f600000000000000000000000031d504908351d2d87f3d6111f491f0b52757b592000000000000000000000000000000000000000000000000000000000000000a', 'topics': [HexBytes('0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef')], 'type': 'mined'})]

TransactionReceipt.modified_state

Boolean indicating if this transaction resuled in any state changes on the blockchain.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.modified_state
True

TransactionReceipt.new_contracts

A list of new contract addresses that were deployed during this transaction, as the result of contract call.

>>> tx = Deployer.deploy_new_contract()
Transaction sent: 0x6c3183e41670101c4ab5d732bfe385844815f67ae26d251c3bd175a28604da92
  Gas price: 0.0 gwei   Gas limit: 79781
  Deployer.deploy_new_contract confirmed - Block: 4   Gas used: 79489 (99.63%)

>>> tx.new_contracts
["0x1262567B3e2e03f918875370636dE250f01C528c"]

TransactionReceipt.nonce

The nonce of the transaction.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.nonce
2

TransactionReceipt.receiver

The address the transaction was sent to, as a string.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.receiver
'0x79447c97b6543F6eFBC91613C655977806CB18b0'

TransactionReceipt.revert_msg

The error string returned when a transaction causes the EVM to revert, if any.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.revert_msg
None

TransactionReceipt.return_value

The value returned from the called function, if any. Only available if the RPC client allows debug_traceTransaction.

If more then one value is returned, they are stored in a ReturnValue.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.return_value
True

TransactionReceipt.subcalls

A list of dictionaries providing information about subcalls that occured during the transaction.

The following fields are always included:

• from: Address where the call originated

• to: Address being called

• op: Instruction used to make the call

The following fields are included when the source code for to is known:

• function: Signature of the function being called

• inputs: Dictionary of decoded input arguments in the call

One of the following fields is included, depending on how the call ends:

• return_value: A tuple of decoded return values, if the call ended with RETURN

• revert_msg: The given error message, if the call ended in a REVERT or INVALID instruction

• selfdestruct: Set to True if the call ended in a SELFDESTRUCT instruction

>>> history[-1].subcalls
[
    {
        'from': "0x5AE569698C5F986665018B6e1d92A71be71DEF9a",
        'function': "get_period_timestamp(int128)",
        'inputs': {
            'p': 0
        },
        'op': "STATICCALL",
        'return_value': (1594574319,),
        'to': "0x0C41Fc429cC21BC3c826efB3963929AEdf1DBb8e"
    },
...

TransactionReceipt.sender

The address the transaction was sent from. Where possible, this will be an Account instance instead of a string.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.sender
<Account object '0x6B5132740b834674C3277aAfa2C27898CbE740f6'>

TransactionReceipt.status

An IntEnum object representing the status of the transaction:

• 1: Successful

• 0: Reverted

• -1: Pending

• -2: Dropped

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.status
1

TransactionReceipt.timestamp

The timestamp of the block that this transaction was included in.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.timestamp
1588957325

TransactionReceipt.trace

An expanded transaction trace structLog, returned from the debug_traceTransaction RPC endpoint. If you are using Infura this attribute is not available.

Along with the standard data, the structLog also contains the following additional information:

• address: The address of the contract that executed this opcode

• contractName: The name of the contract

• fn: The name of the function

• jumpDepth: The number of jumps made since entering this contract. The initial function has a value of 1.

• source: The path and offset of the source code associated with this opcode.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> len(tx.trace)
239
>>> tx.trace[0]
{
    'address': "0x79447c97b6543F6eFBC91613C655977806CB18b0",
    'contractName': "Token",
    'depth': 0,
    'error': "",
    'fn': "Token.transfer",
    'gas': 128049,
    'gasCost': 22872,
    'jumpDepth': 1,
    'memory': [],
    'op': "PUSH1",
    'pc': 0,
    'source': {
        'filename': "contracts/Token.sol",
        'offset': [53, 2053]
    },
    'stack': [],
    'storage': {
    }
}

TransactionReceipt.txid

The transaction hash.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.txid
'0xa8afb59a850adff32548c65041ec253eb64e1154042b2e01e2cd8cddb02eb94f'

TransactionReceipt.txindex

The integer of the transaction’s index position in the block.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.txindex
0

TransactionReceipt.value

The value of the transaction, in Wei.

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.value
0

TransactionReceipt Methods

TransactionReceipt.replace(increment=None, gas_price=None)

Broadcast an identical transaction with the same nonce and a higher gas price.

Exactly one of the following arguments must be provided:

• increment: Multiplier applied to the gas price of the current transaction in order to determine a new gas price

• gas_price: Absolute gas price to use in the replacement transaction

For EIP-1559 transactions, the modification is applied to max_fee. The priority_fee is always multiplied by 1.1 (the minimum increase required to be accepted by a node).

Returns a TransactionReceipt object.

>>> tx = accounts[0].transfer(accounts[1], 100, required_confs=0, gas_price="1 gwei")
Transaction sent: 0xc1aab54599d7875fc1fe8d3e375abb0f490cbb80d5b7f48cedaa95fa726f29be
  Gas price: 13.0 gwei   Gas limit: 21000   Nonce: 3
<Transaction object '0xc1aab54599d7875fc1fe8d3e375abb0f490cbb80d5b7f48cedaa95fa726f29be'>

>>> tx.replace(1.1)
Transaction sent: 0x9a525e42b326c3cd57e889ad8c5b29c88108227a35f9763af33dccd522375212
  Gas price: 14.3 gwei   Gas limit: 21000   Nonce: 3
<Transaction '0x9a525e42b326c3cd57e889ad8c5b29c88108227a35f9763af33dccd522375212'>

classmethod TransactionReceipt.info()

Displays verbose information about the transaction, including event logs and the error string if a transaction reverts.

>>> tx = accounts[0].transfer(accounts[1], 100)
<Transaction object '0x2facf2d1d2fdfa10956b7beb89cedbbe1ba9f4a2f0592f8a949d6c0318ec8f66'>
>>> tx.info()

Transaction was Mined
---------------------
Tx Hash: 0x2facf2d1d2fdfa10956b7beb89cedbbe1ba9f4a2f0592f8a949d6c0318ec8f66
From: 0x5fe657e72E76E7ACf73EBa6FA07ecB40b7312d80
To: 0x5814fC82d51732c412617Dfaecb9c05e3B823253
Value: 100
Block: 1
Gas Used: 21000

   Events In This Transaction
   --------------------------
   Transfer
      from: 0x5fe657e72E76E7ACf73EBa6FA07ecB40b7312d80
      to: 0x31d504908351d2d87f3d6111f491f0b52757b592
      value: 100

classmethod TransactionReceipt.call_trace(expand=False)

Display the complete sequence of contracts and functions called while execiting this transaction.

Each line is formatted as:

ContractName.functionName  (external call opcode)  start:stop  [internal / total gas used]

• start:stop are index values for the TransactionReceipt.trace, showing where the call begins and ends

• for calls that include subcalls, gas use is displayed as [gas used in this frame / gas used in this frame + subcalls]

• Calls that terminate with a REVERT or INVALID instruction are highlighted in red

>>> tx.call_trace()
Call trace for '0x7824c6032966ca2349d6a14ec3174d48d546d0fb3020a71b08e50c7b31c1bcb1':
Initial call cost  [21228 gas]
LiquidityGauge.deposit  0:3103  [64010 / 128030 gas]
├── LiquidityGauge._checkpoint  83:1826  [-6420 / 7698 gas]
│   ├── GaugeController.get_period_timestamp  [STATICCALL]  119:384  [2511 gas]
│   ├── ERC20CRV.start_epoch_time_write  [CALL]  411:499  [1832 gas]
│   ├── GaugeController.gauge_relative_weight_write  [CALL]  529:1017  [3178 / 7190 gas]
│   │   └── GaugeController.change_epoch  697:953  [2180 / 4012 gas]
│   │       └── ERC20CRV.start_epoch_time_write  [CALL]  718:806  [1832 gas]
│   └── GaugeController.period  [STATICCALL]  1043:1336  [2585 gas]
├── LiquidityGauge._update_liquidity_limit  1929:2950  [45242 / 54376 gas]
│   ├── VotingEscrow.balanceOf  [STATICCALL]  1957:2154  [2268 gas]
│   └── VotingEscrow.totalSupply  [STATICCALL]  2180:2768  [6029 / 6866 gas]
│       └── VotingEscrow.supply_at  2493:2748  [837 gas]
└── ERC20LP.transferFrom  [CALL]  2985:3098  [1946 gas]

Setting expand=True displays an expanded call trace that also includes function inputs and return values for all external calls.

>>> history[-1].call_trace(True)

Call trace for '0x7824c6032966ca2349d6a14ec3174d48d546d0fb3020a71b08e50c7b31c1bcb1':
Initial call cost  [21228 gas]
LiquidityGauge.deposit  0:3103  [64010 / 128030 gas]
├── LiquidityGauge._checkpoint  83:1826  [-6420 / 7698 gas]
│   │
│   ├── GaugeController.get_period_timestamp  [STATICCALL]  119:384  [2511 gas]
│   │       ├── address: 0x0C41Fc429cC21BC3c826efB3963929AEdf1DBb8e
│   │       ├── input arguments:
│   │       │   └── p: 0
│   │       └── return value: 1594574319
...

classmethod TransactionReceipt.traceback()

Returns an error traceback for the transaction, similar to a regular python traceback. If the transaction did not revert, returns an empty string.

>>> tx = >>> Token[0].transfer(accounts[1], "100000 ether")

Transaction sent: 0x9542e92a904e9d345def311ea52f22c3191816c6feaf7286f9b48081ab255ffa
Token.transfer confirmed (reverted) - block: 5   gas used: 23956 (100.00%)
<Transaction object '0x9542e92a904e9d345def311ea52f22c3191816c6feaf7286f9b48081ab255ffa'>

>>> tx.traceback()
Traceback for '0x9542e92a904e9d345def311ea52f22c3191816c6feaf7286f9b48081ab255ffa':
Trace step 99, program counter 1699:
  File "contracts/Token.sol", line 67, in Token.transfer:
    balances[msg.sender] = balances[msg.sender].sub(_value);
Trace step 110, program counter 1909:
  File "contracts/SafeMath.sol", line 9, in SafeMath.sub:
    require(b <= a);

classmethod TransactionReceipt.error(pad=3)

Displays the source code that caused the first revert in the transaction, if any.

• pad: Number of unrelated liness of code to include before and after the relevant source

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.error()
Source code for trace step 86:
  File "contracts/SafeMath.sol", line 9, in SafeMath.sub:

        c = a + b;
        require(c >= a);
    }
    function sub(uint a, uint b) internal pure returns (uint c) {
        require(b <= a);
        c = a - b;
    }
    function mul(uint a, uint b) internal pure returns (uint c) {
        c = a * b;

classmethod TransactionReceipt.source(idx, pad=3)

Displays the associated source code for a given stack trace step.

• idx: Stack trace step index

• pad: Number of unrelated liness of code to include before and after the relevant source

>>> tx
<Transaction object '0xac54b49987a77805bf6bdd78fb4211b3dc3d283ff0144c231a905afa75a06db0'>
>>> tx.source(86)
Source code for trace step 86:
  File "contracts/SafeMath.sol", line 9, in SafeMath.sub:

        c = a + b;
        require(c >= a);
    }
    function sub(uint a, uint b) internal pure returns (uint c) {
        require(b <= a);
        c = a - b;
    }
    function mul(uint a, uint b) internal pure returns (uint c) {
        c = a * b;

classmethod TransactionReceipt.wait(n)

Will wait for n confirmations of the transaction. This has no effect if n is less than the current amount of confirmations.

>>> tx
<Transaction '0x830b842e24efae712b67dddd97633356122c36e6cf2193fcf9f7dc635c4cbe2f'>
>>> tx.wait(2)
This transaction already has 3 confirmations.
>>> tx.wait(6)
Required confirmations: 6/6
  Transaction confirmed - Block: 17   Gas used: 21000 (0.31%)

brownie.network.web3

The web3 module contains a slightly modified version of the web3.py Web3 class that is used throughout various Brownie modules for RPC communication.

Web3

See the Web3 API documentation for detailed information on all the methods and attributes available here. This document only outlines methods that differ from the normal Web3 public interface.

class brownie.network.web3.Web3

Brownie subclass of Web3. An instance is created at brownie.network.web3.web and available for import from the main package.

>>> from brownie import web3
>>>

Web3 Methods

classmethod Web3.connect(uri, timeout=30)

Connects to a provider. uri can be the path to a local IPC socket, a websocket address beginning in ws:// or a URL.

>>> web3.connect('https://127.0.0.1:8545')
>>>

classmethod Web3.disconnect()

Disconnects from a provider.

>>> web3.disconnect()
>>>

Web3 Attributes

classmethod Web3.chain_uri()

Returns a BIP122 blockchain URI for the active chain.

>>> web3.chain_uri
'blockchain://a82ff4a4184a7b9e57aba1ae1ef91214c7d14a1040f4e1df8c0ec95f87a5bb62/block/66760b538b3f02f6fbd4a745b3943af9fda982f2b8b26b502180ed96b2c7f52d'

classmethod Web3.genesis_hash()

Returns the hash of the genesis block for the active chain, as a string without a 0x prefix.

>>> web3.genesis_hash
'41941023680923e0fe4d74a34bdac8141f2540e3ae90623718e47d66d1ca4a2d'

classmethod Web3.supports_traces()

Boolean indicating if the currently connected node client supports the debug_traceTransaction RPC endpoint.

>>> web3.supports_traces
True

Web3 Internals

Web3._mainnet

Provides access to a Web3 instance connected to the mainnet network as defined in the configuration file. Used internally for ENS and ethPM lookups.

Raises MainnetUndefined if the mainnet network is not defined.

Internal Methods

brownie.network.web3._resolve_address(address)

Used internally for standardizing address inputs. If address is a string containing a . Brownie will attempt to resolve an ENS domain name address. Otherwise, returns the result of convert.to_address.