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> 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. 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.

Applies the same validation, storage, and identifier binding 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, identifier: Identifier, ) -> Result<Option<String>, ClientError>

The inbox that holds identifier, or None. The backend’s answer counts only when the newest state the client derives for the answered inbox holds the 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, acts: &[ConsentAct], ) -> Result<(), ClientError>

Store the app’s consent decisions in one transaction. An act on a group id the client does not hold fails the whole call, and nothing is stored.

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

The consent an app reads for an entity: a conversation’s under its key, held or not, or an inbox’s record.

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. Every account resolves before the group is stored, as do member identities and key packages. An account with no inbox fails with GroupError::AddressNotFound.

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

Returns the stored group if its first add is still pending when the wait ends. A later sync completes the add.

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. A stored DM whose creation stopped before the peer was added gets the peer first, and any failure of that add is returned, as a new DM’s creation returns its add’s failure.

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 async fn message_with_group( &self, id: &[u8], ) -> Result<Option<(StoredGroupMessage, MlsGroup<Context>)>, ClientError>

Look up a stored message and its current conversation. A message in a duplicate DM resolves to the stitched conversation.

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>

List one page of the app’s conversations, in activity order unless args names another order. A page holds at most args.limit conversations, or CONVERSATION_LIST_DEFAULT_LIMIT when it names none. To read the next page, pass the last row’s listing_time_ns as the order’s before time and its group id as before_id.

Internal callers that need every group use find_groups or fetch_conversation_list, which apply no default limit.

pub async fn register_with_owner( &self, owner: &impl InboxOwner, ) -> Result<(), ClientError>

Register this installation with an inbox owner and wait until it is visible.

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. Return success only after the backend can read the registration receipt.

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

Whether registration has completed its visibility confirmation. A stored identity with a pending receipt is not yet registered.

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

Confirm a stored registration before reporting success.

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.

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>

Reports whether the backend names an inbox for each identifier. This is an unverified availability hint. The client does not independently verify the lookup against current association state or check key packages. This is not a delivery guarantee.

Arguments:

• account_identifier: a list of account identifiers to check

Returns: A map from each identifier to its availability hint.

impl<Context: XmtpSharedContext> Client<Context>

pub fn attachments(&self) -> Attachments<Context>

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 with its recipient reset owed.

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

Read the locally stored state without a backend call.

impl<Context: XmtpSharedContext> Client<Context>

pub async fn resolve_handles( &self, handles: &[Handle], ) -> Result<Vec<Option<InboxId>>, ClientError>

The inbox that holds each handle, in order, or None. An answer from the backend counts only when the newest state the client derives for the answered inbox holds the handle. An old handle of an inbox still resolves to it.

pub async fn handles_have_owner( &self, handles: &[Handle], ) -> Result<Vec<bool>, ClientError>

Whether the backend names an inbox for each handle, in order. This checks no association state: use it only where a wrong answer costs a candidate, never to reach an inbox.

pub async fn available_handles( &self, input: &str, ) -> Result<Vec<Handle>, ClientError>

The handles for input that no inbox holds. input is a handle as a user typed it; its ASCII capitals become lowercase. Input with a code checks only that handle. A name without a code checks the name and HANDLE_SEARCH_CODES distinct random codes in one lookup, and the name comes first in the result. Text outside the handle grammar fails before any request. No policy applies here, so a returned handle can still be refused when it is claimed.

pub async fn claim_handle(&self, handle: &Handle) -> Result<(), ClientError>

Claim handle for this client’s inbox, signed by this installation’s key. A claim of a handle the inbox already holds makes it the display handle again. The backend refuses a taken, reserved, short, or too frequent claim with ApiError::HandleRejected. After the publish, the client has stored the inbox’s new identity update.

pub async fn resolve_targets( &self, targets: &[IdentityTarget], ) -> Result<Vec<InboxId>, ClientError>

The inbox of each target, in order, from one call. Fails when any target has no inbox: an account as find_or_create_dm_by_identity does, and a handle with HandleError::NotFound.

pub async fn find_dm_by_target( &self, target: &IdentityTarget, ) -> Result<Option<MlsGroup<Context>>, ClientError>

The active DM with target, or None. A target that no inbox holds has no DM.

pub async fn find_or_create_dm_by_target( &self, target: &IdentityTarget, opts: DMMetadataOptions, ) -> Result<MlsGroup<Context>, ClientError>

Find the DM with target, or create it. A handle resolves before the existing DM is looked up.

pub async fn create_group_with_targets( &self, targets: &[IdentityTarget], permissions_policy_set: Option<PolicySet>, opts: Option<GroupMetadataOptions>, ) -> Result<MlsGroup<Context>, ClientError>

Create a group with targets as its members, in one commit. Targets, member identities, and key packages resolve before the group is stored. A target with no inbox leaves no group: a handle fails with HandleError::NotFound, an account with GroupError::AddressNotFound.

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_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>>

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

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.