Documentation for agents: an index at /llms.txt, every docs page in one file at /llms-full.txt, and Markdown for any docs page by adding .md to its URL.

Skip to Content
ensforgeSDK

Connect an indexer

Add an indexer to your ensforge client so you can list names, search them and read history, and learn how to read its freshness metadata.

By the end of this guide your client can answer questions the chain cannot answer on its own, such as "which names does this address own?", by asking an indexer: a service that reads every ENS event as it happens and keeps the results in a searchable database.

Prerequisites

  • A viem public client for Ethereum mainnet or Sepolia. See Create a client.

1. Add an indexer to the client

Pass an indexer to Ensforge.create, then add the indexerActions() group. bigname() is the built-in indexer for ENS on mainnet and Sepolia.

Example (Creating a Client with bigname)

indexer-client.ts
import { ensActions, Ensforge } from "@ensforge/sdk";
import { bigname, indexerActions } from "@ensforge/sdk/indexer";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
  indexer: bigname(),
})
  .extend(ensActions())
  .extend(indexerActions());

const page = await ens.indexer.search({ query: "vitalik" });
  • indexer: bigname() tells the client where to send list queries. The client's chain picks the host: https://api.bigname.sh for mainnet and https://sepolia.api.bigname.sh for Sepolia.
  • indexerActions() adds the ens.indexer.* actions. ensActions() does not include them, because they need an indexer.
  • On-chain actions such as record.getAddress do not use the indexer.

See Name lists and indexers and bigname.

2. Check the connection

indexer.getStatus reads the indexer's health and how far each chain is indexed.

Example (Reading the Indexer Status)

indexer-status.ts
import { ensActions, Ensforge } from "@ensforge/sdk";
import { bigname, indexerActions } from "@ensforge/sdk/indexer";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
  indexer: bigname(),
})
  .extend(ensActions())
  .extend(indexerActions());

const status = await ens.indexer.getStatus();

console.log(status.status, status.indexer);
for (const [chainId, chain] of Object.entries(status.chains)) {
  console.log(chainId, chain.status, chain.lagBlocks);
}

status is "ready", "degraded" or "stale". Each chain reports the block it has indexed, the latest block, and lagBlocks and lagSeconds. See indexer.getStatus.

3. Read answers with care

Every indexer answer carries metadata besides its data:

FieldDescription
asOfThe chain snapshot (block and time) the answer was read at.
completeness"full", "partial" or "unsupported". A partial answer is never presented as complete.
unsupportedReasonWhy the answer is partial or unsupported.
origin"indexed" when answered from the index, "verified" when read on-chain.
indexerThe id of the indexer that answered, such as bigname.

An indexer is fast but can lag the chain by a few blocks. For an authoritative answer about one name, read the chain with name.get.

Use Basenames and Goldsky

goldsky() serves ENS and Basenames (*.base.eth) on mainnet. It reads only the latest state. It has fewer fields than bigname: no verified records, and subnames without expiry. Missing fields are null.

Example (Reading a Basename)

goldsky-client.ts
import { ensActions, Ensforge } from "@ensforge/sdk";
import { goldsky, indexerActions } from "@ensforge/sdk/indexer";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
  indexer: goldsky(),
})
  .extend(ensActions())
  .extend(indexerActions());

const name = await ens.indexer.getName({ name: "jesse.base.eth" });

Use more than one indexer

fallback asks indexers in order. Each query goes to the first one that can answer it. The next one is asked when an indexer is unavailable, rate limiting, behind, or does not serve the query or namespace. A name that is not found is an answer, so it is not retried.

Example (bigname First, Goldsky After)

fallback-client.ts
import { ensActions, Ensforge } from "@ensforge/sdk";
import { bigname, fallback, goldsky, indexerActions } from "@ensforge/sdk/indexer";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const ens = Ensforge.create({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
  indexer: fallback([bigname(), goldsky()]),
})
  .extend(ensActions())
  .extend(indexerActions());
  • Every answer reports which indexer gave it, in indexer.
  • A cursor or snapshot token goes back to the indexer that issued it, so paging never switches indexer halfway.
  • fallback([...], { on: ["unavailable", "rateLimited"] }) limits when the next indexer is asked. The reasons are "unavailable", "rateLimited", "unsupported" and "behind".

Point at your own server

Both built-in indexers take the same connection options, for a self-hosted server, a proxy or an API key.

Example (A Self-Hosted bigname with a Header)

self-hosted.ts
import { bigname } from "@ensforge/sdk/indexer";

const authorization = "Bearer <token>";

const indexer = bigname({
  url: "https://bigname.internal",
  headers: { authorization },
  timeout: 10_000,
  retryCount: 1,
  cache: true,
});
OptionTypeDefaultDescription
urlstringthe public host for the client's chainBase URL of a server with the same API. A /v1 path is added unless the URL ends with one.
headersRecord<string, string>noneExtra request headers, such as an API key.
fetchtypeof fetchglobalThis.fetchThe fetch to send requests with.
timeoutnumber15000Milliseconds per request before it is retried or fails.
retryCountnumber2Retries of rate-limited, unavailable and timed-out requests. Retry-After is honoured.
cachebooleanfalsebigname only. Revalidates repeated reads with ETags.

To adapt another data source, see Custom indexers.

Troubleshooting

INDEXER_NOT_CONFIGURED

The client has no indexer. Pass indexer to Ensforge.create. See INDEXER_NOT_CONFIGURED.

Property 'indexer' does not exist in TypeScript

You did not add indexerActions() with .extend(...). ensActions() does not include the indexer actions.

INDEXER_UNSUPPORTED

The indexer does not serve the query or its namespace. Examples: the client's chain has no public host (pass url), the namespace is not indexed (bigname does not serve Basenames at the time of writing), or Goldsky was asked for a snapshot (at) or a safe or finalized read. Combine indexers with fallback. See INDEXER_UNSUPPORTED.

INDEXER_UNAVAILABLE or INDEXER_RATE_LIMITED

The indexer is down or limiting you. Both are marked retryable. ensforge already retries retryCount times, so add a second indexer with fallback. See INDEXER_UNAVAILABLE and INDEXER_RATE_LIMITED.

INDEXER_BEHIND

The indexer is behind the chain. Retry shortly, or read on-chain instead. See INDEXER_BEHIND.

Was this page helpful?