ENS Subnames Explained: Building Identity Systems on Ethereum

ENS names like vitalik.eth are the most visible part of the Ethereum naming system, but they're just the tip of the iceberg. ENS supports an infinite hierarchy of subnames — names nested under a parent, like alice.myprotocol.eth or user123.coolapp.eth. Subnames have become the foundation of Web3 identity systems, letting protocols assign human-readable names to users at scale.

What Are ENS Subnames?

An ENS subname is any name with more than one label separated by dots. If you own myprotocol.eth, you control the entire namespace under it — you can create alice.myprotocol.eth, bob.myprotocol.eth, and any other subname you like, either directly or by deploying a custom resolver that handles the logic programmatically.

From the resolver's perspective, subnames resolve identically to top-level names. A client calls addr(namehash("alice.myprotocol.eth")) and gets back an Ethereum address. The resolution path is the same; only the data source differs.

On-Chain vs Off-Chain Subnames

There are two fundamental approaches to issuing subnames:

On-Chain Subnames

On-chain subnames are stored directly in the ENS Registry on Ethereum mainnet. Each subname is a separate registry entry, and setting records (like an address) requires a transaction. This approach provides the strongest guarantees — every record is verifiable onchain — but comes with gas costs for each issuance and update.

Off-Chain Subnames (CCIP-Read)

Off-chain subnames use CCIP-Read (EIP-3668), a standard that allows an ENS resolver to redirect resolution requests to an external HTTPS endpoint. The parent name owner deploys a resolver that points to their own API. When a client resolves alice.myprotocol.eth, the resolver tells the client to fetch data from https://api.myprotocol.xyz/ens/{sender}/{data}.json and verify the response signature.

Off-chain subnames are essentially free to issue — no gas required per user. The trade-off is that the data is managed by a centralized server, though the resolver can enforce signature verification to prevent tampering.

Use Cases for Subnames

• Protocol identity: Give each user a name like alice.uniswap.eth tied to their account
• NFT communities: Issue 0001.bayc.eth to token holders
• DAOs: Assign alice.compound.eth to governance participants
• Gaming: Player usernames like wizard.mygame.eth with in-game metadata in text records
• Enterprise: Department identities like payments.company.eth for smart contract routing

How Subname Resolution Works

For onchain subnames, the resolution is straightforward — the ENS Registry has a direct entry. For offchain subnames, the process involves one extra step:

1. Client calls the resolver contract with the subname's namehash
2. Resolver returns an OffchainLookup error containing a gateway URL
3. Client fetches signed data from the gateway URL
4. Client calls the resolver again with the signed response
5. Resolver verifies the signature and returns the record

Resolvio handles this entire flow automatically. Whether a subname is onchain or offchain, you make the same API call and get the same response format.

Resolving Subnames with Resolvio

The Resolvio API resolves subnames with zero configuration — just pass the full name:

# Resolve an offchain subname
curl https://api.resolvio.xyz/ens/v2/profile/alice.namespace.eth

# Resolve an onchain subname on an L2
curl https://api.resolvio.xyz/ens/v2/profile/user.linea.eth

{
  "name": "alice.namespace.eth",
  "address": "0xAbC123...",
  "avatar": "https://example.com/avatar.png",
  "records": {
    "com.twitter": "aliceeth",
    "description": "Web3 developer"
  }
}

Building Your Own Subname System

If you want to issue subnames under your own .eth name, Namespace provides the infrastructure — offchain resolvers, issuance APIs, and management tooling — so you can launch a subname program without deploying custom smart contracts. Resolvio will resolve your subnames out of the box once you're set up.