Struct Client 

pub struct Client<Context> {
    pub context: Context,
    pub installation_id: InstallationId,
    /* private fields */
}

Clients manage access to the network, identity, and data store

Fields

context: Context

installation_id: InstallationId

Implementations

impl Client<()>

pub fn builder(strategy: IdentityStrategy) -> ClientBuilder<(), ()>

Get the builder for this Client

impl<Context: XmtpSharedContext> Client<Context>

pub async fn enable_notifications( &self, config: NotificationConfig, ) -> Result<NotificationState, NotificationError>

Store configuration, then register inline. The task retries transient errors.

pub async fn disable_notifications(&self) -> Result<(), NotificationError>

Disable locally before unregistering. The recipient identity and overrides stay. A failed unregister leaves the client disabled; the backend recipient expires.

pub fn notification_state(&self) -> Result<NotificationState, StorageError>

Read the locally stored state without a backend call.

impl<Context> Client<Context>

where Context: XmtpSharedContext,

pub fn identity_updates(&self) -> IdentityUpdates<&Context>

pub fn mls_store(&self) -> MlsStore<Context>

pub fn scw_verifier(&self) -> Arc<Box<dyn SmartContractSignatureVerifier>>

pub fn version_info(&self) -> &VersionInfo

impl<Context> Client<Context>

where Context: XmtpSharedContext, Context::ApiClient: HasStats,

pub fn api_stats(&self) -> ApiStats

pub fn identity_api_stats(&self) -> IdentityStats

pub fn clear_stats(&self)

impl<Context> Client<Context>

where Context: XmtpSharedContext + 'static,

pub fn reconnect_db(&self) -> Result<(), ClientError>

Reconnect to the client’s database if it has previously been released

pub async fn close(&self) -> Result<(), ClientError>

Cleanly shut down this client: cancel in-flight workers and streams, then release the DB connection. Idempotent — a second call is Ok(()).

Callers (notably the Node binding consumers) should await this before deleting the SQLite file or dropping the client wrapper, to avoid late log spew from detached workers/streams firing against a dead DB.

pub async fn wait_for_sync_worker_init(&self)

yields until the sync worker notifies that it is initialized and running.

pub fn sync_metrics(&self) -> Option<Arc<WorkerMetrics<SyncMetric>>>

impl<Context> Client<Context>

where Context: XmtpSharedContext,

pub fn server_configuration(&self) -> &ServerConfiguration

What this deployment published about itself, as resolved at build (CFG-030, CFG-080). A refresh rewrites the stored copy; it never changes this value.

pub async fn refresh_server_configuration( &self, ) -> Result<ServerConfiguration, ClientError>

Fetch the deployment configuration now and rewrite the stored copy (CFG-082).

Applies the same validation (CFG-044), storage (CFG-048), and identifier binding (CFG-051) the refresh worker applies. The snapshot this client is holding is unchanged: a new value takes effect at the next build.

pub fn installation_public_key(&self) -> InstallationId

Retrieves the client’s installation public key, sometimes also called installation_id

pub fn inbox_id(&self) -> InboxIdRef<'_>

Retrieves the client’s inbox ID

pub fn db(&self) -> <Context::Db as XmtpDb>::DbQuery

get a reference to the monolithic Database object where higher-level queries are defined

pub fn device_sync_client(&self) -> DeviceSyncClient<Context>

pub async fn find_inbox_id_from_identifier( &self, conn: &impl DbQuery, identifier: Identifier, ) -> Result<Option<String>, ClientError>

Calls the server to look up the inbox_id associated with a given identifier

pub fn inbox_sequence_id( &self, conn: &DbConnection<<Context::Db as XmtpDb>::Connection>, ) -> Result<i64, StorageError>

Get the highest sequence_id from the local database for the client’s inbox_id. This may not be consistent with the latest state on the backend.

pub async fn inbox_state( &self, refresh_from_network: bool, ) -> Result<AssociationState, ClientError>

Get the AssociationState for the client’s inbox_id

pub async fn inbox_addresses( &self, refresh_from_network: bool, inbox_ids: Vec<InboxIdRef<'_>>, ) -> Result<Vec<AssociationState>, ClientError>

Get the AssociationState for each inbox_id

pub async fn fetch_inbox_updates_count( &self, refresh_from_network: bool, inbox_ids: Vec<InboxIdRef<'_>>, ) -> Result<HashMap<InboxId, u32>, ClientError>

Get the total number of inbox updates for inbox_ids. refresh_from_network will force a network refresh. May still access network if an inbox_id does not yet exist in the local cache.

pub async fn fetch_own_inbox_updates_count( &self, refresh_from_network: bool, ) -> Result<u32, ClientError>

Get the total number of inbox updates for the client’s inbox_id. Setting refresh_from_network forces a network refresh, otherwise this operation is offline.

pub async fn inbox_creation_signature_kind( &self, inbox_id: InboxIdRef<'_>, refresh_from_network: bool, ) -> Result<Option<SignatureKind>, ClientError>

Get the signature kind used to create an inbox.

Arguments

• inbox_id - The inbox ID to check
• refresh_from_network - Whether to fetch updates from the network first

Returns

• Some(SignatureKind) - The signature kind used to create the inbox
• None - Inbox doesn’t exist or creation info is unavailable

pub async fn set_consent_states( &self, records: &[StoredConsentRecord], ) -> Result<(), ClientError>

Set a consent record in the local database. If the consent record is an address set the consent state for both the address and inbox_id

pub async fn get_consent_state( &self, entity_type: ConsentType, entity: String, ) -> Result<ConsentState, ClientError>

Get the consent state for a given entity

pub fn release_db_connection(&self) -> Result<(), ClientError>

Release the client’s database connection

pub fn identity(&self) -> &Identity

Get a reference to the client’s identity struct

pub fn create_group( &self, permissions_policy_set: Option<PolicySet>, opts: Option<GroupMetadataOptions>, ) -> Result<MlsGroup<Context>, ClientError>

Create a new group with the default settings Applies a custom PolicySet to the group if one is specified

pub async fn create_group_with_identifiers( &self, account_identifiers: &[Identifier], permissions_policy_set: Option<PolicySet>, opts: Option<GroupMetadataOptions>, ) -> Result<MlsGroup<Context>, ClientError>

Create a group with an initial set of members added

pub async fn create_group_with_members( &self, inbox_ids: &[impl AsIdRef], permissions_policy_set: Option<PolicySet>, opts: Option<GroupMetadataOptions>, ) -> Result<MlsGroup<Context>, ClientError>

pub async fn find_or_create_dm_by_identity( &self, target_identity: Identifier, opts: Option<DMMetadataOptions>, ) -> Result<MlsGroup<Context>, ClientError>

Find or create a Direct Message with the default settings

pub async fn find_or_create_dm( &self, inbox_id: impl AsIdRef, opts: Option<DMMetadataOptions>, ) -> Result<MlsGroup<Context>, ClientError>

Find or create a Direct Message by inbox_id with the default settings

pub fn group( &self, group_id: &GroupId, ) -> Result<MlsGroup<Context>, ClientError>

Look up a group by its ID

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

pub fn stitched_group( &self, group_id: &GroupId, ) -> Result<MlsGroup<Context>, ClientError>

Look up a group by its ID while stitching DMs

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

pub fn find_duplicate_dms_for_group( &self, group_id: &GroupId, ) -> Result<Vec<MlsGroup<Context>>, ClientError>

Find all the duplicate dms for this group

pub fn group_disappearing_settings( &self, group_id: &GroupId, ) -> Result<Option<MessageDisappearingSettings>, ClientError>

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 dm_group_from_target_inbox( &self, target_inbox_id: String, ) -> Result<MlsGroup<Context>, ClientError>

Look up a DM group by the target’s inbox_id.

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

pub fn message( &self, message_id: Vec<u8>, ) -> Result<StoredGroupMessage, ClientError>

Look up a message by its ID Returns a StoredGroupMessage if the message exists, or an error if it does not

pub fn message_v2( &self, message_id: Vec<u8>, ) -> Result<DecodedMessage, ClientError>

Look up and enrich a message by its ID, returning a DecodedMessage Returns an error if the message is not found or if it cannot be decoded/enriched

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

Delete a message by its ID This method is idempotent and will not error if the message is not found Returns the number of messages deleted (0 or 1)

pub fn find_groups( &self, args: GroupQueryArgs, ) -> Result<Vec<MlsGroup<Context>>, ClientError>

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 list_conversations( &self, args: GroupQueryArgs, ) -> Result<Vec<ConversationListItem<Context>>, ClientError>

pub async fn register_identity( &self, signature_request: SignatureRequest, ) -> Result<(), ClientError>

Upload the key package before the identity update exposes this installation. Record its receipt for key retirement and retain the registration cursor.

pub async fn wait_for_registration_visible( &self, options: VisibilityConfirmationOptions, ) -> Result<(), ClientError>

Wait until the serving database exposes the registration identity-topic head. A missing or older head is polled. The timeout also bounds each request.

pub fn queue_key_rotation(&self) -> Result<(), ClientError>

If no key rotation is scheduled, queue it to occur in the next 5 seconds.

pub async fn rotate_and_upload_key_package(&self) -> Result<(), ClientError>

Upload a new key package to the network replacing an existing key package This is expected to be run any time the client receives new Welcome messages

pub async fn get_key_packages_for_installation_ids( &self, installation_ids: Vec<Vec<u8>>, ) -> Result<HashMap<Vec<u8>, Result<VerifiedKeyPackageV2, KeyPackageVerificationError>>, ClientError>

Fetches the current key package from the network for each of the installation_ids specified

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

Download all unread welcome messages and converts to a group struct, ignoring malformed messages. Returns any new groups created in the operation

pub async fn sync_all_groups( &self, groups: Vec<MlsGroup<Context>>, ) -> Result<GroupSyncSummary, GroupError>

Sync all groups for the current installation and return the number of groups that were synced. Only active groups will be synced.

pub async fn sync_all_welcomes_and_groups( &self, consent_states: Option<Vec<ConsentState>>, ) -> Result<GroupSyncSummary, GroupError>

Sync all unread welcome messages and then sync all groups. Returns the total number of active groups synced.

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

Sweep every group flagged paused_for_version and clear the pause flag for any whose floor is now satisfied by this client’s pkg_version. Pure local-state operation — no network calls. Returns the count of groups unstuck.

sync_all_welcomes_and_groups already runs this sweep as a preamble; the standalone entry point is for SDKs that want a cheap “post-upgrade recovery” hook independent of the normal sync flow.

pub async fn sync_all_welcomes_and_device_sync_groups( &self, ) -> Result<GroupSyncSummary, ClientError>

pub async fn sync_all_device_sync_groups( &self, ) -> Result<GroupSyncSummary, ClientError>

pub async fn validate_credential_against_network( &self, conn: &DbConnection<<Context::Db as XmtpDb>::Connection>, credential: &[u8], installation_pub_key: Vec<u8>, ) -> Result<InboxId, ClientError>

Validates a credential against the given installation public key

This will go to the network and get the latest association state for the inbox. It ensures that the installation_pub_key is in that association state

pub async fn can_message( &self, account_identifiers: &[Identifier], ) -> Result<HashMap<Identifier, bool>, ClientError>

Check whether an account_identifier has a key package registered on the network

Arguments:

• account_identifier: a list of account identifiers to check

Returns: A Vec of booleans indicating whether each account address has a key package registered on the network

impl<C: XmtpSharedContext + 'static> Client<C>

pub async fn catch_up_to_live( &self, timeout: Option<Duration>, ) -> Result<CatchUpSummary, CatchUpError>

Process fixed starting targets and only the discoveries from the enrolled Welcomes.

impl<C> Client<C>

where C: XmtpSharedContext + 'static, C::ApiClient: XmtpMlsBidiStreams + XmtpMlsStreams + ApiClientIdentity + Clone + Send + Sync + 'static, <C::ApiClient as XmtpMlsBidiStreams>::SubscribeStream: 'static,

pub fn stream_all_messages_with_callback_dispatch( client: Arc<Client<C>>, conversation_type: Option<ConversationType>, consent_states: Option<Vec<ConsentState>>, callback: impl FnMut(Result<StoredGroupMessage, SubscribeError>) + MaybeSend + 'static, on_close: impl FnOnce() + MaybeSend + 'static, ) -> impl StreamHandle<StreamOutput = Result<(), SubscribeError>>

pub fn stream_conversations_with_callback_dispatch( client: Arc<Client<C>>, conversation_type: Option<ConversationType>, include_duplicate_dms: bool, callback: impl FnMut(Result<MlsGroup<C>, SubscribeError>) + MaybeSend + 'static, on_close: impl FnOnce() + MaybeSend + 'static, ) -> impl StreamHandle<StreamOutput = Result<(), SubscribeError>>

impl<Context> Client<Context>

where Context: XmtpSharedContext + 'static,

pub async fn process_streamed_welcome_message( &self, envelope_bytes: Vec<u8>, ) -> Result<Vec<MlsGroup<Context>>, SubscribeError>

Use push metadata as a target. Fetch its complete prefix before processing.

pub async fn stream_conversations( &self, conversation_type: Option<ConversationType>, include_duplicate_dms: bool, ) -> Result<impl Stream<Item = Result<MlsGroup<Context>, SubscribeError>> + use<'_, Context>, SubscribeError>

where Context::ApiClient: XmtpMlsStreams,

pub async fn stream_conversations_owned( &self, conversation_type: Option<ConversationType>, include_duplicate_dms: bool, ) -> Result<impl Stream<Item = Result<MlsGroup<Context>, SubscribeError>> + 'static + use<Context>, SubscribeError>

where Context::ApiClient: XmtpMlsStreams,

Stream conversations but decouple the lifetime of ‘self’ from the stream.

impl<Context> Client<Context>

where Context: XmtpSharedContext + 'static, Context::ApiClient: XmtpMlsStreams + 'static, Context::MlsStorage: 'static,

pub fn stream_conversations_with_callback( client: Arc<Client<Context>>, conversation_type: Option<ConversationType>, convo_callback: impl FnMut(Result<MlsGroup<Context>, SubscribeError>) + MaybeSend + 'static, on_close: impl FnOnce() + MaybeSend + 'static, include_duplicate_dms: bool, ) -> impl StreamHandle<StreamOutput = Result<(), SubscribeError>>

pub async fn stream_all_messages( &self, conversation_type: Option<ConversationType>, consent_state: Option<Vec<ConsentState>>, ) -> Result<impl Stream<Item = Result<StoredGroupMessage, SubscribeError>> + '_, SubscribeError>

pub async fn stream_all_messages_owned( &self, conversation_type: Option<ConversationType>, consent_state: Option<Vec<ConsentState>>, ) -> Result<impl Stream<Item = Result<StoredGroupMessage, SubscribeError>> + 'static + use<Context>, SubscribeError>

pub fn stream_all_messages_with_callback( context: Context, conversation_type: Option<ConversationType>, consent_state: Option<Vec<ConsentState>>, callback: impl FnMut(Result<StoredGroupMessage, SubscribeError>) + MaybeSend + 'static, on_close: impl FnOnce() + MaybeSend + 'static, ) -> impl StreamHandle<StreamOutput = Result<(), SubscribeError>>

pub fn stream_consent_with_callback( client: Arc<Client<Context>>, callback: impl FnMut(Result<Vec<StoredConsentRecord>, SubscribeError>) + MaybeSend + 'static, on_close: impl FnOnce() + MaybeSend + 'static, ) -> impl StreamHandle<StreamOutput = Result<(), SubscribeError>>

pub fn stream_preferences_with_callback( client: Arc<Client<Context>>, callback: impl FnMut(Result<Vec<PreferenceUpdate>, SubscribeError>) + MaybeSend + 'static, on_close: impl FnOnce() + MaybeSend + 'static, ) -> impl StreamHandle<StreamOutput = Result<(), SubscribeError>>

pub fn stream_message_deletions_with_callback( client: Arc<Client<Context>>, callback: impl FnMut(Result<DecodedMessage, SubscribeError>) + MaybeSend + 'static, on_close: impl FnOnce() + MaybeSend + 'static, ) -> impl StreamHandle<StreamOutput = Result<(), SubscribeError>>

Trait Implementations

impl<Context: Clone> Clone for Client<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> Drop for Client<Context>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.