Struct ClientHandle

pub struct ClientHandle {
    pub(crate) inner: Option<Arc<Client>>,
}

User handle to the Client instance

On the drop of ClientHandle the client will be shut-down, and resources it used freed.

Notably it ops::Derefs to the Client where most methods live.

Put this in an Arc to clone it (see ClientHandleArc).

Fields

inner: Option<Arc<Client>>

Implementations

impl ClientHandle

pub(crate) fn new(inner: Arc<Client>) -> Self

Create

pub(crate) fn as_inner(&self) -> &Arc<Client>

pub fn start_executor(&self)

pub async fn shutdown(self)

Shutdown the client.

pub(crate) async fn shutdown_inner(&mut self)

pub async fn restart(self) -> Result<ClientHandle>

Restart the client

Returns false if there are other clones of ClientHandle, or starting the client again failed for some reason.

Notably it will re-use the original Database handle, and not attempt to open it again.

impl ClientHandle

pub(crate) fn downgrade(&self) -> ClientWeak

Methods from Deref<Target = Client>

pub async fn create_backup(&self, metadata: Metadata) -> Result<ClientBackup>

Create a backup, include provided metadata

async fn load_previous_backup(&self) -> Option<ClientBackup>

async fn store_last_backup(&self, backup: &ClientBackup)

pub async fn backup_to_federation(&self, metadata: Metadata) -> Result<()>

Prepare an encrypted backup and send it to federation for storing

pub fn validate_backup(&self, backup: &EncryptedClientBackup) -> Result<()>

Validate backup before sending it to federation

pub async fn upload_backup(&self, backup: &EncryptedClientBackup) -> Result<()>

Upload backup to federation

pub async fn download_backup_from_federation( &self, ) -> Result<Option<ClientBackup>>

pub fn get_backup_id(&self) -> PublicKey

Backup id derived from the root secret key (public key used to self-sign backup requests)

fn get_derived_backup_encryption_key(&self) -> LessSafeKey

fn get_derived_backup_signing_key(&self) -> Keypair

pub async fn get_decoded_client_secret<T: Decodable>(&self) -> Result<T>

pub fn api(&self) -> &(dyn IGlobalFederationApi + 'static)

pub fn api_clone(&self) -> DynGlobalApi

pub fn task_group(&self) -> &TaskGroup

Get the TaskGroup that is tied to Client’s lifetime.

pub fn start_executor(self: &Arc<Self>)

pub fn federation_id(&self) -> FederationId

pub(crate) fn context_gen(self: &Arc<Self>) -> ModuleGlobalContextGen

pub async fn config(&self) -> ClientConfig

pub fn api_secret(&self) -> &Option<String>

pub fn decoders(&self) -> &ModuleDecoderRegistry

pub(crate) fn get_module( &self, instance: ModuleInstanceId, ) -> &(dyn IClientModule + Send + Sync)

Returns a reference to the module, panics if not found

pub(crate) fn try_get_module( &self, instance: ModuleInstanceId, ) -> Option<&(dyn IClientModule + Send + Sync)>

pub fn has_module(&self, instance: ModuleInstanceId) -> bool

pub(crate) fn transaction_builder_balance( &self, builder: &TransactionBuilder, ) -> (Amount, Amount)

Returns the input amount and output amount of a transaction

Panics

If any of the input or output versions in the transaction builder are unknown by the respective module.

pub fn get_internal_payment_markers(&self) -> Result<(PublicKey, u64)>

pub fn get_meta(&self, key: &str) -> Option<String>

pub(crate) fn root_secret(&self) -> DerivableSecret

pub async fn add_state_machines( &self, dbtx: &mut DatabaseTransaction<'_>, states: Vec<DynState>, ) -> AddStateMachinesResult

pub async fn get_active_operations(&self) -> HashSet<OperationId>

pub fn operation_log(&self) -> &OperationLog

pub fn meta_service(&self) -> &Arc<MetaService>

Get the meta manager to read meta fields.

pub(crate) async fn finalize_transaction( &self, dbtx: &mut DatabaseTransaction<'_>, operation_id: OperationId, partial_transaction: TransactionBuilder, ) -> Result<(Transaction, Vec<DynState>, Range<u64>)>

Adds funding to a transaction or removes over-funding via change.

pub async fn finalize_and_submit_transaction<F, M>( &self, operation_id: OperationId, operation_type: &str, operation_meta: F, tx_builder: TransactionBuilder, ) -> Result<(TransactionId, Vec<OutPoint>)>

where F: Fn(TransactionId, Vec<OutPoint>) -> M + Clone + MaybeSend + MaybeSync, M: Serialize + MaybeSend,

Add funding and/or change to the transaction builder as needed, finalize the transaction and submit it to the federation.

Errors

The function will return an error if the operation with given ID already exists.

Panics

The function will panic if the database transaction collides with other and fails with others too often, this should not happen except for excessively concurrent scenarios.

pub(crate) async fn finalize_and_submit_transaction_inner( &self, dbtx: &mut DatabaseTransaction<'_>, operation_id: OperationId, tx_builder: TransactionBuilder, ) -> Result<(TransactionId, Vec<OutPoint>)>

pub(crate) async fn transaction_update_stream( &self, operation_id: OperationId, ) -> BoxStream<'static, TxSubmissionStatesSM>

pub async fn operation_exists(&self, operation_id: OperationId) -> bool

pub async fn has_active_states(&self, operation_id: OperationId) -> bool

pub async fn await_primary_module_output( &self, operation_id: OperationId, out_point: OutPoint, ) -> Result<Amount>

Waits for an output from the primary module to reach its final state.

pub fn get_first_module<M: ClientModule>( &self, ) -> Result<ClientModuleInstance<'_, M>>

Returns a reference to a typed module client instance by kind

pub fn get_module_client_dyn( &self, instance_id: ModuleInstanceId, ) -> Result<&(dyn IClientModule + Send + Sync)>

pub fn db(&self) -> &Database

pub async fn transaction_updates( &self, operation_id: OperationId, ) -> TransactionUpdates

Returns a stream of transaction updates for the given operation id that can later be used to watch for a specific transaction being accepted.

pub fn get_first_instance( &self, module_kind: &ModuleKind, ) -> Option<ModuleInstanceId>

Returns the instance id of the first module of the given kind. The primary module will always be returned before any other modules (which themselves are ordered by their instance ID).

pub async fn root_secret_encoding<T: Decodable>(&self) -> Result<T>

Returns the data from which the client’s root secret is derived (e.g. BIP39 seed phrase struct).

pub async fn await_primary_module_outputs( &self, operation_id: OperationId, outputs: Vec<OutPoint>, ) -> Result<Amount>

Waits for outputs from the primary module to reach its final state.

pub async fn get_config_json(&self) -> JsonClientConfig

Returns the config of the client in JSON format.

Compared to the consensus module format where module configs are binary encoded this format cannot be cryptographically verified but is easier to consume and to some degree human-readable.

pub fn primary_module(&self) -> &DynClientModule

Get the primary module

pub async fn get_balance(&self) -> Amount

Balance available to the client for spending

pub async fn subscribe_balance_changes(&self) -> BoxStream<'static, Amount>

Returns a stream that yields the current client balance every time it changes.

pub async fn load_and_refresh_common_api_version(&self) -> Result<ApiVersionSet>

pub async fn get_metadata(&self) -> Metadata

Get the client Metadata

pub async fn set_metadata(&self, metadata: &Metadata)

Set the client Metadata

pub fn has_pending_recoveries(&self) -> bool

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

Wait for all module recoveries to finish

This will block until the recovery task is done with recoveries. Returns success if all recovery tasks are complete (success case), or an error if some modules could not complete the recovery at the time.

A bit of a heavy approach.

pub fn subscribe_to_recovery_progress( &self, ) -> impl Stream<Item = (ModuleInstanceId, RecoveryProgress)>

Subscribe to recover progress for all the modules.

This stream can contain duplicate progress for a module. Don’t use this stream for detecting completion of recovery.

pub async fn wait_for_module_kind_recovery( &self, module_kind: ModuleKind, ) -> Result<()>

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

pub(crate) fn spawn_module_recoveries_task( &self, recovery_sender: Sender<BTreeMap<ModuleInstanceId, RecoveryProgress>>, module_recoveries: BTreeMap<ModuleInstanceId, Pin<Box<dyn Future<Output = Result<()>> + Send>>>, module_recovery_progress_receivers: BTreeMap<ModuleInstanceId, Receiver<RecoveryProgress>>, )

pub async fn get_peer_url_announcements( &self, ) -> BTreeMap<PeerId, SignedApiAnnouncement>

You likely want to use Client::get_peer_urls. This function returns only the announcements and doesn’t use the config as fallback.

pub async fn get_peer_urls(&self) -> BTreeMap<PeerId, SafeUrl>

Returns a list of guardian API URLs

pub async fn invite_code(&self, peer: PeerId) -> Option<InviteCode>

Create an invite code with the api endpoint of the given peer which can be used to download this client config

pub async fn get_guardian_public_keys_blocking( &self, ) -> BTreeMap<PeerId, PublicKey>

Blocks till the client has synced the guardian public key set (introduced in version 0.4) and returns it. Once it has been fetched once this function is guaranteed to return immediately.

pub fn handle_global_rpc( &self, method: String, params: Value, ) -> BoxStream<'_, Result<Value>>

pub async fn log_event<E>(&self, module_id: Option<ModuleInstanceId>, event: E)

where E: Event + Send,

pub async fn log_event_dbtx<E, Cap>( &self, dbtx: &mut DatabaseTransaction<'_, Cap>, module_id: Option<ModuleInstanceId>, event: E, )

where E: Event + Send, Cap: Send,

pub async fn log_event_raw_dbtx<Cap>( &self, dbtx: &mut DatabaseTransaction<'_, Cap>, kind: EventKind, module: Option<(ModuleKind, ModuleInstanceId)>, payload: Vec<u8>, transient: bool, )

where Cap: Send,

pub async fn handle_events<F, R, K>( &self, pos_key: &K, call_fn: F, ) -> Result<()>

where K: DatabaseKey + DatabaseRecord + MaybeSend + MaybeSync + DatabaseRecord<Value = EventLogId>, F: Fn(&mut DatabaseTransaction<'_, NonCommittable>, EventLogEntry) -> R, R: Future<Output = Result<()>>,

pub async fn get_event_log( &self, pos: Option<EventLogId>, limit: u64, ) -> Vec<(EventLogId, EventKind, Option<(ModuleKind, ModuleInstanceId)>, u64, Value)>

pub async fn get_event_log_dbtx<Cap>( &self, dbtx: &mut DatabaseTransaction<'_, Cap>, pos: Option<EventLogId>, limit: u64, ) -> Vec<(EventLogId, EventKind, Option<(ModuleKind, ModuleInstanceId)>, u64, Value)>

where Cap: Send,

pub fn get_event_log_transient_receiver(&self) -> Receiver<EventLogEntry>

Register to receiver all new transient (unpersisted) events

Trait Implementations

impl Debug for ClientHandle

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

Formats the value using the given formatter.

impl Deref for ClientHandle

type Target = Client

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Drop for ClientHandle

We need a separate drop implementation for Client that triggers Executor::stop_executor even though the Drop implementation of ExecutorInner should already take care of that. The reason is that as long as the executor task is active there may be a cycle in the Arc<Client>s such that at least one Executor never gets dropped.

fn drop(&mut self)

Executes the destructor for this type.