xmtp_mls

XMTP core MLS Implementation on top of openmls

Overview

The xmtp_mls crate is the core implementation of XMTP’s Messaging Layer Security (MLS) protocol. It provides the primary client interface for creating and managing encrypted group conversations, handling identity management, and syncing messages across devices.

Installation

[dependencies]
xmtp_mls = "*"

Key Exports

The crate exports the following modules and types from lib.rs:

Client · struct

The main client interface for XMTP MLS operations. Parameterized by context type to allow different API/DB combinations.

Network · enum

Represents the network the client connects to:

• Local(&'static str) - Local development network
• Dev - Development network (default)
• Prod - Production network

GroupCommitLock · struct

A manager for group-specific semaphores to prevent concurrent modifications to the same group.

MlsGroupGuard · struct

A guard that releases the group semaphore when dropped, ensuring proper lock cleanup.

Core Modules

builder

Provides ClientBuilder for fluent construction of clients with identity, API, and storage configuration.

client

Contains the main Client<Context> type with methods for:

• Creating and managing groups
• Sending and receiving messages
• Identity management
• Device synchronization

context

Defines XmtpMlsLocalContext which centralizes dependencies:

• API client
• Storage/database
• Identity manager
• Group locks
• Event streams

groups

Group conversation management including:

• Creating groups
• Adding/removing members
• Sending messages
• Group permissions and metadata
• DM (direct message) support

identity

Identity and authentication:

• Installation identities
• Key package management
• Credential verification

messages

Message handling:

• Encoding/decoding messages
• Content types
• Message delivery status
• Message enrichment

subscriptions

Real-time event subscriptions:

• New messages
• Group updates
• Identity changes

Main Types and Traits

Client<Context> · struct

Generic client parameterized by context type. Provides all MLS operations.

Key Methods:

• create_group() - Create a new group conversation
• create_dm() - Create a direct message conversation
• group() - Get an existing group
• conversations() - List all conversations
• sync() - Synchronize with network

MlsGroup · struct

Represents a group conversation.

Key Methods:

• send_message() - Send a message to the group
• add_members() - Add members to the group
• remove_members() - Remove members from the group
• messages() - Retrieve messages
• sync() - Sync group state

ClientBuilder · struct

Builder pattern for constructing clients.

Methods:

• api_client() - Set API client
• identity() - Set identity
• store() - Set storage
• build() - Construct the client

Usage Examples

Creating a Client

use xmtp_mls::{Client, Network};
use xmtp_mls::builder::ClientBuilder;

// Create a new client with builder pattern
let client = ClientBuilder::new()
    .api_client(api_client)
    .identity(wallet)
    .store(db_connection)
    .build()
    .await?;

Creating a Group

// Create a new group conversation
let group = client
    .create_group(
        None, // no permissions override
        GroupMetadataOptions::default(),
    )
    .await?;

// Add members to the group
group.add_members(vec!["inbox_id_1", "inbox_id_2"]).await?;

Sending Messages

// Send a text message
let message_id = group
    .send_message(b"Hello, world!")
    .await?;

// Send with options
group
    .send_message_with_opts(
        b"Important message",
        SendMessageOpts::default()
    )
    .await?;

Receiving Messages

// Get all messages
let messages = group.messages(None).await?;

// Process messages
for message in messages {
    println!("From: {}", message.sender_inbox_id);
    println!("Content: {:?}", message.decrypted_message_bytes);
}

Subscribing to Events

use tokio_stream::StreamExt;

// Subscribe to new messages
let mut stream = client.stream_messages().await?;

while let Some(message) = stream.next().await {
    println!("New message: {:?}", message);
}

Features

test-utils · feature

Utilities for testing, including mock implementations and test helpers.

bench · feature

Benchmarking utilities and performance testing tools.

d14n · feature

Decentralized API support.

v3 · feature

Version 3 protocol support.

dev · feature

Development configuration and utilities.

Error Handling

The crate uses structured error types:

use xmtp_mls::client::ClientError;

match result {
    Ok(value) => { /* success */ }
    Err(ClientError::Storage(e)) => { /* handle storage error */ }
    Err(ClientError::Api(e)) => { /* handle API error */ }
    Err(e) => { /* handle other errors */ }
}

Platform Support

• Native (Linux, macOS, Windows)
• WebAssembly (WASM)
• iOS (via FFI bindings)
• Android (via FFI bindings)

Dependencies

Key dependencies include:

• openmls - MLS protocol implementation
• xmtp_db - Storage layer
• xmtp_id - Identity management
• xmtp_proto - Protocol definitions
• xmtp_cryptography - Cryptographic primitives