Client Lifecycle

pub struct Client<Context> {
    pub context: Context,
    pub installation_id: InstallationId,
    pub(crate) local_events: broadcast::Sender<LocalEvents>,
    pub(crate) workers: Arc<WorkerRunner>,
}

pub enum IdentityStrategy {
    /// Create identity if database is new, load if exists
    CreateIfNotFound {
        inbox_id: String,
        identifier: Identifier,
        nonce: u64,
        credential: XmtpInstallationCredential,
    },
    
    /// Only load from existing database
    CachedOnly,
    
    /// Use externally provided identity
    External(Identity),
}

let client = Client::builder(IdentityStrategy::CreateIfNotFound {
    inbox_id: inbox_id.clone(),
    identifier: wallet_identifier,
    nonce: 0,
    credential: XmtpInstallationCredential::new(),
})
.api_clients(api_client, sync_api_client)
.store(encrypted_store)
.default_mls_store()?
.with_scw_verifier(verifier)
.build()
.await?;

.api_clients(api_client, sync_api_client)

.store(encrypted_store)
.default_mls_store()?

.with_scw_verifier(verifier)

.with_remote_verifier()?

.with_disable_workers(true)  // Disable background workers
.device_sync_worker_mode(DeviceSyncMode::Enabled)  // Enable device sync

.version(VersionInfo { ... })  // Set version metadata
.with_allow_offline(true)      // Skip network calls during build
.fork_recovery_opts(opts)      // Configure fork recovery behavior

use xmtp_mls::client::{Client, ClientBuilder};
use xmtp_mls::builder::{IdentityStrategy, DeviceSyncMode};
use xmtp_id::associations::Identifier;
use xmtp_cryptography::XmtpInstallationCredential;

let wallet_identifier = Identifier::eth(&wallet_address)?;
let inbox_id = wallet_identifier.inbox_id(0)?;

let client = ClientBuilder::new(IdentityStrategy::CreateIfNotFound {
    inbox_id: inbox_id.clone(),
    identifier: wallet_identifier.clone(),
    nonce: 0,
    credential: XmtpInstallationCredential::new(),
})
.api_clients(api_client.clone(), api_client.clone())
.store(encrypted_store)
.default_mls_store()?
.with_remote_verifier()?
.device_sync_worker_mode(DeviceSyncMode::Enabled)
.build()
.await?;

// Build signature request
let mut signature_request = SignatureRequestBuilder::new(inbox_id)
    .create_inbox(wallet_identifier.clone(), 0)
    .add_association(
        installation_identifier,
        wallet_identifier.into(),
    )
    .build();

// Add installation signature (client can do this)
let installation_signature = credential.sign(&signature_request.signature_text())?;
signature_request.add_signature(
    UnverifiedSignature::InstallationKey(installation_signature),
    &scw_verifier,
).await?;

// Application must add wallet signature
let wallet_signature = wallet.sign(&signature_request.signature_text())?;
signature_request.add_signature(wallet_signature, &scw_verifier).await?;

// Register with network
client.register_identity(signature_request).await?;

let mut signature_request = SignatureRequestBuilder::new(inbox_id)
    .add_association(
        installation_identifier,
        existing_wallet_identifier.into(),
    )
    .build();

// Add signatures (installation + existing wallet)
signature_request.add_signature(installation_sig, &scw_verifier).await?;
signature_request.add_signature(wallet_sig, &scw_verifier).await?;

client.register_identity(signature_request).await?;

if client.identity().is_ready() {
    println!("Already registered!");
} else {
    // Perform registration
}

client.rotate_and_upload_key_package().await?;

client.queue_key_rotation().await?;

let packages = client.get_key_packages_for_installation_ids(
    vec![installation_id_1, installation_id_2],
).await?;

for (id, result) in packages {
    match result {
        Ok(package) => println!("Valid package for {}", hex::encode(id)),
        Err(e) => eprintln!("Invalid package: {}", e),
    }
}

// Installation ID
let installation_id = client.installation_public_key();

// Inbox ID  
let inbox_id = client.inbox_id();

// Database connection
let db = client.db();

// Identity
let identity = client.identity();

// Version info
let version = client.version_info();

if !client.identity().is_ready() {
    eprintln!("Client not ready. Call register_identity() first.");
    return;
}

// Get current association state
let state = client.inbox_state(true).await?;

println!("Inbox ID: {}", state.inbox_id());
println!("Recovery address: {:?}", state.recovery_identifier());
println!("Installations: {:?}", state.installation_ids());
println!("Addresses: {:?}", state.identifiers());

let conn = client.db().conn();
let sequence_id = client.inbox_sequence_id(&conn)?;

client.release_db_connection()?;

client.reconnect_db()?;

client.wait_for_sync_worker_init().await;

let new_groups = client.sync_welcomes().await?;
println!("Joined {} new groups", new_groups.len());

let summary = client.sync_all_welcomes_and_groups(
    Some(vec![ConsentState::Allowed]),
).await?;

println!("Synced {} groups", summary.total_groups_synced);

Err(ClientError::Identity(IdentityError::UninitializedIdentity))

Err(ClientError::Storage(StorageError::...))

Err(ClientError::Api(ApiError::...))

use xmtp_common::RetryableError;

if error.is_retryable() {
    // Retry operation
} else {
    // Permanent failure
}

use xmtp_cryptography::utils::generate_local_wallet;

let wallet = generate_local_wallet();
let client = ClientBuilder::new_test_client(&wallet).await;

let api = MockApi::new();
let scw_verifier = MockSmartContractSignatureVerifier::new(false);

let client = ClientBuilder::new(strategy)
    .api_clients(api.clone(), api)
    .with_scw_verifier(scw_verifier)
    .build()
    .await?;

let client = ClientBuilder::new(strategy)
    .with_allow_offline(true)
    .build()
    .await?;

.device_sync_worker_mode(DeviceSyncMode::Enabled)

.with_disable_workers(true)

use xmtp_common::{retry_async, Retry};

retry_async!(
    Retry::default(),
    (async { client.sync_welcomes().await })
)?;

let store = EncryptedMessageStore::new(
    db_path,
    encryption_key,
)?;
// Migrations run during initialization