Skip to content
XMTP status

Envelope types with XMTP

This document covers envelope types that clients can publish to XMTP APIs. These are the top-level message structures that can be sent and received through the XMTP network. This information is primarily useful for:

  • Developers contributing to the XMTP protocol itself
  • Understanding XMTP internals and debugging
  • Reading XMTP Improvement Proposals (XIPs)

The envelope types described here are handled automatically by XMTP SDKs and rarely need direct interaction from app developers.

For app development, you'll typically work with content types instead. Content types define how your app's messages are structured and encoded (text, attachments, reactions, etc.) and are what you'll use in your day-to-day development.

Overview

XMTP supports several envelope types that clients can publish to the network:

  • Group message envelopes: Contain MLS protocol messages (application messages and commits)
  • Welcome message envelopes: Bootstrap new members into existing groups
  • Key package envelopes: Register cryptographic credentials for user installations
  • Identity update envelopes: Verify and authenticate user identities

These envelope types work together to enable secure group communication with forward secrecy and post-compromise security.

Note: In the MLS context, "group" refers to any collection of clients that share cryptographic state, which includes both direct message (1:1) or group chat conversations.

Group message envelope

A group message envelope contains an MLS protocol message that can be either an application message or a commit message. This is the primary envelope type used for day-to-day communication.

Application messages

Application messages represent the actual content that users send to each other, including:

  • Text messages
  • Attachments
  • Reactions
  • Read receipts
  • On-chain transaction references
  • Custom content types

Application messages are:

  • Encrypted using the group's shared secrets
  • Authenticated with sender signatures
  • Encoded using XMTP content types
  • Sent on the groupMessage topic

Commit messages

Commit messages update the group's cryptographic state, membership, and permissions. While technically a single message type, commit messages serve many different purposes.

Understanding commit messages is especially helpful when debugging and understanding your app's user experience. For example:

  • Different commit types help explain why certain messages appear in logs
  • Some commits happen invisibly, while others are tied to user actions

User-initiated commits

  • Add member commits: When a user explicitly adds someone to a group
  • Remove member commits: When a user removes someone from a group
  • Update metadata commits: When a user changes group name, description, or permissions
  • Update permissions commits: When a user modifies group permission settings

System-initiated commits

  • Key update commits: Automatically generated when a new member joins before sending their first message
  • Missing member commits: Triggered when the system detects someone is missing from the group
  • Scheduled commits: Periodic commits for security maintenance

MLS protocol commits

  • Update path commits: Generated by the MLS protocol for key rotation and security
  • External sender commits: For handling external participants

For more information about MLS commits, see RFC 9420 Section 12.4.

Welcome message envelope

A welcome message envelope bootstraps a new member into an existing group. The welcome is dependent on the newcomer's key package and provides the new member with the current state of the group after application of a commit message.

A welcome message contains:

  • Group context information
  • Encrypted group secrets
  • Tree structure for the group
  • Confirmation tags for epoch verification

If decryption fails due to an outdated or missing key package, the SDK automatically fetches the latest package and retries.

Key package envelope

A key package envelope registers cryptographic credentials for a user installation. XMTP SDKs create and upload fresh key packages behind the scenes when an installation is initialized or rotated.

Think of a key package as a calling card for an installation that says: here's how to encrypt to me, here's how long this card is valid, and it's signed so you can trust it.

A key package contains:

  • Public key for encrypting welcome messages
  • Signature key for authentication
  • Capabilities (supported protocol version, cipher suites, lifetime, etc.)
  • Credential for identity verification
  • Content of the leaf node representing this client

Group members cache key packages to authenticate future handshakes and welcome material, enabling asynchronous addition of clients to groups.

When an app inspects a group member, the SDK provides a PublicIdentity object containing the decoded fields, allowing apps to display identity information or check if the key package has expired.

Identity update envelope

An identity update envelope verifies and authenticates a user identity across the network. It is signed by the user's identity and verifiable by peers.

Identity update envelopes enable group members to rotate their signature or HPKE keys while preserving group continuity and authenticity.

They handle:

  • Linking an installation to an XMTP inbox
  • Key rotation and revocation
  • Linking multiple devices (though history sync is used to synchronize data between those devices)

Identity update messages are stored permanently to ensure continuity of trust and identity verification.