improve event format description of m.room.encrypted events (#2413)

Signed-off-by: Johanna Stuber <johannas@element.io>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

changelogs/client_server/newsfragments/2413.clarification

@@ -0,0 +1 @@
+Improve the format description of `m.room.encrypted` (Olm/Megolm) events.

content/client-server-api/modules/end_to_end_encryption.md

@@ -1723,28 +1723,30 @@ Devices that support Olm must include "m.olm.v1.curve25519-aes-sha2" in
 their list of supported messaging algorithms, must list a Curve25519
 device key, and must publish Curve25519 one-time keys.
 
-An event encrypted using Olm has the following format:
+The content of an [`m.room.encrypted`](#mroomencrypted) event using Olm has the following format:
 
 ```json
 {
-  "type": "m.room.encrypted",
   "content": {
     "algorithm": "m.olm.v1.curve25519-aes-sha2",
     "sender_key": "<sender_curve25519_key>",
     "ciphertext": {
       "<device_curve25519_key>": {
         "type": 0,
-        "body": "<encrypted_payload_base_64>"
+        "body": "<base64_encoded_olm_message>"
       }
     }
   }
 }
 ```
-
+Note that when the event is received from the server, it will have a `type`
-`ciphertext` is a mapping from device Curve25519 key to an encrypted
+(with a value of `m.room.encrypted`) and `sender` property alongside the
-payload for that device. `body` is a Base64-encoded [Olm message body](/olm-megolm/olm/#the-olm-message-format).
+`content` property. In `content`, `ciphertext` is a mapping from a device
-`type` is an integer indicating the type of the message body: 0 for the
+Curve25519 key to an object with a `type` and a `body`. Here, `body` is a
-initial [pre-key message](/olm-megolm/olm/#pre-key-messages), 1 for [normal messages](/olm-megolm/olm/#normal-messages).
+Base64-encoded [Olm message](/olm-megolm/olm/#the-olm-message-format), and
+`type` is an integer indicating the type of the message:
+0 for the initial [pre-key messages](/olm-megolm/olm/#pre-key-messages),
+1 for [normal messages](/olm-megolm/olm/#normal-messages).
 
 Olm sessions will generate messages with a type of 0 until they receive
 a message. Once a session has decrypted a message it will produce
@@ -1893,23 +1895,26 @@ This uses:
 Devices that support Megolm must support Olm, and include
 "m.megolm.v1.aes-sha2" in their list of supported messaging algorithms.
 
-An event encrypted using Megolm has the following format:
+The content of an [`m.room.encrypted`](#mroomencrypted) event using Megolm has the following format:
 
 ```json
 {
-  "type": "m.room.encrypted",
   "content": {
     "algorithm": "m.megolm.v1.aes-sha2",
     "sender_key": "<sender_curve25519_key>",
     "device_id": "<sender_device_id>",
     "session_id": "<outbound_group_session_id>",
-    "ciphertext": "<encrypted_payload_base_64>"
+    "ciphertext": "<base64_encoded_megolm_message>"
   }
 }
 ```
+Note that when the event is received from the server, it will have additional
+properties alongside the `content` property, including a `type` (with a value
+of `m.room.encrypted`) and a `sender` property. (See [Room event format](#room-event-format).)
 
-The encrypted payload can contain any message event. The plaintext is of
+Within `content`, `ciphertext`
-the form:
+is a Base64-encoded [Megolm message](/olm-megolm/megolm/#message-format),
+whose plaintext body is of the form:
 
 ```json
 {
@@ -1919,7 +1924,7 @@ the form:
 }
 ```
 
-We include the room ID in the payload, because otherwise the homeserver
+We include the room ID in the encrypted message, because otherwise the homeserver
 would be able to change the room a message was sent in.
 
 Clients must guard against replay attacks by keeping track of the

content/client-server-api/modules/event_replacements.md

@@ -91,13 +91,13 @@ For example, a replacement for an encrypted event might look like this:
         "sender_key": "<sender_curve25519_key>",
         "device_id": "<sender_device_id>",
         "session_id": "<outbound_group_session_id>",
-        "ciphertext": "<encrypted_payload_base_64>"
+        "ciphertext": "<base64_encoded_megolm_message>"
     }
     // irrelevant fields not shown
 }
 ```
 
-... and, once decrypted, the payload might look like this:
+... and the plaintext body of the Megolm message might look like this:
 
 ```json
 {