status-im/specs
2
0
Fork 0
mirror of https://github.com/status-im/specs.git synced 2025-01-27 14:45:06 +00:00
Code Issues Projects Releases Wiki Activity

x4: protocol overview move payload stuff

Browse Source
This commit is contained in:
Oskar Thoren 2019-04-22 12:56:11 +08:00
parent e4acdcc909
commit 6f6031d70e
No known key found for this signature in database
GPG Key ID: 33AAFB33580C538E
2 changed files with 66 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
x4.md
View File

@ -125,7 +125,7 @@ The goal of this protocol is to allow people running Ethereum nodes with Whisper
It's important to notice that messages [are not limited to be text messages](#content-types) only. They can also have special meaning depending on the client implementation. For example, in the current implementation, there are message which informs about Eth requests.
This protocol consist of three components:
* payload
* [payload](x8.md)
* Whisper adapter
* offline messaging.
@ -137,64 +137,6 @@ Offline messaging describes how the protocol handles delivering messages when on
The protocol does not specify additional things like peers discovery, running Whisper nodes, underlying p2p protocols etc.
# Payload
Payload is an array of bytes exchanged between peers. In the case of this protocol, the payload is encoded using [transit format](https://github.com/cognitect/transit-format). It is a text-based format so even encoded version is easily readable by humans.
Payload contains the following fields:
1. text `string`
2. content type `enum { text/plain }` (more in [Content types](#content-types))
3. message type `enum { public-group-user-message, user-message, group-user-message }` (more in [Message types](#message-types))
4. clock `int64`
5. timestamp `int64`
6. content `struct { chat-id string, text string }`
Example of a valid encoded payload:
```
["~#c4",["abc123","text/plain","~:public-group-user-message",154593077368201,1545930773682,["^ ","~:chat-id","testing-adamb","~:text","abc123"]]]
```
As you can see, the message is an array and each index value has its meaning:
* 0: `c4` is a decoder handler identification for the current payload format. Identifications allow to register handlers for many different types of payload
* 1: array which items correspond to the described payload fields above
For more details regarding serialization and deserialization please consult [transit format](https://github.com/cognitect/transit-format) specification.
## Content types
Content types are required for a proper interpretation of incoming messaages. Not each message is a plain text but may carry a different information.
The following content types MUST be supported:
* `text/plain` identifies a message which content is a plain text
* `sticker` TODO
* `status` TODO
* `command` TODO
* `command-request` TODO
* `emoji` TODO
TODO: select which are required and which are client-specific.
## Message types
Message types are required to decide how a particular message is encrypted (more in [Whisper > Message encryption](#message-encryption)) and what metadata needs to be attacjed (more in [Whisper > Topic](#topic)) when passing a message to the transport layer.
The following messages types MUST be supported:
* `public-group-user-message` is a message to the public group
* `user-message` is a private message
* `group-user-message` is a message to the private group.
## Clock vs Timestamp and message ordering
`timestamp` MUST be Unix time calculated when the message is created. Because the peers in the Whisper network should have synchronized time, `timestamp` values should be fairly accurate among all Whisper network participants.
`clock` SHOULD be calculated using the algorithm of [Lamport timestamps](https://en.wikipedia.org/wiki/Lamport_timestamps). When there are messages available in a chat, `clock`'s value is calculated based on the last received message in a particular chat: `last-message-clock-value + 1`. If there are no messages, `clock` is initialized with `timestamp`'s value.
`clock` value is used for the message ordering. Due to the used algorithm and distributed nature of the system, we achieve casual ordering which might produce counterintuitive results in some edge cases. For example, when one joins a public chat and sends a message before receiving the exist messages, their message `clock` value might be lower and the message will end up in the past when the historical messages are fetched.
## Replies
TBD
# Whisper adapter

67
x8.md
View File

@ -14,8 +14,71 @@ Using Adam's spec as starting point. Also be mindful of integration with the ove
**TODO: Remove non transport privacy layer aspects here**
Status Secure Messaging Protocol
==================================================
# Payload
# Payload
Payload is an array of bytes exchanged between peers. In the case of this protocol, the payload is encoded using [transit format](https://github.com/cognitect/transit-format). It is a text-based format so even encoded version is easily readable by humans. For more information about the payload in Status, please see [Initial Message Payload Specification Specification](x8.md).
Payload contains the following fields:
1. text `string`
2. content type `enum { text/plain }` (more in [Content types](#content-types))
3. message type `enum { public-group-user-message, user-message, group-user-message }` (more in [Message types](#message-types))
4. clock `int64`
5. timestamp `int64`
6. content `struct { chat-id string, text string }`
Example of a valid encoded payload:
```
["~#c4",["abc123","text/plain","~:public-group-user-message",154593077368201,1545930773682,["^ ","~:chat-id","testing-adamb","~:text","abc123"]]]
```
As you can see, the message is an array and each index value has its meaning:
* 0: `c4` is a decoder handler identification for the current payload format. Identifications allow to register handlers for many different types of payload
* 1: array which items correspond to the described payload fields above
For more details regarding serialization and deserialization please consult [transit format](https://github.com/cognitect/transit-format) specification.
## Content types
Content types are required for a proper interpretation of incoming messaages. Not each message is a plain text but may carry a different information.
The following content types MUST be supported:
* `text/plain` identifies a message which content is a plain text
* `sticker` TODO
* `status` TODO
* `command` TODO
* `command-request` TODO
* `emoji` TODO
TODO: select which are required and which are client-specific.
## Message types
Message types are required to decide how a particular message is encrypted (more in [Whisper > Message encryption](#message-encryption)) and what metadata needs to be attacjed (more in [Whisper > Topic](#topic)) when passing a message to the transport layer.
The following messages types MUST be supported:
* `public-group-user-message` is a message to the public group
* `user-message` is a private message
* `group-user-message` is a message to the private group.
## Clock vs Timestamp and message ordering
`timestamp` MUST be Unix time calculated when the message is created. Because the peers in the Whisper network should have synchronized time, `timestamp` values should be fairly accurate among all Whisper network participants.
`clock` SHOULD be calculated using the algorithm of [Lamport timestamps](https://en.wikipedia.org/wiki/Lamport_timestamps). When there are messages available in a chat, `clock`'s value is calculated based on the last received message in a particular chat: `last-message-clock-value + 1`. If there are no messages, `clock` is initialized with `timestamp`'s value.
`clock` value is used for the message ordering. Due to the used algorithm and distributed nature of the system, we achieve casual ordering which might produce counterintuitive results in some edge cases. For example, when one joins a public chat and sends a message before receiving the exist messages, their message `clock` value might be lower and the message will end up in the past when the historical messages are fetched.
## Replies
TBD
# Status Secure Messaging Protocol
- [Status Secure Messaging Protocol](#status-secure-messaging-protocol)
- [Abstract](#abstract)