Struct MlsGroup 

pub struct MlsGroup<Context> {
    pub group_id: GroupId,
    pub dm_id: Option<String>,
    pub conversation_type: ConversationType,
    pub created_at_ns: i64,
    pub context: Context,
    /* private fields */
}

An LibXMTP MlsGroup NOTE: The Eq implementation compares GroupId, so a dm group with the same identity will be different. the Hash implementation hashes the GroupId

Fields

group_id: GroupId

dm_id: Option<String>

conversation_type: ConversationType

created_at_ns: i64

context: Context

Implementations

impl<Context: XmtpSharedContext> MlsGroup<Context>

pub fn restore_from_archive( context: &Context, save: &GroupSave, ) -> Result<bool, GroupError>

Apply one archive group element. Returns whether storage changed.

impl<Context> MlsGroup<Context>

where Context: XmtpSharedContext,

Represents a group, which can contain anywhere from 1 to MAX_GROUP_SIZE inboxes.

This is a wrapper around OpenMLS’s MlsGroup that handles our application-level configuration and validations.

pub fn new( context: Context, group_id: GroupId, dm_id: Option<String>, conversation_type: ConversationType, created_at_ns: i64, ) -> Self

pub fn new_cached( context: Context, group_id: &GroupId, ) -> Result<(Self, StoredGroup), StorageError>

Creates a new group instance from the database. Validate that the group exists in the DB before constructing the group.

Returns

Returns the Group and the stored group information as a tuple.

pub fn find( context: &Context, args: GroupQueryArgs, ) -> Result<Vec<Self>, MlsStoreError>

Query for groups with optional filters

Filters:

• allowed_states: only return groups with the given membership states
• created_after_ns: only return groups created after the given timestamp (in nanoseconds)
• created_before_ns: only return groups created before the given timestamp (in nanoseconds)
• limit: only return the first limit groups

pub fn load_by_id( context: &Context, group_id: &GroupId, ) -> Result<Self, MlsStoreError>

Look up a group by its ID

Returns a MlsGroup if the group exists, or an error if it does not

pub async fn membership_capabilities( &self, ) -> Result<GroupMembershipCapabilities, GroupError>

Snapshot this group’s membership capabilities: the extension types in the group context, plus the extension types each member installation advertises.

This reports raw capability facts rather than answers — callers filter it to whatever question they care about. For the proposal (app-data-dictionary) migration specifically, a caller checks for MlsExtensionType::AppDataDictionary in context_extensions (already migrated?) and in each installation’s supported_extensions (eligible / who is blocking?).

Every installation’s capabilities — the local one included — come from its latest published key package, not its in-group leaf node: a leaf is frozen when the installation joins and is never updated, so it would understate a client that upgraded afterward. An installation whose key package has not been published or fails verification is reported with capabilities_known == false and an empty extension list, so callers can distinguish “unknown” from “advertises nothing”. Transient failures (network, auth, db) surface as an Err rather than masquerading as unknown capabilities.

pub fn validate_key_packages_support_proposals( &self, key_packages: &[KeyPackage], ) -> Result<(), GroupError>

Validate that key packages support the AppData dictionary group-context extension. A leaf that advertises ExtensionType::AppDataDictionary in its standard MLS Capabilities can join a migrated group and receive standalone AppDataUpdate proposals.

impl<Context> MlsGroup<Context>

where Context: XmtpSharedContext,

pub async fn add_members_by_identity( &self, account_identifiers: &[Identifier], ) -> Result<UpdateGroupMembershipResult, GroupError>

Add members to the group by account address

An account resolves to an inbox only when the newest state of the inbox the backend names holds it. The add fails with GroupError::AddressNotFound, before any commit, when an account has no such inbox.

If any existing members have new installations that have not been added or removed, the group membership will be updated to include those changes as well.

Returns

• Ok(UpdateGroupMembershipResult): Contains details about the membership changes, including:
  • added_members: list of added installations
  • removed_members: A list of installations that were removed.
  • members_with_errors: A list of members that encountered errors during the update.
• Err(GroupError): If the operation fails due to an error.

pub async fn add_members<S: AsIdRef>( &self, inbox_ids: impl AsRef<[S]>, ) -> Result<UpdateGroupMembershipResult, GroupError>

pub async fn ensure_dm_peer(&self) -> Result<(), GroupError>

Add the DM peer when this DM’s GROUP_MEMBERSHIP lacks it, before a message is queued in the DM.

A creation that stops between storing the DM and adding the peer leaves a DM that holds only its creator. A DM peer can never leave or be removed, so a missing peer always means such an interruption. Await this before queueing a message in a DM: intents publish in queue order, so a message queued before the add is encrypted at an epoch the peer never joins. Does nothing for a group that is not a DM, an inactive DM (such as a restored placeholder), or a DM whose pair does not include this inbox.

Returns Ok when the add is published with a receipt but its processing is not confirmed when the wait ends. That outcome belongs to the add, not to the caller’s message, which is not queued yet. The backend holds the add, and nothing is prepared behind a published state change until its echo is applied (SEND-022), so a message queued next is built at an epoch that holds the peer. Every other failure of the add, including a wait that ends before the add has a receipt, is returned.

pub async fn remove_members_by_identity( &self, account_addresses_to_remove: &[Identifier], ) -> Result<(), GroupError>

Removes members from the group by their account addresses. An account resolves to an inbox only when the newest state of the inbox the backend names holds it; an account with no such inbox is skipped.

Arguments

• client - The XMTP client.
• account_addresses_to_remove - A vector of account addresses to remove from the group.

Returns

A Result indicating success or failure of the operation.

pub async fn remove_members( &self, inbox_ids: &[InboxIdRef<'_>], ) -> Result<(), GroupError>

Removes members from the group by their inbox IDs.

Arguments

• client - The XMTP client.
• inbox_ids - A vector of inbox IDs to remove from the group.

Returns

A Result indicating success or failure of the operation.

pub async fn remove_members_pending_removal(&self) -> Result<(), GroupError>

Removes all members from the group who are currently in the pending removal list.

Only admins and super admins can call this function. Validates permissions, filters out invalid removal requests and performs batch removal of valid pending members.

Returns

• Ok(()) - All valid pending members were successfully removed
• Err(GroupError) - Failed to retrieve metadata, validate permissions or execute removals

pub async fn cleanup_pending_removal_list(&self) -> Result<(), GroupError>

Removes members from the pending removal list who are no longer in the group.

Iterates through all members in the pending removal list, checking each one to see if they’re still in the group. If a member is no longer in the group, they are removed from the pending list. The pending list is refreshed after each removal to ensure we’re working with the most current data.

Returns

• Ok(()) - Successfully processed all pending removal members
• Err(GroupError) - Failed to retrieve data or update the pending list

pub async fn leave_group(&self) -> Result<(), GroupError>

impl<Context> MlsGroup<Context>

where Context: XmtpSharedContext,

pub async fn send_message( &self, message: &[u8], opts: SendMessageOpts, ) -> Result<Vec<u8>, GroupError>

Send a message on this users XMTP Client.

pub async fn publish_messages(&self) -> Result<(), GroupError>

Publish all unpublished messages. This happens by calling sync_until_last_intent_resolved which publishes all pending intents and reads them back from the network.

pub async fn update_installations(&self) -> Result<(), GroupError>

Checks the network to see if any group members have identity updates that would cause installations to be added or removed from the group.

If so, adds/removes those group members

pub fn send_message_optimistic( &self, message: &[u8], opts: SendMessageOpts, ) -> Result<Vec<u8>, GroupError>

Send a message, optimistically returning the ID of the message before the result of a message publish.

In a DM, await Self::ensure_dm_peer first. This method does not add a missing peer, so the peer could never read the message.

pub fn prepare_message_for_later_publish( &self, message: &[u8], should_push: bool, idempotency_key: Option<String>, ) -> Result<Vec<u8>, GroupError>

Prepare a message for later publishing.

Stores the message locally with Unpublished delivery status but does NOT create an intent to publish. Use publish_stored_message to publish later.

Arguments

• message - The message content bytes
• should_push - Whether to send a push notification when publishing
• idempotency_key - Optional caller-supplied key the message id is derived from. Defaults to a random key when None.

Returns the message ID.

In a DM, await Self::ensure_dm_peer first. This method does not add a missing peer, so the peer could never read the message.

pub async fn publish_stored_message( &self, message_id: &[u8], ) -> Result<(), GroupError>

Publish a previously stored message by ID.

Creates an intent for the message and publishes it to the network. Uses the should_push value that was stored with the message. This is a no-op if the message is already published.

Returns an error if the message is not found.

pub fn reject_reserved_stored_transcript_content( &self, message_id: &[u8], ) -> Result<(), GroupError>

Refuse reserved stored content before work that can publish, such as DM repair. Publication rechecks the row under its own transaction.

pub fn delete_message(&self, message_id: Vec<u8>) -> Result<Vec<u8>, GroupError>

Delete a message for everyone.

Only the original sender or a super admin can delete a message. An unsent own message is cancelled: it and its queued sends are removed, nothing is published, and its own id is returned. Otherwise a deletion message is queued and its id returned; the target changes when the deletion’s echo is processed.

In a DM, await Self::ensure_dm_peer first unless the target is an unsent own message. This method does not add a missing peer, so the peer could never read the deletion.

Wire Protocol

The DeleteMessage protobuf encodes message_id as a hex-encoded string for wire transmission, while the database stores message IDs as raw bytes.

pub fn cancel_unsent(&self, message_id: &[u8]) -> Result<bool, GroupError>

Check that this installation may delete message_id, then cancel it when it is this installation’s unsent message. Returns false when the message is not unsent here; Self::delete_message then queues a deletion. A DM caller repairs the peer between the two.

pub fn reject_reserved_transcript_content( message: &[u8], ) -> Result<(), GroupError>

Refuse reserved transcript types at any reply depth and replies that exceed the bounded scan. Call this before network work such as Self::ensure_dm_peer.

pub fn find_messages( &self, args: &MsgQueryArgs, ) -> Result<Vec<StoredGroupMessage>, GroupError>

Query the database for stored messages. Optionally filtered by time, kind, delivery_status and limit

pub fn count_messages(&self, args: &MsgQueryArgs) -> Result<i64, GroupError>

Count the number of stored messages matching the given criteria

pub fn get_last_read_times( &self, ) -> Result<LatestMessageTimeBySender, GroupError>

pub fn load(&self) -> Result<StoredGroup, StorageError>

Load the group reference stored in the local database

impl<Context> MlsGroup<Context>

where Context: XmtpSharedContext,

pub async fn update_group_name( &self, group_name: String, ) -> Result<(), GroupError>

Updates the name of the group. Will error if the user does not have the appropriate permissions to perform these updates.

pub async fn update_app_data( &self, app_data: String, expected_app_data: Option<String>, ) -> Result<(), GroupError>

Set the group’s opaque app_data slot.

expected_app_data is an optional compare-and-swap guard. When Some, the update is abandoned with GroupError::AppDataSuperseded unless the committed value still equals it — including when another member’s commit wins the epoch race after this intent was published. Callers reconciling structured state should pass the value they merged against, so a concurrent write is reported rather than overwritten.

None keeps the historical last-writer-wins behavior: whatever landed in the meantime is overwritten.

pub async fn update_group_min_version( &self, version: &str, ) -> Result<(), GroupError>

Updates min version of the group to match the given version.

Arguments

• version - The libxmtp version to update the group min version to. This is a semver-formatted string matching the Cargo.toml in the libxmtp dependency, and does not match mobile or web release versions. Versions compare by SemVer precedence (SemVer 2.0.0 section 11), so pre-release identifiers (e.g. "1.0.0-rc.1") sort BEFORE the corresponding release ("1.0.0"), and build metadata (+...) has no precedence: "1.0.0+a" equals "1.0.0" and "1.0.0+b". The group stores the string as given.

Returns

A Result indicating success or failure of the operation.

pub async fn update_permission_policy( &self, permission_update_type: PermissionUpdateType, permission_policy: PermissionPolicyOption, metadata_field: Option<MetadataField>, ) -> Result<(), GroupError>

Updates the permission policy of the group. This requires super admin permissions.

pub fn group_name(&self) -> Result<String, GroupError>

Retrieves the group name from the group’s mutable metadata extension.

pub fn app_data(&self) -> Result<String, GroupError>

Retrieves the app_data field from the group’s mutable metadata extension

pub async fn update_group_description( &self, group_description: String, ) -> Result<(), GroupError>

Updates the description of the group.

pub fn group_description(&self) -> Result<String, GroupError>

pub async fn update_group_image_url_square( &self, group_image_url_square: String, ) -> Result<(), GroupError>

Updates the image URL (square) of the group.

pub fn group_image_url_square(&self) -> Result<String, GroupError>

Retrieves the image URL (square) of the group from the group’s mutable metadata extension.

pub async fn update_conversation_message_disappearing_settings( &self, settings: MessageDisappearingSettings, ) -> Result<(), GroupError>

pub async fn remove_conversation_message_disappearing_settings( &self, ) -> Result<(), GroupError>

pub fn paused_for_version(&self) -> Result<Option<String>, GroupError>

If group is not paused, will return None, otherwise will return the version that the group is paused for

pub fn conversation_message_disappearing_settings( &self, ) -> Result<MessageDisappearingSettings, GroupError>

pub fn conversation_message_disappearing_settings_from_extensions( mutable_metadata: &GroupMutableMetadata, ) -> Result<MessageDisappearingSettings, GroupError>

pub fn pending_remove_list(&self) -> Result<Vec<String>, GroupError>

pub fn is_in_pending_remove(&self, inbox_id: &str) -> Result<bool, GroupError>

Checks if the given inbox ID is the pending-remove list of the group at the most recently synced epoch.

pub fn admin_list(&self) -> Result<Vec<String>, GroupError>

Retrieves the admin list of the group from the group’s mutable metadata extension.

The dictionary-backed TlsSet<InboxId> is iterated in sorted raw-byte order.

pub fn super_admin_list(&self) -> Result<Vec<String>, GroupError>

Retrieves the super admin list of the group from the group’s mutable metadata extension.

Same ordering contract as Self::admin_list.

pub fn is_admin(&self, inbox_id: String) -> Result<bool, GroupError>

Checks if the given inbox ID is an admin of the group at the most recently synced epoch.

pub fn is_super_admin(&self, inbox_id: String) -> Result<bool, GroupError>

Checks if the given inbox ID is a super admin of the group at the most recently synced epoch.

pub fn is_super_admin_without_lock( &self, mls_group: &OpenMlsGroup, inbox_id: String, ) -> Result<bool, GroupMutableMetadataError>

Checks if the given inbox ID is a super admin of the group at the most recently synced epoch

pub async fn conversation_type(&self) -> Result<ConversationType, GroupError>

Retrieves the conversation type of the group from the group’s metadata extension.

impl<Context> MlsGroup<Context>

where Context: XmtpSharedContext,

pub fn metadata_fields( &self, ) -> Result<Vec<MetadataFieldDescriptor>, GroupError>

The group’s metadata fields in component ID order.

pub fn metadata_field( &self, name: &str, ) -> Result<Option<MetadataFieldDescriptor>, GroupError>

The field named name, preferring a well-known field to an application field of the same name.

pub fn metadata_value( &self, field: &MetadataFieldRef, ) -> Result<Option<MetadataValue>, GroupError>

The value of field, None when absent.

pub fn metadata_values( &self, fields: &[MetadataFieldRef], ) -> Result<Vec<MetadataFieldValue>, GroupError>

The values of fields in request order, read from one snapshot.

pub fn map_value( &self, field: &MetadataFieldRef, key: &FieldKey, ) -> Result<Option<FieldValue>, GroupError>

The value under key of the map field.

pub fn user_data( &self, fields: Option<&[MetadataFieldRef]>, inbox_ids: Option<&[InboxId]>, ) -> Result<BTreeMap<InboxId, Vec<UserFieldValue>>, GroupError>

Per-inbox user field values, read from one snapshot. See FieldSnapshot::user_data for the None selections.

pub async fn update_metadata_field( &self, field: &MetadataFieldRef, mutation: &ComponentMutation, ) -> Result<(), GroupError>

Apply mutation to field in one commit, subject to the committed registry’s type and policies.

pub async fn update_user_data( &self, values: &[UserFieldUpdate], ) -> Result<(), GroupError>

Set or clear this inbox’s own entries of user fields in one commit. Nothing is committed when values is empty or only clears absent entries.

impl<Context> MlsGroup<Context>

where Context: XmtpSharedContext,

pub fn state_snapshot(&self) -> Result<ConversationStateSnapshot, GroupError>

Read conversation state with one group and consent query, one notification query, and two OpenMLS key reads.

pub fn last_activity_ns( &self, content_types: Option<&[ContentType]>, ) -> Result<i64, GroupError>

Get the last application message time for the selected content types.

pub async fn update_admin_list( &self, action_type: UpdateAdminListType, inbox_id: String, ) -> Result<(), GroupError>

Updates the admin list of the group and syncs the changes to the network.

pub fn added_by_inbox_id(&self) -> Result<String, GroupError>

Find the inbox_id of the group member who added the member to the group

pub fn consent_state(&self) -> Result<ConsentState, GroupError>

The conversation consent of the group: a DM’s is its peer’s inbox record.

pub fn update_consent_state( &self, state: ConsentState, ) -> Result<(), GroupError>

Set the consent of this conversation, as a decision.

pub async fn epoch(&self) -> Result<u64, GroupError>

Get the current epoch number of the group.

pub async fn cursor(&self) -> Result<Cursor, GroupError>

pub async fn local_commit_log(&self) -> Result<Vec<LocalCommitLog>, GroupError>

pub async fn remote_commit_log( &self, ) -> Result<Vec<RemoteCommitLog>, GroupError>

pub async fn debug_info(&self) -> Result<ConversationDebugInfo, GroupError>

pub async fn key_update(&self) -> Result<(), GroupError>

Update this installation’s leaf key in the group by creating a key update commit

pub fn is_active(&self) -> Result<bool, GroupError>

Checks if the current user is active in the group.

If the current user has been kicked out of the group, is_active will return false

pub fn membership_state(&self) -> Result<GroupMembershipState, GroupError>

Returns the membership state of the current user in this group.

pub async fn metadata(&self) -> Result<GroupMetadata, GroupError>

Get the GroupMetadata of the group.

The AppData dictionary contains CONVERSATION_TYPE, CREATOR_INBOX_ID, DM_MEMBERS, and ONESHOT_MESSAGE. Restored conversations have an empty creator until activation.

pub fn mutable_metadata(&self) -> Result<GroupMutableMetadata, GroupError>

Get the GroupMutableMetadata of the group.

The AppData dictionary contains all mutable metadata. Restored conversations have no public admin roles until activation.

pub fn permissions(&self) -> Result<GroupMutablePermissions, GroupError>

Returns the permissions projection for this group.

pub fn disappearing_settings( &self, ) -> Result<Option<MessageDisappearingSettings>, GroupError>

Fetches the message disappearing settings for a given group ID.

Returns Some(MessageDisappearingSettings) if the group exists and has valid settings, None if the group or settings are missing, or Err(ClientError) on a database error.

pub fn find_duplicate_dms(&self) -> Result<Vec<MlsGroup<Context>>, GroupError>

Find all the duplicate dms for this group

impl<Context> MlsGroup<Context>

where Context: XmtpSharedContext,

pub async fn members(&self) -> Result<Vec<GroupMember>, GroupError>

Load the member list for the group from the DB, merging together multiple installations into a single entry

impl<Context: XmtpSharedContext> MlsGroup<Context>

pub fn find_history_page_with_stored( &self, query: &MsgQueryArgs, ) -> Result<EnrichedHistoryPage, EnrichMessageError>

Read base rows, raw coverage and relations in one database snapshot.

pub fn find_recovery_page_with_stored( &self, query: RecoveryQueryArgs, ) -> Result<EnrichedRecoveryPage, EnrichMessageError>

Read Failed and Unpublished rows and relations in one database snapshot.

impl<Context> MlsGroup<Context>

where Context: XmtpSharedContext,

pub fn find_messages_v2( &self, query: &MsgQueryArgs, ) -> Result<Vec<DecodedMessage>, EnrichMessageError>

pub fn find_messages_v2_with_stored( &self, query: &MsgQueryArgs, ) -> Result<Vec<EnrichedStoredMessage>, EnrichMessageError>

pub fn find_messages_v2_with_conn<C>( &self, query: &MsgQueryArgs, conn: C, ) -> Result<Vec<DecodedMessage>, EnrichMessageError>

where C: QueryGroupMessage + DbQuery,

impl<Context> MlsGroup<Context>

where Context: XmtpSharedContext,

pub async fn maybe_update_installations( &self, update_interval_ns: Option<i64>, ) -> Result<(), GroupError>

pub fn hmac_keys( &self, epoch_delta_range: RangeInclusive<i64>, ) -> Result<Zeroizing<Vec<HmacKey>>, StorageError>

Provides hmac keys for a range of epochs around current epoch group.hmac_keys(-1..=1)`` will provide 3 keys consisting of last epoch, current epoch, and next epoch group.hmac_keys(0..=0) will provide 1 key, consisting of only the current epoch

impl<Context> MlsGroup<Context>

where Context: XmtpSharedContext,

pub async fn receive(&self) -> Result<ProcessSummary, GroupError>

Wait for a fixed network prefix. The summary is local history, not proof of completion.

impl<Context> MlsGroup<Context>

where Context: XmtpSharedContext,

pub async fn sync(&self) -> Result<SyncSummary, GroupError>

pub async fn sync_with_conn(&self) -> Result<SyncSummary, SyncSummary>

Sync from the network with the ‘conn’ (local database). must return a summary of all messages synced, whether they were successful or not.

impl<Context: XmtpSharedContext> MlsGroup<Context>

pub fn set_notifications( &self, value: NotificationOverride, ) -> Result<(), StorageError>

Set an override after which the task recomputes the desired set.

pub fn notifications_enabled(&self) -> Result<bool, StorageError>

Return the effective local rule for this conversation.

impl<Context: XmtpSharedContext> MlsGroup<Context>

pub async fn add_members_by_targets( &self, targets: &[IdentityTarget], ) -> Result<UpdateGroupMembershipResult, GroupError>

Add targets to the group in one commit. Every target resolves first, and the add fails before any commit when a target has no inbox: a handle with [HandleError::NotFound], an account with GroupError::AddressNotFound.

pub async fn remove_members_by_targets( &self, targets: &[IdentityTarget], ) -> Result<(), GroupError>

Remove targets from the group in one commit. Every target resolves first. The removal fails before any commit when a handle has no inbox, and skips an account with no inbox.

Trait Implementations

impl<Context: XmtpSharedContext> Clone for MlsGroup<Context>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Context> Debug for MlsGroup<Context>

where Context: XmtpSharedContext,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<Context: Clone> From<MlsGroup<&Context>> for MlsGroup<Context>

fn from(group: MlsGroup<&Context>) -> MlsGroup<Context>

Converts to this type from the input type.

impl<C> Hash for MlsGroup<C>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<C> PartialEq for MlsGroup<C>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<C> Eq for MlsGroup<C>