fork_network_anvil

Documentation for eth_defi.anvil.fork_network_anvil function.

fork_network_anvil(fork_url=None, unlocked_addresses=None, cmd='anvil', port=19999, block_time=0, launch_wait_seconds=20.0, attempts=3, hardfork='london', gas_limit=None, steps_tracing=False, test_request_timeout=3.0)

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)