0
# eth-brownie
1
2
A comprehensive Python framework for Ethereum smart contract deployment, testing and interaction. Brownie provides publication-quality development tools for blockchain applications, serving as the foundational framework for Python-based Ethereum development with built-in support for Solidity and Vyper.
3
4
## Package Information
5
6
- **Package Name**: eth-brownie
7
- **Language**: Python
8
- **Installation**: `pip install eth-brownie`
9
10
## Core Imports
11
12
```python
13
import brownie
14
from brownie import accounts, Contract, project, network, chain, history, web3
15
```
16
17
Common imports for specific functionality:
18
19
```python
20
from brownie.convert import Wei, Fixed, to_address
21
from brownie.test import given, strategy
22
from brownie.network import gas_limit, gas_price, connect, disconnect
23
```
24
25
## Basic Usage
26
27
```python
28
from brownie import accounts, Contract, project, network
29
30
# Connect to local development network
31
network.connect('development')
32
33
# Get account for transactions
34
account = accounts[0] # Use first local account
35
# or load account from private key
36
account = accounts.add('0x...') # Add account from private key
37
38
# Deploy a contract
39
contract_source = '''
40
pragma solidity ^0.8.0;
41
contract SimpleStorage {
42
uint256 public storedData;
43
function set(uint256 x) public { storedData = x; }
44
function get() public view returns (uint256) { return storedData; }
45
}
46
'''
47
48
# Compile and deploy
49
compiled = project.compile_source(contract_source)
50
contract = compiled.SimpleStorage.deploy({'from': account})
51
52
# Interact with contract
53
tx = contract.set(42, {'from': account})
54
print(f"Transaction hash: {tx.txid}")
55
print(f"Stored value: {contract.get()}")
56
57
# Check transaction history
58
print(f"Gas used: {tx.gas_used}")
59
print(f"Transaction events: {tx.events}")
60
```
61
62
## Architecture
63
64
Brownie's architecture centers on several key components:
65
66
- **Accounts**: Manages private keys, signers, and transaction broadcasting
67
- **Network**: Handles blockchain connections, RPC nodes, and network state
68
- **Project**: Manages contract compilation, deployment artifacts, and scripts
69
- **Chain**: Provides blockchain state management including snapshots and time control
70
- **Convert**: Offers type conversion between Python and Ethereum data types
71
72
This design enables complete control over the smart contract development lifecycle from initial development through testing to production deployment.
73
74
## Capabilities
75
76
### Account Management
77
78
Comprehensive account management including local private key accounts, external signers, and transaction broadcasting with gas optimization and error handling.
79
80
```python { .api }
81
class Accounts:
82
def __getitem__(self, index: int) -> LocalAccount: ...
83
def add(self, private_key: str) -> LocalAccount: ...
84
def load(self, filename: str, password: str = None) -> LocalAccount: ...
85
86
class LocalAccount:
87
def __init__(self, address: str, private_key: str): ...
88
def transfer(self, to: str, amount: int, **kwargs) -> TransactionReceipt: ...
89
def deploy(self, contract, *args, **kwargs) -> Contract: ...
90
```
91
92
[Account Management](./accounts.md)
93
94
### Contract Interaction
95
96
Smart contract deployment, method calls, event handling, and transaction management with comprehensive debugging and error reporting capabilities.
97
98
```python { .api }
99
class Contract:
100
def __init__(self, address: str, abi: list): ...
101
def __getattr__(self, name: str): ... # Contract method access
102
103
class ProjectContract(Contract):
104
@classmethod
105
def deploy(cls, *args, **kwargs) -> 'ProjectContract': ...
106
107
class ContractContainer:
108
def deploy(self, *args, **kwargs) -> ProjectContract: ...
109
def at(self, address: str) -> ProjectContract: ...
110
```
111
112
[Contract Interaction](./contracts.md)
113
114
### Network Management
115
116
Blockchain network connections, RPC node management, chain state control, and multi-network configuration for development, testing, and production environments.
117
118
```python { .api }
119
def connect(network: str = None, launch_rpc: bool = True) -> None: ...
120
def disconnect() -> None: ...
121
def is_connected() -> bool: ...
122
123
class Chain:
124
def snapshot() -> str: ...
125
def revert(snapshot_id: str) -> None: ...
126
def mine(blocks: int = 1) -> None: ...
127
128
class Rpc:
129
def launch(self, cmd: str) -> None: ...
130
def kill(self) -> None: ...
131
```
132
133
[Network Management](./network.md)
134
135
### Project Management
136
137
Brownie project creation, contract compilation, script execution, and build artifact management with support for both Solidity and Vyper smart contracts.
138
139
```python { .api }
140
def new(path: str = ".", name: str = None, ignore_existing: bool = False) -> Project: ...
141
def load(project_path: str = ".", name: str = None) -> Project: ...
142
def compile_source(source: str, solc_version: str = None, **kwargs): ...
143
def run(script_path: str, method_name: str = None, *args, **kwargs): ...
144
145
class Project:
146
def load_config(self) -> None: ...
147
def compile(self, **kwargs) -> None: ...
148
def close(self) -> None: ...
149
```
150
151
[Project Management](./project.md)
152
153
### Data Conversion & Testing
154
155
Type conversion utilities for seamless interaction between Python and Ethereum data types, plus integration with Hypothesis for property-based testing.
156
157
```python { .api }
158
class Wei:
159
def __init__(self, value: Union[int, str, float]): ...
160
def to(self, unit: str) -> Union[int, float]: ...
161
162
def to_address(value: Any) -> str: ...
163
def to_uint(value: Any, type_str: str = "uint256") -> int: ...
164
def to_bytes(value: Any, type_str: str = "bytes32") -> bytes: ...
165
166
def given(**strategies) -> Callable: ... # Testing decorator
167
def strategy(name: str, **kwargs) -> Callable: ... # Strategy creator
168
```
169
170
[Data Conversion & Testing](./conversion-testing.md)
171
172
### Command Line Interface
173
174
Comprehensive CLI tools for project management, compilation, testing, and deployment with support for interactive console and GUI.
175
176
```bash { .api }
177
brownie init [project_name] # Initialize new project
178
brownie bake [template_name] # Create from brownie-mix template
179
brownie compile [options] # Compile contracts
180
brownie console [options] # Interactive Python console
181
brownie test [options] # Run test suite
182
brownie run [script] [method] # Execute project scripts
183
brownie accounts [command] # Manage local accounts
184
brownie networks [command] # Manage network connections
185
brownie pm [command] # Package manager
186
brownie gui [options] # Launch web GUI
187
```
188
189
[Command Line Interface](./cli.md)
190
191
### Exception Handling
192
193
Comprehensive exception hierarchy for handling network, contract, compilation, and transaction errors with detailed error messages and debugging support.
194
195
```python { .api }
196
# Network Exceptions
197
class VirtualMachineError(Exception): ... # EVM execution errors
198
class TransactionError(VirtualMachineError): ... # Transaction failures
199
class RPCConnectionError(Exception): ... # RPC connection issues
200
class MainnetUndefined(Exception): ... # Mainnet configuration errors
201
202
# Project Exceptions
203
class CompilerError(Exception): ... # Contract compilation errors
204
class ProjectNotFound(Exception): ... # Missing project errors
205
class ContractNotFound(Exception): ... # Contract reference errors
206
207
# Account Exceptions
208
class UnknownAccount(Exception): ... # Invalid account references
209
```
210
211
[Exception Handling](./exceptions.md)
212
213
### Configuration Management
214
215
Global configuration system for network settings, compiler options, and development environment customization through brownie-config.yaml files.
216
217
```python { .api }
218
# Global configuration access
219
config: ConfigContainer # Configuration settings container
220
221
# Configuration categories
222
config.networks # Network connection settings
223
config.compiler # Solidity/Vyper compiler settings
224
config.dependencies # Package dependency management
225
config.hypothesis # Property-based testing configuration
226
```
227
228
## Global Objects
229
230
```python { .api }
231
# Global singletons available after import
232
accounts: Accounts # Account management
233
chain: Chain # Blockchain state
234
history: TxHistory # Transaction history
235
rpc: Rpc # RPC node control
236
web3: Web3 # Web3 interface
237
multicall: Multicall # Batch calls
238
config: ConfigContainer # Configuration
239
240
# Constants
241
ETH_ADDRESS: str = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"
242
ZERO_ADDRESS: str = "0x0000000000000000000000000000000000000000"
243
```