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
• ClientStrong 🔒
  Internal self-reference to Client
• ClientWeak 🔒
  Like ClientStrong but using a Weak handle to Client
• 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