0
# Configuration Management
1

2
The Web3 configuration management system provides centralized settings control with event-driven updates and comprehensive blockchain-specific configuration options. It serves as the foundation for all Web3 instance behavior and transaction parameters.
3

4
## Capabilities
5

6
### Web3Config Class
7

8
Abstract base class providing configuration management with event emission for configuration changes.
9

10
```typescript { .api }
11
/**
12
 * Abstract base configuration class with event emission for setting changes
13
 */
14
abstract class Web3Config extends Web3EventEmitter<{
15
  CONFIG_CHANGE: {
16
    name: string;
17
    oldValue: unknown;
18
    newValue: unknown;
19
  };
20
}> {
21
  constructor(options?: Partial<Web3ConfigOptions>);
22
  
23
  /**
24
   * Update multiple configuration options at once
25
   * @param options - Partial configuration options to update
26
   */
27
  setConfig(options: Partial<Web3ConfigOptions>): void;
28
  
29
  // Configuration properties (getters/setters)
30
  handleRevert: boolean;
31
  defaultAccount?: HexString;
32
  defaultBlock: BlockNumberOrTag;
33
  transactionSendTimeout: number;
34
  transactionBlockTimeout: number;
35
  transactionConfirmationBlocks: number;
36
  transactionPollingInterval: number;
37
  transactionPollingTimeout: number;
38
  transactionReceiptPollingInterval?: number;
39
  transactionConfirmationPollingInterval?: number;
40
  blockHeaderTimeout: number;
41
  maxListenersWarningThreshold: number;
42
  contractDataInputFill: 'data' | 'input' | 'both';
43
  defaultNetworkId?: Numbers;
44
  defaultChain: string;
45
  defaultHardfork: string;
46
  ignoreGasPricing: boolean;
47
  defaultCommon?: Common;
48
  defaultTransactionType: Numbers;
49
  defaultMaxPriorityFeePerGas: Numbers;
50
  enableExperimentalFeatures: {
51
    useSubscriptionWhenCheckingBlockTimeout: boolean;
52
    useRpcCallSpecification: boolean;
53
    [key: string]: boolean;
54
  };
55
  transactionBuilder?: TransactionBuilder;
56
  transactionTypeParser?: TransactionTypeParser;
57
  customTransactionSchema?: CustomTransactionSchema;
58
  defaultReturnFormat: DataFormat;
59
}
60
```
61

62
**Usage Examples:**
63

64
```typescript
65
import { Web3Config } from "web3-core";
66

67
// Extend Web3Config for custom implementation
68
class MyWeb3Config extends Web3Config {
69
  constructor(options?: Partial<Web3ConfigOptions>) {
70
    super(options);
71
    
72
    // Listen to configuration changes
73
    this.on("CONFIG_CHANGE", ({ name, oldValue, newValue }) => {
74
      console.log(`Config ${name} changed from ${oldValue} to ${newValue}`);
75
    });
76
  }
77
}
78

79
// Create configuration instance
80
const config = new MyWeb3Config({
81
  defaultBlock: "latest",
82
  transactionSendTimeout: 60000,
83
  transactionConfirmationBlocks: 24,
84
  handleRevert: true
85
});
86

87
// Update individual properties
88
config.defaultAccount = "0x742d35Cc6634C0532925a3b8D0d3";
89
config.transactionSendTimeout = 120000;
90

91
// Update multiple properties at once
92
config.setConfig({
93
  defaultBlock: "pending",
94
  transactionPollingInterval: 4000,
95
  maxListenersWarningThreshold: 100
96
});
97
```
98

99
### Configuration Options Interface
100

101
Comprehensive configuration interface defining all available Web3 settings.
102

103
```typescript { .api }
104
/**
105
 * Complete configuration options for Web3 instances
106
 */
107
interface Web3ConfigOptions {
108
  /**
109
   * Handle revert reasons in failed transactions
110
   * @default false
111
   */
112
  handleRevert: boolean;
113
  
114
  /**
115
   * Default account address for transactions
116
   * @default undefined
117
   */
118
  defaultAccount?: HexString;
119
  
120
  /**
121
   * Default block parameter for calls ("latest", "earliest", "pending", or block number)
122
   * @default "latest"
123
   */
124
  defaultBlock: BlockNumberOrTag;
125
  
126
  /**
127
   * Timeout for sending transactions in milliseconds
128
   * @default 750000
129
   */
130
  transactionSendTimeout: number;
131
  
132
  /**
133
   * Timeout for waiting for blocks in milliseconds
134
   * @default 50000
135
   */
136
  transactionBlockTimeout: number;
137
  
138
  /**
139
   * Number of confirmation blocks required for transactions
140
   * @default 24
141
   */
142
  transactionConfirmationBlocks: number;
143
  
144
  /**
145
   * Polling interval for transaction receipts in milliseconds
146
   * @default 1000
147
   */
148
  transactionPollingInterval: number;
149
  
150
  /**
151
   * Timeout for polling transaction receipts in milliseconds
152
   * @default 750000
153
   */
154
  transactionPollingTimeout: number;
155
  
156
  /**
157
   * Optional custom polling interval for transaction receipts in milliseconds
158
   * @default undefined
159
   */
160
  transactionReceiptPollingInterval?: number;
161
  
162
  /**
163
   * Optional custom polling interval for transaction confirmations in milliseconds
164
   * @default undefined
165
   */
166
  transactionConfirmationPollingInterval?: number;
167
  
168
  /**
169
   * Timeout for block header subscriptions in milliseconds
170
   * @default 10000
171
   */
172
  blockHeaderTimeout: number;
173
  
174
  /**
175
   * Warning threshold for maximum event listeners
176
   * @default 100
177
   */
178
  maxListenersWarningThreshold: number;
179
  
180
  /**
181
   * Contract data input field preference
182
   * @default "data"
183
   */
184
  contractDataInputFill: 'data' | 'input' | 'both';
185
  
186
  /**
187
   * Default network ID for transactions
188
   * @default undefined
189
   */
190
  defaultNetworkId?: Numbers;
191
  
192
  /**
193
   * Default blockchain network
194
   * @default "mainnet"
195
   */
196
  defaultChain: string;
197
  
198
  /**
199
   * Default hardfork version
200
   * @default "london"
201
   */
202
  defaultHardfork: string;
203
  
204
  /**
205
   * Skip automatic gas pricing
206
   * @default false
207
   */
208
  ignoreGasPricing: boolean;
209
  
210
  /**
211
   * Default common configuration for transactions
212
   * @default undefined 
213
   */
214
  defaultCommon?: Common;
215
  
216
  /**
217
   * Default transaction type (0: legacy, 1: EIP-2930, 2: EIP-1559)
218
   * @default 2
219
   */
220
  defaultTransactionType: Numbers;
221
  
222
  /**
223
   * Default maximum priority fee per gas for EIP-1559 transactions
224
   * @default 2500000000
225
   */
226
  defaultMaxPriorityFeePerGas: Numbers;
227
  
228
  /**
229
   * Experimental feature flags
230
   * @default { useSubscriptionWhenCheckingBlockTimeout: false, useRpcCallSpecification: false }
231
   */
232
  enableExperimentalFeatures: {
233
    /** Use subscription for block timeout checking */
234
    useSubscriptionWhenCheckingBlockTimeout: boolean;
235
    /** Use RPC call specification (EIP-1474) */
236
    useRpcCallSpecification: boolean;
237
    /** Other experimental features */
238
    [key: string]: boolean;
239
  };
240
  
241
  /**
242
   * Custom transaction builder function
243
   * @default undefined
244
   */
245
  transactionBuilder?: TransactionBuilder;
246
  
247
  /**
248
   * Custom transaction type parser function
249
   * @default undefined
250
   */
251
  transactionTypeParser?: TransactionTypeParser;
252
  
253
  /**
254
   * Custom transaction schema for validation
255
   * @default undefined
256
   */
257
  customTransactionSchema?: CustomTransactionSchema;
258
  
259
  /**
260
   * Default data format for return values
261
   * @default DataFormat.JSON
262
   */
263
  defaultReturnFormat: DataFormat;
264
}
265
```
266

267
**Usage Examples:**
268

269
```typescript
270
// Complete configuration example
271
const fullConfig: Web3ConfigOptions = {
272
  handleRevert: true,
273
  defaultAccount: "0x742d35Cc6634C0532925a3b8D0d3",
274
  defaultBlock: "latest",
275
  transactionSendTimeout: 60000,
276
  transactionBlockTimeout: 50000,
277
  transactionConfirmationBlocks: 24,
278
  transactionPollingInterval: 1000,
279
  transactionPollingTimeout: 750000,
280
  blockHeaderTimeout: 10000,
281
  maxListenersWarningThreshold: 100,
282
  contractDataInputFill: "data",
283
  defaultNetworkId: 1,
284
  defaultChain: "mainnet",
285
  defaultHardfork: "london",
286
  ignoreGasPricing: false,
287
  defaultTransactionType: 2,
288
  defaultMaxPriorityFeePerGas: 2500000000,
289
  enableExperimentalFeatures: {
290
    useNativeKeccak: true,
291
    useRpcCallSpecification: false
292
  },
293
  defaultReturnFormat: DataFormat.JSON
294
};
295
```
296

297
### Configuration Events
298

299
Event system for tracking configuration changes across the application.
300

301
```typescript { .api }
302
/**
303
 * Configuration change events
304
 */
305
enum Web3ConfigEvent {
306
  CONFIG_CHANGE = 'CONFIG_CHANGE'
307
}
308

309
/**
310
 * Configuration change event payload
311
 */
312
interface ConfigChangeEvent {
313
  name: string;
314
  oldValue: unknown;
315
  newValue: unknown;
316
}
317
```
318

319
**Usage Examples:**
320

321
```typescript
322
// Listen to all configuration changes
323
config.on("CONFIG_CHANGE", ({ name, oldValue, newValue }) => {
324
  console.log(`Configuration '${name}' changed:`);
325
  console.log(`  Old value: ${JSON.stringify(oldValue)}`);
326
  console.log(`  New value: ${JSON.stringify(newValue)}`);
327
  
328
  // React to specific configuration changes
329
  switch (name) {
330
    case "defaultAccount":
331
      console.log("Default account updated, refreshing UI...");
332
      break;
333
    case "defaultBlock":
334
      console.log("Default block changed, clearing cache...");
335
      break;
336
    case "transactionSendTimeout":
337
      console.log("Transaction timeout updated");
338
      break;
339
  }
340
});
341

342
// Configuration changes trigger events
343
config.defaultBlock = "pending"; 
344
// Logs: Configuration 'defaultBlock' changed: Old value: "latest", New value: "pending"
345

346
config.setConfig({ 
347
  transactionSendTimeout: 90000,
348
  transactionConfirmationBlocks: 12
349
});
350
// Logs events for both changed properties
351
```
352

353
### Transaction Configuration
354

355
Specialized configuration options for transaction behavior and gas management.
356

357
```typescript { .api }
358
/**
359
 * Transaction builder function type
360
 */
361
type TransactionBuilder<ReturnType = Transaction> = (options: {
362
  transaction: TransactionWithFromLocalWalletIndex;
363
  web3Context: Web3Context;
364
  privateKey?: HexString;
365
  fillGasPrice?: boolean;
366
  fillGasLimit?: boolean;
367
}) => Promise<ReturnType>;
368

369
/**
370
 * Transaction type parser function type
371
 */
372
type TransactionTypeParser = (transaction: Transaction) => HexString | undefined;
373

374
/**
375
 * Custom transaction schema definition
376
 */
377
type CustomTransactionSchema = {
378
  type: string;
379
  properties: Record<string, Schema>;
380
};
381
```
382

383
**Usage Examples:**
384

385
```typescript
386
// Custom transaction builder
387
const customBuilder: TransactionBuilder = async (options) => {
388
  const { transaction, web3Context, fillGasPrice, fillGasLimit } = options;
389
  
390
  // Custom transaction building logic
391
  const builtTransaction = { ...transaction };
392
  
393
  if (fillGasPrice && !builtTransaction.gasPrice) {
394
    const gasPrice = await web3Context.requestManager.send({
395
      method: "eth_gasPrice",
396
      params: []
397
    });
398
    builtTransaction.gasPrice = gasPrice;
399
  }
400
  
401
  if (fillGasLimit && !builtTransaction.gas) {
402
    const gasLimit = await web3Context.requestManager.send({
403
      method: "eth_estimateGas", 
404
      params: [transaction]
405
    });
406
    builtTransaction.gas = gasLimit;
407
  }
408
  
409
  return builtTransaction;
410
};
411

412
// Custom transaction type parser
413
const typeParser: TransactionTypeParser = (transaction) => {
414
  if (transaction.maxFeePerGas || transaction.maxPriorityFeePerGas) {
415
    return "0x2"; // EIP-1559
416
  } else if (transaction.accessList) {
417
    return "0x1"; // EIP-2930
418
  } else {
419
    return "0x0"; // Legacy
420
  }
421
};
422

423
// Apply custom configuration
424
config.setConfig({
425
  transactionBuilder: customBuilder,
426
  transactionTypeParser: typeParser,
427
  defaultTransactionType: 2,
428
  ignoreGasPricing: false
429
});
430
```
431

432
### Network and Chain Configuration
433

434
Configuration options for blockchain network and consensus parameters.
435

436
```typescript { .api }
437
/**
438
 * Common configuration object for blockchain parameters
439
 */
440
interface Common {
441
  customChain: {
442
    name?: string;
443
    networkId: number;
444
    chainId: number;
445
  };
446
  baseChain?: 'mainnet' | 'goerli' | 'sepolia' | 'holesky' | string;
447
  hardfork?: string;
448
}
449
```
450

451
**Usage Examples:**
452

453
```typescript
454
// Configure for custom network
455
const customNetworkConfig: Partial<Web3ConfigOptions> = {
456
  defaultChain: "polygon",
457
  defaultNetworkId: 137,
458
  defaultHardfork: "london",
459
  defaultCommon: {
460
    customChain: {
461
      name: "Polygon Mainnet",
462
      networkId: 137,
463
      chainId: 137
464
    },
465
    baseChain: "mainnet",
466
    hardfork: "london"
467
  }
468
};
469

470
// Configure for testnet
471
const testnetConfig: Partial<Web3ConfigOptions> = {
472
  defaultChain: "goerli",
473
  defaultNetworkId: 5,
474
  defaultCommon: {
475
    customChain: {
476
      name: "Goerli Testnet", 
477
      networkId: 5,
478
      chainId: 5
479
    },
480
    baseChain: "goerli",
481
    hardfork: "london"
482
  },
483
  transactionConfirmationBlocks: 3 // Faster confirmations on testnet
484
};
485

486
config.setConfig(customNetworkConfig);
487
```
488

489
### Data Format Configuration
490

491
Configuration for controlling data format of return values throughout the library.
492

493
```typescript { .api }
494
/**
495
 * Data format enumeration for return values
496
 */
497
enum DataFormat {
498
  JSON = "JSON",
499
  HEX = "HEX"
500
}
501
```
502

503
**Usage Examples:**
504

505
```typescript
506
// Configure return format
507
config.defaultReturnFormat = DataFormat.HEX;
508

509
// This affects all return values from methods
510
// Numbers will be returned as hex strings instead of numbers
511
// Addresses and hashes remain hex strings
512
// Booleans and strings are unaffected
513
```