Struct ClientBuilder

pub struct ClientBuilder {
    pub(crate) module_inits: ClientModuleInitRegistry,
    pub(crate) primary_module_instance: Option<ModuleInstanceId>,
    pub(crate) primary_module_kind: Option<ModuleKind>,
    pub(crate) admin_creds: Option<AdminCreds>,
    pub(crate) db_no_decoders: Database,
    pub(crate) meta_service: Arc<MetaService>,
    pub(crate) connector: Connector,
    pub(crate) stopped: bool,
    pub(crate) log_event_added_transient_tx: Sender<EventLogEntry>,
}

Used to configure, assemble and build Client

Fields

module_inits: ClientModuleInitRegistry

primary_module_instance: Option<ModuleInstanceId>

primary_module_kind: Option<ModuleKind>

admin_creds: Option<AdminCreds>

db_no_decoders: Database

meta_service: Arc<MetaService>

connector: Connector

stopped: bool

log_event_added_transient_tx: Sender<EventLogEntry>

Implementations

impl ClientBuilder

pub(crate) fn new(db: Database) -> Self

pub(crate) fn from_existing(client: &Client) -> Self

pub fn with_module_inits(&mut self, module_inits: ClientModuleInitRegistry)

Replace module generator registry entirely

pub fn with_module<M: ClientModuleInit>(&mut self, module_init: M)

Make module generator available when reading the config

pub fn stopped(&mut self)

pub fn with_primary_module(&mut self, primary_module_instance: ModuleInstanceId)

👎Deprecated since 0.6.0: Use with_primary_module_kind instead, as the instance id can’t be known upfront. If you really need the old behavior you can use with_primary_module_instance_id.

Uses this module with the given instance id as the primary module. See ClientModule::supports_being_primary for more information.

Panics

If there was a primary module specified previously

pub fn with_primary_module_instance_id( &mut self, primary_module_instance: ModuleInstanceId, )

You are likely looking for ClientBuilder::with_primary_module_kind. This function is rarely useful and often dangerous, handle with care.

Uses this module with the given instance id as the primary module. See ClientModule::supports_being_primary for more information. Since the module instance id of modules of a specific kind may differ between different federations it is generally not recommended to specify it, but rather to specify the module kind that should be used as primary. See ClientBuilder::with_primary_module_kind.

Panics

If there was a primary module specified previously

pub fn with_primary_module_kind(&mut self, primary_module_kind: ModuleKind)

Uses this module kind as the primary module if present in the config. See ClientModule::supports_being_primary for more information.

Panics

If there was a primary module kind specified previously

pub fn with_meta_service(&mut self, meta_service: Arc<MetaService>)

pub(crate) async fn migrate_database(&self, db: &Database) -> Result<()>

pub fn db_no_decoders(&self) -> &Database

pub async fn load_existing_config(&self) -> Result<ClientConfig>

pub fn set_admin_creds(&mut self, creds: AdminCreds)

pub fn with_connector(&mut self, connector: Connector)

pub fn with_tor_connector(&mut self)

pub(crate) async fn init( self, pre_root_secret: DerivableSecret, config: ClientConfig, api_secret: Option<String>, init_mode: InitMode, ) -> Result<ClientHandle>

pub async fn join( self, pre_root_secret: DerivableSecret, config: ClientConfig, api_secret: Option<String>, ) -> Result<ClientHandle>

Join a new Federation

When a user wants to connect to a new federation this function fetches the federation config and initializes the client database. If a user already joined the federation in the past and has a preexisting database use ClientBuilder::open instead.

Warning: Calling join with a root_secret key that was used previous to join a Federation will lead to all sorts of malfunctions including likely loss of funds.

This should be generally called only if the root_secret key is known not to have been used before (e.g. just randomly generated). For keys that might have been previous used (e.g. provided by the user), it’s safer to call Self::recover which will attempt to recover client module states for the Federation.

A typical “join federation” flow would look as follows:

// Create a root secret, e.g. via fedimint-bip39, see also:
// https://github.com/fedimint/fedimint/blob/master/docs/secret_derivation.md
// let root_secret = …;

// Get invite code from user
let invite_code = InviteCode::from_str("fed11qgqpw9thwvaz7te3xgmjuvpwxqhrzw3jxumrvvf0qqqjpetvlg8glnpvzcufhffgzhv8m75f7y34ryk7suamh8x7zetly8h0v9v0rm")
    .expect("Invalid invite code");
let config = fedimint_api_client::api::net::Connector::default().download_from_invite_code(&invite_code).await
    .expect("Error downloading config");

// Tell the user the federation name, bitcoin network
// (e.g. from wallet module config), and other details
// that are typically contained in the federation's
// meta fields.

// let network = config.get_first_module_by_kind::<WalletClientConfig>("wallet")
//     .expect("Module not found")
//     .network;

println!(
    "The federation name is: {}",
    config.meta::<String>(META_FEDERATION_NAME_KEY)
        .expect("Could not decode name field")
        .expect("Name isn't set")
);

// Open the client's database, using the federation ID
// as the DB name is a common pattern:

// let db_path = format!("./path/to/db/{}", config.federation_id());
// let db = RocksDb::open(db_path).expect("error opening DB");

let client = Client::builder(db).await.expect("Error building client")
    // Mount the modules the client should support:
    // .with_module(LightningClientInit)
    // .with_module(MintClientInit)
    // .with_module(WalletClientInit::default())
    .join(root_secret, config, None)
    .await
    .expect("Error joining federation");

pub async fn download_backup_from_federation( &self, root_secret: &DerivableSecret, config: &ClientConfig, api_secret: Option<String>, ) -> Result<Option<ClientBackup>>

Download most recent valid backup found from the Federation

pub async fn recover( self, root_secret: DerivableSecret, config: ClientConfig, api_secret: Option<String>, backup: Option<ClientBackup>, ) -> Result<ClientHandle>

Join a (possibly) previous joined Federation

Unlike Self::join, recover will run client module recovery for each client module attempting to recover any previous module state.

Recovery process takes time during which each recovering client module will not be available for use.

Calling recovery with a root_secret that was not actually previous used in a given Federation is safe.

pub async fn open( self, pre_root_secret: DerivableSecret, ) -> Result<ClientHandle>

pub(crate) async fn build( self, pre_root_secret: DerivableSecret, config: ClientConfig, api_secret: Option<String>, stopped: bool, ) -> Result<ClientHandle>

Build a Client and start the executor

pub(crate) async fn build_stopped( self, root_secret: DerivableSecret, config: &ClientConfig, api_secret: Option<String>, log_event_added_transient_tx: Sender<EventLogEntry>, ) -> Result<ClientHandle>

Build a Client but do not start the executor

pub(crate) async fn load_init_state(db: &Database) -> InitState

pub(crate) fn decoders(&self, config: &ClientConfig) -> ModuleDecoderRegistry

pub(crate) fn config_decoded( config: &ClientConfig, decoders: &ModuleDecoderRegistry, ) -> Result<ClientConfig, DecodeError>

pub(crate) fn federation_root_secret( root_secret: &DerivableSecret, config: &ClientConfig, ) -> DerivableSecret

Re-derive client’s root_secret using the federation ID. This eliminates the possibility of having the same client root_secret across multiple federations.

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

Register to receiver all new transient (unpersisted) events