From c17e423a682b1586cc876040329ad1d88b75c8da Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Tue, 12 May 2026 16:33:25 +0200 Subject: [PATCH 01/13] Refine "Hosted Instances" page --- .../docs/docs/integrate/hosted-instances.mdx | 53 ++++++++++--------- 1 file changed, 29 insertions(+), 24 deletions(-) diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx index 28ad82e245..4e79a6d7f4 100644 --- a/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx +++ b/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx @@ -13,14 +13,33 @@ NameHash Labs provides freely available hosted instances for ENS developers look These instances are provided free of charge with no API key required, have no rate limiting, and are maintained and monitored by the NameHash Labs team. -:::caution[No Uptime / Performance Guarantees] -These hosted instances are provided free of charge to the ENS community, and while we strive for strong uptime and performance, neither of these can be guaranteed. By using these instances you accept the possibility of downtime, degraded performance, or other unforeseen events. If you'd like to run ENSNode in production, consider [hosting your own ENSNode instance](/docs/self-host). -::: +### Available instance configurations -## Available ENSNode Instances +Each ENSNode hosted instance is configured for a specific ENS namespace and activated ENSNode plugins. The ENS namespace is the source of truth for the data indexed by the instance, and the activated ENSNode plugins determine the specific data model for indexing and querying. + +Each ENS namespace is defined by onchain state as per implemented ENS protocol version (i.e. ENS V1, ENS V2). Currently, ENSNode supports the following ENS namespaces: +- ENS V2 Sepolia +- ENS V1 Mainnet +- ENS V1 Sepolia + +### ENS V2 instances + +These instances demonstrate the latest ENS V2 support in ENSNode. + +#### ENSNode 'v2 Sepolia' + + + +## ENS V1 Instances + +These instances demonstrate the ENS V1 support in ENSNode. -The key differences between these hosted deployments is the ENS deployment being indexed (mainnet vs a testnet) and the list of ENSNode plugins that are activated. See the table below for details. -Main difference from client perspective is chain being indexed and list of plugins being handled. Here is the table listing differences between those. ### Alpha-style Deployments @@ -32,8 +51,8 @@ These ENSNode instances focus on pushing the boundaries of what's possible with instanceURL="https://api.alpha.ensnode.io" connectWithENSAdminURL="https://admin.ensnode.io/connection?connection=https%3A%2F%2Fapi.alpha.ensnode.io" namespace="mainnet" - plugins="subgraph, basenames, lineanames, threedns, protocol-acceleration, registrars" - purpose="Demonstration of ENSNode's multichain ENS indexing capability for the ENS namespace rooted on Mainnet. Provides a superset of the data indexed by the ENS Subgraph. Offers a preview of ENS Protocol Acceleration." + plugins="subgraph, basenames, lineanames, threedns, ensv2, protocol-acceleration, registrars, tokenscope" + purpose="Demonstration of ENSNode's multichain ENS indexing capability for the ENS V1 namespace rooted on Mainnet. Provides a superset of the data indexed by the ENS Subgraph. Offers a preview of ENS Protocol Acceleration." /> #### ENSNode 'Alpha-Sepolia' @@ -42,8 +61,8 @@ These ENSNode instances focus on pushing the boundaries of what's possible with instanceURL="https://api.alpha-sepolia.ensnode.io" connectWithENSAdminURL="https://admin.ensnode.io/connection?connection=https%3A%2F%2Fapi.alpha-sepolia.ensnode.io" namespace="sepolia" - plugins="subgraph, basenames, lineanames, protocol-acceleration, registrars" - purpose="Demonstration of ENSNode's multichain ENS indexing capability for the ENS namespace rooted on Sepolia. Provides a superset of the data indexed by the ENS Subgraph. Offers a preview of ENS Protocol Acceleration." + plugins="subgraph, basenames, lineanames, registrars, ensv2,protocol-acceleration" + purpose="Demonstration of ENSNode's multichain ENS indexing capability for the ENS V1 namespace rooted on Sepolia. Provides a superset of the data indexed by the ENS Subgraph. Offers a preview of ENS Protocol Acceleration." /> ### Subgraph-style Deployments @@ -70,20 +89,6 @@ These ENSNode instances focus on maximizing backwards compatibility with the ENS purpose="Demonstration of ENSNode's backwards compatibility with the ENS Subgraph. Provides 1:1 Subgraph compatible data on Sepolia." /> -### ENS V2 Deployments - -These instances demonstrate the latest ENSv2 support in ENSNode. - -#### ENSNode 'v2 Sepolia' - - - ## Endpoints For more details on how to use these instances, refer to the [ENSNode Quickstart](/docs/integrate). From df105bf5b72fb76baa5020f4cd98cf1cd612bb6f Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Tue, 12 May 2026 16:38:24 +0200 Subject: [PATCH 02/13] Link "Building ENSNode Docker Images" from "Self-host: Docker" page --- docs/ensnode.io/src/content/docs/docs/self-host/docker.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/docker.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/docker.mdx index 9123f81279..908e0c92a7 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/docker.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/docker.mdx @@ -61,6 +61,12 @@ docker compose -f docker/docker-compose.devnet.yml up -d href="https://github.com/namehash/ensnode/blob/main/docker" /> + + :::note[Port Mappings] Note that while the default `docker/docker-compose.yml` exposes each container's port to the host machine (useful for development), you may only wish to expose ENSApi's `4334` and avoid exposing services like ENSRainbow, ENSAdmin, and Postgres to the wider internet. ::: From 3ace0a4431a8cd054939951a8b6353cc4dfbc48e Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Tue, 12 May 2026 16:53:24 +0200 Subject: [PATCH 03/13] Update content regarding Subgraph --- .../starlight/sidebar-topics/reference.ts | 20 +++--- .../src/content/docs/docs/reference/index.mdx | 1 - .../content/docs/docs/reference/rest-api.mdx | 55 ---------------- .../subgraph-legacy/subgraph-api.mdx | 63 +++++++++++++++++++ .../subgraph-compatibility-tooling.mdx | 0 .../what-is-the-ens-subgraph.mdx | 2 +- 6 files changed, 76 insertions(+), 65 deletions(-) create mode 100644 docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/subgraph-api.mdx rename docs/ensnode.io/src/content/docs/docs/reference/{ => subgraph-legacy}/subgraph-compatibility-tooling.mdx (100%) rename docs/ensnode.io/src/content/docs/docs/reference/{ => subgraph-legacy}/what-is-the-ens-subgraph.mdx (99%) diff --git a/docs/ensnode.io/config/integrations/starlight/sidebar-topics/reference.ts b/docs/ensnode.io/config/integrations/starlight/sidebar-topics/reference.ts index 3dfa5ce0a7..7903cbfba5 100644 --- a/docs/ensnode.io/config/integrations/starlight/sidebar-topics/reference.ts +++ b/docs/ensnode.io/config/integrations/starlight/sidebar-topics/reference.ts @@ -19,10 +19,6 @@ export const referenceSidebarTopic = { label: "What is ENSNode?", link: "/docs/reference/what-is-ensnode", }, - { - label: "What is the ENS Subgraph?", - link: "/docs/reference/what-is-the-ens-subgraph", - }, { label: "REST API", link: "/docs/reference/rest-api", @@ -35,10 +31,6 @@ export const referenceSidebarTopic = { label: "ENSNode V2 Notes", link: "/docs/reference/ensnode-v2-notes", }, - { - label: "Subgraph Compatibility", - link: "/docs/reference/subgraph-compatibility-tooling", - }, { label: "Indexing ENS-Compatible Names", link: "/docs/reference/indexing-ens-compatible-onchain-names", @@ -51,6 +43,18 @@ export const referenceSidebarTopic = { label: "Subgraph API (Legacy)", collapsed: true, items: [ + { + label: "What is the ENS Subgraph?", + link: "/docs/reference/subgraph-legacy/what-is-the-ens-subgraph", + }, + { + label: "Subgraph API", + link: "/docs/reference/subgraph-legacy/subgraph-api", + }, + { + label: "Subgraph Compatibility Tooling", + link: "/docs/reference/subgraph-legacy/subgraph-compatibility-tooling", + }, { label: "With ENSjs", link: "/docs/reference/subgraph-legacy/with-ensjs", diff --git a/docs/ensnode.io/src/content/docs/docs/reference/index.mdx b/docs/ensnode.io/src/content/docs/docs/reference/index.mdx index ca7946f2d3..24d8847435 100644 --- a/docs/ensnode.io/src/content/docs/docs/reference/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/reference/index.mdx @@ -14,6 +14,5 @@ Go deeper into mastery of ENSNode, including terminology and becoming an active - diff --git a/docs/ensnode.io/src/content/docs/docs/reference/rest-api.mdx b/docs/ensnode.io/src/content/docs/docs/reference/rest-api.mdx index ec9b423c4f..2f4655c3fc 100644 --- a/docs/ensnode.io/src/content/docs/docs/reference/rest-api.mdx +++ b/docs/ensnode.io/src/content/docs/docs/reference/rest-api.mdx @@ -7,61 +7,6 @@ sidebar: import { LinkCard } from "@astrojs/starlight/components"; -## Subgraph API -ENSNode exposes a Subgraph-Compatible GraphQL endpoint at `/subgraph`. - -:::note[Subgraph API Compatibility Reference] -For details on subgraph compatibility, see the Subgraph Compatibility documentation. - - -::: - -### GraphiQL Playground - -To explore the schema and run queries, use the GraphiQL Playground below. - - - -### GraphQL Examples - -Fetch data about the three most recently-created domains. - -```gql -{ - domains(orderBy: createdAt, orderDirection: desc, first: 3) { - name - expiryDate - } -} -``` - -```json -{ - "data": { - "domains": [ - { - "name": "ensanguo.eth", - "expiryDate": "1758170255" - }, - { - "name": "fiffer.eth", - "expiryDate": "2041994243" - }, - { - "name": "rifaisicilia.eth", - "expiryDate": "1758170039" - } - ] - } -} -``` - ## Config API The Config API provides a complete view of an ENSNode instance's public diff --git a/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/subgraph-api.mdx b/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/subgraph-api.mdx new file mode 100644 index 0000000000..6b7450084c --- /dev/null +++ b/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/subgraph-api.mdx @@ -0,0 +1,63 @@ +--- +title: Subgraph API +sidebar: + order: 2 +--- + +import { LinkCard } from "@astrojs/starlight/components"; + +## Subgraph API +ENSNode exposes a Subgraph-Compatible GraphQL endpoint at `/subgraph`. + +:::note[Subgraph API Compatibility Reference] +For details on subgraph compatibility, see the Subgraph Compatibility documentation. + + +::: + +### GraphiQL Playground + +To explore the schema and run queries, use the GraphiQL Playground below. + + + +### GraphQL Examples + +Fetch data about the three most recently-created domains. + +```gql +{ + domains(orderBy: createdAt, orderDirection: desc, first: 3) { + name + expiryDate + } +} +``` + +```json +{ + "data": { + "domains": [ + { + "name": "ensanguo.eth", + "expiryDate": "1758170255" + }, + { + "name": "fiffer.eth", + "expiryDate": "2041994243" + }, + { + "name": "rifaisicilia.eth", + "expiryDate": "1758170039" + } + ] + } +} +``` + diff --git a/docs/ensnode.io/src/content/docs/docs/reference/subgraph-compatibility-tooling.mdx b/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/subgraph-compatibility-tooling.mdx similarity index 100% rename from docs/ensnode.io/src/content/docs/docs/reference/subgraph-compatibility-tooling.mdx rename to docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/subgraph-compatibility-tooling.mdx diff --git a/docs/ensnode.io/src/content/docs/docs/reference/what-is-the-ens-subgraph.mdx b/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/what-is-the-ens-subgraph.mdx similarity index 99% rename from docs/ensnode.io/src/content/docs/docs/reference/what-is-the-ens-subgraph.mdx rename to docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/what-is-the-ens-subgraph.mdx index b58b72a8bc..ca3bc97969 100644 --- a/docs/ensnode.io/src/content/docs/docs/reference/what-is-the-ens-subgraph.mdx +++ b/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/what-is-the-ens-subgraph.mdx @@ -63,7 +63,7 @@ ENSNode has developed tooling to verify subgraph compatibility and ease migratio ## Subgraph-Compatible GraphQL API Reference From e6029155b6092587e14cde5b2ae6863b82b4d4f4 Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Tue, 12 May 2026 16:53:59 +0200 Subject: [PATCH 04/13] Remove references to "Registrar Actions API" --- .../content/docs/docs/reference/rest-api.mdx | 39 ------------------- 1 file changed, 39 deletions(-) diff --git a/docs/ensnode.io/src/content/docs/docs/reference/rest-api.mdx b/docs/ensnode.io/src/content/docs/docs/reference/rest-api.mdx index 2f4655c3fc..73f1d99173 100644 --- a/docs/ensnode.io/src/content/docs/docs/reference/rest-api.mdx +++ b/docs/ensnode.io/src/content/docs/docs/reference/rest-api.mdx @@ -175,42 +175,3 @@ When you include this parameter it influences the HTTP response code as follows: - **Success (200 OK)**: The latest indexed block of each chain is guaranteed within the requested distance from realtime. - **Service Unavailable (503)**: The latest indexed block of each chain is NOT guaranteed within the requested distance from realtime. - - -## Registrar Actions API - -Query the "logical registrar actions" performed on indexed -subregistries with the Registrar Actions API. This endpoint returns a list -of "logical registrar actions", such as "registration" or "renewal". - -Each "logical registrar action" refers to: -- ID of the action, -- type of the action, -- incremental duration, -- registrant address, -- one registration lifecycle record, -- pricing details (optionally), -- referral details (optionally), -- onchain transaction details (block number, timestamp, transaction hash), -- event IDs that have ever contributed to the "logical registrar action" record. - -Each registration lifecycle record refers to: -- subregistry that manages this Registration Lifecycle, -- node (namehash) of the FQDN of the domain the registration lifecycle is - associated with, -- expiry date which identifies when the Registration Lifecycle is scheduled - to expire. - -Each subregistry includes: -- subregistry account ID which identifies the chainId and address of - the associated subregistry smart contract, -- node (namehash) of the name the subregistry manages subnames of. - - -**Endpoint:** `GET /api/registrar-actions` -**Endpoint with custom results count limit:** `GET /api/registrar-actions?limit=5` -**Endpoint with results sourced for the `namehash('eth')` parent node:** `GET /api/registrar-actions/0x93cdeb708b7545dc668eb9280176169d1c33cfd8ed6f04690a0bcc88a93fc4ae` - -### Example response - -TDB From ce4e0795a7dd30086e6eeb975bcadd39a3d3b367 Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Tue, 12 May 2026 16:56:29 +0200 Subject: [PATCH 05/13] Update content regarding Subgraph --- .../integrations/starlight/sidebar-topics/reference.ts | 8 ++++---- .../{ => subgraph-legacy}/querying-best-practices.mdx | 0 .../docs/services/ensrainbow/concepts/unknown-labels.mdx | 1 - 3 files changed, 4 insertions(+), 5 deletions(-) rename docs/ensnode.io/src/content/docs/docs/reference/{ => subgraph-legacy}/querying-best-practices.mdx (100%) diff --git a/docs/ensnode.io/config/integrations/starlight/sidebar-topics/reference.ts b/docs/ensnode.io/config/integrations/starlight/sidebar-topics/reference.ts index 7903cbfba5..27207039b7 100644 --- a/docs/ensnode.io/config/integrations/starlight/sidebar-topics/reference.ts +++ b/docs/ensnode.io/config/integrations/starlight/sidebar-topics/reference.ts @@ -23,10 +23,6 @@ export const referenceSidebarTopic = { label: "REST API", link: "/docs/reference/rest-api", }, - { - label: "Querying Best Practices", - link: "/docs/reference/querying-best-practices", - }, { label: "ENSNode V2 Notes", link: "/docs/reference/ensnode-v2-notes", @@ -51,6 +47,10 @@ export const referenceSidebarTopic = { label: "Subgraph API", link: "/docs/reference/subgraph-legacy/subgraph-api", }, + { + label: "Querying Best Practices", + link: "/docs/reference/subgraph-legacy/querying-best-practices", + }, { label: "Subgraph Compatibility Tooling", link: "/docs/reference/subgraph-legacy/subgraph-compatibility-tooling", diff --git a/docs/ensnode.io/src/content/docs/docs/reference/querying-best-practices.mdx b/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/querying-best-practices.mdx similarity index 100% rename from docs/ensnode.io/src/content/docs/docs/reference/querying-best-practices.mdx rename to docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/querying-best-practices.mdx diff --git a/docs/ensnode.io/src/content/docs/docs/services/ensrainbow/concepts/unknown-labels.mdx b/docs/ensnode.io/src/content/docs/docs/services/ensrainbow/concepts/unknown-labels.mdx index 3defefed84..c70f2ad562 100644 --- a/docs/ensnode.io/src/content/docs/docs/services/ensrainbow/concepts/unknown-labels.mdx +++ b/docs/ensnode.io/src/content/docs/docs/services/ensrainbow/concepts/unknown-labels.mdx @@ -221,4 +221,3 @@ For more details, see [Label Sets & Versioning](/docs/services/ensrainbow/concep - **[Architecture](/docs/services/ensrainbow/concepts/architecture)** - High-level system architecture and data flow - **[API Reference](/docs/services/ensrainbow/usage/api)** - Complete HTTP API documentation for ENSRainbow - **[Terminology Reference](/docs/reference/terminology)** - Comprehensive ENSNode terminology including [Unknown Label](/docs/reference/terminology#unknown-label) and [Encoded LabelHash](/docs/reference/terminology#encoded-labelhash) -- **[Querying Best Practices](/docs/reference/querying-best-practices)** - How to handle unknown labels when querying ENSNode From 5976b9b67a2ca20ff67191a135b3dd54bc786387 Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Tue, 12 May 2026 16:57:31 +0200 Subject: [PATCH 06/13] Drop "indexing-ens-compatible-onchain-names" page --- .../starlight/sidebar-topics/reference.ts | 4 -- .../indexing-ens-compatible-onchain-names.mdx | 45 ------------------- 2 files changed, 49 deletions(-) delete mode 100644 docs/ensnode.io/src/content/docs/docs/reference/indexing-ens-compatible-onchain-names.mdx diff --git a/docs/ensnode.io/config/integrations/starlight/sidebar-topics/reference.ts b/docs/ensnode.io/config/integrations/starlight/sidebar-topics/reference.ts index 27207039b7..62854d98a2 100644 --- a/docs/ensnode.io/config/integrations/starlight/sidebar-topics/reference.ts +++ b/docs/ensnode.io/config/integrations/starlight/sidebar-topics/reference.ts @@ -27,10 +27,6 @@ export const referenceSidebarTopic = { label: "ENSNode V2 Notes", link: "/docs/reference/ensnode-v2-notes", }, - { - label: "Indexing ENS-Compatible Names", - link: "/docs/reference/indexing-ens-compatible-onchain-names", - }, { label: "Mainnet Subnames of Subregistries", link: "/docs/reference/mainnet-registered-subnames-of-subregistries", diff --git a/docs/ensnode.io/src/content/docs/docs/reference/indexing-ens-compatible-onchain-names.mdx b/docs/ensnode.io/src/content/docs/docs/reference/indexing-ens-compatible-onchain-names.mdx deleted file mode 100644 index 7b0a879c59..0000000000 --- a/docs/ensnode.io/src/content/docs/docs/reference/indexing-ens-compatible-onchain-names.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Indexing ENS‐Compatible On‐Chain Names ---- - -:::caution[Work in Progress] -This documentation is under active development. Some sections may be incomplete or out of date. -::: - - -## Accessing on-chain data - -Fetching data about on-chain activity can be either done via direct RPC calls to a blockchain node, or via an API service that has previously indexed the on-chain data. Using direct RPC calls loads data directly from the source of truth, but it's also more complex and the data may not be in the caller's preferred format or structure. Using an API service is more flexible, because it abstracts away the data transformation process and allows the clients to query a set of prepared aggregates. - -## ENS and the `eth` top-level domain - -### Indexing on-chain data - -The ENS community has adopted the Graph Protocol and built [the ENS Subgraph](https://github.com/ensdomains/ens-subgraph) to index on-chain data about ENS and the `eth` subnames. The indexing engine sources data from an RPC node, and aggregates it into a set of collections. The main collections describe following data entities: -- Account -- Domain -- Registration -- Resolver -- WrappedDomain - -### Serving aggregate data - -Clients that want to access ENS data can easily do so with [the ensjs client library](https://github.com/ensdomains/ensjs). The ensjs lib queries both an RPC endpoint and, for more complex functions, the [the ENS Subgraph deployment](https://api.thegraph.com/subgraphs/name/ensdomains/ens). This deployment has [a GraphiQL interface](https://api.thegraph.com/subgraphs/name/ensdomains/ens/graphql?query=%7B%0A++account%28id%3A+%220xd4416b13d2b3a9abae7acd5d6c2bbdbe25686401%22%29+%7B%0A++++domains%28orderBy%3A+createdAt%2C+orderDirection%3A+desc%2C+first%3A+3%29+%7B%0A++++++name%0A++++++createdAt%0A++++++resolver+%7B%0A++++++++addr+%7B%0A++++++++++id%0A++++++++%7D%0A++++++++contentHash%0A++++++++texts%0A++++++%7D%0A++++%7D%0A++%7D%0A++registrations%28orderBy%3A+registrationDate%2C+orderDirection%3A+desc%2C+first%3A+3%29+%7B%0A++++registrationDate%0A++++domain+%7B%0A++++++name%0A++++%7D%0A++++registrant+%7B%0A++++++id%0A++++%7D%0A++%7D%0A%7D) if you'd like to interact with it and check out the data model it offers. - -## Other ENS-compatible protocols - -The canonical ENS protocol has been originally deployed on the Ethereum Mainnet. [There are plans](https://x.com/ensdomains/status/1869020192388616497) to scale the protocol with its own layer-2 chain, called Namechain. - -Some members of the ENS community have started building their own [ENS subname systems on top of the CCIP-read protocol](https://docs.ens.domains/learn/ccip-read), for example: -- [Basenames](https://www.base.org/names) from coinbase.com ([source](https://github.com/base-org/basenames)) -- [Linea ENS](https://names.linea.build/) from consensys.io ([source](https://github.com/Consensys/linea-ens)) - -These L2 systems run their own copy of ENS-compatible contracts and represent a multi-chain extension of the unified ENS namespace. A core design goal of ENSNode is to index ENS names whever they live, whether that's on-chain (on mainnet or L2s like Base, Linea, and Namechain) or off-chain (ex. `.cb.id`, `.uni.eth`). - -### Indexing L2 subnames - -:::caution[Work in Progress] -TODO -::: - - From b00cc2be6a2968c5f45fa419abbaf5b3e3a6f75d Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Tue, 12 May 2026 19:19:50 +0200 Subject: [PATCH 07/13] Update content for ENSApi index page --- .../docs/docs/services/ensapi/index.mdx | 21 ++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/ensnode.io/src/content/docs/docs/services/ensapi/index.mdx b/docs/ensnode.io/src/content/docs/docs/services/ensapi/index.mdx index d0cff1304f..bb91860123 100644 --- a/docs/ensnode.io/src/content/docs/docs/services/ensapi/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/services/ensapi/index.mdx @@ -8,7 +8,26 @@ sidebar: import { LinkCard } from '@astrojs/starlight/components'; -ENSApi is the API service for ENSNode. +ENSApi is a web service built on top of [ENSDb](./ensdb), and provides access to indexed ENS data through multiple HTTP APIs. + +## GraphQL APIs + +### ENS Omnigraph API + +The Omnigraph API is the new primary GraphQL API for ENSNode that provides a unified access model for both ENSv1 and ENSv2 data. Write your queries once and get automatic support for ENSv1 and ENSv2 data! + +### ENS Subgraph API + +The Subgraph API is the legacy GraphQL API for ENSNode that was built to provide a drop-in replacement for The Graph's ENS subgraph. It is now deprecated in favor of the Omnigraph API, but is still available for compatibility reasons. + +## REST APIs + +ENSApi also provides a set of REST APIs for accessing ENS data. These APIs are designed to be simple and easy to use, and are ideal for use cases where GraphQL is not a good fit. + + ## Configuration From 8bb245735521d8e7c7104d1f8f89b73049a53f76 Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Thu, 14 May 2026 11:57:44 +0200 Subject: [PATCH 08/13] Refine ENSNode docs --- .../docs/docs/integrate/hosted-instances.mdx | 16 +-- .../content/docs/docs/reference/rest-api.mdx | 134 ++---------------- .../content/docs/docs/self-host/docker.mdx | 2 +- .../docs/docs/services/ensapi/index.mdx | 11 +- .../contributing/creating-a-plugin.mdx | 34 ++++- .../services/ensindexer/usage/management.mdx | 29 ++-- 6 files changed, 73 insertions(+), 153 deletions(-) diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx index 4e79a6d7f4..89255f42a8 100644 --- a/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx +++ b/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx @@ -17,14 +17,14 @@ These instances are provided free of charge with no API key required, have no ra Each ENSNode hosted instance is configured for a specific ENS namespace and activated ENSNode plugins. The ENS namespace is the source of truth for the data indexed by the instance, and the activated ENSNode plugins determine the specific data model for indexing and querying. -Each ENS namespace is defined by onchain state as per implemented ENS protocol version (i.e. ENS V1, ENS V2). Currently, ENSNode supports the following ENS namespaces: -- ENS V2 Sepolia -- ENS V1 Mainnet -- ENS V1 Sepolia +Each ENS namespace is defined by onchain state as per implemented ENS protocol version (i.e. ENSv1, ENSv2). Currently, ENSNode supports the following ENS namespaces: +- ENSv2 Sepolia +- ENSv1 Mainnet +- ENSv1 Sepolia -### ENS V2 instances +### ENSv2 instances -These instances demonstrate the latest ENS V2 support in ENSNode. +These instances demonstrate the latest ENSv2 support in ENSNode. #### ENSNode 'v2 Sepolia' @@ -36,7 +36,7 @@ These instances demonstrate the latest ENS V2 support in ENSNode. purpose="Preview of ENSNode's support for the ENS V2 Sepolia namespace." /> -## ENS V1 Instances +## ENSv1 Instances These instances demonstrate the ENS V1 support in ENSNode. @@ -61,7 +61,7 @@ These ENSNode instances focus on pushing the boundaries of what's possible with instanceURL="https://api.alpha-sepolia.ensnode.io" connectWithENSAdminURL="https://admin.ensnode.io/connection?connection=https%3A%2F%2Fapi.alpha-sepolia.ensnode.io" namespace="sepolia" - plugins="subgraph, basenames, lineanames, registrars, ensv2,protocol-acceleration" + plugins="subgraph, basenames, lineanames, registrars, ensv2, protocol-acceleration" purpose="Demonstration of ENSNode's multichain ENS indexing capability for the ENS V1 namespace rooted on Sepolia. Provides a superset of the data indexed by the ENS Subgraph. Offers a preview of ENS Protocol Acceleration." /> diff --git a/docs/ensnode.io/src/content/docs/docs/reference/rest-api.mdx b/docs/ensnode.io/src/content/docs/docs/reference/rest-api.mdx index 73f1d99173..9e91222b64 100644 --- a/docs/ensnode.io/src/content/docs/docs/reference/rest-api.mdx +++ b/docs/ensnode.io/src/content/docs/docs/reference/rest-api.mdx @@ -7,74 +7,6 @@ sidebar: import { LinkCard } from "@astrojs/starlight/components"; -## Config API - -The Config API provides a complete view of an ENSNode instance's public -configuration, making it easy to understand and verify it's configuration. - -**Endpoint:** `GET /api/config` - -This endpoint returns the public configuration object containing all -the essential information about an ENSNode instance, -including ENS namespace, indexed chains, enabled features, active plugins, -and dependency versions. - -### Key Configuration Details - -The response includes several important configuration categories: - -- **ENS**: current ENS namespace -- **Network Configuration**: URLs for ENSAdmin interface, public ENSNode API, - and ENSRainbow service -- **Chains**: Lists of indexed chains -- **Feature Flags**: Boolean settings for experimental features and optional - functionality -- **Plugins**: Activated plugins -- **ENSIndexer Version Information**: Ponder framework version, - ENSRainbow public config, ENSDb version, ENSIndexer version, [ENS Normalize version](https://www.npmjs.com/package/@adraffy/ens-normalize) - -### Example response - -```json -{ - "indexedChainIds": [ - 1, - 8453, - 59144, - 10, - 42161, - 534352 - ], - "ensIndexerSchemaName": "alphaSchema0.35.0", - "isSubgraphCompatible": false, - "labelSet": { - "labelSetId": "subgraph", - "labelSetVersion": 0 - }, - "namespace": "mainnet", - "plugins": [ - "subgraph", - "basenames", - "lineanames", - "threedns", - "protocol-acceleration", - "registrars", - "tokenscope" - ], - "versionInfo": { - "ponder": "0.16.1", - "ensDb": "1.5.1", - "ensIndexer": "1.5.1", - "ensNormalize": "1.11.1", - "ensRainbowPublicConfig": { - "version": "1.5.1", - "labelSet": { "labelSetId": "subgraph", "highestLabelSetVersion": 0 }, - "recordsCount": 133856894 - } - } -} -``` - ## Indexing Status API Monitor an ENSNode's indexing progress across multiple chains with @@ -89,60 +21,11 @@ as an omnichain indexing status snapshot. Perfect for building monitoring dashboards, health checks, or determining whether your ENSNode has caught up with recent onchain activity. -### Understanding the Response - -The status response provides both overall and chain-specific information. - -### Example response - -```json -{ - "responseCode": "ok", - "realtimeProjection": { - "projectedAt": 1760435068, - "worstCaseDistance": 199550209, - "snapshot": { - "strategy": "omnichain", - "slowestChainIndexingCursor": 1560884859, - "snapshotTime": 1760435068, - "omnichainSnapshot": { - "omnichainStatus": "omnichain-backfill", - "chains": { - "1": { - "chainStatus": "chain-backfill", - "config": { - "rangeType": "left-bounded", - "startBlock": { - "timestamp": 1489165544, - "number": 3327417 - } - }, - "latestIndexedBlock": { - "timestamp": 1560884859, - "number": 7984099 - }, - "backfillEndBlock": { - "timestamp": 1760432243, - "number": 23574893 - } - }, - "8453": { - "chainStatus": "chain-queued", - "config": { - "rangeType": "left-bounded", - "startBlock": { - "timestamp": 1721932307, - "number": 17571480 - } - } - } - }, - "omnichainIndexingCursor": 1560884859 - } - } - } -} -``` + ### Realtime Indexing Distance @@ -175,3 +58,10 @@ When you include this parameter it influences the HTTP response code as follows: - **Success (200 OK)**: The latest indexed block of each chain is guaranteed within the requested distance from realtime. - **Service Unavailable (503)**: The latest indexed block of each chain is NOT guaranteed within the requested distance from realtime. + + + diff --git a/docs/ensnode.io/src/content/docs/docs/self-host/docker.mdx b/docs/ensnode.io/src/content/docs/docs/self-host/docker.mdx index 908e0c92a7..1398a9790d 100644 --- a/docs/ensnode.io/src/content/docs/docs/self-host/docker.mdx +++ b/docs/ensnode.io/src/content/docs/docs/self-host/docker.mdx @@ -65,7 +65,7 @@ docker compose -f docker/docker-compose.devnet.yml up -d title="Building ENSNode Docker Images" description="Learn about building docker images for ENSNode services." href="/docs/reference/contributing/building" - /> +/> :::note[Port Mappings] Note that while the default `docker/docker-compose.yml` exposes each container's port to the host machine (useful for development), you may only wish to expose ENSApi's `4334` and avoid exposing services like ENSRainbow, ENSAdmin, and Postgres to the wider internet. diff --git a/docs/ensnode.io/src/content/docs/docs/services/ensapi/index.mdx b/docs/ensnode.io/src/content/docs/docs/services/ensapi/index.mdx index bb91860123..a8ccafefcb 100644 --- a/docs/ensnode.io/src/content/docs/docs/services/ensapi/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/services/ensapi/index.mdx @@ -8,25 +8,26 @@ sidebar: import { LinkCard } from '@astrojs/starlight/components'; -ENSApi is a web service built on top of [ENSDb](./ensdb), and provides access to indexed ENS data through multiple HTTP APIs. +ENSApi is a web service built on top of [ENSDb](./ensdb), and provides access to indexed ENS data through multiple HTTP APIs. ## GraphQL APIs ### ENS Omnigraph API -The Omnigraph API is the new primary GraphQL API for ENSNode that provides a unified access model for both ENSv1 and ENSv2 data. Write your queries once and get automatic support for ENSv1 and ENSv2 data! +The **Omnigraph API** is the _new_ primary GraphQL API for ENSNode that provides a unified access model for both ENSv1 and ENSv2 data. Write your queries once and get automatic support for ENSv1 and ENSv2 data! ### ENS Subgraph API -The Subgraph API is the legacy GraphQL API for ENSNode that was built to provide a drop-in replacement for The Graph's ENS subgraph. It is now deprecated in favor of the Omnigraph API, but is still available for compatibility reasons. +The Subgraph API is the _legacy_ GraphQL API for ENSNode that was built to provide a drop-in replacement for The Graph's ENS subgraph. It is now deprecated in favor of the Omnigraph API, but is still available for compatibility reasons. ## REST APIs ENSApi also provides a set of REST APIs for accessing ENS data. These APIs are designed to be simple and easy to use, and are ideal for use cases where GraphQL is not a good fit. ## Configuration diff --git a/docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx b/docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx index 56ba6e65fe..c64751a48a 100644 --- a/docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx +++ b/docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx @@ -8,8 +8,34 @@ sidebar: import { LinkCard } from '@astrojs/starlight/components'; -:::note -This guide covers how to create a plugin for ENSIndexer. -::: +## ENSIndexer Plugins -TODO +ENSIndexer is designed to be extensible with plugins that can implement custom indexing logic and data models. This allows you to tailor ENSIndexer to your specific use case and ENS data needs. + +ENSIndexer will only active the plugins you specify in the `PLUGINS` env variable, so you can choose to only activate the plugins that are relevant to your use case. The `PLUGINS` env variable accepts a comma-separated list of plugin names to be activated. For example, if you want to activate the `ensv2` and `protocol-acceleration` plugins, you can set `PLUGINS=ensv2,protocol-acceleration`. + +## Plugin Architecture + +The ENSIndexer plugin is a standalone TypeScript module that can be developed, tested, and deployed independently. Plugins can define their own data models, and indexing logic. It must include two main files: +- `event-handlers.ts`: This file defines the event handlers for the plugin, which are functions that will be called when specific ENS events are indexed. The event handlers contain the logic for how to process the indexed data and store it in the ENSIndexer Schema. +- `plugin.ts`: This file defines the plugin itself, including its name, description, and any configuration options, like datasources to be used for specifying onchain contracts that will be indexed. + +### Event handlers + +The `event-handlers.ts` file has to export a function via default export. This function will be only called by ENSIndexer runtime when the plugin is activated. We leverage this approach to conditionally execute `addOnchainEventListener` calls for active plugins only. This way, ENSIndexer learns which specific onchain events it need to listen to, and what indexing logic to execute for each indexed event, based on the event handlers from the active plugins. + +You need to import the `event-handlers.ts` file from each plugin into [`register-handlers.ts`](https://github.com/namehash/ensnode/blob/main/apps/ensindexer/ponder/src/register-handlers.ts) file. This way ENSIndexer can recognize the event handlers and know when to have them executed during indexing. For example, by checking `config.plugins` value for the specific plugin name, ENSIndexer runtime can conditionally execute relevant `event-handlers.ts` files across all active plugins. + +### Plugin definition + +The `plugin.ts` file has a default export with the plugin definition object returned from `createPlugin` function. The plugin definition object includes the plugin name, datasources required for the plugin to operate, and the config for contracts to be indexed by ENSIndexer when the plugin is active. + +You need to import the plugin definition object into [`apps/ensindexer/src/plugins/index.ts`](https://github.com/namehash/ensnode/tree/main/apps/ensindexer/src/plugins/index.ts) file and have it included in the `ALL_PLUGINS` array. This way, you let the ENSIndexer runtime know that the plugin is available for activation, which in turn allows you to activate the plugin by including its name in the `PLUGINS` env variable. + +## Existing Plugins + +You can find the current list of existing ENSIndexer plugins in [the ENSIndexer repository](https://github.com/namehash/ensnode/tree/main/apps/ensindexer/src/plugins). + +## Creating Your Own Plugin + +If you’re interested in building a plugin, reach out to the NameHash Labs team who is happy to provide support and additional info. diff --git a/docs/ensnode.io/src/content/docs/docs/services/ensindexer/usage/management.mdx b/docs/ensnode.io/src/content/docs/docs/services/ensindexer/usage/management.mdx index 3a2bad06f6..cd5c782302 100644 --- a/docs/ensnode.io/src/content/docs/docs/services/ensindexer/usage/management.mdx +++ b/docs/ensnode.io/src/content/docs/docs/services/ensindexer/usage/management.mdx @@ -1,31 +1,34 @@ --- -title: Managing ENSNode Instances +title: Managing ENSIndexer Instances sidebar: label: Management order: 8 --- -:::caution[Work in Progress] -TODO -::: +## Database operations -## Indexing Schemas +Each instance of ENSIndexer maintains its own ENSIndexer Schema instance in ENSDb. The same ENSIndexer instance will always use the same ENSIndexer Schema, even after restarts. However, if you need to update ENSIndexer config, or deploy a new version of ENSIndexer, you will have to update the `ENSINDEXER_SCHEMA_NAME` env variable to point to a new schema, as otherwise, the ENSIndexer instance will detect that the ENSIndexer Schema was already owned by an ENSIndexer instance with different config / indexing logic and will refuse to start. -:::caution[Work in Progress] -TODO -::: +### ENSIndexer Schema lifecycle +- Let's say you're currently running ENSNode version X that's indexing into `ENSINDEXER_SCHEMA_NAME=myschema_X` +- Now, when you upgrade to ENSNode version Y, if you try to continue using `ENSINDEXER_SCHEMA_NAME=myschema_X` then ENSIndexer will immediately terminate with an error because indexing logic or config will be different. +- Therefore, you must update the `ENSINDEXER_SCHEMA_NAME` to `myschema_Y`, which will: + - Build a completely new index from scratch into `myschema_Y` which may grow to become 100+ GB depending on how ENSIndexer is configured. + - Still retain all the data in `myschema_X` which could also be 100+ GB... +- Now imagine you repeat this process across multiple updates to your `ENSINDEXER_SCHEMA_NAME`, you might have hundreds and hundreds of GB of ENSIndexer Schema instances no longer in use that are just taking up disk space in ENSDb instance until you completely run out of disk space. +- The solution is that you need to manually delete all the old `ENSINDEXER_SCHEMA_NAME` in your ENSDb instance you no longer use. -### Dropping Orphaned Indexing Schemas +### Dropping orphaned ENSIndexer Schemas -When re-deploying any Ponder indexer, including ENSNode a new schema is created (via the `ENSINDEXER_SCHEMA_NAME` env variable) and the previous schemas are abandoned. They remain available for rollbacks, but take up database space—dropping these schemas once no longer available is useful for reclaiming space in your Postgres instance. +If your ENSDb instance have orphaned ENSIndexer Schemas that you no longer use, you can drop them with a SQL command like the following: ```sql -DROP SCHEMA CASCADE; +DROP SCHEMA myschema_X CASCADE; ``` -### `ponder_sync` Schema +### Dropping the RPC Cache -Ponder internal state schema, notably holds the RPC Cache. If you'd like to drop your RPC cache and any internal Ponder state, you can: +Ponder internal state is kept in the `ponder_sync` database schema. Notably, it holds the RPC Cache. If you'd like to drop your RPC cache and any internal Ponder state, you can: ```sql DROP SCHEMA ponder_sync CASCADE; From 297d18156f30db5531dea7085222705f2ccb316f Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Thu, 14 May 2026 12:19:16 +0200 Subject: [PATCH 09/13] Apply AI PR feedback --- docs/ensnode.io/astro.config.mjs | 3 ++- .../content/docs/docs/integrate/ensv2-readiness.mdx | 2 +- .../src/content/docs/docs/reference/rest-api.mdx | 4 ++-- .../subgraph-legacy/querying-best-practices.mdx | 2 +- .../docs/reference/subgraph-legacy/subgraph-api.mdx | 4 ++-- .../content/docs/docs/reference/what-is-ensnode.mdx | 11 ++--------- .../src/content/docs/docs/services/ensapi/index.mdx | 2 +- .../ensindexer/contributing/creating-a-plugin.mdx | 4 ++-- .../docs/services/ensindexer/usage/management.mdx | 2 +- 9 files changed, 14 insertions(+), 20 deletions(-) diff --git a/docs/ensnode.io/astro.config.mjs b/docs/ensnode.io/astro.config.mjs index 601d0e766c..f74cfee992 100644 --- a/docs/ensnode.io/astro.config.mjs +++ b/docs/ensnode.io/astro.config.mjs @@ -23,7 +23,8 @@ export default defineConfig({ "/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": "/docs/reference/what-is-the-ens-subgraph", + "/ensnode/concepts/what-is-the-ens-subgraph": + "/docs/reference/subgraph-legacy/what-is-the-ens-subgraph", "/ensadmin": "/docs/services/ensadmin", "/ensapi": "/docs/services/ensapi", "/ensdb": "/docs/services/ensdb", diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/ensv2-readiness.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/ensv2-readiness.mdx index 54efcb0fc1..e4405d9ae0 100644 --- a/docs/ensnode.io/src/content/docs/docs/integrate/ensv2-readiness.mdx +++ b/docs/ensnode.io/src/content/docs/docs/integrate/ensv2-readiness.mdx @@ -16,7 +16,7 @@ import { LinkCard, Aside } from "@astrojs/starlight/components"; Fully supporting ENSv1 requires two separate systems working in parallel: 1. **On-chain resolution** — RPC calls with CCIP-read support (e.g. via [viem](/docs/reference/subgraph-legacy/with-viem) or [ensjs](/docs/reference/subgraph-legacy/with-ensjs)) to resolve names to addresses and records at the current state of the chain. -2. **Indexed data** — the [ENS Subgraph](/docs/reference/what-is-the-ens-subgraph) for historical data, registration info, reverse records, and browsing names owned by an address. +2. **Indexed data** — the [ENS Subgraph](/docs/reference/subgraph-legacy/what-is-the-ens-subgraph) for historical data, registration info, reverse records, and browsing names owned by an address. Neither system alone is complete. The Subgraph gives you queryable indexed history but can lag behind the chain and has no CCIP-read support. diff --git a/docs/ensnode.io/src/content/docs/docs/reference/rest-api.mdx b/docs/ensnode.io/src/content/docs/docs/reference/rest-api.mdx index 9e91222b64..40f04a9cdb 100644 --- a/docs/ensnode.io/src/content/docs/docs/reference/rest-api.mdx +++ b/docs/ensnode.io/src/content/docs/docs/reference/rest-api.mdx @@ -24,7 +24,7 @@ whether your ENSNode has caught up with recent onchain activity. ### Realtime Indexing Distance @@ -63,5 +63,5 @@ When you include this parameter it influences the HTTP response code as follows: diff --git a/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/querying-best-practices.mdx b/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/querying-best-practices.mdx index 0409da77d6..9011c5fea1 100644 --- a/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/querying-best-practices.mdx +++ b/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/querying-best-practices.mdx @@ -139,7 +139,7 @@ ENSNode's handling of unnormalized labels is controlled by the `SUBGRAPH_COMPAT` - `SUBGRAPH_COMPAT=true` allows unnormalized labels to be returned as Subgraph Interpreted Labels (required for full ENS Subgraph compatibility) - `SUBGRAPH_COMPAT=false` (default) encodes unnormalized labels as Interpreted Labels, improving security -For more details, see [Subgraph Compatibility](/docs/reference/what-is-the-ens-subgraph). +For more details, see [Subgraph Compatibility](/docs/reference/subgraph-legacy/what-is-the-ens-subgraph). ::: ### When `SUBGRAPH_COMPAT=true` diff --git a/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/subgraph-api.mdx b/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/subgraph-api.mdx index 6b7450084c..545652ace5 100644 --- a/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/subgraph-api.mdx +++ b/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/subgraph-api.mdx @@ -9,8 +9,8 @@ import { LinkCard } from "@astrojs/starlight/components"; ## Subgraph API ENSNode exposes a Subgraph-Compatible GraphQL endpoint at `/subgraph`. -:::note[Subgraph API Compatibility Reference] -For details on subgraph compatibility, see the Subgraph Compatibility documentation. +:::note[Subgraph API Compatibility] +ENSNode provides verified backwards compatibility with the ENS Subgraph. See configuration details below. 10x faster than ENS Subgraph) - Isolated indexing schemas (supporting branches, staging environments) - Access your indexed data directly from Postgres - 4. **Self-hostable Decentralization Approach** - - Self-hostable infrastructure - Bring-your-own Postgres - Bring-your-own ENSRainbow diff --git a/docs/ensnode.io/src/content/docs/docs/services/ensapi/index.mdx b/docs/ensnode.io/src/content/docs/docs/services/ensapi/index.mdx index a8ccafefcb..00d18954b4 100644 --- a/docs/ensnode.io/src/content/docs/docs/services/ensapi/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/services/ensapi/index.mdx @@ -8,7 +8,7 @@ sidebar: import { LinkCard } from '@astrojs/starlight/components'; -ENSApi is a web service built on top of [ENSDb](./ensdb), and provides access to indexed ENS data through multiple HTTP APIs. +ENSApi is a web service built on top of [ENSDb](/docs/services/ensdb), and provides access to indexed ENS data through multiple HTTP APIs. ## GraphQL APIs diff --git a/docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx b/docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx index c64751a48a..b5f570a87c 100644 --- a/docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx +++ b/docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx @@ -12,7 +12,7 @@ import { LinkCard } from '@astrojs/starlight/components'; ENSIndexer is designed to be extensible with plugins that can implement custom indexing logic and data models. This allows you to tailor ENSIndexer to your specific use case and ENS data needs. -ENSIndexer will only active the plugins you specify in the `PLUGINS` env variable, so you can choose to only activate the plugins that are relevant to your use case. The `PLUGINS` env variable accepts a comma-separated list of plugin names to be activated. For example, if you want to activate the `ensv2` and `protocol-acceleration` plugins, you can set `PLUGINS=ensv2,protocol-acceleration`. +ENSIndexer will only activate the plugins you specify in the `PLUGINS` env variable, so you can choose to only activate the plugins that are relevant to your use case. The `PLUGINS` env variable accepts a comma-separated list of plugin names to be activated. For example, if you want to activate the `ensv2` and `protocol-acceleration` plugins, you can set `PLUGINS=ensv2,protocol-acceleration`. ## Plugin Architecture @@ -22,7 +22,7 @@ The ENSIndexer plugin is a standalone TypeScript module that can be developed, t ### Event handlers -The `event-handlers.ts` file has to export a function via default export. This function will be only called by ENSIndexer runtime when the plugin is activated. We leverage this approach to conditionally execute `addOnchainEventListener` calls for active plugins only. This way, ENSIndexer learns which specific onchain events it need to listen to, and what indexing logic to execute for each indexed event, based on the event handlers from the active plugins. +The `event-handlers.ts` file has to export a function via default export. This function will only be called by ENSIndexer runtime when the plugin is activated. We leverage this approach to conditionally execute `addOnchainEventListener` calls for active plugins only. This way, ENSIndexer learns which specific onchain events it needs to listen to, and what indexing logic to execute for each indexed event, based on the event handlers from the active plugins. You need to import the `event-handlers.ts` file from each plugin into [`register-handlers.ts`](https://github.com/namehash/ensnode/blob/main/apps/ensindexer/ponder/src/register-handlers.ts) file. This way ENSIndexer can recognize the event handlers and know when to have them executed during indexing. For example, by checking `config.plugins` value for the specific plugin name, ENSIndexer runtime can conditionally execute relevant `event-handlers.ts` files across all active plugins. diff --git a/docs/ensnode.io/src/content/docs/docs/services/ensindexer/usage/management.mdx b/docs/ensnode.io/src/content/docs/docs/services/ensindexer/usage/management.mdx index cd5c782302..09e81c001a 100644 --- a/docs/ensnode.io/src/content/docs/docs/services/ensindexer/usage/management.mdx +++ b/docs/ensnode.io/src/content/docs/docs/services/ensindexer/usage/management.mdx @@ -20,7 +20,7 @@ Each instance of ENSIndexer maintains its own ENSIndexer Schema instance in ENSD ### Dropping orphaned ENSIndexer Schemas -If your ENSDb instance have orphaned ENSIndexer Schemas that you no longer use, you can drop them with a SQL command like the following: +If your ENSDb instance has orphaned ENSIndexer Schemas that you no longer use, you can drop them with a SQL command like the following: ```sql DROP SCHEMA myschema_X CASCADE; From 1e4ef70cca3493b23414d955c54900cb9e07b9ae Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Thu, 14 May 2026 12:27:00 +0200 Subject: [PATCH 10/13] Apply AI PR feedback --- docs/ensnode.io/astro.config.mjs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/ensnode.io/astro.config.mjs b/docs/ensnode.io/astro.config.mjs index f74cfee992..2629287f56 100644 --- a/docs/ensnode.io/astro.config.mjs +++ b/docs/ensnode.io/astro.config.mjs @@ -25,6 +25,12 @@ export default defineConfig({ "/ensnode/concepts/what-is-ensnode": "/docs/reference/what-is-ensnode", "/ensnode/concepts/what-is-the-ens-subgraph": "/docs/reference/subgraph-legacy/what-is-the-ens-subgraph", + "/docs/reference/what-is-the-ens-subgraph": + "/docs/reference/subgraph-legacy/what-is-the-ens-subgraph", + "/docs/reference/querying-best-practices": + "/docs/reference/subgraph-legacy/querying-best-practices", + "/docs/reference/subgraph-compatibility-tooling": + "/docs/reference/subgraph-legacy/subgraph-compatibility-tooling", "/ensadmin": "/docs/services/ensadmin", "/ensapi": "/docs/services/ensapi", "/ensdb": "/docs/services/ensdb", From 0aa37269fc786681f2826c8e1eaf339111eece96 Mon Sep 17 00:00:00 2001 From: Tomek Kopacki Date: Thu, 14 May 2026 14:16:05 +0200 Subject: [PATCH 11/13] Apply suggestions from code review Co-authored-by: lightwalker.eth <126201998+lightwalker-eth@users.noreply.github.com> Co-authored-by: Tomek Kopacki --- .../docs/docs/integrate/hosted-instances.mdx | 23 +++++++++++-------- .../subgraph-legacy/subgraph-api.mdx | 2 +- .../docs/docs/services/ensapi/index.mdx | 6 ++--- .../contributing/creating-a-plugin.mdx | 6 ++--- .../services/ensindexer/usage/management.mdx | 2 +- 5 files changed, 21 insertions(+), 18 deletions(-) diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx index 89255f42a8..833d7e28b8 100644 --- a/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx +++ b/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx @@ -15,16 +15,19 @@ These instances are provided free of charge with no API key required, have no ra ### Available instance configurations -Each ENSNode hosted instance is configured for a specific ENS namespace and activated ENSNode plugins. The ENS namespace is the source of truth for the data indexed by the instance, and the activated ENSNode plugins determine the specific data model for indexing and querying. +Each ENSNode hosted instance is configured for a specific ENS namespace and activated ENSNode plugins. The ENS namespace is the source of truth for the data indexed by the instance, and the activated ENSNode plugins determine the specific data model produced by indexing and available for querying. -Each ENS namespace is defined by onchain state as per implemented ENS protocol version (i.e. ENSv1, ENSv2). Currently, ENSNode supports the following ENS namespaces: -- ENSv2 Sepolia -- ENSv1 Mainnet -- ENSv1 Sepolia +Each ENS namespace is associated with a particular ENS root registry deployment, which may or may not have completed the transition from ENSv1 to ENSv2. Currently, ENSNode supports the following ENS namespaces: +- `mainnet` (ENSv1) +- `sepolia` (ENSv1) +- `sepolia-v2` (An independent deployment of ENS to Sepolia that is already upgraded to ENSv2) +- `ens-test-env` (A deployment of ENSv2 to a local Anvil chain for development and testing. For details see https://github.com/ensdomains/ens-test-env and https://github.com/ensdomains/contracts-v2) + +More details about ENS namespaces can be found inside [ENSNode's datasources package](https://github.com/namehash/ensnode/tree/main/packages/datasources). ### ENSv2 instances -These instances demonstrate the latest ENSv2 support in ENSNode. +These instances are associated with an ENS namespace that has upgraded to ENSv2 and demonstrate the latest ENSv2 support in ENSNode. #### ENSNode 'v2 Sepolia' @@ -33,12 +36,12 @@ These instances demonstrate the latest ENSv2 support in ENSNode. connectWithENSAdminURL="https://admin.ensnode.io/connection?connection=https%3A%2F%2Fapi.v2-sepolia.ensnode.io" namespace="sepolia-v2" plugins="ensv2, protocol-acceleration" - purpose="Preview of ENSNode's support for the ENS V2 Sepolia namespace." + purpose="Demonstration of ENSNode's support for an ENS namespace that has already transitioned to ENSv2." /> ## ENSv1 Instances -These instances demonstrate the ENS V1 support in ENSNode. +These instances are associated with an ENS namespace that has **NOT** upgraded to ENSv2 yet and are still operating under ENSv1. These demonstrate how the ENS Omnigraph API, enssdk, enskit, and full the stack of ENSNode services provide support to developers to become ENSv2 ready even before ENSv2 launches. ### Alpha-style Deployments @@ -52,7 +55,7 @@ These ENSNode instances focus on pushing the boundaries of what's possible with connectWithENSAdminURL="https://admin.ensnode.io/connection?connection=https%3A%2F%2Fapi.alpha.ensnode.io" namespace="mainnet" plugins="subgraph, basenames, lineanames, threedns, ensv2, protocol-acceleration, registrars, tokenscope" - purpose="Demonstration of ENSNode's multichain ENS indexing capability for the ENS V1 namespace rooted on Mainnet. Provides a superset of the data indexed by the ENS Subgraph. Offers a preview of ENS Protocol Acceleration." + purpose="Demonstration of ENSNode's multichain ENS indexing capability for an ENS namespace (mainnet) that is still operating ENSv1. Experience how the ENS Omnigraph API, enssdk, enskit, and full the stack of ENSNode services provide support to developers to become ENSv2 ready even before ENSv2 launches. Provides a superset of the data indexed by the ENS Subgraph. Offers a preview of ENS Protocol Acceleration." /> #### ENSNode 'Alpha-Sepolia' @@ -62,7 +65,7 @@ These ENSNode instances focus on pushing the boundaries of what's possible with connectWithENSAdminURL="https://admin.ensnode.io/connection?connection=https%3A%2F%2Fapi.alpha-sepolia.ensnode.io" namespace="sepolia" plugins="subgraph, basenames, lineanames, registrars, ensv2, protocol-acceleration" - purpose="Demonstration of ENSNode's multichain ENS indexing capability for the ENS V1 namespace rooted on Sepolia. Provides a superset of the data indexed by the ENS Subgraph. Offers a preview of ENS Protocol Acceleration." + purpose="Demonstration of ENSNode's multichain ENS indexing capability for an ENS namespace (sepolia) that is still operating ENSv1. Experience how the ENS Omnigraph API, enssdk, enskit, and full the stack of ENSNode services provide support to developers to become ENSv2 ready even before ENSv2 launches. Provides a superset of the data indexed by the ENS Subgraph. Offers a preview of ENS Protocol Acceleration." /> ### Subgraph-style Deployments diff --git a/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/subgraph-api.mdx b/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/subgraph-api.mdx index 545652ace5..1bde89d0e0 100644 --- a/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/subgraph-api.mdx +++ b/docs/ensnode.io/src/content/docs/docs/reference/subgraph-legacy/subgraph-api.mdx @@ -23,7 +23,7 @@ ENSNode provides verified backwards compatibility with the ENS Subgraph. See con To explore the schema and run queries, use the GraphiQL Playground below. diff --git a/docs/ensnode.io/src/content/docs/docs/services/ensapi/index.mdx b/docs/ensnode.io/src/content/docs/docs/services/ensapi/index.mdx index 00d18954b4..6f1b02ac95 100644 --- a/docs/ensnode.io/src/content/docs/docs/services/ensapi/index.mdx +++ b/docs/ensnode.io/src/content/docs/docs/services/ensapi/index.mdx @@ -18,15 +18,15 @@ The **Omnigraph API** is the _new_ primary GraphQL API for ENSNode that provides ### ENS Subgraph API -The Subgraph API is the _legacy_ GraphQL API for ENSNode that was built to provide a drop-in replacement for The Graph's ENS subgraph. It is now deprecated in favor of the Omnigraph API, but is still available for compatibility reasons. +The Subgraph API is the **deprecated** _legacy_ ENSv1-only GraphQL API. It is now deprecated in favor of the Omnigraph API, but is still available for backwards compatibility reasons with The Graph's ENS subgraph. ## REST APIs -ENSApi also provides a set of REST APIs for accessing ENS data. These APIs are designed to be simple and easy to use, and are ideal for use cases where GraphQL is not a good fit. +A growing set of REST APIs are also being added to ENSApi. diff --git a/docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx b/docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx index b5f570a87c..b4544b68c7 100644 --- a/docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx +++ b/docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx @@ -10,14 +10,14 @@ import { LinkCard } from '@astrojs/starlight/components'; ## ENSIndexer Plugins -ENSIndexer is designed to be extensible with plugins that can implement custom indexing logic and data models. This allows you to tailor ENSIndexer to your specific use case and ENS data needs. +ENSNode is extensible through ENSIndexer plugins that implement custom indexing logic and produce custom indexed data models inside ENSDb. This allows you to tailor ENSNode to your specific use case and data needs. ENSIndexer will only activate the plugins you specify in the `PLUGINS` env variable, so you can choose to only activate the plugins that are relevant to your use case. The `PLUGINS` env variable accepts a comma-separated list of plugin names to be activated. For example, if you want to activate the `ensv2` and `protocol-acceleration` plugins, you can set `PLUGINS=ensv2,protocol-acceleration`. ## Plugin Architecture -The ENSIndexer plugin is a standalone TypeScript module that can be developed, tested, and deployed independently. Plugins can define their own data models, and indexing logic. It must include two main files: -- `event-handlers.ts`: This file defines the event handlers for the plugin, which are functions that will be called when specific ENS events are indexed. The event handlers contain the logic for how to process the indexed data and store it in the ENSIndexer Schema. +Each ENSIndexer plugin is a standalone TypeScript module that can be developed, tested, and deployed independently. Plugins can define their own indexed data models and indexing logic. It must include two main files: +- `event-handlers.ts`: This file defines the event handlers for the plugin, which are functions that will be called when specific onchain events are indexed. The event handlers contain the logic for how to process the indexed data and store it in the relevant indexed data model inside the ENSIndexer Schema. - `plugin.ts`: This file defines the plugin itself, including its name, description, and any configuration options, like datasources to be used for specifying onchain contracts that will be indexed. ### Event handlers diff --git a/docs/ensnode.io/src/content/docs/docs/services/ensindexer/usage/management.mdx b/docs/ensnode.io/src/content/docs/docs/services/ensindexer/usage/management.mdx index 09e81c001a..bb154c1c9e 100644 --- a/docs/ensnode.io/src/content/docs/docs/services/ensindexer/usage/management.mdx +++ b/docs/ensnode.io/src/content/docs/docs/services/ensindexer/usage/management.mdx @@ -7,7 +7,7 @@ sidebar: ## Database operations -Each instance of ENSIndexer maintains its own ENSIndexer Schema instance in ENSDb. The same ENSIndexer instance will always use the same ENSIndexer Schema, even after restarts. However, if you need to update ENSIndexer config, or deploy a new version of ENSIndexer, you will have to update the `ENSINDEXER_SCHEMA_NAME` env variable to point to a new schema, as otherwise, the ENSIndexer instance will detect that the ENSIndexer Schema was already owned by an ENSIndexer instance with different config / indexing logic and will refuse to start. +Each instance of ENSIndexer maintains its own ENSIndexer Schema instance in ENSDb. The same ENSIndexer instance will always use the same ENSIndexer Schema, even after restarts. However, if you need to update an ENSIndexer config, or deploy a new version of ENSIndexer, you will have to update the `ENSINDEXER_SCHEMA_NAME` env variable to point to a new schema, as otherwise, the ENSIndexer instance will detect that the ENSIndexer Schema was already owned by an ENSIndexer instance with different config / indexing logic and will refuse to start. These measures are taken to protect the state invariants indexing event handlers expect and require. ### ENSIndexer Schema lifecycle - Let's say you're currently running ENSNode version X that's indexing into `ENSINDEXER_SCHEMA_NAME=myschema_X` From 736ab0bd5319da85d4881a6f14eab0a516ec2824 Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Thu, 14 May 2026 14:28:22 +0200 Subject: [PATCH 12/13] Apply AI PR feedback --- .../docs/docs/integrate/hosted-instances.mdx | 26 +++++++++---------- .../contributing/creating-a-plugin.mdx | 6 ++--- .../services/ensindexer/usage/management.mdx | 8 ++++-- 3 files changed, 22 insertions(+), 18 deletions(-) diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx index 833d7e28b8..cee9bc402c 100644 --- a/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx +++ b/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx @@ -15,19 +15,19 @@ These instances are provided free of charge with no API key required, have no ra ### Available instance configurations -Each ENSNode hosted instance is configured for a specific ENS namespace and activated ENSNode plugins. The ENS namespace is the source of truth for the data indexed by the instance, and the activated ENSNode plugins determine the specific data model produced by indexing and available for querying. +Each ENSNode hosted instance is configured for a specific ENS namespace and activated ENSNode plugins. The ENS namespace is the source of truth for the data indexed by the instance, and the activated ENSNode plugins determine the specific data model produced by indexing and available for querying. -Each ENS namespace is associated with a particular ENS root registry deployment, which may or may not have completed the transition from ENSv1 to ENSv2. Currently, ENSNode supports the following ENS namespaces: -- `mainnet` (ENSv1) -- `sepolia` (ENSv1) -- `sepolia-v2` (An independent deployment of ENS to Sepolia that is already upgraded to ENSv2) -- `ens-test-env` (A deployment of ENSv2 to a local Anvil chain for development and testing. For details see https://github.com/ensdomains/ens-test-env and https://github.com/ensdomains/contracts-v2) - -More details about ENS namespaces can be found inside [ENSNode's datasources package](https://github.com/namehash/ensnode/tree/main/packages/datasources). +Each ENS namespace is associated with a particular ENS root registry deployment, which may or may not have completed the transition from ENSv1 to ENSv2. Currently, ENSNode supports the following ENS namespaces: +- `mainnet` (ENSv1) +- `sepolia` (ENSv1) +- `sepolia-v2` (An independent deployment of ENS to Sepolia that is already upgraded to ENSv2) +- `ens-test-env` (A deployment of ENSv2 to a local Anvil chain for development and testing. For details see https://github.com/ensdomains/ens-test-env and https://github.com/ensdomains/contracts-v2) + +More details about ENS namespaces can be found inside [ENSNode's datasources package](https://github.com/namehash/ensnode/tree/main/packages/datasources). ### ENSv2 instances -These instances are associated with an ENS namespace that has upgraded to ENSv2 and demonstrate the latest ENSv2 support in ENSNode. +These instances are associated with an ENS namespace that has upgraded to ENSv2 and demonstrate the latest ENSv2 support in ENSNode. #### ENSNode 'v2 Sepolia' @@ -36,12 +36,12 @@ These instances are associated with an ENS namespace that has upgraded to ENSv2 connectWithENSAdminURL="https://admin.ensnode.io/connection?connection=https%3A%2F%2Fapi.v2-sepolia.ensnode.io" namespace="sepolia-v2" plugins="ensv2, protocol-acceleration" - purpose="Demonstration of ENSNode's support for an ENS namespace that has already transitioned to ENSv2." + purpose="Demonstration of ENSNode's support for an ENS namespace that has already transitioned to ENSv2." /> ## ENSv1 Instances -These instances are associated with an ENS namespace that has **NOT** upgraded to ENSv2 yet and are still operating under ENSv1. These demonstrate how the ENS Omnigraph API, enssdk, enskit, and full the stack of ENSNode services provide support to developers to become ENSv2 ready even before ENSv2 launches. +These instances are associated with an ENS namespace that has **NOT** upgraded to ENSv2 yet and are still operating under ENSv1. These demonstrate how the ENS Omnigraph API, enssdk, enskit, and full the stack of ENSNode services provide support to developers to become ENSv2 ready even before ENSv2 launches. ### Alpha-style Deployments @@ -55,7 +55,7 @@ These ENSNode instances focus on pushing the boundaries of what's possible with connectWithENSAdminURL="https://admin.ensnode.io/connection?connection=https%3A%2F%2Fapi.alpha.ensnode.io" namespace="mainnet" plugins="subgraph, basenames, lineanames, threedns, ensv2, protocol-acceleration, registrars, tokenscope" - purpose="Demonstration of ENSNode's multichain ENS indexing capability for an ENS namespace (mainnet) that is still operating ENSv1. Experience how the ENS Omnigraph API, enssdk, enskit, and full the stack of ENSNode services provide support to developers to become ENSv2 ready even before ENSv2 launches. Provides a superset of the data indexed by the ENS Subgraph. Offers a preview of ENS Protocol Acceleration." + purpose="Demonstration of ENSNode's multichain ENS indexing capability for an ENS namespace (mainnet) that is still operating ENSv1. Experience how the ENS Omnigraph API, enssdk, enskit, and full the stack of ENSNode services provide support to developers to become ENSv2 ready even before ENSv2 launches. Provides a superset of the data indexed by the ENS Subgraph. Offers a preview of ENS Protocol Acceleration." /> #### ENSNode 'Alpha-Sepolia' @@ -65,7 +65,7 @@ These ENSNode instances focus on pushing the boundaries of what's possible with connectWithENSAdminURL="https://admin.ensnode.io/connection?connection=https%3A%2F%2Fapi.alpha-sepolia.ensnode.io" namespace="sepolia" plugins="subgraph, basenames, lineanames, registrars, ensv2, protocol-acceleration" - purpose="Demonstration of ENSNode's multichain ENS indexing capability for an ENS namespace (sepolia) that is still operating ENSv1. Experience how the ENS Omnigraph API, enssdk, enskit, and full the stack of ENSNode services provide support to developers to become ENSv2 ready even before ENSv2 launches. Provides a superset of the data indexed by the ENS Subgraph. Offers a preview of ENS Protocol Acceleration." + purpose="Demonstration of ENSNode's multichain ENS indexing capability for an ENS namespace (sepolia) that is still operating ENSv1. Experience how the ENS Omnigraph API, enssdk, enskit, and full the stack of ENSNode services provide support to developers to become ENSv2 ready even before ENSv2 launches. Provides a superset of the data indexed by the ENS Subgraph. Offers a preview of ENS Protocol Acceleration." /> ### Subgraph-style Deployments diff --git a/docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx b/docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx index b4544b68c7..98ad0810bb 100644 --- a/docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx +++ b/docs/ensnode.io/src/content/docs/docs/services/ensindexer/contributing/creating-a-plugin.mdx @@ -10,14 +10,14 @@ import { LinkCard } from '@astrojs/starlight/components'; ## ENSIndexer Plugins -ENSNode is extensible through ENSIndexer plugins that implement custom indexing logic and produce custom indexed data models inside ENSDb. This allows you to tailor ENSNode to your specific use case and data needs. +ENSNode is extensible through ENSIndexer plugins that implement custom indexing logic and produce custom indexed data models inside ENSDb. This allows you to tailor ENSNode to your specific use case and data needs. ENSIndexer will only activate the plugins you specify in the `PLUGINS` env variable, so you can choose to only activate the plugins that are relevant to your use case. The `PLUGINS` env variable accepts a comma-separated list of plugin names to be activated. For example, if you want to activate the `ensv2` and `protocol-acceleration` plugins, you can set `PLUGINS=ensv2,protocol-acceleration`. ## Plugin Architecture -Each ENSIndexer plugin is a standalone TypeScript module that can be developed, tested, and deployed independently. Plugins can define their own indexed data models and indexing logic. It must include two main files: -- `event-handlers.ts`: This file defines the event handlers for the plugin, which are functions that will be called when specific onchain events are indexed. The event handlers contain the logic for how to process the indexed data and store it in the relevant indexed data model inside the ENSIndexer Schema. +Each ENSIndexer plugin is a standalone TypeScript module that can be developed, tested, and deployed independently. The ENSIndexer Plugin can define its own indexed data models and indexing logic. It must include two main files: +- `event-handlers.ts`: This file defines the event handlers for the plugin, which are functions that will be called when specific onchain events are indexed. The event handlers contain the logic for how to process the indexed data and store it in the relevant indexed data model inside the ENSIndexer Schema. - `plugin.ts`: This file defines the plugin itself, including its name, description, and any configuration options, like datasources to be used for specifying onchain contracts that will be indexed. ### Event handlers diff --git a/docs/ensnode.io/src/content/docs/docs/services/ensindexer/usage/management.mdx b/docs/ensnode.io/src/content/docs/docs/services/ensindexer/usage/management.mdx index bb154c1c9e..a12bac58eb 100644 --- a/docs/ensnode.io/src/content/docs/docs/services/ensindexer/usage/management.mdx +++ b/docs/ensnode.io/src/content/docs/docs/services/ensindexer/usage/management.mdx @@ -7,7 +7,7 @@ sidebar: ## Database operations -Each instance of ENSIndexer maintains its own ENSIndexer Schema instance in ENSDb. The same ENSIndexer instance will always use the same ENSIndexer Schema, even after restarts. However, if you need to update an ENSIndexer config, or deploy a new version of ENSIndexer, you will have to update the `ENSINDEXER_SCHEMA_NAME` env variable to point to a new schema, as otherwise, the ENSIndexer instance will detect that the ENSIndexer Schema was already owned by an ENSIndexer instance with different config / indexing logic and will refuse to start. These measures are taken to protect the state invariants indexing event handlers expect and require. +Each instance of ENSIndexer maintains its own ENSIndexer Schema instance in ENSDb. The same ENSIndexer instance will always use the same ENSIndexer Schema, even after restarts. However, if you need to update an ENSIndexer config, or deploy a new version of ENSIndexer, you will have to update the `ENSINDEXER_SCHEMA_NAME` env variable to point to a new schema, as otherwise, the ENSIndexer instance will detect that the ENSIndexer Schema was already owned by an ENSIndexer instance with different config / indexing logic and will refuse to start. These measures are taken to protect the state invariants indexing event handlers expect and require. ### ENSIndexer Schema lifecycle - Let's say you're currently running ENSNode version X that's indexing into `ENSINDEXER_SCHEMA_NAME=myschema_X` @@ -16,15 +16,19 @@ Each instance of ENSIndexer maintains its own ENSIndexer Schema instance in ENSD - Build a completely new index from scratch into `myschema_Y` which may grow to become 100+ GB depending on how ENSIndexer is configured. - Still retain all the data in `myschema_X` which could also be 100+ GB... - Now imagine you repeat this process across multiple updates to your `ENSINDEXER_SCHEMA_NAME`, you might have hundreds and hundreds of GB of ENSIndexer Schema instances no longer in use that are just taking up disk space in ENSDb instance until you completely run out of disk space. -- The solution is that you need to manually delete all the old `ENSINDEXER_SCHEMA_NAME` in your ENSDb instance you no longer use. +- The solution is that you need to manually delete all the old ENSIndexer Schema instances in your ENSDb instance you no longer use. ### Dropping orphaned ENSIndexer Schemas If your ENSDb instance has orphaned ENSIndexer Schemas that you no longer use, you can drop them with a SQL command like the following: +:::danger[`DROP SCHEMA ... CASCADE` is a destructive operation!] +Once executed, this operation is irreversible. Double-check your database connection and schema name before running this in production. + ```sql DROP SCHEMA myschema_X CASCADE; ``` +::: ### Dropping the RPC Cache From 38e2c081d09a16dc83bd153f6023a78af1ed8a73 Mon Sep 17 00:00:00 2001 From: Tomasz Kopacki Date: Thu, 14 May 2026 14:29:41 +0200 Subject: [PATCH 13/13] Apply AI PR feedback --- .../src/content/docs/docs/integrate/hosted-instances.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx b/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx index cee9bc402c..5ab490cd6b 100644 --- a/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx +++ b/docs/ensnode.io/src/content/docs/docs/integrate/hosted-instances.mdx @@ -41,7 +41,7 @@ These instances are associated with an ENS namespace that has upgraded to ENSv2 ## ENSv1 Instances -These instances are associated with an ENS namespace that has **NOT** upgraded to ENSv2 yet and are still operating under ENSv1. These demonstrate how the ENS Omnigraph API, enssdk, enskit, and full the stack of ENSNode services provide support to developers to become ENSv2 ready even before ENSv2 launches. +These instances are associated with an ENS namespace that has **NOT** upgraded to ENSv2 yet and are still operating under ENSv1. These demonstrate how the ENS Omnigraph API, enssdk, enskit, and the full stack of ENSNode services provide support to developers to become ENSv2 ready even before ENSv2 launches. ### Alpha-style Deployments @@ -55,7 +55,7 @@ These ENSNode instances focus on pushing the boundaries of what's possible with connectWithENSAdminURL="https://admin.ensnode.io/connection?connection=https%3A%2F%2Fapi.alpha.ensnode.io" namespace="mainnet" plugins="subgraph, basenames, lineanames, threedns, ensv2, protocol-acceleration, registrars, tokenscope" - purpose="Demonstration of ENSNode's multichain ENS indexing capability for an ENS namespace (mainnet) that is still operating ENSv1. Experience how the ENS Omnigraph API, enssdk, enskit, and full the stack of ENSNode services provide support to developers to become ENSv2 ready even before ENSv2 launches. Provides a superset of the data indexed by the ENS Subgraph. Offers a preview of ENS Protocol Acceleration." + purpose="Demonstration of ENSNode's multichain ENS indexing capability for an ENS namespace (mainnet) that is still operating ENSv1. Experience how the ENS Omnigraph API, enssdk, enskit, and the full stack of ENSNode services provide support to developers to become ENSv2 ready even before ENSv2 launches. Provides a superset of the data indexed by the ENS Subgraph. Offers a preview of ENS Protocol Acceleration." /> #### ENSNode 'Alpha-Sepolia' @@ -65,7 +65,7 @@ These ENSNode instances focus on pushing the boundaries of what's possible with connectWithENSAdminURL="https://admin.ensnode.io/connection?connection=https%3A%2F%2Fapi.alpha-sepolia.ensnode.io" namespace="sepolia" plugins="subgraph, basenames, lineanames, registrars, ensv2, protocol-acceleration" - purpose="Demonstration of ENSNode's multichain ENS indexing capability for an ENS namespace (sepolia) that is still operating ENSv1. Experience how the ENS Omnigraph API, enssdk, enskit, and full the stack of ENSNode services provide support to developers to become ENSv2 ready even before ENSv2 launches. Provides a superset of the data indexed by the ENS Subgraph. Offers a preview of ENS Protocol Acceleration." + purpose="Demonstration of ENSNode's multichain ENS indexing capability for an ENS namespace (sepolia) that is still operating ENSv1. Experience how the ENS Omnigraph API, enssdk, enskit, and the full stack of ENSNode services provide support to developers to become ENSv2 ready even before ENSv2 launches. Provides a superset of the data indexed by the ENS Subgraph. Offers a preview of ENS Protocol Acceleration." /> ### Subgraph-style Deployments