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
- For full history, a client with an indexer and
indexerActions(). See Connect an indexer. - For recent events only, a plain client is enough. See Read recent events from the chain.
Read the full history of a name
indexer.getHistory returns one page of events, newest first.
Example (Reading a Name's History)
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
typeandactionvocabulary as the on-chainevent.get. order: "asc"returns the oldest first.- Each event includes its details in
data, unless you passincludeData: false. scopepicks 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)
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)
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)
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);
}fromBlockis required.toBlockdefaults to"latest".- Events come back in chain order.
- Ranges the RPC provider rejects are split. After
maxRequestseth_getLogsrequests (default 500), the read fails withLOG_RANGE_TOO_LARGEinstead of sending more. event.getcovers one name. Address-wide and full history needs an indexer.
See event.get.
Options
indexer.getHistory takes a name or an address, plus:
| Option | Type | Default | Description |
|---|---|---|---|
name | string | required without address | The name whose history to read. |
address | string | required without name | The account whose names' history to read. |
namespace | "ens" or "basenames" | inferred from the name, every namespace for an address | Naming system to read. |
scope | "name", "registration" or "both" | "both" | Name events, registration events, or both. |
types | list of event types | none | Only these types. |
excludeTypes | list of event types | none | Leave these types out. |
recordKey | string | none | Only changes to this record, such as avatar, text:url or addr:60. |
from, to | bigint or Date | none | Inclusive time bounds, in Unix seconds or dates. |
order | "asc" or "desc" | "desc" | Newest first by default. |
includeData | boolean | true | Include each event's data and action. |
includeChildRegistrations | boolean | none | With name: also the registrations of its children. |
relation | list of "owner", "manager", "roleHolder" | all three | With address: which relations to follow. |
limit, cursor, includeTotal | Paging. 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?