Linearized Matrix

3.2.1. Room Versions

TODO: We should consider naming this something else.¶

Each room declares which room version it's using, and each room version (identified by a single string) describes the specific algorithms a server needs to follow in order to particpate in rooms with that version. Room versions are immutable once specified, as otherwise a change in algorithms could cause a split-brain between servers participating in affected rooms.¶

Room versions prefixed with I. MUST only be used within the IETF specification process. Room versions consisting solely of 0-9 and . MUST only be used by the Matrix protocol.¶

This document as a whole describes I.1 as a room version.¶

Servers MUST implement support for I.1 at a minimum. Servers SHOULD use I.1 when creating new rooms.¶

Implementation note: Currently I.1 is not a real thing. Use org.matrix.i-d.ralston-mimi-linearized-matrix.02 when testing against other Linearized Matrix implementations. This string may be updated later to account for breaking changes.¶

Implementation note: org.matrix.i-d.ralston-mimi-linearized-matrix.00 also exists in the wild, defining a set of algorithms which exist in a prior version of this document (00 and 01).¶

TODO: Remove implementation notes.¶

There is no implicit ordering or hierarchy to room versions. Future room versions, such as an I.2, can choose to build upon I.1's algorithms or start completely from scratch if they prefer.¶

A room version has the following algorithms defined:¶

• Event authorization - Rules which govern when events are accepted, rejected, or soft-failed by a server. For I.1, this is Section 5.2.¶
• Redaction - Description of which fields to keep on an event during redaction. Redaction is used by the signing and hash algorithms, meaning they need to be consistent across implementations. For I.1, this is Section 8.¶
• Event format - Which fields are expected to be present on an event, and the schema for each. For I.1, this is Section 3.5.¶
• Canonical JSON - Specific details about how to canonicalize an event as JSON. This is used by the signing algorithm and must be consistent between implementations. For I.1, this is Section 7.¶
• Hub selection - Rules around picking the hub server and transferring to a new hub. For I.1, this is Section 11.¶
• Identifier grammar - All identifiers (room IDs, user IDs, event IDs, etc) can change grammar within a room version. As such, they SHOULD generally be treated as opaque as possible over a transport. For I.1, these details are described in Section 3.1, Section 3.2, Section 3.3, Section 3.4, and Section 3.5.¶

The transport between servers is decoupled from the algorithms above. For example, events are treated as blobs with no specific format over the wire but have strict schema in the context of a room or room version. Endpoints MUST be designed with this distinction in mind.¶

Each room version has a "stable" or "unstable" designation. Stable room versions SHOULD be used in production by messaging providers. Unstable room versions might contain bugs or are not yet fully specified and SHOULD NOT be used in production by messaging providers.¶

I.1 shall be considered "stable".¶

Implementation note: org.matrix.i-d.ralston-mimi-linearized-matrix.02 is considered "unstable".¶

TODO: Remove implementation notes.¶

TODO: Matrix considers a version as stable once accepted through FCP. When would be the process equivalent for the IETF?¶

The ABNF [RFC5234] grammar for a room version is:¶

room_version = 1*128room_version_char
room_version_char = DIGIT
                  / %x61-7A         ; a-z
                  / "-" / "."

Examples:¶

• 1¶
• I.1¶
• org.example.my-room-version¶

Room versions not formally specified SHOULD be prefixed using reverse domain name notation, creating a sort of namespace. org.example.my-room-version is an example of this.¶

3.5.1. Linearized PDU

All events generated by participant servers are routed through the hub, but the participant servers themselves are unable to populate fields like prev_events because they can't guarantee order and those fields contribute to the event ID, signatures, and overall validity. To fix this, participant servers send the hub server a "Linearized PDU" or "LPDU" which does not include the fields they cannot set while still ensuring integrity of the event contents themselves.¶

The participant server MUST NOT populate the following fields on events (LPDUs) they are sending to the hub:¶

• auth_events - the participant cannot reliably determine what allows it to send the event.¶
• prev_events - the participant cannot reliably know what event precedes theirs.¶
• hashes (except hashes.lpdu) - top-level hashes cover the above two fields.¶

The participant server MUST populate the hashes.lpdu object, covering a content hash (Section 9.1) of the partial event, giving authenticity to the sender's contents. The participant server additionally signs this partial event before sending it to the hub.¶

The participant server will receive an echo of the fully-formed event from the hub once appended to the room.¶

3.5.2. State Events

State events track metadata for the room, such as name, topic, and members. State is keyed by a tuple of type and state_key. The state "at" an event is the set of state events which have the most recent (in terms of event ordering, not timestamp) state tuple.¶

For example, consider the following (simplified) room history:¶

[
   /* in all events, irrelevant fields are not shown for brevity */

   /* 0 */ {
      "type": "m.room.create", "state_key": ""
   },

   /* 1 */ {
      "type": "m.room.member", "state_key": "@alice:example.org"
   },

   /* 2 */ {
      "type": "m.room.encrypted"
   },

   /* 3 */ {
      "type": "m.room.member", "state_key": "@bob:example.org"
   },

   /* 4 */ {
      "type": "m.room.member", "state_key": "@alice:example.org"
   }
]

The state at index 2 consists of Alice's m.room.member event (Section 3.5.3.3) and the m.room.create event (Section 3.5.3.1) from the room. The m.room.encrypted event itself is not a state event and therefore does not get appended to the state "at" any particular event.¶

The state at index 4 would have Alice's new m.room.member event, Bob's m.room.member event, and the m.room.create event from before. Alice's old membership event is overridden due to having the same type and state_key as the previous event. Note however that the state at index 3 still contains the older membership event, as the new event happens later with respect to event ordering.¶

"Current state" is the state at the most recent event in the room. Calculating the state at a given event is needed for the authorization rules (Section 5.2) and event visibility (Section 3.5.3.5.1) algorithms. Clients additionally need to know current state to show accurate room names, topics, avatars, etc.¶

{
   "type": "m.room.create",
   "sender": "@alice:example.org",
   "state_key": "",
   "content": {
      "room_version": "I.1"
   }
}

3.5.3. Event Types

Linearized Matrix defines the following event types. The section headers are the event type.¶

4.5.1. m.mls.commit

Represents an MLS commit, which may be rejected by the hub server.¶

content for the event MUST contain at least the following example:¶

{
   "message": "<unpadded base64 encoded PublicMessage>",
   "public_group_state": "<unpadded base64 encoded public group state>"
}

As mentioned, message is a PublicMessage from MLS. public_group_state is to enable external joins.¶

An optional field, prev_commit_event_id, SHOULD be specified when a parent commit exists. This is to enable clients to find the commit they have keys for upon joining the room, as the most recent one may not be decryptable to them. The client can then work forwards from where they can decrypt the message.¶

TODO: Should we use the RatchetTree extension? It might make the group state massive...¶

TODO: Which fields from this need to be protected by Section 8?¶

4.5.2. m.room.encrypted

Represents an encrypted MLS application message. The sender first encrypts the message per the content format then MUST send an event with content matching:¶

{
   "algorithm": "m.mls.v1.[ciphersuite]",
   "ciphertext": "<unpadded base64 encoded MLS ciphertext>",
   "commit_event_id": "<event ID of applicable m.mls.commit event>"
}

Within this document, algorithm will be m.mls.v1.dhkemx25519-aes128gcm-sha256-ed25519. The other fields are as described in the example.¶

Clients SHOULD treat m.room.encrypted events which are improperly structured as undecryptable events.¶

TODO: Which fields from this need to be protected by Section 8?¶

5.2.1. Auth Events Selection

The auth_events on an event MUST consist of the following state events, with the exception of an m.room.create event which has no auth_events.¶

1. The m.room.create state event.¶
2. The current m.room.power_levels state event, if any.¶
3. The sender's current m.room.member state event, if any.¶

4. If the type is m.room.member:¶

   1. The target's (state_key) current m.room.member state event, if any.¶
   2. If content.membership is join or invite, the current m.room.join_rules state event, if any.¶

TODO: Talk about restricted room joins here?¶

5.2.2. Calculating Power Levels

A requirement of the authorization rules is being able to determine the current/future "power level" for a user. All power levels are calculated with reference to the content of an m.room.power_levels state event (Section 3.5.3.4).¶

To calculate a user's current power level:¶

1. If users is present, use the power level for the user ID, if present.¶
2. If users is not present, or the user ID is not present in users, use users_default.¶
3. If users_default is not present, use 0.¶

To calculate the required power level to do an action:¶

1. If the action (kick, ban, invite, or redact) is present, use that power level.¶
2. If not present, use the default for the action (50 for kick, ban, and redact, 0 for invite).¶

To calculate the required power level to send an event:¶

1. If events is present, use the power level for the event type, if present.¶

2. If events is not present, or the event type is not present in events:¶

   1. If state_key is present (including empty), use state_default.¶

      1. If state_default is not specified, use 50.¶

   2. If state_key is not present, use events_default.¶

      1. If events_default is not specified, use 0.¶

5.2.3. Auth Rules Algorithm

With consideration for default/calculated power levels (Section 5.2.2), each event MUST pass the following rules. "Current state" (and "current membership", etc) are the state of the room before the event being checked is applied.¶

TODO: should we reference m.federate?¶

1. Events must be signed (Section 6.3) by the server denoted by the sender field. Note that this may be an LPDU if the hub_server is specified and not the same server. If the event is improperly signed, reject the event.¶
2. If hub_server is present on the event, the event must be signed (Section 6.3) by that server. If it is improperly signed, reject the event.¶

3. If the event's type is m.room.create:¶

   1. If it has any prev_events, reject the event.¶
   2. If the domain of the room_id is not the same domain as the sender, reject the event.¶
   3. If content.room_version is not I.1, reject the event.¶
   4. Otherwise, allow the event.¶

4. Considering the event's auth_events:¶

   TODO: Does this check make sense for Linearized Matrix? We already removed what was #3 because it talked about rejecting events which reference rejected events.¶

   1. If there are duplicate entries for a given type and state_key pair, reject the event.¶
   2. If there are entries whose type and state_key do not match those specified by the auth events selection algorithm (Section 5.2.1), reject the event.¶
   3. If there is no m.room.create event among the entries, reject.¶

5. If the event's type is m.room.member:¶

   1. If there is no state_key property, or no membership in content, reject the event.¶

   2. If the event content's membership field is join:¶

      1. If the previous event is an m.room.create event and the state_key is the creator, allow the event.¶
      2. If sender does not match state_key, reject the event.¶
      3. If the sender is banned, reject the event.¶
      4. If the join_rule for m.room.join_rules is invite or knock, then allow the event if the current membership state is invite or join.¶
      5. If the join_rule for m.room.join_rules is public, allow the event.¶
      6. Otherwise, reject the event.¶

   3. If the event content's membership field is invite:¶

      1. If the sender's current membership state is not join, reject the event.¶
      2. If the target user's (state_key) membership is join or ban, reject the event.¶
      3. If the sender's power level is greater than or equal to the power level needed to send invites, allow the event.¶
      4. Otherwise, reject the event.¶

   4. If the event content's membership field is leave:¶

      1. If the sender matches the state_key, allow the event if and only if that user's current membership state is knock, join, or invite.¶
      2. If the sender's current membership state is not join, reject the event.¶
      3. If the target user's (state_key) current membership state is ban, and the sender's power level is less than the power level needed to ban other users, reject the event.¶
      4. If the sender's power level is greater than or equal to the power level needed to kick users, and the target user's (state_key) power level is less than the sender's, allow the event.¶
      5. Otherwise, reject the event.¶

   5. If the event content's membership field is ban:¶

      1. If the sender's current membership state is not join, reject the event.¶
      2. If the sender's power level is greater than or equal to the power level needed to ban users, and the target user's (state_key) power level is less than the sender's power level, allow the event.¶
      3. Otherwise, reject the event.¶

   6. If the event content's membership field is knock:¶

      1. If the join_rule for m.room.join_rules is anything other than knock, reject the event.¶
      2. If the sender does not match the state_key, reject the event.¶
      3. If the sender's current membership state is not ban or join, allow the event.¶
      4. Otherwise, reject the event.¶
   7. Otherwise, the membership is unknown. reject the event.¶
6. If the sender's current membership state is not join, reject the event.¶
7. If the event type's required power level to send it is greater than the sender's power level, reject the event.¶

8. If the event has a state_key which starts with an @ and does not match the sender, reject the event.¶

   TODO: Do we care? This is theoretically to allow for owned state events, but in practice nothing which uses this concept makes it this far into the auth rules (membership events are validated above).¶

9. If the event's type is m.room.power_levels:¶

   1. If any of the fields users_default, events_default, state_default, ban, redact, kick, or invite in content are present and not an integer, reject the event.¶
   2. If events in content is present and not an object with values that are integers, reject the event.¶
   3. If the users in content is present and not an object with valid user IDs as keys and integers as values, reject the event.¶
   4. If there is no previous m.room.power_levels event in the room, allow the event.¶

   5. For the fields users_default, events_default, state_default, ban, redact, kick, and invite, check if they were added, changed, or removed. For each found alteration:¶

      1. If the current value is higher than the sender's current power level, reject the event.¶
      2. If the new value is higher than the sender's current power level, reject the event.¶

   6. For each entry being changed in or removed from events:¶

      1. If the current value is higher than the sender's current power level, reject the event.¶

   7. For each entry being added to or changed in events:¶

      1. If the new value is greater than the sender's current power level, reject the event.¶

   8. For each entry being changed in or removed from users, other than the sender's own entry:¶

      1. If the current value is higher than the sender's current power level, reject the event.¶

   9. For each entry being added to or changed in users:¶

      1. If the new value is greater than the sender's current power level, reject the event.¶
   10. Otherwise, allow the event.¶
10. Otherwise, allow the event.¶

There are some consequences to these rules:¶

• Unless you are already a member of the room, the only permitted operations (aside from the initial create/join) are being able to join public rooms, accept invites to rooms, and reject invites to rooms.¶
• To unban another user, the sender must have a power level greater than or equal to both the kick and ban power levels, and greater than the target user's power level.¶

TODO: If we want to enforce a single hub in a room, we'd do so here with auth rules.¶

12.2.1. Requests and Responses

All HTTP POST and PUT endpoints require the sending server to supply a (potentially empty) JSON object as the request body. Requesting servers SHOULD supply a Content-Type header of application/json for such requests.¶

All endpoints which require a server to respond with a JSON object MUST include a Content-Type header of application/json.¶

All JSON data, in requests or responses, MUST be encoded using UTF-8 [RFC3629].¶

All endpoints in this document do not support trailing slashes on them. When such a request is encountered, it MUST be handled as an unknown endpoint (Section 12.2.3). Examples include:¶

• https://example.org/_matrix/path - valid.¶
• https://example.org/_matrix/path/ - unknown/invalid.¶
• https://example.org//_matrix/path - unknown/invalid (domain also can't have a trailing slash).¶
• https://example.org//_matrix/path/ - doubly unknown/invalid.¶

Servers (both hub and participants) MUST implement all endpoints unless otherwise specified.¶

Most endpoints have a version number as part of the path. This version number is that endpoint's version, allowing for breaking changes to be made to the schema of that endpoint. For clarity, the version number is not representative of an API version.¶

12.2.2. Errors

All errors are represented by an error code defined by this document and an accompanied HTTP status code. It is possible for a HTTP status code to map to multiple error codes, and it's possible for an error code to map to multiple HTTP status codes.¶

When a server is returning an error to a caller, it MUST use the most appropriate error response defined by the endpoint. If no appropriate error response is specified, the server SHOULD use M_UNKNOWN as the error code and 500 Internal Server Error as the HTTP status code.¶

Errors are represented as JSON objects, requiring a Content-Type: application/json response header:¶

{
  "errcode": "M_UNKNOWN",
  "error": "Something went wrong."
}

errcode is required and denotes the error code. error is an optional human-readable description of the error. error can be as precise or vague as the responding server desires - the strings in this document are suggestions.¶

Some common error codes are:¶

• M_UNKNOWN - An unknown error has occurred.¶
• M_FORBIDDEN - The caller is not permitted to access the resource. For example, trying to join a room the user does not have an invite for.¶
• M_NOT_JSON - The request did not contain valid JSON. Must be accompanied by a 400 Bad Request HTTP status code.¶
• M_BAD_JSON - The request did contain valid JSON, but it was missing required keys or was malformed in another way. Must be accompanied by a 400 Bad Request HTTP status code.¶
• M_LIMIT_EXCEEDED - Too many requests have been sent. The caller should wait before trying the request again.¶
• M_TOO_LARGE - The request was too large for the receiver to handle.¶

12.2.3. Unsupported Endpoints

If a server receives a request for an unsupported or otherwise unknown endpoint, the server MUST respond with an HTTP 404 Not Found status code and M_UNRECOGNIZED error code. If the request was for a known endpoint, but wrong HTTP method, a 405 Method Not Allowed HTTP status code and M_UNRECOGNIZED error code (Section 12.2.2).¶

12.2.4. Malformed Requests

If a server is expecting JSON in the request body but receives something else, it MUST respond with an HTTP status code of 400 Bad Request and error code M_NOT_JSON (Section 12.2.2). If the request contains JSON, and is for a known endpoint, but otherwise missing required keys or is malformed, the server MUST respond with an HTTP status code of 400 Bad Request and error code M_BAD_JSON (Section 12.2.2). Where possible, error for M_BAD_JSON should describe the missing keys or other parsing error.¶

12.2.5. Transaction Identifiers

Where endpoints use HTTP PUT, it is typical for a "transaction ID" to be specified in the path parameters. This transaction ID MUST ONLY be used for making requests idempotent - if a server receives two (or more) requests with the same transaction ID, it MUST return the same response for each and only process the request body once. It is assumed that requests using the same transaction ID also contain the same request body between calls.¶

A transaction ID only needs to be unique per-endpoint and per-sending server. A server's transaction IDs do not affect requests made by other servers or made to other endpoints by the same server.¶

12.2.6. Rate Limiting

Servers SHOULD implement rate limiting semantics to reduce the risk of being overloaded. Endpoints which support being rate limited are annotated in this document.¶

If a rate limit is encountered, the server MUST respond with an HTTP 429 Too Many Requests status code and M_LIMIT_EXCEEDED error code (Section 12.2.2). If applicable, the server should additionally include a retry_after_ms integer field on the error response to denote how long the caller should wait before retrying, in milliseconds.¶

{
  "errcode": "M_LIMIT_EXCEEDED",
  "error": "Too many requests. Try again later.",
  "retry_after_ms": 10254
}

The exact rate limit mechanics are left as an implementation detail. A potential approach may be to prevent repeated requests for the same resource at a high rate and ensuring a remote server does not request more than a defined number of resources at a time.¶

12.3.1. GET /.well-known/matrix/server

Used by the server name resolution approach to determine a delegated hostname for a given server. 30x HTTP redirection MUST be followed, though loops SHOULD be avoided. Normal X.509 certificate validation is applied to this endpoint (not the specific validation required by the server name resolution steps) [RFC5280].¶

This endpoint MAY be implemented by servers (it is optional).¶

Rate-limited: No.¶

Authentication required: No.¶

This HTTP endpoint does not specify any request parameters or body.¶

200 OK response:¶

{
   "m.server": "delegated.example.org:8448"
}

m.server is a required response field. Responses SHOULD have a Content-Type HTTP header of application/json, however servers parsing the response should assume that the body is JSON regardless of Content-Type header. Failures in parsing the JSON or otherwise invalid data that prevents parsing MUST NOT result in discovery failure. Instead, the caller is expected to move on to the next step of the name resolution approach.¶

Cache control headers SHOULD be respected on a 200 OK response. Callers SHOULD impose a maximum cache time of 48 hours, regardless of cache control headers. A default of 24 hours SHOULD be used when no cache control headers are present.¶

Error responses (non-200) SHOULD be cached for no longer than 1 hour. Callers SHOULD exponentially back off (to a defined limit) upon receiving repeated error responses.¶

12.4.1. Retrieving Server Keys

TODO: Explain what notaries are and what they do, if we keep this section at all.¶

A server's signing keys are published under /_matrix/key/v2/server (Section 12.4.1.2) and can be queried through notary servers in two ways: Section 12.4.1.3 and Section 12.4.1.4. Notary servers implicitly call /_matrix/key/v2/server when queried, signing and caching the response for some time. This allows the target server to offline without affecting their previously sent events.¶

The approach used here is borrowed from the Perspectives Project [PerspectivesProject], modified to cover the server's ed25519 keys and to use JSON instead of XML. The advantage of this system is it allows each server to pick which notaries it trusts, and can contact multiple notaries to corroborate the keys returned by any given notary.¶

Servers SHOULD attempt to contact the target server directly before using a notary server.¶

Note that these endpoints operate outside the context of a room: a server does not need to participate in any shared rooms to be used as a notary by another server, and does not need to use the hub as a notary.¶

{
   "server_name": "example.org",
   "valid_until_ts": 1686776437176,
   "m.linearized": true,
   "verify_keys": {
      "ed25519:0": {
         "key": "<unpadded base64 encoded public key>"
      }
   },
   "old_verify_keys": {
      "ed25519:bad": {
         "expired_ts": 1586776437176,
         "key": "<unpadded base64 encoded public key>"
      }
   },
   "signatures": {
      "example.org": {
         "ed25519:0": "<unpadded base64 encoded signature>"
      }
   }
}

{
   "server_keys": [
      {/* server key */}
   ]
}

{
   "server_keys": {
      "example.org": {
         "ed25519:0": {
            "minimum_valid_until_ts": 1686783382189
         }
      }
   }
}

12.5.1. PUT /_matrix/federation/v2/send/:txnId

Sends (L)PDUs (Section 3.5, Section 3.5.1) to another server. The sending server MUST wait for a 200 OK response from the receiver before sending another request with a different :txnId.¶

Implementation note: Currently this endpoint doesn't actually exist. Use PUT /_matrix/federation/unstable/org.matrix.i-d.ralston-mimi-linearized-matrix.02/send/:txnId when testing against other Linearized Matrix implementations. This string may be updated later to account for breaking changes.¶

TODO: Remove implementation notes.¶

Rate-limited: No.¶

Authentication required: Yes.¶

Path parameters:¶

• :txnId - the transaction ID (Section 12.2.5) for the request.¶

Query parameters: None applicable.¶

Request body:¶

{
   "edus": [
      {/* EDU */}
   ],
   "pdus": [
      {/* Either an LPDU or PDU */}
   ]
}

edus are the Ephemeral Data Units (Section 12.9) to send. If no EDUs are being sent, this field MAY be excluded from the request body. There MUST NOT be more than 100 entries in edus.¶

pdus are the events/PDUs (Section 3.5) and LPDUs (Section 3.5.1) to send to the server. Whether it's an LPDU or PDU depends on the sending server's role in that room: if they are a non-hub server, it will be an LPDU. There MUST NOT be more than 50 entries in pdus.¶

Each event in the pdus array gets processed as such:¶

1. Identify the room ID for the event. The exact format of the event can differ between room versions, however currently this would be done by extracting the room_id property.¶

   1. If that room ID is invalid/not found, the event is rejected.¶
   2. If the server is not participating in the room, the event is dropped/skipped.¶
2. If the event is an LPDU and the receiving server is the hub, the additional PDU fields are appended before continuing.¶
3. If the event is an LPDU and the receiving server is not the hub, the event is dropped/skipped.¶
4. The checks defined by Section 5.1 are performed.¶
5. If the event still hasn't been dropped/rejected, it is appended to the room. For participant servers, this may mean it's queued for sending to local clients.¶

Server implementation authors should note that these steps can be condensed, but are expanded here for specification purposes. For example, an LPDU's signature can/will fail without ever needing to append the PDU fields first - the server can skip some extra work this way.¶

200 OK response:¶

{
   "failed_pdus": {
      "$eventid": {
         "error": "Invalid event format"
      },
      "$eventid": {
         "error":
            "@alice:example.org cannot send m.room.power_levels"
      }
   }
}

The receiving server MUST NOT send a 200 OK response until all events have been processed. Servers SHOULD NOT block responding to this endpoint on sending accepted events to local clients or other participant servers, as doing so could lead to a lengthy backlog of events waiting to be sent.¶

Sending servers SHOULD apply/expect a timeout and retry the exact same request with the same transaction ID until they see a 200 OK response. If the sending server attempts to send a different transaction ID from the one already in flight, the receiving server MUST respond with a 400 Bad Request HTTP status code and M_BAD_STATE error code (Section 12.2.2). Receiving servers SHOULD continue processing requests to this endpoint event after the sender has disconnected/timed out, but SHOULD NOT process the request multiple times due to the transaction ID (Section 12.2.5).¶

failed_pdus is an object mapping event ID (Section 3.5) to error string. Event IDs are based upon the received object, not the final/complete object. For example, if an LPDU is sent, gets its PDU fields appended, and fails event authorization, then the error would be for the event ID of the LPDU, not the fully-formed PDU. This is to allow the sender to correlate what they sent with errors.¶

The object for each event ID MUST contain an error string field, representing the human-readable reason for an event being rejected.¶

Events which are dropped/ignored or accepted do not appear in failed_pdus.¶

TODO: Should we also return fully-formed PDUs for the LPDUs we received?¶

12.6.1. GET /_matrix/federation/v2/event/:eventId

Retrieves a single event.¶

Implementation note: Currently this endpoint doesn't actually exist. Use GET /_matrix/federation/unstable/org.matrix.i-d.ralston-mimi-linearized-matrix.02/event/:eventId when testing against other Linearized Matrix implementations. This string may be updated later to account for breaking changes.¶

TODO: Remove implementation notes.¶

Rate-limited: Yes.¶

Authentication required: Yes.¶

Path parameters:¶

• :eventId - the event ID (Section 3.5) to retrieve. Note that event IDs are typically reference hashes (Section 9.2) of the event itself, which includes the room ID. This makes event IDs globally unique.¶

Query parameters: None applicable.¶

Request body: None applicable.¶

200 OK response:¶

{
   /* the event */
}

The response body is simply the event (Section 3.5) itself, if the requesting server has reasonable visibility of the event (Section 3.5.3.5.1). When the server can see an event but not the contents, the event is served redacted (Section 8) instead.¶

If the event isn't known to the server, or the requesting server has no reason to know that the event even exists, a 404 Not Found HTTP status code and M_NOT_FOUND error code (Section 12.2.2) is returned.¶

The returned event MUST be checked before being used by the requesting server (Section 5.1). This endpoint MUST NOT return LPDUs (Section 3.5.1), instead treating such events as though they didn't exist.¶

12.6.2. GET /_matrix/federation/v1/state/:roomId

Retrieves a snapshot of the room state (Section 3.5.2) at the given event. This is typically most useful when a participant server prefers to store minimal information about the room, but still needs to offer context to its clients.¶

Rate-limited: Yes.¶

Authentication required: Yes.¶

Path parameters:¶

• :roomId - the room ID (Section 3.2) to retrieve state in.¶

Query parameters:¶

• event_id (string; required) - The event ID (Section 3.5) to retrieve state at.¶

Request body: None applicable.¶

200 OK response:¶

{
   "auth_chain": [
      {/* event */}
   ],
   "pdus": [
      {/* event */}
   ]
}

The returned room state is in two parts: the pdus, consisting of the events which represent "current state" (Section 3.5.2) prior to considering state changes induced by the event in the original request, and auth_chain, consisting of the events which make up the auth_events (Section 5.2.1) for the pdus and the auth_events of those events, recursively.¶

The auth_chain will eventually stop recursing when it reaches the m.room.create event, as it cannot have any auth_events.¶

TODO: Do we actually need to recurse auth events to get the full auth chain here? What are participant servers expected to do with this information? (Do they even care about it?)¶

For example, if the requested event ID was an m.room.power_levels event, the returned state would be as if the new power levels were not applied.¶

Both auth_chain and pdus contain event objects (Section 3.5).¶

If the requesting server does not have reasonable visibility on the room (Section 3.5.3.5.1), or either the room ID or event ID don't exist, a 404 Not Found HTTP status code and M_NOT_FOUND error code (Section 12.2.2) is returned. The same error is returned if the event ID doesn't exist in the requested room ID.¶

Note that the requesting server will generally always have visibility of the auth_chain and pdu events, but may not be able to see their contents. In this case, they are redacted (Section 8) before being served.¶

The returned events MUST be checked before being used by the requesting server (Section 5.1). This endpoint MUST NOT return LPDUs (Section 3.5.1), instead treating such events as though they didn't exist.¶

If the receiving server is not the hub server for the room ID, an HTTP status code of 400 Bad Request and error code M_WRONG_SERVER (Section 12.2.2) is returned.¶

12.6.3. GET /_matrix/federation/v1/state_ids/:roomId

This performs the same function as Section 12.6.2 but returns just the event IDs instead.¶

Rate-limited: Yes.¶

Authentication required: Yes.¶

Path parameters:¶

• :roomId - the room ID (Section 3.2) to retrieve state in.¶

Query parameters:¶

• event_id (string; required) - The event ID (Section 3.5) to retrieve state at.¶

Request body: None applicable.¶

200 OK response:¶

{
   "auth_chain_ids": ["$event1", "$event2"],
   "pdu_ids": ["$event3", "$event4"]
}

See Section 12.6.2 for behaviour. Note that auth_chain becomes auth_chain_ids when using this endpoint, and pdus becomes pdu_ids.¶

12.6.4. GET /_matrix/federation/v2/backfill/:roomId

Retrieves a sliding window history of previous events in a given room.¶

Implementation note: Currently this endpoint doesn't actually exist. Use GET /_matrix/federation/unstable/org.matrix.i-d.ralston-mimi-linearized-matrix.02/backfill/:roomId when testing against other Linearized Matrix implementations. This string may be updated later to account for breaking changes.¶

TODO: Remove implementation notes.¶

Rate-limited: Yes.¶

Authentication required: Yes.¶

Path parameters:¶

• :roomId - the room ID (Section 3.2) to retrieve events from.¶

Query parameters:¶

• v (string; required) - The event ID (Section 3.5) to start backfilling from.¶
• limit (integer; required) - The maximum number of events to return, including v.¶

Request body: None applicable.¶

200 OK response:¶

{
   "pdus": [
      {/* event */}
   ]
}

The number of returned pdus MUST NOT exceed the limit provided by the caller. limit SHOULD have a maximum value imposed by the receiving server. pdus contains the events (Section 3.5) preceeding the requested event ID (v), including v. pdus is ordered from oldest to newest.¶

If the requesting server does not have reasonable visibility on the room (Section 3.5.3.5.1), or either the room ID or event ID don't exist, a 404 Not Found HTTP status code and M_NOT_FOUND error code (Section 12.2.2) is returned. The same error is returned if the event ID doesn't exist in the requested room ID.¶

If the requesting server does have visibility on the returned events, but not their contents, they are redacted (Section 8) before being served.¶

The returned events MUST be checked before being used by the requesting server (Section 5.1). This endpoint MUST NOT return LPDUs (Section 3.5.1), instead treating such events as though they didn't exist.¶

12.7.1. Make and Send Handshake

When a server is already participating in a room, it can use m.room.member (Section 3.5.3.3) events and the /send API (Section 12.5.1) to directly change membership. When the server is not already involved in the room, such as when being invited for the first time, the server needs to "make" an event and "send" it through the hub server to append it to the room.¶

The different processes which use this handshake are:¶

• Rejecting Invites (Section 12.7.2.2)¶
• Joins (Section 12.7.3)¶
• Knocks (Section 12.7.4)¶

The "make" portion of the endpoints take the shape of GET /_matrix/federation/v1/make_CHANGE/:roomId/:userId, where CHANGE is leave, join, or knock (respective to the list above). This endpoint will return a partial LPDU (Section 3.5.1) which needs to be turned into a full LPDU and signed before being sent using POST /_matrix/federation/v3/send_CHANGE/:txnId.¶

The flow for this handshake appears as such:¶

Note that the send_CHANGE step re-checks the event against the auth rules: any amount of time could have passed between the make_CHANGE and send_CHANGE calls.¶

TODO: Describe how the external server is meant to find the hub. Invites work by (usually) trying to contact the server which sent the invite, but knocking is a guess.¶

12.7.2. Invites

When inviting a user belonging to a server already in the room, senders SHOULD use m.room.member (Section 3.5.3.3) events and the /send API (Section 12.5.1). This section's endpoints SHOULD only be used when the target server is not participating in the room already.¶

Note that being invited does not count as the server "participating" in the room. This can mean that while a server has a user with a pending invite in the room, this section's endpoints are needed to send additional invites to other users on the same server.¶

The full invite sequence is:¶

POST /invite is shorthand for Section 12.7.2.1.¶

What causes a user to be considered "ineligible" for an invite is left as an implementation detail. See Section 13 and Section 14 for suggestions on handling user-level privacy controls and spam invites.¶

{
   "event": {/* the event */},
   "invite_room_state": [/* stripped state events */],
   "room_version": "I.1"
}

{
   "pdu": {/* signed fully-formed event */}
}

{
   "event": {/* partial LPDU */},
   "room_version": "I.1"
}

{
   /* LPDU created from make_leave template */
}

{/* deliberately empty object */}

12.7.3. Joins

Joins for users SHOULD be sent directly whenever possible, and otherwise use the "make and send" handshake (Section 12.7.1) approach described here.¶

{
   /* partial LPDU */
}

{
   /* LPDU created from make_join template */
}

{
   "state": [/* events */],
   "auth_chain": [/* events */],
   "event": {/* fully-formed event */}
}

12.7.4. Knocks

To knock on a room is to request an invite to that room. It is not a join, nor is it an invite itself. "Approving" the knock is done by inviting the user, which is typically only allowed by moderators in these rooms. "Denying" the knock is done through kicking (sending a leave membership) or banning the user. If the user is kicked, they may re-send their knock.¶

Senders should note the reason field on m.room.member events (Section 3.5.3.3) to provide context for their knock.¶

To retract a knock, the sending server uses the same APIs as rejecting an invite (Section 12.7.2.2).¶

Where possible, knocks from users SHOULD be sent directly, otherwise using the "make and send" handshake (Section 12.7.1) approach described here.¶

{
   /* partial LPDU */
}

{
   /* LPDU created from make_knock template */
}

{
   "stripped_state": [
      /* stripped state events */
   ]
}

12.10.1. Device Info Publishing

When a user creates a new encryption-capable device, or removes one, a "device list update" is sent to all servers the user shares a room with. The receiving servers then determine which local clients need to be made aware of the device list change and sends the information to them. This is primarily used by this document's MLS implementation (Section 4) to indicate to other devices that either a new possible device has come online or that another needs to be removed from some MLS groups due to being deleted.¶

Typically, a device is created by a user when they log in to a new session. Similarly, a device is deleted/removed when they log out of that client.¶

The device list update takes the shape of an EDU (Section 12.9), as such:¶

{
   "type": "m.device_list_update",
   "sender_id": "@alice:example.org",
   "content": {
      "changed": [/* Device Objects */],
      "removed": [/* Device IDs */]
   }
}

The device objects are the same as in the response for /user/:userId/device/:deviceId (Section 12.10.1.1), indicating that either a new device was created or that information about a previous device has changed.¶

TODO: Matrix's m.device_list_update EDU is very different from this, and relatively complicated. Do we actually need a stream_id, like in Matrix? Do we then need the /devices endpoint?¶

{
   "device_id": "ABCDEF",
   "user_id": "@alice:example.org",
   "algorithms": [
      "m.mls.v1.dhkemx25519-aes128gcm-sha256-ed25519"
   ],
   "keys": {
      "m.mls.v1.credential.ed25519:ABCDEF":
         "<unpadded base64 BasicCredential>"
   },
   "signatures": {
      "@alice:example.org": {
         "m.mls.v1.credential.ed25519:ABCDEF":
            "<unpadded base64 signature>"
      }
   }
}

12.10.2. To-Device Messaging

To-device messaging is an ability to send information directly to another device, typically to carry MLS Welcome messages and similar. They are sent as EDUs (Section 12.9), one per receipient device and payload:¶

{
   "type": "m.direct_to_device",
   "sender": "@alice:example.org",
   "content": {
      "target": "@bob:example.org",
      "target_device": "ABCD",
      "message_type": "m.room.encrypted",
      "message": {
         /* message_type-specific schema */
      }
   }
}

target and target_device denote the destination user ID (Section 3.3) and device ID (Section 3.4) for that user. This EDU MUST be sent to the server denoted by the target user ID. If the target user doesn't exist or doesn't have a device with the ID described, the receiving server drops/ignores the EDU.¶

See Section 4.3 for an example of a to-device message being used.¶

12.10.3. One Time Key Claiming

To enable two devices to communicate, they need to claim a key package (Section 4.4) for the other device. These key packages are also called "one time keys". This is done through the following endpoint.¶

{
  "one_time_keys": {
    "@alice:example.org": {
      "ABCD":
        "m.mls.v1.key_package.dhkemx25519-aes128gcm-sha256-ed25519"
    }
  }
}

{
  "one_time_keys": {
    "@alice:example.org": {
      "ABCD": {
        "m.mls.v1.key_package.dhkemx25519-aes128gcm-sha256-ed25519":
          "<unpadded base64 encoded key package>"
      }
    }
  }
}

12.11.1. Open Questions

• Should we include /_matrix/federation/v1/version in here? It's used by federation testers, but not really anything else.¶