0
# Web3 Eth
1

2
Web3 Eth is a comprehensive TypeScript/JavaScript library that provides complete functionality for interacting with the Ethereum blockchain and smart contracts. It offers essential blockchain operations including account management, transaction handling, block retrieval, contract interaction, gas management, and real-time event monitoring through subscriptions.
3

4
## Package Information
5

6
- **Package Name**: web3-eth
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install web3-eth`
10

11
## Core Imports
12

13
```typescript
14
import { Web3Eth } from "web3-eth";
15
```
16

17
For standalone functions:
18

19
```typescript
20
import { 
21
  getBalance, 
22
  sendTransaction, 
23
  getBlock, 
24
  estimateGas,
25
  waitForTransactionReceipt 
26
} from "web3-eth";
27
```
28

29
For CommonJS:
30

31
```javascript
32
const { Web3Eth } = require("web3-eth");
33
```
34

35
## Basic Usage
36

37
```typescript
38
import { Web3Eth } from "web3-eth";
39

40
// Initialize with provider
41
const eth = new Web3Eth("https://mainnet.infura.io/v3/YOUR_PROJECT_ID");
42

43
// Get account balance
44
const balance = await eth.getBalance("0x742d35Cc6634C0532925a3b8D7389Fc3C1b6c5E");
45

46
// Get latest block
47
const block = await eth.getBlock("latest");
48

49
// Send transaction
50
const receipt = await eth.sendTransaction({
51
  from: "0x742d35Cc6634C0532925a3b8D7389Fc3C1b6c5E",
52
  to: "0x8ba1f109551bD432803012645Hac136c1c1b6c5E",
53
  value: "1000000000000000000" // 1 ETH in wei
54
});
55

56
// Subscribe to new blocks
57
const subscription = await eth.subscribe("newHeads");
58
subscription.on("data", (blockHeader) => {
59
  console.log("New block:", blockHeader.number);
60
});
61
```
62

63
## Architecture
64

65
Web3 Eth is built around several key components:
66

67
- **Web3Eth Class**: Main class providing all Ethereum blockchain interaction methods
68
- **RPC Method Wrappers**: Standalone functions that wrap Ethereum JSON-RPC calls
69
- **Subscription System**: Real-time event monitoring for logs, blocks, and transactions
70
- **Transaction Utilities**: Helper functions for transaction building, formatting, and processing
71
- **Type System**: Complete TypeScript integration with configurable data formatting
72
- **Validation Layer**: Input validation and transaction verification functions
73

74
## Capabilities
75

76
### Blockchain State Access
77

78
Complete read access to blockchain data including blocks, transactions, accounts, and network information.
79

80
```typescript { .api }
81
class Web3Eth {
82
  getBlock(blockHashOrBlockNumber?: BlockNumberOrTag, hydrated?: boolean, returnFormat?: DataFormat): Promise<Block>;
83
  getTransaction(transactionHash?: HexString32Bytes, returnFormat?: DataFormat): Promise<Transaction>;
84
  getBalance(address: Address, blockNumber?: BlockNumberOrTag, returnFormat?: DataFormat): Promise<Numbers>;
85
  getBlockNumber(returnFormat?: DataFormat): Promise<Numbers>;
86
}
87
```
88

89
[Blockchain State Access](./blockchain-state.md)
90

91
### Transaction Management
92

93
Complete transaction lifecycle management from creation to confirmation, including signing and gas estimation.
94

95
```typescript { .api }
96
class Web3Eth {
97
  sendTransaction(transaction?: Transaction, returnFormat?: DataFormat, options?: SendTransactionOptions): Promise<TransactionReceipt>;
98
  sendSignedTransaction(transaction: Bytes, returnFormat?: DataFormat, options?: SendSignedTransactionOptions): Promise<TransactionReceipt>;
99
  estimateGas(transaction?: TransactionCall, blockNumber?: BlockNumberOrTag, returnFormat?: DataFormat): Promise<Numbers>;
100
  getTransactionReceipt(transactionHash?: HexString32Bytes, returnFormat?: DataFormat): Promise<TransactionReceipt>;
101
}
102
```
103

104
[Transaction Management](./transaction-management.md)
105

106
### Account Operations
107

108
Account balance queries, nonce management, storage inspection, and cryptographic proof generation.
109

110
```typescript { .api }
111
class Web3Eth {
112
  getBalance(address: Address, blockNumber?: BlockNumberOrTag, returnFormat?: DataFormat): Promise<Numbers>;
113
  getTransactionCount(address: Address, blockNumber?: BlockNumberOrTag, returnFormat?: DataFormat): Promise<Numbers>;
114
  getCode(address: Address, blockNumber?: BlockNumberOrTag, returnFormat?: DataFormat): Promise<Bytes>;
115
  getStorageAt(address: Address, storageSlot: Numbers, blockNumber?: BlockNumberOrTag, returnFormat?: DataFormat): Promise<Bytes>;
116
  getProof(address: Address, storageKeys?: HexString32Bytes[], blockNumber?: BlockNumberOrTag, returnFormat?: DataFormat): Promise<AccountObject>;
117
}
118
```
119

120
[Account Operations](./account-operations.md)
121

122
### Smart Contract Interaction
123

124
Execute contract calls, estimate gas consumption, and interact with contract state.
125

126
```typescript { .api }
127
class Web3Eth {
128
  call(transaction?: TransactionCall, blockNumber?: BlockNumberOrTag, returnFormat?: DataFormat): Promise<Bytes>;
129
  estimateGas(transaction?: TransactionCall, blockNumber?: BlockNumberOrTag, returnFormat?: DataFormat): Promise<Numbers>;
130
  createAccessList(transaction?: TransactionForAccessList, blockNumber?: BlockNumberOrTag, returnFormat?: DataFormat): Promise<AccessListResult>;
131
}
132
```
133

134
[Smart Contract Interaction](./smart-contract-interaction.md)
135

136
### Event Monitoring & Subscriptions
137

138
Real-time blockchain event monitoring through subscription mechanisms for logs, blocks, and transactions.
139

140
```typescript { .api }
141
class Web3Eth {
142
  subscribe(subscriptionName: 'logs' | 'newHeads' | 'newPendingTransactions' | 'syncing', subscriptionOptions?: LogsInput | object): Promise<RegisteredSubscription>;
143
  getPastLogs(filter?: Filter, returnFormat?: DataFormat): Promise<LogsOutput>;
144
  clearSubscriptions(): Promise<boolean>;
145
}
146
```
147

148
[Event Monitoring & Subscriptions](./event-monitoring.md)
149

150
### Gas & Fee Management
151

152
Comprehensive gas price discovery, fee market support, and EIP-1559 transaction fee calculation.
153

154
```typescript { .api }
155
class Web3Eth {
156
  getGasPrice(returnFormat?: DataFormat): Promise<Numbers>;
157
  getMaxPriorityFeePerGas(returnFormat?: DataFormat): Promise<Numbers>;
158
  getFeeData(returnFormat?: DataFormat): Promise<FeeData>;
159
  getFeeHistory(blockCount: Numbers, lastBlock: BlockNumberOrTag, rewardPercentiles?: Numbers[], returnFormat?: DataFormat): Promise<FeeHistoryOutput>;
160
  calculateFeeData(baseFeePerGas?: Numbers, alternativeMaxPriorityFeePerGas?: Numbers): Promise<FeeData>;
161
}
162
```
163

164
[Gas & Fee Management](./gas-fee-management.md)
165

166
### Cryptographic Operations
167

168
Message and transaction signing with support for EIP-712 typed data and various signature formats.
169

170
```typescript { .api }
171
class Web3Eth {
172
  sign(message: Bytes, addressOrIndex: Address | Numbers, returnFormat?: DataFormat): Promise<SignatureObject>;
173
  signTransaction(transaction: Transaction, returnFormat?: DataFormat): Promise<SignedTransactionInfoAPI>;
174
  signTypedData(address: Address, typedData: Eip712TypedData, useLegacy?: boolean, returnFormat?: DataFormat): Promise<SignatureObject>;
175
}
176
```
177

178
[Cryptographic Operations](./cryptographic-operations.md)
179

180
### Network Information
181

182
Access to network and node information including protocol version, chain ID, and synchronization status.
183

184
```typescript { .api }
185
class Web3Eth {
186
  getProtocolVersion(): Promise<string>;
187
  getChainId(): Promise<Numbers>;
188
  isSyncing(): Promise<SyncingStatusAPI | boolean>;
189
  getCoinbase(): Promise<Address>;
190
  isMining(): Promise<boolean>;
191
  getNodeInfo(): Promise<string>;
192
}
193
```
194

195
[Network Information](./network-information.md)
196

197
### Transaction Utilities
198

199
Helper functions for transaction building, formatting, validation, and processing workflows.
200

201
```typescript { .api }
202
function detectTransactionType(transaction: Transaction): TransactionType;
203
function transactionBuilder(options: TransactionBuilderOptions): Transaction;
204
function waitForTransactionReceipt(web3Context: Web3Context, transactionHash: HexString32Bytes, returnFormat?: DataFormat, options?: TransactionReceiptOptions): Promise<TransactionReceipt>;
205
function formatTransaction(transaction: Transaction, returnFormat: DataFormat): FormattedTransaction;
206
function prepareTransactionForSigning(transaction: Transaction, web3Context: Web3Context, privateKey?: HexString, fillGasPrice?: boolean): Promise<Transaction>;
207
```
208

209
[Transaction Utilities](./transaction-utilities.md)
210

211
## Core Types
212

213
```typescript { .api }
214
interface Web3EthExecutionAPI {
215
  eth_getBalance: (address: Address, blockNumber: BlockNumberOrTag) => Numbers;
216
  eth_getCode: (address: Address, blockNumber: BlockNumberOrTag) => Bytes;
217
  eth_getStorageAt: (address: Address, storageSlot: Numbers, blockNumber: BlockNumberOrTag) => Bytes;
218
  eth_getTransactionCount: (address: Address, blockNumber: BlockNumberOrTag) => Numbers;
219
  eth_sendTransaction: (transaction: Transaction) => HexString32Bytes;  
220
  eth_sendRawTransaction: (transaction: Bytes) => HexString32Bytes;
221
  eth_call: (transaction: TransactionCall, blockNumber: BlockNumberOrTag) => Bytes;
222
  eth_estimateGas: (transaction: TransactionCall, blockNumber?: BlockNumberOrTag) => Numbers;
223
  eth_getBlockByHash: (blockHash: HexString32Bytes, hydrated: boolean) => Block | null;
224
  eth_getBlockByNumber: (blockNumber: BlockNumberOrTag, hydrated: boolean) => Block | null;
225
  eth_getTransactionByHash: (transactionHash: HexString32Bytes) => Transaction | null;
226
  eth_getTransactionReceipt: (transactionHash: HexString32Bytes) => TransactionReceipt | null;
227
}
228

229
interface RegisteredSubscription {
230
  logs: typeof LogsSubscription;
231
  newPendingTransactions: typeof NewPendingTransactionsSubscription;
232
  pendingTransactions: typeof NewPendingTransactionsSubscription;
233
  newHeads: typeof NewHeadsSubscription;
234
  newBlockHeaders: typeof NewHeadsSubscription;
235
  syncing: typeof SyncingSubscription;
236
}
237

238
interface SendTransactionOptions<ResolveType = TransactionReceipt> {
239
  ignoreGasPricing?: boolean;
240
  transactionConfirmationBlocks?: Numbers;
241
  transactionBlockTimeout?: Numbers;
242
  transactionConfirmationPollingInterval?: Numbers;
243
  transactionReceiptPollingInterval?: Numbers;
244
  transactionSendTimeout?: Numbers;
245
  ignoreFillingGasLimit?: boolean;
246
  contractAbi?: AbilityType;
247
}
248

249
interface TransactionMiddleware {
250
  processTransaction(transaction: Transaction, options?: SendTransactionOptions): Promise<Transaction>;
251
}
252
```