This package has ENS functions for interacting with Ethereum Name Service.
npx @tessl/cli install tessl/npm-web3-eth-ens@4.0.0Web3 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.
npm install web3-eth-ensimport { ENS, registryAddresses } from "web3-eth-ens";For CommonJS:
const { ENS, registryAddresses } = require("web3-eth-ens");import { ENS } from "web3-eth-ens";
// Create ENS instance with default mainnet registry
const ens = new ENS(undefined, "https://mainnet.infura.io/v3/your-key");
// Resolve ENS name to address
const address = await ens.getAddress("ethereum.eth");
console.log(address); // "0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359"
// Get ENS record owner
const owner = await ens.getOwner("ethereum.eth");
console.log(owner);
// Check if record exists
const exists = await ens.recordExists("ethereum.eth");
console.log(exists); // true
// Get public key
const pubkey = await ens.getPubkey("ethereum.eth");
console.log(pubkey.x, pubkey.y);Web3 ENS is built around several key components:
Creates an ENS instance for interacting with Ethereum Name Service.
/**
* Create an ENS instance
* @param registryAddr - Optional custom ENS registry address
* @param provider - Web3 provider or provider URL
*/
class ENS {
constructor(
registryAddr?: string,
provider?: SupportedProviders<EthExecutionAPI & Web3NetAPI> | Web3ContextObject<EthExecutionAPI & Web3NetAPI> | string
);
/** The ENS registry address being used */
registryAddress: string;
}Usage Example:
import { ENS } from "web3-eth-ens";
// Use default mainnet registry
const ens = new ENS(undefined, "https://mainnet.infura.io/v3/your-key");
// Use custom registry address
const customEns = new ENS(
"0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e",
"https://goerli.infura.io/v3/your-key"
);Resolves ENS names to cryptocurrency addresses.
/**
* Resolves an ENS name to an Ethereum address
* @param ENSName - The ENS name to resolve
* @param coinType - The coin type (defaults to 60 for ETH)
* @returns The cryptocurrency address
*/
getAddress(ENSName: string, coinType = 60): Promise<Address>;Usage Example:
// Resolve to Ethereum address (default)
const ethAddress = await ens.getAddress("ethereum.eth");
// Resolve to Bitcoin address
const btcAddress = await ens.getAddress("ethereum.eth", 0);Checks if an ENS record exists in the registry.
/**
* Returns true if the record exists
* @param name - The ENS name to check
* @returns True if record exists in registry
*/
recordExists(name: string): Promise<boolean>;Gets the owner address of an ENS name.
/**
* Returns the owner of an ENS name
* @param name - The ENS name
* @returns The address of the owner
*/
getOwner(name: string): Promise<Address>;Gets the time-to-live (caching duration) for an ENS record.
/**
* Returns the caching TTL of an ENS name
* @param name - The ENS name
* @returns The TTL in seconds
*/
getTTL(name: string): Promise<string>;Retrieves the public key associated with an ENS name.
/**
* Returns the X and Y coordinates of the curve point for the public key
* @param ENSName - The ENS name
* @returns Object with x and y coordinates
*/
getPubkey(ENSName: string): Promise<PubkeyResult>;Usage Example:
const pubkey = await ens.getPubkey("ethereum.eth");
console.log(pubkey.x); // X coordinate
console.log(pubkey.y); // Y coordinateGets the content hash (IPFS/Swarm hash) associated with an ENS name.
/**
* Returns the content hash object associated with an ENS node
* @param ENSName - The ENS name
* @returns The content hash (typically IPFS hash)
*/
getContenthash(ENSName: string): Promise<string>;Gets the resolver contract instance for an ENS name.
/**
* Returns the Resolver contract for the given ENS name
* @param name - The ENS name
* @returns Contract instance of the resolver
*/
getResolver(name: string): Promise<Contract<typeof PublicResolverAbi>>;Checks if a resolver supports specific interfaces.
/**
* Returns true if the resolver supports the given signature or interface ID
* @param ENSName - The ENS name
* @param interfaceId - The function signature or interface ID
* @returns True if interface is supported
*/
supportsInterface(ENSName: string, interfaceId: string): Promise<boolean>;Usage Example:
// Check if resolver supports address resolution
const supportsAddr = await ens.supportsInterface("ethereum.eth", "addr(bytes32)");
// Check using interface ID
const supportsAddrById = await ens.supportsInterface("ethereum.eth", "0x3b3b57de");Validates the current network supports ENS and returns the registry address.
/**
* Checks if current network is synced and supports ENS
* @returns The ENS registry address for the detected network
* @throws ENSNetworkNotSyncedError if network is not synced
* @throws ENSUnsupportedNetworkError if network doesn't support ENS
*/
checkNetwork(): Promise<string>;Provides access to ENS registry contract events.
/**
* Returns all events that can be emitted by the ENS registry
*/
get events(): any;Pre-configured ENS registry addresses for supported networks.
interface RegistryAddresses {
main: string; // "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e"
goerli: string; // "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e"
}
const registryAddresses: RegistryAddresses;// Core ENS result types
interface PubkeyResult {
"0": string; // X coordinate
"1": string; // Y coordinate
x: string; // X coordinate
y: string; // Y coordinate
}
// Web3 context types from web3-core
interface Web3ContextObject<T = unknown> {
provider?: SupportedProviders<T>;
config?: Partial<Web3Config>;
}
// Provider types from web3-types
type SupportedProviders<T = unknown> =
| HttpProvider<T>
| WebSocketProvider<T>
| IpcProvider<T>
| string;
// Execution API types from web3-types
interface EthExecutionAPI {
eth_call: (transaction: TransactionCall, blockNumber?: BlockNumberOrTag) => string;
eth_getCode: (address: Address, blockNumber?: BlockNumberOrTag) => string;
// Additional methods...
}
interface Web3NetAPI {
net_version: () => string;
net_peerCount: () => string;
net_listening: () => boolean;
}
// Contract type from web3-eth-contract
interface Contract<T> {
options: {
address?: Address;
from?: Address;
gas?: string;
gasPrice?: string;
};
methods: ContractMethods<T>;
events: ContractEvents<T>;
}
// Address type
type Address = string;
// Block identifier types
type BlockNumberOrTag = string | number | "latest" | "earliest" | "pending";
// Transaction call type
interface TransactionCall {
to?: Address;
from?: Address;
gas?: string;
gasPrice?: string;
data?: string;
value?: string;
}
// Contract method and event types
type ContractMethods<T> = any;
type ContractEvents<T> = any;
// Provider types
interface HttpProvider<T> {
host: string;
timeout?: number;
}
interface WebSocketProvider<T> {
url: string;
timeout?: number;
}
interface IpcProvider<T> {
path: string;
timeout?: number;
}
// Web3 configuration
interface Web3Config {
defaultAccount?: Address;
defaultBlock?: BlockNumberOrTag;
transactionBlockTimeout?: number;
// Additional config options...
}
// ABI types for ENS contracts
const ENSRegistryAbi: readonly any[];
const PublicResolverAbi: readonly any[];The library throws specific error types for different failure scenarios:
Currently supports:
Custom networks can be used by providing a custom registry address to the ENS constructor.