0
# Web3 ENS
1

2
Web3 ENS is a TypeScript library providing comprehensive ENS (Ethereum Name Service) functionality for resolving human-readable domain names to Ethereum addresses and vice versa. It offers read-only ENS operations including domain resolution, reverse lookups, and registry interactions, specifically designed for integration with the web3.js ecosystem.
3

4
## Package Information
5

6
- **Package Name**: web3-eth-ens
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install web3-eth-ens`
10
- **License**: LGPL-3.0
11
- **Node.js**: >=14
12

13
## Core Imports
14

15
```typescript
16
import { ENS, registryAddresses } from "web3-eth-ens";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { ENS, registryAddresses } = require("web3-eth-ens");
23
```
24

25
## Basic Usage
26

27
```typescript
28
import { ENS } from "web3-eth-ens";
29

30
// Create ENS instance with default mainnet registry
31
const ens = new ENS(undefined, "https://mainnet.infura.io/v3/your-key");
32

33
// Resolve ENS name to address
34
const address = await ens.getAddress("ethereum.eth");
35
console.log(address); // "0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359"
36

37
// Get ENS record owner
38
const owner = await ens.getOwner("ethereum.eth");
39
console.log(owner);
40

41
// Check if record exists
42
const exists = await ens.recordExists("ethereum.eth");
43
console.log(exists); // true
44

45
// Get public key
46
const pubkey = await ens.getPubkey("ethereum.eth");
47
console.log(pubkey.x, pubkey.y);
48
```
49

50
## Architecture
51

52
Web3 ENS is built around several key components:
53

54
- **ENS Class**: Main interface providing high-level ENS operations
55
- **Registry**: Direct ENS registry contract interactions for ownership and resolver queries
56
- **Resolver**: ENS resolver contract interactions for address and content resolution
57
- **Network Detection**: Automatic ENS registry detection based on current network
58
- **ABI Definitions**: Complete contract ABIs for ENS Registry and Public Resolver
59

60
## Capabilities
61

62
### ENS Instance Creation
63

64
Creates an ENS instance for interacting with Ethereum Name Service.
65

66
```typescript { .api }
67
/**
68
 * Create an ENS instance
69
 * @param registryAddr - Optional custom ENS registry address
70
 * @param provider - Web3 provider or provider URL
71
 */
72
class ENS {
73
  constructor(
74
    registryAddr?: string,
75
    provider?: SupportedProviders<EthExecutionAPI & Web3NetAPI> | Web3ContextObject<EthExecutionAPI & Web3NetAPI> | string
76
  );
77
  
78
  /** The ENS registry address being used */
79
  registryAddress: string;
80
}
81
```
82

83
**Usage Example:**
84

85
```typescript
86
import { ENS } from "web3-eth-ens";
87

88
// Use default mainnet registry
89
const ens = new ENS(undefined, "https://mainnet.infura.io/v3/your-key");
90

91
// Use custom registry address
92
const customEns = new ENS(
93
  "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e",
94
  "https://goerli.infura.io/v3/your-key"
95
);
96
```
97

98
### Address Resolution
99

100
Resolves ENS names to cryptocurrency addresses.
101

102
```typescript { .api }
103
/**
104
 * Resolves an ENS name to an Ethereum address
105
 * @param ENSName - The ENS name to resolve
106
 * @param coinType - The coin type (defaults to 60 for ETH)
107
 * @returns The cryptocurrency address
108
 */
109
getAddress(ENSName: string, coinType = 60): Promise<Address>;
110
```
111

112
**Usage Example:**
113

114
```typescript
115
// Resolve to Ethereum address (default)
116
const ethAddress = await ens.getAddress("ethereum.eth");
117

118
// Resolve to Bitcoin address  
119
const btcAddress = await ens.getAddress("ethereum.eth", 0);
120
```
121

122
### Record Existence Check
123

124
Checks if an ENS record exists in the registry.
125

126
```typescript { .api }
127
/**
128
 * Returns true if the record exists
129
 * @param name - The ENS name to check
130
 * @returns True if record exists in registry
131
 */
132
recordExists(name: string): Promise<boolean>;
133
```
134

135
### Owner Resolution
136

137
Gets the owner address of an ENS name.
138

139
```typescript { .api }
140
/**
141
 * Returns the owner of an ENS name
142
 * @param name - The ENS name
143
 * @returns The address of the owner
144
 */
145
getOwner(name: string): Promise<Address>;
146
```
147

148
### TTL Retrieval
149

150
Gets the time-to-live (caching duration) for an ENS record.
151

152
```typescript { .api }
153
/**
154
 * Returns the caching TTL of an ENS name
155
 * @param name - The ENS name
156
 * @returns The TTL in seconds
157
 */
158
getTTL(name: string): Promise<string>;
159
```
160

161
### Public Key Resolution
162

163
Retrieves the public key associated with an ENS name.
164

165
```typescript { .api }
166
/**
167
 * Returns the X and Y coordinates of the curve point for the public key
168
 * @param ENSName - The ENS name
169
 * @returns Object with x and y coordinates
170
 */
171
getPubkey(ENSName: string): Promise<PubkeyResult>;
172
```
173

174
**Usage Example:**
175

176
```typescript
177
const pubkey = await ens.getPubkey("ethereum.eth");
178
console.log(pubkey.x); // X coordinate
179
console.log(pubkey.y); // Y coordinate
180
```
181

182
### Content Hash Resolution
183

184
Gets the content hash (IPFS/Swarm hash) associated with an ENS name.
185

186
```typescript { .api }
187
/**
188
 * Returns the content hash object associated with an ENS node
189
 * @param ENSName - The ENS name
190
 * @returns The content hash (typically IPFS hash)
191
 */
192
getContenthash(ENSName: string): Promise<string>;
193
```
194

195
### Resolver Contract Access
196

197
Gets the resolver contract instance for an ENS name.
198

199
```typescript { .api }
200
/**
201
 * Returns the Resolver contract for the given ENS name
202
 * @param name - The ENS name
203
 * @returns Contract instance of the resolver
204
 */
205
getResolver(name: string): Promise<Contract<typeof PublicResolverAbi>>;
206
```
207

208
### Interface Support Check
209

210
Checks if a resolver supports specific interfaces.
211

212
```typescript { .api }
213
/**
214
 * Returns true if the resolver supports the given signature or interface ID
215
 * @param ENSName - The ENS name
216
 * @param interfaceId - The function signature or interface ID
217
 * @returns True if interface is supported
218
 */
219
supportsInterface(ENSName: string, interfaceId: string): Promise<boolean>;
220
```
221

222
**Usage Example:**
223

224
```typescript
225
// Check if resolver supports address resolution
226
const supportsAddr = await ens.supportsInterface("ethereum.eth", "addr(bytes32)");
227

228
// Check using interface ID
229
const supportsAddrById = await ens.supportsInterface("ethereum.eth", "0x3b3b57de");
230
```
231

232
### Network Validation
233

234
Validates the current network supports ENS and returns the registry address.
235

236
```typescript { .api }
237
/**
238
 * Checks if current network is synced and supports ENS
239
 * @returns The ENS registry address for the detected network
240
 * @throws ENSNetworkNotSyncedError if network is not synced
241
 * @throws ENSUnsupportedNetworkError if network doesn't support ENS
242
 */
243
checkNetwork(): Promise<string>;
244
```
245

246
### Event Access
247

248
Provides access to ENS registry contract events.
249

250
```typescript { .api }
251
/**
252
 * Returns all events that can be emitted by the ENS registry
253
 */
254
get events(): any;
255
```
256

257
## Constants
258

259
### Registry Addresses
260

261
Pre-configured ENS registry addresses for supported networks.
262

263
```typescript { .api }
264
interface RegistryAddresses {
265
  main: string;    // "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e"
266
  goerli: string;  // "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e"
267
}
268

269
const registryAddresses: RegistryAddresses;
270
```
271

272

273
## Types
274

275
```typescript { .api }
276
// Core ENS result types
277
interface PubkeyResult {
278
  "0": string; // X coordinate
279
  "1": string; // Y coordinate  
280
  x: string;   // X coordinate
281
  y: string;   // Y coordinate
282
}
283

284
// Web3 context types from web3-core
285
interface Web3ContextObject<T = unknown> {
286
  provider?: SupportedProviders<T>;
287
  config?: Partial<Web3Config>;
288
}
289

290
// Provider types from web3-types
291
type SupportedProviders<T = unknown> = 
292
  | HttpProvider<T>
293
  | WebSocketProvider<T>
294
  | IpcProvider<T>
295
  | string;
296

297
// Execution API types from web3-types
298
interface EthExecutionAPI {
299
  eth_call: (transaction: TransactionCall, blockNumber?: BlockNumberOrTag) => string;
300
  eth_getCode: (address: Address, blockNumber?: BlockNumberOrTag) => string;
301
  // Additional methods...
302
}
303

304
interface Web3NetAPI {
305
  net_version: () => string;
306
  net_peerCount: () => string;
307
  net_listening: () => boolean;
308
}
309

310
// Contract type from web3-eth-contract
311
interface Contract<T> {
312
  options: {
313
    address?: Address;
314
    from?: Address;
315
    gas?: string;
316
    gasPrice?: string;
317
  };
318
  methods: ContractMethods<T>;
319
  events: ContractEvents<T>;
320
}
321

322
// Address type
323
type Address = string;
324

325
// Block identifier types
326
type BlockNumberOrTag = string | number | "latest" | "earliest" | "pending";
327

328
// Transaction call type
329
interface TransactionCall {
330
  to?: Address;
331
  from?: Address;
332
  gas?: string;
333
  gasPrice?: string;
334
  data?: string;
335
  value?: string;
336
}
337

338
// Contract method and event types
339
type ContractMethods<T> = any;
340
type ContractEvents<T> = any;
341

342
// Provider types
343
interface HttpProvider<T> {
344
  host: string;
345
  timeout?: number;
346
}
347

348
interface WebSocketProvider<T> {
349
  url: string;
350
  timeout?: number;
351
}
352

353
interface IpcProvider<T> {
354
  path: string;
355
  timeout?: number;
356
}
357

358
// Web3 configuration
359
interface Web3Config {
360
  defaultAccount?: Address;
361
  defaultBlock?: BlockNumberOrTag;
362
  transactionBlockTimeout?: number;
363
  // Additional config options...
364
}
365

366
// ABI types for ENS contracts
367
const ENSRegistryAbi: readonly any[];
368
const PublicResolverAbi: readonly any[];
369
```
370

371
## Error Handling
372

373
The library throws specific error types for different failure scenarios:
374

375
- **ENSNetworkNotSyncedError**: Thrown when the network is not synchronized
376
- **ENSUnsupportedNetworkError**: Thrown when the current network doesn't support ENS
377
- **ResolverMethodMissingError**: Thrown when a resolver doesn't support a requested method
378

379
## Network Support
380

381
Currently supports:
382
- **Mainnet** (chain ID: 0x1)
383
- **Goerli** (chain ID: 0x5) 
384

385
Custom networks can be used by providing a custom registry address to the ENS constructor.
386

387
## Limitations
388

389
- **Read-only operations**: No modification methods available (by design)
390
- **Limited network support**: Only mainnet and Goerli supported out of the box
391
- **No built-in caching**: Resolver contracts are fetched on each operation
392
- **Network dependency**: Requires active network connection to function