0
# Web3 Core Helpers
1

2
Web3 Core Helpers is an internal utility package that provides standardized error handling and data formatting capabilities for the Web3.js ecosystem. It contains essential error creators and formatters that ensure consistent behavior across all Web3.js sub-packages when interacting with Ethereum nodes.
3

4
## Package Information
5

6
- **Package Name**: web3-core-helpers
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install web3-core-helpers`
10

11
## Core Imports
12

13
```javascript
14
const { errors, formatters } = require("web3-core-helpers");
15
```
16

17
ES6/TypeScript:
18
```typescript
19
import { errors, formatters } from "web3-core-helpers";
20
```
21

22
## Basic Usage
23

24
```javascript
25
const { errors, formatters } = require("web3-core-helpers");
26

27
// Create standardized errors
28
const connectionError = errors.InvalidConnection("wss://localhost:8546");
29
const paramError = errors.InvalidNumberOfParams(2, 3, "eth_getBalance");
30

31
// Format data for Ethereum nodes
32
const formattedAddress = formatters.inputAddressFormatter("0xd46e8dd67c5d32be8058bb8eb970870f07244567");
33
const formattedBlockNumber = formatters.inputBlockNumberFormatter("latest");
34

35
// Format data from Ethereum nodes
36
const formattedTransaction = formatters.outputTransactionFormatter({
37
  blockNumber: "0x5bad55",
38
  value: "0xde0b6b3a7640000"
39
});
40
```
41

42
## Architecture
43

44
Web3 Core Helpers is organized around two main functional areas:
45

46
- **Error Handling**: Standardized error creation with consistent messaging and metadata across Web3.js
47
- **Data Formatting**: Bidirectional formatters for converting between JavaScript types and Ethereum node formats
48
- **Provider Base Classes**: TypeScript base classes for different provider types (WebSocket, HTTP, IPC)
49

50
## Capabilities
51

52
### Error Handling
53

54
Complete error handling system providing standardized error creation for connection issues, validation failures, transaction problems, and contract interactions.
55

56
```javascript { .api }
57
// Connection & Provider Errors
58
function ErrorResponse(result: Error): Error;
59
function InvalidConnection(host: string, event?: WebSocketEvent): ConnectionError;
60
function InvalidProvider(): Error;
61
function ConnectionTimeout(ms: string): Error;
62

63
// Transaction Errors  
64
function TransactionError(message: string, receipt: object): TransactionError;
65
function RevertInstructionError(reason: string, signature: string): RevertInstructionError;
66
function TransactionOutOfGasError(receipt: object): TransactionError;
67

68
// Contract Errors
69
function ContractMissingABIError(): Error;
70
function ContractNoAddressDefinedError(): Error;
71
```
72

73
[Error Handling](./errors.md)
74

75
### Data Formatting
76

77
Comprehensive data formatting utilities for converting between JavaScript types and Ethereum node formats, with separate input and output formatters for different data types.
78

79
```javascript { .api }
80
// Input Formatters (JS -> Ethereum node format)
81
function inputAddressFormatter(address: string): string;
82
function inputBlockNumberFormatter(blockNumber: string | number): string | number;
83
function inputTransactionFormatter(options: object): object;
84
function txInputFormatter(options: object): object;
85
function inputSignFormatter(data: string): string;
86

87
// Output Formatters (Ethereum node -> JS format)  
88
function outputBigNumberFormatter(number: string | number): string;
89
function outputTransactionFormatter(tx: object, hexFormat?: boolean): object;
90
function outputBlockFormatter(block: object, hexFormat?: boolean): object;
91
function outputLogFormatter(log: object): object;
92

93
// Utility Functions
94
function isPredefinedBlockNumber(blockNumber: string): boolean;
95
```
96

97
[Data Formatting](./formatters.md)
98

99
## Types
100

101
```typescript { .api }
102
interface ConnectionError extends Error {
103
  code: string | undefined;
104
  reason: string | undefined;
105
}
106

107
interface TransactionError extends Error {
108
  receipt: object;
109
}
110

111
interface RevertInstructionError extends Error {
112
  reason: string;
113
  signature: string;
114
}
115

116
interface WebSocketEvent {
117
  code?: number;
118
  reason?: string;
119
}
120

121
interface JsonRpcPayload {
122
  jsonrpc: string;
123
  method: string;
124
  params?: any[];
125
  id?: string | number;
126
}
127

128
interface JsonRpcResponse {
129
  jsonrpc: string;
130
  id: string | number;
131
  result?: any;
132
  error?: {
133
    readonly code?: number;
134
    readonly data?: unknown;
135
    readonly message: string;
136
  };
137
}
138
```