ERC-634 Storing ENS text records (Storage of text records in ENS)

Stagnant · Names & metadata · created 2017-05-17

A resolver profile that lets you store and retrieve arbitrary key-value text data, such as email, avatar, social media accounts, or URLs, on an ENS name.

Why it is needed

ENS names were originally meant to link machine-readable data, like an Ethereum address or content hash, to a name that humans can easily remember. But there was no standardized way to store and retrieve human-readable supplementary information, such as an email address, avatar image, bio, or social media account, that is useful for debugging, operations, or guidance. Without a standard, every service ends up storing metadata in its own way, and wallets or apps have no way of knowing in advance which key to query for which value, making it hard to use ENS names as general-purpose profiles. Extensibility also suffers if the resolver itself has to change every time a new service appears.

What to implement

In depth

Resolver interface and ERC-165

This standard defines the resolver interface IERC634, consisting of a single function, text(bytes32 node, string key). node is the node hash of the ENS name, and key is the key to query. The return value is an arbitrary UTF-8 string, and if the key does not exist, an empty string must be returned. The ERC-165 interface ID for this interface is 0x59d1d43c, and a resolver can use this ID to announce support for the text function.

Global keys

Global keys consist only of lowercase letters, digits, and hyphens (-). The keys defined in the source are avatar (avatar image URL), description (a description of the name), display (the canonical display name including case, which must match the ENS name when case-folded, otherwise clients must ignore it), email (email address), keywords (a comma-separated list of keywords in order of importance), mail (physical mailing address), notice (a notice about the name), location (region, e.g. Toronto, Canada), phone (phone number in E.164 format), and url (website URL).

Service keys and reverse dot notation

Service keys consist of reverse dot notation for a namespace owned by that service, and can use a DNS name (.com, .io, etc.) or an ENS name (.eth). A service key must contain at least one dot. This approach lets new services use their own keys without worrying about colliding with existing services, and means this document does not need to be updated every time a new service is added. The source recommends examples such as com.github, com.peepeth, com.linkedin, com.twitter, io.keybase, and org.telegram, and notes that sub-level keys like com.example.users can also be constructed.

Legacy keys

Earlier drafts of this standard used the keys vnd.github (now com.github), vnd.peepeth (now com.peepeth), and vnd.twitter (now com.twitter). The source notes that use of these is likely not widespread, but advises that applications seeking maximum compatibility may fall back to querying these legacy keys if a lookup under the new keys fails.

Why a general-purpose key-value structure was chosen

The source explains that rather than defining a dedicated record type for each piece of human-readable data, such as url or email, it adopted a general-purpose key-value structure modeled after a variant of DNS TXT records. This approach allows keys to be extended in the future without changing the resolver interface, while also letting applications use their own custom keys.

Proposal status

This ERC is currently in Stagnant status, a proposal written in 2017 that has not seen further discussion since. The source itself notes in the Legacy Keys section that the document was still in draft stage, so the list of keys or the specification may change in the future, or may simply never be updated again.

Original ERC · ← ERCs