You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
XMTP's identity model includes an inbox ID and its associated identities and installations.
4
+
5
+
With an inbox ID at its core, instead of a specific wallet address or other identity value, the model is designed for extensibility. A user can associate any number of identity types to their inbox ID and use them to send and receive messages. This gives the user the freedom to add and remove identity types as they naturally change over time, while maintaining the same stable inbox destination for their messages.
6
+
7
+
8
+
9
+
The identity model also allows XMTP to support any identity type, as long as it can produce a verifiable cryptographic signature. Currently supported identity types include Ethereum EOAs, Ethereum smart contract wallets, and passkeys.
10
+
11
+
## Inbox ID
12
+
13
+
An **inbox ID** is a user's stable destination for their messages. Their inbox ID remains constant even as they add or remove [identities](#identity) and [installations](#installations).
14
+
15
+
The inbox ID is derived from the hash of the first associated wallet address and a nonce and acts as an opaque identifier that apps use for messaging.
16
+
17
+
## Identity
18
+
19
+
An **identity** is an addressable account that can be associated with an inbox ID. Each identity has a type (like EOA, smart contract wallet, or passkey) and an identifier (like an Ethereum address).
20
+
21
+
- Multiple identities can be linked to a single inbox ID
22
+
- The first identity becomes the **recovery identity** with special privileges
23
+
- All messages sent to any associated identity are delivered to the same inbox
24
+
- Any identity that can produce a verifiable cryptographic signature can be supported by XMTP
25
+
26
+
## Installation
27
+
28
+
An **installation** represents a specific app installation that can access an inbox. Each installation has its own cryptographic keys for signing messages and participating in conversations.
29
+
30
+
- Generated automatically when `Client.create()` is called for the first time with an identity that hasn't been used with XMTP before
31
+
- Multiple installations can access the same inbox (up to 10)
32
+
- Installations can be revoked by the recovery identity
33
+
34
+
## Relationships
35
+
36
+
**One inbox ID** → **multiple identities**: Users can receive messages as any of their identities, all flowing to the same inbox
37
+
38
+
```
39
+
Inbox ID (stable destination for messages)
40
+
├── Identity 1 (recovery identity, first identity added to an inbox)
41
+
├── Identity 2 (EOA wallet)
42
+
├── Identity 3 (SCW wallet)
43
+
└── Any identity that can produce a verifiable cryptographic signature
44
+
```
45
+
46
+
**One identity** → **multiple installations**: Users can access their messages from different apps on the same or different devices
47
+
48
+
```
49
+
Each identity can authenticate new installations:
50
+
├── Installation A (phone app)
51
+
├── Installation B (web app)
52
+
├── Installation C (desktop app)
53
+
└── Up to 10 installations
54
+
```
55
+
56
+
## Identity actions
57
+
58
+
To learn how to build agents with identity actions, see [Manage XMTP inboxes, identities, and installations](/agents/core-messaging/agent-installations).
59
+
60
+
To learn how to build chat apps with identity actions, see [Manage XMTP inboxes, identities, and installations](/chat-apps/core-messaging/manage-inboxes).
Copy file name to clipboardExpand all lines: docs/pages/protocol/overview.mdx
+56-30Lines changed: 56 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,34 +1,70 @@
1
1
# XMTP protocol overview
2
2
3
-
XMTP is a decentralized messaging protocol that enables secure, end-to-end encrypted communication between blockchain addresses. This section covers the technical foundations and implementation details of how XMTP works under the hood.
3
+
XMTP is a decentralized messaging protocol that enables secure, end-to-end encrypted communication between any identities that can produce a verifiable cryptographic signature.
4
4
5
-
## Architecture fundamentals
5
+
XMTP implements [Messaging Layer Security](https://messaginglayersecurity.rocks/) (MLS), which is designed to operate within the context of a messaging service. As the messaging service, XMTP needs to provide two services to facilitate messaging using MLS:
6
6
7
-
With XMTP, messages are routed through **[topics](/protocol/topics)**, which are unique addresses that identify conversation channels. Messages are packaged as **[envelope types](/protocol/envelope-types)** that contain the actual message data plus metadata for routing and processing.
7
+
- An [authentication service](https://messaginglayersecurity.rocks/mls-architecture/draft-ietf-mls-architecture.html#name-authentication-service)
8
+
- A [delivery service](https://messaginglayersecurity.rocks/mls-architecture/draft-ietf-mls-architecture.html#name-delivery-service)
8
9
9
-
The protocol prioritizes **security** through advanced cryptographic techniques, delivering end-to-end encryption for both 1:1 and group conversations. To learn more, see XMTP's [security properties](/protocol/security) and how [wallet signatures](/protocol/signatures) authenticate users.
10
+
This section covers the elements of XMTP that provide these services.
10
11
11
-
## Group messaging mechanics
12
+
:::info[Who should read these docs]
12
13
13
-
For group conversations, XMTP introduces sophisticated state management:
14
+
This protocol documentation is designed for:
14
15
15
-
-**[Epochs](/protocol/epochs)** represent the cryptographic state of a group at any point in time. Each group operation (like adding members) creates a new epoch with fresh encryption keys. This concept comes from [Messaging Layer Security](https://messaginglayersecurity.rocks/), which XMTP builds upon.
16
+
- Protocol contributors working on XMTP's core implementation
- Anyone curious about the technical details behind XMTP's messaging
16
19
17
-
-**[Intents](/protocol/intents)** provide reliable state management through an internal bookkeeping system that handles retries, crashes, and race conditions when applying group changes.
20
+
For most developers, the [Build chat apps](/chat-apps/intro/get-started) and [Build agents](/agents/get-started/build-an-agent) sections provide the practical guidance needed to build with XMTP.
21
+
22
+
:::
23
+
24
+
## Encryption
25
+
26
+
The encryption elements are mainly defined by MLS, with some additions by XMTP. To learn more, see:
27
+
28
+
-[Security](/protocol/security)
29
+
30
+
XMTP and MLS prioritize security, privacy, and message integrity through advanced cryptographic techniques, delivering end-to-end
31
+
encryption for both 1:1 and group conversations
32
+
33
+
-[Epochs](/protocol/epochs)
34
+
35
+
Represent the cryptographic state of a group at any point in time. Each group operation (like adding members) creates a new epoch with fresh encryption keys
36
+
37
+
-[Envelope types](/protocol/envelope-types)
38
+
39
+
Messages are packaged as envelope types that contain the actual message data plus metadata for routing and processing.
40
+
41
+
## Identity
42
+
43
+
The identity elements are mainly defined by XMTP. To learn more, see:
44
+
45
+
-[Inboxes, identities, and installations](/protocol/identity)
46
+
47
+
The identity model includes an inbox ID and its associated identities and installations.
18
48
19
-
-**[Cursors](/protocol/cursors)** enable efficient message synchronization by tracking where each client left off when fetching new messages.
49
+
-[Wallet signatures](/protocol/signatures)
20
50
21
-
## Key concepts
51
+
Authenticate users using verifiable cryptographic signatures.
22
52
23
-
| Concept | Purpose | Key benefit |
24
-
|---------|---------|-------------|
25
-
|[Security](/protocol/security)| End-to-end encryption | Privacy and message integrity |
26
-
|[Topics](/protocol/topics)| Message routing and addressing | Efficient pub/sub architecture |
27
-
|[Envelope types](/protocol/envelope-types)| Message format and structure | Standardized communication protocol |
28
-
|[Epochs](/protocol/epochs)| Group cryptographic state | Key rotation and post-compromise security |
29
-
|[Intents](/protocol/intents)| Reliable group operations | Consistency despite network issues |
The delivery elements are mainly defined by XMTP. To learn more, see:
56
+
57
+
-[Topics](/protocol/topics)
58
+
59
+
Messages are routed through topics, which are unique addresses that identify conversation channels.
60
+
61
+
-[Cursors](/protocol/cursors)
62
+
63
+
Enable efficient message synchronization by tracking where each client left off when fetching new messages.
64
+
65
+
-[Intents](/protocol/intents)
66
+
67
+
Provide reliable groupstate management through an internal bookkeeping system that handles retries, crashes, and race conditions when applying group changes.
-**Anyone curious** about the technical details behind XMTP's messaging
53
-
54
-
For most developers, the [Build chat apps](/chat-apps/intro/get-started) and [Build agents](/agents/get-started/build-an-agent) sections provide the practical guidance needed to build with XMTP.
Used for quantum-resistant key encapsulation in Welcome messages. XWING is a hybrid post-quantum KEM that combines conventional cryptography with [ML-KEM](https://csrc.nist.gov/pubs/fips/203/final) (the NIST-standardized post-quantum component), providing protection against future quantum computer attacks while maintaining current security standards.
102
+
103
+
## FAQ about messaging security
104
+
105
+
1.**Can XMTP read user messages?**
106
+
107
+
No, messages are encrypted end-to-end. Only participants in a conversation have the keys to decrypt the messages in it. Your app cannot decrypt messages either.
108
+
109
+
2.**How does XMTP's encryption compare to Signal or WhatsApp?**
110
+
111
+
XMTP provides the same security properties (forward secrecy and post-compromise security) as Signal and WhatsApp, using the newer, more efficient MLS protocol.
112
+
113
+
3.**Can others see who users are messaging with?**
114
+
115
+
No. Message recipients are encrypted, so even network nodes cannot see who is messaging whom. Nodes can only see timing and size of encrypted messages.
116
+
117
+
4.**What happens if a user loses access to their wallet?**
118
+
119
+
They'll need to start new conversations from their new wallet. Messages sent to their old wallet address can't be decrypted without access to that wallet.
120
+
121
+
5.**Are group messages as secure as direct messages?**
122
+
123
+
Yes, MLS provides the same security properties for both group and direct messages. In fact, MLS is particularly efficient for group messaging.
124
+
125
+
6.**What if a user suspects their wallet is compromised?**
126
+
127
+
Due to forward secrecy, even if someone gains access to their wallet, they can't read their past messages. They should start using a new wallet immediately - this ensures attackers won't be able to read future messages either.
128
+
129
+
7.**How does encryption work across different XMTP apps?**
130
+
131
+
All XMTP apps use the same MLS protocol, ensuring consistent encryption across the ecosystem regardless of which app users choose.
0 commit comments