Expand description
§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§
- Client backup
- Database keys used by the client
- Environment variables
- Management of meta fields
- Module client interface definitions
- Operation log subsystem of the client
- Secret handling & derivation
- Client state machine interfaces and executor implementation
- Structs and interfaces to construct Fedimint transactions
Macros§
Structs§
- Admin (guardian) identification and authentication
- Main client type
- Used to configure, assemble and build
Client
- User handle to
Client
- Resources particular to a module instance
- Global state and functionality provided to all state machines running in the client
Enums§
Traits§
Functions§
- 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.