or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-web3-eth-ens

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/web3-eth-ens@4.0.x

To install, run

npx @tessl/cli install tessl/npm-web3-eth-ens@4.0.0

index.mddocs/

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