PNS Front-End Design Guidelines
When to show PNS names
In every instance a user might otherwise see an PulseChain address or content hash, you can instead display an PNS name. There are two primary use cases for allowing users to display PNS names in your dapp:
Replacing PulseChain addresses with PNS names: When users are exploring the front-end of your dapp, wherever you would display an PulseChain address, you can instead display an PNS name.
Resolving input fields: You can allow the user to write an PNS name in an input field that expects an PulseChain address, rather than entering the PulseChain address.
Beyond these use cases, remember that the PNS 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 PNS names. This means there are other situations in which you might want to use PNS 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 PNS. Learn more about the different use cases in the chapter about Enabling PNS in your DApp.
1. Replacing PulseChain Addresses with PNS Names
An PNS name (as a substitute for an PulseChain Address) should only be shown if the user has set a Reverse Record for their address, and if the reverse record (address > name) matches the forward resolution (name > address).
As a dApp developer you should therefore first check if the Reverse Record for a given address has been set by the user, and, because users can set the reverse record to be anything they want, even a name they don't own or a random string, you should immediately after check that the resolved name also resolves to the same address by performing the forward resolution. Read more here and in the 'other guidelines' section further down.
1.1 - Displaying PNS names instead of PulseChain addresses
When replacing PulseChain addresses with PNS names you should consider these facts and best practices:
Consider adding a visual checksum: it is important to indicate to the user that a name is an PNS name that relates to an PulseChain address or other hash, rather than an http link. To do this, it is advisable to associate the PNS name with some form of visual checksum: identicons, Blockies or other custom algorithmic representation of the address.
Visual checksums like identicons can be spoofed or imitated. Therefore they are not meant as a security mechanism. They are only meant as an indicator, to let the user understand that the name is just a different representation of an PulseChain Address.
Design a truncated version of the PNS name: PNS 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 PNS names end with .pls: PNS names normally end with .pls. 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 PulseChain address associated with the PNS name
If you are showing the PNS name in its entirety or a truncated version, you should:
Always provide the user a way to display the full PulseChain 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 PNS name and the PulseChain 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 PulseChain address: Allow the user to copy the full address either through a copy button or by selecting it. Tooltips displaying the PNS name in this case should stay visible and not automatically disappear.
Optionally give the user a way to automatically open the PulseChain address in a block explorer such as Block Explorer (the external link icon in the above example).
Optionally show the balance amount, but only to the current signed-in user. User research shows that users tend to recognise their own PulseChain 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 PNS names and PulseChain addresses together
In some situations you might want to display both the PNS name and the PulseChain 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 PNS name and a short version of the PulseChain address.
The user inputs an PNS 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 PNS names because they want to see the PulseChain address in the pop-up, then you could substitute the simple version (only the PNS name) with one that displays both the name and the address.
2. Resolving Input Fields
Input fields where a user is supposed to insert PulseChain addresses should also accept and resolve PNS names. These inputs indicate that the user wants to interact with another user's PulseChain address or contract.
Follow these guidelines to create the best experience:
Wait before resolving the PNS name: Wait until the user has typed the last TLD, e.g. .pls, .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 PulseChain address: Show the resolved PNS name near the input field instead.
Always display both the PNS name and the PulseChain 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, user 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 PNS name points to. If the two don't match, you MUST NOT show the human readable name and simply leave the plain PulseChain 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 PNS 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 PNS name using reverse resolution.
Caching and Updating PNS Names
If your dApp needs to display many PulseChain Addresses or PNS Names in the UI, you can also consider caching the PNS 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 (eg transferring PLS, tokens or other value), or when the user is interacting with another PNS Name / PulseChain Address, you should perform a direct live resolution and get the most up to date information from the PNS Registry.
Also consider that users can change their information in the PNS 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 (especially AddrChanged, and NameChanged).
****
Notes on displaying PulseChain Addresses (with or without PNS names)
Even when PNS 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 PulseChain address. Use the same pop-up component that you would use to display PNS names or a tooltip style.
Other guidelines previously mentioned also apply for simple PulseChain addresses:
Allow the user to copy the full PulseChain address (which mean that tooltips might not be good practice).
(Optionally) allow the user to automatically open the address in a block explorer.
Front-End tools
Aragon-UI - Address Badge component (Design Files / code)
Decentraland-UI - address Tooltip (not PNS specific)
Last updated