Welcome to XMTP protocol development! We recommend you skim this guide as a quickstarter, and then use it as a reference to come back to whenever you need to go deeper. Later in your journey, if there's ever a feature or concept you don't understand, please ping the team to add a link to the guide!
Here we describe each component, as well as providing links to the interface boundaries between components, which is the key to getting a high level understanding. Make sure to follow the README in each relevant repo if you want to set it up.
- Centralized repo: https://github.com/xmtp/xmtp-node-go
- Decentralized repo: https://github.com/xmtp/xmtpd
This is the backend, currently a set of centralized nodes operated by Ephemera, sharing a Postgres instance. The current API interface is captured in the protos repo, mostly here and here. A simple mental model of the backend is a pub/sub system, with append-only, ordered lists of payloads categorized by topic and indexed by cursors.
A trustless, decentralized replacement is currently under development. More information can be found in the explainer and XIP.
- Libxmtp repo: https://github.com/xmtp/libxmtp
- OpenMLS repo (fork): https://github.com/xmtp/openmls
This is the core client SDK. It fetches and publishes payloads from the backend, encrypting and decrypting them using OpenMLS, and storing them in the database before exposing results to the native SDK's via bindings.
It's recommended to start by understanding envelope types and intents, before moving onto deeper level concepts in the Core Concepts section below.
This is simply a library in the libxmtp repo for validating payloads that is used in both the backend and client.
- iOS repo: https://github.com/xmtp/xmtp-ios
- Android repo: https://github.com/xmtp/xmtp-android
- React Native repo: https://github.com/xmtp/xmtp-react-native
- JS (browser/node.js) repo: https://github.com/xmtp/xmtp-js
- Push notif server example: https://github.com/xmtp/example-notification-server-go
This is a set of SDK's for each native platform. The interface to Rust is described in the bindings, and the user interface is described in the docs.
- Convos (iOS) repo: https://github.com/ephemeraHQ/convos-ios
- xmtp.chat (web) repo: https://github.com/xmtp/xmtp-js/tree/main/apps/xmtp.chat
- Agents repo: https://github.com/ephemeraHQ/xmtp-agent-examples
These are open-source reference apps and bots developed by Ephemera. We recommend downloading Convos from the App store and loading xmtp.chat in your browser to get a feel for the types of features you can build on top of XMTP. Please ping a team member so you can DM with them in the app and get added to a developer's group. Outside of Ephemera, there are a wide variety of apps and agents from an array of organizations built on XMTP - please ask for a list, and experiment with them too.
The XMTP protocol can be understood via three core concepts:
- MLS protocol
- Go through 'libxmtp' section above
- Intuition and formal talk: Understand the general goals and mechanisms
- Overview: Understand how the 'authentication service' and 'delivery service' plug into the protocol, browse through other pages as needed
- OpenMLS library: Familiarize yourself with common operations
- MLS spec: Use as a reference for specifics later, read it end-to-end if dedicated (or feed it into an AI and chat about it)
- Identity protocol (authentication service)
- Message delivery protocol (delivery service)
Once the core concepts are well-understood, there is a vast number of additional topics to explore, non-exhaustive list below (please add links!):
- Protocol:
- Content types
- Device sync and consent
- DM stitching
- MLS group context and mutable metadata
- Automated fork recovery
- Disappearing messages
- Push notifications
- Post-quantum security
- Bots and agents
- SDK release process and versioning
- Performance testing
- Decentralization:
- Payer portal
- Migration