0
# Ethereum Operations  
1

2
Core Ethereum blockchain operations including transaction management, block and account queries, smart contract deployment and interaction, event filtering, and gas management.
3

4
## Capabilities
5

6
### Account Operations
7

8
Account management and balance queries.
9

10
```python { .api }
11
class Eth:
12
    @property
13
    def accounts(self) -> List[ChecksumAddress]:
14
        """Get list of available accounts."""
15

16
    @property
17
    def coinbase(self) -> ChecksumAddress:
18
        """Get coinbase account."""
19

20
    def get_balance(
21
        self,
22
        account: AnyAddress,
23
        block_identifier: BlockIdentifier = "latest"
24
    ) -> Wei:
25
        """
26
        Get account balance in Wei.
27
        
28
        Parameters:
29
        - account: Account address
30
        - block_identifier: Block number, hash, or 'latest'/'pending'
31
        """
32

33
    def get_transaction_count(
34
        self,
35
        account: AnyAddress,
36
        block_identifier: BlockIdentifier = "latest"
37
    ) -> Nonce:
38
        """
39
        Get account transaction count (nonce).
40
        
41
        Parameters:
42
        - account: Account address
43
        - block_identifier: Block number, hash, or 'latest'/'pending'
44
        """
45

46
    def get_code(
47
        self,
48
        account: AnyAddress,
49
        block_identifier: BlockIdentifier = "latest"
50
    ) -> HexBytes:
51
        """
52
        Get account code (for contracts).
53
        
54
        Parameters:
55
        - account: Account address
56
        - block_identifier: Block number, hash, or 'latest'/'pending'
57
        """
58
```
59

60
### Block Operations
61

62
Block queries and information retrieval.
63

64
```python { .api }
65
class Eth:
66
    @property
67
    def block_number(self) -> BlockNumber:
68
        """Get latest block number."""
69

70
    def get_block(
71
        self,
72
        block_identifier: BlockIdentifier,
73
        full_transactions: bool = False
74
    ) -> BlockData:
75
        """
76
        Get block data.
77
        
78
        Parameters:
79
        - block_identifier: Block number, hash, or 'latest'/'pending'
80
        - full_transactions: Include full transaction data
81
        """
82

83
    def get_block_transaction_count(
84
        self,
85
        block_identifier: BlockIdentifier
86
    ) -> int:
87
        """
88
        Get transaction count in block.
89
        
90
        Parameters:
91
        - block_identifier: Block number, hash, or 'latest'/'pending'
92
        """
93

94
    def get_block_receipts(
95
        self,
96
        block_identifier: BlockIdentifier
97
    ) -> BlockReceipts:
98
        """
99
        Get all transaction receipts in block.
100
        
101
        Parameters:
102
        - block_identifier: Block number, hash, or 'latest'/'pending'
103
        """
104

105
    @property
106
    def gas_price(self) -> Wei:
107
        """Get current gas price."""
108

109
    @property
110
    def max_priority_fee(self) -> Wei:
111
        """Get max priority fee per gas."""
112

113
    @property
114
    def blob_base_fee(self) -> Wei:
115
        """Get current blob base fee."""
116

117
    def fee_history(
118
        self,
119
        block_count: int,
120
        newest_block: BlockIdentifier = "latest",
121
        reward_percentiles: Optional[List[float]] = None
122
    ) -> FeeHistory:
123
        """
124
        Get fee history data.
125
        
126
        Parameters:
127
        - block_count: Number of blocks to query
128
        - newest_block: Most recent block
129
        - reward_percentiles: Percentiles for reward calculation
130
        """
131
```
132

133
### Transaction Operations
134

135
Transaction creation, sending, and monitoring.
136

137
```python { .api }  
138
class Eth:
139
    def send_transaction(self, transaction: TxParams) -> HexBytes:
140
        """
141
        Send transaction.
142
        
143
        Parameters:
144
        - transaction: Transaction parameters
145
        
146
        Returns:
147
        Transaction hash
148
        """
149

150
    def send_raw_transaction(self, transaction: HexStr) -> HexBytes:
151
        """
152
        Send raw signed transaction.
153
        
154
        Parameters:
155
        - transaction: Signed transaction data
156
        
157
        Returns:
158
        Transaction hash
159
        """
160

161
    def get_transaction(self, transaction_hash: Hash32) -> TxData:
162
        """
163
        Get transaction data.
164
        
165
        Parameters:
166
        - transaction_hash: Transaction hash
167
        """
168

169
    def get_transaction_receipt(self, transaction_hash: Hash32) -> TxReceipt:
170
        """
171
        Get transaction receipt.
172
        
173
        Parameters:
174
        - transaction_hash: Transaction hash
175
        """
176

177
    def get_raw_transaction(self, transaction_hash: Hash32) -> HexBytes:
178
        """
179
        Get raw transaction data.
180
        
181
        Parameters:
182
        - transaction_hash: Transaction hash
183
        """
184

185
    def get_transaction_by_block(
186
        self,
187
        block_identifier: BlockIdentifier,
188
        index: int
189
    ) -> TxData:
190
        """
191
        Get transaction by block and index.
192
        
193
        Parameters:
194
        - block_identifier: Block number, hash, or 'latest'/'pending'
195
        - index: Transaction index in block
196
        """
197

198
    def get_raw_transaction_by_block(
199
        self,
200
        block_identifier: BlockIdentifier,
201
        index: int
202
    ) -> HexBytes:
203
        """
204
        Get raw transaction by block and index.
205
        
206
        Parameters:
207
        - block_identifier: Block number, hash, or 'latest'/'pending'
208
        - index: Transaction index in block
209
        """
210

211
    def wait_for_transaction_receipt(
212
        self,
213
        transaction_hash: Hash32,
214
        timeout: float = 120,
215
        poll_latency: float = 0.1
216
    ) -> TxReceipt:
217
        """
218
        Wait for transaction to be mined.
219
        
220
        Parameters:
221
        - transaction_hash: Transaction hash
222
        - timeout: Maximum wait time in seconds
223
        - poll_latency: Polling interval in seconds
224
        """
225

226
    def estimate_gas(
227
        self,
228
        transaction: TxParams,
229
        block_identifier: BlockIdentifier = "latest"
230
    ) -> int:
231
        """
232
        Estimate gas for transaction.
233
        
234
        Parameters:
235
        - transaction: Transaction parameters
236
        - block_identifier: Block for estimation
237
        """
238

239
    def call(
240
        self,
241
        transaction: TxParams,
242
        block_identifier: BlockIdentifier = "latest",
243
        state_override: Optional[StateOverride] = None,
244
        ccip_read_enabled: Optional[bool] = None
245
    ) -> HexBytes:
246
        """
247
        Execute contract call without creating transaction.
248
        
249
        Parameters:
250
        - transaction: Transaction parameters
251
        - block_identifier: Block for execution
252
        - state_override: State override for the call
253
        - ccip_read_enabled: Enable CCIP read functionality
254
        """
255

256
    def create_access_list(
257
        self,
258
        transaction: TxParams,
259
        block_identifier: BlockIdentifier = "latest"
260
    ) -> CreateAccessListResponse:
261
        """
262
        Create access list for transaction.
263
        
264
        Parameters:
265
        - transaction: Transaction parameters
266
        - block_identifier: Block for estimation
267
        """
268

269
    def replace_transaction(
270
        self,
271
        transaction_hash: Hash32,
272
        new_transaction: TxParams
273
    ) -> HexBytes:
274
        """
275
        Replace pending transaction.
276
        
277
        Parameters:
278
        - transaction_hash: Original transaction hash
279
        - new_transaction: New transaction parameters
280
        """
281

282
    def modify_transaction(
283
        self,
284
        transaction_hash: Hash32,
285
        **transaction_params: Any
286
    ) -> HexBytes:
287
        """
288
        Modify pending transaction.
289
        
290
        Parameters:
291
        - transaction_hash: Original transaction hash
292
        - transaction_params: Modified transaction parameters
293
        """
294
```
295

296
### Contract Operations
297

298
Smart contract deployment and interaction.
299

300
```python { .api }
301
class Eth:  
302
    def contract(
303
        self,
304
        address: Optional[AnyAddress] = None,
305
        abi: Optional[ABI] = None,
306
        ContractFactoryClass: Type[Contract] = Contract,
307
        **contract_kwargs: Any
308
    ) -> Contract:
309
        """
310
        Create contract instance.
311
        
312
        Parameters:
313
        - address: Contract address (for existing contracts)
314
        - abi: Contract ABI
315
        - ContractFactoryClass: Contract factory class
316
        - contract_kwargs: Additional contract arguments
317
        """
318

319
    def get_storage_at(
320
        self,
321
        account: AnyAddress,
322
        position: int,
323
        block_identifier: BlockIdentifier = "latest"
324
    ) -> HexBytes:
325
        """
326
        Get storage at position.
327
        
328
        Parameters:
329
        - account: Contract address
330
        - position: Storage slot position  
331
        - block_identifier: Block number, hash, or 'latest'/'pending'
332
        """
333

334
    def get_proof(
335
        self,
336
        account: AnyAddress,
337
        positions: Sequence[int],
338
        block_identifier: BlockIdentifier = "latest"
339
    ) -> MerkleProof:
340
        """
341
        Get Merkle proof for account and storage positions.
342
        
343
        Parameters:
344
        - account: Account address
345
        - positions: Storage positions to prove
346
        - block_identifier: Block number, hash, or 'latest'/'pending'
347
        """
348

349
    def set_contract_factory(
350
        self,
351
        contract_factory: Type[Contract]
352
    ) -> None:
353
        """
354
        Set contract factory class.
355
        
356
        Parameters:
357
        - contract_factory: Contract factory class
358
        """
359
```
360

361
### Signing Operations
362

363
Cryptographic signing operations for transactions and messages.
364

365
```python { .api }
366
class Eth:
367
    def sign(
368
        self,
369
        account: AnyAddress,
370
        data: Union[int, bytes] = None,
371
        hexstr: HexStr = None,
372
        text: str = None
373
    ) -> HexStr:
374
        """
375
        Sign data with account.
376
        
377
        Parameters:
378
        - account: Account address
379
        - data: Data to sign (bytes)
380
        - hexstr: Data to sign (hex string)
381
        - text: Data to sign (text)
382
        """
383

384
    def sign_transaction(self, transaction: TxParams) -> SignedTx:
385
        """
386
        Sign transaction.
387
        
388
        Parameters:
389
        - transaction: Transaction parameters
390
        """
391

392
    def sign_typed_data(
393
        self,
394
        account: AnyAddress,
395
        data: Dict[str, Any]
396
    ) -> HexStr:
397
        """
398
        Sign structured data (EIP-712).
399
        
400
        Parameters:
401
        - account: Account address
402
        - data: Structured data to sign
403
        """
404
```
405

406
### Simulation Operations
407

408
Advanced transaction simulation capabilities.
409

410
```python { .api }
411
class Eth:
412
    def simulate_v1(
413
        self,
414
        payload: SimulateV1Payload,
415
        block_identifier: BlockIdentifier
416
    ) -> Sequence[SimulateV1Result]:
417
        """
418
        Simulate transaction bundle.
419
        
420
        Parameters:
421
        - payload: Simulation payload
422
        - block_identifier: Block for simulation
423
        """
424
```
425

426
### Event and Log Operations
427

428
Event filtering and log retrieval.
429

430
```python { .api }
431
class Eth:
432
    def get_logs(self, filter_params: FilterParams) -> List[LogReceipt]:
433
        """
434
        Get logs matching filter.
435
        
436
        Parameters:
437
        - filter_params: Filter parameters
438
        """
439

440
    def filter(self, filter_params: FilterParams) -> LogFilter:
441
        """
442
        Create log filter.
443
        
444
        Parameters:  
445
        - filter_params: Filter parameters
446
        """
447

448
    def get_filter_changes(self, filter_id: HexStr) -> List[LogReceipt]:
449
        """
450
        Get filter changes.
451
        
452
        Parameters:
453
        - filter_id: Filter identifier
454
        """
455

456
    def get_filter_logs(self, filter_id: HexStr) -> List[LogReceipt]:
457
        """
458
        Get all logs for filter.
459
        
460
        Parameters:
461
        - filter_id: Filter identifier
462
        """
463

464
    def uninstall_filter(self, filter_id: HexStr) -> bool:
465
        """
466
        Uninstall filter.
467
        
468
        Parameters:
469
        - filter_id: Filter identifier
470
        """
471
```
472

473
### Mining Operations
474

475
Mining and blockchain state operations.
476

477
```python { .api }
478
class Eth:
479
    @property
480
    def mining(self) -> bool:
481
        """Check if node is mining."""
482

483
    @property
484
    def hashrate(self) -> int:
485
        """Get current hashrate."""
486

487
    @property
488
    def syncing(self) -> Union[bool, SyncStatus]:
489
        """Get syncing status."""
490

491
    @property
492
    def chain_id(self) -> int:
493
        """Get chain ID."""
494
```
495

496
## Async Operations
497

498
All Eth operations have async equivalents in AsyncEth with the same API.
499

500
```python { .api }
501
class AsyncEth:
502
    async def get_balance(
503
        self,
504
        account: AnyAddress,
505
        block_identifier: BlockIdentifier = "latest"
506
    ) -> Wei:
507
        """Async version of get_balance."""
508

509
    async def send_transaction(self, transaction: TxParams) -> HexBytes:
510
        """Async version of send_transaction."""
511

512
    async def wait_for_transaction_receipt(
513
        self,
514
        transaction_hash: Hash32,
515
        timeout: float = 120,
516
        poll_latency: float = 0.1
517
    ) -> TxReceipt:
518
        """Async version of wait_for_transaction_receipt."""
519

520
    async def subscribe(
521
        self,
522
        subscription_type: SubscriptionType,
523
        subscription_arg: Optional[Union[LogsSubscriptionArg, bool]] = None,
524
        handler: Optional[EthSubscriptionHandler] = None,
525
        handler_context: Optional[Dict[str, Any]] = None,
526
        label: Optional[str] = None,
527
        parallelize: Optional[bool] = None
528
    ) -> HexStr:
529
        """
530
        Subscribe to events (WebSocket only).
531
        
532
        Parameters:
533
        - subscription_type: Type of subscription
534
        - subscription_arg: Subscription arguments
535
        - handler: Event handler function
536
        - handler_context: Handler context
537
        - label: Subscription label
538
        - parallelize: Enable parallel processing
539
        """
540

541
    async def unsubscribe(self, subscription_id: HexStr) -> bool:
542
        """
543
        Unsubscribe from events.
544
        
545
        Parameters:
546
        - subscription_id: Subscription ID to cancel
547
        """
548
```
549

550
## Usage Examples
551

552
### Basic Account Operations
553

554
```python
555
from web3 import Web3
556

557
w3 = Web3(Web3.HTTPProvider('https://mainnet.infura.io/v3/YOUR-PROJECT-ID'))
558

559
# Get account balance
560
address = '0x742d35Cc6635C0532925a3b8D5c0d9E3C4B3c8'
561
balance = w3.eth.get_balance(address)
562
balance_ether = w3.from_wei(balance, 'ether')
563
print(f"Balance: {balance_ether} ETH")
564

565
# Get transaction nonce
566
nonce = w3.eth.get_nonce(address)
567
print(f"Nonce: {nonce}")
568
```
569

570
### Transaction Sending
571

572
```python
573
from web3 import Web3
574

575
w3 = Web3(Web3.HTTPProvider('http://localhost:8545'))
576

577
# Build transaction
578
transaction = {
579
    'from': '0x742d35Cc6635C0532925a3b8D5c0d9E3C4B3c8',
580
    'to': '0x123...',
581
    'value': w3.to_wei(1, 'ether'),
582
    'gas': 21000,
583
    'gasPrice': w3.to_wei(20, 'gwei'),
584
    'nonce': w3.eth.get_nonce('0x742d35Cc6635C0532925a3b8D5c0d9E3C4B3c8')
585
}
586

587
# Send transaction
588
tx_hash = w3.eth.send_transaction(transaction)
589
print(f"Transaction hash: {tx_hash.hex()}")
590

591
# Wait for confirmation
592
receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
593
print(f"Transaction mined in block: {receipt.blockNumber}")
594
```
595

596
### Block Queries
597

598
```python
599
from web3 import Web3
600

601
w3 = Web3(Web3.HTTPProvider('https://mainnet.infura.io/v3/YOUR-PROJECT-ID'))
602

603
# Get latest block
604
latest_block = w3.eth.get_block('latest')
605
print(f"Block number: {latest_block.number}")
606
print(f"Block hash: {latest_block.hash.hex()}")
607
print(f"Transaction count: {len(latest_block.transactions)}")
608

609
# Get specific block with full transactions
610
block = w3.eth.get_block(17000000, full_transactions=True)
611
for tx in block.transactions:
612
    print(f"TX: {tx.hash.hex()} from {tx['from']} to {tx.to}")
613
```
614

615
### Event Filtering
616

617
```python
618
from web3 import Web3
619

620
w3 = Web3(Web3.HTTPProvider('https://mainnet.infura.io/v3/YOUR-PROJECT-ID'))
621

622
# Filter for Transfer events
623
filter_params = {
624
    'fromBlock': 'latest',
625
    'toBlock': 'latest',
626
    'topics': ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef']
627
}
628

629
# Create filter
630
event_filter = w3.eth.filter(filter_params)
631

632
# Get filter changes
633
while True:
634
    for event in w3.eth.get_filter_changes(event_filter.filter_id):
635
        print(f"Transfer event: {event}")
636
    time.sleep(2)
637
```
638

639
### Async Operations
640

641
```python
642
import asyncio
643
from web3 import AsyncWeb3
644

645
async def main():
646
    w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider('https://mainnet.infura.io/v3/YOUR-PROJECT-ID'))
647
    
648
    # Get balance asynchronously
649
    balance = await w3.eth.get_balance('0x742d35Cc6635C0532925a3b8D5c0d9E3C4B3c8')
650
    print(f"Balance: {w3.from_wei(balance, 'ether')} ETH")
651
    
652
    # Get latest block
653
    block = await w3.eth.get_block('latest')
654
    print(f"Latest block: {block.number}")
655

656
asyncio.run(main())
657
```