TransactionContext - Wire CoreCrypto

TransactionContext provides transactional access to Core Crypto internals. Every operation that writes to the keystore must be performed through this struct. Operations are buffered in memory and persisted atomically when finish is called. Obtain a context from CoreCrypto::new_transaction.

After calling finish or abort, the context transitions to an Invalid state. Any subsequent method call will return an error. Do not reuse a finished context.

Transaction lifecycle

`finish`

pub async fn finish(&self) -> Result<()>

Commits all buffered operations to the keystore in a single database transaction. The context is invalidated after this call. Example

let tx = cc.new_transaction().await?;
tx.mls_init(client_id, transport).await?;
tx.finish().await?; // all writes committed atomically

`abort`

pub async fn abort(&self) -> Result<()>

Discards all buffered operations without writing to the keystore. The context is invalidated after this call.

MLS session management

`mls_init`

pub async fn mls_init(
    &self,
    session_id: ClientId,
    transport: Arc<dyn MlsTransport>,
) -> Result<()>

Initialises the MLS client for this CoreCrypto instance. Must be called once before any conversation operation. Credentials should be added via add_credential before generating key packages.

session_id

ClientId

required

Unique identifier for this client device. Typically derived from the Wire user/device ID pair, e.g. b7ac11a4-8f01-4527-af88-1c30885a7931:6add501bacd1d90e@example.com.

transport

Arc<dyn MlsTransport>

required

Application-provided delivery service transport. See MlsTransport.

Example

let transport = Arc::new(MyTransport::new());
let client_id: ClientId = b"alice:device1@example.com".to_vec().into();
tx.mls_init(client_id, transport).await?;

`mls_is_pki_env_setup` / `e2ei_is_enabled`

pub async fn e2ei_is_enabled(&self, ciphersuite: Ciphersuite) -> Result<bool>

Returns true if the MLS session has an X.509 credential registered for the given ciphersuite. Returns false for Basic credential setups. Fails if no credential exists for the ciphersuite.

ciphersuite

Ciphersuite

required

The ciphersuite to query.

bool

true when E2EI is active for the given ciphersuite.

`client_id`

pub async fn client_id(&self) -> Result<ClientId>

Returns the ClientId of the current MLS session.

`random_bytes`

pub async fn random_bytes(&self, len: usize) -> Result<Vec<u8>>

Generates len cryptographically random bytes using the MLS crypto provider’s RNG.

len

usize

required

Number of random bytes to generate.

Conversation operations

Conversation operations are performed via a ConversationGuard obtained from conversation. See the MLS Conversations reference for the full API.

`conversation`

pub async fn conversation(
    &self,
    id: &ConversationIdRef,
) -> Result<ConversationGuard>

Acquires a mutable guard for an existing conversation. Returns an error if the conversation is not found or if a pending (external-commit) conversation exists under the same ID.

&ConversationIdRef

required

The conversation / group identifier bytes.

ConversationGuard

A guard that provides mutable access to the conversation. See MLS Conversations.

`new_conversation`

pub async fn new_conversation(
    &self,
    id: &ConversationIdRef,
    credential_ref: &CredentialRef,
    config: MlsConversationConfiguration,
) -> Result<()>

Creates a new MLS group. Fails if a conversation with the same ID already exists. See MLS Conversations — new_conversation for full parameter docs.

`conversation_exists`

pub async fn conversation_exists(
    &self,
    id: &ConversationIdRef,
) -> Result<bool>

Returns true if a fully-initialised conversation with the given ID is present in the local keystore.

`join_by_external_commit`

pub async fn join_by_external_commit(
    &self,
    group_info: VerifiableGroupInfo,
    credential_ref: &CredentialRef,
) -> Result<WelcomeBundle>

Joins an existing group via an external commit. See MLS Conversations — join_by_external_commit.

Key package operations

See the Key Packages reference for full documentation.

`generate_keypackage`

pub async fn generate_keypackage(
    &self,
    credential_ref: &CredentialRef,
    lifetime: Option<Duration>,
) -> Result<Keypackage>

Generates and persists a new KeyPackage from the referenced credential. If lifetime is None, KEYPACKAGE_DEFAULT_LIFETIME (~3 months) is used.

`get_keypackage_refs`

pub async fn get_keypackage_refs(&self) -> Result<Vec<KeypackageRef>>

Returns all KeypackageRefs currently stored in the keystore.

`remove_keypackage`

pub async fn remove_keypackage(&self, kp_ref: &KeypackageRef) -> Result<()>

Removes a single key package and its associated HPKE private key and encryption keypair from the database. Succeeds silently if the key package no longer exists.

Credential operations

See the Credentials reference for full documentation.

`add_credential`

pub async fn add_credential(
    &self,
    credential: Credential,
) -> Result<CredentialRef>

Adds a credential to the session database. The credential’s client ID must match the session’s client ID.

`remove_credential`

pub async fn remove_credential(
    &self,
    credential_ref: &CredentialRef,
) -> Result<()>

Removes a credential and all key packages generated from it. Fails if the credential is still in use by any conversation.

`find_credentials`

pub async fn find_credentials(
    &self,
    find_filters: CredentialFindFilters<'_>,
) -> Result<Vec<CredentialRef>>

Finds credentials matching the supplied filters among all session identities.

`get_credentials`

pub async fn get_credentials(&self) -> Result<Vec<CredentialRef>>

Returns all credentials belonging to this session. Equivalent to calling find_credentials with no filters.

E2EI operations

See the E2EI API reference for full documentation.

`e2ei_new_enrollment`

pub async fn e2ei_new_enrollment(
    &self,
    client_id: ClientId,
    display_name: String,
    handle: String,
    team: Option<String>,
    expiry_sec: u32,
    ciphersuite: Ciphersuite,
) -> Result<E2eiEnrollment>

Begins an E2EI enrollment. See E2EI API — e2ei_new_enrollment.

`save_x509_credential`

pub async fn save_x509_credential(
    &self,
    enrollment: &mut E2eiEnrollment,
    certificate_chain: String,
) -> Result<(CredentialRef, NewCrlDistributionPoints)>

Finalises an enrollment by parsing the ACME certificate response and saving a new X.509 credential. See E2EI API — save_x509_credential.

`e2ei_mls_init_only`

pub async fn e2ei_mls_init_only(
    &self,
    enrollment: &mut E2eiEnrollment,
    certificate_chain: String,
    transport: Arc<dyn MlsTransport>,
) -> Result<(CredentialRef, NewCrlDistributionPoints)>

Initialises the MLS session with an X.509 credential in a single step. See E2EI API — e2ei_mls_init_only.

`e2ei_is_enabled`

pub async fn e2ei_is_enabled(&self, ciphersuite: Ciphersuite) -> Result<bool>

Returns true when the session uses an X.509 credential for the given ciphersuite.

Proteus operations

The following methods are only available when the crate is compiled with the proteus feature flag.

`proteus_init`

#[cfg(feature = "proteus")]
pub async fn proteus_init(&self) -> Result<()>

Initialises the Proteus session. Must be called before any other proteus_* method.

`proteus_session_from_prekey`

#[cfg(feature = "proteus")]
pub async fn proteus_session_from_prekey(
    &self,
    session_id: &str,
    prekey: &[u8],
) -> Result<Vec<u8>>

Initialises a Proteus session from a remote pre-key bundle. Returns the initial ciphertext envelope.

session_id

&str

required

A unique string identifying the Proteus session (typically the remote client ID).

prekey

&[u8]

required

The serialised Proteus pre-key bundle from the remote party.

`proteus_session_from_message`

#[cfg(feature = "proteus")]
pub async fn proteus_session_from_message(
    &self,
    session_id: &str,
    envelope: &[u8],
) -> Result<Vec<u8>>

Initialises a Proteus session from an incoming envelope. Returns the decrypted plaintext.

`proteus_encrypt`

#[cfg(feature = "proteus")]
pub async fn proteus_encrypt(
    &self,
    session_id: &str,
    plaintext: &[u8],
) -> Result<Vec<u8>>

Encrypts a message for an existing Proteus session.

`proteus_decrypt`

#[cfg(feature = "proteus")]
pub async fn proteus_decrypt(
    &self,
    session_id: &str,
    ciphertext: &[u8],
) -> Result<Vec<u8>>

Decrypts a Proteus message within an existing session.

`proteus_auto_prekey`

#[cfg(feature = "proteus")]
pub async fn proteus_auto_prekey(&self, id: u16) -> Result<Vec<u8>>

Generates a new Proteus pre-key bundle for the given pre-key ID and returns the serialised bundle.

`proteus_last_resort_prekey`

#[cfg(feature = "proteus")]
pub async fn proteus_last_resort_prekey(&self) -> Result<Vec<u8>>

Returns the serialised last-resort pre-key bundle. The last-resort pre-key is never consumed and remains valid indefinitely.

`proteus_session_delete`

#[cfg(feature = "proteus")]
pub async fn proteus_session_delete(&self, session_id: &str) -> Result<()>

Deletes a Proteus session from the local keystore.

`proteus_session_exists`

#[cfg(feature = "proteus")]
pub async fn proteus_session_exists(&self, session_id: &str) -> Result<bool>

Returns true if a Proteus session with the given ID exists in the keystore.

#[cfg(feature = "proteus")]
pub async fn proteus_fingerprint(&self) -> Result<String>

#[cfg(feature = "proteus")]
pub async fn proteus_fingerprint_local(
    &self,
    session_id: &str,
) -> Result<String>

#[cfg(feature = "proteus")]
pub async fn proteus_fingerprint_remote(
    &self,
    session_id: &str,
) -> Result<String>

Return hex-encoded Proteus fingerprints for the local identity key, the local session key, and the remote session key respectively.

Consumer data checkpoint

`set_data`

pub async fn set_data(&self, data: Vec<u8>) -> Result<()>

Persists arbitrary bytes as a checkpoint marker. The data is committed as part of the transaction. Intended for application-level progress tracking.

`get_data`

pub async fn get_data(&self) -> Result<Option<Vec<u8>>>

Retrieves the checkpoint bytes previously stored by set_data. Returns None if no data has been set.

API Reference

FFI & Bindings

​Transaction lifecycle

​finish

​abort

​MLS session management

​mls_init

​mls_is_pki_env_setup / e2ei_is_enabled

​client_id

​random_bytes

​Conversation operations

​conversation

​new_conversation

​conversation_exists

​join_by_external_commit

​Key package operations

​generate_keypackage

​get_keypackage_refs

​remove_keypackage

​Credential operations

​add_credential

​remove_credential

​find_credentials

​get_credentials

​E2EI operations

​e2ei_new_enrollment

​save_x509_credential

​e2ei_mls_init_only

​e2ei_is_enabled

​Proteus operations

​proteus_init

​proteus_session_from_prekey

​proteus_session_from_message

​proteus_encrypt

​proteus_decrypt

​proteus_auto_prekey

​proteus_last_resort_prekey

​proteus_session_delete

​proteus_session_exists

​proteus_fingerprint and related

​Consumer data checkpoint

​set_data

​get_data

Build docs developers (and LLMs) love

Transaction lifecycle

`finish`

`abort`

MLS session management

`mls_init`

`mls_is_pki_env_setup` / `e2ei_is_enabled`

`client_id`

`random_bytes`

Conversation operations

`conversation`

`new_conversation`

`conversation_exists`

`join_by_external_commit`

Key package operations

`generate_keypackage`

`get_keypackage_refs`

`remove_keypackage`

Credential operations

`add_credential`

`remove_credential`

`find_credentials`

`get_credentials`

E2EI operations

`e2ei_new_enrollment`

`save_x509_credential`

`e2ei_mls_init_only`

`e2ei_is_enabled`

Proteus operations

`proteus_init`

`proteus_session_from_prekey`

`proteus_session_from_message`

`proteus_encrypt`

`proteus_decrypt`

`proteus_auto_prekey`

`proteus_last_resort_prekey`

`proteus_session_delete`

`proteus_session_exists`

`proteus_fingerprint` and related

Consumer data checkpoint

`set_data`

`get_data`