Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add spec for status protocol stack, deprecate waku-usage spec #105

Merged
merged 10 commits into from
Oct 25, 2024
Prev Previous commit
Next Next commit
docs: missed some spots
jm-clius committed Oct 25, 2024
commit 1ece043080d94dbd17d98c545cfb769320ec5710
6 changes: 3 additions & 3 deletions status/raw/status-app-protocols.md
Original file line number Diff line number Diff line change
@@ -14,7 +14,7 @@
## Abstract

This specification describes the Status Application protocol stack.
It focuses on elements and features in the protocol stack for all application-level functions:

Check failure on line 17 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:17:81 MD013/line-length Line length [Expected: 80; Actual: 94] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md

Check failure on line 17 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:17:81 MD013/line-length Line length [Expected: 80; Actual: 94] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md

- functional scope (also _broadcast audience_)
- content topic
@@ -23,7 +23,7 @@
- encryption layer
- transport layer (Waku)

It also introduces strategies to restrict resource usage, distribute large messages, etc.

Check failure on line 26 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:26:81 MD013/line-length Line length [Expected: 80; Actual: 89] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md

Check failure on line 26 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:26:81 MD013/line-length Line length [Expected: 80; Actual: 89] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md
Application-level functions are out of scope and specified separately. See:

- [55/STATUS-1TO1-CHAT](../55/1to1-chat.md)
@@ -53,31 +53,31 @@
- Status 1:1 Chat, as specified in [55/STATUS-1TO1-CHAT](../55/1to1-chat.md)
- Status Private Group Chat, as specified in a subsection of [55/STATUS-1TO1-CHAT](../55/1to1-chat.md#negotiation-of-a-11-chat-amongst-multiple-participants-group-chat)

<!-- TODO: list functions not related to main app features, such as user sync, backup, push notifications, etc. -->

Check failure on line 56 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:56:81 MD013/line-length Line length [Expected: 80; Actual: 115] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md

Check failure on line 56 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:56:81 MD013/line-length Line length [Expected: 80; Actual: 115] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md

Each application-level function, regardless which feature set it supports, has the following properties:

Check failure on line 58 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:58:81 MD013/line-length Line length [Expected: 80; Actual: 104] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md

Check failure on line 58 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:58:81 MD013/line-length Line length [Expected: 80; Actual: 104] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md

1. Functional scope
2. Content topic
3. Ephemerality
1. Content topic
1. Ephemerality

### Functional Scope

Each Status app-level message MUST define a functional scope.
The functional scope MUST define the _minimum_ scope of the audience that should _participate_ in the app function the message is related to.

Check failure on line 67 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:67:81 MD013/line-length Line length [Expected: 80; Actual: 141] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md

Check failure on line 67 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:67:81 MD013/line-length Line length [Expected: 80; Actual: 141] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md
In other words, it determines the minimum subset of Status app participants
that should have access to messages related to that function.

Note that the functional scope is distinct from the number of participants that is _addressed_ by a specific message.

Check failure on line 71 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:71:81 MD013/line-length Line length [Expected: 80; Actual: 117] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md

Check failure on line 71 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:71:81 MD013/line-length Line length [Expected: 80; Actual: 117] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md
For example, a participant will address a 1:1 chat to only one other participant.
However, since all users of the Status app MUST be able to participate in 1:1 chats,
the functional scope of messages enabling 1:1 chats MUST be a global scope.
Similarly, since private group chats can be set up between any subset of Status app users,

Check failure on line 75 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:75:81 MD013/line-length Line length [Expected: 80; Actual: 90] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md

Check failure on line 75 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:75:81 MD013/line-length Line length [Expected: 80; Actual: 90] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md
the functional scope for messages related to private group chats MUST be global.
As a counter-example, messages that originate within a community (and are _addressed_ to members of that community)

Check failure on line 77 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:77:81 MD013/line-length Line length [Expected: 80; Actual: 115] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md

Check failure on line 77 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:77:81 MD013/line-length Line length [Expected: 80; Actual: 115] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md
are only of interest to participants that are also members of that community.
Such messages MUST have a community-wide functional scope.
A third group of messages are addressed only to the participant that generated those messages itself.

Check failure on line 80 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:80:81 MD013/line-length Line length [Expected: 80; Actual: 101] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md

Check failure on line 80 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:80:81 MD013/line-length Line length [Expected: 80; Actual: 101] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md
These _self-addressed_ messages MUST have a local functional scope.

If we further make a distinction between "control" and "content" messages,
@@ -87,7 +87,7 @@

#### Global scope

1. _Global control_: messages enabling the basic functioning of the app to control features that all app users should be able to participate in. Examples include Contact Requests, Community Invites, global Status Updates, Group Chat Invites, etc.

Check failure on line 90 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:90:81 MD013/line-length Line length [Expected: 80; Actual: 246] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md

Check failure on line 90 in status/raw/status-app-protocols.md

GitHub Actions / lint

Line length

status/raw/status-app-protocols.md:90:81 MD013/line-length Line length [Expected: 80; Actual: 246] https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md013.md
2. _Global content_: messages carrying user-generated content for global functions. Examples include 1:1 chat messages, images shared over private group chats, etc.

#### Community scope
@@ -140,7 +140,7 @@
The end-to-end reliability layer contains the functions related to one of the two end-to-end reliability schemes defined for Status app messages:

1. Minimum Viable protocol for Data Synchronisation, or MVDS (see [STATUS-MVDS-USAGE](./status-mvds.md))
2. Scalable distributed log reliability (spec and a punchier name TBD, see the [original forum post announcement](https://forum.vac.dev/t/end-to-end-reliability-for-scalable-distributed-logs/293/16))
1. Scalable distributed log reliability (spec and a punchier name TBD, see the [original forum post announcement](https://forum.vac.dev/t/end-to-end-reliability-for-scalable-distributed-logs/293/16))

Ephemeral messages SHOULD omit this layer.
Non-ephemeral 1:1 chat messages SHOULD make use of MVDS to achieve reliable data synchronisation between the two parties involved in the communication.