Background and Motivation # The purpose of Status communities, as specified in this document, is allowing for large group chats. Communities can have further substructure, e.g. specific channels.
Smaller group chats, on the other hand, are out of scope for this document and can be built over 55/STATUS-1TO1-CHAT.">
Background and Motivation # The purpose of Status communities, as specified in this document, is allowing for large group chats. Communities can have further substructure, e.g. specific channels.
Smaller group chats, on the other hand, are out of scope for this document and can be built over 55/STATUS-1TO1-CHAT." />
<p>The purpose of Status communities, as specified in this document, is allowing for large group chats.
Communities can have further substructure, e.g. specific channels.</p>
<p>Smaller group chats, on the other hand, are out of scope for this document and can be built over <ahref="/spec/55">55/STATUS-1TO1-CHAT</a>.
We refer to these smaller group chats simply as “group chats”, to differentiate them from Communities.</p>
<p>For group chats based on <ahref="/spec/55">55/STATUS-1TO1-CHAT</a>, the key exchange mechanism MUST be X3DH, as described in <ahref="/spec/53/">53/WAKU2-X3DH</a>.</p>
<p>However, this method does not scale as the number of participants increases, for the following reasons -</p>
<ol>
<li>The number of messages sent over the network increases with the number of participants.</li>
<li>Handling the X3DH key exchange for each participant is computationally expensive.</li>
</ol>
<p>Having multicast channels reduces the overhead of a group chat based on 1:1 chat.
Additionally, if all the participants of the group chat have a shared key, then the number of messages sent over the network is reduced to one per message.</p>
<h1id="terminology">
Terminology
<aclass="anchor"href="#terminology">#</a>
</h1>
<ul>
<li><strong>Community</strong>: A group of peers that can communicate with each other.</li>
<li><strong>Member</strong>: A peer that is part of a community.</li>
<li><strong>Admin</strong>: A member that has administrative privileges. Used interchangeably with “owner”.</li>
<li><strong>Channel</strong>: A designated subtopic for a community. Used interchangeably with “chat”.</li>
</ul>
<h1id="design-requirements">
Design Requirements
<aclass="anchor"href="#design-requirements">#</a>
</h1>
<p>Due to the nature of communities, the following requirements are necessary for the design of communities -</p>
<ol>
<li>The creator of the Community is the owner of the Community.</li>
<li>The Community owner is trusted.</li>
<li>The Community owner can add or remove members from the Community.
This extends to banning and kicking members.</li>
<li>The Community owner can add, edit and remove channels.</li>
<li>Community members can send/receive messages to the channels which they have access to.</li>
<li>Communities may be encrypted (private) or unencrypted (public).</li>
<li>A Community is uniquely identified by a public key.</li>
<li>The public key of the Community is shared out of band.</li>
<li>The metadata of the Community can be found by listening on a content topic derived from the public key of the Community.</li>
<li>Community members run their own Waku nodes, with the configuration described in <ahref="#Waku-Protocols">#Waku-Protocols</a>.
Light nodes solely implementing <ahref="/spec/19/">19/WAKU2-LIGHTPUSH</a> may not be able to run their own Waku node with the configuration described.</li>
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// payload is a context based payload for the profile image data,
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#75715e"></span><spanstyle="color:#75715e">// context is determined by the `source_type`
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// image_type signals the image type and method of parsing the payload
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// encryption_keys is a list of encrypted keys that can be used to decrypt an encrypted payload
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// encrypted signals the encryption state of the payload, default is false.
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// SourceType are the predefined types of image source allowed
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// RAW_PAYLOAD image byte data
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// ENS_AVATAR uses the ENS record's resolver get-text-data.avatar data
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#75715e"></span><spanstyle="color:#75715e">// The `payload` field will be ignored if ENS_AVATAR is selected
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#75715e"></span><spanstyle="color:#75715e">// The application will read and parse the ENS avatar data as image payload data, URLs will be ignored
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#75715e"></span><spanstyle="color:#75715e">// The parent `ChatMessageIdentity` must have a valid `ens_name` set
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// SocialLinks represents social link associated with given chat identity (personal/community)
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// Type of the social link
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#75715e"></span><spanstyle="color:#66d9ef">string</span> text <spanstyle="color:#f92672">=</span><spanstyle="color:#ae81ff">1</span>;<spanstyle="color:#960050;background-color:#1e0010">
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// URL of the social link
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// ChatIdentity represents identity of a community/chat
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// Lamport timestamp of the message
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// ens_name is the valid ENS name associated with the chat key
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// images is a string indexed mapping of images associated with an identity
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// display name is the user set identity
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// description is the user set description
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#66d9ef">string</span> color <spanstyle="color:#f92672">=</span><spanstyle="color:#ae81ff">6</span>;<spanstyle="color:#960050;background-color:#1e0010">
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// first known message timestamp in seconds (valid only for community chats for now)
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// Community ID (The public key of the community)
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The member ID (The public key of the member)
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The chat for which the grant is given
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The Lamport timestamp of the grant
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The roles a community member MAY have
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The type of access a community MAY have
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// If the community should be available only to ens users
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// If the community is private
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// If the Community admin may pin messages
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// A map of members in the community to their roles in a chat
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#75715e"></span> map<<spanstyle="color:#66d9ef">string</span>,CommunityMember> members <spanstyle="color:#f92672">=</span><spanstyle="color:#ae81ff">1</span>;<spanstyle="color:#960050;background-color:#1e0010">
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The permissions of the chat
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The metadata of the chat
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The category of the chat
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The position of chat in the display
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#75715e"></span><spanstyle="color:#66d9ef">int32</span> position <spanstyle="color:#f92672">=</span><spanstyle="color:#ae81ff">5</span>;<spanstyle="color:#960050;background-color:#1e0010">
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The category id
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The name of the category
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#75715e"></span><spanstyle="color:#66d9ef">string</span> name <spanstyle="color:#f92672">=</span><spanstyle="color:#ae81ff">2</span>;<spanstyle="color:#960050;background-color:#1e0010">
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The position of the category in the display
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#75715e"></span><spanstyle="color:#66d9ef">int32</span> position <spanstyle="color:#f92672">=</span><spanstyle="color:#ae81ff">3</span>;<spanstyle="color:#960050;background-color:#1e0010">
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// Encrypted/unencrypted community description
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The grant offered by the community
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#75715e"></span><spanstyle="color:#66d9ef">bytes</span> grant <spanstyle="color:#f92672">=</span><spanstyle="color:#ae81ff">2</span>;<spanstyle="color:#960050;background-color:#1e0010">
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The chat id requested to join
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The public key of the community
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The Lamport timestamp of the request
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The ENS name of the requester
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The chat id requested to join
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The public key of the community
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The display name of the requester
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The Lamport timestamp of the request
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The ENS name of the requester
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The chat id requested to join
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The public key of the community
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The display name of the requester
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// Magnet uri for community history protocol
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The Lamport timestamp of the request
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The community description
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#75715e"></span> CommunityDescription community <spanstyle="color:#f92672">=</span><spanstyle="color:#ae81ff">2</span>;<spanstyle="color:#960050;background-color:#1e0010">
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// If the request was accepted
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The grant offered by the community
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#75715e"></span><spanstyle="color:#66d9ef">bytes</span> grant <spanstyle="color:#f92672">=</span><spanstyle="color:#ae81ff">4</span>;<spanstyle="color:#960050;background-color:#1e0010">
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The community public key
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The Lamport timestamp of the request
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The community public key
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The Lamport timestamp of the message
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// A mapping of members in the community to their roles
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#75715e"></span> map<<spanstyle="color:#66d9ef">string</span>,CommunityMember> members <spanstyle="color:#f92672">=</span><spanstyle="color:#ae81ff">2</span>;<spanstyle="color:#960050;background-color:#1e0010">
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The permissions of the Community
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The metadata of the Community
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// A mapping of chats to their details
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// A list of banned members
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// A mapping of categories to their details
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The admin settings of the Community
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// If the community is encrypted
</span></span></span><spanstyle="display:flex;"><span><spanstyle="color:#960050;background-color:#1e0010"></span><spanstyle="color:#75715e">// The list of tags
</span></span></span></code></pre></div><p>Note: The usage of the clock is described in the <ahref="#clock">Clock</a> section.</p>
<h2id="content-topic-usage">
Content topic usage
<aclass="anchor"href="#content-topic-usage">#</a>
</h2>
<p>“Content topic” refers to the field in <ahref="/spec/14/#message-attributes">14/WAKU2-MESSAGE</a>, further elaborated in <ahref="/spec/10/#overview-of-protocol-interaction">10/WAKU2</a>.</p>
<p>The content topic that the community is advertised on MUST be derived from the public key of the community.
The content topic MUST be the first four bytes of the keccak-256 hash of the compressed (33 bytes) public key of the community encoded into a hex string.</p>
<p>The unique identifier for a community channel/chat is the chat id.</p>
<!-- raw HTML omitted -->
<p>The content topic that Community channels/chats use MUST be the hex-encoded keccak-256 hash of the public key of the community concatenated with the chat id.</p>
<p>Requests to leave, join, kick and ban, as well as key exchange messages, MUST be sent to the content topic derived from the public key of the community.
The content topic MUST be the hex-encoded keccak-256 hash of the public key of the community.</p>
<li>A member requests to leave a Community by sending a “CommunityRequestToLeave” message to the Community.</li>
<li>The Community owner MAY accept or reject the request.</li>
<li>If the request is accepted, the Community owner removes the member from the Community metadata, and publishes the updated Community metadata.</li>
</ol>
<h3id="community-ban-flow">
Community Ban Flow
<aclass="anchor"href="#community-ban-flow">#</a>
</h3>
<ol>
<li>The Community owner adds a member to the ban list, revokes their grants, and publishes the updated Community metadata.</li>
<li>If the Community is Private, Re-keying is performed between the members of the Community, to ensure that the banned member is unable to decrypt any messages.</li>
</ol>
<h2id="waku-protocols">
Waku protocols
<aclass="anchor"href="#waku-protocols">#</a>
</h2>
<p>The following Waku protocols SHOULD be used to implement Status Communities -</p>
<ol>
<li><ahref="/spec/11/">11/WAKU2-RELAY</a> - To send and receive messages</li>
<li><ahref="/spec/53/">53/WAKU2-X3DH</a> - To encrypt and decrypt messages</li>
<li><ahref="/spec/54/">53/WAKU2-X3DH-SESSIONS</a> - To handle session keys</li>
<li><ahref="/spec/14/">14/WAKU2-MESSAGE</a> - To wrap community messages in a Waku message</li>
<li><ahref="/spec/13/">13/WAKU2-STORE</a> - To store and retrieve messages for offline devices</li>
</ol>
<p>The following Waku protocols MAY be used to implement Status Communities -</p>
<ol>
<li><ahref="/spec/12/">12/WAKU2-FILTER</a> - Content filtering for resource restricted devices</li>
<li><ahref="/spec/19">19/WAKU2-LIGHTPUSH</a> - Allows Light clients to participate in the network</li>
</ol>
<h2id="backups">
Backups
<aclass="anchor"href="#backups">#</a>
</h2>
<p>The member MAY back up their local settings, by encrypting it with their public key, and sending it to a given content topic.
The member MAY then rely on this backup to restore their local settings, in case of a data loss.
This feature relies on <ahref="/spec/13/">13/WAKU2-STORE</a> for storing and retrieving messages.</p>
<h2id="clock">
Clock
<aclass="anchor"href="#clock">#</a>
</h2>
<p>The clock used in the wire format refers to the Lamport timestamp of the message.
The Lamport timestamp is a logical clock that is used to determine the order of events in a distributed system.
This allows ordering of messages in an asynchronous network where messages may be received out of order.</p>
<p>The Community owner is a single point of failure. If the Community owner is compromised, the Community is compromised.</p>
</li>
<li>
<p>Follows the same security considerations as the <ahref="/spec/53/">53/WAKU2-X3DH</a> protocol.</p>
</li>
</ol>
<h1id="future-work">
Future work
<aclass="anchor"href="#future-work">#</a>
</h1>
<ol>
<li>
<p>To scale and optimize the Community management, the Community metadata should be stored on a decentralized storage system, and only the references to the Community metadata should be broadcasted. The following document describes this method in more detail - <ahref="https://hackmd.io/rD1OfIbJQieDe3GQdyCRTw">Optimizing the <code>CommunityDescription</code> dissemination</a></p>
</li>
<li>
<p>Token gating for communities</p>
</li>
<li>
<p>Sharding the content topic used for <ahref="#community-event-messages">#Community Event Messages</a>, since members of the community don’t need to receive all the control messages.</p>
</li>
</ol>
<h1id="copyright">
Copyright
<aclass="anchor"href="#copyright">#</a>
</h1>
<p>Copyright and related rights waived via <ahref="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p>
