ensnode-sdk

ENSNode SDK

This package is a set of libraries enabling smooth interaction with ENSNode services and data, including shared types, data processing (such as validating data and enforcing invariants), and ENS-oriented helper functions.

Learn more about ENSNode from the ENSNode docs.

Installation

npm install @ensnode/ensnode-sdk

EnsNodeClient

The EnsNodeClient provides a unified interface for the ENSNode REST APIs:

• Resolution API (Protocol Accelerated Forward/Reverse Resolution)
• Indexing Status API

Basic Usage

import { EnsNodeClient, evmChainIdToCoinType } from "@ensnode/ensnode-sdk";
import { mainnet } from "viem/chains";

const client = new EnsNodeClient();

// Resolution API: Records Resolution
const { records } = await client.resolveRecords("jesse.base.eth", {
  addresses: [evmChainIdToCoinType(mainnet.id)],
  texts: ["avatar", "com.twitter"],
});

// Resolution API: Primary Name Resolution
const { name } = await client.resolvePrimaryName("0x179A862703a4adfb29896552DF9e307980D19285", mainnet.id);
// name === 'gregskril.eth'

// Resolution API: Primary Names Resolution
const { names } = await client.resolvePrimaryNames("0x179A862703a4adfb29896552DF9e307980D19285");
// names === { '1': 'gregskril.eth', "8453": "greg.base.eth", ... }

API Methods

Resolution API

resolveRecords(name, selection, options)

Resolves records for an ENS name (Forward Resolution), via ENSNode, which implements Protocol Acceleration for indexed names.

The returned name field, if set, is guaranteed to be a Normalized Name. If the name record returned by the resolver is not normalized, null is returned as if no name record was set.

• name: The ENS Name whose records to resolve
• selection: Optional selection of Resolver records:
  • addresses: Array of coin types to resolve addresses for
  • texts: Array of text record keys to resolve
• options: (optional) additional options
  • trace: (optional) Whether to include a trace in the response (default: false)
  • accelerate: (optional) Whether to attempt Protocol Acceleration (default: false)

import { mainnet, base } from 'viem/chains';

const { records } = await client.resolveRecords("greg.base.eth", {
  // Resolve ETH Mainnet Address (if set) and Base Address (if set)
  addresses: [evmChainIdToCoinType(mainnet.id), evmChainIdToCoinType(base.id)],
  // or pass the CoinTypes directly if you know them
  // addresses: [60, 2147492101],
  texts: ["avatar", "com.twitter"],
});

console.log(records);
// {
//   "addresses": {
//     "60": "0x179A862703a4adfb29896552DF9e307980D19285",
//     "2147492101": "0x179A862703a4adfb29896552DF9e307980D19285"
//   },
//   "texts": {
//     "avatar": "https://...",
//     "com.twitter": "gregskril"
//   }
// }

resolvePrimaryName(address, chainId, options)

Resolves the primary name of the provided address on the specified chainId, via ENSNode, which implements Protocol Acceleration for indexed names. If the chainId-specific Primary Name is not defined, but the address specifies a valid ENSIP-19 Default Name, the Default Name will be returned. You may query the Default EVM Chain Id (0) in order to determine the address's Default Name directly.

The returned Primary Name, if set, is guaranteed to be a Normalized Name. If the primary name set for the address is not normalized, null is returned as if no primary name was set.

• address: The Address whose Primary Name to resolve
• chainId: The chain id within which to query the address' ENSIP-19 Multichain Primary Name
• options: (optional) additional options
  • trace: (optional) Whether to include a trace in the response (default: false)
  • accelerate: (optional) Whether to attempt Protocol Acceleration (default: false)

import { mainnet, base } from 'viem/chains';
import { DEFAULT_EVM_CHAIN_ID } from '@ensnode/ensnode-sdk';

// Resolve the address' Primary Name on Ethereum Mainnet
const { name } = await client.resolvePrimaryName("0x179A862703a4adfb29896552DF9e307980D19285", mainnet.id);
// name === 'gregskril.eth'

// Resolve the address' Primary Name on Base
const { name } = await client.resolvePrimaryName("0x179A862703a4adfb29896552DF9e307980D19285", base.id);
// name === 'greg.base.eth'

// Resolve the address' Default Primary Name
const { name } = await client.resolvePrimaryName("0x179A862703a4adfb29896552DF9e307980D19285", DEFAULT_EVM_CHAIN_ID);
// name === 'gregskril.eth'

resolvePrimaryNames(address, options)

Resolves the primary names of the provided address on the specified chainIds, via ENSNode, which implements Protocol Acceleration for indexed names. For each Primary Name, if the chainId-specific Primary Name is not defined, but the address specifies a valid ENSIP-19 Default Name, the Default Name will be returned. You may not query the Default EVM Chain Id (0) directly, and should rely on the aforementioned per-chain defaulting behavior.

Each returned Primary Name, if set, is guaranteed to be a Normalized Name. If the primary name set for the address on any chain is not normalized, null is returned for that chain as if no primary name was set.

• address: The Address whose Primary Names to resolve
• options: (optional) additional options
  • chainIds: The chain ids within which to query the address' ENSIP-19 Multichain Primary Name (default: all ENSIP-19 supported chains)
  • trace: (optional) Whether to include a trace in the response (default: false)
  • accelerate: (optional) Whether to attempt Protocol Acceleration (default: false)

import { mainnet, base } from 'viem/chains';

// Resolve an address' Primary Names on all ENSIP-19 supported chain ids
const { names } = await client.resolvePrimaryNames("0x179A862703a4adfb29896552DF9e307980D19285");

console.log(names);
// {
//   "1": "gregskril.eth", // Default Primary Name
//   "10": "gregskril.eth", // Default Primary Name
//   "8453": "greg.base.eth", // Base-specific Primary Name!
//   "42161": "gregskril.eth", // Default Primary Name
//   "59144": "gregskril.eth", // Default Primary Name
//   "534352": "gregskril.eth" // Default Primary Name
// }

// Resolve an address' Primary Names on specific chain Ids
const { names } = await client.resolvePrimaryNames("0x179A862703a4adfb29896552DF9e307980D19285", {
  chainIds: [mainnet.id, base.id],
});

console.log(names);
// {
//   "1": "gregskril.eth",
//   "8453": "greg.base.eth", // base-specific Primary Name!
// }

Indexing Status API

indexingStatus()

Fetches the ENSNode's omnichain indexing status.

• Returns: IndexingStatusResponse - The indexing status data for all indexed chains
• Throws: Error if the request fails or the ENSNode API returns an error response

// Get current indexing status
const indexingStatusResponse = await client.indexingStatus();

if (indexingStatusResponse.responseCode === EnsApiIndexingStatusResponseCodes.Ok) {
  const { realtimeProjection, stackInfo } = indexingStatusResponse;
  console.log("RealtimeIndexingStatusProjection:", realtimeProjection);
  console.log("EnsNodeStackInfo:", stackInfo);
} else {
  console.error("Error while fetching Indexing Status");
}

Configuration

const client = new EnsNodeClient({
  url: new URL("https://my-ensnode-instance.com"),
});