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 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 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 async fn all_members_support_proposals( &self, mls_group: &OpenMlsGroup, ) -> Result<bool, GroupError>

Check if all members in the group support the proposal-by-reference flow.

This checks both:

1. Leaf node capabilities in the MLS group (via check_extension_support)
2. The latest published key packages for all member installations fetched from the network, since leaf nodes may be stale (they aren’t updated after the first message is sent).

Returns true if all members support proposals, false otherwise.

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 (the same reason Self::all_members_support_proposals falls back to key packages). 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

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 remove_members_by_identity( &self, account_addresses_to_remove: &[Identifier], ) -> Result<(), GroupError>

Removes members from the group by their account addresses.

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.

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.

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 delete_message(&self, message_id: Vec<u8>) -> Result<Vec<u8>, GroupError>

Delete a message by its ID. Returns the ID of the deletion message.

Only the original sender or a super admin can delete a message.

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. This function handles the conversion: it accepts raw bytes, hex-encodes them for the wire protocol, and when processing incoming deletions (in process_delete_message), the hex string is decoded back to bytes for database lookups.

Arguments

• message_id - The message ID as bytes

Returns

The ID of the deletion message

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. Comparison is done via the semver crate’s Ord impl, so pre-release identifiers (e.g. "1.0.0-rc.1") sort BEFORE the corresponding release ("1.0.0") per semver 2.0 §11. Build metadata (+...) parses but is included in ordering by the semver crate — avoid passing it unless you understand the total-ordering implication.

Returns

A Result indicating success or failure of the operation.

pub async fn update_commit_log_signer( &self, commit_log_signer: Secret, ) -> Result<(), GroupError>

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

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>

Find the consent_state of the group

pub fn quietly_update_consent_state( &self, state: ConsentState, db: &impl DbQuery, ) -> Result<Vec<StoredConsentRecord>, GroupError>

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

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>>, ClientError>

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<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> MlsGroup<Context>

where Context: XmtpSharedContext + 'static,

pub async fn process_streamed_group_message( &self, envelope_bytes: Vec<u8>, ) -> Result<Vec<StoredGroupMessage>, SubscribeError>

Use a push envelope only as a target for ordered receipt and processing.

pub async fn stream<'a>( &'a self, ) -> Result<impl Stream<Item = Result<StoredGroupMessage, SubscribeError>> + use<'a, Context>, SubscribeError>

where Context::ApiClient: XmtpMlsStreams + 'a,

pub async fn stream_owned( &self, ) -> Result<impl Stream<Item = Result<StoredGroupMessage, SubscribeError>> + 'static, SubscribeError>

where Context: 'static, Context::ApiClient: XmtpMlsStreams + 'static, Context::Db: 'static,

create a stream that is not attached to any lifetime

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. A list of accounts only keeps the account path and its errors. Any other list resolves every target first and fails before any commit when a target has no inbox, with the account path’s error for an account.

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

Remove targets from the group in one commit. A list of accounts only keeps the account path and its errors. Any other list resolves every target first. It fails before any commit when a handle has no inbox, and skips an account with no inbox, as the account path does.

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>