The Matrix protocol is full of concepts sometimes hard to grasp. In this post I’m going to try to cover how it’s used in the context of messaging, how close to e-mail it can feel, and how decentralisation is achieved in the open safely. For the sake of simplicity and ease of understanding I might lie to you sometimes: this post is aimed at non-experts.

Instant messaging

Matrix is a protocol to describe interactions between several entities. It can be used for many things, but its most popular usage right now is for instant messaging. Two people can have a conversation, but there can also be much larger conversations with many people participating at the same time.

The protocol also allows more fancy things than sending and receiving text messages. It is possible to place calls, send pictures, edit typos, send emoji reactions and much more. But the protocol is not finished and is in fact enriched regularly. As an example short voice messages are being worked on at the moment.

Matrix is a very special kind of instant messaging protocol: it’s a federated one. This concept can sound complicated in the first place, but you probably already know everything there is to know about federation. In fact, you even already use a federated system every day: e-mails are federated!

That thing called email

The email we know

People are quite familiar with e-mail and understood it rapidly because the analogy with the physical world is pretty straightforward. An interesting aspect of e-mails is that you don’t need to sign-up on the same provider as the person you are writing to: people who have a gmail.com address can send and receive emails from people who have an outlook.com address. Being able to talk to one or more people on a different provider than the one you use has a name: it’s called a federated system.

You are probably already familiar with how e-mail addresses look like, but let’s highlight the important bits. E-mail addresses contain two important informations: the identifier, and who is their provider. Let’s take [email protected] as an example. In this case alice is the identifier and gmail.com is the provider.

One last very interesting aspect of e-mails is their ability to follow-up on conversations. When two or more people send emails and replies to others, their client creates a thread: a succession of messages on a same topic, grouped together by most modern e-mail clients.

E-mail but instantaneous?

In the Matrix universe things are quite similar to e-mail. People will get a personal Matrix ID, comparable to an e-mail address. It is also composed of an identifier, and a provider. Let’s take @bob:gnome.org as an example: the leading @ means the ID belongs to a person, bob is the identifier of that person, and gnome.org is the provider.

People who have a different provider can talk to one another. People with a kde.org Matrix account can send and receive messages from people who have a gnome.org Matrix account. Instead of exchanging e-mails, people exchange instant messages, pictures, edits… All of those are called events.

When two or more people send events to others, their client does not create a thread but creates a room. In the same ways email threads don’t have an address, rooms don’t have one by default. They only have a very cryptic identifier (e.g. !gUVCqdHIPVYUqxHmYk:gnome.org for the Newcomers room of GNOME)

Contratory to e-mail threads, when some people want to make the Matrix conversation public they can give an address to their room, which is sometimes also called an alias. For example, the Newcomers room of GNOME has the #newcomers:gnome.org alias as a main address. The alias of a room is made of two important bits: the leading # means this alias belongs to a room, newcomers is the idenfier (here newcomers) and gnome.org is the provider where the alias was created.

Two or more providers can create an alias for the same room. When a room has two or more aliases, it needs to pick a single primary one called a canonical alias. Every additional one is an alternate alias.

The table below recapitulates the concepts which are close in the e-mail world and in the Matrix universe.

Decentralised does not mean messy

Spread the words

In e-mail threads every participant has a copy of the conversation in their mailbox. The same thing happens on Matrix: rooms are not stored on a single server but on each server of the participants.

That means if a room only has members with a :gnome.org account, the room will only exist on the gnome.org server. As soon as someone with a e.g. :ergaster.org account joins the room, the ergaster.org server will get a copy of the room too.

Fortunately, the Matrix protocol allows participants of a room to get organised. Some people can have authority over the rest of the room to enforce policies.

Not just dumb pipes

Inside a room people have roles to determine what they can or can’t do. Those roles have a corresponding “Power Level”, a number that can vary between 0 and 100. To simplify things, let’s just consider the three default roles: no role, moderator, and administrator.

By default, when someone joins a room they have no role: their Power Level is 0. They can only speak (send message events).

Someone can be granted Moderator rights by changing their Power Level to 50. By default, moderators can change some room settings, kick and ban troublemakers, and change the name and main address of the room.

It is also possible to grant someone Administrator rights by changing their Power Level to 100. By Default, administrators can do everything the moderators can, plus enable room encryption, change history visibility, permissions, or upgrade the room.

A key point to bear in mind is that people with privileges can only promote or demote people with a strictly lower power level than theirs. This means that someone can lose sovereignty over a room if they carelessly grant Administrator privileges to someone who is on a different server!

The table below highlights a few of the default authorizations for each role.

Finally, people can add local aliases (alternate aliases) bearing their own provider’s name. As an example, someone with a :kde.org account can create a #gnome-newcomers:kde.org alias if they want. The main address will remain #newcomers:gnome.org because only the Moderators or Administrators of the room can change it. Who on the server can add an alias to a room is not part of the Matrix specification, but is specific to each server implementation.

I lied to you

I told you early in the article that I lied to you. I could cover in greater depth how power level can actually go below 0 and why it’s useful, or how the authorizations corresponding to a power level can actually be updated. This is out of the scope of this article. A post on how an organisation can keep its sovereignty in a decentralised and open network as Matrix will follow in the coming weeks. We at the GNOME Foundation indeed are very excited about Matrix but need to take care of managing things properly to ensure our contributors’ safety.