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

Indexers

Look up the indexers, query options and result types of @ensforge/sdk/indexer, the adapters that serve search, history and name listings.

Exports of @ensforge/sdk/indexer. See Connect an indexer.

Indexers

bigname

The bigname indexer (api.bigname.sh), the indexer the ENS app uses.

function bigname(options: RestIndexerOptions & { /** Revalidate repeated reads with ETags. @default false */ cache?: boolean | undefined; } = {}): Indexer

Use for ENS names on mainnet and Sepolia: ENSv1 and ENSv2 state, records, subnames, history, permissions, and verified (on-chain) records and primary names.

  • Public hosts: https://api.bigname.sh (mainnet) and https://sepolia.api.bigname.sh (Sepolia); other chains need url.
  • Answers can be pinned to a snapshot (at) and read at safe or finalized finality.
  • What it serves is read from its /status and /namespaces routes on first use: a client on another chain, or a namespace it does not index yet (Basenames, at the time of writing), fails with INDEXER_UNSUPPORTED, so fallback moves on.
  • cache: true revalidates repeated reads with ETags.
Mainnet or Sepolia
import { Ensforge } from "@ensforge/sdk"
import { bigname, indexerActions } from "@ensforge/sdk/indexer"

const ens = Ensforge.create({ publicClient, indexer: bigname() }).extend(indexerActions())
A self-hosted bigname
import { bigname } from "@ensforge/sdk/indexer"

const indexer = bigname({ url: "https://bigname.internal", headers: { authorization } })
With Goldsky for Basenames
import { bigname, fallback, goldsky } from "@ensforge/sdk/indexer"

const indexer = fallback([bigname(), goldsky()])

defineIndexer

Builds an indexer from your own functions, e.g. for an in-house API or a test double.

function defineIndexer(adapter: Adapter): Indexer

Use when your data source does not speak bigname's REST API; for one that does (a self-hosted bigname, a proxy), pass its URL to bigname({ url }) instead.

  • Implement only the queries you serve; the others fail with INDEXER_UNSUPPORTED, so fallback moves on to the next indexer.
  • Queries arrive validated: names normalized, addresses checksummed, the namespace resolved.
  • Return null from single-resource queries (getName, getRecords, …) when nothing exists.
  • Throw an ensforge error (e.g. Errors.IndexerError) to control how a failure is reported; anything else becomes INDEXER_UNAVAILABLE.
An adapter for an in-house API
import { defineIndexer } from "@ensforge/sdk/indexer"

const inHouse = defineIndexer({
  id: "in-house",
  getSubnames: async ({ name, cursor }, { signal }) => {
    const page = await api.subnames(name, cursor, { signal })
    return { items: page.items, cursor: page.next, hasMore: page.next !== null, totalCount: null }
  },
})
Trying it before bigname
import { Ensforge } from "@ensforge/sdk"
import { bigname, fallback } from "@ensforge/sdk/indexer"

const ens = Ensforge.create({ publicClient, indexer: fallback([inHouse, bigname()]) })
A test double
import { defineIndexer } from "@ensforge/sdk/indexer"

const indexer = defineIndexer({
  id: "test",
  getName: async ({ name }) => (name === "nick.eth" ? fixture : null),
})

fallback

Asks several indexers in order: each query goes to the first one that can answer it.

function fallback(indexers: readonly Indexer[], options: { readonly on?: readonly FallbackReason[] | undefined } = {}): Indexer

Use to combine indexers with different coverage (bigname for Sepolia and verified reads, Goldsky for Basenames) or to keep reading when one is down.

  • The next indexer is asked when one is unavailable, rate limiting, behind, or does not serve the query or its namespace (on narrows this). Not found is an answer: it is not retried.
  • Every answer reports the indexer that gave it (indexer).
  • Cursors and asOfTokens are tagged with the indexer that issued them; follow-up pages and snapshot reads go back to that indexer only.
  • When every indexer fails, the last failure that was not INDEXER_UNSUPPORTED is reported.
bigname first, Goldsky after
import { Ensforge } from "@ensforge/sdk"
import { bigname, fallback, goldsky } from "@ensforge/sdk/indexer"

const ens = Ensforge.create({ publicClient, indexer: fallback([bigname(), goldsky()]) })
Only when the first is down
import { bigname, fallback, goldsky } from "@ensforge/sdk/indexer"

const indexer = fallback([bigname(), goldsky()], { on: ["unavailable", "rateLimited"] })
A self-hosted indexer first
import { bigname, fallback } from "@ensforge/sdk/indexer"

const indexer = fallback([bigname({ url: "https://bigname.internal" }), bigname()])

goldsky

Goldsky's ENS indexer (ens-api.goldsky.com), which serves bigname's API for ENS and Basenames.

function goldsky(options: RestIndexerOptions = {}): Indexer

Use for Basenames (*.base.eth), or as a second indexer behind bigname on mainnet.

  • Mainnet only (ENS on chain 1, Basenames on Base); other chains need url.
  • Reads the latest state only: at and finality: "safe" | "finalized" fail with INDEXER_UNSUPPORTED, as does getResolvers.
  • Answers carry fewer fields than bigname's (no verified records, subnames without expiry); missing fields are null.
Basenames
import { Ensforge } from "@ensforge/sdk"
import { goldsky, indexerActions } from "@ensforge/sdk/indexer"

const ens = Ensforge.create({ publicClient, indexer: goldsky() }).extend(indexerActions())
const name = await ens.indexer.getName({ name: "jesse.base.eth" })
Behind bigname
import { bigname, fallback, goldsky } from "@ensforge/sdk/indexer"

const indexer = fallback([bigname(), goldsky()])
With an API key header
import { goldsky } from "@ensforge/sdk/indexer"

const indexer = goldsky({ headers: { "x-api-key": key } })

indexerActions

Adds the indexer actions to a client.

function indexerActions()

paginate

Iterates over every page of an indexer list, following cursor until the last page.

async function* paginate<options extends { cursor?: string | undefined }, item>( load: (options: options) => Promise<Page<item>>, options: options, ): AsyncGenerator<Page<item>, void, undefined>

Use to walk a whole list, such as a name's subnames or an address's names; break stops requesting further pages.

Every subname of a name
import { paginate } from "@ensforge/sdk/indexer"

for await (const page of paginate(ens.indexer.getSubnames, { name: "ens.eth", limit: 200 })) {
  render(page.items)
}
Collecting names, at most 1,000
import { paginate } from "@ensforge/sdk/indexer"

const names: string[] = []
for await (const page of paginate(ens.indexer.getNamesForAddress, { address })) {
  names.push(...page.items.map((item) => item.name))
  if (names.length >= 1000) break
}
With a standalone action
import { Actions } from "@ensforge/sdk"
import { paginate } from "@ensforge/sdk/indexer"

const pages = paginate(
  (options: Actions.indexer.getSubnames.Options) => Actions.indexer.getSubnames(ens, options),
  { name: "ens.eth" },
)

Queries

Query.Contract

A contract on the client's chain unless chainId says otherwise.

type Contract
FieldTypeDescription
addressAddress
chainIdnumber

Query.GetEvents

The query of getEvents.

type GetEvents = HistoryFilters & { /** Only this naming system; every namespace the indexer serves when omitted. */ namespace?: Namespace | undefined; name?: string | undefined; address?: Address | undefined; resolver?: { readonly chainId: number; readonly address: Address } | undefined; /** Emitting contract. */ contract?: Address | undefined; registrationId?: string | undefined; fromBlock?: bigint | undefined; toBlock?: bigint | undefined; };
FieldTypeDescription
limit (optional)numberRows per page, 1–200. @default 50
cursor (optional)stringThe previous page's cursor.
includeTotal (optional)booleanCount every row (totalCount); slower.
types (optional)readonly EventType[]
excludeTypes (optional)readonly EventType[]
recordKey (optional)stringRecord key, e.g. avatar, text:url or addr:60.
from (optional)bigint | DateInclusive time bounds (Unix seconds or dates).
to (optional)bigint | Date
order (optional)"asc" | "desc"Sort direction.
includeData (optional)booleanInclude each event's details (data, action). @default true
namespace (optional)NamespaceOnly this naming system; every namespace the indexer serves when omitted.
name (optional)string
address (optional)Address
resolver (optional){ readonly chainId: number; readonly address: Address }
contract (optional)AddressEmitting contract.
registrationId (optional)string
fromBlock (optional)bigint
toBlock (optional)bigint

Query.GetHistory

The query of getHistory.

type GetHistory = HistoryFilters & ( | { name: string; /** The naming system the name belongs to. */ namespace: Namespace; address?: undefined; /** Name events, registration events, or both. @default "both" */ scope?: "name" | "registration" | "both" | undefined; /** Also the registrations of its children. */ includeChildRegistrations?: boolean | undefined; } | { address: Address; /** Only this naming system; every namespace the indexer serves when omitted. */ namespace?: Namespace | undefined; name?: undefined; scope?: "name" | "registration" | "both" | undefined; /** @default ["owner", "manager", "roleHolder"] */ relation?: readonly ("owner" | "manager" | "roleHolder")[] | undefined; } );
FieldTypeDescription
limit (optional)numberRows per page, 1–200. @default 50
cursor (optional)stringThe previous page's cursor.
includeTotal (optional)booleanCount every row (totalCount); slower.
types (optional)readonly EventType[]
excludeTypes (optional)readonly EventType[]
recordKey (optional)stringRecord key, e.g. avatar, text:url or addr:60.
from (optional)bigint | DateInclusive time bounds (Unix seconds or dates).
to (optional)bigint | Date
order (optional)"asc" | "desc"Sort direction.
includeData (optional)booleanInclude each event's details (data, action). @default true
name (optional)string
namespace (optional)NamespaceThe naming system the name belongs to.
address (optional)undefined
scope (optional)"name" | "registration" | "both"Name events, registration events, or both. @default "both"

Query.GetName

The query of getName.

type GetName = Snapshot & { name: string; /** The naming system the name belongs to. */ namespace: Namespace; /** `verified` reads the answer on-chain through the indexer. @default "indexed" */ source?: "indexed" | "verified" | undefined; };
FieldTypeDescription
at (optional){ readonly token: string } | { readonly timestamp: bigint | Date }Read at a snapshot: an earlier answer's asOfToken, or a time.
finality (optional)"latest" | "safe" | "finalized"How settled the data must be: latest, safe or finalized.
namestring
namespaceNamespaceThe naming system the name belongs to.
source (optional)"indexed" | "verified"verified reads the answer on-chain through the indexer. @default "indexed"

Query.GetNamesByExpiry

The query of getNamesByExpiry.

type GetNamesByExpiry = List & { /** The naming system the name belongs to. */ namespace: Namespace; expiresAfter?: bigint | Date | undefined; expiresBefore?: bigint | Date | undefined; /** Up to 32 disjoint expiry windows; results report the matching `windowIndex`. */ windows?: readonly Window[] | undefined; graceEndsAfter?: bigint | Date | undefined; graceEndsBefore?: bigint | Date | undefined; graceWindows?: readonly Window[] | undefined; authority?: Authority | readonly Authority[] | undefined; parent?: string | undefined; /** Field the rows are sorted by. */ sort?: "expiry" | "graceEnd" | undefined; /** Sort direction. */ order?: "asc" | "desc" | undefined; };
FieldTypeDescription
limit (optional)numberRows per page, 1–200. @default 50
cursor (optional)stringThe previous page's cursor.
includeTotal (optional)booleanCount every row (totalCount); slower.
namespaceNamespaceThe naming system the name belongs to.
expiresAfter (optional)bigint | Date
expiresBefore (optional)bigint | Date
windows (optional)readonly Window[]Up to 32 disjoint expiry windows; results report the matching windowIndex.
graceEndsAfter (optional)bigint | Date
graceEndsBefore (optional)bigint | Date
graceWindows (optional)readonly Window[]
authority (optional)Authority | readonly Authority[]
parent (optional)string
sort (optional)"expiry" | "graceEnd"Field the rows are sorted by.
order (optional)"asc" | "desc"Sort direction.

Query.GetNamesForAddress

The query of getNamesForAddress.

type GetNamesForAddress = List & { address: Address; /** Every namespace the indexer serves when omitted. */ namespace?: Namespace | undefined; /** * Relations to list; `any` is owner, manager and role holder. `resolvesTo` and `formerOwner` * stand alone. @default "any" */ relation?: Relation | "any" | readonly Relation[] | undefined; /** Coin type for `resolvesTo`, or `evm` for every EVM chain. @default 60 */ coinType?: bigint | "evm" | undefined; /** Only direct children of this name. */ parent?: string | undefined; authority?: Authority | readonly Authority[] | undefined; /** Only names migrated to ENSv2 (or only not migrated). */ migrated?: boolean | undefined; /** Expiry bounds (Unix seconds or dates), with `formerOwner` only. */ expiresAfter?: bigint | Date | undefined; expiresBefore?: bigint | Date | undefined; search?: string | undefined; /** * Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). * * @default "prefix" */ match?: "prefix" | "contains" | undefined; /** Field the rows are sorted by. */ sort?: "name" | "expiry" | "registered" | "created" | undefined; /** Sort direction. */ order?: "asc" | "desc" | undefined; /** One row per name, or per registration. @default "name" */ dedupe?: "name" | "registration" | undefined; };
FieldTypeDescription
limit (optional)numberRows per page, 1–200. @default 50
cursor (optional)stringThe previous page's cursor.
includeTotal (optional)booleanCount every row (totalCount); slower.
addressAddress
namespace (optional)NamespaceEvery namespace the indexer serves when omitted.
relation (optional)Relation | "any" | readonly Relation[]Relations to list; any is owner, manager and role holder. resolvesTo and formerOwner stand alone. @default "any"
coinType (optional)bigint | "evm"Coin type for resolvesTo, or evm for every EVM chain. @default 60
parent (optional)stringOnly direct children of this name.
authority (optional)Authority | readonly Authority[]
migrated (optional)booleanOnly names migrated to ENSv2 (or only not migrated).
expiresAfter (optional)bigint | DateExpiry bounds (Unix seconds or dates), with formerOwner only.
expiresBefore (optional)bigint | Date
search (optional)string
match (optional)"prefix" | "contains"Whether search matches from the start of a label (prefix) or anywhere (contains).
sort (optional)"name" | "expiry" | "registered" | "created"Field the rows are sorted by.
order (optional)"asc" | "desc"Sort direction.
dedupe (optional)"name" | "registration"One row per name, or per registration. @default "name"

Query.GetNamespace

The query of getNamespace.

type GetNamespace
FieldTypeDescription
namespaceNamespace

Query.GetPermissions

The query of getPermissions.

type GetPermissions = List & { /** Only this naming system; every namespace the indexer serves when omitted. */ namespace?: Namespace | undefined; /** Include how each grant was obtained. */ includeLineage?: boolean | undefined; } & ( | { name: string; registrationId?: undefined; address?: undefined; registry?: undefined } | { registrationId: string; name?: undefined; address?: undefined; registry?: undefined } | { address: Address; name?: undefined; registrationId?: undefined; registry?: undefined } | { registry: { readonly chainId: number; readonly address: Address }; name?: undefined; registrationId?: undefined; address?: undefined; } );
FieldTypeDescription
limit (optional)numberRows per page, 1–200. @default 50
cursor (optional)stringThe previous page's cursor.
includeTotal (optional)booleanCount every row (totalCount); slower.
namespace (optional)NamespaceOnly this naming system; every namespace the indexer serves when omitted.
includeLineage (optional)booleanInclude how each grant was obtained.
name (optional)string
registrationId (optional)undefined
address (optional)undefined
registry (optional)undefined

Query.GetPrimaryName

The query of getPrimaryName.

type GetPrimaryName
FieldTypeDescription
addressAddress
coinType (optional)bigint
namespace (optional)NamespaceOnly this naming system; every namespace the indexer serves when omitted.
source (optional)"indexed" | "verified"Both, verified first, when omitted.

Query.GetRecords

The query of getRecords.

type GetRecords = Snapshot & { name: string; /** The naming system the name belongs to. */ namespace: Namespace; /** Record keys (`avatar`, `text:url`, `addr:60`, `contenthash`); the inventory's when omitted. */ keys?: readonly string[] | undefined; /** `false` returns only the inventory, without values. @default true */ values?: boolean | undefined; /** @default "indexed" */ source?: "indexed" | "verified" | "auto" | undefined; /** Read the records the name has on this resolver instead of its current one. */ resolver?: { readonly chainId: number; readonly address: Address } | undefined; };
FieldTypeDescription
at (optional){ readonly token: string } | { readonly timestamp: bigint | Date }Read at a snapshot: an earlier answer's asOfToken, or a time.
finality (optional)"latest" | "safe" | "finalized"How settled the data must be: latest, safe or finalized.
namestring
namespaceNamespaceThe naming system the name belongs to.
keys (optional)readonly string[]Record keys (avatar, text:url, addr:60, contenthash); the inventory's when omitted.
values (optional)booleanfalse returns only the inventory, without values. @default true
source (optional)"indexed" | "verified" | "auto"
resolver (optional){ readonly chainId: number; readonly address: Address }Read the records the name has on this resolver instead of its current one.

Query.GetRegistry

The query of getRegistry.

type GetRegistry = Snapshot & Contract & { includeCounts?: boolean | undefined };
FieldTypeDescription
at (optional){ readonly token: string } | { readonly timestamp: bigint | Date }Read at a snapshot: an earlier answer's asOfToken, or a time.
finality (optional)"latest" | "safe" | "finalized"How settled the data must be: latest, safe or finalized.
addressAddress
chainIdnumber
includeCounts (optional)boolean

Query.GetRegistryLabels

The query of getRegistryLabels.

type GetRegistryLabels = List & Contract & { owner?: Address | undefined; excludeOwner?: Address | undefined };
FieldTypeDescription
limit (optional)numberRows per page, 1–200. @default 50
cursor (optional)stringThe previous page's cursor.
includeTotal (optional)booleanCount every row (totalCount); slower.
addressAddress
chainIdnumber
owner (optional)Address
excludeOwner (optional)Address

Query.GetResolver

The query of getResolver.

type GetResolver = Snapshot & Contract & List;
FieldTypeDescription
at (optional){ readonly token: string } | { readonly timestamp: bigint | Date }Read at a snapshot: an earlier answer's asOfToken, or a time.
finality (optional)"latest" | "safe" | "finalized"How settled the data must be: latest, safe or finalized.
addressAddress
chainIdnumber
limit (optional)numberRows per page, 1–200. @default 50
cursor (optional)stringThe previous page's cursor.
includeTotal (optional)booleanCount every row (totalCount); slower.

The query of getResolverLinks.

type GetResolverLinks = Snapshot & Contract & List;
FieldTypeDescription
at (optional){ readonly token: string } | { readonly timestamp: bigint | Date }Read at a snapshot: an earlier answer's asOfToken, or a time.
finality (optional)"latest" | "safe" | "finalized"How settled the data must be: latest, safe or finalized.
addressAddress
chainIdnumber
limit (optional)numberRows per page, 1–200. @default 50
cursor (optional)stringThe previous page's cursor.
includeTotal (optional)booleanCount every row (totalCount); slower.

Query.GetResolverRoles

The query of getResolverRoles.

type GetResolverRoles = Snapshot & Contract & List;
FieldTypeDescription
at (optional){ readonly token: string } | { readonly timestamp: bigint | Date }Read at a snapshot: an earlier answer's asOfToken, or a time.
finality (optional)"latest" | "safe" | "finalized"How settled the data must be: latest, safe or finalized.
addressAddress
chainIdnumber
limit (optional)numberRows per page, 1–200. @default 50
cursor (optional)stringThe previous page's cursor.
includeTotal (optional)booleanCount every row (totalCount); slower.

Query.GetResolvers

The query of getResolvers.

type GetResolvers = List & { roleHolder: Address; chainId?: number | undefined };
FieldTypeDescription
limit (optional)numberRows per page, 1–200. @default 50
cursor (optional)stringThe previous page's cursor.
includeTotal (optional)booleanCount every row (totalCount); slower.
roleHolderAddress
chainId (optional)number

Query.GetStatus

The query of getStatus.

type GetStatus

Query.GetSubnames

The query of getSubnames.

type GetSubnames = List & { name: string; /** The naming system the name belongs to. */ namespace: Namespace; search?: string | undefined; /** Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). */ match?: "prefix" | "contains" | undefined; /** * Field the rows are sorted by. * * @default "name" */ sort?: "name" | "expiry" | "registered" | undefined; /** Sort direction. */ order?: "asc" | "desc" | undefined; /** @default true */ includeExpired?: boolean | undefined; };
FieldTypeDescription
limit (optional)numberRows per page, 1–200. @default 50
cursor (optional)stringThe previous page's cursor.
includeTotal (optional)booleanCount every row (totalCount); slower.
namestring
namespaceNamespaceThe naming system the name belongs to.
search (optional)string
match (optional)"prefix" | "contains"Whether search matches from the start of a label (prefix) or anywhere (contains).
sort (optional)"name" | "expiry" | "registered"Field the rows are sorted by.
order (optional)"asc" | "desc"Sort direction.
includeExpired (optional)boolean

Query.HistoryFilters

History filters shared by getHistory and getEvents.

type HistoryFilters = List & { types?: readonly EventType[] | undefined; excludeTypes?: readonly EventType[] | undefined; /** Record key, e.g. `avatar`, `text:url` or `addr:60`. */ recordKey?: string | undefined; /** Inclusive time bounds (Unix seconds or dates). */ from?: bigint | Date | undefined; to?: bigint | Date | undefined; /** * Sort direction. * * @default "desc" */ order?: "asc" | "desc" | undefined; /** Include each event's details (`data`, `action`). @default true */ includeData?: boolean | undefined; };
FieldTypeDescription
limit (optional)numberRows per page, 1–200. @default 50
cursor (optional)stringThe previous page's cursor.
includeTotal (optional)booleanCount every row (totalCount); slower.
types (optional)readonly EventType[]
excludeTypes (optional)readonly EventType[]
recordKey (optional)stringRecord key, e.g. avatar, text:url or addr:60.
from (optional)bigint | DateInclusive time bounds (Unix seconds or dates).
to (optional)bigint | Date
order (optional)"asc" | "desc"Sort direction.
includeData (optional)booleanInclude each event's details (data, action). @default true

Query.List

Paging, on list routes.

type List
FieldTypeDescription
limit (optional)numberRows per page, 1–200. @default 50
cursor (optional)stringThe previous page's cursor.
includeTotal (optional)booleanCount every row (totalCount); slower.

Query.Lookup

The query of lookup.

type Lookup
FieldTypeDescription
inputsreadonly string[]Names and addresses, up to 1,000.
namespace (optional)NamespaceOnly this naming system; every namespace the indexer serves when omitted.
profile (optional)"feed" | "detail"detail adds records and resolution. @default "feed"

Query.Search

The query of search.

type Search = List & { query: string; /** Only this naming system; every namespace the indexer serves when omitted. */ namespace?: Namespace | undefined; /** * Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). * * @default "prefix" */ match?: "prefix" | "contains" | undefined; };
FieldTypeDescription
limit (optional)numberRows per page, 1–200. @default 50
cursor (optional)stringThe previous page's cursor.
includeTotal (optional)booleanCount every row (totalCount); slower.
querystring
namespace (optional)NamespaceOnly this naming system; every namespace the indexer serves when omitted.
match (optional)"prefix" | "contains"Whether search matches from the start of a label (prefix) or anywhere (contains).

Query.Snapshot

Snapshot selection, on routes that read one snapshot (names, records, registries, resolvers).

type Snapshot
FieldTypeDescription
at (optional){ readonly token: string } | { readonly timestamp: bigint | Date }Read at a snapshot: an earlier answer's asOfToken, or a time.
finality (optional)"latest" | "safe" | "finalized"How settled the data must be: latest, safe or finalized.

Query.Window

A half-open window [after, before), Unix seconds or dates.

type Window
FieldTypeDescription
afterbigint | Date
beforebigint | Date

Types

Adapter

A custom adapter: an id and the queries it answers, as Promise functions.

type Adapter = { readonly id: string; /** What distinguishes this indexer from others with the same id (see `Indexer.key`). */ readonly key?: string | undefined; } & { readonly [method in Method]?: ( query: Parameters<Methods[method]>[0], context: Context, ) => Promise<Draft<ReturnType<Methods[method]>>>; };
FieldTypeDescription
idstring
key (optional)stringWhat distinguishes this indexer from others with the same id (see Indexer.key).

AddressName

A name an address is related to.

type AddressName = IndexedName & { readonly relations: readonly Relation[]; /** Whether it is the address's primary name. */ readonly isPrimary: boolean; readonly migratedAt: bigint | null; readonly recordCount: number | null; readonly subnameCount: number | null; };
FieldTypeDescription
namestringNormalized name; unknown labels appear as [labelhash].
displayNamestring
namespacestring
nodeHex
statusNameStatus | null
authorityAuthority | null
ownerAddress | nullToken holder (ENSv2) or registrant; null when unowned or not reported.
managerAddress | nullENSv1 registry owner (controller) when it differs in meaning from the holder.
registeredAtbigint | nullUnix seconds of the current registration. Lineage rules differ between indexers.
createdAtbigint | nullUnix seconds the name first appeared.
expiresAtbigint | nullUnix seconds; 2^64 - 1 for names that never expire.
graceEndsAtbigint | null
expiryReason"noExpiry" | "notSet" | "released" | nullWhy expiresAt is null.
ensV1EnsV1Facts | null
relationsreadonly Relation[]
isPrimarybooleanWhether it is the address's primary name.
migratedAtbigint | null
recordCountnumber | null
subnameCountnumber | null

AnswerStatus

Outcome of one answer inside a result (a record, a primary name, a lookup input).

type AnswerStatus = | "ok" | "notFound" | "invalidName" | "mismatch" | "unsupported" | "stale" | "failed";

Authority

Which ENS protocol holds a name: ensV0 is the pre-2020 registry, ensV1 the current ENSv1 registry, ensV2 an ENSv2 registry.

type Authority = "ensV0" | "ensV1" | "ensV2";

ChainStatus

Indexing progress of one chain.

type ChainStatus
FieldTypeDescription
status"ready" | "degraded" | "stale"
indexedbigint | null
latestbigint | null
safebigint | null
finalizedbigint | null
lagBlocksnumber | null
lagSecondsnumber | null

Completeness

How much of an answer the indexer could give. partial and unsupported come with a reason; a partial answer is never presented as complete.

type Completeness = "full" | "partial" | "unsupported";

Context

What an adapter knows about the call besides its query.

type Context
FieldTypeDescription
chainIdnumberChain of the ensforge client, e.g. 1 for mainnet.
signalAbortSignalAborted when the call is cancelled.

ContractRef

A contract on a chain.

type ContractRef
FieldTypeDescription
chainIdnumber
addressAddress

Draft

What an adapter returns for an answer type: the answer, with every Meta field optional. ensforge fills the missing ones (completeness: "full", no snapshot) and sets indexer to the adapter id.

type Draft<answer> = answer extends null ? null : Omit<answer, keyof Meta> & Partial<Meta>;

EnsV1Facts

ENSv1 facts about a name: its ENSv1 resolver and NameWrapper state.

type EnsV1Facts
FieldTypeDescription
resolverContractRef | null
expiresAtbigint | null
wrapperState"wrapped" | "emancipated" | "locked" | "lapsed" | "unwrapped" | "unknown" | null
wrapperExpiresAtbigint | null
wrapperFusesnumber | nullNameWrapper fuses as a bitmap; decode with Fuse.

ExpiringName

A name from getNamesByExpiry, with the window it matched.

type ExpiringName = IndexedName & { /** Index into `windows` (or `graceWindows`) that matched. */ readonly windowIndex: number | null; };
FieldTypeDescription
namestringNormalized name; unknown labels appear as [labelhash].
displayNamestring
namespacestring
nodeHex
statusNameStatus | null
authorityAuthority | null
ownerAddress | nullToken holder (ENSv2) or registrant; null when unowned or not reported.
managerAddress | nullENSv1 registry owner (controller) when it differs in meaning from the holder.
registeredAtbigint | nullUnix seconds of the current registration. Lineage rules differ between indexers.
createdAtbigint | nullUnix seconds the name first appeared.
expiresAtbigint | nullUnix seconds; 2^64 - 1 for names that never expire.
graceEndsAtbigint | null
expiryReason"noExpiry" | "notSet" | "released" | nullWhy expiresAt is null.
ensV1EnsV1Facts | null
windowIndexnumber | nullIndex into windows (or graceWindows) that matched.

FallbackReason

Failures after which fallback asks the next indexer.

type FallbackReason = "unavailable" | "rateLimited" | "unsupported" | "behind";

IndexedEvent

One event from an indexer's history, in the same vocabulary as event.*.

type IndexedEvent
FieldTypeDescription
idstring
typeEventType
actionEventAction | nullWhat happened; present when the event data was requested (includeData).
kindstring | nullIndexer event kind, e.g. RegistrationGranted.
namestring | nullThe name the event is about; null when the indexer does not say.
namespacestring
subject"name" | "child" | nullWhether the event is about the name or one of its children.
registrationIdstring | null
contractAddress | null
blockNumberbigint | null
timestampbigint | null
transactionHashHex | null
logIndexnumber | null
dataReadonly<Record<string, unknown>> | nullEvent details with camelCase keys, when requested with includeData.

IndexedName

A name as lists return it.

type IndexedName
FieldTypeDescription
namestringNormalized name; unknown labels appear as [labelhash].
displayNamestring
namespacestring
nodeHex
statusNameStatus | null
authorityAuthority | null
ownerAddress | nullToken holder (ENSv2) or registrant; null when unowned or not reported.
managerAddress | nullENSv1 registry owner (controller) when it differs in meaning from the holder.
registeredAtbigint | nullUnix seconds of the current registration. Lineage rules differ between indexers.
createdAtbigint | nullUnix seconds the name first appeared.
expiresAtbigint | nullUnix seconds; 2^64 - 1 for names that never expire.
graceEndsAtbigint | null
expiryReason"noExpiry" | "notSet" | "released" | nullWhy expiresAt is null.
ensV1EnsV1Facts | null

IndexedNameDetail

One name in full.

type IndexedNameDetail = IndexedName & { readonly chainId: number | null; /** Indexer handle for the current registration; opaque, differs between indexers. */ readonly registrationId: string | null; readonly tokenId: bigint | null; readonly resolver: ContractRef | null; /** ENSv2 registry for the name's children. */ readonly subregistry: ContractRef | null; /** The ETH address the name resolves to. */ readonly primaryAddress: Address | null; readonly migratedAt: bigint | null; readonly records: IndexedProfile | null; readonly recordCount: number | null; readonly subnameCount: number | null; };
FieldTypeDescription
namestringNormalized name; unknown labels appear as [labelhash].
displayNamestring
namespacestring
nodeHex
statusNameStatus | null
authorityAuthority | null
ownerAddress | nullToken holder (ENSv2) or registrant; null when unowned or not reported.
managerAddress | nullENSv1 registry owner (controller) when it differs in meaning from the holder.
registeredAtbigint | nullUnix seconds of the current registration. Lineage rules differ between indexers.
createdAtbigint | nullUnix seconds the name first appeared.
expiresAtbigint | nullUnix seconds; 2^64 - 1 for names that never expire.
graceEndsAtbigint | null
expiryReason"noExpiry" | "notSet" | "released" | nullWhy expiresAt is null.
ensV1EnsV1Facts | null
chainIdnumber | null
registrationIdstring | nullIndexer handle for the current registration; opaque, differs between indexers.
tokenIdbigint | null
resolverContractRef | null
subregistryContractRef | nullENSv2 registry for the name's children.
primaryAddressAddress | nullThe ETH address the name resolves to.
migratedAtbigint | null
recordsIndexedProfile | null
recordCountnumber | null
subnameCountnumber | null

IndexedPrimaryName

An address's primary name from getPrimaryName.

type IndexedPrimaryName
FieldTypeDescription
addressAddress
coinTypenumber
namespacestring
namestring | nullThe primary name: verified when the indexer verified it, otherwise indexed.
source"indexed" | "verified" | nullWhich answer name came from.
answersreadonly PrimaryNameAnswer[]

IndexedProfile

A name's records as getName and lookup return them: values the indexer has seen.

type IndexedProfile
FieldTypeDescription
textsReadonly<Record<string, string>>
addressesReadonly<Record<string, string>>Addresses by decimal coin type, encoded as the chain writes them.
contentHashHex | null
namestring | nullName record (ENSIP-3) of reverse names.
textKeysreadonly string[]Every text key ever set, including cleared ones.
coinTypesreadonly string[]Every coin type ever set, including cleared ones.

IndexedRecords

A name's records from getRecords.

type IndexedRecords
FieldTypeDescription
namespacestring
resolverContractRef | null
textsReadonly<Record<string, string>>
addressesReadonly<Record<string, string>>Addresses by decimal coin type.
contentHashHex | null
answersReadonly<Record<string, RecordAnswer>>Every answer by record key (text:avatar, addr:60, contenthash), including failures.
inventory{ readonly keys: readonly string[]; readonly unsetKeys: readonly string[]; readonly unsupportedKeys: readonly string[]; } | nullEvery record key the resolver has seen for the name. keys are set; unsetKeys were cleared; unsupportedKeys cannot be read through the indexer.

IndexedRegistry

An ENSv2 registry.

type IndexedRegistry
FieldTypeDescription
chainIdnumber
addressAddress
namestring | nullThe name whose children it holds, when known.
parentContractRef | null
createdAtbigint | null
createdBlockNumberbigint | null
createdTransactionHashHex | null
counts{ readonly labels: number | null; readonly roles: number | null; readonly events: number | null; } | null
referencedByreadonly string[]Names whose subregistry pointer is this registry.

IndexedResolver

A resolver and the names bound to it.

type IndexedResolver
FieldTypeDescription
chainIdnumber
addressAddress
namesreadonly string[]Names using this resolver, one page of them.
cursorstring | null
hasMoreboolean
mirrorsContractRef | nullENSv1 registry this resolver mirrors, for ENSv1 compatibility resolvers.

Indexer

An indexer ensforge reads through: bigname(), goldsky(), fallback([...]) or defineIndexer({...}). Pass it to Ensforge.create({ indexer }).

interface Indexer
FieldTypeDescription
idstringAdapter id, reported as indexer on every answer.
keystringThe adapter and where it reads from, e.g. bigname:https://bigname.internal: two indexers with the same key answer alike, so caches (React's) can share their answers.
~ensforge/indexertrue

IndexerActions

indexer actions bound to a client.

type IndexerActions
FieldTypeDescription
indexer{ /** Searches indexed ENS events by name, address, resolver, contract or block range. */ readonly getEvents: Bound<typeof indexer.getEvents>; /** Reads the full history of a name, or of every name an address is related to. */ readonly getHistory: Bound<typeof indexer.getHistory>; /** Reads one name from the indexer: owner, manager, expiry, resolver, records and protocol. */ readonly getName: Bound<typeof indexer.getName>; /** Lists names by when they expire or leave their grace period. */ readonly getNamesByExpiry: Bound<typeof indexer.getNamesByExpiry>; /** Lists the names an address owns, manages, holds roles on, resolves to, or used to own. */ readonly getNamesForAddress: Bound<typeof indexer.getNamesForAddress>; /** Reads what the indexer serves for a namespace: its networks and which features are complete. */ readonly getNamespace: Bound<typeof indexer.getNamespace>; /** Lists who can do what over a name, a registration, an account or an ENSv2 registry. */ readonly getPermissions: Bound<typeof indexer.getPermissions>; /** Reads an address's primary name from the indexer, verified on-chain when the indexer can. */ readonly getPrimaryName: Bound<typeof indexer.getPrimaryName>; /** Reads a name's records and its record inventory from the indexer. */ readonly getRecords: Bound<typeof indexer.getRecords>; /** Reads an ENSv2 registry: the name it serves, its parent registry, when it was created and its counts. */ readonly getRegistry: Bound<typeof indexer.getRegistry>; /** Lists the labels of an ENSv2 registry, optionally only those an address holds or does not hold. */ readonly getRegistryLabels: Bound<typeof indexer.getRegistryLabels>; /** Reads a resolver and one page of the names bound to it. */ readonly getResolver: Bound<typeof indexer.getResolver>; /** Lists the names linked to record sets on an ENSv2 resolver. */ readonly getResolverLinks: Bound<typeof indexer.getResolverLinks>; /** Lists the role grants on an ENSv2 resolver. */ readonly getResolverRoles: Bound<typeof indexer.getResolverRoles>; /** Lists the ENSv2 resolvers on which an address holds roles. */ readonly getResolvers: Bound<typeof indexer.getResolvers>; /** Reads the indexer's health and how far each chain is indexed. */ readonly getStatus: Bound<typeof indexer.getStatus>; /** Lists the direct subnames of a name. */ readonly getSubnames: Bound<typeof indexer.getSubnames>; /** Reads up to 1,000 names and addresses in one request. */ readonly lookup: Bound<typeof indexer.lookup>; /** Searches names by text. */ readonly search: Bound<typeof indexer.search>; }

IndexerStatus

An indexer's health.

type IndexerStatus
FieldTypeDescription
status"ready" | "degraded" | "stale"
chainsReadonly<Record<number, ChainStatus>>
indexerstring

LookupResult

One input's answer from lookup.

type LookupResult
FieldTypeDescription
inputstring
kind"name" | "address"
statusAnswerStatus
name(IndexedNameDetail & { readonly isPrimary: boolean | null }) | nullA name input, or an address's primary name.
namesreadonly (IndexedNameDetail & { readonly isPrimary: boolean | null })[]An address input's related names.
reasonstring | null

Meta

What every indexer answer carries besides its data.

type Meta
FieldTypeDescription
asOfSnapshot | nullSnapshot of the answer's main chain, or null when the indexer reports none.
snapshotsReadonly<Record<number, Snapshot>>Every chain the answer read, keyed by chain ID.
asOfTokenstring | nullPass back as at: { token } to read the same snapshot again (snapshot routes only). null when the indexer does not support snapshots.
completenessCompleteness
unsupportedReasonstring | nullWhy the answer is partial or unsupported.
unsupportedFieldsreadonly string[]Fields the indexer could not fill.
origin"indexed" | "verified" | nullWhether the indexer answered from its index or by an on-chain read.
indexerstringId of the adapter that answered, e.g. bigname.

Method

Name of an indexer query.

type Method = keyof Methods;

Methods

Every query an adapter can answer, with its query and answer types. null answers mean "not found".

type Methods
FieldTypeDescription
getName(query: Query.GetName) => Result<IndexedNameDetail> | null
getNamesForAddress(query: Query.GetNamesForAddress) => Page<AddressName>
getSubnames(query: Query.GetSubnames) => Page<Subname>
getHistory(query: Query.GetHistory) => Page<IndexedEvent>
getEvents(query: Query.GetEvents) => Page<IndexedEvent>
search(query: Query.Search) => Page<IndexedName>
lookup(query: Query.Lookup) => Result<{ readonly results: readonly LookupResult[] }>
getNamesByExpiry(query: Query.GetNamesByExpiry) => Page<ExpiringName>
getPrimaryName(query: Query.GetPrimaryName) => Result<IndexedPrimaryName>
getRecords(query: Query.GetRecords) => Result<IndexedRecords> | null
getPermissions(query: Query.GetPermissions) => Page<PermissionRow>
getRegistry(query: Query.GetRegistry) => Result<IndexedRegistry> | null
getRegistryLabels(query: Query.GetRegistryLabels) => Page<RegistryLabel>
getResolver(query: Query.GetResolver) => Result<IndexedResolver> | null
getResolverLinks(query: Query.GetResolverLinks) => Page<ResolverLink>
getResolverRoles(query: Query.GetResolverRoles) => Page<ResolverRole>
getResolvers(query: Query.GetResolvers) => Page<RoleHolderResolver>
getNamespace(query: Query.GetNamespace) => Result<NamespaceInfo> | null
getStatus(query: Query.GetStatus) => IndexerStatus

NameStatus

A name's registration lifecycle.

type NameStatus = "active" | "expired" | "released" | "unregistered";

Namespace

A naming system an indexer serves: ENS, or Basenames (*.base.eth, on Base).

type Namespace = "ens" | "basenames";

NamespaceInfo

What an indexer serves for one namespace.

type NamespaceInfo
FieldTypeDescription
namespacestring
capabilitiesReadonly<Record<string, Completeness>>Feature (e.g. subnames, verified_records) → completeness.
networksreadonly { readonly network: string; readonly chainId: number | null; /** ENS protocol resolving on that network, and since which block. */ readonly protocol: "ensV1" | "ensV2" | null; readonly sinceBlock: bigint | null; }[]

Page

One page of a list, with its Meta.

type Page<item> = Meta & { readonly items: readonly item[]; /** Pass as `cursor` for the next page; `null` on the last page. */ readonly cursor: string | null; readonly hasMore: boolean; /** Total across pages, when requested with `includeTotal` and the indexer can count. */ readonly totalCount: number | null; };
FieldTypeDescription
asOfSnapshot | nullSnapshot of the answer's main chain, or null when the indexer reports none.
snapshotsReadonly<Record<number, Snapshot>>Every chain the answer read, keyed by chain ID.
asOfTokenstring | nullPass back as at: { token } to read the same snapshot again (snapshot routes only). null when the indexer does not support snapshots.
completenessCompleteness
unsupportedReasonstring | nullWhy the answer is partial or unsupported.
unsupportedFieldsreadonly string[]Fields the indexer could not fill.
origin"indexed" | "verified" | nullWhether the indexer answered from its index or by an on-chain read.
indexerstringId of the adapter that answered, e.g. bigname.
itemsreadonly item[]
cursorstring | nullPass as cursor for the next page; null on the last page.
hasMoreboolean
totalCountnumber | nullTotal across pages, when requested with includeTotal and the indexer can count.

PermissionRow

A permission one address holds over a name, registry or resolver.

type PermissionRow
FieldTypeDescription
addressAddress
namestring | null
registrationIdstring
powersreadonly string[]Powers in the indexer's vocabulary, e.g. set_resolver, admin_renew.
scopestringWhere the grant applies: registry, registration, resolver, …
relation"operator" | "holder" | null
wrapperState"wrapped" | "emancipated" | "locked" | nullNameWrapper state the permission depends on.
lineageReadonly<Record<string, unknown>> | null

PrimaryNameAnswer

One primary name answer.

type PrimaryNameAnswer
FieldTypeDescription
source"indexed" | "verified"
statusAnswerStatus
namestring | null
reasonstring | null

RecordAnswer

One record answer from getRecords.

type RecordAnswer
FieldTypeDescription
statusAnswerStatus
valuestring | null
reasonstring | null

RegistryLabel

A label in an ENSv2 registry.

type RegistryLabel = Subname & { readonly roleHolderCount: number | null; };
FieldTypeDescription
namestringNormalized name; unknown labels appear as [labelhash].
displayNamestring
namespacestring
nodeHex
statusNameStatus | null
authorityAuthority | null
ownerAddress | nullToken holder (ENSv2) or registrant; null when unowned or not reported.
managerAddress | nullENSv1 registry owner (controller) when it differs in meaning from the holder.
registeredAtbigint | nullUnix seconds of the current registration. Lineage rules differ between indexers.
createdAtbigint | nullUnix seconds the name first appeared.
expiresAtbigint | nullUnix seconds; 2^64 - 1 for names that never expire.
graceEndsAtbigint | null
expiryReason"noExpiry" | "notSet" | "released" | nullWhy expiresAt is null.
ensV1EnsV1Facts | null
labelhashHex | null
subnameCountnumber | null
subregistryContractRef | null
roleHolderCountnumber | null

Relation

How an address relates to a name.

type Relation = "owner" | "manager" | "roleHolder" | "resolvesTo" | "formerOwner";

A name linked to a record set on an ENSv2 resolver.

type ResolverLink
FieldTypeDescription
namestring
nodeHex
recordIdstring
isDefaultbooleanWhether it is the resolver's default record set.
blockNumberbigint | null
transactionHashHex | null

ResolverRole

A role grant on an ENSv2 resolver.

type ResolverRole
FieldTypeDescription
addressAddress
namestring | null
registrationIdstring
powersreadonly string[]
blockNumberbigint | null

RestIndexerOptions

Connection options shared by the built-in REST indexers.

type RestIndexerOptions
OptionTypeDefaultDescription
urlstringthe public host for the client's chainBase URL of a server with the same API (self-hosted, a proxy). A version path (/v1) is added unless the URL ends with one.
headersReadonly<Record<string, string>>Extra request headers, e.g. an API key.
fetchtypeof fetchfetch to send requests with. @default globalThis.fetch
timeoutnumberMilliseconds per request before it is retried or fails. @default 15_000
retryCountnumber2Retries of rate-limited, unavailable and timed-out requests; Retry-After is honoured.

Result

One answer with its Meta.

type Result<data> = data & Meta;
FieldTypeDescription
asOfSnapshot | nullSnapshot of the answer's main chain, or null when the indexer reports none.
snapshotsReadonly<Record<number, Snapshot>>Every chain the answer read, keyed by chain ID.
asOfTokenstring | nullPass back as at: { token } to read the same snapshot again (snapshot routes only). null when the indexer does not support snapshots.
completenessCompleteness
unsupportedReasonstring | nullWhy the answer is partial or unsupported.
unsupportedFieldsreadonly string[]Fields the indexer could not fill.
origin"indexed" | "verified" | nullWhether the indexer answered from its index or by an on-chain read.
indexerstringId of the adapter that answered, e.g. bigname.

RoleHolderResolver

A resolver on which an address holds roles.

type RoleHolderResolver = ContractRef & { readonly grantCount: number; readonly powers: readonly string[]; };
FieldTypeDescription
chainIdnumber
addressAddress
grantCountnumber
powersreadonly string[]

Snapshot

The chain state an answer was read at.

type Snapshot
FieldTypeDescription
chainIdnumber
blockNumberbigint
blockHashHex
timestampbigintUnix seconds.

Subname

A direct child of a name.

type Subname = IndexedName & { readonly labelhash: Hex | null; readonly subnameCount: number | null; readonly subregistry: ContractRef | null; };
FieldTypeDescription
namestringNormalized name; unknown labels appear as [labelhash].
displayNamestring
namespacestring
nodeHex
statusNameStatus | null
authorityAuthority | null
ownerAddress | nullToken holder (ENSv2) or registrant; null when unowned or not reported.
managerAddress | nullENSv1 registry owner (controller) when it differs in meaning from the holder.
registeredAtbigint | nullUnix seconds of the current registration. Lineage rules differ between indexers.
createdAtbigint | nullUnix seconds the name first appeared.
expiresAtbigint | nullUnix seconds; 2^64 - 1 for names that never expire.
graceEndsAtbigint | null
expiryReason"noExpiry" | "notSet" | "released" | nullWhy expiresAt is null.
ensV1EnsV1Facts | null
labelhashHex | null
subnameCountnumber | null
subregistryContractRef | null

Was this page helpful?