Crate fedimint_client

Client library

Notably previous crate became fedimint_client_module and the project is gradually moving things, that are irrelevant to the interface between client and client modules.

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 fedimint_client_module::module::ClientModule trait and a factory struct implementing fedimint_client_module::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 crate::sm::executor::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 fedimint_client_module::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 fedimint_client_module::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_client_module as module;

Modules

api

Re-exporting of everything from fedimint_client_module

api_announcements 🔒

Federation Api announcement handling

api_version_discovery

Re-exporting of everything from fedimint_client_module

backup

Client backup

client 🔒

Core Client

db

Database keys used by the client

envs

Re-exporting of everything from fedimint_client_module

meta

Management of meta fields

module_init

oplog

secret

Re-exporting of everything from fedimint_client_module

sm

transaction

Re-exporting of everything from fedimint_client_module

Macros

sm_enum_variant_translation

Re-exporting of everything from fedimint_client_module

Structs

AdminCreds

Re-exporting of everything from fedimint_client_module

Client

Main client type

ClientBuilder

Used to configure, assemble and build Client

ClientHandle

User handle to the Client instance

ClientModuleInstance

Re-exporting of everything from fedimint_client_module

DynGlobalClientContext

Re-exporting of everything from fedimint_client_module

GetInviteCodeRequest

Re-exporting of everything from fedimint_client_module

ModuleKind

Re-exporting of everything from fedimint_client_module

ModuleRecoveryCompleted

Re-exporting of everything from fedimint_client_module

ModuleRecoveryStarted

Re-exporting of everything from fedimint_client_module

OperationId

Re-exporting of everything from fedimint_client_module

TransactionUpdates

Re-exporting of everything from fedimint_client_module

TxAcceptedEvent

Re-exporting of everything from fedimint_client_module

TxCreatedEvent

Re-exporting of everything from fedimint_client_module

TxRejectedEvent

Re-exporting of everything from fedimint_client_module

Enums

AddStateMachinesError

Re-exporting of everything from fedimint_client_module

Traits

ClientModule

Re-exporting of everything from fedimint_client_module

IGlobalClientContext

Re-exporting of everything from fedimint_client_module

IInput

Re-exporting of everything from fedimint_client_module

IOutput

Re-exporting of everything from fedimint_client_module

Type Aliases

AddStateMachinesResult

Re-exporting of everything from fedimint_client_module

ClientHandleArc

An alias for a reference counted ClientHandle

InstancelessDynClientInput

Re-exporting of everything from fedimint_client_module

InstancelessDynClientInputBundle

Re-exporting of everything from fedimint_client_module

InstancelessDynClientInputSM

Re-exporting of everything from fedimint_client_module

InstancelessDynClientOutput

Re-exporting of everything from fedimint_client_module

InstancelessDynClientOutputBundle

Re-exporting of everything from fedimint_client_module

InstancelessDynClientOutputSM

Re-exporting of everything from fedimint_client_module

ModuleGlobalContextGen

Re-exporting of everything from fedimint_client_module

ModuleInstanceId

Re-exporting of everything from fedimint_client_module

StateGenerator

Re-exporting of everything from fedimint_client_module