Skip to main content

Matrix Message Transport

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft whose latest revision state is "Replaced".
Authors Travis Ralston , Matthew Hodgson
Last updated 2022-11-06
Replaced by draft-ralston-mimi-linearized-matrix, draft-ralston-mimi-linearized-matrix
RFC stream (None)
Stream Stream state (No stream defined)
Consensus boilerplate Unknown
RFC Editor Note (None)
IESG IESG state I-D Exists
Telechat date (None)
Responsible AD (None)
Send notices to (None)
More Instant Messaging Interoperability                       T. Ralston
Internet-Draft                                                M. Hodgson
Intended status: Informational          The Foundation C.I.C.
Expires: 10 May 2023                                     6 November 2022

                        Matrix Message Transport


   This document specifies an openly federated protocol, Matrix, for
   interoperable message transport.

About This Document

   This note is to be removed before publishing as an RFC.

   The latest revision of this draft can be found at
   mimi-matrix-transport.html.  Status information for this document may
   be found at

   Discussion of this document takes place on the More Instant Messaging
   Interoperability Working Group mailing list (,
   which is archived at
   Subscribe at

   Source for this draft and an issue tracker can be found at

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 10 May 2023.

Ralston & Hodgson          Expires 10 May 2023                  [Page 1]
Internet-Draft          Matrix Message Transport           November 2022

Copyright Notice

   Copyright (c) 2022 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Matrix Primitives . . . . . . . . . . . . . . . . . . . . . .   3
   3.  Federation Basics and Eventual Consistency  . . . . . . . . .   4
   4.  Interoperability  . . . . . . . . . . . . . . . . . . . . . .   5
   5.  Encryption  . . . . . . . . . . . . . . . . . . . . . . . . .   6
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .   6
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   6
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .   6
     7.2.  Informative References  . . . . . . . . . . . . . . . . .   7
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .   8
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   8

1.  Introduction

   Designing transports for interoperable messaging can often be a race
   towards the lowest common denominator among the systems one is
   attempting to interoperate.  In addition to considering those
   systems' capabilities, the design must also account for a number of
   edge cases and routine failures that often come up during
   implementation, such as handling of network partitions/disconnects,
   malicious actors (intentional or accidental), and recovering from
   failure states.

   Matrix solves this by providing a highest-common denominator
   messaging layer between current real-world messaging systems, which
   expresses events in an authenticated Directed Acyclic Graph (DAG)
   that is incrementally replicated between untrusted participating
   servers, providing decentralized access control without single points
   of control.  This ensures that all participants converge on a
   consistent view of room history as rapidly as possible, including
   key/value state, even in the face of bad actors or network partitions
   - rather than all participants piecing together partial independent

Ralston & Hodgson          Expires 10 May 2023                  [Page 2]
Internet-Draft          Matrix Message Transport           November 2022

   views of a room from pubsub streams or other sources.  This provides
   aggressive resilience to network partitions, suitable even for the
   harshest denied, disrupted, intermittent and high latency
   environments (for example, P2P networks overlaying Bluetooth or HF
   carriers; maritime or space deployments).

   Matrix [MxSpec] is an open standard first created in 2014 to define
   interoperable, decentralized, secure communication.  Matrix exited
   beta in June 2019, and having been actively maintained and improved
   since under an open governance model [MxFoundation], a subset of the
   open standard fits extremely well within the More Instant Messaging
   Interoperability (MIMI) working group's efforts to establish
   standards for interoperable modern messaging applications.  This
   document focuses on the transport (message- or event-passing) portion
   of the Matrix protocol as it relates to MIMI.

2.  Matrix Primitives

   Within Matrix there are four key primitives needed for cross-server

   1.  Homeservers (or simply "servers"), identified as [RFC1123] Host
       Names with extensions for IPv6, which act as a namespace for
       holding Users and replicated copies of Rooms.

   2.  Rooms, identified as !, consist of the
       Directed Acyclic Graph (DAG) for Events sent by Users.  The DAG
       is replicated across all Homeservers participating in that Room.
       It can be thought of as a pubsub topic with additional semantics
       to access and authenticate message history and key/value state.

   3.  Events, identified as $base64HashOfItself, have a type
       ( or, for example) and are sent by
       Users, added to the Room (DAG) by Homeservers.  State Events are
       versioned key/value data which are pinned in the room, usually
       tracking information about the room itself (membership, room
       name, topic, etc).  State Events can be overwritten while other
       Events can not (though normal Events can be "edited" by sending a
       new Event which points to the original Event).

   4.  Users, identified as, can have multiple
       devices (logged-in sessions) to join/leave Rooms and send Events
       to those rooms.

   Other primitives do exist in Matrix, such as Devices for users,
   however they are not directly relevant to this document's purpose and
   have been excluded.

Ralston & Hodgson          Expires 10 May 2023                  [Page 3]
Internet-Draft          Matrix Message Transport           November 2022

3.  Federation Basics and Eventual Consistency

   Matrix uses a set of RPC APIs (typically over HTTPS) to pass JSON
   objects between client and server, and server and server
   (federation).  In its simplest form, a user sends an event to a room
   using the Client-Server API [CSApi], which servers then forward to
   each other using the Federation API [SSApi].  For an interoperable
   transport, the Federation API would be used.  The events which users
   send are populated with information about previous events (as known
   to the local server), "authorization events" (events which prove the
   sender is allowed to send the event in the first place), and
   additional server-specific signatures (to prove authenticity) by the
   server before the event is sent to other servers.  Receiving servers
   check the authorization events against their local view of the room
   to decide whether the received event should be accepted, soft-failed
   or rejected - thus providing decentralized access control semantics.

   An example workflow might be that Alice ( wants
   to invite Bob ( to a room over federation
   (because the users are on different servers).  Alice's client would
   send an /invite [CSInviteApi] request for in that
   room, which causes to send a similar /invite
   [SSInviteApi] request over federation to  When Bob
   has accepted the invite (by joining the room, using similar
   endpoints), the room's state and recent history are replicated to
   Bob's server and sent to Bob's client.  Both Alice and Bob can now
   send events, including events for instant messaging
   cases, and their servers will build a DAG off of them.  Servers by
   default push events to each other, but can also pull events from each
   other in order to fill holes in their DAG.

   A key part of this eventually consistent model is that a server can
   go offline (for any reason, including being affected by a Denial of
   Service (DoS) attack, network partition, or being turned off) and
   other servers in the room are not affected.  The other servers can
   continue to send events into the room and amongst each other while
   the other server is offline.  When that server comes back online, it
   will have the events it missed efficiently synchronized to it by the
   other servers.  Similarly, if the offline server was operational but
   unable to send events to other servers, it can continue sending its
   own events to the room and have those events be "merged" with the
   other servers' events when network connectivity is restored.
   Conflicts with state events (two or more changes to the room state at
   the same time or by temporarily diverged servers, often due to
   network connectivity issues) are resolved using an appropriate State
   Resolution Algorithm [SSStateResAlgo].  The state resolution
   algorithm is not covered here for brevity, and would likely be its
   own document.

Ralston & Hodgson          Expires 10 May 2023                  [Page 4]
Internet-Draft          Matrix Message Transport           November 2022

   Practically, this looks like:

  Room on server A sent message A1,     The same room on server B has
  then sent A2, and received C1 from    received A1 and A2, but not C1,
  server C which raced with A2 and so   e.g. due to network connectivity
  follows A1.                            problems.
     __________                                              __________
    '          '                                            '          '
    '    A1    '                                            '    A1    '
    '   /  \   '                                            '   /      '
    '  A2  C1  '                                            '  A2      '
    '__________'                                            '__________'

  Server A sends another message, A3:

     __________                                              __________
    '          '                                            '          '
    '    A1    '                                            '    A1    '
    '   /  \   '                                            '   /      '
    '  A2  C1  '------------------------------------------->'  A2   ?  '
    '   \  /   '  HTTP PUT                                  '   \  /   '
    '    A3    '  /_matrix/federation/v1/send/{txnId}       '    A3    '
    '__________'  A3                                        '__________'

  Server B sees that A3 refers to missing event C1, and pulls it from A:

     __________                                              __________
    '          '                                            '          '
    '    A1    '                                            '    A1    '
    '   /  \   '                                            '   /  \   '
    '  A2  C1  '<-------------------------------------------'  A2   C1 '
    '   \  /   '  HTTP GET                                  '   \  /   '
    '    A3    '  /_matrix/federation/v1/get_missing_events '    A3    '
    '__________'  C1                                        '__________'

  Typically, get_missing_events isn't needed, given servers push all
  events to all participating servers by default.

   Figure 1

4.  Interoperability

   Matrix's split of Federation and Client-Server APIs allow homeservers
   to implement the API surface which is most relevant for its
   application.  For interoperability, only the Federation API is
   relevant.  The APIs have been designed to intrinsically support load
   balancing and active/active horizontal scaling - for instance, it's
   valid for different parts of a server to race together when sending a

Ralston & Hodgson          Expires 10 May 2023                  [Page 5]
Internet-Draft          Matrix Message Transport           November 2022

   message in a room (causing a temporary fork in the room's event DAG,
   same as if the race happened against a remote server), avoiding the
   need for global locks within the server.

   The steps needed for an existing system to be interoperable with
   another over Matrix would mean implementing the Federation API and
   storing minimal information about the room's current state (state
   events (including members), a few of the most recent event
   identifiers seen, etc) and hooking that up to their existing
   application.  An example of this happening is Gitter showcasing
   Matrix interoperability back in 2020 [GitterMigration].

   As was the case with Gitter, existing messaging applications could
   deploy a homeserver using software which already exists to rapidly
   get connected to the Matrix network.  Later stages of implementation
   for messaging applications might include writing proprietary software
   to handle application-specific traffic on one end and Matrix
   federation on the other, optimizing for internal scaling

5.  Encryption

   End-to-end Encryption is deliberately layered on top of the Matrix
   transport (Client-Server or Federation APIs).  Currently a
   combination of Double Ratchet (Olm) encryption and group ratchet
   encryption (Megolm) is specified in the End-to-End Encryption section
   of the Client-Server API [CSEncryptionApi], but Matrix over MLS
   [I-D.ietf-mls-protocol] (with minor bookkeeping to compensate for the
   lack of a centralised sequencing function in Matrix) is being
   specified as DMLS.  [DMLS]

6.  Security Considerations

   TODO Security.  Matrix has its own threat model that needs to be
   described here to protect against malicious actors.

7.  References

7.1.  Normative References

   [RFC1123]  Braden, R., Ed., "Requirements for Internet Hosts -
              Application and Support", STD 3, RFC 1123,
              DOI 10.17487/RFC1123, October 1989,

   [SSApi]    The Foundation C.I.C., "Federation API", 2022,

Ralston & Hodgson          Expires 10 May 2023                  [Page 6]
Internet-Draft          Matrix Message Transport           November 2022

7.2.  Informative References

   [CSApi]    The Foundation C.I.C., "Client-Server API",
              2022, <>.

              The Foundation C.I.C., "End-to-End Encryption |
              Client-Server API", 2022, <

              The Foundation C.I.C., "POST
              /_matrix/client/v3/rooms/:roomId/invite | Client-Server
              API", 2022, <

   [DMLS]     Chathi, H., "Decentralised MLS", Web 
    , 2021, <

              Hodgson, M., "Gitter now speaks Matrix!", 2020,

              Barnes, R., Beurdouche, B., Robert, R., Millican, J.,
              Omara, E., and K. Cohn-Gordon, "The Messaging Layer
              Security (MLS) Protocol", Work in Progress, Internet-
              Draft, draft-ietf-mls-protocol-16, 11 July 2022,

              The Foundation C.I.C., "The
              Foundation", 2019, <>.

   [MxSpec]   The Foundation C.I.C., "Matrix Specification |
              v1.4", 2022, <>.

Ralston & Hodgson          Expires 10 May 2023                  [Page 7]
Internet-Draft          Matrix Message Transport           November 2022

              The Foundation C.I.C., "POST
              /_matrix/federation/v2/invite/:roomId/:eventId |
              Federation API", 2022, <

              The Foundation C.I.C., "Room State Resolution |
              Federation API", 2022, <


   TODO acknowledge.

Authors' Addresses

   Travis Ralston
   The Foundation C.I.C.

   Matthew Hodgson
   The Foundation C.I.C.

Ralston & Hodgson          Expires 10 May 2023                  [Page 8]