Description
A standard for profile information as text records in ENS
Status
draft
Created
2023-08-02
Authors
  • TateB
  • adraffy
  • galligan

ENSIP-18: Profile Text Records

Abstract

This ENSIP which extends ENSIP-5: Text Records defines a set of text records that should be used for profile information, along with the format that each should have.

Motivation

ENS names have become increasingly popular to use as an identifying profile across the Ethereum ecosystem. Although many apps have started integrating ENS "profiles", the only defined global text record keys are in ENSIP-5. These global keys were defined based on the usecase of ENS names at the time, and were not created with profiles in mind.

This specification extends the existing set of global keys, as well as creating a new subset within global keys called "profile keys".

Specification

The Profile Keys are a subset of Global Keys, the newly defined global keys are specified in the "Global Keys" section.

Profile Keys

alias

Description: A display alias

Format: Any text

Example: ENS

Design Considerations: This should be displayed near the ENS name, but should not be displayed as a replacement for it and should be below it in the visual hierarchy. You can also choose not to show the alias at all.

theme

Description: A user customised theme to use

Format: An array of comma separated hex colours. Order should be as follows: <background>,<text>,<accent>,<accentText>,<border>. Colours can be full or half length hex codes (e.g. FFFFFF, or FFF). A colour scheme can be incomplete but still valid by skipping a value similar to CSV (e.g. 000000,,F6F6F6,FFFFFF,FFF700)

Example: 3889FF,000,F6F6F6,FFFFFF,FFF700

Design Considerations: These colours can be used wherever a profile context is used (e.g. more than just the name), but separate colour schemes should never be used together on the same page. The scheme can also be extended to site-wide themability based on the primary name of the connected wallet. Selected accent and text colours should maintain a 4.5:1 contrast ratio against the selected background colour. Contrast ratio should be validated on record submission, as well as retrieval. If on retrieval colours do not meet the required contrast ratio, they should not be used. If the context requires that colours from a specific theme be used (e.g. an app theme), you can use the closest match to a colour in the theme.

Other Notes: If allowing a user to select a theme that is specific to one vendor (e.g. com.example), you should use a vendor specific version of this record e.g. com.example.theme

avatar

Description: An avatar image

Format: See ENSIP-12: Avatar Text Records

Example: See ENSIP-12: Avatar Text Records

Design Considerations: This should be displayed next to the ENS name wherever possible. The image should be displayed with an aspect ratio of 1:1. If the source doesn't match the target ratio, the image should be cropped from the centre to fill the ratio. The image should not have any visible blank space.

header

Description: A header image

Format: See ENSIP-12: Avatar Text Records

Example: See ENSIP-12: Avatar Text Records

Design Considerations: This should be displayed above all other profile content, or not at all. The image should be displayed with an aspect ratio of between 3:1 and 6:1. If the source doesn't match the target ratio, the image should be cropped from the centre to fill the ratio. The image should not have any visible blank space.

email

Description: An email that can be used as contact

Format: Standard email address

Example: test@example.com

Design Considerations: None.

description

Description: A biography

Format: Any string not exceeding 160 characters in length.

Example: Human readable names for Ethereum.

Design Considerations: None.

location

Description: A location

Format: Any location, if location is layered should use , for separation (e.g. Melbourne, Australia)

Example: Melbourne, Australia

Design Considerations: This value should not be assumed to be real coordinates or properly formatted place, as it may be a non-existent location

url

Description: A website URL

Format: Any valid HTTP or HTTPS link.

Example: https://ens.domains

Design Considerations: This link should be clickable, and wherever possible shown at the bottom of the profile.

timezone

Description: A timezone

Format: Any timezone name from the tz database. Follows <area>/<location>[/<quantifier>]

Example: Australia/Melbourne

Design Considerations: None.

language

Description: A language

Format: A two letter language code from ISO 639-1.

Example: en

Design Considerations: None.

primary-contact

Description: The record key for a primary contact

Format: email, or any existing profile service key

Example: com.github

Design Considerations: When resolving primary-contact for a profile, the value should resolve to the service (which could be logo or name) and the corresponding value. Direct links to the service should be supported on a best-effort basis (e.g. com.github => https://github.com/)

Global Keys

Profile Keys are a subset of Global Keys, therefore these global keys extend the existing global keys defined in ENSIP-5.

Profile Service Keys

A profile service key is a profile key derived from the root of the service's domain. E.g. com.github, org.telegram, etc.

When creating a profile service key record, the value should be void of optional service-specific formatting such as prefixes like /u/ or @.

In the case that the value is always displayed in a certain format, the formatting may be kept. However, any parsing or processing done on said value should attempt to be compatible with values that do not have the formatting applied.

Image files

When setting an image for an avatar or header, it is strongly recommended to limit the file size to an absolute maximum of 10MB. The image being set should be validated against this limit, whether it is a URL, or an NFT. Ideally, if creating an image to be set on behalf of the user, the file size should be limited to 2MB. Additionally, maintainers of image endpoints should support dimensions of images to be limited via query string ?width={width}&height={height} wherever possible.

When retrieving an image for an avatar or header, images should attempt to be loaded if 10MB or less in file size. Loading images above 10MB is not required, but ideally loading should still be attempted. If retrieving an image via URL, a query string can be optionally appended to the URL to limit the dimensions via ?width={width}&height={height}. However, the query string may have no effect.

Backwards Compatibility

The alias key replaces the pre-existing name key. When displaying an alias, you should consider also resolving the name key and displaying it, if alias is not available.

Security Considerations

None.

Copyright

Copyright and related rights waived via CC0.