LNS Front-End Design Guidelines

LNS 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 LNS user experience.

When to show LNS names

In every instance a user might otherwise see an smartBCH address or content hash, you can instead display an LNS name. There are two primary use cases for allowing users to display LNS names in your dapp:

1. Replacing smartBCH addresses with LNS names: When users are exploring the front-end of your dapp, wherever you would display an smartBCH address, you can instead display an LNS name.

2. Resolving input fields: You can allow the user to write an LNS name in an input field that expects an smartBCH address, rather than entering the smartBCH address.

Beyond these use cases, remember that the LNS 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 LNS names. This means there are other situations in which you might want to use LNS 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 LNS. Learn more about the different use cases in the chapter about Enabling LNS in your DApp.

1. Replacing smartBCH Addresses with LNS Names

An LNS name (as a substitute for an smartBCH 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 LNS names instead of smartBCH addresses

example of showing just the name and the visual checksum

When replacing smartBCH addresses with LNS 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 LNS name that relates to an smartBCH address or other hash, rather than an http link. To do this, it is advisable to associate the LNS 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 smartBCH Address.

• Design a truncated version of the LNS name: LNS 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 LNS names end with .bch: LNS names normally end with .bch. 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 smartBCH address associated with the LNS name

by clicking the name, this expanded pop-up appears showing the name with the full address

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

• Always provide the user a way to display the full smartBCH 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 LNS name and the smartBCH 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 smartBCH address: Allow the user to copy the full address either through a copy button or by selecting it. Tooltips displaying the LNS name in this case should stay visible and not automatically disappear.

• Optionally give the user a way to automatically open the smartBCH address in a block explorer such as Etherscan (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 smartBCH 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 LNS names and smartBCH addresses together

example of names with the address visible at the same time

In some situations you might want to display both the LNS name and the smartBCH 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 LNS name and a short version of the smartBCH address.

• The user inputs an LNS 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 LNS names because they want to see the smartBCH address in the pop-up, then you could substitute the simple version (only the LNS name) with one that displays both the name and the address.

2. Resolving Input Fields

when resolving an input show both the LNS name and the Address together

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

Follow these guidelines to create the best experience:

• Wait before resolving the LNS name: Wait until the user has typed the last TLD, e.g. .bch, .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 smartBCH address: Show the resolved LNS name near the input field instead.

• Always display both the LNS name and the smartBCH 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 LNS name points to. If the two don't match, you MUST NOT show the human readable name and simply leave the plain smartBCH 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 LNS 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 LNS name using reverse resolution.

Caching and Updating LNS Names

If your dApp needs to display many smartBCH Addresses or LNS Names in the UI, you can also consider caching the LNS 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 BCH, tokens or other value), or when the user is interacting with another LNS Name / smartBCH Address, you should perform a direct live resolution and get the most up to date information from the LNS Registry.

Also consider that users can change their information in the LNS 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 smartBCH Addresses (with or without LNS names)

Even when LNS names are not available, research shows that there are some good practices to follow when displaying smartBCH 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 smartBCH address. Use the same pop-up component that you would use to display LNS names or a tooltip style.

decentralandUI Tooltip showing the full Address

Other guidelines previously mentioned also apply for simple smartBCH addresses:

• Allow the user to copy the full smartBCH 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 LNS specific)