Skip to main content

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us