# Custom indexers

> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).

Build an indexer from your own data source with defineIndexer, or combine bigname and Goldsky, so lists, search and history work on your data.

Source: https://ensforge.com/docs/sdk/custom-indexers

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 [#prerequisites]

- Know what an indexer is and how to connect one. See
  [Connect an indexer](/docs/sdk/connect-an-indexer) and
  [Name lists and indexers](/docs/sdk/name-lists-and-indexers).
- A data source you can query from TypeScript.

## When to write one [#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 [#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`](/docs/reference/errors/INDEXER_UNSUPPORTED), which
lets `fallback` ask the next indexer.

**Example** (An Adapter for an In-House Subnames API)

```ts title="in-house.ts"
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) and `signal`, aborted when the call is
  cancelled. Pass `signal` to your fetches.
- A page needs `items`, `cursor` (the value to pass back for the next page, or `null`),
  `hasMore` and `totalCount`.
- Every answer also has metadata (`asOf`, `snapshots`, `completeness`, `origin` and more). Leave it
  out and ensforge fills it: no snapshot, `completeness: "full"`, and `indexer` set to your `id`.
  Set `completeness` yourself 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 [#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`](/docs/reference/errors/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`](/docs/reference/errors/INDEXER_RESPONSE_INVALID).

**Example** (Reporting a Rate Limit)

```ts title="errors.ts"
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 [#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)

```ts title="client.ts"
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 [#walk-every-page]

`paginate` follows `cursor` until the last page. `break` stops requesting pages.

**Example** (Walking Every Page of a Custom Indexer)

```ts title="paginate.ts"
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 [#use-one-as-a-test-double]

A small adapter makes tests independent of a live service. See
[Test your integration](/docs/sdk/testing).

**Example** (An Indexer That Finds Nothing)

```ts title="double.ts"
import { defineIndexer } from "@ensforge/sdk/indexer";

export const empty = defineIndexer({ id: "test", getName: async () => null });
```

## Effect adapters [#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](/docs/sdk/effect-api).

## Limits [#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 [#check-the-result]

Call an action you implemented and read `indexer` on the answer. It should be your adapter's `id`.

## Troubleshooting [#troubleshooting]

### `INDEXER_NOT_CONFIGURED` [#indexer_not_configured]

The client has no `indexer`. Pass it to `Ensforge.create`. See
[`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED).

### `INDEXER_UNSUPPORTED` [#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`](/docs/reference/errors/INDEXER_UNSUPPORTED).

### `INDEXER_RESPONSE_INVALID` [#indexer_response_invalid]

The adapter answered `null` for a query that cannot be `null`, or a page without `items`. See
[`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID).