status update – July 2017

Hi folks,

Thought it was worth giving a quick status update on what’s going on since our last blog post, which explained the funding situation Matrix has found itself in.  The TL;DR is that we’re still here; things are moving faster than ever (not least as we refocus on getting everything needed to get Matrix funded and sustainable in the longer term), but we still need concrete support from the community (both company sponsorship and personal donations) to ensure things keep going at the current rate.


Funding Status

So, the good news is that we had a great initial response to last week’s call to help – right now we have 199 people signed up on Patreon (go on, be the 200th! you know you want to :D), ~30 on Liberapay, and 14 bitcoin donations.  This sums up to just over $2000/month – which is getting close to our initial Patreon goal of $2500/month to helping support half the cost of the less senior devs working on Matrix. Endless thanks to everyone who has donated – especially the 19 folks (18 on Patreon, one on Liberapay) who have so generously pledged $50 or more a month!! Meanwhile, if you’re reading this and you haven’t pledged support yet – *please* consider heading over to Patreon or Liberapay or Bitcoin 1LxowEgsquZ3UPZ68wHf8v2MDZw82dVmAE and helping keep the project running.  Literally every dollar counts.

Meanwhile, while Patreon & friends are headed in the right direction to support one developer, we still have another 10 people working on all the various core components of Matrix itself who need to be supported in the near future.  (We look to be safe for the next month or two, but beyond that we’re counting on having solved this problem ;).  Right now we are hoping that companies who believe in Matrix and/or are building services on top will step up to sponsor development – as it’s pretty obvious that accelerating Dendrite, final E2E, Groups etc will improve professional Matrix-based services immeasurably.  If this sounds like you, please get in touch asap.

We’re also able to provide paid consulting and development (and prioritised development) services on Matrix (through Vector, the for-profit company responsible for Riot) for large pieces of work – for instance, if you’re anxious to see enterprise-focused Matrix features land sooner than later, please reach out.

Exciting news is that we already have one concrete offer of paid consulting work from a very major company who happens to love Matrix, building out Integrations capabilities which should directly benefit the wider Matrix ecosystem – and we also are very proud to announce our very first official corporate sponsor (see the next section for details)!  However, we still have a long way to go, so don’t be shy about getting in touch: we need your support!

Heads up that we’ve also started our various reward schemes for supporters – folks donating more than $5 on Patreon will have already heard most of this update in the first episode of the video blog that Amandine & I posted last Friday; and folks donating more than $10 will have heard some of the other details first hand through the broadcast of the global team weekly sync on Monday!  We’re still figuring out how to get these rewards over to liberapay & bitcoin supporters (not helped by both services being anonymous…).  We haven’t yet opened up the room as maintaining the accesslist is effectively blocked on Groups landing.  We also want to use Groups to manage the various lists of supporters around the place, so apologies that we haven’t got the lists published yet!

Finally on the funding side of things: we’re setting up the Foundation non-profit legal entity this week, letting us accept donations and sponsorship in a way which can directly fund the core developers (more details as we have them).  As soon as it’s incorporated, we’ll be able to sign up fully on Liberapay to accept donations there.


Announcing UpCloud: our very first official Corporate Sponsor!

As hinted above, we’re incredibly excited and happy that UpCloud have signed up as our first official corporate sponsor.  UpCloud has already been hosting all of’s infrastructure for the last 6 months (no mean feat, given the scale of the synapse & postgres!) – and last week they committed to extend their sponsorship further to help the project out in our time of need.

We’ve been very impressed with UpCloud’s service since migrating over back in February – particularly their spectacularly fast block IO (~500MB/s write, ~10,000 IOPS) which is incredibly useful for running a huge synapse deployment like’s – and they have a great footprint of datacentres around the world.

They also like Matrix so much that they’ve written this great tutorial for getting Synapse up and running on their hosts – and best of all, they have a special $25 discount for anyone in the Matrix community who wishes to use them: check out for the details!

We’d like to thank them profusely for being first in line to support us – and we look forward to seeing how far we can push their hardware over the coming months! :D


Development Status

Finally, loads and loads of stuff is happening on Matrix itself.  The main headlines are:

  • Groups.  Work in Synapse and matrix-react-sdk is happening at breakneck speed to get Groups out the door as soon as possible, so we can use them both to support the funding drive and in general to implement one of the most asked-for features of Matrix: the ability to group rooms together into a well-defined community (similar to Slack Teams or Discord Servers etc).  The way Groups work is to let users define groupings of both users and rooms; you can also define a metadata for the group to let you build homepages similar to the one which Riot/Web sprouted a few months ago.  You can then refer to the group of users when inviting/banning/kicking etc – or when managing your own roomlist.  We think it’s going to completely change how people use Matrix, and can’t wait to see it land on, although it’s still a few weeks away.
  • E2E Crypto.  We have three main things remaining here, after which E2E should be much much more usable for day-to-day purposes:
    1. Fixing the matrix-js-sdk to store crypto state in indexeddb rather than localstorage, to prevent multiple browser tabs racing and corrupting localstorage (which provides no locking mechanism).  This turns out to be much more of an epic than we thought, as indexeddb’s APIs are all strictly async, resulting in a whole bunch of previously synchronous APIs in matrix-js-sdk needing to become async too, as well as requiring us to switch promises library at least from Q to Bluebird.  However, most of this is now done so hopefully the new storage layer will land shortly. is the bug tracking this one…
    2. Fixing the overall UX of managing devices in a room (including key shares). is the bug for this one :)  Relatedly we also need to ensure invitees can decrypt messages in e2e rooms before they join (if history visibility allows it) – this is
    3. Fixing the UX of verifying devices (including cross-signing devices), to minimise the pain in verifying device ownership. is the master bug for this.
  • Integrations.  A large slice of the team is working on our next-generation integration hosting platform, which is starting to look unspeakably awesome.  We’ll be yelling loudly about this once there’s something to see and play with…

  • Rich Text Editor.  This was originally a GSoC project from last year, but is finally on by default now in matrix-react-sdk – letting users author their messages with full WYSIWYG behaviour and critically have a radically improved autocompletion UI/UX, including emoji, user names, room names, etc.  You can check it out at already :)
  • Mentions.  We’re finally semantically tagging references to users in messages so that they can be displayed nicely in the UI, and help with highlighting notifications!  This is due as soon as the Rich Text Editor work has finished.
  • Mobile SDKs.  The iOS & Android teams are currently on a mission to get parity between the iOS & Android SDKs and matrix-react-sdk.  This is stuff like implementing the new User Search API; Membership Event List Summaries; Dark theme(!); Translations; etc.  Progress is looking good!
  • Synapse performance.  Many many optimisations when calculating push rules when sending messages, which was taking up a substantial amount of the send path time.  Synapse develop looks to have reduced this significantly now – and as of Monday we’re running the new optimisations on
  • Dendrite.  Lots of work going into implementing Invitations currently, including improvements to the overall append-only log architecture to support them nicely.
  • Riot-Static.  This is one of our GSoC projects this year, written by Michael Telatynski (t3chguy) – providing a full static (no-JS) read-only view of Matrix, suitable for dumb web browsers and search engines.  It’s looking really exciting (although needs CSS) – there’s a copy currently deployed over at

Meanwhile, there’s a tonne of stuff happening in the community – an excellent summary may be found at this Community Round Up blog post by uhoreg!

So: this is where things stand right now – the team is sprinting away getting all the stuff above landed, and meanwhile I’m spending most of my life worrying about funding.  We’ll try to keep blogging more regularly to give better visibility on progress on both the funding & development situation, as well as to ensure there’s a written public record as well as the regular supporter-only updates.  However, for the latest realtime updates and sneak previews and tidbits you’ll probably want to sign up on Patreon or Liberapay :D


A Call to Arms: Supporting Matrix!

Hi folks,

TL;DR: if you like Matrix (and especially if you’re building stuff on it), please support us via Patreon or Liberapay to keep the core team able to work on it full-time, otherwise the project is going to be seriously impacted.  And if you’re a company who is invested in Matrix (e.g. itching for Dendrite), please get in touch ASAP if you’d like to sponsor core development work from the team.  And if you’re a philanthropic billionaire who believes in our ideals of decentralisation, encryption, and open communication as a basic human right – we’d love to hear from you too O:-)

I was expecting this blog post to be the Matrix Summer Special, focusing entirely on the incredible progress and updates we’ve made in the last few months in Matrix.  However, instead I’m going to talk about something different and literally critical to Matrix’s success.

As many people know, development has historically been exclusively and very generously sponsored by a large multinational telecoms infrastructure company for whom most of the core team once built telco messaging apps.  However, despite the project progressing better than ever (more on that later), we have just had our funding dramatically cut by >60%.

We seem to be suffering from a darkly amusing paradox, as the rationale from our corporate overlords is essentially: “Wow! Matrix is doing great and growing well – and you seem to have all sorts of exciting people and companies using and building on it.  But we’ve been footing the whole development bill since the outset in May 2014, and this simply doesn’t feel fair.  We’re happy to keep funding though – but only if others do too!”.  In other words, in some ways we are a victim of our own success…

So we now find ourselves in the situation that despite the project looking better than ever and having a tonne of amazing stuff in the pipeline, we are suddenly missing the funding to keep the core team working on it.  And the team is quite sizeable – reflecting the ambition and size of Matrix: right now we have effectively 11 people working specifically on Matrix itself: 1 on Synapse, 1 on Dendrite, 1 on e2e crypto, 2 on matrix-react-sdk (which powers Riot/Web), 2 on matrix-ios-kit / matrix-ios-sdk, 2 on matrix-android-sdk, 1 on bridges, and me (Matthew) managing the overall project.  (This ignores folks who overlap the team who are working specifically on Riot stuff).

Over the last few years we’ve had countless people ask if they can financially support Matrix. We haven’t been able to accept it for various reasons, but now is the time for us to step towards a more independent setup, and avoid a repeat of the situation we’re currently facing by opening up to external support.

So we need help from the community to keep going!  Please head over to Patreon or Liberapay and put some money in the meter (or send some bitcoin to 1LxowEgsquZ3UPZ68wHf8v2MDZw82dVmAE). In return, you’ll get to keep Matrix evolving at a decent rate, be a member of the upcoming group (complete with flair badges!), and other benefits like access to – a new dedicated room for prioritised support, discounted goodies from Riot once paid services arrive, access to a weekly supporters-only status podcast(!), and of course receive our eternal thanks. :)

Meanwhile, if you’re a company who depends on Matrix: please get in touch. We have the option for you to sponsor core Matrix development (e.g. Dendrite) or for us to provide you with more targeted support or feature development.  We’re already talking to several organisations who want to accelerate Dendrite specifically – and the more support we have there the faster we can go.

We’d also like to thank UpCloud for sponsoring hosting for the synapse instances – UpCloud has been coping impressively with the massive I/O and CPU/RAM requirements we have, and we recommend them unreservedly for folks looking to run their own homeservers.

Finally, one of the longer term plans to help fund Matrix is to get sponsorship from Riot, once Riot starts offering paid services. So, if you’re an investor who’s interested in the for-profit sides of Riot (paid integrations and paid Matrix hosting) then please get in touch with the Riot team ASAP!

Moving forward we are confident that we can secure funding, through sponsorship and Riot paid services, but in truth this decision caught us by surprise and so we need help both long term but also right now!

And whatever the funding situation, we’re of course always looking for contributions for code, bug reports, or just spreading the word about the project too! :)

Status Update

(or scroll to next section to see why this is bigger than “just” decentralised encrypted communication)

Despite the funding issue, the project really is going very well. Our vital stats (as seen through the lens of the synapse) are looking like this:

And meanwhile, looking back at the last big update (Holiday Special 2016), we can compare our progress with our goals for 2017 thus far:

  • Getting E2E Encryption out of beta ASAP.

This has progressed massively – we haven’t really yelled about it yet, but latest now finally implements the ability to share message keys between clients to let them decrypt older history and fix “unable to decrypt” errors (Mobile coming soon).  Meanwhile various root causes of “unable to decrypt” errors have been gradually eliminated; I can’t actually remember the last time I saw one! Once key-sharing and improved device verification UX is fully tested and tuned we should be able to declare E2E out of beta.


  • Ensuring we can scale beyond Synapse – i.e. implement Dendrite

Likewise, Dendrite is on track: we’ve implemented all the Hard Stuff which forms the skeleton of Dendrite (core federation, message signing, /sync, message sending, media repository etc) – which takes us to over 50% of Phase 1. After phase 1, we will have an initial usable release for all the core functionality.  Synapse’s performance has also improved enormously this year.


  • Getting as many bots and bridges into Matrix as possible, and doing everything we can to support them, host them and help them be as high quality as possible – making the public federated Matrix network as useful and diverse as possible.

Bridges and bots continue – from the core team we have a ‘puppeting’ Telegram bridge (matrix-appservice-tg), and from the wider community we have Discord, Skype, Signal, new Rocket.Chat and more.  Getting them polished and live is certainly an area where we need more manpower though.

  • Supporting Riot’s leap to the mainstream, ensuring Matrix has at least one killer app.

Riot has been sprouting new releases every few weeks, with a huge emphasis on proving UX:

  • an entirely new streamlined sign-up process
  • the new concept of home pages
  • a user directory search that actually works
  • internationalised to 27 languages
  • compact layout
  • loads of desktop improvements
  • piwik analytics support; etc.

There is still a lot of UX work to be done, but it’s converging fast on being a great entry point into the Matrix ecosystem, driving its growth across different groups and communities..

Meanwhile, a massive update to the iOS & Android apps just landed yesterday, switching to an entirely new UI layout to separate People from Rooms, synchronized Read Markers, and more!

  • Adding the final major missing features:
    • Customisable User Profiles (this is almost done, actually)

This is still hovering at ‘almost done’, and will be needed for some of the implementation of Groups (see below)..

  • Groups (i.e. ability to define groups of users, and perform invites, powerlevels, etc. per-group as well as per-user)

Groups are also in testing in Synapse too!  These will probably be the single biggest change to Matrix that we’ve seen since E2E encryption landed: it changes the dynamic of the whole network, given users can explicitly declare allegiance to different groups, which in turn have their own home pages and directories etc.  It lets users form communities, and declare their participation in those communities (if desired), and also lets rooms be grouped together.  One of our single biggest requests has been “subrooms” and we’re incredibly excited to see how well Groups solve this.

  • Threading

Sadly no progress on Threading so far this year.

  • Editable events (and Reactions)

We’re hoping to get looking at this (at last!) once Groups are done.

  • Maturing and polishing the spec (we are way overdue a new release)

You’ll have noticed that in the “how many people work on Matrix?” stats above, we didn’t mention anyone working on the Spec.  Because right now there isn’t anyone explicitly maintaining it, unfortunately; updates are done best-effort when everyone’s primary responsibilities allow it.  That said, there’s quite a lot of good stuff currently unreleased on HEAD. This is something which is obviously critical to fix once we have sustainable funding sorted again.  We can only apologise to folks like the Ruma developers who have suffered from the spec lag. :(

  • Improving VoIP – especially conferencing.

VoIP is improving lots on iOS, thanks to Denis Morozov’s GSoC project, and meanwhile we have all new conferencing powered by Jitsi on the horizon in the next few weeks too.

  • Reputation/Moderation management (i.e. spam/abuse filtering).

Lots of thinking about this (see below), but no development yet.

  • Much-needed SDK performance work on matrix-{react,ios,android}-sdk.

About 40% of the desired performance work has happened here (although not all has gone live yet).

  • …and a few other things which would be premature to mention right now. :D

All will be revealed in the next week or two – but suffice it to say that Integrations are going to be getting a Lot More Useful™. :)


There are very very few people actually working professionally on trying to build general-purpose open communication networks and protocols.  There’s us, some XMPP, IRCv3 and GNU Social/Mastodon folks, GNU Ring, Tox, Briar, Secure Scuttlebutt, IPFS,, Ricochet… and that’s literally all the major projects I can think of (sorry if I missed you!).  There’s probably only 50 developers in total working in this domain as their day job.

Meanwhile, there are literally hundreds of thousands of folks trudging away building more and more near-indistinguishable proprietary closed communication systems – trapping users inside ever more silos and fragmenting the basic ability to communicate on the ‘net.  It’s like a world where the open web was pushed into a tiny underground resistance, and everyone else was trapped in the walled gardens of AOL and Compuserve (or more contemporarily: Facebook, Twitter, WhatsApp etc).

In other words: the whole world of decentralised communication desperately needs your support.  This is a clear case of user choice and freedom: to give users the ability to pick who they trust with their data and metadata, without being forced into unilaterally trusting the Silicon Valley megacorps.  And this, dear Reader, is your chance to fix the world for the greater good. Seriously, the Matrix team is one of a handful in the world in a position to continue to push things in the right direction and avoid us falling into a permanent dystopia where communication is even more closed and proprietary than the Public Telephone Network!

Finally, there’s an even bigger issue at stake here than open communication.  As an open network, people can literally publish whatever content they like into Matrix – same as the web or the internet itself.  As a result, there’s scope for spam; abusive/malicious content; propaganda; and generally the whole spectrum of the best and worst of humanity.  Now, if we were a centralised system like Facebook, we might hire thousands of content moderators to frantically impose a rulebook on ‘acceptable’ content.  Or we might build invisible filter-bubbles for our users based on their social graph, cocooning them from scary unfamiliar content outside their social circles and reinforcing their preconceptions (whilst the resulting self-affirmation keeps them coming back, viewing more and more ads).

But we’re decentralised, and we have no absolute moral arbiter, and nor should we – on an open network it should be up to users and users alone to define and manage their own worldview and alignment.  Plus we are not fiscally obligated to keep users coming back to view more ads no matter what.  Instead, we are forced to confront the fundamental problem: building tools which empower users to curate and visualise their own content filters; letting them filter out the stuff they’re not interested in or find repellant… while still helping them be aware of their own viewpoint and the shape of the world beyond it.  We haven’t really started building this yet, but in the long term our feeling is that these tools will literally be vital for the survival of the human race (e.g. exposing anti-climate-change propaganda for what it is or helping users opt out of World War 3) – let alone the success of decentralisation.  A world where users blindly consume propaganda is doomed, and it’s a fascinating situation that the same tools which will allow Matrix users to tune out the rooms, users and conversations they’re not interested in could be directly applied to the bigger global problem.

So: Matrix needs you. Please become a supporter on Patreon or Liberapay, and help us save the world :)

– Matthew, Amandine & the whole team.


Synapse 0.21.1 released!

Hi folks – we forgot to mention that Synapse 0.21.1 was released last week.  This contains a important fix to the report-stats option, which was otherwise failing to report any usage stats for folks who had the option turned on.

This is a good opportunity to note that the report-stats option is really really important for the ongoing health of the Matrix ecosystem: when raising funding to continue working on Matrix we have to be able to demonstrate how the ecosystem is growing and why it’s a good idea to support us to work on it. In practice, the data we collect is: hostname, synapse version & uptime, total_users, total_nonbridged users, total_room_count, daily_active_users, daily_active_rooms, daily_messages and daily_sent_messages.

Folks: if you have turned off report-stats for whatever reason, please consider upgrading to 0.21.1 and turning it back on.

In return, the plan is that we’ll start to publish an official Grafana of the anonymised aggregate stats, probably embedded into the frontpage of, and then you and everyone else can have a view of the state of the Matrix universe. And critically, it’ll really help us continue to justify $ to spend on growing the project!

You can get Synapse 0.21.1 from or as normal.

Synapse 0.19.3 released

Hi all,

We’ve released Synapse 0.19.3-rc2 as 0.19.3 with no changes. This is a slightly unusual release, as 0.19.3-rc2 dates from March 13th and a lot of stuff has landed on the develop branch since then – however, we’ll be releasing that as 0.20.0 once it’s ready. Instead, 0.19.3 has a set of intermediary performance and bug fixes; the only new feature is a set of admin APIs kindly contributed by @morteza-araby.

The changelog follows – please upgrade from or your OS packages as normal :)

Changes in synapse v0.19.3 (2017-03-20)

No changes since v0.19.3-rc2

Changes in synapse v0.19.3-rc2 (2017-03-13)

Bug fixes:

  • Fix bug in handling of incoming device list updates over federation.

Changes in synapse v0.19.3-rc1 (2017-03-08)



Bug fixes:

  • Fix synapse_port_db failure. Thanks to @Pneumaticat! (PR #1904)
  • Fix caching to not cache error responses (PR #1913)
  • Fix APIs to make kick & ban reasons work (PR #1917)
  • Fix bugs in the /keys/changes api (PR #1921)
  • Fix bug where users couldn’t forget rooms they were banned from (PR #1922)
  • Fix issue with long language values in pushers API (PR #1925)
  • Fix a race in transaction queue (PR #1930)
  • Fix dynamic thumbnailing to preserve aspect ratio. Thanks to @jkolo! (PR #1945)
  • Fix device list update to not constantly resync (PR #1964)
  • Fix potential for huge memory usage when getting device that have changed (PR #1969)

An Adventure in IRC-Land

Hi everyone. I’m Kegan, one of the core developers at This is the first in a series on the IRC bridge. The aim of this series is to try to give a behind the scenes look at how the IRC bridge works, what kinds of problems we encountered, and how we plan to scale in the future. This post looks at how the IRC bridge actually works.

Firstly, what is “bridging”? The simple answer is that it is a program which maps between different messaging protocols so that users on different protocols can communicate with each other. Some protocols may have features which are not supported in the other (typing notifications in Matrix, DCC – direct file transfers – in IRC). This means that bridging will always be “inferior” to just using the respective protocol. That being said, where there is common ground a bridge can work well; all messaging protocols support sending and receiving text messages for example. As we’ll see however, the devil is in the detail…

A lot of existing IRC bridges for different protocols share one thing in common: they use a single global bot to bridge traffic. This bot listens to all messages from IRC, and sends them to the other network. The bot also listens for messages from users on the other network, and sends messages on their behalf to IRC. This is a lot easier than having to maintain dedicated TCP connections for each user. However, it isn’t a great experience for IRC users as they:

  • Don’t know who is reading messages on a channel as there is just 1 bot in the membership list.
  • Cannot PM users on the other network.
  • Cannot kick/ban users on the other network without affecting everyone else.
  • Cannot bing/mention users on the other network easily (tab completion).

We made the decision very early on that we would keep dedicated TCP connections for each Matrix user. This means every Matrix user has their own tiny IRC client. This has its own problems:

  • It involves multiple connections to the IRCd so you need special permission to set up an i:line.
  • You need to be able to support identification of individual users (via ident or unique IPv6 addresses).
  • With all these connections to the same IRC channels, you need to have some way to identify which incoming messages have already been handled and which have not.

Mapping Rooms

So now that we have a way to send and receive messages, how do we map the rooms/channels between protocols? This isn’t as easy as you may think. We can have a single static one-to-one mapping:

  • All messages to #channel go to !
  • All messages from ! go to #channel.
  • All PMs between and Bob go to ! and the respective PM on IRC.

In order to make PMs secure, we need to limit who can access the room. This is done by making the Matrix PM room “invite-only”. This can cause problems though if the Matrix user ever leaves that room: they won’t be able to ever re-join! The IRC bridges get around this by allowing Matrix users to replace their dedicated PM room with a new room, and by checking to make sure that the Matrix user is inside the room before sending messages.

Then you have problem of “ownership” of rooms. Who should be able to kick users in a bridged room? There are two main scenarios to consider:

  • The IRC channel has existed for a while and there are existing IRC channel operators.
  • The IRC channel does not exist, but there are existing Matrix moderators.

In the first case, we want to defer ownership to the channel operators. This is what happens by default for all bridged IRC channels on The Matrix users have no power in the room, and are at the mercy of the IRC channel operators. The channel operators are represented by virtual Matrix users in the room. However, they do not have any power level: they are at the same level as real Matrix users. Why? The bridge does this because, unlike IRC, it’s not possible in Matrix to bring a user to the same level as yourself (e.g +o), and then downgrade them back to a regular user (e.g. -o). Instead, the bridge bot itself acts as a custodian for the room, and performs privileged IRC operations (topic changing, kickbans, etc) on the IRC channel operator’s behalf.

In the second case, we want to defer ownership to the Matrix moderators. This is what happens when you “provision a room” in Matrix. The bridge will PM a currently online channel operator and ask for their permission to bridge to Matrix. If they accept, the bridge is made and the power levels in the pre-existing Matrix room are left untouched, giving moderators in Matrix control over the room. However, this power doesn’t extend completely to IRC. If a Matrix moderator grants moderator powers to another Matrix user, this will not be mapped to IRC. Why? It’s not possible for the bridge to give chanops to any random user on any random IRC channel, so it cannot always honour the request. This relies on the humans on either side of the bridge to communicate and map power accordingly. This is done on purpose as there is no 100% perfect mapping between IRC powers and Matrix powers: it’s always going to need to compromise which only a human can make.

Finally, there is the problem of one-to-many mappings. It is possible to have two Matrix rooms bridged to the same IRC channel. The problem occurs when a Matrix user in one room speaks. The bridge can easily map that to IRC, but unless it also maps it back to Matrix, the message will never make it to the 2nd Matrix room. The bridge cannot control/puppet the Matrix user who spoke, so instead it creates a virtual Matrix user to represent that real Matrix user and then sends the message into the 2nd Matrix room. Needless to say, this can be quite confusing and we strongly discourage one-to-many mappings for this reason.

Mapping Messages

Mapping Matrix messages to IRC is rather easy for the most part. Messages are passed from the Homeserver to the bridge via the AS API, and the bridge sends a textual representation of the message to IRC using the IRC connection for that Matrix user. The exact form of the text for images, videos and long text can be quite subjective, and there is inevitably some data loss along the way. For example, you can send big text headings, tables and lists in Matrix, but there is no equivalent on IRC. Thankfully, most Matrix users are sending the corresponding markdown and so the formatting can be reasonably preserved by just sending the plaintext (markdown) body.

Mapping IRC messages to Matrix is more difficult: not because it’s hard to represent the message in Matrix, but because of the architecture of the bridge. The bridge maintains separate connections for each Matrix user. This means the bridge might have, for example, 5 users (and hence connections) on the same channel. When an IRC user sends a message, the bridge gets 5 copies of the message. How does the bridge know:

  • If the message has already been sent?
  • If the message is an intentional duplicate?

The IRC protocol does not have message IDs, so the bridge cannot de-duplicate messages as they arrive. Instead, it “nominates” a single user’s connection to be responsible for delivering messages from that channel. This introduces another problem though. Long-lived TCP connections are fickle things, and can fail without any kind of visible warning until you try to send bytes down it. If a user’s connection drops, another user needs to take over responsibility for delivering messages. This is what the “IRC Event Broker” class does. It allows users to “steal” messages if the bridge has any indication that the connection in charge has dropped. This technique has worked well for us, and gives us the ability to have more robust connections to the channel than with one TCP connection alone.

Admin Rooms

Admin rooms are private Matrix rooms between a real Matrix user and the bridge bot. It allows the Matrix user to control their connection to IRC. It allows:

  • The IRC nick to be changed.
  • The ability to issue /whois commands.
  • The ability to bypass the bridge and send raw IRC commands directly down the TCP connection (e.g. MODE commands).
  • The ability to save a NickServ password for use when the bridge reconnects you.
  • The ability to disconnect from the network entirely.

To perform these actions, Matrix users send a text message which starts with a command name, e.g !whois $ARG. Like all commands, you expect to get a reply once you’ve issued it. However, IRC makes this extremely difficult to do. There is no request/response pair like there is with HTTP requests. Instead, the IRC server may:

  • Ignore the request entirely.
  • Send an error you’re aware of (in the RFC/most servers)
  • Send some information which can be assumed to indicate success.
  • Send an error you’re unaware of.
  • Send some information which sometimes indicates success.

This makes it very difficult to know if a request succeeded or failed, and I’ll go into more detail in the next post which focuses on problems we’ve encountered when developing the IRC bridge. This room is also used to inform the Matrix user about general information about their IRC connection, such as when their connection has been lost, or if there are any errors (e.g. “requires chanops to do this action”). The bridge makes no effort to parse these errors, because it doesn’t always know what caused the error to happen.


Developing a comprehensive IRC bridge is a very difficult task. This post has outlined a few of the ways in which we’ve designed our bridge, and some of the general problems in this field. The bridge is constantly improving as we discover new edge cases with the plethora of IRCd implementations out there. The next post will look at some of these edge cases and look back at some previous outages and examine why they occurred.

New bridged IRC network: GIMPNet

Hey everyone! As of last week, we are now bridging (GIMPNet) for all your GTK+/GNOME needs! It’s running a bleeding-edge version of the IRC bridge which supports basic chanops syncing from IRC to Matrix. This means that if an IRC user gives chanops to a Matrix connection, the bridge will give that Matrix user moderator privileges in the room, allowing them to set the room topic/avatar/alias/etc! We hope this will make customising Matrix-bridged rooms a lot easier.

For a more complete list of current and future bridged IRC networks, see the official wishlist.