0
# Data Formatting
1

2
Comprehensive data formatting utilities for converting between JavaScript types and Ethereum node formats. The formatters are divided into input formatters (for preparing data to send to Ethereum nodes) and output formatters (for processing data received from nodes).
3

4
## Capabilities
5

6
### Input Formatters
7

8
Input formatters prepare JavaScript data for transmission to Ethereum nodes, handling hex encoding, address validation, and parameter formatting.
9

10
```javascript { .api }
11
/**
12
 * Formats block number with default fallback to this.defaultBlock
13
 * @param blockNumber - Block number to format or null/undefined for default
14
 * @returns Formatted block number as hex string or predefined string
15
 */
16
function inputDefaultBlockNumberFormatter(blockNumber: string | number): string;
17

18
/**
19
 * Formats block number to hex or predefined string
20
 * @param blockNumber - Block number, predefined string, or 'genesis'
21
 * @returns Hex string for numbers, original string for predefined values
22
 */
23
function inputBlockNumberFormatter(blockNumber: string | number): string | number;
24

25
/**
26
 * Formats transaction call options
27
 * @param options - Transaction call options object
28
 * @returns Formatted options with hex-encoded values and validated addresses
29
 */
30
function inputCallFormatter(options: object): object;
31

32
/**
33
 * Formats transaction options for sending
34
 * @param options - Transaction options object
35
 * @returns Formatted options with required 'from' field validation
36
 */
37
function inputTransactionFormatter(options: object): object;
38

39
/**
40
 * Formats transaction input options (core transaction formatter used internally)
41
 * @param options - Transaction options object
42
 * @returns Formatted options with hex-encoded values and validated addresses
43
 */
44
function txInputFormatter(options: object): object;
45

46
/**
47
 * Formats and validates Ethereum addresses, supporting IBAN format
48
 * @param address - Ethereum address or IBAN address
49
 * @returns Lowercase hex address with 0x prefix
50
 * @throws Error if address is invalid or indirect IBAN
51
 */
52
function inputAddressFormatter(address: string): string;
53

54
/**
55
 * Formats whisper post messages
56
 * @param post - Whisper post object
57
 * @returns Formatted post with hex-encoded numeric values and topics
58
 */
59
function inputPostFormatter(post: object): object;
60

61
/**
62
 * Formats log filter options
63
 * @param options - Log filter options
64
 * @returns Formatted options with hex block numbers and topics
65
 */
66
function inputLogFormatter(options: object): object;
67

68
/**
69
 * Formats data for signing (hex encoding)
70
 * @param data - Data string to format for signing
71
 * @returns Hex-encoded string or original if already hex
72
 */
73
function inputSignFormatter(data: string): string;
74

75
/**
76
 * Formats storage keys array to hex strings
77
 * @param keys - Array of storage keys (numbers, strings, BN, BigNumber)
78
 * @returns Array of hex-encoded storage keys
79
 */
80
function inputStorageKeysFormatter(keys: Array): Array;
81

82
/**
83
 * Formats block number with default fallback to this.defaultBlock
84
 * @param blockNumber - Block number to format or null/undefined for default
85
 * @returns Formatted block number as hex string or predefined string
86
 */
87
function inputDefaultBlockNumberFormatter(blockNumber: string | number): string;
88

89
/**
90
 * Formats whisper post messages
91
 * @param post - Whisper post object
92
 * @returns Formatted post with hex-encoded numeric values and topics
93
 */
94
function inputPostFormatter(post: object): object;
95

96
/**
97
 * Formats log filter options
98
 * @param options - Log filter options
99
 * @returns Formatted options with hex block numbers and topics
100
 */
101
function inputLogFormatter(options: object): object;
102
```
103

104
**Usage Examples:**
105

106
```javascript
107
const { formatters } = require("web3-core-helpers");
108

109
// Address formatting
110
const address = formatters.inputAddressFormatter("0xd46e8dd67c5d32be8058bb8eb970870f07244567");
111
console.log(address); // "0xd46e8dd67c5d32be8058bb8eb970870f07244567"
112

113
// Block number formatting
114
const blockNum = formatters.inputBlockNumberFormatter(15000000);
115
console.log(blockNum); // "0xe4e1c0"
116

117
const latest = formatters.inputBlockNumberFormatter("latest");
118
console.log(latest); // "latest"
119

120
// Transaction formatting
121
const txOptions = formatters.inputTransactionFormatter({
122
  to: "0xd46e8dd67c5d32be8058bb8eb970870f07244567",
123
  value: 1000000000000000000,
124
  gas: 21000,
125
  from: "0x8ba1f109551bD432803012645Hac136c30c6dE3e"
126
});
127
console.log(txOptions.value); // "0xde0b6b3a7640000"
128
console.log(txOptions.gas); // "0x5208"
129

130
// Sign data formatting
131
const signData = formatters.inputSignFormatter("Hello World");
132
console.log(signData); // "0x48656c6c6f20576f726c64"
133
```
134

135
### Output Formatters
136

137
Output formatters process data received from Ethereum nodes, converting hex values to appropriate JavaScript types and formatting addresses.
138

139
```javascript { .api }
140
/**
141
 * Formats big numbers to decimal strings
142
 * @param number - Number in hex or other format
143
 * @returns Decimal string representation
144
 */
145
function outputBigNumberFormatter(number: string | number): string;
146

147
/**
148
 * Formats transaction objects received from nodes
149
 * @param tx - Transaction object from node
150
 * @param hexFormat - Optional flag to preserve hex format for numbers
151
 * @returns Formatted transaction with converted types and checksummed addresses
152
 */
153
function outputTransactionFormatter(tx: object, hexFormat?: boolean): object;
154

155
/**
156
 * Formats transaction receipt objects
157
 * @param receipt - Transaction receipt from node
158
 * @returns Formatted receipt with converted numbers and processed logs
159
 */
160
function outputTransactionReceiptFormatter(receipt: object): object;
161

162
/**
163
 * Formats block objects received from nodes
164
 * @param block - Block object from node
165
 * @param hexFormat - Optional flag to preserve hex format for numbers
166
 * @returns Formatted block with converted numbers and processed transactions
167
 */
168
function outputBlockFormatter(block: object, hexFormat?: boolean): object;
169

170
/**
171
 * Formats log objects with generated log IDs
172
 * @param log - Log object from node
173
 * @returns Formatted log with converted numbers and checksummed address
174
 */
175
function outputLogFormatter(log: object): object;
176

177
/**
178
 * Formats whisper post messages
179
 * @param post - Whisper post object
180
 * @returns Formatted post with converted numbers and UTF8 topics
181
 */
182
function outputPostFormatter(post: object): object;
183

184
/**
185
 * Formats syncing status objects
186
 * @param result - Syncing status from node
187
 * @returns Formatted syncing status with converted numbers
188
 */
189
function outputSyncingFormatter(result: object): object;
190

191
/**
192
 * Formats account proof objects
193
 * @param proof - Account proof from node
194
 * @returns Formatted proof with checksummed address and converted numbers
195
 */
196
function outputProofFormatter(proof: object): object;
197

198
/**
199
 * Formats whisper post messages
200
 * @param post - Whisper post object
201
 * @returns Formatted post with converted numbers and UTF8 topics
202
 */
203
function outputPostFormatter(post: object): object;
204
```
205

206
**Usage Examples:**
207

208
```javascript
209
// Transaction formatting
210
const rawTx = {
211
  blockNumber: "0x5bad55",
212
  value: "0xde0b6b3a7640000",
213
  gasPrice: "0x4a817c800",
214
  from: "0xd46e8dd67c5d32be8058bb8eb970870f07244567",
215
  to: "0x8ba1f109551bd432803012645hac136c30c6de3e"
216
};
217

218
const formattedTx = formatters.outputTransactionFormatter(rawTx);
219
console.log(formattedTx.blockNumber); // 6073685
220
console.log(formattedTx.value); // "1000000000000000000"
221
console.log(formattedTx.from); // "0xd46e8dd67c5d32be8058bb8eb970870f07244567" (checksummed)
222

223
// Block formatting
224
const rawBlock = {
225
  number: "0x5bad55",
226
  gasLimit: "0x1c9c380",
227
  gasUsed: "0x5208",
228
  timestamp: "0x55ba467c"
229
};
230

231
const formattedBlock = formatters.outputBlockFormatter(rawBlock);
232
console.log(formattedBlock.number); // 6073685
233
console.log(formattedBlock.gasLimit); // 30000000
234

235
// Big number formatting
236
const bigNum = formatters.outputBigNumberFormatter("0xde0b6b3a7640000");
237
console.log(bigNum); // "1000000000000000000"
238

239
// Log formatting with ID generation
240
const rawLog = {
241
  blockHash: "0x1234567890abcdef",
242
  transactionHash: "0xfedcba0987654321",
243
  logIndex: "0x0",
244
  address: "0xd46e8dd67c5d32be8058bb8eb970870f07244567"
245
};
246

247
const formattedLog = formatters.outputLogFormatter(rawLog);
248
console.log(formattedLog.id); // "log_a1b2c3d4" (generated ID)
249
console.log(formattedLog.logIndex); // 0
250
```
251

252
## Internal Formatting Functions
253

254
These functions are used internally by the main formatters:
255

256
### Transaction Input Formatter
257

258
```javascript { .api }
259
/**
260
 * Internal function that formats transaction options (used by inputCallFormatter and inputTransactionFormatter)
261
 * @param options - Transaction options object
262
 * @returns Formatted options with hex-encoded values
263
 */
264
function _txInputFormatter(options: object): object;
265
```
266

267
This function handles:
268
- Address formatting for `to` field
269
- Data/input field validation and normalization
270
- Gas and gasLimit field handling
271
- EIP-1559 fee fields (maxPriorityFeePerGas, maxFeePerGas)
272
- Hex encoding of numeric fields
273

274
## Error Handling in Formatters
275

276
Formatters include validation and throw errors for invalid input:
277

278
```javascript
279
// Address validation
280
try {
281
  formatters.inputAddressFormatter("invalid-address");
282
} catch (error) {
283
  console.log(error.message); // "Provided address invalid-address is invalid..."
284
}
285

286
// Transaction data validation
287
try {
288
  formatters.inputTransactionFormatter({
289
    data: "not-hex-data"
290
  });
291
} catch (error) {
292
  console.log(error.message); // "The data field must be HEX encoded data."
293
}
294
```
295

296
## Dependencies
297

298
The formatters module depends on:
299
- **web3-utils**: For hex conversion, address validation, and utility functions
300
- **web3-eth-iban**: For IBAN address format support