CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-web3-eth-ens

This package has ENS functions for interacting with Ethereum Name Service.

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Web3 ENS

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.

Package Information

  • Package Name: web3-eth-ens
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install web3-eth-ens
  • License: LGPL-3.0
  • Node.js: >=14

Core Imports

import { ENS, registryAddresses } from "web3-eth-ens";

For CommonJS:

const { ENS, registryAddresses } = require("web3-eth-ens");

Basic Usage

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);

Architecture

Web3 ENS is built around several key components:

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

Capabilities

ENS Instance Creation

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"
);

Address Resolution

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);

Record Existence Check

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>;

Owner Resolution

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>;

TTL Retrieval

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>;

Public Key Resolution

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 coordinate

Content Hash Resolution

Gets 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>;

Resolver Contract Access

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>>;

Interface Support Check

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");

Network Validation

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>;

Event Access

Provides access to ENS registry contract events.

/**
 * Returns all events that can be emitted by the ENS registry
 */
get events(): any;

Constants

Registry Addresses

Pre-configured ENS registry addresses for supported networks.

interface RegistryAddresses {
  main: string;    // "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e"
  goerli: string;  // "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e"
}

const registryAddresses: RegistryAddresses;

Types

// 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[];

Error Handling

The library throws specific error types for different failure scenarios:

  • ENSNetworkNotSyncedError: Thrown when the network is not synchronized
  • ENSUnsupportedNetworkError: Thrown when the current network doesn't support ENS
  • ResolverMethodMissingError: Thrown when a resolver doesn't support a requested method

Network Support

Currently supports:

  • Mainnet (chain ID: 0x1)
  • Goerli (chain ID: 0x5)

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

Limitations

  • Read-only operations: No modification methods available (by design)
  • Limited network support: Only mainnet and Goerli supported out of the box
  • No built-in caching: Resolver contracts are fetched on each operation
  • Network dependency: Requires active network connection to function
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/web3-eth-ens@4.0.x
Publish Source
CLI
Badge
tessl/npm-web3-eth-ens badge