From 0348720fd217d7114400ef91c2c9c4381c5d9ada Mon Sep 17 00:00:00 2001 From: Samuel Hawksby-Robinson Date: Tue, 8 Sep 2020 16:24:52 +0100 Subject: [PATCH 01/14] Updated draft payload spec to stable --- docs/stable/6-payloads.md | 192 +++++++++++++++++++++++++++++--------- 1 file changed, 147 insertions(+), 45 deletions(-) diff --git a/docs/stable/6-payloads.md b/docs/stable/6-payloads.md index 1039abb7..4ae1891b 100644 --- a/docs/stable/6-payloads.md +++ b/docs/stable/6-payloads.md @@ -6,11 +6,11 @@ title: 6/PAYLOADS # 6/PAYLOADS -> Version: 0.3 +> Version: 0.6 > > Status: Stable > -> Authors: Adam Babik , Andrea Maria Piana , Oskar Thorén (alphabetical order) +> Authors: Adam Babik , Andrea Maria Piana , Oskar Thorén , Samuel Hawksby-Robinson (alphabetical order) ## Abstract @@ -34,12 +34,15 @@ as various clients created using different technologies. - [Payload](#payload-1) - [Content types](#content-types) - [Sticker content type](#sticker-content-type) + - [Image content type](#image-content-type) + - [Audio content type](#audio-content-type) - [Message types](#message-types) - [Clock vs Timestamp and message ordering](#clock-vs-timestamp-and-message-ordering) - [Chats](#chats) - [Contact Update](#contact-update) - [Payload](#payload-2) - [Contact update](#contact-update-1) + - [EmojiReaction](#emojireaction) - [SyncInstallationContact](#syncinstallationcontact) - [Payload](#payload-3) - [SyncInstallationPublicChat](#syncinstallationpublicchat) @@ -50,7 +53,7 @@ as various clients created using different technologies. - [Upgradability](#upgradability) - [Security Considerations](#security-considerations) - [Changelog](#changelog) - - [Version 0.3](#version-03) + - [Copyright](#copyright) ## Introduction @@ -62,36 +65,9 @@ The node wraps all payloads in a [protobuf record](https://developers.google.com record: ```protobuf -message ApplicationMetadataMessage { - bytes signature = 1; - bytes payload = 2; - - Type type = 3; - - enum Type { - UNKNOWN = 0; - CHAT_MESSAGE = 1; - CONTACT_UPDATE = 2; - MEMBERSHIP_UPDATE_MESSAGE = 3; - PAIR_INSTALLATION = 4; - SYNC_INSTALLATION = 5; - REQUEST_ADDRESS_FOR_TRANSACTION = 6; - ACCEPT_REQUEST_ADDRESS_FOR_TRANSACTION = 7; - DECLINE_REQUEST_ADDRESS_FOR_TRANSACTION = 8; - REQUEST_TRANSACTION = 9; - SEND_TRANSACTION = 10; - DECLINE_REQUEST_TRANSACTION = 11; - SYNC_INSTALLATION_CONTACT = 12; - SYNC_INSTALLATION_ACCOUNT = 13; - SYNC_INSTALLATION_PUBLIC_CHAT = 14; - CONTACT_CODE_ADVERTISEMENT = 15; - PUSH_NOTIFICATION_REGISTRATION = 16; - PUSH_NOTIFICATION_REGISTRATION_RESPONSE = 17; - PUSH_NOTIFICATION_QUERY = 18; - PUSH_NOTIFICATION_QUERY_RESPONSE = 19; - PUSH_NOTIFICATION_REQUEST = 20; - PUSH_NOTIFICATION_RESPONSE = 21; - } +message StatusProtocolMessage { + bytes signature = 4001; + bytes payload = 4002; } ``` @@ -99,8 +75,6 @@ message ApplicationMetadataMessage { The node needs the signature to validate authorship of the message, so that the message can be relayed to third parties. If a signature is not present, but an author is provided by a layer below, the message is not to be relayed to third parties, and it is considered plausibly deniable. -`payload` is the protobuf encoded content of the message, with the corresponding `type` set. - ## Encoding The node encodes the payload using [Protobuf](https://developers.google.com/protocol-buffers) @@ -131,7 +105,6 @@ message ChatMessage { // Chat id, this field is symmetric for public-chats and private group chats, // but asymmetric in case of one-to-ones, as the sender will use the chat-id // of the received, while the receiver will use the chat-id of the sender. - // Probably should be the concatenation of sender-pk & receiver-pk in alphabetical order string chat_id = 6; // The type of message (public/one-to-one/private-group-chat) @@ -141,15 +114,10 @@ message ChatMessage { oneof payload { StickerMessage sticker = 9; + ImageMessage image = 10; + AudioMessage audio = 11; } - enum MessageType { - UNKNOWN_MESSAGE_TYPE = 0; - ONE_TO_ONE = 1; - PUBLIC_GROUP = 2; - PRIVATE_GROUP = 3; - // Only local - SYSTEM_MESSAGE_PRIVATE_GROUP = 4;} enum ContentType { UNKNOWN_CONTENT_TYPE = 0; TEXT_PLAIN = 1; @@ -159,6 +127,8 @@ message ChatMessage { TRANSACTION_COMMAND = 5; // Only local SYSTEM_MESSAGE_CONTENT_PRIVATE_GROUP = 6; + IMAGE = 7; + AUDIO = 8; } } ``` @@ -175,7 +145,7 @@ message ChatMessage { | 6 | chat_id | `string` | The local ID of the chat the message is sent to | | 7 | message_type | `MessageType` | The type of message, different for one-to-one, public or group chats | | 8 | content_type | `ContentType` | The type of the content of the message | -| 9 | payload | `Sticker|nil` | The payload of the message based on the content type | +| 9 | payload | `Sticker` I `Image` I `Audio` I `nil` | The payload of the message based on the content type | #### Content types @@ -189,6 +159,8 @@ There are other content types that MAY be implemented by the client: * `STATUS` * `EMOJI` * `TRANSACTION_COMMAND` +* `IMAGE` +* `AUDIO` ##### Mentions @@ -211,9 +183,59 @@ message StickerMessage { } ``` +##### Image content type + +A `ChatMessage` with `IMAGE` `Content/Type` MUST also specify the `payload` of the image +and the `type`. + +Clients MUST sanitize the payload before accessing its content, in particular: +- Clients MUST choose a secure decoder +- Clients SHOULD strip metadata if present without parsing/decoding it +- Clients SHOULD NOT add metadata/exif when sending an image file for privacy and security reasons +- Clients MUST make sure that the transport layer constraints the size of the payload to limit they are able to handle securely + + +```protobuf +message ImageMessage { + bytes payload = 1; + ImageType type = 2; + enum ImageType { + UNKNOWN_IMAGE_TYPE = 0; + PNG = 1; + JPEG = 2; + WEBP = 3; + GIF = 4; + } +} +``` + +##### Audio content type + +A `ChatMessage` with `AUDIO` `Content/Type` MUST also specify the `payload` of the audio, +the `type` and the duration in milliseconds (`duration_ms`). + +Clients MUST sanitize the payload before accessing its content, in particular: +- Clients MUST choose a secure decoder +- Clients SHOULD strip metadata if present without parsing/decoding it +- Clients SHOULD NOT add metadata/exif when sending an audio file for privacy and security reasons +- Clients MUST make sure that the transport layer constraints the size of the payload to limit they are able to handle securely + +```protobuf +message AudioMessage { + bytes payload = 1; + AudioType type = 2; + uint64 duration_ms = 3; + enum AudioType { + UNKNOWN_AUDIO_TYPE = 0; + AAC = 1; + AMR = 2; + } +} +``` + #### Message types -A node requires message types to decide how to encrypt a particular message and what metadata needs to be attached when passing a message to the transport layer. For more on this, see [3/WHISPER-USAGE](3-whisper-usage.md) and [10/WAKU-USAGE](10-waku-usage.md). +A node requires message types to decide how to encrypt a particular message and what metadata needs to be attached when passing a message to the transport layer. For more on this, see [3/WHISPER-USAGE](./3-whisper-usage.md) and [10/WAKU-USAGE](./10-waku-usage.md). @@ -223,6 +245,17 @@ The following messages types MUST be supported: * `PUBLIC_GROUP` is a private message * `PRIVATE_GROUP` is a message to the private group. +```protobuf + enum MessageType { + UNKNOWN_MESSAGE_TYPE = 0; + ONE_TO_ONE = 1; + PUBLIC_GROUP = 2; + PRIVATE_GROUP = 3; + // Only local + SYSTEM_MESSAGE_PRIVATE_GROUP = 4; +} +``` + #### Clock vs Timestamp and message ordering If a user sends a new message before the messages sent while the user was offline are received, the new @@ -288,6 +321,52 @@ A client SHOULD send a `ContactUpdate` to all the contacts each time: A client SHOULD also periodically send a `ContactUpdate` to all the contacts, the interval is up to the client, the Status official client sends these updates every 48 hours. +### EmojiReaction + +`EmojiReaction`s represents a user's "reaction" to a specific chat message. For more information about the concept of +emoji reactions see [Facebook Reactions](https://en.wikipedia.org/wiki/Facebook_like_button#Use_on_Facebook). + +This specification RECOMMENDS that the UI/UX implementation of sending `EmojiReactions` requires only a single click +operation, as users have an expectation that emoji reactions are effortless and simple to perform. + +```protobuf +message EmojiReaction { + // clock Lamport timestamp of the chat message + uint64 clock = 1; + + // chat_id the ID of the chat the message belongs to, for query efficiency the chat_id is stored in the db even though the + // target message also stores the chat_id + string chat_id = 2; + + // message_id the ID of the target message that the user wishes to react to + string message_id = 3; + + // message_type is (somewhat confusingly) the ID of the type of chat the message belongs to + MessageType message_type = 4; + + // type the ID of the emoji the user wishes to react with + Type type = 5; + + enum Type { + UNKNOWN_EMOJI_REACTION_TYPE = 0; + LOVE = 1; + THUMBS_UP = 2; + THUMBS_DOWN = 3; + LAUGH = 4; + SAD = 5; + ANGRY = 6; + } + + // whether this is a retraction of a previously sent emoji + bool retracted = 6; +} +``` + +Clients MUST specify `clock`, `chat_id`, `message_id`, `type` and `message_type`. + +This specification RECOMMENDS that the UI/UX implementation of retracting an `EmojiReaction`s requires only a single +click operation, as users have an expectation that emoji reaction removals are effortless and simple to perform. + ### SyncInstallationContact The node uses `SyncInstallationContact` messages to synchronize in a best-effort the contacts to other devices. @@ -372,8 +451,31 @@ There are two ways to upgrade the protocol without breaking compatibility: ## Changelog +### Version 0.6 + +Release //TODO + +- Updated draft spec to stable status + +### Version 0.5 + +Released [August 25, 2020](https://github.com/status-im/specs/commit/968fafff23cdfc67589b34dd64015de29aaf41f0) + +- Added support for emoji reactions + +### Version 0.4 + +Released [July 16, 2020](https://github.com/status-im/specs/commit/ad45cd5fed3c0f79dfa472253a404f670dd47396) + +- Added support for images +- Added support for audio + ### Version 0.3 Released [May 22, 2020](https://github.com/status-im/specs/commit/664dd1c9df6ad409e4c007fefc8c8945b8d324e8) - Added language to include Waku in all relevant places + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 4ed839959d47dc646aceff884eb8b3f7f28b521c Mon Sep 17 00:00:00 2001 From: Samuel Hawksby-Robinson Date: Tue, 8 Sep 2020 16:53:47 +0100 Subject: [PATCH 02/14] Minor fix of backtick --- docs/draft/6-payloads.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/draft/6-payloads.md b/docs/draft/6-payloads.md index 01a3c0f4..ed839b79 100644 --- a/docs/draft/6-payloads.md +++ b/docs/draft/6-payloads.md @@ -261,7 +261,7 @@ message is supposed to be displayed last in a chat. This is where the basic algo as it's only meant to order causally related events. The status client therefore makes a "bid", speculating that it will beat the current chat-timestamp, s.t. the status client's -Lamport timestamp format is: `clock = `max({timestamp}, chat_clock + 1)` +Lamport timestamp format is: `clock = max({timestamp}, chat_clock + 1)` This will satisfy the Lamport requirement, namely: a -> b then T(a) < T(b) From 780773a9fcf3a16efcff8a5fa48c5c7d4b7584cc Mon Sep 17 00:00:00 2001 From: Samuel Hawksby-Robinson Date: Wed, 9 Sep 2020 14:54:26 +0100 Subject: [PATCH 03/14] First review ready draft of ChatMessageIdentity --- docs/draft/6-payloads.md | 129 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 127 insertions(+), 2 deletions(-) diff --git a/docs/draft/6-payloads.md b/docs/draft/6-payloads.md index ed839b79..2c45362d 100644 --- a/docs/draft/6-payloads.md +++ b/docs/draft/6-payloads.md @@ -39,6 +39,7 @@ as various clients created using different technologies. - [Message types](#message-types) - [Clock vs Timestamp and message ordering](#clock-vs-timestamp-and-message-ordering) - [Chats](#chats) + - [Chat Message Identity](#chat-message-identity) - [Contact Update](#contact-update) - [Payload](#payload-2) - [Contact update](#contact-update-1) @@ -100,7 +101,7 @@ message ChatMessage { string text = 3; // Id of the message that we are replying to string response_to = 4; - // Ens name of the sender + // DEPRECATED. Ens name of the sender string ens_name = 5; // Chat id, this field is symmetric for public-chats and private group chats, // but asymmetric in case of one-to-ones, as the sender will use the chat-id @@ -141,7 +142,7 @@ message ChatMessage { | 2 | timestamp | `uint64` | The sender timestamp at message creation | | 3 | text | `string` | The content of the message | | 4 | response_to | `string` | The ID of the message replied to | -| 5 | ens_name | `string` | The ENS name of the user sending the message | +| 5 | ens_name | `string` | DEPRECATED - [See Chat Message Identity](#chat-message-identity). The ENS name of the user sending the message | | 6 | chat_id | `string` | The local ID of the chat the message is sent to | | 7 | message_type | `MessageType` | The type of message, different for one-to-one, public or group chats | | 8 | content_type | `ContentType` | The type of the content of the message | @@ -288,6 +289,124 @@ All incoming messages can be matched against a chat. The below table describes h |user-message|let `P` be a public key of message's signature; `hex-encode(P)` is a chat ID; discard `chat-id` from message|Incoming|if there is no matched chat, it might be the first message from public key `P`; the node MAY discard the message or MAY create a new chat; Status official clients create a new chat| |PRIVATE_GROUP|use `chatId` from the message|Incoming/Outgoing|find an existing chat by `chatId`; if none is found, the user is not a member of that chat or the user hasn't joined that chat, the message MUST be discarded | +### Chat Message Identity + +The `ChatMessageIdentity` allows a user to OPTIONALLY broadcast an identity to be associated with their messages. + +The main components of the `ChatMessageIdentity` are: + +| Field name | Description | +| --------------- |---| +| `ens_name` | A valid registered ENS name for the user. Deprecates the `ens_name` field in `ChatMessage` | +| `display_name` | A user determined display name not requiring blockchain registry | +| `profile_image` | A `ProfileImage` data struct used to transmit user profile image data | + +#### Profile Image + +The `ProfileImage` data struct describes the mechanisms by which the application parses and presents the user's chosen visual representation. + +The main components of the `ProfileImage` are: + +| Field name | Description | +| --------------- |---| +| `payload` | A context based payload for the profile image data. Context is determined by the `source_type` | +| `source_type` | A `SourceType` enum, signals the image payload source | +| `image_type` | An `ImageType` enum, signals the image type and method of parsing the payload | + +#### Payload + +```protobuf +syntax="proto3"; + +// ChatMessageIdentity represents the user defined identity associated with their messages +message ChatMessageIdentity { + // Lamport timestamp of the chat message + uint64 clock = 1; + + // ens_name is the valid ENS name associated with the chat key + string ens_name = 2; + + // display_name is the user's chosen display name + string display_name = 3; + + // profile_image is the data associated with the user's profile image + ProfileImage profile_image = 4; +} + +// ProfileImage represents data associated with a user's profile image +message ProfileImage { + + // payload is a context based payload for the profile image data, + // context is determined by the `source_type` + string 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; + + // SourceType are the predefined types of image source allowed + enum SourceType { + UNKNOWN_SOURCE_TYPE = 0; + + // RAW_PAYLOAD uses base64 encoded image data + // `payload` must be set + // `payload` is base64 encoded image 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 + // The parent `ChatMessageIdentity` must have a valid `ens_name` set + ENS_AVATAR = 2; + } + + // ImageType is the type of profile image data + enum ImageType { + UNKNOWN_IMAGE_TYPE = 0; + + // RASTER_IMAGE_FILE is payload data that can be read as a raster image + // examples: jpg, png, gif, webp file types + RASTER_IMAGE_FILE = 1; + + // VECTOR_IMAGE_FILE is payload data that can be interpreted as a vector image + // example: svg file type + VECTOR_IMAGE_FILE = 2; + + // AVATAR is payload data that can be parsed as avatar compilation instructions + AVATAR = 3; + } + +} +``` + +#### Implementation Recommendations + +##### Identity Update + +An `IdentityUpdate` is a concept representing the event of the application sending a `ChatMessageIdentity` in response to either: + +- sending the user's first message in a chat topic +- sending a message to a chat topic after a change to the user identity +- sending a message to a chat topic after the expiry of the chat type `ChatMessageIdentity TTL` period + +##### One-To-One Chat + +This specification RECOMMENDS that the application only sends one `IdentityUpdate`, with no `ChatMessageIdentity TTL`. + +##### Private Group Chat + +This specification RECOMMENDS that the application only sends one `IdentityUpdate`, with not `ChatMessageIdentity TTL`, and once per new user joining the chat group. + +##### Public Chat + + This specification RECOMMENDS that the application only sends one `IdentityUpdate`, with a `ChatMessageIdentity TTL` of 24 hours. + +##### Security + +To preserve the privacy of the user, the `ProfileImage.payload` or ENS `get-text-data.avatar` field SHOULD NOT be or be parsed as a URL, an IPFS address or an IPNS address. Malicious actors could set their payload to an image URL and force all users that parse their `ProfileImage.payload` and log the IP address of users of selected topics. + ### Contact Update `ContactUpdate` is a message exchange to notify peers that either the @@ -449,6 +568,12 @@ There are two ways to upgrade the protocol without breaking compatibility: ## Changelog +### Version 0.7 + +Released //TODO + +- Added Chat Identity payload + ### Version 0.5 Released [August 25, 2020](https://github.com/status-im/specs/commit/968fafff23cdfc67589b34dd64015de29aaf41f0) From fcca4b27a2992e157023de58aec33df21f2e260e Mon Sep 17 00:00:00 2001 From: Samuel Hawksby-Robinson Date: Wed, 9 Sep 2020 15:06:15 +0100 Subject: [PATCH 04/14] Updata to changelog --- docs/draft/6-payloads.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/draft/6-payloads.md b/docs/draft/6-payloads.md index 2c45362d..ccc90085 100644 --- a/docs/draft/6-payloads.md +++ b/docs/draft/6-payloads.md @@ -572,7 +572,8 @@ There are two ways to upgrade the protocol without breaking compatibility: Released //TODO -- Added Chat Identity payload +- Added `ChatMessageIdentity` payload +- Marks `ChatMessage.ens_name` as DEPRECATED ### Version 0.5 From b4cd5c1fb0160c8bd0cffcf3fe7cac522d20e402 Mon Sep 17 00:00:00 2001 From: Samuel Hawksby-Robinson Date: Wed, 9 Sep 2020 15:14:00 +0100 Subject: [PATCH 05/14] Update to wordlist --- wordlist.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/wordlist.txt b/wordlist.txt index e2bfb323..fcf60a93 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -31,6 +31,7 @@ chatId chatID chatid ChatMessage +ChatMessageIdentity contactCode contactcode ContactCodeAdvertisement @@ -123,10 +124,12 @@ identicon IK im ImageMessage +ImageType ImportECDSA ImportECDSAPublic infura IPFS +IPNS IPs Iubenda Jacek @@ -196,6 +199,8 @@ prepend prepended prepending privkey +ProfileImage +proto protobuf ProtocolMessage PSS @@ -237,10 +242,12 @@ SIP SIPs SNT Sourcecode +SourceType SPK StickerMessage stickerpack strconv +struct suboptimal subprotocol subprotocols From 13cad9fa036795f59db6797b6ca74a4f1be61c64 Mon Sep 17 00:00:00 2001 From: Samuel Hawksby-Robinson Date: Wed, 9 Sep 2020 15:23:40 +0100 Subject: [PATCH 06/14] Added note about support for ChatMessage.ens_name --- docs/draft/6-payloads.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/draft/6-payloads.md b/docs/draft/6-payloads.md index ccc90085..7b189107 100644 --- a/docs/draft/6-payloads.md +++ b/docs/draft/6-payloads.md @@ -383,6 +383,10 @@ message ProfileImage { #### Implementation Recommendations +##### ChatMessage ens_name + +The application MUST handle `ChatMessage.ens_name` as well as `ChatMessageIdentity.ens_name` to maintain backwards compatibility. The `ChatMessage.ens_name` field has been marked as DEPRECATED in this version of the specification to highlight that this field should be removed as part of any upgrade to a major version. + ##### Identity Update An `IdentityUpdate` is a concept representing the event of the application sending a `ChatMessageIdentity` in response to either: @@ -397,11 +401,11 @@ This specification RECOMMENDS that the application only sends one `IdentityUpdat ##### Private Group Chat -This specification RECOMMENDS that the application only sends one `IdentityUpdate`, with not `ChatMessageIdentity TTL`, and once per new user joining the chat group. +This specification RECOMMENDS that the application only sends one `IdentityUpdate`, with no `ChatMessageIdentity TTL`, and once per new user joining the chat group. ##### Public Chat - This specification RECOMMENDS that the application only sends one `IdentityUpdate`, with a `ChatMessageIdentity TTL` of 24 hours. +This specification RECOMMENDS that the application only sends one `IdentityUpdate`, with a `ChatMessageIdentity TTL` of 24 hours. ##### Security From fb11868a07225d9a9d0ffae6504186c871b2036e Mon Sep 17 00:00:00 2001 From: Samuel Hawksby-Robinson Date: Wed, 9 Sep 2020 15:43:27 +0100 Subject: [PATCH 07/14] IdentityUpdate MUST be after sending a message --- docs/draft/6-payloads.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/draft/6-payloads.md b/docs/draft/6-payloads.md index 7b189107..a4f6a0df 100644 --- a/docs/draft/6-payloads.md +++ b/docs/draft/6-payloads.md @@ -411,6 +411,8 @@ This specification RECOMMENDS that the application only sends one `IdentityUpdat To preserve the privacy of the user, the `ProfileImage.payload` or ENS `get-text-data.avatar` field SHOULD NOT be or be parsed as a URL, an IPFS address or an IPNS address. Malicious actors could set their payload to an image URL and force all users that parse their `ProfileImage.payload` and log the IP address of users of selected topics. +An additional step to maintaining user privacy is to adhere to the `IdentityUpdate` event triggering, `IdentityUpdate` MUST only be sent after a user sends a `ChatMessage` to a topic. This will ensure that users who wish to only read topic messages do not "leak" their identity data into topics they have not actively participated in. + ### Contact Update `ContactUpdate` is a message exchange to notify peers that either the From 0ff71505d45bd68d57215688d03ece5ee3839cb3 Mon Sep 17 00:00:00 2001 From: Samuel Hawksby-Robinson Date: Wed, 9 Sep 2020 15:45:24 +0100 Subject: [PATCH 08/14] I like neat tables --- docs/draft/6-payloads.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/draft/6-payloads.md b/docs/draft/6-payloads.md index a4f6a0df..c8874e01 100644 --- a/docs/draft/6-payloads.md +++ b/docs/draft/6-payloads.md @@ -307,11 +307,11 @@ The `ProfileImage` data struct describes the mechanisms by which the application The main components of the `ProfileImage` are: -| Field name | Description | -| --------------- |---| -| `payload` | A context based payload for the profile image data. Context is determined by the `source_type` | +| Field name | Description | +| ------------- |---| +| `payload` | A context based payload for the profile image data. Context is determined by the `source_type` | | `source_type` | A `SourceType` enum, signals the image payload source | -| `image_type` | An `ImageType` enum, signals the image type and method of parsing the payload | +| `image_type` | An `ImageType` enum, signals the image type and method of parsing the payload | #### Payload From 6cde2b09954f64e17ad665230ae59af99d46d879 Mon Sep 17 00:00:00 2001 From: Samuel Hawksby-Robinson Date: Wed, 9 Sep 2020 15:53:19 +0100 Subject: [PATCH 09/14] Updated payload tables to conform to spec convention --- docs/draft/6-payloads.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/draft/6-payloads.md b/docs/draft/6-payloads.md index c8874e01..67c3a4eb 100644 --- a/docs/draft/6-payloads.md +++ b/docs/draft/6-payloads.md @@ -295,11 +295,11 @@ The `ChatMessageIdentity` allows a user to OPTIONALLY broadcast an identity to b The main components of the `ChatMessageIdentity` are: -| Field name | Description | -| --------------- |---| -| `ens_name` | A valid registered ENS name for the user. Deprecates the `ens_name` field in `ChatMessage` | -| `display_name` | A user determined display name not requiring blockchain registry | -| `profile_image` | A `ProfileImage` data struct used to transmit user profile image data | +| Field | Name | Type | Description | +| ----- | --------------- | -------------- | --- | +| 2 | `ens_name` | `string` | A valid registered ENS name for the user. Deprecates the `ens_name` field in `ChatMessage` | +| 3 | `display_name` | `string` | A user determined display name not requiring blockchain registry | +| 4 | `profile_image` | `ProfileImage` | A data struct used to transmit user profile image data | #### Profile Image @@ -307,11 +307,11 @@ The `ProfileImage` data struct describes the mechanisms by which the application The main components of the `ProfileImage` are: -| Field name | Description | -| ------------- |---| -| `payload` | A context based payload for the profile image data. Context is determined by the `source_type` | -| `source_type` | A `SourceType` enum, signals the image payload source | -| `image_type` | An `ImageType` enum, signals the image type and method of parsing the payload | +| Field | Name | Type | Description | +| ----- | ------------- | ------------ | --- | +| 1 | `payload` | `string` | A context based payload for the profile image data. Context is determined by the `source_type` | +| 2 | `source_type` | `SourceType` | Enum, signals the image payload source | +| 3 | `image_type` | `ImageType` | Enum, signals the image type and method of parsing the payload | #### Payload From 2ddd643d0a699269c99b2e89d98a317a5a52617d Mon Sep 17 00:00:00 2001 From: Samuel Hawksby-Robinson Date: Tue, 29 Sep 2020 14:02:09 +0100 Subject: [PATCH 10/14] Updated ChatIdentity to reflect shared use of ImageType enum --- docs/draft/6-payloads.md | 84 ++++++++++++++-------------------------- 1 file changed, 30 insertions(+), 54 deletions(-) diff --git a/docs/draft/6-payloads.md b/docs/draft/6-payloads.md index 67c3a4eb..8223acb3 100644 --- a/docs/draft/6-payloads.md +++ b/docs/draft/6-payloads.md @@ -200,13 +200,6 @@ Clients MUST sanitize the payload before accessing its content, in particular: message ImageMessage { bytes payload = 1; ImageType type = 2; - enum ImageType { - UNKNOWN_IMAGE_TYPE = 0; - PNG = 1; - JPEG = 2; - WEBP = 3; - GIF = 4; - } } ``` @@ -230,6 +223,8 @@ message AudioMessage { UNKNOWN_AUDIO_TYPE = 0; AAC = 1; AMR = 2; + } +} ``` #### Message types @@ -289,17 +284,17 @@ All incoming messages can be matched against a chat. The below table describes h |user-message|let `P` be a public key of message's signature; `hex-encode(P)` is a chat ID; discard `chat-id` from message|Incoming|if there is no matched chat, it might be the first message from public key `P`; the node MAY discard the message or MAY create a new chat; Status official clients create a new chat| |PRIVATE_GROUP|use `chatId` from the message|Incoming/Outgoing|find an existing chat by `chatId`; if none is found, the user is not a member of that chat or the user hasn't joined that chat, the message MUST be discarded | -### Chat Message Identity +### Chat Identity -The `ChatMessageIdentity` allows a user to OPTIONALLY broadcast an identity to be associated with their messages. +The `ChatIdentity` allows a user to OPTIONALLY broadcast an identity to be associated with their messages. -The main components of the `ChatMessageIdentity` are: +The main components of the `ChatIdentity` are: -| Field | Name | Type | Description | -| ----- | --------------- | -------------- | --- | -| 2 | `ens_name` | `string` | A valid registered ENS name for the user. Deprecates the `ens_name` field in `ChatMessage` | -| 3 | `display_name` | `string` | A user determined display name not requiring blockchain registry | -| 4 | `profile_image` | `ProfileImage` | A data struct used to transmit user profile image data | +| Field | Name | Type | Description | +| ----- | --------------- | ---------------------------- | --- | +| 1 | `clock` | `uint64` | A lamport timestamp of the message | +| 2 | `ens_name` | `string` | A valid registered ENS name for the user. Deprecates the `ens_name` field in `ChatMessage` | +| 3 | `images` | `map` | A string indexed mapping of images associated with an identity | #### Profile Image @@ -307,78 +302,59 @@ The `ProfileImage` data struct describes the mechanisms by which the application The main components of the `ProfileImage` are: -| Field | Name | Type | Description | -| ----- | ------------- | ------------ | --- | -| 1 | `payload` | `string` | A context based payload for the profile image data. Context is determined by the `source_type` | -| 2 | `source_type` | `SourceType` | Enum, signals the image payload source | -| 3 | `image_type` | `ImageType` | Enum, signals the image type and method of parsing the payload | +| Field | Name | Type | Description | +| ----- | ------------- | ------------------ | --- | +| 1 | `payload` | `bytes` | A context based payload for the profile image data. Context is determined by the `source_type` | +| 2 | `source_type` | `SourceType` | Enum, signals the image payload source | +| 3 | `image_type` | `enums.ImageType` | Enum, signals the image type and method of parsing the payload | #### Payload ```protobuf -syntax="proto3"; +syntax = "proto3"; -// ChatMessageIdentity represents the user defined identity associated with their messages -message ChatMessageIdentity { - // Lamport timestamp of the chat message +package protobuf; + +// ChatIdentity represents the user defined identity associated with their public chat key +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; - - // display_name is the user's chosen display name - string display_name = 3; - - // profile_image is the data associated with the user's profile image - ProfileImage profile_image = 4; + + // images is a string indexed mapping of images associated with an identity + map images = 3; } // ProfileImage represents data associated with a user's profile image -message ProfileImage { +message IdentityImage { // payload is a context based payload for the profile image data, // context is determined by the `source_type` - string payload = 1; + 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; - + // SourceType are the predefined types of image source allowed enum SourceType { UNKNOWN_SOURCE_TYPE = 0; - // RAW_PAYLOAD uses base64 encoded image data - // `payload` must be set - // `payload` is base64 encoded image data + // 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 + // 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; } - - // ImageType is the type of profile image data - enum ImageType { - UNKNOWN_IMAGE_TYPE = 0; - - // RASTER_IMAGE_FILE is payload data that can be read as a raster image - // examples: jpg, png, gif, webp file types - RASTER_IMAGE_FILE = 1; - - // VECTOR_IMAGE_FILE is payload data that can be interpreted as a vector image - // example: svg file type - VECTOR_IMAGE_FILE = 2; - - // AVATAR is payload data that can be parsed as avatar compilation instructions - AVATAR = 3; - } - } + ``` #### Implementation Recommendations From fc6755f506bd831796e58e19644a034dd1e0125b Mon Sep 17 00:00:00 2001 From: Samuel Hawksby-Robinson Date: Tue, 29 Sep 2020 15:26:50 +0100 Subject: [PATCH 11/14] Updated wordlist --- wordlist.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/wordlist.txt b/wordlist.txt index fcf60a93..b7408568 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -30,6 +30,7 @@ Changelog chatId chatID chatid +ChatIdentity ChatMessage ChatMessageIdentity contactCode @@ -121,6 +122,7 @@ html http HTTPS identicon +IdentityImage IK im ImageMessage @@ -146,6 +148,7 @@ keypair keypairs Kozieiev Lamport +lamport legislations len libp From 7f086defa9d9d5ddf26c05f3095029a3a33f460c Mon Sep 17 00:00:00 2001 From: Samuel Hawksby-Robinson Date: Tue, 29 Sep 2020 15:45:22 +0100 Subject: [PATCH 12/14] Moved ImageType to new Enums section Also added references to ImageType where needed --- docs/draft/6-payloads.md | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/docs/draft/6-payloads.md b/docs/draft/6-payloads.md index 8223acb3..a01ed09d 100644 --- a/docs/draft/6-payloads.md +++ b/docs/draft/6-payloads.md @@ -39,7 +39,7 @@ as various clients created using different technologies. - [Message types](#message-types) - [Clock vs Timestamp and message ordering](#clock-vs-timestamp-and-message-ordering) - [Chats](#chats) - - [Chat Message Identity](#chat-message-identity) + - [Chat Identity](#chat-identity) - [Contact Update](#contact-update) - [Payload](#payload-2) - [Contact update](#contact-update-1) @@ -51,6 +51,8 @@ as various clients created using different technologies. - [PairInstallation](#pairinstallation) - [Payload](#payload-5) - [MembershipUpdateMessage and MembershipUpdateEvent](#membershipupdatemessage-and-membershipupdateevent) + - [Enums](#enums) + - [ImageType](#imagetype) - [Upgradability](#upgradability) - [Security Considerations](#security-considerations) - [Changelog](#changelog) @@ -187,7 +189,7 @@ message StickerMessage { ##### Image content type A `ChatMessage` with `IMAGE` `Content/Type` MUST also specify the `payload` of the image -and the `type`. +and the `type`. Also see [ImageType](#imagetype) Clients MUST sanitize the payload before accessing its content, in particular: - Clients MUST choose a secure decoder @@ -306,7 +308,7 @@ The main components of the `ProfileImage` are: | ----- | ------------- | ------------------ | --- | | 1 | `payload` | `bytes` | A context based payload for the profile image data. Context is determined by the `source_type` | | 2 | `source_type` | `SourceType` | Enum, signals the image payload source | -| 3 | `image_type` | `enums.ImageType` | Enum, signals the image type and method of parsing the payload | +| 3 | `image_type` | `enums.ImageType` | Enum, signals the image type and method of parsing the payload. See [ImageType](#imagetype) | #### Payload @@ -537,6 +539,28 @@ message PairInstallation { `MembershipUpdateEvent` is a message used to propagate information about group membership changes in a group chat. The details are in the [Group chats specs](./7-group-chat.md). +## Enums + +### ImageType + +```protobuf +enum ImageType { + UNKNOWN_IMAGE_TYPE = 0; + + // Raster image files is payload data that can be read as a raster image + PNG = 1; + JPEG = 2; + WEBP = 3; + GIF = 4; + + // Vector image files is payload data that can be interpreted as a vector image + SVG = 101; + + // AVATAR is payload data that can be parsed as avatar compilation instructions + AVATAR = 201; +} +``` + ## Upgradability There are two ways to upgrade the protocol without breaking compatibility: From 279fa598bab1532ed77012ce95e28cfac9075f5a Mon Sep 17 00:00:00 2001 From: Samuel Hawksby-Robinson Date: Tue, 29 Sep 2020 15:50:00 +0100 Subject: [PATCH 13/14] Fixed broken link --- docs/draft/6-payloads.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/draft/6-payloads.md b/docs/draft/6-payloads.md index a01ed09d..a2b524ce 100644 --- a/docs/draft/6-payloads.md +++ b/docs/draft/6-payloads.md @@ -144,7 +144,7 @@ message ChatMessage { | 2 | timestamp | `uint64` | The sender timestamp at message creation | | 3 | text | `string` | The content of the message | | 4 | response_to | `string` | The ID of the message replied to | -| 5 | ens_name | `string` | DEPRECATED - [See Chat Message Identity](#chat-message-identity). The ENS name of the user sending the message | +| 5 | ens_name | `string` | DEPRECATED - [See Chat Identity](#chat-identity). The ENS name of the user sending the message | | 6 | chat_id | `string` | The local ID of the chat the message is sent to | | 7 | message_type | `MessageType` | The type of message, different for one-to-one, public or group chats | | 8 | content_type | `ContentType` | The type of the content of the message | From d222ea75b8c4a462ec1edf6e64546f9c8f194de7 Mon Sep 17 00:00:00 2001 From: Samuel Hawksby-Robinson Date: Tue, 29 Sep 2020 15:57:55 +0100 Subject: [PATCH 14/14] Updated wordlist --- wordlist.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/wordlist.txt b/wordlist.txt index b7408568..9cbd998f 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -32,7 +32,6 @@ chatID chatid ChatIdentity ChatMessage -ChatMessageIdentity contactCode contactcode ContactCodeAdvertisement @@ -87,6 +86,7 @@ EncodeToString enode enr enum +Enums exif ERC ErrorType @@ -193,6 +193,7 @@ pin Pinzaru plaintext Pluggable +PNG Pombeiro PoW pre @@ -255,6 +256,7 @@ suboptimal subprotocol subprotocols SuggestGasPrice +SVG SyncInstallationContact SyncInstallationPublicChat TCP @@ -291,6 +293,7 @@ Waku Waku's waku wakuext +WEBP webview Webview wei