Proposal: Portable consent state for v2 SDKs

[saulmc]

Authors: @nakajima, @saulmc
Stage: Draft

Abstract

Make consent portable by introducing network-level allow and block lists.

Problem

To safeguard users, XMTP inbox apps are adopting UX designs that categorize conversation consent into three states: allowed, blocked, and pending (neither allowed nor blocked). For instance, an app may place pending conversations on a separate tab, while fully hiding conversations from blocked addresses.

As there is currently no standard method to share consent state changes across the network, actions taken in one app won’t reflect in others. This leads to inconsistent experiences for users and hinders the potential network effect of XMTP for developers.

Proposed Solution

We should give clients the ability to send and retrieve background messages that indicate when users allow or block addresses. This enhancement will mitigate spam at the network level by empowering users with a “block once, block everywhere” capability, while also providing developers with explicit indications of user consent.

Functional Requirements

As a user, I can

1. Approve a sender across all my XMTP apps.
2. Block a sender across all my XMTP apps.
3. Move a sender from my block list to my allow list or vice versa.

As a client app developer, I can

1. Retrieve a filtered list of conversations that are in a 'pending' state for the user.
2. Retrieve a filtered list of the user’s conversations with allowed addresses.
3. Stream new 'pending' conversations.
4. Stream new conversations with allowed addresses.
5. Access a list of the user’s allowed and blocked addresses.
6. Update the network when a user allows or blocks an address.

Specification

We propose introducing a new message topic: "privatestore-(address)/allowlist"

Messages published to this topic should be encrypted AllowList objects:

{
	type: 'allow' | 'block',
	addresses: [string]
}

Clients will be able to generate lists of “allowed” and “blocked” addresses by replaying the messages in this topic.

SDK Support

A new ConsentState type will be introduced to describe the state of the conversation based on whether the peer address is allowed or blocked.

type ConsentState = 'allowed' | 'blocked' | 'unknown'

Conversation will have a new field, consentState that will return an ConsentState for the conversation. Apps can use this to filter out unknown or blocked conversations from their main conversation lists and show blocked/unknown conversations in a more appropriate place in their UIs.

API	Description
client.contacts.allowed()	Returns the list of allowed addresses
client.contacts.blocked()	Returns the list of blocked addresses (for users to potentially unblock them)
client.contacts.allow([string])	Enables individual and bulk addition of addresses to allow list
client.contacts.block([string])	Enables individual and bulk addition of addresses to block list

Other considerations

Clients will need to locally cache the allow and block lists in order to properly apply filters to conversations on initial load.

Clients are free to use conversation consent state as they see fit to deliver the best inbox experience to their users.

[neekolas]

Thanks for putting this together. This is great.

A few questions:

1. How do I unblock a conversation and return it to the pending list? For example, if the user hit block accidentally.
2. Why do we need to change the behaviour of the conversations.list() API? We could alternatively just expose the status on each conversation and let developers do with it what they wish. Filtering the list makes assumptions about how the client would want to display the conversations (maybe you want to show allowed and pending in one list, maybe two). We may actually be making things harder for developers, when filtering later is so trivially easy (conversations.filter(c => c.isAllowed)). The same is true for streaming APIs, where developers who wanted to show pending and allowed conversations would need to have two open streams.
3. What state transitions are allowed? Can I block a previously allowed conversation? Can I allow a blocked conversation?
4. How will we encrypt the messages in the private channel? The other entries in the PrivateStore are encrypted using a wallet signature that is immediately discarded after use. While we could keep that secret around for longer, that comes with an increased risk of compromise (which would then compromise the user's entire XMTP identity). The JS SDK does have support for Signed ECIES payloads, which would be a more secure option since it uses ephemeral keys for encryption and decrypts using the XMTP identity key.

[nakajima]

How do I unblock a conversation and return it to the pending list? For example, if the user hit block accidentally.

If you block accidentally, you could still allow from the client.conversations.blocked() list. Do you think we need to allow putting an address back into pending state?

Why do we need to change the behaviour of the conversations.list() API?

Different objects (Conversation vs PendingConversation) feel better to me here. Sending/listing messages from conversations that haven't been accepted feels off to me. I could be convinced otherwise though.

The same is true for streaming APIs, where developers who wanted to show pending and allowed conversations would need to have two open streams.

We could maybe consolidate the streaming APIs into one that returns a union (or enum in Swift/Kotlin) for new conversation info?

What state transitions are allowed? Can I block a previously allowed conversation? Can I allow a blocked conversation?

I think yes.

How will we encrypt the messages in the private channel?

I do not have a strong opinion (or enough expertise to say for sure in any direction) on this. I'd defer to folks with more knowledge here.

[neekolas]

If you block accidentally, you could still allow from the client.conversations.blocked() list. Do you think we need to allow putting an address back into pending state?

We could probably live without a blocked -> pending state transition.

Sending/listing messages from conversations that haven't been accepted feels off to me. I could be convinced otherwise though.

I'm not sure this is a call we need to make as a protocol. We should be giving developers flexibility to design their apps however they choose. For example, I could imagine apps treating allow/pending the same and only respecting blocks.

Also worth noting that developers are 100% going to have to list messages from pending conversations. How else would you show the user the first message in the convo to let them decide if it's a scam or not? That's the existing UX in many apps today that have implemented block/allow. We're also going to want developers to be able to build content-based SPAM detection tools, which requires the SDK to allow you to read those messages to evaluate them.

If we don't let apps interact with pending conversations, developers are going to default to allowing everything and then maybe blocking later...which kinda defeats the point of the pending status altogether.

[nakajima]

Also worth noting that developers are 100% going to have to list messages from pending conversations. How else would you show the user the first message in the convo to let them decide if it's a scam or not? That's the existing UX in many apps today that have implemented block/allow. We're also going to want developers to be able to build content-based SPAM detection tools, which requires the SDK to allow you to read those messages to evaluate them.

I'm convinced and on board with just adding a flag to Conversation.

[richardhuaaa]

This is very logical.

1. How will enableAllowList() work? Do we intend to persist a flag somewhere? Will apps be able to query if it has already been enabled, to avoid doing it twice?

2. How will we transition from the old system to the new system? A naive implementation would move all existing conversations to the pending state. Is the idea that the first app to enable this would also move all existing conversations to the allowed state?

[nakajima]

How will enableAllowList() work? Do we intend to persist a flag somewhere? Will apps be able to query if it has already been enabled, to avoid doing it twice?

Let's ignore this and go with Nick's suggestion to just make this a ClientCreationOption.

How will we transition from the old system to the new system? A naive implementation would move all existing conversations to the pending state. Is the idea that the first app to enable this would also move all existing conversations to the allowed state?

Yea, I think that's sort of up to folks who decide to adopt the allow list to handle in their apps. Since allow should take an array, it shouldn't be too tedious to allow all existing conversations.

[neekolas]

Leaving it up to devs to migrate seems reasonable to me. Some will already have their own allow/block lists stored in their applications.

[neekolas]

Clients will need to locally cache the allow and block lists in order to properly apply filters to conversations on initial load.

Just to clarify, this would be handled inside the Client? When would that cache be invalidated/updated?

[nakajima]

I think ideally it would be handled inside the Client. I'm not entirely sure how/where it fits best in V2 land, that's definitely something to think about.

[neekolas]

We do have a pretty decent caching layer inside xmtp-js for conversation caching, so it seems reasonable to extend it to caching this state. Mobile SDKs might require more of a lift.

[neekolas]

SDK support for allow and block lists will be opt-in to start and enabled by calling client.enableAllowList().

Why not just make this a ClientCreateOption?

[nakajima]

Good call.

[neekolas]

For encryption, I think the thing that makes the most sense here is actually to write a small ECIES library in Rust and expose it to all the other SDKs via FFI. There is a decent looking ECIES crate we can use, and we can create some protos that add a signature inside the encrypted payload.

It's a good warm-up for our future WASM needs. Gives us a very small library we can expose via WASM that'll be way less complicated than v3, so we can verify it's working end to end.

[nakajima]

Updated the proposal to just remove the client option since adding the flag means no changes need to happen to existing APIs. I also included the new field on conversation that denotes its allowed state.

[marian2js]

Hi everyone! I like the approach the protocol is taking in general, but I think the block list should understand more than just addresses.

From what I've seen, most of the time, spammers use a different address for each message. This would make blocking addresses kind of useless and might end up converting "pending tabs" into spam folders that no one would check. The problem with managing blocking at the address level is that creating addresses is virtually free.
I believe apps will need to rely on on-chain data to differentiate between a potentially good address and a potential spammer. Since domains like ENS or UD have a cost, they can be a good initial indicator.

The only cases I saw a spammer reusing an address is when it is associated with an ENS. For example, I received messages from "cb-security.eth" on multiple wallets. If the block list is only at the address level, it could be profitable for the spammer to spam hundreds of users once a day, move the ENS to a different address, and repeat.

However, if the block list also includes ENS/UD, then the user can block a certain domain forever. This will also be good for a UX perspective. An end-user that blocks certain ENS and the other day receives again a message from than ENS might believe the protocol is broken (without realizing the ENS is on a different address). I believe when a user blocks a conversation (normally displayed with an ENS/UD), the block should happen both at the address and domain level.

This suggestion shouldn't imply a big change in the implementation. Instead of accepting addresses, the protocol could accept to block/allow any string. Then, when an app is blocking an address, it can send both the address and the displayed domain. The same when checking if an address is allowed/blocked.

[fabriguespe]

Proposing a public list for string domains could increase the effectiveness of the block feature. A spammy ENS address would be publicly flagged very fast. Without a public block list, each spammy address could operate across the network uninterrupted, which might still be economically viable for spammers.

[yash-luna]

That's an awesome idea.

It may be useful to have a distinct action like 'Report' to add 0x addresses and ENS/UD names to the public list. The difference here being:

• Block: user wants to stop receiving messages from a given address
• Report: user thinks a given address is sending problematic content or spam (and wants to caution the community about it)

Clients can also provide an option to 'Report and Block' to allow users to easily do both in one click.

[trebor-yatska]

I think when it comes to crowdsourced list generation we have to be careful that we create a fair process. If there are not proper guardrails in place it becomes too easy to censor. I can think of at least a few ways to attack a "report" feature.

I think the idea is worth exploring, but it would be a fairly elaborate protocol component in my mind.

[marian2js]

I agree with @trebor-yatska, it'd be too easy to exploit a report or public list feature if any address can report:

Since creating addresses is free, a malicious person could easily create a million wallets and use all to report GoodCompany.eth. Spammers could be incentivized to do such attacks to force clients to stop using the public list.

However, if the protocol only considers reports from addresses with an ENS/UD, then it would be expensive to do any kind of massive reports.

[fabriguespe]

I support the idea of defaulting conversations to pending state. Developers will be able to chose how to handle pending and allowed. Some of them may offer customizable options in their settings, for example receive the pending in the Archive inbox. Or moving the allowed into a priority inbox. Some of them may not process them separately, which may be fine also.

If the majority of addresses are going to be blocked. Then we can think of blocked / pending as the default state and allowed opt-in only. My concern lies in handling notifications:

• If we only receive notifications from allowed, users will loose potentially important notifications
• If we get all pending notifications, then we will be annoyed by spam

[neekolas]

We propose introducing a new message topic: "privatestore-(address)/allowlist"

@nakajima I think we can do better on the privacy front here. There is no reason other users on the network need to be able to find this data, so I don't see any reason to make the topic associated with a particular account. The existing private-store data needs to be in an obvious location because of a chicken and egg problem (how can I create an unguessable topic without my keys...which are found in the privatestore).

Seeing when messages were written to these topics would leak times that the user was online and actively blocking/allowing users.

We could derive some sort of topic identifier using HKDF of encryption keys used for the topic. That way only the holder of the keys would know where to look. This would be very similar to our solution to deterministic topics used for V2 conversations.

[polmaire]

Thank you very much @saulmc for this proposal. Following some of the comments here, I think it is crucial for most clients to synchronise on how we'll migrate from client-based consent to protocol-based consent, and how we'll keep being synced in the future.

Please find below a proposition on how to handle it as clients.

Constraints

• most clients already have a « block / accept » centralized feature
• consent is user-based (not conversation based)
• greatness of user experience should be kept

Principles

• a client should not overwrite the protocol’s status except for immediate action from the user
• response to a conversation can be considered as consent for historical conversations

Solution
For any new user connexion, for every conversation

• if XMTP state is pending
  • if client state for the user is set, update XMTP's state of the user
  • if not and user sent at least one message in the conversation, set XMTP's state as "Accepted"
  • else, do nothing
• if XMTP state is set
  • do nothing on XMTP's side
  • update client's state to match XMTP's state

After that

• for every new user connexion, we repeat the process
• for any consent / block action coming from the user the user while he/she uses the app, the client updates the protocol

Overall, the most crucial aspect is to respect a previous input by another client in order to avoid clients constantly overwriting the state of a given user.

[qrtp]

Thanks @polmaire for outlining. I agree completely with the approach 👍

[saulmc]

As we wrap up implementation, we are looking for feedback on two proposed refinements to the original proposal:

1) Rename "Allowed / Blocked" to "Allowed / Denied".

The terms "Allowed / Blocked" closely resemble the ubiquitous "Accept / Block" UI pattern. Although this UI pattern is compatible with portable consent, other patterns such as "Subscribe" and "Enable notifications" are also supported. The protocol's language should avoid implying specific user interface decisions.

"Allowed / Denied" provides a more UI-neutral terminology. This also paves the way for the use of the increasingly common terms "allowlist" and "denylist" when referencing lists of allowed/denied addresses. For reference, consider Google's style guide on the matter.

2) Include business logic for implied consent scenarios

When a user initiates a new conversation, developers need to add the new conversation peer to the user's allowlist. Failing to do this makes the new conversation hard to locate in apps that filter unknown consent.

Similarly, responding to a conversation in apps lacking portable consent leaves consent as unknown, making the chat hard to locate elsewhere.

Given these situations, it's reasonable to believe the user wants to continue the conversation. To address this, we'll automatically set the consent state to allowed whenever a user starts a new conversation or answers an existing one.

[polmaire]

Thanks @saulmc works well for me!

[nplasterer]

Just wanted to update that these changes have landed in the latest version of RN, Android, and iOS SDKs. As well as the beta branch of JS.