Matrix is a Distributed Real-time Database

What is Matrix?

A chat network

What is Matrix?

A group messaging network

What is Matrix?

An ecosystem

What is Matrix?

With bridges!

What is Matrix?

And bots!

Integrate with GitLab, Mastodon, others
Display comics
Perform calculations
Track karma
Send SMS
Render LaTeX
Show the weather
... many more ...

What is Matrix?

An open network for secure, decentralized communication

What is Matrix?

An open network for secure, decentralized communication

It's an open standard
There's a spec at matrix.org/docs/spec
JSON over HTTP

What is Matrix?

An open network for secure, decentralized communication

This is the interesting bit
Federated, like email
Anyone can run a homeserver
You can talk to people on other homeservers

What is Matrix?

An open network for secure, decentralized communication

You can run your own server
You can still connect to other people
(if you want to)

Sending messages with curl

Run Synapse:

python -m synapse.app.homeserver \
    --config-path homeserver.yaml

Sending messages with curl

Ask the server what version it is:

$ curl -s 'http://localhost:8008/_matrix/client/versions'
{
  "versions": [ ..., "v1.2" ],
  "unstable_features": { ... }
}

Sending messages with curl

Ask to register a new user:

$ curl -s '.../_matrix/client/r0/register' -d '{}'
{
  "session": "sEdCvdBIiRxwqxULhKyBGNMx",
  "flows": [ { "stages": [ "m.login.dummy" ] } ],
  "params": {}
}

Sending messages with curl

$ curl -s '.../_matrix/client/v1/register' -d '{
    "auth": { "type": "m.login.dummy" },
    "username": "curluser1",
    "password": "mypassword"
}'

{
  "user_id": "@curluser1:localhost",
  "home_server": "localhost",
  "access_token": "syt_Y3VybHVzZXIx_...",
  "device_id": "HHOGSCKLWW"
}

Sending messages with curl

Find the types of login:

$ curl -s '.../_matrix/client/r0/login'

{
  "flows": [
    { "type": "m.login.password" },
    { "type": "m.login.application_service" },
    ...
  ]
}

Sending messages with curl

$ curl -s '.../matrix/client/v1/login' -d '{
    "type":"m.login.password",
    "identifier": { "user": "@curluser1:localhost", "type": "m.id.user" },
    "password":"mypassword"
}'

{
  "user_id": "@curluser1:localhost",
  "access_token": "syt_Y3VybHVzZXIx_...",
  "home_server": "localhost",
  "device_id": "HEUUQYFAMG",
  "well_known": { ... }
}

Sending messages with curl

(Register another user:)

$ curl -s '.../_matrix/client/v1/register' -d '{
    "auth": { "type": "m.login.dummy" },
    "username": "curluser2",
    "password": "mypassword"
}'

Sending messages with curl

Create a room:

$ curl -s '.../_matrix/client/r0/createRoom'
    -H 'Authorization: Bearer syt_Y3VybHVzZXIx_...'
    -d '{"invite":["@curluser2:localhost"]}'

{
  "room_id": "!JRyYpMzvxJMAhVAPSv:localhost"
}

Sending messages with curl

Sync: (initial sync)

$ curl -s '.../_matrix/client/r0/sync'
    -H 'Authorization: Bearer syt_Y3VybHVzZXIx_...'

{
  "next_batch": "s41_4149_0_7_28_1_2_17_1",
  "account_data": { ...
  "presence": { ...
  "rooms": {
    "join": {
      "!JRyYpMzvxJMAhVAPSv:localhost": {
        "timeline": { "events": [ {
          "type": "m.room.create",
...

Sending messages with curl

Sync again:

$ curl -s '.../v1/sync?since=s41_4149_0_7_28_1_2_17_1'
    -H 'Authorization: Bearer syt_Y3VybHVzZXIx_...'

{
  "next_batch": "s41_4159_0_7_28_1_2_17_1",
  "presence": {
...

Sending messages with curl

As user2, sync to find the invite:

$ curl -s '.../_matrix/client/v1/sync'
    -H 'Authorization: Bearer abc_Y3VybHVzZXIy_...'

{
  "next_batch": "s41_4165_0_7_28_1_2_17_1",
  "account_data": { ... }, "presence": { ... },
  "rooms": {
    "invite": {
      "!JRyYpMzvxJMAhVAPSv:localhost": {
        "invite_state": {
          "events": [
            { "type": "m.room.create",
...

Sending messages with curl

"events": [ ...
            {
              "type": "m.room.member",
              "state_key": "@curluser1:localhost",
              "content": {
                "membership": "join",
                "displayname": "curluser1"
              },
              "sender": "@curluser1:localhost"
            },
...

Sending messages with curl

"events": [ ...
            {
              "type": "m.room.member",
              "state_key": "@curluser2:localhost",
              "content": {
                "membership": "invite",
                "displayname": "curluser2"
              },
              "sender": "@curluser1:localhost",
              "event_id": "$rMb..."
              ...
            }
...

Sending messages with curl

As user2, check what rooms we are in:

$ curl -s '.../_matrix/client/r0/joined_rooms'
    -H 'Authorization: Bearer abc_Y3VybHVzZXIy_...'

{
  "joined_rooms": []
}

Sending messages with curl

As user2, accept the invite:

$ curl -s '.../r0/rooms/!JRyYpMzvxJMAhVAPSv:localhost/join'
    -H 'Authorization: Bearer syt_Y3VybHVzZXIy_...'
    -d '{ "roomId": "!JRyYpMzvxJMAhVAPSv:localhost" }'

{
  "room_id": "!JRyYpMzvxJMAhVAPSv:localhost"
}

Sending messages with curl

As user2, check again:

$ curl -s '.../_matrix/client/r0/joined_rooms'
    -H 'Authorization: Bearer abc_Y3VybHVzZXIy_...'

{
  "joined_rooms": [
    "!JRyYpMzvxJMAhVAPSv:localhost"
  ]
}

Sending messages with curl

As user2, sync again:

$ curl -s '.../_matrix/client/r0/sync?since=s41_4165_0_7_28_1_2_17_1'
    -H 'Authorization: Bearer abc_Y3VybHVzZXIy_...'

{
...
  "rooms": {
    "join": {
      "!JRyYpMzvxJMAhVAPSv:localhost": {
        ... events here ...
...

Sending messages with curl

As user1, sync:

$ curl -s '.../_matrix/client/v1/sync?since=s41_4159_0_7_28_1_2_17_1'
    -H 'Authorization: Bearer syt_Y3VybHVzZXIx_...'

{ ...
          "events": [
            {
              "type": "m.room.member",
              "sender": "@curluser2:localhost",
...
}

Sending messages with curl

As user1, say something:

$ curl -s -X PUT '.../v1/rooms/!JRyYpMzvxJMAhVAPSv:localhost
    /send/m.room.message/mytransaction-A'
    -d '{ "body": "Hello from curl!", "msgtype": "m.text" }'
    -H 'Authorization: Bearer syt_Y3VybHVzZXIx_...'

{
  "event_id": "$F_CZ9..."
}

Sending messages with curl

As user2, sync:

$ curl -s '.../v1/sync?since=s42_4186_0_7_28_1_2_17_1'
    -H 'Authorization: Bearer abc_Y3VybHVzZXIy_...'
...
  "rooms": { "join": { "!JRyYpMzvxJMAhVAPSv:localhost": {
    "timeline": { "events": [ {
      "content": {
        "body": "Hello from curl!",
        "msgtype": "m.text"
      },
      "sender": "@curluser1:localhost",
      "event_id": "$F_CZ9...",
...

Sending messages with curl

Syncing is a long poll ...

$ curl -s '.../v1/sync?timeout=1000000&since=s43_5796_0_7_28_1_2_17_1'
    -H 'Authorization: Bearer abc_Y3VybHVzZXIy_...'

...

Sending messages with curl

... that returns when something happens

$ curl -s '.../v1/sync?timeout=1000000&since=s43_5796_0_7_28_1_2_17_1'
    -H 'Authorization: Bearer abc_Y3VybHVzZXIy_...'

...
  "rooms": { "join": { "!JRyYpMzvxJMAhVAPSv:localhost": {
    "timeline": { "events": [ {
      "content": {
        "body": "It works!",
        "msgtype": "m.text"
      },
      "sender": "@curluser1:localhost",
      "event_id": "$F_CZ9...",
...

Messages are events

"content" is what a client sends

{
  "content": {
    "body": "hello",
    "msgtype": "m.text"
  },
  "event_id": "$14606535757KCGXo:localhost",
  "origin_server_ts": 1460653575105,
  "sender": "@example:localhost",
  "type": "m.room.message",
  "unsigned": { "age": 800348 }
}

Messages are events

The server assigns ID, sender etc.

{
  "content": {
    "body": "hello",
    "msgtype": "m.text"
  },
  "event_id": "$14606535757KCGXo:localhost",
  "origin_server_ts": 1460653575105,
  "sender": "@example:localhost",
  "type": "m.room.message",
  "unsigned": { "age": 800348 }
}

Messages are events

The type is part of the URL we sent

$ curl -s -X PUT '.../send/m.room.message/mytransaction-A'

...
  "content": ...
  "event_id": "$14606535757KCGXo:localhost",
  "origin_server_ts": 1460653575105,
  "sender": "@example:localhost",
  "type": "m.room.message",
  "unsigned": { "age": 800348 }
}

Messages are events

The content can vary

{
  "content": {
    "body": "What *is* this?",
    "formatted_body": "What <b>is</b> this?",
    "format": "org.matrix.custom.html",
    "msgtype": "m.text"
  },
...

Messages are events

Or maybe even like this⁴:

  "type": "m.message",
  "content": {
    "m.message": [
      {
        "mimetype": "text/plain",
        "body": "Something _new_?"
      },
      {
        "mimetype": "text/html",
        "body": "Something <i>new</i>?"
      }
...

[4] artificialworlds.net/blog/2022/03/08/comparison-of-matrix-events-before-and-after-extensible-events/

Other types of events

There are:

Message events
State events
Ephemeral events
Probably some others

Other types of events

Some message events:

Normal messages
Redactions
Polls
... lots of others ...

Other types of events

Normal messages we have already seen:

{
  "content": {
    "body": "What *is* this?",
    "formatted_body": "What <b>is</b> this?",
    "format": "org.matrix.custom.html",
    "msgtype": "m.text"
  },
...

Other types of events

Redactions destroy another event's content:

{
  "content": { "reason": "Spamming" },
  "event_id": "$143273582443PhrSn:example.org",
  "origin_server_ts": 1432735824653,
  "redacts": "$fukweghifu23:localhost",
  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
  "sender": "@example:example.org",
  "type": "m.room.redaction",
  "unsigned": { "age": 1234 }
}

Other types of events

Polls allow asking a question:

{
  "type": "org.matrix.msc3381.poll.start",
  "content": {
    "org.matrix.msc3381.poll.start": {
      "question": { "m.text": "Which?" },
      "answers": [
        { "id": "a", "m.text": "A, of course" },
        { "id": "b", "m.text": "But B!" },
      ]
    },
...

Other types of events

Polls are unstable.

This is allowed/encouraged.

Find out more about polls in MSC3381⁵.

[5] github.com/matrix-org/matrix-spec-proposals/pull/3381

Other types of events

Some state events:

Creation of a room
Name of a room
Membership of a person
... lots of others ...

Other types of events

Creation of a room:

{
  "content": {
    "creator": "@example:example.org",
    "room_version": "9",
    ...
  },
  "state_key": "",
  "type": "m.room.create",
...

Other types of events

Name of a room:

{
  "content": {
    "name": "The best room"
  },
  "state_key": "",
  "type": "m.room.name",
...

Other types of events

Membership of a person

{
  "content": {
    "displayname": "Alice Margatroid",
    "membership": "join",
    ...
  },
  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
  "sender": "@example:example.org",
  "state_key": "@alice:example.org",
  "type": "m.room.member",
...

Other types of events

Ephemeral events don't last long

{
  "content": {
    "user_ids": [
      "@alice:matrix.org",
      "@bob:example.com"
    ]
  },
  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
  "type": "m.typing"
}

(Note: no event id)

State Resolution

The event graph

State Resolution

A split brain

State Resolution

A state conflict

State Resolution

In what order did important things happen?

State Resolution

Kahn's algorithm: no in-arrows means new

State Resolution

Kahn's algorithm: no in-arrows means new

State Resolution

Kahn's algorithm: no in-arrows means new

State Resolution

Kahn's algorithm: no in-arrows means new

State Resolution

Resolve ties using Matrix-specifics e.g. timestamp

State Resolution

Important: servers with the same events get the same result.
Contrast to blockchains:
- Split brains are fine
- We can merge history

Distributed Real-time Database

Chat requires a distributed real-time database

To receive messages when offline
To support multiple devices
For chat history
When federation servers appear or disappear
To be robust to network splits

Distributed Real-time Database

A distributed real-time database is exactly what we need for many, many other things:

Video conferences and voice rooms
Collaborative creativity
Immersive environments
Peer-to-peer

Matrix was always designed with this in mind.

Distributed Real-time Database

Video conferences and voice rooms

WebRTC works to communicate
But how do you negotiate who calls each other?
We can do the signalling layer over Matrix
MSC3401⁶ defines how to do it
"Full mesh" (peer to peer) or via central foci
We can even have multiple foci involved in one room
Element Call works right now (full mesh)

[6] github.com/matrix-org/matrix-spec-proposals/pull/3401

Distributed Real-time Database

Collaborative creativity

TheBoard whiteboard⁷
Collabs library⁸ collaborative editor and more
Matrix CRDT⁹ based on Yjs
File storage¹⁰ - Matrix for permissions etc.
Everything Is A Room

[7] github.com/toger5/TheBoard
[8] npmjs.com/package/@collabs/collabs
[9] github.com/YousefED/Matrix-CRDT
[10] fosdem.org/2022/schedule/event/matrix_filesystem/

Distributed Real-time Database

Immersive environments

[11] Third Room: youtu.be/e26UJRCGfGk

Distributed Real-time Database

Peer-to-peer

The server runs on your device
No need to trust anyone
Robust to network attacks

Contents

What is Matrix?

What is Matrix?

What is Matrix?

What is Matrix?

What is Matrix?

What is Matrix?

What is Matrix?

What is Matrix?

What is Matrix?

What is Matrix?

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Sending messages with curl

Messages are events

Messages are events

Messages are events

Messages are events

Messages are events

Other types of events

Other types of events

Other types of events

Other types of events

Other types of events

Other types of events

Other types of events

Other types of events

Other types of events

Other types of events

Other types of events

Other types of events

Other types of events

State Resolution

State Resolution

State Resolution

State Resolution

State Resolution

State Resolution

State Resolution

State Resolution

State Resolution

State Resolution

State Resolution

Distributed Real-time Database

Distributed Real-time Database

Distributed Real-time Database

Distributed Real-time Database

Distributed Real-time Database

Distributed Real-time Database

More info

More info