Proposal: User defined preference for address → name resolution order

[qrtp]

At Unstoppable Domains we recently released XMTP chat clients on our website and mobile apps. A concern we're hearing from many users is that the current XMTP user experience is confusing due to inconsistent wallet display name rendering across different client apps. Since XMTP as a protocol cares about wallet address (as it should) and displaying the user name is pushed to the client (as it should), it can lead to an inconsistent user experience as user interacts with different parts of the web3 ecosystem. Each app has it's own way and priority of resolving the wallet address to a user name.

Example

Let me provide an example that might help clarify the problem.

• My wallet 0xcd0dadab45baf9a06ce1279d1342ecc3f44845af has many domains from different naming systems
  • ENS aaronquirk.eth
  • Unstoppable Domains quirk.x
  • Lens 5quirks.lens
  • And more...
• Here's a list of how my name shows up in different XMTP clients
  • Converse, xmtp.chat, Coinbase Wallet - aaronquirk.eth
  • Lenster - 5quirks
  • Unstoppable Domains website, mobile app - quirk.x

Problem discussion

As the same wallet owner, my identity appears quite fragmented across web3 clients. While my chat history stays portable and attached to my singular wallet address, from a user experience my display name seems very inconsistent. I have no control. As a developer, I totally understand why it's like this and it doesn't bother me because I know how it's working behind the scenes. But as a user (and we've been hearing it a lot) it appears like "I'm trying to chat as domain X but I'm showing up as domain Y" to my friend on this other app. They don't know it's me, and there's no way for me to have control of my display name.

Let me be clear, I agree with the wallet address being the identifier at the protocol level and push naming resolution and display responsibilities to the client. However, I think giving a configuration for display preference to the XMTP account owner would be incredibly powerful. We have to be careful here. We definitely don't want to offer the configuration of a free form string like "display name=my name" that the user can set arbitrarily. This would open up clients to the risk of user impersonation, allowing the user to set a nefarious display name that's not derived from their wallet address. The display name must be resolved from a value on-chain using the wallet address.

Proposal

What I propose is a naming system display order suggestion, configurable by the wallet owner that can be optionally used by XMTP clients as a hint as to how to display the user's name. The values could be a typed enum. I'm picturing code kind of like this:

export enum NamingSystem {
  ENS = "ens",
  UnstoppableDomains = "ud",
  Lens = "lens",
}

export interface XmtpProfile {
  displayNameOrder: NamingSystem[];
}

On the XMTP client side, this display name preference could then be queried when retrieving the XMTP account. The name resolution and display would still happen at the client side as it does today, but the user has the ability to suggest their preferred order for them to be identified. If I set displayOrder=["ud", "ens", "lens"] for my XMTP account 0xcd0dadab45baf9a06ce1279d1342ecc3f44845af (and the client respects my preference) then I can identify as quirk.x as a common name across apps. If I change my order to ["ens", "lens", "ud"] then I can now start identifying as aaronquirk.eth across the same apps.

I think this approach strikes a balance of giving user power to request a display preference, and the client app to either respect that request or not depending on the application needs and context. But at least having a standard in place gives the possibility of consistency that does not exist right now. I think for wider adoption something like this will be required, especially with non-crypto-native users that we want to see entering the space.

I also think that apps will support this type of preference, because it will improve the user experience. As an app owner, I would be more than happy to show the user's name as name.lens if I know that's what they would like to do. If they see a name that is familiar and they identify with, they are more likely to stay engaged which is good for us as a project. I think most projects will share the sentiment and get behind a standard.

Related discussions

This discussion on Identity to identity messaging #24 is related to this proposal, but has a slightly different level of abstraction for identity. In the other approach, every conversation might have a different display name for "who I am talking to" and the display name decision is left to the user starting the conversation. In other words, as the user starting the conversation when I search for aaronquirk.eth (vs quirk.x in the same wallet) my XMTP client would store metadata in the conversation that aaronquirk.eth is the display name of my conversation peer.

My proposal puts that initial preference of displayed name in the hands of the wallet owner, and at a higher account level vs. conversation level of abstraction. Once that initial display name decision is made, proposal #24 takes over to preserve the state of that display name. In principal, both solutions could be used simultaneously by an XMTP client to provide the best user experience.

[yash-luna]

Thanks for this excellent post @qrtp! Portability for display preferences have the potential to not only mitigate confusion stemming from inconsistent resolution but also empower users to determine their human-readable identity.

Couple questions to better understand the proposal:

• Where do you see the enum NamingSystem that captures the display order preferences being stored?
• How can clients access the preferences?

Also wanted to surface this related discussion around storing a different type of preferences (inbox filtering/management) - https://github.com/orgs/xmtp/discussions/33?. Important to note that the inbox filtering preferences are meant to only be readable by the user themself as opposed to the display preferences which should be readable by other clients.

[qrtp]

Thanks for your thoughts. I've provided some responses below.

Question 1

Where do you see the enum NamingSystem that captures the display order preferences being stored?

I think that the various XMTP client SDK packages would be updated to include such an enum, so that the clients are aware of the available naming system options. When calling the POST API (described below) the enum values would of course be included as an ordered list in the request, and then validated on the server side before storing the preference.

Validation discussion

If a non-supported value is provided then the API could return a 400 response. It's debatable whether the server needs to enforce the enum. On one hand, allowing arbitrary values would be more flexible to allow clients to use a naming system not defined by the SDK. On the other hand, enforcing a known list might give more protection to the user by only allowing reputable naming systems. It could also get messy without enforcing the enum values, in that only some clients will know how to resolve the non-defined naming system. And then we'd end up in the same situation we're in now with inconsistent client UX.

Given these risks (user protection, inconsistent client UX) I think it's best to validate the supported naming system enum on the server side. It's easy to update the SDK version with a new enum value if a naming system needs to be added.

Question 2

How can clients access the preferences

The XMTP protocol would need to support a couple new API endpoints to enable users to manage their account preferences (such as display order, or possibly the inbox filtering preferences you referenced in #33) and of course for the XMTP clients to retrieve them. We'd need at minimum a POST call for a user to update their preference, and a GET call from a client to retrieve preference for a given account.

As a user

I view this type of API endpoint from a user perspective as a something that can be used to update structured data, and then stored on the XMTP network somehow associated with the user account. I haven't investigated how things are stored by XMTP, so would appreciate some guidance on how to store "stuff" such as user preferences. As you mentioned there is #33 where there is a desire to store other types of metadata than the display order I'm proposing here. This same "user preference" API endpoint would be used to support any such user metadata. The user update would obviously need to be signed with their XMTP private key so it can be validated on the server side.

As a client

From the client side, a GET API needs to be available to retrieve the user preferences. Authentication on this endpoint should be optional.

• If authentication is provided, return all user associated data (public and private) such as the inbox prefs mentioned in Standardized inbox filtering #33
• If no authentication is provided, only return public metadata such as the display name order preference

Authentication

Authentication is simple to achieve using the XMTP private key already available on the client. The API request should just be signed with the user's private key, and the resulting signature included in the request header. On the server side the provided signature is validated against the expected XMTP account. We are using this approach at Unstoppable Domains to register conversation topics with mobile device tokens, and it works very well.

[qrtp]

As an aside, Unstoppable Domains has an API endpoint that supports user-preferred naming resolution. In the example below, my wallet address 0xcd0dadab45baf9a06ce1279d1342ecc3f44845af contains ENS, Lens and Unstoppable Domains identities. Changing the resolution order in the the query string value will influence which identity is returned for my address.

Example

https://api.unstoppabledomains.com/profile/resolve/0xcd0dadab45baf9a06ce1279d1342ecc3f44845af?resolutionOrder=ud,ens,lens

You can try it out with one of your own addresses.

This API (or one like it) would be used by an XMTP client to determine a display name that respects the user's preference. The current proposal would allow the query string value to be retrieved from the user's XMTP account, so that the display preference can persist across different XMTP clients.

[polmaire]

hey @qrtp thank you for raising this issue and mentioning the #24 discussion. This is a complicated topic and I know believe that proposition #24 was too complicated.

At Converse, we observe that users often:

1. wonder how they appear on other clients but also on Converse (UX issue on our end for the latter)
2. have a very clear idea on how they would like to be displayed
3. generally have one thing in mind for one wallet

That's why:

• I believe your suggestion makes sense overall
• I agree with @yash-luna that we should keep in mind that this parameter is meant to be read by everyone, and not only by the user themself
• I would not rank several options for a given wallet but I'd actually just select the one that the user wants (and that they can change after)

For the last point, what is the need to have several identity providers ranked according to you?

[qrtp]

For the last point, what is the need to have several identity providers ranked according to you?

I suggested a ranked list of providers for flexibility. I think you're right that most times users will have in mind a specific naming service for a given wallet, and just want that name to appear as their identity. My thinking is that it's just as easy to store a list as a single value, and it allows the solution to be used in cases we may not have thought of for clients. For example, if the ENS name in my wallet expires or I sell it on OpenSea, what name should be displayed as a fallback for this wallet?

[polmaire]

Thanks for your response! About the easiness to store multiple values, I agree with you. But I'd say that it's not because it can be done that it has to be done. If the domain expires it's actually a good opportunity to ask again the user about their preferences.

[qrtp]

Understood, the intention was not to be a sticking point but to add flexibility. In my mind, the more flexible the framework, the easier it is to gain community support.

[Mimicute101]

That's great
Heard you're hiring

[qrtp]

@yash-luna and XMTP team, what would be the best approach to store such a preference value at the account level? The goal would be a publicly viewable preference, so that it's easy for client apps to determine how to display the account name.

[cboscolo]

Thanks for writing up this proposal, @qrtp!

We built something similar to what you have proposed with the one caveat that we implemented the request/response protocol over XMTP. (The advantage of building this protocol over XMTP instead of HTTP is that you get wallet-level authentication for free.)
The user can publish which name/pfp they want to use, and push it to the "profile directory".

With that said, if I could do it all over again, I would have done something more similar to https://github.com/orgs/xmtp/discussions/24.

I would create an XMTP codec that allows a client to send its preferred Name/PFP and any other contact meta data desired. The UX could be behave similar to iMessage when you update your contact info. The advantage to this approach is:

• The user sending the message maintains full control over what name others see. (I agree with @polmaire that user just want to pick their name, instead of wondering how it might show up due to some client-dependent algorithm.)
• If the user changes their name, it updates immediately with the person they are talking to.
• Does not require some centralized service that different clients would need to rely on.
• The same mechanism that handles the name would also handle the PFP.
• Doesn't depend on address to name resolution. (See next point.)

XMTP Clients should not rely and address to name lookup

I think it is a mistake to rely on address-to-name lookups at all in XMTP clients. Ultimately, this proposal is needed because there is no deterministic way to map addresses to names. Plus, with the advent of CCIP name lookups for domains like cb.id it is very uncommon for reverse records to be configured for many users. Instead, if clients configure which name they want to be known as, the peers only need to confirm that the forward lookup of the name matches the address of sender.

[cboscolo]

Sorry if I was not clear when I said:

the peers only need to confirm that the forward lookup of the name matches the address of sender

I am not proposing user be able to choose any arbitrary name. I agree with you that names should be web3 verified. What I am saying is this verification should only rely on the forward lookups. So if you tell me you are "barmstrong.eth", then my client does a forward lookup and confirms that the resulting address is indeed the address I am talking to. If it doesn't then it may want to warn the user and not show the name. But, to do this, clients need to send the name they want to be known as.

Forward lookups (name-to-address) can know what chain to use based on the name. This means names can exist on any chain so long as the client knows how to query said chain.

Reverse lookups (address-to-name) require either some oracle for all addresses, or some algorithm (like this proposal) to figure out where to perform the reverse lookup. To me this is an anti-pattern. FWIW, reverse lookups for IP addresses followed a similar history, no ones does them anymore.

[qrtp]

I'm sorry, I totally missed that last sentence in your post. Thank you for re-stating, and the forward resolution on the account's desired name makes sense.

[galligan]

@cboscolo I really like this approach personally. It satisfies one core tension that I've had with how name resolution has worked with most XMTP clients, in that they're defined by the recipient client, and not based on the sender's intent.

As an email sender, I can choose to use a different alias to send from, depending on the circumstances. The recipient may reply and engage with that alias, while I'm still managing the conversation through a single inbox.

I see the various web3 identifiers in a similar light. Let's take a simple example: that I control galligan.eth and matt.xmtplabs.eth from the same EOA. When I send a message, it might be my intent to send it from my xmtplabs.eth subname because I'm trying to signal my affiliation with the company. In this case, I wouldn't want the recipient client to change it back to galligan.eth just because that's set as my primary ENS name. This might be especially true in a situation with a Lens profile, where .lens might be the preferred TLD in the context of a Lens-initiated conversation.

Another reason that sender-defined, recipient-resolved identifier selection would be valuable is when an identifier is sold or transferred. When I'm conversing with someone, and midway through they sell a domain, going back to a bare address, it might be confusing when I look back at my history. But if there could be a name associated with those messages that could be confirmed, it would be useful to preserve historical context.

I could see this sort of thing becoming a content type, where the intended name is sent via a message. Clients that support it could do forward resolution and make use of the intended name, while those that don't support it might just fall back on traditional reverse resolution.

There's still more nuance to get into here, but I like the direction!

[polmaire]

Not much to add here - fully aligned with your response @galligan - what prevents us from starting this in the near future?

[cboscolo]

Thanks for elaborating other scenarios that could be improved with approach, @galligan!
I also like the shortened label you gave it: sender-defined, recipient-resolved identifier selection

To turn this into a spec, here's the broad strokes of what I think it should to cover:

1. The definition for a Contact record content type
2. Guidelines for how clients should send/receive the Contact content type to provide a rich and verified user experience

Contact record content type

The Contact record should function similar to sharing contacts in iMessage. Although it could contain any information typically contained in a contact record, clients may choose to only send a very limited set of information such as your web3 name.

The Contact record should define of the valid fields (I think all fields should be optional, but some listed as SHOULD be included):
List of SHOULD fields:

• web3Name - Web3 Name of the sender (ie. ENS, UD, Lens, Farcaster)
• web3PFP - An NFT that can resolve on-chain.

Other optional fields could include things like:

• Anything traditionally found in contact records such as (ie. name/twitter/github/phone)

Guidelines for handling Contact record content types

This is not exhaustive, but here are some of the more important things these guidelines should cover.

Sending Contact information

1. Sender should always include web3Name in Contact record
2. Senders should always include a Contact content type on the first message of a new conversation
3. Senders can send a Contact record at any time to inform the peer of the senders identity info has changed.

Processing received Contact records

1. Receiver should perform a forward lookup of the web3Name and verify that the name maps to the addresses of the peer.
2. If web3PFP present, verify it is owned by peer

There is a lot more that would need to be fleshed out to make this an full blown spec. Hoping someone from the XMTP team or this community could run with it as I don't have the bandwidth to fully write this up.