Struct ContextClient 

pub struct ContextClient { /* private fields */ }

A client for interacting with the context management system.

This struct serves as the primary public API, providing methods to create, join, query, and manage contexts and their members. It orchestrates interactions between the datastore, background actors, and external networks.

Implementations

impl ContextClient

pub fn new_identity(&self) -> Result<PublicKey>

Creates a new cryptographic identity (key pair) and stores it in the datastore. The private key is randomly generated. The new identity doesn’t have any sender_key. If needed, the sender_key could be set via update_identity() method later.

Note

This identity is not initially tied to a specific context (it is stored under a zeroed-out ContextId). It can be seen as a “global” identity within the node that can later be associated with one or more contexts.

Returns

A Result containing the PublicKey of the newly created identity.

Errors

Returns an error if there is an issue writing the new identity to the datastore.

pub fn get_identity( &self, context_id: &ContextId, public_key: &PublicKey, ) -> Result<Option<ContextIdentity>>

Retrieves an identity from the datastore for a given context.

Arguments

• context_id - The context in which the identity is being retrieved.
• public_key - The public key of the identity to fetch.

Returns

An Option containing the ContextIdentity if found, otherwise None.

Errors

Returns an error if there is an issue reading from the datastore.

pub fn update_identity( &self, context_id: &ContextId, new_identity: &ContextIdentity, ) -> Result<()>

Updates an existing identity in the datastore.

This is typically used to add or change the sender_key or private_key for an identity that the node already knows about.

Arguments

• context_id - The context of the identity to update.
• new_identity - The ContextIdentity object containing the updated fields.

Errors

Returns an error if the identity does not exist or if there is a datastore issue.

pub fn delete_identity( &self, context_id: &ContextId, public_key: &PublicKey, ) -> Result<()>

Deletes an identity from the datastore for a given context.

Arguments

• context_id - The context from which to delete the identity.
• public_key - The public key of the identity to delete.

Errors

Returns an error if there is an issue writing to the datastore.

impl ContextClient

pub fn context_config( &self, context_id: &ContextId, ) -> Result<Option<ContextConfigParams<'static>>>

impl ContextClient

pub const fn external_client<'a>( &'a self, context_id: &ContextId, config: &'a ContextConfigParams<'a>, ) -> Result<ExternalClient<'a>>

impl ContextClient

pub async fn sync_context_config( &self, context_id: ContextId, config: Option<ContextConfigParams<'_>>, ) -> Result<Context>

impl ContextClient

pub const fn new( datastore: Store, node_client: NodeClient, external_client: ExternalClient<AnyTransport>, context_manager: LazyRecipient<ContextMessage>, ) -> Self

pub fn datastore_handle(&self) -> Handle<Store>

Returns a handle to the datastore for direct access. Used by node components that need to read stored data.

pub async fn create_context( &self, protocol: String, application_id: &ApplicationId, identity_secret: Option<PrivateKey>, init_params: Vec<u8>, seed: Option<[u8; 32]>, ) -> Result<CreateContextResponse>

Sends a request to create a new context.

This operation is asynchronous and is handled by the ContextManager actor.

Arguments

• protocol - The name of the protocol that will be used for the new context.
• application_id - The ID of the application that will run in the context.
• identity_secret - An optional private key to use for the initial identity. If not provided, a new identity will be generated.
• init_params - Raw byte parameters for initializing the application state.
• seed - An optional 32-byte seed for deterministic context ID and identity creation.

Returns

A Result containing the CreateContextResponse from the actor upon completion.

pub async fn invite_member( &self, context_id: &ContextId, inviter_id: &PublicKey, invitee_id: &PublicKey, ) -> Result<Option<ContextInvitationPayload>>

Invites a new member to an existing context.

This involves an external call to the on-chain contract to register the new member.

Arguments

• context_id - The context to invite the member to.
• inviter_id - The public key of an existing member who is performing the invitation.
• invitee_id - The public key of the identity being invited.

Returns

• A Result containing an Option with the shareable ContextInvitationPayload.
• Returns Ok(None) if the context configuration cannot be found locally.

pub async fn invite_member_by_open_invitation( &self, context_id: &ContextId, inviter_id: &PublicKey, valid_for_blocks: BlockHeight, _secret_salt: [u8; 32], ) -> Result<Option<SignedOpenInvitation>>

Creates and signs a one-time, expiring open invitation for a new member.

This method allows an existing member of a context (the inviter) to generate a shareable invitation. The method fetches the inviter’s private key managed by the local node, signs the invitation details, and returns the resulting payload and signature.

Arguments

• context_id - The context to invite the new member to.
• inviter_id - The public key of the existing member creating the invitation. This node must have the corresponding private key for this identity.
• valid_for_blocks - A number of blocks from the current block height for which the invitation is considered to be valid.
• secret_salt - A 32-byte random value to ensure the invitation is unique.

Returns

• A Result containing the SignedOpenInvitation if successful, or an error if the inviter’s private key is not found or signing fails.
• Returns Ok(None) if the context configuration cannot be found locally.

pub async fn join_context( &self, invitation_payload: ContextInvitationPayload, ) -> Result<JoinContextResponse>

Sends a request to join a context using an invitation payload.

This is an asynchronous operation handled by the ContextManager actor. The actor will parse the payload, validate the information, and configure the local node to participate in the specified context.

Arguments

• invitation_payload - The opaque ContextInvitationPayload received from an inviter.

Returns

A Result containing the JoinContextResponse from the actor upon completion.

pub async fn join_context_by_open_invitation( &self, signed_invitation: SignedOpenInvitation, new_member_public_key: &PublicKey, ) -> Result<Option<JoinContextResponse>>

Sends a request to join a context using the new commit-reveal open invitation flow.

This is an asynchronous operation handled by the ContextManager actor. The actor will parse the payload, validate the information, and configure the local node to participate in the specified context.

Arguments

• invitation_payload - The opaque ContextInvitationPayload received from an inviter.

Returns

• A Result containing the JoinContextResponse from the actor upon completion.
• Returns Ok(None) if the context configuration cannot be found locally.

pub fn has_context(&self, context_id: &ContextId) -> Result<bool>

Checks if a context’s metadata exists in the local datastore.

Arguments

• context_id - The ID of the context to check for.

Returns

A Result containing true if the context exists locally, false otherwise.

pub fn get_context(&self, context_id: &ContextId) -> Result<Option<Context>>

Retrieves a context metadata from the local datastore.

Arguments

• context_id - The ID of the context to retrieve.

Returns

A Result containing Some(Context) if the context is found, or None if it is not.

pub fn update_dag_heads( &self, context_id: &ContextId, dag_heads: Vec<[u8; 32]>, ) -> Result<()>

Updates the DAG heads for a context after applying a delta.

Arguments

• context_id - The ID of the context to update.
• dag_heads - The new DAG heads (typically the delta ID that was just applied).

Returns

A Result indicating success or failure.

pub fn update_context_application_id( &self, context_id: &ContextId, application_id: ApplicationId, ) -> Result<()>

Updates the ApplicationId for a context.

Arguments

• context_id - The ID of the context to update.
• application_id - The new ApplicationId.

Returns

A Result indicating success or failure.

pub fn compute_root_hash(&self, context_id: &ContextId) -> Result<[u8; 32]>

Computes the actual root hash from storage by reading the root Index entry.

This reads the EntityIndex for Id::root() from RocksDB and extracts the Merkle full_hash. This is the authoritative hash computed from the actual state, not a claimed value.

Arguments

• context_id - The ID of the context to compute the root hash for.

Returns

The computed root hash, or [0; 32] if no root index exists (empty state).

pub fn force_root_hash( &self, context_id: &ContextId, root_hash: Hash, ) -> Result<()>

Forces the root hash for a context to a specific value.

WARNING: This bypasses verification and should only be used when the hash has already been verified or during controlled operations. Prefer compute_root_hash + set_root_hash for safety.

Arguments

• context_id - The ID of the context to update.
• root_hash - The root hash to set.

Returns

A Result indicating success or failure.

pub fn verify_root_hash( &self, context_id: &ContextId, claimed_hash: [u8; 32], ) -> Result<()>

Verifies that the stored root hash matches the actual state.

Computes the root hash from storage and compares with the claimed hash. Returns Ok(()) if they match, or an error describing the mismatch.

Arguments

• context_id - The ID of the context to verify.
• claimed_hash - The hash to verify against.

Returns

A Result indicating success if hashes match, or an error if they don’t.

pub fn get_context_ids( &self, start: Option<ContextId>, ) -> impl Stream<Item = Result<ContextId>>

Returns a stream of all context IDs stored locally.

Arguments

• start - An optional ContextId from which to begin the stream. If None, the stream starts from the beginning.

Returns

An implementation of Stream that yields Result<ContextId>.

pub fn has_member( &self, context_id: &ContextId, public_key: &PublicKey, ) -> Result<bool>

Checks if a given public key is a member of a context in the local datastore.

Arguments

• context_id - The context to check within.
• public_key - The public key of the potential member.

Returns

A Result containing true if the identity is a known member, false otherwise.

pub fn get_context_members( &self, context_id: &ContextId, owned: Option<bool>, ) -> impl Stream<Item = Result<(PublicKey, bool)>>

Retrieves and returns a stream of all members of a given context.

Arguments

• context_id - The context to query for members.
• owned - If Some(true), the stream returns only members for which this node holds the private key. If Some(false) or None, it returns all members.

Returns

A stream of tuples (PublicKey, bool), where the boolean indicates if the identity is owned.

pub async fn execute( &self, context_id: &ContextId, executor: &PublicKey, method: String, payload: Vec<u8>, aliases: Vec<Alias<PublicKey>>, atomic: Option<ContextAtomic>, ) -> Result<ExecuteResponse, ExecuteError>

Sends a request to execute a method within a context.

This is the primary way to interact with the application running inside a context. The request is handled asynchronously by the ContextManager actor.

Arguments

• context_id - The ID of the context where the execution should occur.
• executor - The public key of the identity performing the execution. The executor must be a member of the context.
• method - The string name of the application method to call.
• payload - The input data (e.g., serialized JSON) for the method.
• aliases - A list of public key aliases to use for this specific execution.
• atomic - An optional handle for batching multiple executions into an atomic transaction.

Returns

A Result containing the ExecuteResponse on success, or an ExecuteError on failure.

pub async fn update_application( &self, context_id: &ContextId, application_id: &ApplicationId, identity: &PublicKey, migrate_method: Option<String>, ) -> Result<()>

Sends a request to update the application for a given context. This is an asynchronous operation handled by the ContextManager actor.

Arguments

• context_id - The ID of the context where to update the application.
• application_id - The ID of the new application to switch to.
• identity - The public key of the member authorizing the update.
• migrate_method - Optional name of the migration function to execute.

Returns

An empty Result indicating the outcome of the application update request.

pub async fn delete_context( &self, context_id: &ContextId, ) -> Result<DeleteContextResponse>

Sends a request to delete a context from the local node. This is an asynchronous operation handled by the ContextManager actor. It will remove all associated data for the context from the local datastore.

Arguments

• context_id - The ID of the context to delete.

Returns

A Result containing the DeleteContextResponse from the actor.

Trait Implementations

impl Clone for ContextClient

fn clone(&self) -> ContextClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ContextClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.