0
# Address Operations
1
2
Comprehensive Ethereum address handling including validation, format conversion, and EIP-55 checksum processing. Supports all address formats used in Ethereum: binary (20 bytes), hex, normalized (lowercase), and checksummed.
3
4
## Capabilities
5
6
### Address Validation
7
8
Check if a value is a valid Ethereum address in any format.
9
10
```python { .api }
11
def is_address(value) -> bool:
12
"""
13
Check if value is any valid Ethereum address format.
14
15
Args:
16
value: Value to check for address validity
17
18
Returns:
19
bool: True if value is a valid address format
20
"""
21
```
22
23
```python
24
from eth_utils import is_address
25
26
# Valid addresses return True
27
is_address("0xd3CdA913deB6f67967B99D67aCDFa1712C293601") # True
28
is_address("0xd3cda913deb6f67967b99d67acdfa1712c293601") # True
29
is_address(b'\xd3\xcd\xa9\x13\xde\xb6\xf6yg\xb9\x9dg\xac\xdf\xa1q,)6\x01') # True
30
31
# Invalid addresses return False
32
is_address("0x123") # False (too short)
33
is_address("not an address") # False
34
```
35
36
### Format-Specific Validation
37
38
Check for specific address formats.
39
40
```python { .api }
41
def is_binary_address(value) -> bool:
42
"""Check if value is 20-byte binary address."""
43
44
def is_hex_address(value) -> bool:
45
"""Check if value is hex-encoded address (40 hex chars with 0x prefix)."""
46
47
def is_canonical_address(address) -> bool:
48
"""Check if address is in canonical (20-byte) format."""
49
50
def is_normalized_address(value) -> bool:
51
"""Check if address is normalized (lowercase hex with 0x prefix)."""
52
53
def is_checksum_address(value) -> bool:
54
"""Validate EIP-55 checksum address format."""
55
56
def is_checksum_formatted_address(value) -> bool:
57
"""Check if address has checksum formatting (mixed case)."""
58
```
59
60
### Address Format Conversion
61
62
Convert addresses between different formats.
63
64
```python { .api }
65
def to_canonical_address(address) -> bytes:
66
"""
67
Convert address to canonical 20-byte format.
68
69
Args:
70
address: Address in any valid format
71
72
Returns:
73
bytes: 20-byte canonical address
74
75
Raises:
76
ValidationError: If address is invalid
77
"""
78
79
def to_checksum_address(value) -> str:
80
"""
81
Convert address to EIP-55 checksum format.
82
83
Args:
84
value: Address in any valid format
85
86
Returns:
87
str: EIP-55 checksummed address (0x-prefixed)
88
89
Raises:
90
ValidationError: If address is invalid
91
"""
92
93
def to_normalized_address(value) -> str:
94
"""
95
Convert address to normalized format (lowercase hex).
96
97
Args:
98
value: Address in any valid format
99
100
Returns:
101
str: Normalized address (0x-prefixed lowercase)
102
103
Raises:
104
ValidationError: If address is invalid
105
"""
106
```
107
108
```python
109
from eth_utils import to_checksum_address, to_canonical_address, to_normalized_address
110
111
address = "0xd3cda913deb6f67967b99d67acdfa1712c293601"
112
113
# Convert to checksum format (EIP-55)
114
checksum = to_checksum_address(address)
115
print(checksum) # 0xd3CdA913deB6f67967B99D67aCDFa1712C293601
116
117
# Convert to canonical (bytes) format
118
canonical = to_canonical_address(address)
119
print(canonical.hex()) # d3cda913deb6f67967b99d67acdfa1712c293601
120
121
# Convert to normalized (lowercase) format
122
normalized = to_normalized_address(address)
123
print(normalized) # 0xd3cda913deb6f67967b99d67acdfa1712c293601
124
```
125
126
### Address Comparison
127
128
Compare addresses for equality regardless of format.
129
130
```python { .api }
131
def is_same_address(left, right) -> bool:
132
"""
133
Compare two addresses for equality (format-agnostic).
134
135
Args:
136
left: First address in any valid format
137
right: Second address in any valid format
138
139
Returns:
140
bool: True if addresses represent the same Ethereum address
141
142
Raises:
143
ValidationError: If either address is invalid
144
"""
145
```
146
147
```python
148
from eth_utils import is_same_address
149
150
# These all represent the same address
151
addr1 = "0xd3CdA913deB6f67967B99D67aCDFa1712C293601" # Checksum
152
addr2 = "0xd3cda913deb6f67967b99d67acdfa1712c293601" # Lowercase
153
addr3 = b'\xd3\xcd\xa9\x13\xde\xb6\xf6yg\xb9\x9dg\xac\xdf\xa1q,)6\x01' # Binary
154
155
print(is_same_address(addr1, addr2)) # True
156
print(is_same_address(addr1, addr3)) # True
157
print(is_same_address(addr2, addr3)) # True
158
```
159
160
## Address Format Types
161
162
Ethereum addresses can be represented in multiple formats:
163
164
- **Binary (Canonical)**: 20-byte `bytes` object
165
- **Hex**: 42-character string with '0x' prefix (40 hex chars + prefix)
166
- **Normalized**: Hex format with all lowercase letters
167
- **Checksum**: Hex format with EIP-55 mixed case for error detection
168
169
## Common Patterns
170
171
### Safe Address Handling
172
173
```python
174
from eth_utils import is_address, to_checksum_address
175
176
def process_address(addr_input):
177
"""Safely process an address input."""
178
if not is_address(addr_input):
179
raise ValueError(f"Invalid address: {addr_input}")
180
181
# Always work with checksum format for display
182
return to_checksum_address(addr_input)
183
184
# Usage
185
user_input = "0xd3cda913deb6f67967b99d67acdfa1712c293601"
186
safe_addr = process_address(user_input)
187
print(safe_addr) # 0xd3CdA913deB6f67967B99D67aCDFa1712C293601
188
```
189
190
### Address Collection Deduplication
191
192
```python
193
from eth_utils import to_canonical_address
194
195
def deduplicate_addresses(addresses):
196
"""Remove duplicate addresses regardless of format."""
197
canonical_set = set()
198
unique_addresses = []
199
200
for addr in addresses:
201
canonical = to_canonical_address(addr)
202
if canonical not in canonical_set:
203
canonical_set.add(canonical)
204
unique_addresses.append(addr)
205
206
return unique_addresses
207
```