Skip to content

ENSIP-12: Avatar Text Records

Authors: nick.eth, matoken.eth

Created: January 18, 2022

Status: final

A standard for storage of the avatar text record in ENS.

Abstract

This ENSIP defines a process for retrieving avatar URIs from ENS, several URI schemes for the ENS 'avatar' text field, and how they should be interpreted by clients wishing to display a user's avatar image.

Motivation

ENS primary name (formerly known as reverse record) has been widely integrated as a de facto web3 user name across many Ethereum based applications. As multiple apps started specifying avatar profile image as well as let users pick NFT as pfp (profile image), it became obvious to store such information within ENS so that the avatar information can be shared across different applications.

This specification standardises a way to store and retrieve this information using ENSIP-5: Text Records

Specification

Retrieving the avatar URI

The process for retrieving the avatar URI depends on whether the client has an Ethereum address or an ENS name to start with.

ENS Name

To determine the avatar URI for an ENS name, the client MUST first look up the resolver for the name and call .text(namehash(name), 'avatar') on it to retrieve the avatar URI for the name.

The client MUST treat the absence of a resolver, an revert when calling the addr method on the resolver, or an empty string returned by the resolver identically, as a failure to find a valid avatar URI.

Ethereum Address

To determine the avatar URI for an Ethereum address, the client MUST reverse-resolve the address by querying the ENS registry for the resolver of <address>.addr.reverse, where <address> is the lowercase hex-encoded Ethereum address, without leading '0x'. Then, the client calls .text(namehash(<address>.addr.reverse'), 'avatar') to retrieve the avatar URI for the address.

If a resolver is returned for the reverse record, but calling text causes a revert or returns an empty string, the client MUST call .name(namehash('<address>.addr.reverse')). If this method returns a valid ENS name, the client MUST:

  1. Validate that the reverse record is valid, by resolving the returned name and calling addr on the resolver, checking it matches the original Ethereum address.
  2. Perform the process described under 'ENS Name' to look for a valid avatar URI on the name.

A failure at any step of this process MUST be treated by the client identically as a failure to find a valid avatar URI.

General Format

The 'avatar' text field MUST be formatted as a URI. Clients MUST ignore URI types they do not recognise, treating them the same as if no value was set for the field.

Image Types

Clients MUST support images with mime types of image/jpeg, image/png, and image/svg+xml. Clients MAY support additional image types.

URI Types

All clients SHOULD support the URI schemes defined below. They MAY implement additional schemes not defined in this specification.

https

If an https URI is provided, it MUST resolve to an avatar image directly. https URLs MUST NOT resolve to HTML pages, metadata, or other content containing the avatar image.

ipfs

If an ipfs URI is provided, it MUST resolve to an avatar image directly. Clients without built-in IPFS support MAY rewrite the URI to an https URL referencing an IPFS gateway as described in this document before resolving it as an https URL.

data

If a data URL is provided, it MUST resolve to an avatar image directly.

NFTs

A reference to an NFT may be used as an avatar URI, following the standards defined in CAIP-22 and CAIP-29.

Clients MUST support at least ERC721 and ERC1155 type NFTs, and MAY support additional types of NFT.

To resolve an NFT URI, a client follows this process:

  1. Retrieve the metadata URI for the token specified in the avatar field URI.
  2. Resolve the metadata URI, fetching the ERC721 or ERC1155 metadata.
  3. Extract the image URL specified in the NFT metadata.
  4. Resolve the image URL and use it as the avatar.

Clients MUST support at least https and ipfs URIs for resolving the metadata URI and the avatar image, and MAY support additional schemes. Clients MAY implement ifps scheme support by rewriting the URI to an HTTPS URL referencing an IPFS gateway as described above.

Clients SHOULD additionally take the following verification steps:

  1. Where the avatar URI was retrieved via forward resolution (starting from an ENS name), call the addr function on the same resolver and for the same name to retrieve the Ethereum address to which the name resolves. Otherwise, if the avatar URI was retrieved via reverse resolution (starting from an Ethereum address), use that address.
  2. Verify that the address from step 1 is an owner of the NFT specified in the URI. If it is not, the client MUST treat the URI as invalid and behave in the same manner as they would if no avatar URI was specified.

Clients MAY support NFT URIs by rewriting them to https URIs for a service that provides NFT avatar image resolution support.

Examples

The following examples all resolve to the same avatar image:

eip155:1/erc721:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/0 # BAYC token 0
ipfs://QmRRPWG96cmgTn2qSzjwr2qvfNEuhunv6FNeMFGa9bx6mQ # IPFS hash for BAYC token 0 image
https://ipfs.io/ipfs/QmRRPWG96cmgTn2qSzjwr2qvfNEuhunv6FNeMFGa9bx6mQ # HTTPS URL to IPFS gateway for BAYC token 0 image

Backwards Compatibility

Not applicable.

Security Considerations

None.

Copyright

Copyright and related rights waived via CC0.