Network Management

Brownie can be used with both development and live environments.

  • A development environment is a local, temporary network used for testing and debugging. Brownie uses Ganache for development environments.
  • A live environment is a non-local, persistent blockchain. This term is used to refer to both the Ethereum mainnet and testnets.

Network Configuration

Networks settings are handled using the command-line:

$ brownie networks

Viewing Existing Networks

Networks are broadly categorized as “development” (local, ephemeral environments) and “live” (non-local, persistent environments). Live networks are additionally categorized by chain (Ethereum, ETC, etc).

Type brownie networks list to view a list of existing networks:

$ brownie networks list
Brownie - Python development framework for Ethereum

The following networks are declared:

Ethereum
  ├─Mainnet (Infura): mainnet
  ├─Ropsten (Infura): ropsten
  ├─Rinkeby (Infura): rinkeby
  ├─Goerli (Infura): goerli
  └─Kovan (Infura): kovan

Ethereum Classic
  ├─Mainnet: etc
  └─Kotti: kotti

Development
  ├─Ganache-CLI: development
  └─Ganache-CLI (Mainnet Fork): mainnet-fork

Adding a New Network

To add a new network:

$ brownie networks add [environment] [id] host=[host] [KEY=VALUE, ...]

When declaring a new network, the following fields must always be included:

  • environment: the category that the network should be placed in, e.g. “Ethereum”, “Ethereum Classic”, or “Development”
  • id: a unique identifier for the network, e.g. “mainnet”
  • host: the address of the node to connect to, e.g. https://mainnet.infura.io/v3/1234567890abcdef

The following fields are optional:

  • name A longer name to use for the network. If not given, id is used.
  • timeout: The number of seconds to wait for a response when making an RPC call. Defaults to 30.

There are additional required and optional fields that are dependent on the type of network.

Live Networks

Live networks must include the following fields:

The following fields are optional for live networks:

  • explorer: API url used by Contract.from_explorer to fetch source code. If this field is not given, you will not be able to fetch source code when using this network.

Development Networks

Development networks must include the following fields:

  • cmd: The command used to launch the local RPC client, e.g. ganache-cli.

The following optional fields may be given for development networks, which are passed into Ganache as commandline arguments:

  • port: The port to connect to. If not given as a unique field, it should be included within the host path.
  • gas_limit: The block gas limit. Defaults to 6721925.
  • accounts: The number of funded, unlocked accounts. Default 10.
  • mnemonic: A mnemonic to use when generating local accounts.
  • chain_id: The chain id as integer used for eth_chainId and the CHAINID opcode. If no value is given, defaults to the chain id of the forked network or to 1337 and 1 respectively if no fork is specified.
  • network_id: The network id as integer used by ganache to identify itself. Defaults to the current timestamp or the network id of the forked chain.
  • evm_version: The EVM ruleset to use. Default is the most recent available.
  • fork: If given, the local client will fork from another currently running Ethereum client. The value may be an HTTP location and port of the other client, e.g. http://localhost:8545, or the ID of a production network, e.g. mainnet. See Using a Forked Development Network.
  • block_time: The time waited between mining blocks. Defaults to instant mining.
  • default_balance: The starting balance for all unlocked accounts. Can be given as unit string like “1000 ether” or “50 gwei” or as an number in Ether. Will default to 100 ether.
  • time: Date (ISO 8601) that the first block should start. Use this feature, along with Chain.sleep to test time-dependent code. Defaults to the current time.
  • unlock: A single address or a list of addresses to unlock. These accounts are added to the Accounts container and can be used as if the private key is known. Also works in combination with fork to send transactions from any account.

Note

These optional commandline fields can also be specified on a project level in the project’s brownie-config.yaml file. See the configuration files.

Note

brownie networks list true shows a detailed view of existing networks, including all configuration fields. This can be useful for defining fields of a new network.

Setting the Default Network

To modify the default network, add the``networks.default`` field to your project configuration file:

networks:
    default: ropsten

If a configuration file does not exist you will have to create one. See the documentation on configuration files for more information.

Launching and Connecting

Using the CLI

By default, Brownie will launch and connect to ganache-cli each time it is loaded. To connect to a different network, use the --network flag with the ID of the network you wish to connect to:

$ brownie --network ropsten

Using brownie.network

The brownie.network module contains methods that allow you to connect or disconnect from any already-defined network.

To connect to a network:

>>> network.connect('ropsten')
>>> network.is_connected()
True
>>> network.show_active()
'ropsten'

To disconnect:

>>> network.disconnect()
>>> network.is_connected()
False

Live Networks

In addition to using ganache-cli as a local development environment, Brownie can be used on live networks (i.e. any testnet/mainnet node that supports JSON RPC).

Warning

Before you go any further, consider that connecting to a live network can potentially expose your private keys if you aren’t careful:

  • When interacting with the mainnet, make sure you verify all of the details of any transactions before signing or sending. Brownie cannot protect you from sending ETH to the wrong address, sending too much, etc.
  • Always protect your private keys. Don’t leave them lying around unencrypted!

Personal Node vs Hosted Node

To interact with a live network you must connect to a node. You can either run your own node, or connect to a hosted node.

Running your Own Node

Clients such as Geth or Parity can be used to run your own Ethereum node, that Brownie can then connect to. Having your node gives you complete control over which RPC endpoints are available and ensures you have a private and dedicated connection to the network. Unfortunately, keeping a node operating and synced can be a challenging task.

If you wish to learn more about running a node, ethereum.org provides a list of resources that you can use to get started.

Using a Hosted Node

Services such as Infura provide public access to Ethereum nodes. This is a much simpler option than running your own, but it is not without limitations:

  1. Some RPC endpoints may be unavailable. In particular, Infura does not provide access to the debug_traceTransaction method. For this reason, Brownie’s debugging tools will not work when connected via Infura.
  2. Hosted nodes do not provide access to accounts - this would be a major security hazard! You will have to manually unlock your own local account before you can make a transaction.
Using Infura

To Infura you need to register for an account. Once you have signed up, login and create a new project. You will be provided with a project ID, as well as API URLs that can be leveraged to access the network.

To connect to Infura using Brownie, store your project ID as an environment variable named WEB3_INFURA_PROJECT_ID. You can do so with the following command:

$ export WEB3_INFURA_PROJECT_ID=YourProjectID

Using a Forked Development Network

Ganache allows you create a development network by forking from an live network. This is useful for testing interactions between your project and other projects that are deployed on the main-net.

Brownie’s mainnet-fork network uses Infura to create a development network that forks from the main-net. To connect with the console:

$ brownie console --network mainnet-fork

In this mode, you can use Contract.from_explorer to fetch sources and interact with contracts on the network you have forked from.

Note

Forking from Infura can be very slow. If you are using this mode extensively, it may be useful to run your own Geth node.