Struct Client

pub struct Client {

    pub(crate) config: RwLock<ClientConfig>,
    pub(crate) api_secret: Option<String>,
    pub(crate) decoders: ModuleDecoderRegistry,
    pub(crate) db: Database,
    pub(crate) federation_id: FederationId,
    pub(crate) federation_meta: BTreeMap<String, String>,
    pub(crate) primary_module_instance: ModuleInstanceId,
    pub(crate) modules: ClientModuleRegistry,
    pub(crate) module_inits: ClientModuleInitRegistry,
    pub(crate) executor: Executor,
    pub(crate) api: DynGlobalApi,
    pub(crate) root_secret: DerivableSecret,
    pub(crate) operation_log: OperationLog,
    pub(crate) secp_ctx: Secp256k1<All>,
    pub(crate) meta_service: Arc<MetaService>,
    pub(crate) connector: Connector,
    pub(crate) task_group: TaskGroup,
    pub(crate) client_recovery_progress_receiver: Receiver<BTreeMap<ModuleInstanceId, RecoveryProgress>>,
    pub(crate) log_ordering_wakeup_tx: Sender<()>,
    pub(crate) log_event_added_rx: Receiver<()>,
    pub(crate) log_event_added_transient_tx: Sender<EventLogEntry>,
}

Main client type

A handle and API to interacting with a single federation. End user applications that want to support interacting with multiple federations at the same time, will need to instantiate and manage multiple instances of this struct.

Under the hood it is starting and managing service tasks, state machines, database and other resources required.

This type is shared externally and internally, and ClientHandle is responsible for external lifecycle management and resource freeing of the Client.

Fields

config: RwLock<ClientConfig>

api_secret: Option<String>

decoders: ModuleDecoderRegistry

db: Database

federation_id: FederationId

federation_meta: BTreeMap<String, String>

primary_module_instance: ModuleInstanceId

modules: ClientModuleRegistry

module_inits: ClientModuleInitRegistry

executor: Executor

api: DynGlobalApi

root_secret: DerivableSecret

operation_log: OperationLog

secp_ctx: Secp256k1<All>

meta_service: Arc<MetaService>

connector: Connector

task_group: TaskGroup

client_recovery_progress_receiver: Receiver<BTreeMap<ModuleInstanceId, RecoveryProgress>>

Updates about client recovery progress

log_ordering_wakeup_tx: Sender<()>

Internal client sender to wake up log ordering task every time a (unuordered) log event is added.

log_event_added_rx: Receiver<()>

Receiver for events fired every time (ordered) log event is added.

log_event_added_transient_tx: Sender<EventLogEntry>

Implementations

impl 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 async fn download_backup_from_federation_static( api: &DynGlobalApi, root_secret: &DerivableSecret, decoders: &ModuleDecoderRegistry, ) -> Result<Option<ClientBackup>>

Download most recent valid backup found from the Federation

pub fn get_backup_id(&self) -> PublicKey

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

pub fn get_backup_id_static(root_secret: &DerivableSecret) -> PublicKey

fn get_derived_backup_encryption_key_static( secret: &DerivableSecret, ) -> LessSafeKey

Static version of Self::get_derived_backup_encryption_key for testing without creating whole MintClient

fn get_derived_backup_signing_key_static(secret: &DerivableSecret) -> Keypair

Static version of Self::get_derived_backup_signing_key for testing without creating whole MintClient

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>

impl Client

pub async fn builder(db: Database) -> Result<ClientBuilder>

Initialize a client builder that can be configured to create a new client.

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 async fn get_config_from_db(db: &Database) -> Option<ClientConfig>

pub async fn get_api_secret_from_db(db: &Database) -> Option<String>

pub async fn store_encodable_client_secret<T: Encodable>( db: &Database, secret: T, ) -> Result<()>

pub async fn load_decodable_client_secret<T: Decodable>( db: &Database, ) -> Result<T>

pub async fn load_decodable_client_secret_opt<T: Decodable>( db: &Database, ) -> Result<Option<T>>

pub async fn load_or_generate_client_secret(db: &Database) -> Result<[u8; 64]>

pub async fn is_initialized(db: &Database) -> bool

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_gen: F, tx_builder: TransactionBuilder, ) -> Result<OutPointRange>

where F: Fn(OutPointRange) -> 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<OutPointRange>

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 operation_exists_dbtx( dbtx: &mut DatabaseTransaction<'_>, 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<()>

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

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 refresh_peers_api_versions( num_peers: NumPeers, api: DynGlobalApi, db: Database, num_responses_sender: Sender<usize>, )

Query the federation for API version support and then calculate the best API version to use (supported by most guardians).

pub fn supported_api_versions_summary_static( config: &ClientConfig, client_module_init: &ClientModuleInitRegistry, ) -> SupportedApiVersionsSummary

SupportedApiVersionsSummary that the client and its modules support

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

pub(crate) async fn load_and_refresh_common_api_version_static( config: &ClientConfig, module_init: &ClientModuleInitRegistry, api: &DynGlobalApi, db: &Database, task_group: &TaskGroup, ) -> Result<ApiVersionSet>

Load the common api versions to use from cache and start a background process to refresh them.

This is a compromise, so we not have to wait for version discovery to complete every time a Client is being built.

pub(crate) async fn refresh_common_api_version_static( config: &ClientConfig, client_module_init: &ClientModuleInitRegistry, api: &DynGlobalApi, db: &Database, task_group: TaskGroup, ) -> 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 async fn set_metadata_dbtx( dbtx: &mut DatabaseTransaction<'_>, metadata: &Metadata, )

Set the client Metadata

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(crate) async fn run_module_recoveries_task( db: Database, log_ordering_wakeup_tx: Sender<()>, 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(crate) async fn load_peers_last_api_versions( db: &Database, num_peers: NumPeers, ) -> BTreeMap<PeerId, SupportedApiVersionsSummary>

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 Client

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

Formats the value using the given formatter.