0
# Ethereum Interaction
1

2
The Web3Eth module provides comprehensive functionality for interacting with the Ethereum blockchain, including account queries, transaction handling, block operations, and gas estimation. It serves as the primary interface for all Ethereum-specific operations.
3

4
## Capabilities
5

6
### Account Queries
7

8
Retrieve account information and balances from the blockchain.
9

10
```typescript { .api }
11
/**
12
 * Get the balance of an account at a given block
13
 * @param address - The account address
14
 * @param blockNumber - Block number or tag (default: 'latest')
15
 * @param returnFormat - Return format for the response
16
 * @returns Account balance in wei
17
 */
18
getBalance(
19
  address: Address, 
20
  blockNumber?: BlockNumberOrTag, 
21
  returnFormat?: DataFormat
22
): Promise<bigint>;
23

24
/**
25
 * Get the transaction count (nonce) for an account
26
 * @param address - The account address  
27
 * @param blockNumber - Block number or tag (default: 'latest')
28
 * @param returnFormat - Return format for the response
29
 * @returns Transaction count
30
 */
31
getTransactionCount(
32
  address: Address,
33
  blockNumber?: BlockNumberOrTag,
34
  returnFormat?: DataFormat  
35
): Promise<bigint>;
36

37
/**
38
 * Get code at a given address
39
 * @param address - The contract address
40
 * @param blockNumber - Block number or tag (default: 'latest')
41
 * @param returnFormat - Return format for the response  
42
 * @returns Contract code
43
 */
44
getCode(
45
  address: Address,
46
  blockNumber?: BlockNumberOrTag,
47
  returnFormat?: DataFormat
48
): Promise<string>;
49
```
50

51
**Usage Examples:**
52

53
```typescript
54
// Get account balance
55
const balance = await web3.eth.getBalance('0x742C1382...');
56
const balanceInEther = web3.utils.fromWei(balance, 'ether');
57

58
// Get transaction count (nonce)
59
const nonce = await web3.eth.getTransactionCount('0x742C1382...');
60

61
// Get contract code
62
const code = await web3.eth.getCode('0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984');
63
```
64

65
### Transaction Operations
66

67
Send transactions, estimate gas, and retrieve transaction information.
68

69
```typescript { .api }
70
/**
71
 * Send a transaction to the network
72
 * @param transaction - Transaction object
73
 * @param returnFormat - Return format for the response
74
 * @returns PromiEvent with transaction receipt
75
 */
76
sendTransaction(
77
  transaction: Transaction,
78
  returnFormat?: DataFormat
79
): PromiEvent<TransactionReceipt>;
80

81
/**
82
 * Send a signed raw transaction
83
 * @param signedTransaction - Signed transaction data
84
 * @param returnFormat - Return format for the response
85
 * @returns PromiEvent with transaction receipt
86
 */
87
sendSignedTransaction(
88
  signedTransaction: Bytes,
89
  returnFormat?: DataFormat
90
): PromiEvent<TransactionReceipt>;
91

92
/**
93
 * Estimate gas required for a transaction
94
 * @param transaction - Transaction object
95
 * @param blockNumber - Block number or tag (default: 'latest')
96
 * @param returnFormat - Return format for the response
97
 * @returns Estimated gas amount
98
 */
99
estimateGas(
100
  transaction: Transaction,
101
  blockNumber?: BlockNumberOrTag,
102
  returnFormat?: DataFormat
103
): Promise<bigint>;
104

105
/**
106
 * Get transaction by hash
107
 * @param transactionHash - Transaction hash
108
 * @param returnFormat - Return format for the response
109
 * @returns Transaction object or null
110
 */
111
getTransaction(
112
  transactionHash: Bytes,
113
  returnFormat?: DataFormat
114
): Promise<TransactionInfo | null>;
115

116
/**
117
 * Get transaction receipt
118
 * @param transactionHash - Transaction hash
119
 * @param returnFormat - Return format for the response
120
 * @returns Transaction receipt or null
121
 */
122
getTransactionReceipt(
123
  transactionHash: Bytes,
124
  returnFormat?: DataFormat
125
): Promise<TransactionReceipt | null>;
126
```
127

128
**Usage Examples:**
129

130
```typescript
131
// Send a transaction
132
const receipt = await web3.eth.sendTransaction({
133
  from: '0x742C1382...',
134
  to: '0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984',
135
  value: web3.utils.toWei('0.1', 'ether'),
136
  gas: 21000
137
});
138

139
// Estimate gas
140
const gasEstimate = await web3.eth.estimateGas({
141
  to: '0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984',
142
  data: '0xa9059cbb...'
143
});
144

145
// Get transaction info
146
const tx = await web3.eth.getTransaction('0x123...');
147
const receipt = await web3.eth.getTransactionReceipt('0x123...');
148
```
149

150
### Block Operations
151

152
Retrieve block information and monitor new blocks.
153

154
```typescript { .api }
155
/**
156
 * Get block information
157
 * @param blockHashOrBlockNumber - Block hash or number
158
 * @param hydrated - Whether to include full transaction objects (default: false)
159
 * @param returnFormat - Return format for the response
160
 * @returns Block information
161
 */
162
getBlock(
163
  blockHashOrBlockNumber: Bytes | BlockNumberOrTag,
164
  hydrated?: boolean,
165
  returnFormat?: DataFormat
166
): Promise<Block>;
167

168
/**
169
 * Get the latest block number
170
 * @param returnFormat - Return format for the response
171
 * @returns Latest block number
172
 */
173
getBlockNumber(returnFormat?: DataFormat): Promise<bigint>;
174

175
/**
176
 * Get block transaction count
177
 * @param blockHashOrBlockNumber - Block hash or number
178
 * @param returnFormat - Return format for the response
179
 * @returns Number of transactions in block
180
 */
181
getBlockTransactionCount(
182
  blockHashOrBlockNumber: Bytes | BlockNumberOrTag,
183
  returnFormat?: DataFormat
184
): Promise<bigint>;
185
```
186

187
**Usage Examples:**
188

189
```typescript
190
// Get latest block
191
const latestBlock = await web3.eth.getBlock('latest');
192

193
// Get specific block with transactions
194
const block = await web3.eth.getBlock(18000000, true);
195

196
// Get current block number
197
const blockNumber = await web3.eth.getBlockNumber();
198
```
199

200
### Call Operations
201

202
Execute read-only contract calls and simulate transactions.
203

204
```typescript { .api }
205
/**
206
 * Execute a message call transaction
207
 * @param transaction - Call transaction object
208
 * @param blockNumber - Block number or tag (default: 'latest')
209
 * @param returnFormat - Return format for the response
210
 * @returns Call result
211
 */
212
call(
213
  transaction: Transaction,
214
  blockNumber?: BlockNumberOrTag,
215
  returnFormat?: DataFormat
216
): Promise<string>;
217

218
/**
219
 * Get storage value at a specific position
220
 * @param address - Contract address
221
 * @param storageSlot - Storage slot position
222
 * @param blockNumber - Block number or tag (default: 'latest')
223
 * @param returnFormat - Return format for the response
224
 * @returns Storage value
225
 */
226
getStorageAt(
227
  address: Address,
228
  storageSlot: Numbers,
229
  blockNumber?: BlockNumberOrTag,
230
  returnFormat?: DataFormat
231
): Promise<string>;
232
```
233

234
### Gas Price Operations
235

236
Retrieve current gas price information and fee history.
237

238
```typescript { .api }
239
/**
240
 * Get current gas price
241
 * @param returnFormat - Return format for the response
242
 * @returns Current gas price in wei
243
 */
244
getGasPrice(returnFormat?: DataFormat): Promise<bigint>;
245

246
/**
247
 * Get fee history for recent blocks
248
 * @param blockCount - Number of blocks to query
249
 * @param newestBlock - Newest block to include
250
 * @param rewardPercentiles - Array of percentile values for priority fees
251
 * @param returnFormat - Return format for the response
252
 * @returns Fee history data
253
 */
254
getFeeHistory(
255
  blockCount: Numbers,
256
  newestBlock: BlockNumberOrTag,
257
  rewardPercentiles?: Numbers[],
258
  returnFormat?: DataFormat
259
): Promise<FeeHistory>;
260
```
261

262
### Network Information
263

264
Retrieve network and chain information.
265

266
```typescript { .api }
267
/**
268
 * Get the chain ID
269
 * @param returnFormat - Return format for the response
270
 * @returns Chain ID
271
 */
272
getChainId(returnFormat?: DataFormat): Promise<bigint>;
273

274
/**
275
 * Get network ID
276
 * @param returnFormat - Return format for the response
277
 * @returns Network ID
278
 */
279
net: {
280
  getId(returnFormat?: DataFormat): Promise<bigint>;
281
  getPeerCount(returnFormat?: DataFormat): Promise<bigint>;
282
  isListening(returnFormat?: DataFormat): Promise<boolean>;
283
};
284
```
285

286
### Subscription Support
287

288
Subscribe to blockchain events and new data.
289

290
```typescript { .api }
291
/**
292
 * Subscribe to blockchain events
293
 * @param subscription - Subscription type and parameters
294
 * @returns Subscription object
295
 */
296
subscribe<T extends keyof RegisteredSubscription>(
297
  subscription: T,
298
  ...args: Parameters<RegisteredSubscription[T]['new']>
299
): Promise<InstanceType<RegisteredSubscription[T]>>;
300

301
// Available subscriptions
302
interface RegisteredSubscription {
303
  newBlockHeaders: Web3Subscription<BlockHeaderOutput>;
304
  pendingTransactions: Web3Subscription<string>;
305
  newPendingTransactions: Web3Subscription<TransactionInfo>;
306
  syncing: Web3Subscription<SyncingStatusAPI>;
307
  logs: Web3Subscription<Log>;
308
}
309
```
310

311
**Usage Examples:**
312

313
```typescript
314
// Subscribe to new block headers
315
const subscription = await web3.eth.subscribe('newBlockHeaders');
316
subscription.on('data', (blockHeader) => {
317
  console.log('New block:', blockHeader.number);
318
});
319

320
// Subscribe to logs
321
const logSubscription = await web3.eth.subscribe('logs', {
322
  address: '0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984',
323
  topics: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef']
324
});
325
```
326

327
## Types
328

329
```typescript { .api }
330
interface Transaction {
331
  to?: Address;
332
  from?: Address;
333
  value?: Numbers;
334
  gas?: Numbers;
335
  gasPrice?: Numbers;
336
  maxFeePerGas?: Numbers;
337
  maxPriorityFeePerGas?: Numbers;
338
  data?: Bytes;
339
  nonce?: Numbers;
340
  type?: Numbers;
341
  accessList?: AccessList;
342
}
343

344
interface TransactionReceipt {
345
  transactionHash: string;
346
  transactionIndex: bigint;
347
  blockNumber: bigint;
348
  blockHash: string;
349
  from: string;
350
  to: string;
351
  gasUsed: bigint;
352
  cumulativeGasUsed: bigint;
353
  logs: Log[];
354
  status: bigint;
355
  contractAddress?: string;
356
}
357

358
interface Block {
359
  number: bigint;
360
  hash: string;
361
  parentHash: string;
362
  timestamp: bigint;
363
  gasLimit: bigint;
364
  gasUsed: bigint;
365
  miner: string;
366
  transactions: string[] | TransactionInfo[];
367
}
368

369
interface Log {
370
  address: string;
371
  topics: string[];
372
  data: string;
373
  blockNumber: bigint;
374
  transactionHash: string;
375
  transactionIndex: bigint;
376
  blockHash: string;
377
  logIndex: bigint;
378
}
379

380
type BlockNumberOrTag = Numbers | 'earliest' | 'latest' | 'pending' | 'safe' | 'finalized';
381
type Address = string;
382
type Bytes = string | Uint8Array;
383
type Numbers = number | bigint | string;
384
```