provider.anvil

Documentation for eth_defi.provider.anvil Python module.

Anvil integration.

_ ..anvil:

This module provides Python integration for Anvil.

Anvil is a blazing-fast local testnet node implementation in Rust from Foundry project
Anvil can replace eth_tester.main.EthereumTester as the unit/integration test backend.
Anvil is mostly used in mainnet fork test cases.
Anvil is a more stable an alternative to Ganache (eth_defi.ganache)
Anvil is part of Foundry, a toolkit for Ethereum application development.

To install Anvil on:

curl -L https://foundry.paradigm.xyz | bash
PATH=~/.foundry/bin:$PATH
foundryup  # Needs to be in path, or installation fails

This will install foundryup, anvil at ~/.foundry/bin and adds the folder to your shell rc file PATH.

For more information see Anvil reference.

See also eth_defi.trace for Solidity tracebacks using Anvil.

The code was originally lifted from Brownie project.

Module Attributes

CLI_FLAGS

Mappings between Anvil command line parameters and our internal argument names

Functions

`create_fork_funded_wallet`(web3, ...[, ...])	On Anvil forked mainnet, create a wallet with some USDC funds.
`dump_state`(web3)	Call evm_snapshot on Anvil
`fork_network_anvil`([fork_url, ...])	Creates Anvil unit test backend or mainnet fork.
`is_anvil`(web3)	Are we connected to Anvil node.
`is_mainnet_fork`(web3)	Have we forked mainnet for this test.
`launch_anvil`([fork_url, unlocked_addresses, ...])	Creates Anvil unit test backend or mainnet fork.
`load_state`(web3, state)	Call evm_snapshot on Anvil
`make_anvil_custom_rpc_request`(web3, method)	Make a request to special named EVM JSON-RPC endpoint.
`mine`(web3[, timestamp, increase_timestamp])	Call evm_setNextBlockTimestamp on Anvil.
`revert`(web3, snapshot_id)	Call evm_revert on Anvil
`set_balance`(web3, address, raw_amount)	Call anvil_setBalance on Anvil
`sleep`(web3, seconds)	Call emv_increaseTime on Anvil
`snapshot`(web3)	Call evm_snapshot on Anvil
`unlock_account`(web3, address)	Make Anvil mainnet fork to accept transactions to any Ethereum account.

Classes

AnvilLaunch

Control Anvil processes launched on background.

Exceptions

`InvalidArgumentWarning`	Lifted from Brownie.
`RPCRequestError`	Lifted from Brownie.

exception InvalidArgumentWarning

Bases: Warning

Lifted from Brownie.

__init__(*args, **kwargs)

__new__(**kwargs)

add_note(): Exception.add_note(note) – add a note to the exception

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception RPCRequestError

Bases: Exception

Lifted from Brownie.

__init__(*args, **kwargs)

__new__(**kwargs)

add_note(): Exception.add_note(note) – add a note to the exception

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

CLI_FLAGS = {'block_time': '--block-time', 'chain_id': '--chain-id', 'code_size_limit': '--code-size-limit', 'default_balance': '--balance', 'fork': '--fork-url', 'fork_block_number': '--fork-block-number', 'gas_limit': '--gas-limit', 'hardfork': '--hardfork', 'host': '--host', 'port': '--port', 'steps_tracing': '--steps-tracing', 'verbose': '-vvvvv'}: Mappings between Anvil command line parameters and our internal argument names

make_anvil_custom_rpc_request(web3, method, args=None)

Make a request to special named EVM JSON-RPC endpoint.

See the Anvil custom RPC methods here.

Parameters

method (str) – RPC endpoint name
args (Optional[list]) – JSON-RPC call arguments
web3 (web3.main.Web3) –

Returns

RPC result

Raises

RPCRequestError – In the case RPC method errors

Return type

Any

class AnvilLaunch

Bases: object

Control Anvil processes launched on background.

Comes with a helpful close() method when it is time to put Anvil rest.

port: int: Which port was bound by the Anvil

cmd: list[str]: Used command-line to spin up anvil

json_rpc_url: str: Where does Anvil listen to JSON-RPC

process: psutil.Popen: UNIX process that we opened

close(log_level=None, block=True, block_timeout=30)

Close the background Anvil process.

Parameters

log_level (Optional[int]) – Dump Anvil messages to logging
block – Block the execution until anvil is gone
block_timeout – How long time we try to kill Anvil until giving up.

Returns

Anvil stdout, stderr as string

Return type

tuple[bytes, bytes]

__init__(port, cmd, json_rpc_url, process)

Parameters

port (int) –
cmd (list[str]) –
json_rpc_url (str) –
process (psutil.Popen) –

Return type

None

launch_anvil(fork_url=None, unlocked_addresses=None, cmd='anvil', port=(19999, 29999, 25), block_time=0, launch_wait_seconds=20.0, attempts=3, hardfork='cancun', gas_limit=None, steps_tracing=False, test_request_timeout=3.0, fork_block_number=None, log_wait=False, code_size_limit=None, rpc_smoke_test=True, verbose=False)

Creates Anvil unit test backend or mainnet fork.

Anvil can be used as web3.py test backend instead of EthereumTester. Anvil offers faster execution and tracing - see eth_defi.trace.
Forking a mainnet is a common way to test against live deployments. This function invokes anvil command and tells it to fork a given JSON-RPC endpoint.

When called, a subprocess is started on the background. To stop this process, call eth_defi.anvil.AnvilLaunch.close().

This function waits launch_wait_seconds in order to anvil process to start and complete the chain fork.

Unit test backend:

See eth_defi.tests.enzyme.conftest for an example how to use Anvil in your Python based unit test suite

Mainnet fork: Here is an example that forks BNB chain mainnet and transfer 500 BUSD stablecoin to a test account we control:

from eth_defi.anvil import fork_network_anvil
from eth_defi.chain import install_chain_middleware
from eth_defi.gas import node_default_gas_price_strategy


@pytest.fixture()
def large_busd_holder() -> HexAddress:
    # An onchain address with BUSD balance
    # Binance Hot Wallet 6
    return HexAddress(HexStr("0x8894E0a0c962CB723c1976a4421c95949bE2D4E3"))


@pytest.fixture()
def user_1() -> LocalAccount:
    # Create a test account
    return Account.create()


@pytest.fixture()
def anvil_bnb_chain_fork(request, large_busd_holder, user_1, user_2) -> str:
    # Create a testable fork of live BNB chain.
    mainnet_rpc = os.environ["BNB_CHAIN_JSON_RPC"]
    launch = fork_network_anvil(mainnet_rpc, unlocked_addresses=[large_busd_holder])
    try:
        yield launch.json_rpc_url
    finally:
        # Wind down Anvil process after the test is complete
        launch.close(log_level=logging.ERROR)


@pytest.fixture()
def web3(anvil_bnb_chain_fork: str):
    # Set up a local unit testing blockchain
    # https://web3py.readthedocs.io/en/stable/examples.html#contract-unit-tests-in-python
    web3 = Web3(HTTPProvider(anvil_bnb_chain_fork))
    # Anvil needs POA middlware if parent chain needs POA middleware
    install_chain_middleware(web3)
    web3.eth.set_gas_price_strategy(node_default_gas_price_strategy)
    return web3


def test_anvil_fork_transfer_busd(web3: Web3, large_busd_holder: HexAddress, user_1: LocalAccount):
    # Forks the BNB chain mainnet and transfers from USDC to the user.

    # BUSD deployment on BNB chain
    # https://bscscan.com/token/0xe9e7cea3dedca5984780bafc599bd69add087d56
    busd_details = fetch_erc20_details(web3, "0xe9e7CEA3DedcA5984780Bafc599bD69ADd087D56")
    busd = busd_details.contract

    # Transfer 500 BUSD to the user 1
    tx_hash = busd.functions.transfer(user_1.address, 500 * 10**18).transact({"from": large_busd_holder})

    # Because Ganache has instamine turned on by default, we do not need to wait for the transaction
    receipt = web3.eth.get_transaction_receipt(tx_hash)
    assert receipt.status == 1, "BUSD transfer reverted"

    assert busd.functions.balanceOf(user_1.address).call() == 500 * 10**18

See the full example in tests source code.

If anvil refuses to terminate properly, you can kill a process by a port in your terminal:

# Kill any process listening to localhost:19999
kill -SIGKILL $(lsof -ti:19999)

See also launch_anvil()

Warning

This method will crash with Base mainnet sequencer:

requests.exceptions.HTTPError: 403 Client Error: Forbidden for url: https://mainnet-sequencer.base.org/.

Parameters: web3 (web3.main.Web3) – Web3 connection instance to check
Returns: True if we think we are connected to Anvil
Return type: bool

is_mainnet_fork(web3)

Have we forked mainnet for this test.

Only relevant with is_anvil()

Returns: True if we think we are connected to a forked mainnet, False if we think we are a standalone local dev chain.
Parameters: web3 (web3.main.Web3) –
Return type: bool

create_fork_funded_wallet(web3, usdc_address, large_usdc_holder, usdc_amount=Decimal('10000'), eth_amount=Decimal('10'))

On Anvil forked mainnet, create a wallet with some USDC funds.

Make a new private key account on a forked mainnet
Top this up with ETH and USDC from a large USDC holder

Parameters

web3 (web3.main.Web3) –
usdc_address (eth_typing.evm.HexAddress) –
large_usdc_holder (eth_typing.evm.HexAddress) –

Return type

eth_defi.hot_wallet.HotWallet

fork_network_anvil(fork_url=None, unlocked_addresses=None, cmd='anvil', port=(19999, 29999, 25), block_time=0, launch_wait_seconds=20.0, attempts=3, hardfork='cancun', gas_limit=None, steps_tracing=False, test_request_timeout=3.0, fork_block_number=None, log_wait=False, code_size_limit=None, rpc_smoke_test=True, verbose=False)

Creates Anvil unit test backend or mainnet fork.

Anvil can be used as web3.py test backend instead of EthereumTester. Anvil offers faster execution and tracing - see eth_defi.trace.
Forking a mainnet is a common way to test against live deployments. This function invokes anvil command and tells it to fork a given JSON-RPC endpoint.

When called, a subprocess is started on the background. To stop this process, call eth_defi.anvil.AnvilLaunch.close().

This function waits launch_wait_seconds in order to anvil process to start and complete the chain fork.

Unit test backend:

See eth_defi.tests.enzyme.conftest for an example how to use Anvil in your Python based unit test suite

Mainnet fork: Here is an example that forks BNB chain mainnet and transfer 500 BUSD stablecoin to a test account we control:

from eth_defi.anvil import fork_network_anvil
from eth_defi.chain import install_chain_middleware
from eth_defi.gas import node_default_gas_price_strategy


@pytest.fixture()
def large_busd_holder() -> HexAddress:
    # An onchain address with BUSD balance
    # Binance Hot Wallet 6
    return HexAddress(HexStr("0x8894E0a0c962CB723c1976a4421c95949bE2D4E3"))


@pytest.fixture()
def user_1() -> LocalAccount:
    # Create a test account
    return Account.create()


@pytest.fixture()
def anvil_bnb_chain_fork(request, large_busd_holder, user_1, user_2) -> str:
    # Create a testable fork of live BNB chain.
    mainnet_rpc = os.environ["BNB_CHAIN_JSON_RPC"]
    launch = fork_network_anvil(mainnet_rpc, unlocked_addresses=[large_busd_holder])
    try:
        yield launch.json_rpc_url
    finally:
        # Wind down Anvil process after the test is complete
        launch.close(log_level=logging.ERROR)


@pytest.fixture()
def web3(anvil_bnb_chain_fork: str):
    # Set up a local unit testing blockchain
    # https://web3py.readthedocs.io/en/stable/examples.html#contract-unit-tests-in-python
    web3 = Web3(HTTPProvider(anvil_bnb_chain_fork))
    # Anvil needs POA middlware if parent chain needs POA middleware
    install_chain_middleware(web3)
    web3.eth.set_gas_price_strategy(node_default_gas_price_strategy)
    return web3


def test_anvil_fork_transfer_busd(web3: Web3, large_busd_holder: HexAddress, user_1: LocalAccount):
    # Forks the BNB chain mainnet and transfers from USDC to the user.

    # BUSD deployment on BNB chain
    # https://bscscan.com/token/0xe9e7cea3dedca5984780bafc599bd69add087d56
    busd_details = fetch_erc20_details(web3, "0xe9e7CEA3DedcA5984780Bafc599bD69ADd087D56")
    busd = busd_details.contract

    # Transfer 500 BUSD to the user 1
    tx_hash = busd.functions.transfer(user_1.address, 500 * 10**18).transact({"from": large_busd_holder})

    # Because Ganache has instamine turned on by default, we do not need to wait for the transaction
    receipt = web3.eth.get_transaction_receipt(tx_hash)
    assert receipt.status == 1, "BUSD transfer reverted"

    assert busd.functions.balanceOf(user_1.address).call() == 500 * 10**18

See the full example in tests source code.

If anvil refuses to terminate properly, you can kill a process by a port in your terminal:

# Kill any process listening to localhost:19999
kill -SIGKILL $(lsof -ti:19999)