From 15d3cd512c0fafc2fa506bb7b0b40ffe176b61c5 Mon Sep 17 00:00:00 2001 From: status-im-auto Date: Tue, 21 Feb 2023 16:18:47 +0000 Subject: [PATCH] Update documentation --- 404.html | 2 +- categories/index.html | 7 +- docs/index.html | 3 +- docs/index.xml | 11 + ...7901ebd67ce5f95decf61ce59be3cae6d95698d.js | 1792 +++++++++++++++++ ...e4f01993a929eeb3cdd97ac150269467f6c8db7.js | 1 + index.html | 3 +- index.xml | 11 + sitemap.xml | 2 + spec/1/index.html | 3 +- spec/10/index.html | 3 +- spec/11/index.html | 3 +- spec/12/index.html | 3 +- spec/13/index.html | 3 +- spec/14/index.html | 3 +- spec/15/index.html | 3 +- spec/16/index.html | 3 +- spec/17/index.html | 3 +- spec/18/index.html | 3 +- spec/19/index.html | 3 +- spec/2/index.html | 3 +- spec/20/index.html | 3 +- spec/21/index.html | 3 +- spec/22/index.html | 3 +- spec/23/index.html | 3 +- spec/24/index.html | 3 +- spec/25/index.html | 3 +- spec/26/index.html | 3 +- spec/27/index.html | 3 +- spec/28/index.html | 3 +- spec/29/index.html | 3 +- spec/3/index.html | 3 +- spec/30/index.html | 3 +- spec/31/index.html | 3 +- spec/32/index.html | 3 +- spec/33/index.html | 3 +- spec/34/index.html | 3 +- spec/35/index.html | 3 +- spec/36/index.html | 3 +- spec/37/index.html | 3 +- spec/38/index.html | 3 +- spec/4/index.html | 3 +- spec/43/index.html | 3 +- spec/44/index.html | 3 +- spec/45/index.html | 3 +- spec/46/index.html | 3 +- spec/47/index.html | 3 +- spec/48/index.html | 3 +- spec/5/index.html | 3 +- spec/51/index.html | 3 +- spec/52/index.html | 3 +- spec/53/index.html | 3 +- spec/54/index.html | 3 +- spec/55/index.html | 3 +- spec/56/index.html | 797 ++++++++ spec/6/index.html | 3 +- spec/7/index.html | 3 +- spec/8/index.html | 3 +- spec/9/index.html | 3 +- spec/xx/index.html | 3 +- .../index.html | 7 +- tags/index.html | 7 +- tags/logos/consensus/index.html | 7 +- tags/rln/index.html | 7 +- tags/waku-application/index.html | 32 +- tags/waku-application/index.xml | 11 + tags/waku-core-protocol/index.html | 7 +- tags/waku-core/index.html | 7 +- tags/waku/anonymity/index.html | 7 +- tags/waku/core-protocol/index.html | 7 +- 70 files changed, 2795 insertions(+), 83 deletions(-) create mode 100644 en.search-data.min.e1e684aa8c9c7df92087119d87901ebd67ce5f95decf61ce59be3cae6d95698d.js create mode 100644 en.search.min.0d5eae6685decae7eac699d29e4f01993a929eeb3cdd97ac150269467f6c8db7.js create mode 100644 spec/56/index.html diff --git a/404.html b/404.html index dc455aac..1198c691 100644 --- a/404.html +++ b/404.html @@ -14,7 +14,7 @@ - + + + + + + + + +
+ + +
+
+ +
+ + + 56/STATUS-COMMUNITIES + + +
+ + + + + + +
+ + + +
+

+ 56/STATUS-COMMUNITIES + # +

+ + +

+ Status Communities that run over Waku v2 + # +

+ + + + + + + + + + + +

+ Abstract + # +

+

This document describes the design of Status Communities over Waku v2, allowing for multiple users to communicate in a group chat. +This is a key feature for the Status messaging app.

+

+ 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. +We refer to these smaller group chats simply as “group chats”, to differentiate them from Communities.

+

For group chats based on 55/STATUS-1TO1-CHAT, the key exchange mechanism MUST be X3DH, as described in 53/WAKU2-X3DH.

+

However, this method does not scale as the number of participants increases, for the following reasons -

+
    +
  1. The number of messages sent over the network increases with the number of participants.
    2. +
  2. Handling the X3DH key exchange for each participant is computationally expensive.
    3. +
+

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.

+

+ Terminology + # +

+
    +
  • Community: A group of peers that can communicate with each other.
    • +
  • Member: A peer that is part of a community.
    • +
  • Admin: A member that has administrative privileges. Used interchangeably with “owner”.
    • +
  • Channel: A designated subtopic for a community. Used interchangeably with “chat”.
    • +
+

+ Design Requirements + # +

+

Due to the nature of communities, the following requirements are necessary for the design of communities -

+
    +
  1. The creator of the Community is the owner of the Community.
    2. +
  2. The Community owner is trusted.
    3. +
  3. The Community owner can add or remove members from the Community. +This extends to banning and kicking members.
    4. +
  4. The Community owner can add, edit and remove channels.
    5. +
  5. Community members can send/receive messages to the channels which they have access to.
    6. +
  6. Communities may be encrypted (private) or unencrypted (public).
    7. +
  7. A Community is uniquely identified by a public key.
    8. +
  8. The public key of the Community is shared out of band.
    9. +
  9. The metadata of the Community can be found by listening on a content topic derived from the public key of the Community.
    10. +
  10. Community members run their own Waku nodes, with the configuration described in #Waku-Protocols. +Light nodes solely implementing 19/WAKU2-LIGHTPUSH may not be able to run their own Waku node with the configuration described.
    11. +
+

+ Design + # +

+

+ Cryptographic Primitives + # +

+

The following cryptographic primitives are used in the design -

+
    +
  • X3DH
    • +
  • Single Ratchet +
      +
    • The single ratchet is used to encrypt the messages sent to the Community.
      • +
    • The single ratchet is re-keyed when a member is added/removed from the Community.
      • +
    +
    • +
+

+ Wire format + # +

+ + +
syntax = "proto3";
+
+message IdentityImage {
+  // payload is a context based payload for the profile image data,
+  // context is determined by the `source_type`
+  bytes payload = 1;
+  // source_type signals the image payload source
+  SourceType source_type = 2;
+  // image_type signals the image type and method of parsing the payload
+  ImageType image_type = 3;
+  // encryption_keys is a list of encrypted keys that can be used to decrypt an encrypted payload
+  repeated bytes encryption_keys = 4;
+  // encrypted signals the encryption state of the payload, default is false.
+  bool encrypted = 5;
+  // SourceType are the predefined types of image source allowed
+  enum SourceType {
+    UNKNOWN_SOURCE_TYPE = 0;
+
+    // RAW_PAYLOAD image byte data
+    RAW_PAYLOAD = 1;
+
+    // ENS_AVATAR uses the ENS record's resolver get-text-data.avatar data
+    // The `payload` field will be ignored if ENS_AVATAR is selected
+    // The application will read and parse the ENS avatar data as image payload data, URLs will be ignored
+    // The parent `ChatMessageIdentity` must have a valid `ens_name` set
+    ENS_AVATAR = 2;
+  }
+}
+
+// SocialLinks represents social link associated with given chat identity (personal/community)
+message SocialLink {
+  // Type of the social link
+  string text = 1;
+  // URL of the social link
+  string url = 2;
+}
+// ChatIdentity represents identity of a community/chat
+message ChatIdentity {
+  // Lamport timestamp of the message
+  uint64 clock = 1;
+  // ens_name is the valid ENS name associated with the chat key
+  string ens_name = 2;
+  // images is a string indexed mapping of images associated with an identity
+  map<string, IdentityImage> images = 3;
+  // display name is the user set identity
+  string display_name = 4;
+  // description is the user set description
+  string description = 5;
+  string color = 6;
+  string emoji = 7;
+  repeated SocialLink social_links = 8;
+  // first known message timestamp in seconds (valid only for community chats for now)
+  // 0 - unknown
+  // 1 - no messages
+  uint32 first_message_timestamp = 9;
+}
+
+message Grant {
+  // Community ID (The public key of the community)
+  bytes community_id = 1;
+  // The member ID (The public key of the member)
+  bytes member_id = 2;
+  // The chat for which the grant is given
+  string chat_id = 3;
+  // The Lamport timestamp of the grant
+  uint64 clock = 4;
+}
+
+message CommunityMember {
+  // The roles a community member MAY have
+  enum Roles {
+    UNKNOWN_ROLE = 0;
+    ROLE_ALL = 1;
+    ROLE_MANAGE_USERS = 2;
+    ROLE_MODERATE_CONTENT = 3;
+  }
+  repeated Roles roles = 1;
+}
+
+message CommunityPermissions {
+  // The type of access a community MAY have
+  enum Access {
+    UNKNOWN_ACCESS = 0;
+    NO_MEMBERSHIP = 1;
+    INVITATION_ONLY = 2;
+    ON_REQUEST = 3;
+  }
+
+  // If the community should be available only to ens users
+  bool ens_only = 1;
+  // If the community is private
+  bool private = 2;
+  Access access = 3;
+}
+
+message CommunityAdminSettings {
+  // If the Community admin may pin messages
+  bool pin_message_all_members_enabled = 1;
+}
+
+message CommunityChat {
+  // A map of members in the community to their roles in a chat
+  map<string,CommunityMember> members = 1;
+  // The permissions of the chat
+  CommunityPermissions permissions = 2;
+  // The metadata of the chat
+  ChatIdentity identity = 3;
+  // The category of the chat
+  string category_id = 4;
+  // The position of chat in the display
+  int32 position = 5;
+}
+
+message CommunityCategory {
+  // The category id 
+  string category_id = 1;
+  // The name of the category
+  string name = 2;
+  // The position of the category in the display
+  int32 position = 3;
+}
+
+message CommunityInvitation {
+  // Encrypted/unencrypted community description
+  bytes community_description = 1;
+  // The grant offered by the community
+  bytes grant = 2;
+  // The chat id requested to join
+  string chat_id = 3;
+  // The public key of the community
+  bytes public_key = 4;
+}
+
+message CommunityRequestToJoin {
+  // The Lamport timestamp of the request  
+  uint64 clock = 1;
+  // The ENS name of the requester
+  string ens_name = 2;
+  // The chat id requested to join
+  string chat_id = 3;
+  // The public key of the community
+  bytes community_id = 4;
+  // The display name of the requester
+  string display_name = 5;
+}
+
+message CommunityCancelRequestToJoin {
+  // The Lamport timestamp of the request
+  uint64 clock = 1;
+  // The ENS name of the requester
+  string ens_name = 2;
+  // The chat id requested to join
+  string chat_id = 3;
+  // The public key of the community
+  bytes community_id = 4;
+  // The display name of the requester
+  string display_name = 5;
+  // Magnet uri for community history protocol
+  string magnet_uri = 6;
+}
+
+message CommunityRequestToJoinResponse {
+  // The Lamport timestamp of the request
+  uint64 clock = 1;
+  // The community description
+  CommunityDescription community = 2;
+  // If the request was accepted
+  bool accepted = 3;
+  // The grant offered by the community
+  bytes grant = 4;
+  // The community public key
+  bytes community_id = 5;
+}
+
+message CommunityRequestToLeave {
+  // The Lamport timestamp of the request
+  uint64 clock = 1;
+  // The community public key
+  bytes community_id = 2;
+}
+
+message CommunityDescription {
+  // The Lamport timestamp of the message
+  uint64 clock = 1;
+  // A mapping of members in the community to their roles
+  map<string,CommunityMember> members = 2;
+  // The permissions of the Community
+  CommunityPermissions permissions = 3;
+  // The metadata of the Community
+  ChatIdentity identity = 5;
+  // A mapping of chats to their details
+  map<string,CommunityChat> chats = 6;
+  // A list of banned members
+  repeated string ban_list = 7;
+  // A mapping of categories to their details
+  map<string,CommunityCategory> categories = 8;
+  // The admin settings of the Community
+  CommunityAdminSettings admin_settings = 10;
+  // If the community is encrypted
+  bool encrypted = 13;
+  // The list of tags
+  repeated string tags = 14;
+}
+

Note: The usage of the clock is described in the Clock section.

+

+ Content topic usage + # +

+

“Content topic” refers to the field in 14/WAKU2-MESSAGE, further elaborated in 10/WAKU2.

+

+ Advertising a Community + # +

+

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.

+
hash = hex(keccak256(encodeToHex(compressedPublicKey)))
+
+topicLen = 4
+if len(hash) < topicLen {
+    topicLen = len(hash)
+}
+
+var topic [4]byte
+for i = 0; i < topicLen; i++ {
+    topic[i] = hash[i]
+}
+
+contentTopic = "/waku/1/0x" + topic + "/rfc26"
+

+ Community channels/chats + # +

+

The unique identifier for a community channel/chat is the chat id.

+ +

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.

+
hash = hex(keccak256(encodeToHex(compressedPublicKey + chatId)))
+
+topicLen = 4
+if len(hash) < topicLen {
+    topicLen = len(hash)
+}
+var topic [4]byte
+for i = 0; i < topicLen; i++ {
+    topic[i] = hash[i]
+}
+
+contentTopic = "/waku/1/0x" + topic + "/rfc26"
+

+ Community event messages + # +

+

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.

+
hash = hex(keccak256(encodeToHex(publicKey)))
+
+topicLen = 4
+if len(hash) < topicLen {
+    topicLen = len(hash)
+}
+var topic [4]byte
+for i = 0; i < topicLen; i++ {
+    topic[i] = hash[i]
+}
+
+contentTopic = "/waku/1/0x" + topic + "/rfc26"
+

+ Community Management + # +

+

The flows for Community management are as described below.

+

+ Community Creation Flow + # +

+
    +
  1. The Community owner generates a public/private key pair.
    2. +
  2. The Community owner configures the Community metadata, according to the wire format “CommunityDescription”.
    3. +
  3. The Community owner publishes the Community metadata on a content topic derived from the public key of the Community. +the Community metadata SHOULD be encrypted with the public key of the Community. +The Community metadata MAY be sent during fixed intervals, to ensure that the Community metadata is available to members. +The Community metadata SHOULD be sent every time the Community metadata is updated.
    4. +
  4. The Community owner MAY advertise the Community out of band, by sharing the public key of the Community on other mediums of communication.
    5. +
+

+ Community Join Flow (peer requests to join a Community) + # +

+
    +
  1. A peer and the Community owner establish a 1:1 chat as described in 55/STATUS-1TO1-CHAT.
    2. +
  2. The peer requests to join a Community by sending a “CommunityRequestToJoin” message to the Community. +At this point, the peer MAY send a “CommunityCancelRequestToJoin” message to cancel the request.
    3. +
  3. The Community owner MAY accept or reject the request.
    4. +
  4. If the request is accepted, the Community owner sends a “CommunityRequestToJoinResponse” message to the peer.
    5. +
  5. The Community owner then adds the member to the Community metadata, and publishes the updated Community metadata.
    6. +
+

+ Community Join Flow (peer is invited to join a Community) + # +

+
    +
  1. The Community owner and peer establish a 1:1 chat as described in 55/STATUS-1TO1-CHAT.
    2. +
  2. The peer is invited to join a Community by the Community owner, by sending a “CommunityInvitation” message.
    3. +
  3. The peer decrypts the “CommunityInvitation” message, and verifies the signature.
    4. +
  4. The peer requests to join a Community by sending a “CommunityRequestToJoin” message to the Community.
    5. +
  5. The Community owner MAY accept or reject the request.
    6. +
  6. If the request is accepted, the Community owner sends a “CommunityRequestToJoinResponse” message to the peer.
    7. +
  7. The Community owner then adds the member to the Community metadata, and publishes the updated Community metadata.
    8. +
+

+ Community Leave Flow + # +

+
    +
  1. A member requests to leave a Community by sending a “CommunityRequestToLeave” message to the Community.
    2. +
  2. The Community owner MAY accept or reject the request.
    3. +
  3. If the request is accepted, the Community owner removes the member from the Community metadata, and publishes the updated Community metadata.
    4. +
+

+ Community Ban Flow + # +

+
    +
  1. The Community owner adds a member to the ban list, revokes their grants, and publishes the updated Community metadata.
    2. +
  2. 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.
    3. +
+

+ Waku protocols + # +

+

The following Waku protocols SHOULD be used to implement Status Communities -

+
    +
  1. 11/WAKU2-RELAY - To send and receive messages
    2. +
  2. 53/WAKU2-X3DH - To encrypt and decrypt messages
    3. +
  3. 53/WAKU2-X3DH-SESSIONS - To handle session keys
    4. +
  4. 14/WAKU2-MESSAGE - To wrap community messages in a Waku message
    5. +
  5. 13/WAKU2-STORE - To store and retrieve messages for offline devices
    6. +
+

The following Waku protocols MAY be used to implement Status Communities -

+
    +
  1. 12/WAKU2-FILTER - Content filtering for resource restricted devices
    2. +
  2. 19/WAKU2-LIGHTPUSH - Allows Light clients to participate in the network
    3. +
+

+ Backups + # +

+

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 13/WAKU2-STORE for storing and retrieving messages.

+

+ Clock + # +

+

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.

+

+ Security Considerations + # +

+
    +
  1. +

    The Community owner is a single point of failure. If the Community owner is compromised, the Community is compromised.

    +
    2. +
  2. +

    Follows the same security considerations as the 53/WAKU2-X3DH protocol.

    +
    3. +
+

+ Future work + # +

+
    +
  1. +

    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 - Optimizing the CommunityDescription dissemination

    +
    2. +
  2. +

    Token gating for communities

    +
    3. +
  3. +

    Sharding the content topic used for #Community Event Messages, since members of the community don’t need to receive all the control messages.

    +
    4. +
+

+ Copyright + # +

+

Copyright and related rights waived via CC0.

+

+ References + # +

+ +
+ + + +
+ +
+ + + + + +
+ + + +
+ + + +
+ +
+ + + + +
+ + + + +
+ + + + + + + + + + + + + + + + + diff --git a/spec/6/index.html b/spec/6/index.html index 78057c32..0ca4e4d9 100644 --- a/spec/6/index.html +++ b/spec/6/index.html @@ -19,7 +19,7 @@ Motivation # Waku was created to incrementally improve in areas that Whisper is - +