Skip to main content

Invitation and message encryption with XMTP

All XMTP invitations and messages are encrypted.

XMTP V2 invitation and message encryption​

This section describes how invitation and message encryption work for XMTP V2. Only client apps with XMTP client SDK >=v7.0.0 can use XMTP V2.

To learn more about invitations and messages, see XMTP V2 topics and message presentation flow.

To learn about how invitation and message encryption work in XMTP V1, see XMTP V1 message encryption.

Invitation encryption​

A client app encrypts and decrypts invites 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)

The following sequence diagram dives a bit deeper into the flow and illustrates how a client app creates and uses these artifacts to encrypt an invite sent from Amal to Bola:

Diagram showing the sequence of steps a client app takes to use a private key, public key, shared secret, and encryption key to encrypt an invite before submitting it to the XMTP network.

Likewise, this sequence diagram illustrates the invite decryption process:

Diagram showing the sequence of steps a client app takes to retrieve an invitation from the XMTP network and use a private key, public key, shared secret, and encryption key to decrypt the invitation.

Message encryption​

A client app signs, verifies, encrypts, and decrypts messages using the following artifacts:

  • Pre-key (sender)
  • Identity public key (sender)
  • Shared secret (per invitees to a conversation)
  • Encryption key (per invitees to a conversation)

On a related note, the encrypted message is signed by the sender using their private key. Upon decryption but before presentation to the recipient, the client app uses the sender's public key from the message header to verify the sender of the message.

The following sequence diagram dives a bit deeper into the flow and illustrates how a client app creates and uses these artifacts to encrypt and sign a message sent from Amal to Bola:

Diagram showing the sequence of steps a client app takes to use a shared secret to generate an encryption key and use it to encrypt a message before submitting it to the XMTP network.

Likewise, this sequence diagram illustrates the message decryption and message verification process:

Diagram showing the sequence of steps a client app takes to use a shared secret to generate an encryption key and use it to decrypt a message before presenting it to a user.

XMTP V1 message encryption​

This section describes how message encryption works for XMTP V1. To understand whether a client app will use XMTP V1 or V2, see Determining whether to use XMTP V2 or V1 topics.

With XMTP V1 message encryption, 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 for XMTP V1:

Animation showing the flow of a user sending a message to another user, including details of how the sender's client app encrypts and submits the message to the XMTP network, how an XMTP node relays the message to other nodes, and how the recipient's client app retrieves the message from the network, decrypts it, and delivers it to the recipient.

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:

Diagram showing the sequence of steps a client app takes to use a private key, public key, shared secret, and encryption key to encrypt a message before submitting it to the XMTP network.

Likewise, this sequence diagram illustrates the message decryption process:

Diagram showing the sequence of steps a client app takes to retrieve a message from the XMTP network, use a private key, public key, shared secret, and encryption key to decrypt them message, and then deliver the message to a user.

Was the information on this page helpful?
powered by XMTP

On this page