Subgraph

This is a page covering the graph's ENS subgraph. The ENS subgraph indexes onchain events of second-level .eth names, and DNS imported names. It allows us to build a reasonable approximation of the ENS names an address owns.

To read more about why not all names (such as Offchain & Gasless Names) show up in the subgraph read the listing names page.

The Graph

The Graph is a protocol for indexing and querying data from blockchains. There are multiple subgraphs that you can use to query information about ENS names. These subgraphs are available for mainnet, sepolia and holesky.

GraphQL Schema

The schema for the ENS subgraph is defined in /schema.graphql.

Use Cases

There are certain use cases where the graph is better for querying ENS specific information than through the resolution process. One of such use-cases is querying which NFT names are owned by a specific address.

Terminology

When using the subgraph, you may encounter registrant and controller fields. These were the old terminology for Owner and Manager respectively.

The registrant address is the owner of a name. It's the same value that will be returned from calling ownerOf() on the Base Registrar Controller (registrar.ens.eth). A registrant/owner may transfer ownership and assign a controller/manager.

The controller address is the manager of a name. It's the same value that will be returned from calling owner() on the ENS Registry (registry.ens.eth). A controller/manager may change the resolver of a name and set its records.

Example Queries

You can explore the following examples interactively via the Graph Explorer Playground

Getting a list of names owned by an account

Ensure the address is lowercase

query getDomainsForAccount {
  domains(where: { owner: "0xa508c16666c5b8981fa46eb32784fccc01942a71" }) {
    name
  }
}

Getting the top domain for an account based on the longest registry

query getDomainForAccount {
  account(id: "0xa508c16666c5b8981fa46eb32784fccc01942a71") {
    registrations(first: 1, orderBy: expiryDate, orderDirection: desc) {
      domain {
        name
      }
    }
    id
  }
}

returns

{
  "data": {
    "account": {
      "registrations": [
        {
          "domain": {
            "name": "datanexus.eth"
          }
        }
      ],
      "id": "0xa508c16666c5b8981fa46eb32784fccc01942a71"
    }
  }
}

Searching for a subdomain

query getSubDomains($Account: String = "messari.eth") {
  domains(where: { name: "messari.eth" }) {
    name
    id
    subdomains(first: 10) {
      name
    }
    subdomainCount
  }
}

returns

{
  "data": {
    "domains": [
      {
        "name": "messari.eth",
        "id": "0x498ada62251a1227664ace8d97b0de2dcc6652ddf61e6fb5d3150f43ccf599e6",
        "subdomains": [
          {
            "name": "subgraphs.messari.eth"
          },
          {
            "name": "bd.messari.eth"
          }
        ],
        "subdomainCount": 2
      }
    ]
  }
}

Getting the expiry of an ENS domain

query getDomainExp($Account: String = "paulieb.eth") {
  registrations(
    where: { domain_: { name: $Account } }
    first: 1
    orderBy: expiryDate
    orderDirection: desc
  ) {
    expiryDate
  }
}

returns

{
  "data": {
    "registrations": [
      {
        "expiryDate": "1714752524"
      }
    ]
  }
}