vacp2p
/
rfc-index
mirror of https://github.com/vacp2p/rfc-index.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update and rename COMMUNITIES.md to communities.md

This commit is contained in:
Jimmy Debe 2024-02-01 23:33:52 -05:00 committed by GitHub
parent e105bea76b
commit 83507420c3
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 48 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
status/56/COMMUNITIES.md → status/56/communities.md
View File

@ -11,20 +11,20 @@ contributors:
- Andrea Piana <andreap@status.im>
---
# Abstract
## Abstract
This document describes the design of Status Communities over Waku v2, allowing for multiple users to communicate in a discussion space.
This is a key feature for the Status messaging app.
# Background and Motivation
## 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](/spec/55).
Smaller group chats, on the other hand, are out of scope for this document and can be built over [55/STATUS-1TO1-CHAT](../55/1to1-chat.md).
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](/spec/55), the key exchange mechanism MUST be X3DH, as described in [53/WAKU2-X3DH](/spec/53/).
For group chats based on [55/STATUS-1TO1-CHAT](../55/1to1-chat.md), the key exchange mechanism MUST be X3DH, as described in [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh.md).
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.
@ -33,14 +33,14 @@ However, this method does not scale as the number of participants increases, for
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
## 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
## Design Requirements
Due to the nature of communities, the following requirements are necessary for the design of communities -
@ -55,11 +55,11 @@ This extends to banning and kicking members.
8. The public key of the Community is shared out of band.
9. The metadata of the Community can be found by listening on a content topic derived from the public key of the Community.
10. Community members run their own Waku nodes, with the configuration described in [Waku-Protocols](#waku-protocols).
Light nodes solely implementing [19/WAKU2-LIGHTPUSH](/spec/19/) may not be able to run their own Waku node with the configuration described.
Light nodes solely implementing [19/WAKU2-LIGHTPUSH](../../waku/standards/core/19/lightpush.md) may not be able to run their own Waku node with the configuration described.
# Design
## Design
## Cryptographic Primitives
### Cryptographic Primitives
The following cryptographic primitives are used in the design -
@ -285,11 +285,11 @@ message CommunityDescription {
Note: The usage of the clock is described in the [Clock](#clock) section.
## Content topic usage
### Content topic usage
"Content topic" refers to the field in [14/WAKU2-MESSAGE](/spec/14/#message-attributes), further elaborated in [10/WAKU2](/spec/10/#overview-of-protocol-interaction).
"Content topic" refers to the field in [14/WAKU2-MESSAGE](../../waku/standards/core/14/message.md/#message-attributes), further elaborated in [10/WAKU2](../../waku/standards/core/10/waku2.md/#overview-of-protocol-interaction).
### Advertising a Community
#### 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.
@ -310,7 +310,7 @@ for i = 0; i < topicLen; i++ {
contentTopic = "/waku/1/0x" + topic + "/rfc26"
```
### Community channels/chats
#### Community channels/chats
The unique identifier for a community channel/chat is the chat id.
<!-- Don't enforce any constraints on the unique id generation -->
@ -332,7 +332,7 @@ contentTopic = "/waku/1/0x" + topic + "/rfc26"
```
### Community event messages
#### 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.
@ -352,11 +352,11 @@ for i = 0; i < topicLen; i++ {
contentTopic = "/waku/1/0x" + topic + "/rfc26"
```
## Community Management
### Community Management
The flows for Community management are as described below.
### Community Creation Flow
#### Community Creation Flow
1. The Community owner generates a public/private key pair.
2. The Community owner configures the Community metadata, according to the wire format "CommunityDescription".
@ -366,18 +366,18 @@ The Community metadata MAY be sent during fixed intervals, to ensure that the Co
The Community metadata SHOULD be sent every time the Community metadata is updated.
4. The Community owner MAY advertise the Community out of band, by sharing the public key of the Community on other mediums of communication.
### Community Join Flow (peer requests to join a Community)
#### 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](/spec/55/).
1. A peer and the Community owner establish a 1:1 chat as described in [55/STATUS-1TO1-CHAT](../55/1to1-chat.md).
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. The Community owner MAY accept or reject the request.
4. If the request is accepted, the Community owner sends a "CommunityRequestToJoinResponse" message to the peer.
5. The Community owner then adds the member to the Community metadata, and publishes the updated Community metadata.
### Community Join Flow (peer is invited to join a Community)
#### 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](/spec/55/).
1. The Community owner and peer establish a 1:1 chat as described in [55/STATUS-1TO1-CHAT](../55/1to1-chat.md).
2. The peer is invited to join a Community by the Community owner, by sending a "CommunityInvitation" message.
3. The peer decrypts the "CommunityInvitation" message, and verifies the signature.
4. The peer requests to join a Community by sending a "CommunityRequestToJoin" message to the Community.
@ -385,52 +385,52 @@ At this point, the peer MAY send a "CommunityCancelRequestToJoin" message to can
6. If the request is accepted, the Community owner sends a "CommunityRequestToJoinResponse" message to the peer.
7. The Community owner then adds the member to the Community metadata, and publishes the updated Community metadata.
### Community Leave Flow
#### Community Leave Flow
1. A member requests to leave a Community by sending a "CommunityRequestToLeave" message to the Community.
2. The Community owner MAY accept or reject the request.
3. If the request is accepted, the Community owner removes the member from the Community metadata, and publishes the updated Community metadata.
### Community Ban Flow
#### Community Ban Flow
1. The Community owner adds a member to the ban list, revokes their grants, and publishes the updated Community metadata.
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.
## Waku Protocols
### Waku Protocols
The following Waku protocols SHOULD be used to implement Status Communities -
1. [11/WAKU2-RELAY](/spec/11/) - To send and receive messages
2. [53/WAKU2-X3DH](/spec/53/) - To encrypt and decrypt messages
3. [53/WAKU2-X3DH-SESSIONS](/spec/54/) - To handle session keys
4. [14/WAKU2-MESSAGE](/spec/14/) - To wrap community messages in a Waku message
5. [13/WAKU2-STORE](/spec/13/) - To store and retrieve messages for offline devices
1. [11/WAKU2-RELAY](../../waku/standards/core/11/relay.md) - To send and receive messages
2. [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh.md) - To encrypt and decrypt messages
3. [54/WAKU2-X3DH-SESSIONS](/spec/54/x3dh-sessions.md) - To handle session keys
4. [14/WAKU2-MESSAGE](../../waku/standards/core/14/message.md) - To wrap community messages in a Waku message
5. [13/WAKU2-STORE](../../waku/standards/core/13/store.md) - To store and retrieve messages for offline devices
The following Waku protocols MAY be used to implement Status Communities -
1. [12/WAKU2-FILTER](/spec/12/) - Content filtering for resource restricted devices
2. [19/WAKU2-LIGHTPUSH](/spec/19) - Allows Light clients to participate in the network
1. [12/WAKU2-FILTER](../../waku/standards/core/12/filter.md) - Content filtering for resource restricted devices
2. [19/WAKU2-LIGHTPUSH](../../waku/standards/core/19/lightpush.md) - Allows Light clients to participate in the network
## Backups
### 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](/spec/13/) for storing and retrieving messages.
This feature relies on [13/WAKU2-STORE](../../waku/standards/core/13/store.md) for storing and retrieving messages.
## Clock
### 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
## Security Considerations
1. The Community owner is a single point of failure. If the Community owner is compromised, the Community is compromised.
2. Follows the same security considerations as the [53/WAKU2-X3DH](/spec/53/) protocol.
2. Follows the same security considerations as the [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh.md) protocol.
# Future work
## 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](https://hackmd.io/rD1OfIbJQieDe3GQdyCRTw)
@ -438,23 +438,22 @@ This allows ordering of messages in an asynchronous network where messages may b
3. Sharding the content topic used for [#Community Event Messages](#community-event-messages), since members of the community don't need to receive all the control messages.
# Copyright
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
# References
## References
- [55/STATUS-1TO1-CHAT](/spec/55/)
- [53/WAKU2-X3DH](/spec/53/)
- [19/WAKU2-LIGHTPUSH](/spec/19/)
- [14/WAKU2-MESSAGE](/spec/14/)
- [10/WAKU2](/spec/10/)
- [11/WAKU2-RELAY](/spec/11/)
- [54/WAKU2-X3DH-SESSIONS](/spec/54/)
- [13/WAKU2-STORE](/spec/13/)
- [12/WAKU2-FILTER](/spec/12/)
- [19/WAKU2-LIGHTPUSH](/spec/19/)
- [55/STATUS-1TO1-CHAT](../55/1to1-chat.md)
- [53/WAKU2-X3DH](../../waku/standards/application/53/x3dh.md)
- [19/WAKU2-LIGHTPUSH](../../waku/standards/core/19/lightpush.md)
- [14/WAKU2-MESSAGE](../../waku/standards/core/14/message.md)
- [10/WAKU2](../../waku/standards/core/10/waku2.md)
- [11/WAKU2-RELAY](../../waku/standards/core/11/relay.md)
- [54/WAKU2-X3DH-SESSIONS](/spec/54/x3dh-sessions.md)
- [13/WAKU2-STORE](../../waku/standards/core/13/store.md)
- [12/WAKU2-FILTER](../../waku/standards/core/12/filter.md)
## informative
### informative
- [community.go](https://github.com/status-im/status-go/blob/6072bd17ab1e5d9fc42cf844fcb8ad18aa07760c/protocol/communities/community.go)
- [organisation-channels.md](https://github.com/status-im/specs/blob/403b5ce316a270565023fc6a1f8dec138819f4b0/docs/raw/organisation-channels.md)