Domains Front-End Design Guidelines

Domains is a tool to simplify the experience for your users. Here are a series of guidelines and tools that will help you make design choices and implement the best Domains user experience.

When to show Domains names

In every instance a user might otherwise see an Ethereum address or content hash, you can instead display a Domains name.

There are two primary use cases for allowing users to display Domains names in your DApp:

• Replacing Ethereum addresses with Domains names: When users are exploring the front-end of your DApp, wherever you would display an Ethereum address, you can instead display an Domains name.

• Resolving input fields: You can allow the user to write an Domains name in an input field that expects an Ethereum address, rather than entering the Ethereum address.

Beyond these use cases, remember that the Domains Public Resolver allows you to link different kinds of resources, such as content stored on IPFS or Swarm, or any arbitrary data like text fields, to Domains names. This means there are other situations in which you might want to use Domains in your DApp. For example, if you are using complicated IPFS or Swarm hashes it is possible to convert the hashes to human readable names using Domains. Learn more about the different use cases in the chapter about Enabling Domains in your DApp.

1. Replacing Ethereum Addresses with Domains Names

1.1 - Displaying Domains names instead of Ethereum addresses

• Consider adding a visual checksum: it is important to indicate to the user that a name is a Domains name that relates to an Ethereum address or other hash, rather than an http link. To do this, it is advisable to associate the Domains name with some form of visual checksum: identicons, Blockies or other custom algorithmic representation of the address.

• Design a truncated version of the Domains name: Domains names can be very long; besides not being character-limited, users can create an infinite number of subdomains and subdomains of subdomains. If you do show a truncated version of the name, you should provide a way to view the full name, such as expanding it on hover.

• Not all Domains names end with .tomi: Domains names normally end with .tomi. However other top-level domains (TLD) are currently supported (.xyz, .luxe, .kred, .art, .club) and more will be in the future. Consider this if you are thinking about displaying the TLD part in the truncated view of long names.

1.2 - Always provide an option to see the Ethereum address associated with the Domains name

If you are showing the Domains name in its entirety or a truncated version, you should:

• Always provide the user a way to display the full Ethereum address: The above example illustrates a pop-up option. Another option would be to use a tooltip. However, consider that floating / pop-ups may be more appropriate than tooltips because the former also supports the other features described here.

• Provide a view where you display both the Domains name and the Ethereum address together: If the pop-up hides the name and only shows the address it's less friendly than showing both at the same time.

• Allow the user to copy the full Ethereum address: Allow the user to copy the full address either through a copy button or by selecting it. Tooltips displaying the Domains name in this case should stay visible and not automatically disappear.

• Optionally give the user a way to automatically open the Ethereum address in a block explorer such as Ethereum

• Optionally show the balance amount, but only to the current signed-in user. User research shows that users tend to recognise their own Ethereum address through their balance, as well as the address itself. This is meant only for the currently "signed in" user: only show their own balance and avoid showing the balance of other users.

1.3 - Displaying Domains names and Ethereum addresses together

In some situations you might want to display both the Domains name and the Ethereum address to which it resolves. These layouts can be useful when:

• Displaying the currently connected user: For the user badge, for example, it could be appropriate to display both the Domains name and a short version of the Ethereum address.

• The user inputs an Domains name into an input field: This will be described in greater detail in the next chapter that discusses input field resolution.

• In other high-risk situations: These are situations where the user wants to confirm who a given user/address is, or if you notice that your users keep clicking Domains names because they want to see the Ethereum address in the pop-up, then you could substitute the simple version (only the Domains name) with one that displays both the name and the address.

2. Resolving Input Fields

Input fields where a user is supposed to insert Ethereum addresses should also accept and resolve Domains names. These inputs indicate that the user wants to interact with another user's Ethereum address or contract.

Follow these guidelines to create the best experience:

• Wait before resolving the Domains name: Wait until the user has typed the last TLD, e.g. .tomi, .xyz, .luxe or .kred before resolving the name. Alternatively wait until 0.2 - 1.0 seconds after the user has stopped typing in the input field (avoid the eager resolution problem).

• Don't overwrite the input field with the Ethereum address: Show the resolved Domains name near the input field instead.

• Always display both the Domains name and the Ethereum address together : Do this after it has successfully been resolved and possibly add also a visual checksum following the suggestions in guideline 1.1.

Other guidelines and tips

What to do if the Reverse Record doesn't correspond to the Forward Resolution?

As mentioned before, users can set the Reverse Record to be anything they want, even a name owned by another user or a completely random string. This is why, after retrieving the name written in the Reverse Record, a dApp developer should also check that it matches the forward resolution, which means the address that Domains name points to.

If the two don't match, you MUST NOT show the human readable name and simply leave the plain Ethereum Address. If you don't, users may be able to impersonate other users in your dApp.

The chapter on Reverse Resolution has code for you to do this check.

Options for displaying usernames

The obvious choice is to use the user's Domains name as a username. You can do this by providing a mechanism for your users to register a name under your own subdomain, or by looking up the user's Domains name using reverse resolution.

Caching and Updating Domains Names

If your dApp needs to display many Ethereum Addresses or Domains Names in the UI, you can also consider caching the Domains Name after it has been resolved (and verified) or after the user has added the name in an input field.

Your optimistic UI can safely display the names from cache in all non-risky situations, in which your user for example is simply browsing, but doesn't need to act or make decisions, especially risky ones, based on the information displayed.

However, in all risky situations (e.g. transferring TOMI, tokens or other value), or when the user is interacting with another Domains Name / Ethereum Address, you should perform a direct live resolution and get the most up to date information from the Domains Registry.

Also consider that users can change their information in the Domains registry at any time so you should periodically validate the information you cached. For this you can also subscribe to certain Events made available by the contracts.

****

Notes on displaying Ethereum Addresses (with or without Domains names)

Even when Domains names are not available, research shows that there are some good practices to follow when displaying Ethereum addresses in dApps.

• Always show the initial ' 0x ' to indicate it's an address.

• When displaying the name in shorthand versions, show the first 4 and last 4 characters of the address. This is not a security requirement as vanity addresses can be spoofed relatively simply; this is a good practice because some users check the beginning of the name and others check the end of the name. Also, four is the highest number of elements that our mind can easily chunk, parse and remember well.

• Always provide a way to display the full Ethereum address. Use the same pop-up component that you would use to display Domains names or a tooltip style.

Other guidelines previously mentioned also apply for simple Ethereum addresses:

• Allow the user to copy the full Ethereum address (which means that tooltips might not be good practice).

• (Optionally) allow the user to automatically open the address in a block explorer.