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
```