Skip to content
Open
Show file tree
Hide file tree
Changes from 13 commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
a83d810
Update docs for Unigraph examples
tk-o May 26, 2026
5ab3e68
Apply AI PR feedback
tk-o May 26, 2026
3d9881c
Apply AI PR feedback
tk-o May 27, 2026
22012e2
Merge remote-tracking branch 'origin/main' into docs/improve-unigraph…
tk-o May 27, 2026
97ccdb4
Create dedicated pages
tk-o May 27, 2026
15fc5b2
Udpate ENSNode Plugins page
tk-o May 27, 2026
d701b2e
Merge remote-tracking branch 'origin/main' into docs/improve-ensdb-wr…
tk-o May 30, 2026
2e61b46
Shift plugins narrative to focus on "ENSNode Plugins"
tk-o May 30, 2026
dc68c9a
Apply AI PR feedback
tk-o May 30, 2026
799444a
Apply AI PR feedback
tk-o May 30, 2026
4ffbc77
Merge remote-tracking branch 'origin/main' into docs/improve-ensdb-wr…
tk-o May 30, 2026
b9ad9ff
Apply AI PR feedback
tk-o May 30, 2026
8e6910f
Fix sidebar link desc
tk-o May 30, 2026
7078001
Apply suggestions from code review
tk-o Jun 1, 2026
6b1904d
Apply suggestions from code review
tk-o Jun 1, 2026
321a5b6
Merge remote-tracking branch 'origin/main' into docs/improve-ensdb-wr…
tk-o Jun 1, 2026
a8ab221
convert crlf to lf
tk-o Jun 1, 2026
0a94011
Apply PR feedback
tk-o Jun 1, 2026
8439521
Apply PR feedback
tk-o Jun 2, 2026
b278eff
Merge remote-tracking branch 'origin/main' into docs/improve-ensdb-wr…
tk-o Jun 2, 2026
9aa00be
Apply PR feedback
tk-o Jun 2, 2026
3e5bb48
Add plugin info links
tk-o Jun 2, 2026
3aa5d30
Apply AI PR feedback
tk-o Jun 2, 2026
ff7597e
Apply AI PR feedback
tk-o Jun 2, 2026
c6aa559
Apply AI PR feedback
tk-o Jun 3, 2026
ec6fabd
Merge remote-tracking branch 'origin/main' into docs/improve-ensdb-wr…
tk-o Jun 3, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -208,6 +208,18 @@ export const integrateSidebarTopic = {
label: "ENSDb (SQL)",
link: "/docs/integrate/integration-options/ensdb",
},
{
label: "ENSDb Writers (Indexers)",
link: "/docs/integrate/integration-options/ensdb-writers",
},
{
label: "ENSDb Readers (Custom APIs)",
link: "/docs/integrate/integration-options/ensdb-readers",
},
{
label: "ENSNode Plugins (data models)",
link: "/docs/integrate/integration-options/ensnode-plugins",
},
{
label: "enscli (CLI)",
link: "/docs/integrate/integration-options/enscli",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ export const servicesSidebarTopic = {
items: [
{ label: "Overview", link: "/docs/services/ensindexer/contributing" },
{
label: "Creating a Plugin",
label: "Creating an ENSNode Plugin",
link: "/docs/services/ensindexer/contributing/creating-a-plugin",
},
],
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Full access to ENS data formerly required two separate data-fetching strategies

## How ENSNode solves this

**The Unigraph Data Model** — [ENSIndexer](/docs/services/ensindexer)'s `unigraph` plugin builds a single, **unified** indexed data model in [ENSDb](/docs/services/ensdb) that combines all of ENSv1 — mainnet `.eth`, Basenames on Base, Lineanames on Linea, 3DNS on Optimism — together with ENSv2. One data model, every chain, both protocol versions.
**The Unigraph Data Model** — The `unigraph` [ENSNode plugin](/docs/integrate/integration-options/ensnode-plugins), implemented in [ENSIndexer](/docs/services/ensindexer), builds a single, **unified** indexed data model in [ENSDb](/docs/services/ensdb) that combines all of ENSv1 — mainnet `.eth`, Basenames on Base, Lineanames on Linea, 3DNS on Optimism — together with ENSv2. One data model, every chain, both protocol versions.

**The Omnigraph API** — The [ENS Omnigraph API](/docs/integrate/omnigraph), delivered by [ENSApi](/docs/services/ensapi), is a fully typed GraphQL API on top of that Unigraph data model. It handles the ENS protocol's many implementation details for you, so you can focus on building your app instead of wiring up the protocol's internals.

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
---
title: ENSDb Readers (Custom APIs)
description: How to build custom APIs on top of ENSDb, using the ENSDb Reader specification.
Comment thread
tk-o marked this conversation as resolved.
Outdated
---

import { LinkCard } from "@astrojs/starlight/components";

Comment thread
tk-o marked this conversation as resolved.
## Standards-compliant ENSDb Readers
Comment thread
tk-o marked this conversation as resolved.
Outdated

There are multiple [ENSDb Reader](/docs/services/ensdb/concepts/glossary#ensdb-reader) apps created (and planned) by the NameHash team. Find out more about each of them below.

:::note[Build your own ENSDb Reader]
Continuing on the ideas shared in [ENSDb integration options page](/docs/integrate/integration-options/ensdb), you can build your own ENSDb Reader app and define a custom data model and capabilities that are required for your use cases. Feel free to reach out to the NameHash team on [Telegram](https://t.me/ensnode) if you want to build your own ENSDb Reader and want any help or guidance!
:::
Comment thread
tk-o marked this conversation as resolved.

### ENSApi

ENSApi is a reference implementation of an [ENSDb Reader](/docs/services/ensdb/concepts/glossary#ensdb-reader) that includes standards-compliant web services:
Comment thread
tk-o marked this conversation as resolved.
Outdated

- A standards-compliant [ENS Omnigraph GraphQL API](/docs/integrate/integration-options/omnigraph-graphql-api) on top of [ENSNode Plugins](/docs/integrate/integration-options/ensnode-plugins) such as `unigraph` and `protocol-acceleration`.
Comment thread
tk-o marked this conversation as resolved.
Outdated
- A standards-compliant [ENS Subgraph GraphQL API](/docs/integrate/ens-subgraph) on top of [ENSNode Plugins](/docs/integrate/integration-options/ensnode-plugins) such as `subgraph`, `basenames`, `lineanames`, and `threedns`.
Comment thread
tk-o marked this conversation as resolved.
Outdated
- An API for accessing the metadata stored in ENSDb, including [metadata](/docs/services/ensdb/concepts/glossary#indexing-metadata-context) about the indexing status from the [ENSDb Writer](/docs/services/ensdb/concepts/glossary#ensdb-writer) and [metadata](/docs/services/ensdb/concepts/glossary#indexing-metadata-context) about the overall [ENSNode stack of services](/docs/services) active in the ENSNode instance.
Comment thread
tk-o marked this conversation as resolved.
Outdated

<LinkCard
title="Learn more about ENSApi"
description="A reference implementation of ENSDb Reader, built by the NameHash team."
href="/docs/services/ensapi"
/>

### Other ENSDb Readers
Comment thread
tk-o marked this conversation as resolved.
Outdated

<LinkCard
Comment thread
tk-o marked this conversation as resolved.
title="Learn more about ensdb-cli"
description="A command-line interface for interacting with ENSDb."
href="/docs/integrate/integration-options/ensdb-cli"
/>

<LinkCard
title="Learn more about ENSEngine"
description="A push-based web service allowing to track ENS data changes in real-time."
Comment thread
tk-o marked this conversation as resolved.
Outdated
href="/docs/integrate/integration-options/ensengine"
/>

<LinkCard
title="Learn more about ENSAnalytics (coming soon)"
description="A web service that provides analytics and insights on ENS data."
href="#"
/>
Comment thread
tk-o marked this conversation as resolved.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Comment thread
tk-o marked this conversation as resolved.
Comment thread
tk-o marked this conversation as resolved.
Comment thread
tk-o marked this conversation as resolved.
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
---
title: ENSDb Writers (Indexers)
description: How to build indexers for ENSDb, using the ENSDb Writer specification.
Comment thread
tk-o marked this conversation as resolved.
Outdated
---

import { LinkCard } from "@astrojs/starlight/components";

An [ENSDb Writer](/docs/services/ensdb/concepts/glossary#ensdb-writer) defines how an indexing process for ENS looks like, including:
Comment thread
lightwalker-eth marked this conversation as resolved.
Outdated
Comment thread
lightwalker-eth marked this conversation as resolved.
Outdated
Comment thread
tk-o marked this conversation as resolved.
Outdated

- How to source onchain data about ENS (events, blocks, etc.)
- How to process onchain data into an indexed data model (including transforming raw onchain data into a desired internal data model).
- How to store that processed data in the [ENSDb instance](/docs/services/ensdb/concepts/glossary#ensdb-instance).
- How to store metadata about the [ENSDb Writer](/docs/services/ensdb/concepts/glossary#ensdb-writer) in the [ENSDb instance](/docs/services/ensdb/concepts/glossary#ensdb-instance).
Comment thread
tk-o marked this conversation as resolved.
Outdated

:::tip[Build your own ENSDb Writer]
You can build your own ENSDb Writer in any language, using any indexing framework, as long as you follow the [ENSDb Standard](/docs/services/ensdb/concepts/glossary#ensdb-standard). The ENSDb Standard defines rules and constraints for how an ENSDb Writer should write data into an ENSDb instance in a way that maintains the integrity of the data and supports interoperability with any ENSDb Reader.

Your ENSDb Writer must include:

- The _implementation_ of 1 or more standards-compliant [ENSNode plugins](/docs/integrate/integration-options/ensnode-plugins).
- The _implementation_ of an [ENSDb Metadata Writer](/docs/services/ensdb/concepts/glossary#ensdb-metadata-writer) that stores [metadata](/docs/services/ensdb/concepts/glossary#indexing-metadata-context) about the [ENSDb Writer](/docs/services/ensdb/concepts/glossary#ensdb-writer) overall, including which [ENSNode Plugins](/docs/integrate/integration-options/ensnode-plugins) it has activated, what the status of indexing is across each indexed chain, etc.
Comment thread
tk-o marked this conversation as resolved.

:::

## Standards-compliant ENSDb Writers
Comment thread
tk-o marked this conversation as resolved.
Outdated

### ENSIndexer

[ENSIndexer](/docs/services/ensindexer) is a reference implementation of an [ENSDb Writer](/docs/services/ensdb/concepts/glossary#ensdb-writer) built by the NameHash team. It is a multi-chain ENS indexer built on top of [Ponder](https://ponder.sh/), a modular blockchain indexing framework. ENSIndexer processes events from each relevant chain and transforms the data, storing it in your ENSDb instance.
Comment thread
tk-o marked this conversation as resolved.
Outdated

<LinkCard
title="Learn more about ENSIndexer"
description="A reference implementation of ENSDb Writer, built by the NameHash team."
href="/docs/services/ensindexer"
/>

### Envio

The [Envio](https://envio.dev/) team is actively collaborating with NameHash Labs to build another standards-compliant [ENSDb Writer](/docs/services/ensdb/concepts/glossary#ensdb-writer) that uses Envio as the indexing engine. Their initial plugin is `subgraph`, with plans to support `unigraph` and `protocol-acceleration` after that.
Comment thread
tk-o marked this conversation as resolved.
Outdated

## Other Potential ENSDb Writers
Comment thread
tk-o marked this conversation as resolved.
Outdated

### Amp (Edge & Node)
Comment thread
tk-o marked this conversation as resolved.

[Amp](https://www.edgeandnode.com/articles/stream-live-chain-data-into-your-analytics-stack-with-amp) by [Edge & Node](https://www.edgeandnode.com) is a next-generation blockchain data platform that transforms onchain activity into structured, verifiable datasets — preserving full cryptographic provenance for compliance and auditability. Amp can stream live onchain data, including live ENS state, making it a perfect foundation for a new production-grade ENSDb Writer implementation.
Comment thread
tk-o marked this conversation as resolved.
Outdated

### Build Your Own

You can build your own ENSDb Writer in any language, using any indexing framework, as long as you follow the [ENSDb Standard](/docs/services/ensdb/concepts/glossary#ensdb-standard). Join us on [Telegram](https://t.me/ensnode) for any questions and support.
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,9 @@ import EnsDbUseCases from "@components/molecules/EnsDbUseCases.astro";

For special use cases that go beyond what the ENS Omnigraph exposes — you can query the live onchain state of both **ENSv1 and ENSv2** directly via `SQL`.

**ENSDb** is a bi-directional integration standard for any EnsDbWriter and EnsDbReader implementations to coordinate around the live unified onchain state of ENSv1 **and ENSv2** in a carefully-crafted standardized data model within a PostgreSQL database. Because ENSDb builds on Postgres, you can use _any_ language with a Postgres driver — **TypeScript**, **Python**, **Rust**, **Go**, and more.
**ENSDb** is a bi-directional integration standard for any ENSDb Writer and ENSDb Reader implementations to coordinate around the live unified onchain state of ENSv1 **and ENSv2** in a carefully-crafted standardized data model within a PostgreSQL database. Because ENSDb builds on Postgres, you can use _any_ language with a Postgres driver — **TypeScript**, **Python**, **Rust**, **Go**, and more.
Comment thread
tk-o marked this conversation as resolved.
Outdated

The [ENSDb standard](/docs/services/ensdb/concepts/glossary#ensdb-standard) also defines _the abstract specification_ for how [ENSDb Writers](/docs/integrate/integration-options/ensdb-writers) store their [metadata](/docs/services/ensdb/concepts/glossary#indexing-metadata-context) in an [ENSDb instance](/docs/services/ensdb/concepts/glossary#ensdb-instance) in a manner that supports decoupling and interop with any of [ENSDb Readers](/docs/integrate/integration-options/ensdb-readers).
Comment thread
tk-o marked this conversation as resolved.
Outdated

:::tip[Coming soon: ensdb-cli & ENSDb snapshots]
We're building [**`ensdb-cli` & ENSDb snapshots**](/docs/integrate/integration-options/ensdb-cli) so you can pull down a fresh ENSDb in minutes instead of paying for a full historical RPC backfill among many other benefits.
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
---
title: ENSNode Plugins
description: How to customize data models for ENSNode, using the ENSNode Plugin specification.
---

import { LinkCard } from "@astrojs/starlight/components";

## What is an ENSNode Plugin?

An **ENSNode Plugin** is an abstract specification that defines how a specific aspect of the ENS namespace is indexed into [ENSDb](/docs/services/ensdb). It is **not** an implementation — it is a standard that any [ENSDb Writer](/docs/services/ensdb/concepts/glossary#ensdb-writer) can implement.
Comment thread
tk-o marked this conversation as resolved.
Outdated

Each ENSNode Plugin defines:

- **Name** — e.g. `unigraph`, `protocol-acceleration`, `subgraph`.
- **Datasources** — which onchain contracts should be indexed, as a function of the ENS namespace.
Comment thread
tk-o marked this conversation as resolved.
Outdated
- **Dependency relationships** — other plugins that must (or must not) be activated concurrently.
- **Indexed data model** — the tables, columns, and indexes that the plugin produces in ENSDb.
Comment thread
tk-o marked this conversation as resolved.
Outdated
- **Standards and invariants** — rules for how onchain events are translated into the indexed data model during indexing.
Comment thread
tk-o marked this conversation as resolved.
Outdated
- **Versioning** — a version number that can be stored in ENSNode Metadata, to track which version of the plugin implementation is being used by ENSDb Writers and ENSDb Readers.
Comment thread
tk-o marked this conversation as resolved.
Outdated

## Why ENSNode Plugins Matter

ENSNode Plugins are the key architectural piece that enables a decoupling between [ENSDb Writers](/docs/services/ensdb/concepts/glossary#ensdb-writer) and [ENSDb Readers](/docs/services/ensdb/concepts/glossary#ensdb-reader), so that anyone can create their own implementations of these. For example, any team working on indexing infrastructure can implement an ENSDb Writer and have it produce a standards-compliant ENSDb. On the other hand, any team working on products for ENS ecosystem can build their own standards-compliant ENSDb Reader and have it query ENSDb.
Comment thread
tk-o marked this conversation as resolved.
Outdated

:::note[Interoperability between ENSDb Writers and Readers]
When new ENSNode plugins are created, it becomes possible for the [ENS Omnigraph API](/docs/integrate/omnigraph) (or other APIs built by any ENSDb Reader) to unify the ability to query across ENSNode plugins in a single query. For example, you could query both ENS state from the `unigraph` and EFP state about followers from the `efp` plugin in a single GraphQL query.
Comment thread
tk-o marked this conversation as resolved.
Outdated
:::

## Core Plugins
Comment thread
tk-o marked this conversation as resolved.
Outdated

[ENSIndexer](/docs/services/ensindexer) is a reference implementation of an [ENSDb Writer](/docs/services/ensdb/concepts/glossary#ensdb-writer) that implements multiple core plugins following the ENSNode Plugins specification. The code for each plugin inside ENSIndexer is a reference implementation of that plugin's abstract specification. [The core plugins implemented in ENSIndexer today](https://github.com/namehash/ensnode/tree/main/apps/ensindexer/src/plugins) are:
Comment thread
tk-o marked this conversation as resolved.
Outdated

:::note[Built by the NameHash team]
All core ENSNode Plugins are built by the NameHash team. [We welcome contributions and collaborations to expand the ecosystem of plugins](#build-your-own).
:::

Comment thread
tk-o marked this conversation as resolved.
Outdated
| Plugin | Description |
| ----------------------- | ---------------------------------------------------------- |
| `unigraph` | Unified ENSv1 + ENSv2 data model with polymorphic entities |
| `protocol-acceleration` | Accelerated lookups for ENS resolution |
| `subgraph` | Legacy ENS Subgraph-compatible data model |
| `basenames` | Basenames (`.base.eth`) subname indexing |
| `lineanames` | Lineanames (`.linea.eth`) subname indexing |
| `threedns` | 3DNS (`.box`) name indexing |
| `registrars` | Registration and renewal lifecycle tracking |
| `tokenscope` | NFT tokenization and marketplace activity |
Comment thread
tk-o marked this conversation as resolved.
Outdated

## Community Plugins
Comment thread
tk-o marked this conversation as resolved.
Outdated

### Under Development

The `efp` plugin is [a new plugin currently under development](https://github.com/Quantumlyy/efpnode/tree/main/packages/ensnode-plugin-efp) by the [EthId team](https://ethid.org/):
Comment thread
tk-o marked this conversation as resolved.
Outdated

- [EFP (Ethereum Follow Protocol)](https://efp.app/) — onchain social graph protocol
- [Grails](https://grails.app/) — by the EthId Foundation
Comment thread
tk-o marked this conversation as resolved.
Outdated

### Build Your Own

If you are interested in defining a new ENSNode plugin or implementing an existing one, reach out to the NameHash Labs team — we are happy to provide support and additional info. Join us on [Telegram](https://t.me/ensnode) for any questions.

## Related

<LinkCard
title="ENSDb Writers"
description="Learn how to build indexers that implement ENSNode plugins."
href="/docs/integrate/integration-options/ensdb-writers"
/>

<LinkCard
title="ENSDb Readers"
description="Learn how to build APIs that read from ENSNode plugins."
Comment thread
tk-o marked this conversation as resolved.
Outdated
href="/docs/integrate/integration-options/ensdb-readers"
/>
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,34 @@ For special use cases that go beyond what the ENS Omnigraph exposes, query the l
href="/docs/integrate/integration-options/ensdb"
/>

## 5. enscli
## 5. ENSDb Writers

Build your own indexer for ENSDb by implementing the [ENSNode Plugin](/docs/integrate/integration-options/ensnode-plugins) specification. ENSDb Writers index onchain ENS data and write it into an ENSDb instance.
Comment thread
tk-o marked this conversation as resolved.
Outdated

<LinkCard
title="ENSDb Writers Documentation"
Comment thread
tk-o marked this conversation as resolved.
Outdated
href="/docs/integrate/integration-options/ensdb-writers"
/>

## 6. ENSDb Readers

Build custom APIs on top of ENSDb. ENSDb Readers query indexed ENS data from an ENSDb instance and serve it through any API surface (GraphQL, REST, gRPC, etc.).
Comment thread
tk-o marked this conversation as resolved.
Outdated

<LinkCard
title="ENSDb Readers Documentation"
Comment thread
tk-o marked this conversation as resolved.
Outdated
href="/docs/integrate/integration-options/ensdb-readers"
/>

## 7. ENSNode Plugins

ENSNode Plugins are abstract specifications that define indexed data models for ENS. They are the key architectural piece that enables decoupling between ENSDb Writers and ENSDb Readers.
Comment thread
tk-o marked this conversation as resolved.
Outdated

<LinkCard
title="ENSNode Plugins Documentation"
href="/docs/integrate/integration-options/ensnode-plugins"
/>

## 8. enscli

`enscli` is a CLI that wraps `enssdk` to bring the ENS Omnigraph to the terminal. Designed for developers exploring or validating integrations, operators wiring ENS lookups into shell pipelines, and AI coding agents driving `ensskills`.

Expand All @@ -54,7 +81,7 @@ For special use cases that go beyond what the ENS Omnigraph exposes, query the l
href="/docs/integrate/integration-options/enscli"
/>

## 6. ensskills
## 9. ensskills

`ensskills` is a collection of curated skill bundles that give AI coding agents a well-defined contract for working with ENS — powering conversational ENS lookups and streamlining integration code written with `enskit`, `enssdk`, or the raw Omnigraph API.

Expand All @@ -63,7 +90,7 @@ For special use cases that go beyond what the ENS Omnigraph exposes, query the l
href="/docs/integrate/integration-options/ensskills"
/>

## 7. ensdb-cli & ENSDb snapshots
## 10. ensdb-cli & ENSDb snapshots

`ensdb-cli` is the operator-facing tool for ENSDb snapshots — portable, versioned packages of an ENSDb instance. Pull one down, restore it into Postgres, and start querying ENS in minutes instead of waiting days to complete a full historical indexing backfill from scratch.

Expand All @@ -72,7 +99,7 @@ For special use cases that go beyond what the ENS Omnigraph exposes, query the l
href="/docs/integrate/integration-options/ensdb-cli"
/>

## 8. ENSEngine
## 11. ENSEngine

ENSEngine watches your ENSDb for changes in real time and delivers ENS-aware events — including webhooks — to any sink you configure. Stop polling and start reacting to ENS state changes.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ query Namegraph {

The **Unigraph** is the entire collection of these disjoint ENSv2 Namegraphs and multiple ENSv1 Nametables, combined together into a single unified data model using ENS Resolution semantics. Navigating the Unigraph from `"eth"` down to `"vitalik.eth"` and beyond looks identical regardless of whether the underlying entities are ENSv1 or ENSv2.

The [`unigraph` plugin](/docs/services/ensindexer) in ENSIndexer is what builds this unified model. The Unigraph constructs two Namegraphs, one rooted at the ENSv1 Root Registry and another rooted at the ENSv2 Root Registry. It's also where multichain coverage lives: Basenames (`.base.eth`), Lineanames (`.linea.eth`), and 3DNS names (`.box`) are all stitched into the ENSv1 Namegraph.
The `unigraph` [ENSNode plugin](/docs/integrate/integration-options/ensnode-plugins), implemented in [ENSIndexer](/docs/services/ensindexer), is what builds this unified model. The Unigraph constructs two Namegraphs, one rooted at the ENSv1 Root Registry and another rooted at the ENSv2 Root Registry. It's also where multichain coverage lives: Basenames (`.base.eth`), Lineanames (`.linea.eth`), and 3DNS names (`.box`) are all stitched into the ENSv1 Namegraph.
Comment thread
tk-o marked this conversation as resolved.
Outdated

```mermaid
flowchart TD
Expand Down
Loading
Loading