Architectural overview of XMTP
This topic provides an introduction to the architecture of XMTP (Extensible Message Transport Protocol) and how it supports messaging between blockchain accounts.
You can use this information to get an overview of how XMTP works and how building with XMTP can fit into your architecture and environment.
At the most basic level, the architecture of XMTP includes three layers:
The network layer provides the XMTP network which is comprised of nodes (computers) running network client software. The primary responsibilities of the XMTP network and nodes are to:
- Relay messages to other nodes and to storage
- Make messages available for retrieval by client apps built with XMTP
- Store and advertise public key bundles for XMTP identities
- Store encrypted private key bundles for XMTP identities
- Bootstrap newly joined XMTP nodes
Diving a bit deeper into the XMTP network, this diagram illustrates key components of the network topology:
At this time, XMTP Labs runs all nodes in the XMTP network. XMTP Labs aims to publish a phased decentralization roadmap in Fall 2022.
The XMTP network has no security perimeter, enabling any node running XMTP network client software to participate in the network. Currently, the network client software is closed source and all nodes are operated by XMTP Labs.
Every XMTP node:
- Has a bootstrapping service that advertises information about all of the nodes it’s connected to, enabling newly joined nodes to connect to every other node in the network
- Connects to every other node, forming a peer-to-peer network
- Connects to a data store
- Relays messages and key bundles to other nodes
- Stores and advertises public key bundles for XMTP identities
- Stores encrypted private key bundles for XMTP identities
- Stores messages sent by XMTP identities
- Has a private load balancer and connects to a single public load balancer
Here’s a high-level view of how client apps built with XMTP submit and retrieve messages using the XMTP network:
Network storage and message relay
The XMTP network uses pub/sub topics to relay and store messages and key bundles within the network. Here's an overview of the topics the network uses:
- Private store topic
A developer building an app with XMTP can choose to store their users' private key bundles locally or encrypted on the XMTP network. When required by a client app, the XMTP network uses a private store topic to store a user's private key bundle.
- Contact topic
The XMTP network uses a contact topic to store a user’s public key bundle. The network advertises this public key bundle to enable other users to contact the user.
- Intro topic
The XMTP network uses an intro topic to store the first message sent between two participants (blockchain accounts). This enables client apps to know that messages exist in a given direct message topic.
- Direct message topic
The XMTP network uses a direct message topic to store messages sent between two participants. The direct message topic is shared by the two participants.
This diagram illustrates how these XMTP network topics are created and work together to enable a client app to deliver messages to a user:
In this flow, the client app:
- Retrieves Bola’s private key bundle from the network. If one doesn’t exist, it creates it and stores it encrypted on the network in a private store topic, or locally.
- If one doesn't already exist, stores Bola’s public key bundle on the network in a contact topic, so others can message Bola.
- Retrieves Bola’s intro topic to see which conversations they have.
- Retrieves the messages between Bola and Amal from their direct message topic.
- Uses Bola’s private key and Amal’s public key to create a shared secret. Uses the shared secret to create an encryption key to decrypt Amal’s message and present it to Bola.
For more details, see Message encryption and decryption.
Next, let’s look at the client layer and how apps connect to the XMTP network and send and receive encrypted messages.
The client layer consists of XMTP user clients embedded in client apps built with the XMTP SDK. The client layer’s main responsibilities are to:
- Create blockchain account-based XMTP identities, including public and private key bundles, and submit them to the network for storage
- Encrypt and decrypt messages
- Submit and retrieve messages from the XMTP network
- Encode and decode message content types To learn more, see Content types.
Message encryption and decryption
All XMTP messages are encrypted. A client app encrypts and decrypts messages using the following artifacts:
- Public key bundle (per user)
- Private key bundle (per user)
- Shared secret (per sender and recipient pair)
- Encryption key (per sender and recipient pair)
Here’s a high-level overview of the message encryption and decryption flow:
The following sequence diagram dives a bit deeper into the flow and illustrates how a client app creates and uses these artifacts to encrypt a message:
Likewise, this sequence diagram illustrates the message decryption process:
The app layer consists of client apps built with the XMTP SDK.
A developer can provide messaging between blockchain accounts in their app by building with the XMTP SDK. When a developer builds with the XMTP SDK, their app embeds an XMTP user client, which handles XMTP network interactions required to enable their users to send and receive messages.
With XMTP network interactions handled by an XMTP client, developers can focus on the user-related aspects of building client apps, such as:
- User acquisition
- User interface
- User identity metadata
- Inbox filtering
To learn about one developer's approach, see Truths Not Spoofs.
- Custom content types
To learn more, see Content types.