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

Name history

Read everything that happened to a name or an account, from its first event to the latest, as a list of ownership and record events.

By the end of this guide you can show an activity feed for a name or an account: registrations, renewals, transfers, resolver and record changes.

Prerequisites

Read the full history of a name

indexer.getHistory returns one page of events, newest first.

Example (Reading a Name's History)

name-history.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.getHistory({ name: "nick.eth", limit: 25 });

for (const event of page.items) {
  console.log(event.type, event.action, event.timestamp, event.transactionHash);
}
  • Events carry the same type and action vocabulary as the on-chain event.get.
  • order: "asc" returns the oldest first.
  • Each event includes its details in data, unless you pass includeData: false.
  • scope picks the name's own events, its registrations' events, or "both" (the default).

See indexer.getHistory and Load more results.

Filter the history

Example (Reading Transfers and Avatar Changes)

history-filters.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 transfers = await ens.indexer.getHistory({ name: "nick.eth", types: ["transfer"] });

const avatarChanges = await ens.indexer.getHistory({
  name: "nick.eth",
  recordKey: "avatar",
  order: "asc",
});

Read the history of an account

Pass an address instead of a name to read the events of every name the address is related to. By default relation follows owner, manager and role holder.

Example (Reading an Account's Activity)

account-history.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.getHistory({
  address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  types: ["registration", "renewal", "transfer"],
});

Read recent events from the chain

event.get reads a name's events straight from the chain over a block range. It needs no indexer, and shows the same kinds of events. Use it for recent activity, or to see the effect of a write.

Example (Reading Recent Events)

recent-events.ts
import { ensActions, Ensforge } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

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

const head = await publicClient.getBlockNumber();
const events = await ens.event.get({ name: "nick.eth", fromBlock: head - 50_000n });

for (const event of events) {
  console.log(event.type, event.action, event.blockNumber);
}
  • fromBlock is required. toBlock defaults to "latest".
  • Events come back in chain order.
  • Ranges the RPC provider rejects are split. After maxRequests eth_getLogs requests (default 500), the read fails with LOG_RANGE_TOO_LARGE instead of sending more.
  • event.get covers one name. Address-wide and full history needs an indexer.

See event.get.

Options

indexer.getHistory takes a name or an address, plus:

OptionTypeDefaultDescription
namestringrequired without addressThe name whose history to read.
addressstringrequired without nameThe account whose names' history to read.
namespace"ens" or "basenames"inferred from the name, every namespace for an addressNaming system to read.
scope"name", "registration" or "both""both"Name events, registration events, or both.
typeslist of event typesnoneOnly these types.
excludeTypeslist of event typesnoneLeave these types out.
recordKeystringnoneOnly changes to this record, such as avatar, text:url or addr:60.
from, tobigint or DatenoneInclusive time bounds, in Unix seconds or dates.
order"asc" or "desc""desc"Newest first by default.
includeDatabooleantrueInclude each event's data and action.
includeChildRegistrationsbooleannoneWith name: also the registrations of its children.
relationlist of "owner", "manager", "roleHolder"all threeWith address: which relations to follow.
limit, cursor, includeTotalPaging. See Load more results.

Event types are registration, renewal, release, expiry, transfer, authority, resolver, record, primary_name, permission, subregistry, migration, reservation, token and contract.

Troubleshooting

INDEXER_NOT_FOUND

The indexer has no such name. INDEXER_NOT_FOUND is thrown for a name that has never been indexed. Check the spelling, or read the name on-chain.

INDEXER_NOT_CONFIGURED

The client has no indexer, or you forgot indexerActions(). See Connect an indexer and INDEXER_NOT_CONFIGURED.

LOG_RANGE_TOO_LARGE

The block range for event.get is too large for your RPC provider's log limits. Use a smaller range, or read the history from an indexer.

A recent change is missing

The indexer can lag the chain by a few blocks. Read ens.indexer.getStatus(), or use event.get for the latest blocks. See Watch for changes.

Was this page helpful?