Room Version 4

This room version builds on version 3 using a different encoding for event IDs.

Table of Contents

1   Client considerations

This room version changes the format form event IDs sent to clients. Clients should already be treating event IDs as opaque identifiers, and should not be concerned with the format of them. Clients should still encode the event ID when including it in a request path.

Clients should expect to see event IDs changed from the format of $randomstring:example.org to something like $Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg (note the lack of domain).

2   Server implementation components

Warning

The information contained in this section is strictly for server implementors. Applications which use the Client-Server API are generally unaffected by the intricacies contained here. The section above regarding client considerations is the resource that Client-Server API use cases should reference.

Room version 4 uses the same algorithms defined in room version 3, however using URL-safe base64 to generate the event ID.

2.1   Event IDs

Rationale

Room version 3 generated event IDs that were difficult for client implementations which were not encoding the event ID to function in those rooms. It additionally raised concern due to the / character being interpretted differently by some reverse proxy software, and generally made administration harder.

The event ID is the reference hash of the event encoded using a variation of Unpadded Base64 which replaces the 62nd and 63rd characters with - and _ instead of using + and /. This matches RFC4648's definition of URL-safe base64. Event IDs are still prefixed with $ and may result in looking like $Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg.

Just like in room version 3, event IDs should not be sent over federation to servers when the room uses this room version. On the receiving end of an event, the server should compute the relevant event ID for itself. Room version 3 also changes the format of auth_events and prev_events in a PDU.

2.1.1   Persistent Data Unit schema

A persistent data unit (event) for room version 4 and beyond.

Persistent Data Unit

Parameter Type Description
room_id string Required. Room identifier.
sender string Required. The ID of the user sending the event.
origin string Required. The server_name of the homeserver that created this event.
origin_server_ts integer Required. Timestamp in milliseconds on origin homeserver when this event was created.
type string Required. Event type
state_key string If this key is present, the event is a state event, and it will replace previous events with the same type and state_key in the room state.
content object Required. The content of the event.
prev_events [string]

Required. Event IDs for the most recent events in the room that the homeserver was aware of when it made this event.

Must contain less than or equal to 20 events.
depth integer Required. The maximum depth of the prev_events, plus one. Must be less than the maximum value for an integer (2^63 - 1). If the room's depth is already at the limit, the depth must be set to the limit.
auth_events [string]

Required. Event IDs for the authorization events that would allow this event to be in the room.

Must contain less than or equal to 10 events. Note that if the relevant auth event selection rules are used, this restriction should never be encountered.
redacts string For redaction events, the ID of the event being redacted.
unsigned UnsignedData Additional data added by the origin server but not covered by the signatures. More keys than those defined here may be used.
hashes Event Hash Required. Content hashes of the PDU, following the algorithm specified in Signing Events.
signatures {string: Server Signatures} Required. Signatures for the PDU, following the algorithm specified in Signing Events.

UnsignedData

Parameter Type Description
age integer The number of milliseconds that have passed since this message was sent.
replaces_state string The event ID of the state event this event replaces.
prev_sender string The sender of the replaced state event.
prev_content object The content of the replaced state event.
redacted_because string A reason for why the event was redacted.

Event Hash

Parameter Type Description
sha256 string Required. The hash.

Example:

{
    "auth_events": [
        "$URLsafe-base64EncodedHash",
        "$Another_Event"
    ],
    "content": {
        "key": "value"
    },
    "depth": 12,
    "hashes": {
        "sha256": "ThisHashCoversAllFieldsInCaseThisIsRedacted"
    },
    "origin": "matrix.org",
    "origin_server_ts": 1234567890,
    "prev_events": [
        "$URLsafe-base64EncodedHash",
        "$Another_Event"
    ],
    "redacts": "$def_456-oldevent",
    "room_id": "!abc123:matrix.org",
    "sender": "@someone:matrix.org",
    "signatures": {
        "example.com": {
            "ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
        }
    },
    "state_key": "my_key",
    "type": "m.room.message",
    "unsigned": {
        "key": "value"
    }
}