0
# Transaction Management
1

2
The transaction management functionality provides complete transaction lifecycle support from creation and signing to broadcasting and confirmation monitoring.
3

4
## Transaction Sending
5

6
### sendTransaction
7

8
Sends a transaction to the network. Handles gas estimation, nonce management, and signing automatically.
9

10
```typescript { .api }
11
sendTransaction(transaction?: Transaction, returnFormat?: DataFormat, options?: SendTransactionOptions): Promise<TransactionReceipt>;
12
```
13

14
**Parameters:**
15
- `transaction`: Transaction object with from, to, value, data, etc.
16
- `returnFormat`: Output format configuration
17
- `options`: Additional sending options (confirmations, timeouts, etc.)
18

19
**Usage Example:**
20
```typescript
21
// Basic transaction
22
const receipt = await eth.sendTransaction({
23
  from: "0x742d35Cc6634C0532925a3b8D7389Fc3C1b6c5E",
24
  to: "0x8ba1f109551bD432803012645Hac136c1c1b6c5E", 
25
  value: "1000000000000000000", // 1 ETH in wei
26
  gas: "21000"
27
});
28

29
// Contract interaction
30
const contractReceipt = await eth.sendTransaction({
31
  from: "0x742d35Cc6634C0532925a3b8D7389Fc3C1b6c5E",
32
  to: "0x1234567890123456789012345678901234567890", // contract address
33
  data: "0xa9059cbb000000000000000000000000...", // encoded function call
34
  gas: "100000"
35
});
36

37
// With advanced options
38
const receipt = await eth.sendTransaction({
39
  from: "0x742d35Cc6634C0532925a3b8D7389Fc3C1b6c5E",
40
  to: "0x8ba1f109551bD432803012645Hac136c1c1b6c5E",
41
  value: "500000000000000000",
42
  maxFeePerGas: "20000000000", // EIP-1559
43
  maxPriorityFeePerGas: "2000000000"
44
}, DEFAULT_RETURN_FORMAT, {
45
  transactionConfirmationBlocks: 3,
46
  transactionBlockTimeout: 100
47
});
48
```
49

50
### sendSignedTransaction
51

52
Broadcasts a pre-signed transaction to the network.
53

54
```typescript { .api }
55
sendSignedTransaction(transaction: Bytes, returnFormat?: DataFormat, options?: SendSignedTransactionOptions): Promise<TransactionReceipt>;
56
```
57

58
**Usage Example:**
59
```typescript
60
// Send a pre-signed transaction
61
const signedTx = "0xf86c808504a817c800825208942bcda7e0...";
62
const receipt = await eth.sendSignedTransaction(signedTx);
63
```
64

65
## Transaction Estimation and Validation
66

67
### estimateGas
68

69
Estimates the gas required for a transaction or contract call.
70

71
```typescript { .api }
72
estimateGas(transaction?: TransactionCall, blockNumber?: BlockNumberOrTag, returnFormat?: DataFormat): Promise<Numbers>;
73
```
74

75
**Usage Example:**
76
```typescript
77
const gasEstimate = await eth.estimateGas({
78
  from: "0x742d35Cc6634C0532925a3b8D7389Fc3C1b6c5E",
79
  to: "0x1234567890123456789012345678901234567890",
80
  data: "0xa9059cbb000000000000000000000000..."
81
});
82
console.log(`Estimated gas: ${gasEstimate}`);
83
```
84

85
### createAccessList
86

87
Creates an access list for EIP-2930 transactions to reduce gas costs.
88

89
```typescript { .api }
90
createAccessList(transaction?: TransactionForAccessList, blockNumber?: BlockNumberOrTag, returnFormat?: DataFormat): Promise<AccessListResult>;
91
```
92

93
**Usage Example:**
94
```typescript
95
const accessListResult = await eth.createAccessList({
96
  from: "0x742d35Cc6634C0532925a3b8D7389Fc3C1b6c5E",
97
  to: "0x1234567890123456789012345678901234567890",
98
  data: "0xa9059cbb000000000000000000000000..."
99
});
100

101
// Use the access list in the transaction
102
const receipt = await eth.sendTransaction({
103
  from: "0x742d35Cc6634C0532925a3b8D7389Fc3C1b6c5E",
104
  to: "0x1234567890123456789012345678901234567890",
105
  data: "0xa9059cbb000000000000000000000000...",
106
  accessList: accessListResult.accessList,
107
  type: 1 // EIP-2930 transaction
108
});
109
```
110

111
## Transaction Utilities
112

113
### waitForTransactionReceipt
114

115
Waits for a transaction to be mined and returns its receipt.
116

117
```typescript { .api }
118
function waitForTransactionReceipt(
119
  web3Context: Web3Context, 
120
  transactionHash: HexString32Bytes, 
121
  returnFormat?: DataFormat, 
122
  options?: TransactionReceiptOptions
123
): Promise<TransactionReceipt>;
124
```
125

126
**Usage Example:**
127
```typescript
128
import { waitForTransactionReceipt } from "web3-eth";
129

130
// Send transaction and get hash
131
const txHash = "0xabcdef1234567890...";
132

133
// Wait for confirmation
134
const receipt = await waitForTransactionReceipt(eth, txHash, DEFAULT_RETURN_FORMAT, {
135
  transactionConfirmationBlocks: 3,
136
  transactionBlockTimeout: 100
137
});
138

139
if (receipt.status === '0x1') {
140
  console.log("Transaction confirmed successfully");
141
}
142
```
143

144
### trySendTransaction  
145

146
Sends a transaction with automatic retry logic and error handling.
147

148
```typescript { .api }
149
function trySendTransaction(
150
  web3Context: Web3Context,
151
  transaction: Transaction,
152
  returnFormat?: DataFormat,
153
  options?: SendTransactionOptions
154
): Promise<TransactionReceipt>;
155
```
156

157
## Transaction Events
158

159
Both `sendTransaction` and `sendSignedTransaction` emit events during processing:
160

161
```typescript { .api }
162
interface SendTransactionEvents<ReturnFormat = DataFormat> {
163
  sending: Transaction;
164
  sent: Transaction;
165
  transactionHash: HexString32Bytes;
166
  receipt: TransactionReceipt;
167
  confirmation: { confirmations: Numbers; receipt: TransactionReceipt; latestBlockHash: HexString32Bytes };
168
  error: Error;
169
}
170
```
171

172
**Usage Example:**
173
```typescript
174
const promiEvent = eth.sendTransaction({
175
  from: "0x742d35Cc6634C0532925a3b8D7389Fc3C1b6c5E",
176
  to: "0x8ba1f109551bD432803012645Hac136c1c1b6c5E",
177
  value: "1000000000000000000"
178
});
179

180
promiEvent.on("sending", (tx) => {
181
  console.log("Sending transaction...", tx);
182
});
183

184
promiEvent.on("transactionHash", (hash) => {
185
  console.log("Transaction hash:", hash);
186
});
187

188
promiEvent.on("confirmation", (confirmation) => {
189
  console.log(`Confirmation ${confirmation.confirmations}`);
190
});
191

192
promiEvent.on("error", (error) => {
193
  console.error("Transaction error:", error);
194
});
195

196
const receipt = await promiEvent;
197
```
198

199
## Transaction Middleware
200

201
Set custom middleware to process transactions before sending.
202

203
```typescript { .api }
204
interface TransactionMiddleware {
205
  processTransaction(transaction: Transaction, options?: SendTransactionOptions): Promise<Transaction>;
206
}
207

208
setTransactionMiddleware(transactionMiddleware: TransactionMiddleware): void;
209
getTransactionMiddleware(): TransactionMiddleware | undefined;
210
```
211

212
**Usage Example:**
213
```typescript
214
// Custom middleware to add gas buffer
215
const gasBufferMiddleware = {
216
  async processTransaction(tx, options) {
217
    if (!tx.gas) {
218
      const estimated = await eth.estimateGas(tx);
219
      tx.gas = Math.floor(Number(estimated) * 1.2); // 20% buffer
220
    }
221
    return tx;
222
  }
223
};
224

225
eth.setTransactionMiddleware(gasBufferMiddleware);
226
```
227

228
## Core Types
229

230
```typescript { .api }
231
interface Transaction {
232
  from: Address;
233
  to?: Address;
234
  value?: Numbers;
235
  gas?: Numbers;
236
  gasPrice?: Numbers;
237
  maxFeePerGas?: Numbers;
238
  maxPriorityFeePerGas?: Numbers;
239
  data?: Bytes;
240
  nonce?: Numbers;
241
  type?: Numbers;
242
  accessList?: AccessList;
243
  chainId?: Numbers;
244
}
245

246
interface TransactionCall {
247
  from?: Address;
248
  to: Address;
249
  gas?: Numbers;
250
  gasPrice?: Numbers;
251
  maxFeePerGas?: Numbers;
252
  maxPriorityFeePerGas?: Numbers;
253
  value?: Numbers;
254
  data?: Bytes;
255
  type?: Numbers;
256
  accessList?: AccessList;
257
}
258

259
interface TransactionForAccessList {
260
  from?: Address;
261
  to?: Address;
262
  gas?: Numbers;
263
  gasPrice?: Numbers;
264
  maxFeePerGas?: Numbers;
265
  maxPriorityFeePerGas?: Numbers;
266
  value?: Numbers;
267
  data?: Bytes;
268
}
269

270
interface SendTransactionOptions<ResolveType = TransactionReceipt> {
271
  ignoreGasPricing?: boolean;
272
  transactionConfirmationBlocks?: Numbers;
273
  transactionBlockTimeout?: Numbers;
274
  transactionConfirmationPollingInterval?: Numbers;
275
  transactionReceiptPollingInterval?: Numbers;
276
  transactionSendTimeout?: Numbers;
277
  ignoreFillingGasLimit?: boolean;
278
  contractAbi?: AbilityType;
279
}
280

281
interface SendSignedTransactionOptions<ResolveType = TransactionReceipt> {
282
  transactionConfirmationBlocks?: Numbers;
283
  transactionBlockTimeout?: Numbers;
284
  transactionConfirmationPollingInterval?: Numbers;
285
  transactionReceiptPollingInterval?: Numbers;
286
  transactionSendTimeout?: Numbers;
287
}
288

289
interface AccessList {
290
  address: Address;
291
  storageKeys: HexString32Bytes[];
292
}
293

294
interface AccessListResult {
295
  accessList: AccessList[];
296
  gasUsed: HexString;
297
}
298

299
interface TransactionReceiptOptions {
300
  transactionConfirmationBlocks?: Numbers;
301
  transactionBlockTimeout?: Numbers;
302
  transactionReceiptPollingInterval?: Numbers;
303
}
304
```