matrix-spec-proposals/content/rooms/v3.md

title	type	weight
Room Version 3	docs	30

This room version builds on version 2 with an improved event format.

Client considerations

This room version changes the format for event IDs sent to clients. Clients should be aware that these event IDs may contain slashes and other potentially problematic characters. Clients should be treating event IDs as opaque identifiers and should not be attempting to parse them into a usable form, just like with other room versions.

Clients should expect to see event IDs changed from the format of $randomstring:example.org to something like $acR1l0raoZnm60CBwAVgqbZqoO/mYU81xysh1u7XcJk (note the lack of domain and the potentially problematic slash).

Though unchanged in this room version, clients which implement the redaction algorithm locally should refer to the redactions section below for a full overview.

Server implementation components

{{% boxes/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. {{% /boxes/warning %}}

Room version 3 uses the event format described here in addition to all the remaining behaviour described by room version 2.

Handling redactions

{{% rver-fragment name="v3-handling-redactions" withVersioning=true %}}

Event IDs

{{% boxes/rationale %}} In other room versions (namely version 1 and 2) the event ID is a distinct field from the remainder of the event, which must be tracked as such. This leads to complications where servers receive multiple events with the same ID in either the same or different rooms where the server cannot easily keep track of which event it should be using. By removing the use of a dedicated event ID, servers are required to track the hashes on an event to determine its ID. {{% /boxes/rationale %}}

{{% added-in this=true %}} The event ID is the reference hash of the event encoded using Unpadded Base64, prefixed with $. A resulting event ID using this approach should look similar to $CD66HAED5npg6074c6pDtLKalHjVfYb2q4Q3LZgrW6o.

Event format

When events are sent over federation, the event_id field is no longer included. A server receiving an event should compute the relevant event ID for itself.

Additionally, the format of the auth_events and prev_events fields are changed: instead of lists of (event_id, hash) pairs, they are now plain lists of event IDs.

These changes to the format of an event mean that servers must be aware of the version of the room containing an incoming event, so that the event can be correctly parsed and handled. This is facilitated via changes to the server-server API (such as the inclusion of room_version in the response to GET /_matrix/federation/v1/make_join/{roomId}/{userId}.)

The complete structure of a event in a v3 room is shown below.

{{% definition path="api/server-server/definitions/pdu_v3" %}}

Authorization rules

{{% added-in this=true %}} m.room.redaction events are no longer explicitly part of the auth rules. They are still subject to the minimum power level rules, but should always fall into "11. Otherwise, allow". Instead of being authorized at the time of receipt, they are authorized at a later stage: see the Handling Redactions section below for more information.

{{% rver-fragment name="v3-auth-rules" withVersioning=true %}}

Unchanged from v2

The following sections have not been modified since v2, but are included for completeness.

Redactions

{{% rver-fragment name="v1-redactions" %}}

State resolution

{{% rver-fragment name="v2-state-res" %}}

Canonical JSON

{{% rver-fragment name="v1-canonical-json" %}}