Skip to content
ENSNode

What is the ENS Subgraph?

Skip to 'What is ENSNode?' If you already know what the ENS Subgraph is, skip ahead.

The Graph & Graph Node

Section titled “The Graph & Graph Node”

The Graph leads development of Graph Node, an open source software application for indexing blockchain data.

Subgraphs

Section titled “Subgraphs”

Each Graph Node server can run any number of “subgraphs”. Each subgraph is essentially a plugin describing:

  1. A strategy for how the Graph Node should index blockchain data.
  2. A schema for a GraphQL API providing access to the indexed data.

ENS Subgraph

Section titled “ENS Subgraph”

ENS Labs has led development of the ENS Subgraph. In the past, this was the “official” strategy for indexing ENS data. Additional background info is available in official ENS docs.

Graph Network

Section titled “Graph Network”

Operating your own Graph Node server instance can be complex, expensive, and time consuming. An alternative is to use The Graph’s semi-decentralized network of indexers operating Graph Node instances.

This network provides access to a semi-decentralized ENS Subgraph. Developers are welcome to use this rate limited API endpoint above for testing, but are highly encouraged to sign up for an account with The Graph to get their own (paid) API key.

ENSNode’s Backwards Compatibility with the ENS Subgraph

Section titled “ENSNode’s Backwards Compatibility with the ENS Subgraph”

To support the ENS ecosystem’s transition away from legacy ENS indexing strategies to ENSNode, ENSNode provides a verified backwards compatible ENS Subgraph GraphQL endpoint. This therefore also provides backwards compatibility with ensjs.

  1. For those that wish to host their own ENS indexer, it is faster and easier to deploy ENSNode than to run an ENS Subgraph instance.
  2. For those building an app that simply want to query the legacy ENS Subgraph API in the easiest way possible, we make this freely available through our hosted ENSNode instances.

Self-hosted ENSNode instance configuration for ENS Subgraph compatibility

Section titled “Self-hosted ENSNode instance configuration for ENS Subgraph compatibility”

To enable full ENS Subgraph compatibility on a self-hosted ENSNode instance, configure ENSIndexer with SUBGRAPH_COMPAT=true. This single flag:

  1. Applies Subgraph Indexing Behavior: Uses Subgraph Interpreted Labels and Names, allowing unnormalized labels to be returned as they appear in the original ENS Subgraph
  2. Sets Default Plugins & Label Set: Defaults to PLUGINS=subgraph, LABEL_SET_ID=subgraph and LABEL_SET_VERSION=0 to match subgraph indexing logic and label healing behavior

When SUBGRAPH_COMPAT=false (default), ENSIndexer operates in enhanced mode with:

  • Enhanced Indexing Behavior: Uses Interpreted Labels and Names with improved security by encoding unnormalized labels as labelhashes
  • Expanded Plugin Support: Defaults to PLUGINS=subgraph,basenames,lineanames,threedns,protocol-acceleration,registrars,tokenscope for multichain ENS indexing
  • Reverse Address Healing: Attempts to heal subnames of addr.reverse for enhanced reverse resolution support

Compatibility Tooling

Section titled “Compatibility Tooling”

ENSNode has developed tooling to verify subgraph compatibility and ease migration from the ENS Subgraph.

Subgraph Compatibility Tooling

Subgraph-Compatible GraphQL API Reference

Section titled “Subgraph-Compatible GraphQL API Reference”

Supported Features

Section titled “Supported Features”

The feature set used by ensjs and ens-app-v3 is fully supported: see the well-known queries section below.

Planned Features

Section titled “Planned Features”

Possible Features

Section titled “Possible Features”

The following features could be implemented, but are not yet planned.

Unplanned Features

Section titled “Unplanned Features”

The following features of the subgraph graphql api are explicitly unsupported and are not planned.

Well-Known Queries

Section titled “Well-Known Queries”

These are some of the popular queries we’ve seen in the wild (namely via ENSjs and ens-app-v3)—the Subgraph-compatible GraphQL API includes full compatibility with these use-cases (and all other possible queries with the exceptions listed above).

from ensjs

Section titled “from ensjs”
  • getDecodedName — Gets the full name for a name with unknown labels from the subgraph
    • Heals encoded labels using the subgraph
    • Returns if name is fully decoded
    • Splits name into labels
    • Finds domains by id for encoded labels
    • Queries domain by namehash
  • getNameHistory
    • Retrieves all events associated with a name
  • getNamesForAddress
    • Gets all names related to an address via registrant, owner, wrappedOwner, resolvedAddress
    • Supports searchString
    • Supports filtering by expiry, reverse records, empty domains
    • Supports ordering by expiry date, name, labelName, createdAt
    • Supports pagination by excluding previous results
  • getSubgraphRecords — Gets the records for a name from the subgraph
    • Allows querying by specific resolver id
  • getSubgraphRegistrant — Gets the name registrant from the subgraph
    • Supports .eth second-level domains only
  • getSubnames — Gets the subnames for a name
    • Supports searchString
    • Supports filtering by expiry, empty domains
    • Supports ordering by expiry date, name, labelName, createdAt
    • Supports pagination by excluding previous results

from ens-app-v3

Section titled “from ens-app-v3”