Understanding ENS EIP-721: A Practical Overview

Introduction to ENS and EIP-721

The Ethereum Name Service (ENS) has fundamentally transformed how blockchain addresses are accessed and managed. At its core, ENS maps human-readable names like alice.eth to machine-readable identifiers such as Ethereum addresses, content hashes, and metadata. The integration of EIP-721 (the ERC-721 Non-Fungible Token standard) into ENS is not merely a technical convenience—it is a structural shift that treats domain ownership as transferable, composable digital assets.

EIP-721, standardized in 2018, introduced a uniform interface for NFTs on Ethereum. By adopting this standard, ENS domains became NFTs themselves. Each .eth name is now an ERC-721 token, meaning it can be bought, sold, and traded on any NFT marketplace that adheres to the standard. This interoperability unlocks liquidity for domain names, allowing them to be collateralized in DeFi protocols, displayed in wallet galleries, and tracked across block explorers. Understanding this integration is key for developers, domain investors, and protocol engineers who need to programmatically interact with ENS domains.

This article provides a practical, technical overview of ENS under EIP-721: how the standard maps to ENS domains, how metadata is structured, and how to query ownership history. We will cover the contract architecture, the tokenURI mechanism, and real-world query patterns using the ENS subgraph.

The ENS Registry and ERC-721 Contract Architecture

ENS operates through a two-component architecture: the registry and the resolver. The registry is a smart contract that maintains a mapping of domain name hashes (using the Namehash algorithm) to ownership records. Each domain name is hashed to a 256-bit "node" that identifies it uniquely. The registry records the owner, the resolver contract responsible for translating the node to an address, and the Time-to-Live (TTL) for caching.

By combining ENS with EIP-721, the ownership record in the registry is linked to an ERC-721 token ID. Specifically, the .eth registrar contract (the NFT contract) mints a token when a domain is registered. The token ID corresponds to the namehash of the domain. This means that the ERC-721 ownerOf(tokenId) function mirrors the ENS registry's owner(node) function. Any transfer of the ERC-721 token automatically updates the ENS registry ownership for that namehash, ensuring synchronization.

Key contract details:

• The ERC721Token contract (the .eth registrar) uses the standard IERC721 interface.
• Registration and renewal functions on the registrar mint and optionally extend token existence.
• The tokenURI function returns a URI that points to a JSON metadata document compliant with the ERC-721 metadata standard.
• Domain expiration is tracked via the ExpiryAware interface, not through the ERC-721 standard itself—expired tokens can be reclaimed by the registrar.

This dual-track management demands careful attention from developers: while the ERC-721 token is transferable at any time, the domain's resolver and records remain intact. If a domain is transferred, the new owner inherits all resolver settings until they choose to update them.

Metadata and tokenURI Structure

Every ENS domain that is an ERC-721 token exposes a tokenURI(uint256 tokenId) function. The returned URI (typically an IPFS or HTTP endpoint) points to a JSON object that describes the domain. The official ENS metadata format follows this structure:

{
  "name": "alice.eth",
  "description": "alice.eth, an ENS name.",
  "attributes": [
    {
      "trait_type": "Length",
      "value": 5
    },
    {
      "trait_type": "Label",
      "value": "alice"
    },
    {
      "trait_type": "Created Date",
      "display_type": "date",
      "value": 1640995200
    }
  ],
  "image": "ipfs://Qm..."
}

Attributes like length, label, and registration date are stored on-chain within the metadata contract. The image is typically a generated SVG that visualizes the domain name. Developers can use these attributes for filtering or sorting domains in applications.

The metadata contract is upgradeable and uses a helper contract to compute the tokenURI. Notably, the metadata is not stored directly inside the NFT contract to save gas; instead, the contract constructs the URI dynamically by referencing on-chain data. This means that querying the tokenURI for a large number of domains may require multiple RPC calls, which is inefficient at scale. Off-chain indexing via the ENS subgraph is strongly recommended for batch operations.

When building tools, be aware that the metadata image also includes the domain's expiration date visually. If you need to programmatically parse expiration data, use the subgraph rather than the image itself.

Practical Querying with Subgraphs and Tools

The most efficient way to query ENS domain ownership and metadata is through the ENS Subgraph, hosted on The Graph network. It indexes all registry, resolver, and registrar events, providing a GraphQL endpoint. Below is a practical breakdown of common queries.

1) Query a domain's owner and resolver

To find the current owner and resolver address for a specific domain, use this subgraph query:

{
  domains(where: {name: "alice.eth"}) {
    name
    owner {
      id
    }
    resolver {
      address
      addr {
        id
      }
    }
  }
}

This returns the owner's Ethereum address and the resolver contract's address, plus the resolved address if the resolver is set. For reverse resolution (finding a name from an address), you would use the address to name lookup flow. This can be executed manually through the ENS app or programmatically by querying the resolver's name(bytes32 node) function. For a streamlined implementation, you can integrate a dedicated address to name lookup service that abstracts away resolver calls and returns the primary ENS name for any address.

2) List all domains owned by an address

To retrieve the complete list of ENS names held by a wallet, query the registrations entity:

{
  registrations(
    where: {owner: "0x1234..."}
    orderBy: expiryDate
    orderDirection: asc
  ) {
    domain {
      name
    }
    expiryDate
  }
}

Note that the owner field in the Registration entity mirrors the ERC-721 owner. Expired registrations are still indexed but may be marked as expired after the grace period. For sub-second querying of large portfolios, precompute the ENS subgraph query results and cache them—subgraph queries have a 10-second timeout, so pagination is essential for wallets holding hundreds of names.

3) Historical ownership and transfer events

Because ENS domains are ERC-721 tokens, you can track transfer history using the transfer event on the registrar contract. The subgraph indexes these events in the Domain entity's owner history. Another approach is to query the ERC-721 contract directly using IERC721.events.Transfer from a client library like ethers.js or wagmi. The event log includes from, to, and tokenId—the tokenId is the namehash. Reconstructing the domain name from a namehash requires computing the reverse, which is not possible without storing the mapping. Therefore, always store the name-to-hash mapping locally or use the subgraph's hash-to-name resolution.

Tradeoffs and Considerations for Developers

Working with ENS under EIP-721 introduces specific tradeoffs that developers must consider:

• Token ID ≠ Human-readable name: The token ID is a bytes32 namehash, not the string "alice.eth". Converting between them requires the Namehash algorithm, which is computationally cheap but requires both representations to be stored in your database for efficient queries.
• Expiration handling: ERC-721 tokens are not automatically burned upon expiration. The domain enters a grace period (approximately 90 days), during which the original owner can renew. After that, the domain can be reclaimed by anyone via the registrar, but the token remains in existence until explicitly burned. This means a domain may be "owned" in the ERC-721 sense but functionally expired.
• Resolver upgrades: The resolver address is separate from the token ownership. A domain can be transferred to a new owner, but the resolver (which points to an ETH address) remains unchanged until the new owner updates it. This can cause confusion if users assume transferring the token automatically updates the resolved address.
• Gas costs: Registering a domain involves two transactions: one for the ETH payment and one for setting the resolver. Batching these via a multicall contract is recommended for high-volume operations. The ERC-721 transfer also costs gas, but the ENS registrar does not charge a separate fee for transfers.
• Metadata availability: The tokenURI for a domain is computed on-chain. If the underlying metadata contract is paused or updated, the URI may change. Always validate the metadata schema against the latest ENS documentation.

For applications that require real-time domain lookups, using a decentralized subgraph endpoint is strongly recommended. For latency-sensitive scenarios, consider running your own subgraph endpoint or caching resolved addresses in a local database. The ENS team provides a public subgraph endpoint, but rate limits apply at scale.

Conclusion

ENS under EIP-721 represents a powerful convergence of domain naming and NFT standards. By treating every .eth name as an ERC-721 token, the ecosystem gains liquidity, composability, and standardized tooling. Developers can leverage existing NFT infrastructure—marketplaces, wallets, and indexing services—without building custom domain management systems.

To integrate ENS into your application, start with the subgraph for bulk queries, use the registry contract for ownership validation, and handle expiration logic explicitly. The metadata contract provides human-readable descriptors, but always verify the data against on-chain records for critical operations. By understanding the ERC-721 integration layer, you can build robust applications that scale with ENS adoption.