Crate fedimint_client

Client library for fedimintd

This library provides a client interface to build module clients that can be plugged together into a fedimint client that exposes a high-level interface for application authors to integrate with.

Module Clients

Module clients have to at least implement the module::ClientModule trait and a factory struct implementing module::init::ClientModuleInit. The ClientModule trait defines the module types (tx inputs, outputs, etc.) as well as the module’s state machines.

State machines

State machines are spawned when starting operations and drive them forward in the background. All module state machines are run by a central sm::Executor. This means typically starting an operation shall return instantly.

For example when doing a deposit the function starting it would immediately return a deposit address and a OperationId (important concept, highly recommended to read the docs) while spawning a state machine checking the blockchain for incoming bitcoin transactions. The progress of these state machines can then be observed using the operation id, but no further user interaction is required to drive them forward.

State Machine Contexts

State machines have access to both a global context as well as to a module-specific context.

The global context provides access to the federation API and allows to claim module outputs (and transferring the value into the client’s wallet), which can be used for refunds.

The client-specific context can be used for other purposes, such as supplying config to the state transitions or giving access to other APIs (e.g. LN gateway in case of the lightning module).

Extension traits

The modules themselves can only create inputs and outputs that then have to be combined into transactions by the user and submitted via Client::finalize_and_submit_transaction. To make this easier most module client implementations contain an extension trait which is implemented for Client and allows to create the most typical fedimint transactions with a single function call.

To observe the progress each high level operation function should be accompanied by one returning a stream of high-level operation updates. Internally that stream queries the state machines belonging to the operation to determine the high-level operation state.

Primary Modules

Not all modules have the ability to hold money for long. E.g. the lightning module and its smart contracts are only used to incentivize LN payments, not to hold money. The mint module on the other hand holds e-cash note and can thus be used to fund transactions and to absorb change. Module clients with this ability should implement ClientModule::supports_being_primary and related methods.

For a example of a client module see the mint client.

Client

The Client struct is the main entry point for application authors. It is constructed using its builder which can be obtained via Client::builder. The supported module clients have to be chosen at compile time while the actually available ones will be determined by the config loaded at runtime.

For a hacky instantiation of a complete client see the ng subcommand of fedimint-cli.

Re-exports

pub use fedimint_derive_secret as derivable_secret;

Modules

api

api_announcements

api_version_discovery 🔒

backup

Client backup

db

Database keys used by the client

envs

Environment variables

meta

Management of meta fields

module

Module client interface definitions

oplog

Operation log subsystem of the client

secret

Secret handling & derivation

sm

Client state machine interfaces and executor implementation

transaction

Structs and interfaces to construct Fedimint transactions

Macros

sm_enum_variant_translation

Structs

AdminCreds

Admin (guardian) identification and authentication

Client

Main client type

ClientBuilder

Used to configure, assemble and build Client

ClientHandle

User handle to the Client instance

ClientModuleInstance

Resources particular to a module instance

DynGlobalClientContext

Global state and functionality provided to all state machines running in the client

GetInviteCodeRequest 🔒

ModuleGlobalClientContext 🔒

Global state given to a specific client module and state. It is aware inside which module instance and operation it is used and to avoid module being aware of their instance id etc.

ModuleRecoveryCompleted

ModuleRecoveryStarted

TransactionUpdates

See Client::transaction_updates

TxAcceptedEvent

TxCreatedEvent

TxRejectedEvent

Enums

AddStateMachinesError

Constants

SUPPORTED_CORE_API_VERSIONS 🔒

List of core api versions supported by the implementation. Notably major version is the one being supported, and corresponding minor version is the one required (for given major version).

Traits

IGlobalClientContext

Functions

box_up_state 🔒

Not sure why I couldn’t just directly call Box::new ins states_to_instanceless_dyn, but this fixed it.

client_decoders

get_decoded_client_secret

Fetches the encoded client secret from the database and decodes it. If an encoded client secret is not present in the database, or if decoding fails, an error is returned.

states_add_instance 🔒

states_to_instanceless_dyn 🔒

Type Aliases

AddStateMachinesResult

ClientHandleArc

An alias for a reference counted ClientHandle

InstancelessDynClientInput

InstancelessDynClientInputBundle

InstancelessDynClientInputSM

InstancelessDynClientOutput

InstancelessDynClientOutputBundle

InstancelessDynClientOutputSM

ModuleGlobalContextGen