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:
chainid
: The chain ID for a network. Live networks with the same chain ID share local data about contract deployments. See chainid.network for a list of chain IDs.
The following fields are optional for live networks:
explorer
: API url used byContract.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.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 withChain.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 theAccounts
container and can be used as if the private key is known. Also works in combination withfork
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:
- 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.
- 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.