Custom indexers
Build an indexer from your own data source with defineIndexer, or combine bigname and Goldsky, so lists, search and history work on your data.
An indexer is a service that has already collected ENS data into a searchable form, so
ens.indexer.getSubnames or getNamesForAddress can answer in one request. ensforge ships
bigname() and goldsky(). defineIndexer lets you serve the same actions from your own API,
database or test data.
Prerequisites
- Know what an indexer is and how to connect one. See Connect an indexer and Name lists and indexers.
- A data source you can query from TypeScript.
When to write one
Use defineIndexer when your data source does not speak bigname's REST API. If it does, such as a
self-hosted bigname or a proxy, pass its URL to bigname({ url }) instead.
1. Define the adapter
An adapter is an id and the queries it answers, as Promise functions. Implement only the queries
you serve. The others fail with INDEXER_UNSUPPORTED, which
lets fallback ask the next indexer.
Example (An Adapter for an In-House Subnames API)
import { defineIndexer } from "@ensforge/sdk/indexer";
import { namehash } from "viem";
declare const api: {
subnames(
name: string,
cursor: string | undefined,
options: { signal: AbortSignal | undefined },
): Promise<{ names: string[]; next: string | null }>;
};
export const inHouse = defineIndexer({
id: "in-house",
getSubnames: async ({ name, cursor }, { signal }) => {
const page = await api.subnames(name, cursor, { signal });
return {
items: page.names.map((subname) => ({
name: subname,
displayName: subname,
namespace: "ens",
node: namehash(subname),
status: null,
authority: null,
owner: null,
manager: null,
registeredAt: null,
createdAt: null,
expiresAt: null,
graceEndsAt: null,
expiryReason: null,
ensV1: null,
labelhash: null,
subnameCount: null,
subregistry: null,
})),
cursor: page.next,
hasMore: page.next !== null,
totalCount: null,
};
},
});What the adapter gets and returns:
- The first argument is the query. Actions validate it first: names are normalised, addresses checksummed and the namespace resolved.
- The second argument has
chainId(the client's chain) andsignal, aborted when the call is cancelled. Passsignalto your fetches. - A page needs
items,cursor(the value to pass back for the next page, ornull),hasMoreandtotalCount. - Every answer also has metadata (
asOf,snapshots,completeness,originand more). Leave it out and ensforge fills it: no snapshot,completeness: "full", andindexerset to yourid. Setcompletenessyourself when the answer is partial.
The adapter can answer any of these queries: getName, getNamesForAddress, getSubnames,
getHistory, getEvents, search, lookup, getNamesByExpiry, getPrimaryName, getRecords,
getPermissions, getRegistry, getRegistryLabels, getResolver, getResolverLinks,
getResolverRoles, getResolvers, getNamespace and getStatus.
2. Report failures with the right error
Throw an ensforge IndexerError to control how a failure is reported. Anything else you throw
becomes INDEXER_UNAVAILABLE. Return null from
getName, getRecords, getRegistry, getResolver and getNamespace when nothing exists. Other
queries must return an object, or the call fails with
INDEXER_RESPONSE_INVALID.
Example (Reporting a Rate Limit)
import { Errors } from "@ensforge/sdk";
import { defineIndexer } from "@ensforge/sdk/indexer";
declare const fetchProfile: (name: string) => Promise<Response>;
export const guarded = defineIndexer({
id: "guarded",
getName: async () => {
const response = await fetchProfile("nick.eth");
if (response.status === 429) {
throw new Errors.IndexerError({ code: "INDEXER_RATE_LIMITED", status: 429 });
}
return null;
},
});INDEXER_RATE_LIMITED, INDEXER_UNAVAILABLE and INDEXER_BEHIND are retryable and make
fallback move on.
3. Use it
Pass the indexer to the client. Combine it with others using fallback: each query goes to the first
indexer that can answer it.
Example (Yours First, bigname After)
import { Ensforge, ensActions } from "@ensforge/sdk";
import { bigname, fallback, indexerActions, type Indexer } from "@ensforge/sdk/indexer";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
declare const inHouse: Indexer;
const publicClient = createPublicClient({ chain: mainnet, transport: http() });
export const ens = Ensforge.create({
publicClient,
indexer: fallback([inHouse, bigname()]),
})
.extend(ensActions())
.extend(indexerActions());fallback asks the next indexer when one is unavailable, rate limiting, behind, or does not serve
the query. Not found is an answer and is not retried. Cursors are tagged with the indexer that
issued them, so the next page goes back to the same one.
Walk every page
paginate follows cursor until the last page. break stops requesting pages.
Example (Walking Every Page of a Custom Indexer)
import { Ensforge, indexerActions } from "@ensforge/sdk";
import { paginate, type Indexer } from "@ensforge/sdk/indexer";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
declare const inHouse: Indexer;
const publicClient = createPublicClient({ chain: mainnet, transport: http() });
const ens = Ensforge.create({ publicClient, indexer: inHouse }).extend(indexerActions());
for await (const page of paginate(ens.indexer.getSubnames, { name: "ens.eth" })) {
console.log(page.items.length);
}Use one as a test double
A small adapter makes tests independent of a live service. See Test your integration.
Example (An Indexer That Finds Nothing)
import { defineIndexer } from "@ensforge/sdk/indexer";
export const empty = defineIndexer({ id: "test", getName: async () => null });Effect adapters
Indexer.define in @ensforge/sdk/effect takes Effect functions instead of Promises, and fails with
ensforge errors in the error channel. Indexer.paginate returns a Stream. See
The Effect API.
Limits
ensforge checks that an answer is an object, and that a page has an items array. It trusts the
types of the fields to your TypeScript types. Built-in adapters check every response against the
indexer's schema. Two indexers can also disagree on semantics, so apps that compare answers should
stick to one.
Check the result
Call an action you implemented and read indexer on the answer. It should be your adapter's id.
Troubleshooting
INDEXER_NOT_CONFIGURED
The client has no indexer. Pass it to Ensforge.create. See
INDEXER_NOT_CONFIGURED.
INDEXER_UNSUPPORTED
The adapter does not implement that query, or does not serve the namespace. Add the method, or put
another indexer after it in fallback. See
INDEXER_UNSUPPORTED.
INDEXER_RESPONSE_INVALID
The adapter answered null for a query that cannot be null, or a page without items. See
INDEXER_RESPONSE_INVALID.
Was this page helpful?