Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
5 changes: 1 addition & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,7 @@ Thank you for your interest in contributing to ENSNode! We welcome contributions

## Documentation

For detailed contribution guidelines and setup instructions:

- **ENSNode**: Visit [ENSNode Contributing Guide](https://ensnode.io/docs/contributing)
- **ENSRainbow**: Visit [ENSRainbow Contributing Guide](https://ensnode.io/ensrainbow/contributing)
For detailed setup instructions, visit the [ENSNode Contributing Guide](https://ensnode.io/docs/reference/contributing).

## Getting Help

Expand Down
179 changes: 22 additions & 157 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,87 +19,37 @@

# ENSNode

<a href="https://ensnode.io" target="_blank">ENSNode</a> is the new multichain indexer for ENS, including [ENSv2](https://roadmap.ens.domains/roadmap/).

Full Documentation ➡︎ <a href="https://ensnode.io" target="_blank">ensnode.io</a>

[Join us on Telegram](https://t.me/ensnode) to get support, share ideas, and discuss the future of ENSNode.

## The future of ENS indexing

ENSNode provides enhanced ENS indexing capabilities beyond the ENS Subgraph, including faster indexing and simpler self-hosted deployments. Initial multichain capabilities include indexing mainnet, Basenames, Lineanames, 3DNS, and more, providing a unified multichain namespace via a subgraph-compatible GraphQL API. When exclusively activating our subgraph plugin, ENSNode has full data equivalency with the ENS Subgraph.

- Multichain ENS Namespace
- flattened, unified, multichain and multiregistrar namespace via optional plugins
- ✅ All names added to the ENS Registry and the ENS NameWrapper
- ✅ All direct subnames of .eth
- ✅ [Basenames](https://www.base.org/names) (`.base.eth`)
- ✅ [Lineanames](https://names.linea.build/) (`.linea.eth`)
- ✅ [3DNS](https://3dns.box) Support (`.box`, `.xyz`, +more)
- 🚧 Offchain Names
- `.cb.id`, `.uni.id`, + more
- [NameStone](https://namestone.com/) Names
- [NameSpace](https://namespace.ninja/) Names
- [Justaname](https://www.justaname.id/) Names
- 🚧 + more
- Built on [Ponder](https://ponder.sh)
- ✅ Rapid Indexing & Backfill
- 10x faster than ENS Subgraph
- Mainnet Cached Backfill: **4.5 hours** on M1 Macbook Pro
- ✅ More efficient than ENS Subgraph
- 35x less disk space and 35% fewer RPC credits [[source]](https://ponder.sh/docs/why-ponder)
- ✅ End-to-end type safety
- ✅ Automatically reconciles chain reorganizations
- ✅ Deploy anywhere with Node.js & Docker
- Designed for web developers
- ✅ [use ENSNode with ENSjs](https://ensnode.io/docs/usage/with-ensjs)
- ✅ [GraphQL APIs](https://ensnode.io/docs/usage/api)
- ✅ Custom APIs for your app
- [1:1 Subgraph Compatibility](https://ensnode.io/docs/concepts/what-is-the-ens-subgraph)
- ✅ [100% data equivalency](https://github.com/namehash/ens-subgraph-transition-tools) as compared to Subgraph
- ✅ 100% ensjs test suites passing via [ens-test-env](https://github.com/namehash/ens-test-env)
- ✅ 100% ens-app-v3 test suites passing via [ens-test-env](https://github.com/namehash/ens-test-env)
- Own your ENSNode index
- ✅ [Deploy ENSNode to your own cloud](https://ensnode.io/docs/deploying) for controlling your own uptime guarantees and private queries

## Why Index ENS? Why ENSNode?

The ENS protocol enables resolution of names across multiple chains and, increasingly, offchain data sources. ENS smart contracts optimize for some operations, but not others: for example, if you wanted to list all of a user's owned names, there's no practical way to do this through ENS contracts, and an indexer like ENSNode _must_ be used.

An indexer aggregates and reorganizes the representation of ENS's state to make important queries like that possible, efficient, and convenient:
[ENSNode](https://ensnode.io) is the full-stack development platform for [ENSv2](https://ens.domains/ensv2). Use ENSNode to achieve full ENSv2 readiness even before ENSv2 launches.

```graphql
# get all of a user's domains by address — not possible on-chain!
query Domains($adress: String!) {
domains(where: { owner: $address }) {
id
name
...
}
}
```

Historically the ENS Subgraph has served this purpose, but the Subgraph's limitations are increasingly severe as the ENS protocol grows: the ENS Subgraph can only index a single chain at a time (ex: mainnet) and can't integrate with names or that require [CCIP-Read](https://docs.ens.domains/resolvers/ccip-read), which includes all names stored on L2 chains or offchain.

Given how the majority of ENS names are now issued off of mainnet, only a small percentage of ENS names can be indexed by the ENS Subgraph. This issue will only grow more severe with the launch of [ENSv2](https://roadmap.ens.domains/roadmap/) and [Namechain](https://app.ens.domains/ens-v2).
The easiest way to get started is through the new **ENS Omnigraph API** — the world's first and only API to support querying the full state of both ENSv1 and ENSv2 in a single unified API.

ENSNode is a modern, multichain indexer for ENS. It supports backwards-compatible Subgraph queries and sets the stage for supporting [ENSv2](https://roadmap.ens.domains/roadmap/), in particular [Namechain](https://app.ens.domains/ens-v2) and the growing set of off-chain ENS names (like `.uni.eth` and `.cb.id`).
- 📚 **Docs:** [ensnode.io](https://ensnode.io)
- 🚀 **Quickstart:** [ensnode.io/docs/integrate](https://ensnode.io/docs/integrate)
- 💬 **Telegram:** [t.me/ensnode](https://t.me/ensnode)

## Documentation
## Example: query the subnames of '.eth' via the ENS Omnigraph API

Documentation for the ENSNode suite of apps is available at [ensnode.io](https://ensnode.io).
Note that substantial ENS data is not directly queryable through traditional smart contract RPC calls. Examples include: the subnames of a name, or the names owned by an address. ENSNode is the world's first and only solution that makes the full set of ENS data spanning both ENSv1 and ENSv2 accessible through a single unified API.

## Running with Docker

```bash
docker compose -f docker/docker-compose.yml up -d
```graphql
query HelloWorld {
domain(by: { name: "eth" }) {
__typename
canonical { name { interpreted } }
owner { address }
subdomains(first: 20) {
totalCount
edges { node { __typename canonical { name { interpreted } } owner { address } } }
}
}
}
```

See [`docker/README.md`](docker/README.md) for all use cases and commands.
To get started with ENSNode and the ENS Omnigraph API, follow the [Quickstart](https://ensnode.io/docs/integrate).

## Contributions
## Contributing

We welcome community contributions and feedback—please see [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
See [CONTRIBUTING.md](CONTRIBUTING.md).

## Sponsors

Expand All @@ -110,93 +60,8 @@ NameHash has received generous support from the [ENS DAO](https://ensdao.org/) a
<a href="https://www.gitcoin.co/" target="_blank" style="text-decoration: none;"><img src="./docs/ensnode.io/public/gitcoin.png" width="180"></a>
</p>

## Contact Us

Visit our [website](https://namehashlabs.org/) to get in contact, or [join us on Telegram](https://t.me/ensnode).

## License

Licensed under the MIT License, Copyright © 2025-present [NameHash Labs](https://namehashlabs.org).

See [LICENSE](./LICENSE) for more information.

## Repo Overview

The ENSNode monorepo contains multiple modules in the following subdirectories:

- [`apps`](apps) executable applications.
- [`packages`](packages) for libraries that can be embedded into apps.
- [`docs`](docs) documentation sites.

### [`apps/ensadmin`](apps/ensadmin)

<table>
<tr>
<td><img alt="ENSadmin" src=".github/assets/ensadmin-light.svg" width="auto" height="44"></td>
<td><a href="https://ensnode.io/ensadmin" target="_blank">ENSAdmin</a></td>
</tr>
</table>

ENSAdmin is a dashboard for ENSNode and the ENS protocol. See the [ENSAdmin documentation](https://ensnode.io/ensadmin) for more details.

### [`apps/ensindexer`](apps/ensindexer)

<table>
<tr>
<td><img alt="ENSIndexer" src=".github/assets/ensindexer-light.svg" width="auto" height="44"></td>
<td><a href="https://ensnode.io/ensindexer" target="_blank">ENSIndexer</a></td>
</tr>
</table>

ENSIndexer is a Ponder-powered indexer for ENS across multiple chains. See the [ENSIndexer documentation](https://ensnode.io/ensindexer) for more details.

### [`apps/ensrainbow`](apps/ensrainbow)

<table>
<tr>
<td><img alt="ENSRainbow" src=".github/assets/ensrainbow-light.svg" width="auto" height="44"></td>
<td><a href="https://ensnode.io/ensrainbow" target="_blank">ENSRainbow</a></td>
</tr>
</table>

ENSRainbow heals unknown ENS names: it provides a simple API to recover labels from their labelHashes. See the [ENSRainbow documentation](https://ensnode.io/ensrainbow) for more details.

## Packages

### [`packages/ensdb-sdk`](packages/ensdb-sdk)

Software Development Kit for interacting with data in ENSDb.

### [`packages/ensnode-sdk`](packages/ensnode-sdk)

Software Development Kit for interacting with ENSNode services and data. Includes common utilities used across ENSNode applications.

### [`packages/datasources`](packages/datasources)

Convenient catalog of ENSNode-related datasources including chain, contract addresses, start blocks, and event filters.

### [`packages/ensrainbow-sdk`](packages/ensrainbow-sdk)

TypeScript library for interacting with the [ENSRainbow API](apps/ensrainbow).

### [`packages/ponder-sdk`](packages/ponder-sdk)

A utility library for interacting with Ponder apps and data.

### [`packages/ponder-subgraph`](packages/ponder-subgraph)

Subgraph-compatible GraphQL API.

### [`packages/shared-configs`](packages/shared-configs)

Shared internal configuration files.

## Docs

### [`docs/ensnode.io`](docs/ensnode.io/)

Astro/Starlight documentation app for ENSNode, ENSIndexer, ENSAdmin, and ENSRainbow.

### [`docs/ensrainbow.io`](docs/ensrainbow.io/)

Landing page for ENSRainbow.
7 changes: 6 additions & 1 deletion docs/ensnode.io/astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,6 @@ export default defineConfig({
"/docs": "/docs/integrate",
"/ensnode": "/docs/integrate",
"/ensnode/deploying/railway": "/docs/services/ensrainbow/deploying/railway",
"/ensnode/concepts/what-is-ensnode": "/docs/reference/what-is-ensnode",
"/ensnode/concepts/what-is-the-ens-subgraph":
Comment on lines 38 to 39
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Orphaned legacy URL after redirect chain was broken

The redirect from /ensnode/concepts/what-is-ensnode to /docs/reference/what-is-ensnode was removed in this PR. A new redirect for /docs/reference/what-is-ensnode/docs/integrate/why-ensnode was added, but Astro static redirects are one-hop and do not chain. Any existing links pointing to /ensnode/concepts/what-is-ensnode (from external sites, blog posts, or social media) will now 404 instead of resolving through the chain to the new page. Adding a direct redirect for that URL would close the gap.

"/docs/reference/subgraph-legacy/what-is-the-ens-subgraph",
"/docs/reference/what-is-the-ens-subgraph":
Expand All @@ -53,6 +52,12 @@ export default defineConfig({
"/ensrainbow/concepts/label-sets-and-versioning":
"/docs/services/ensrainbow/concepts/label-sets-and-versioning",
"/docs/reference/rest-api": "/docs/services/ensapi/reference/api-reference",
"/docs/integrate/hosted-instances": "/docs/hosted-instances",
Comment thread
lightwalker-eth marked this conversation as resolved.
Comment thread
shrugs marked this conversation as resolved.
Comment thread
shrugs marked this conversation as resolved.
"/docs/integrate/migrate-from-subgraph": "/docs/integrate/ensv2-readiness",
"/docs/reference/ensnode-v2-notes": "/docs/integrate/ensv2-readiness",
"/docs/reference/mainnet-registered-subnames-of-subregistries": "/docs/integrate/omnigraph",
"/docs/reference/roadmap": "/docs/integrate/ensv2-readiness",
"/docs/reference/what-is-ensnode": "/docs/integrate/why-ensnode",
},
env: {
schema: {
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
export const hostedInstancesSidebarTopic = {
label: "Hosted Instances",
link: "/docs/hosted-instances",
icon: "cloud-download",
items: [
{
label: "Hosted Instances",
collapsed: false,
items: [
{ label: "v2 Sepolia", link: "/docs/hosted-instances#ensnode-v2-sepolia" },
{ label: "Alpha", link: "/docs/hosted-instances#ensnode-alpha" },
{ label: "Alpha-Sepolia", link: "/docs/hosted-instances#ensnode-alpha-sepolia" },
{ label: "Mainnet", link: "/docs/hosted-instances#ensnode-mainnet" },
{ label: "Sepolia", link: "/docs/hosted-instances#ensnode-sepolia" },
],
},
Comment thread
lightwalker-eth marked this conversation as resolved.
],
};
Original file line number Diff line number Diff line change
@@ -1,13 +1,15 @@
import type { StarlightSidebarTopicsUserConfig } from "starlight-sidebar-topics";

import { hostedInstancesSidebarTopic } from "./hosted-instances";
import { integrateSidebarTopic } from "./integrate";
import { servicesSidebarTopic } from "./services";
import { referenceSidebarTopic } from "./reference";
import { selfHostSidebarTopic } from "./self-host";

export const starlightSidebarTopicsConfig = [
integrateSidebarTopic,
hostedInstancesSidebarTopic,
selfHostSidebarTopic,
referenceSidebarTopic,
servicesSidebarTopic,
referenceSidebarTopic,
] satisfies StarlightSidebarTopicsUserConfig;
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ export const integrateSidebarTopic = {
},
{
label: "Examples",
collapsed: false,
collapsed: true,
items: [
{
label: "Overview",
Expand Down Expand Up @@ -153,14 +153,6 @@ export const integrateSidebarTopic = {
},
],
},
{
label: "Migrate from ENS Subgraph",
link: "/docs/integrate/migrate-from-subgraph",
},
{
label: "Hosted Instances",
link: "/docs/integrate/hosted-instances",
},
{
label: "AI / LLM Tooling",
link: "/docs/integrate/ai-llm",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,22 +11,6 @@ export const referenceSidebarTopic = {
label: "Terminology",
link: "/docs/reference/terminology",
},
{
label: "Roadmap",
link: "/docs/reference/roadmap",
},
{
label: "What is ENSNode?",
link: "/docs/reference/what-is-ensnode",
},
{
label: "ENSNode V2 Notes",
link: "/docs/reference/ensnode-v2-notes",
},
{
label: "Mainnet Subnames of Subregistries",
link: "/docs/reference/mainnet-registered-subnames-of-subregistries",
},
{
label: "Subgraph API (Legacy)",
collapsed: true,
Expand Down
Loading
Loading