Struct LightningClientModule 

pub struct LightningClientModule {
    pub(crate) federation_id: FederationId,
    pub(crate) cfg: LightningClientConfig,
    pub(crate) notifier: ModuleNotifier<LightningClientStateMachines>,
    pub(crate) client_ctx: ClientContext<Self>,
    pub(crate) module_api: DynModuleApi,
    pub(crate) keypair: Keypair,
    pub(crate) lnurl_keypair: Keypair,
    pub(crate) gateway_conn: Arc<dyn GatewayConnection + Send + Sync>,
    pub(crate) admin_auth: Option<ApiAuth>,
}

Fields

federation_id: FederationId

cfg: LightningClientConfig

notifier: ModuleNotifier<LightningClientStateMachines>

client_ctx: ClientContext<Self>

module_api: DynModuleApi

keypair: Keypair

lnurl_keypair: Keypair

gateway_conn: Arc<dyn GatewayConnection + Send + Sync>

admin_auth: Option<ApiAuth>

Implementations

impl LightningClientModule

pub(crate) fn new( federation_id: FederationId, cfg: LightningClientConfig, notifier: ModuleNotifier<LightningClientStateMachines>, client_ctx: ClientContext<Self>, module_api: DynModuleApi, module_root_secret: &DerivableSecret, gateway_conn: Arc<dyn GatewayConnection + Send + Sync>, custom_meta_fn: Arc<dyn Fn() -> Value + Send + Sync>, admin_auth: Option<ApiAuth>, task_group: &TaskGroup, client_span: &Span, ) -> Self

pub(crate) fn spawn_gateway_map_update_task( &self, task_group: &TaskGroup, client_span: &Span, )

pub(crate) async fn update_gateway_map(&self)

pub async fn select_gateway( &self, invoice: Option<Bolt11Invoice>, ) -> Result<(SafeUrl, RoutingInfo), SelectGatewayError>

Selects an available gateway by querying the federation’s registered gateways, checking if one of them match the invoice’s payee public key, then queries the gateway for RoutingInfo to determine if it is online.

pub async fn list_gateways( &self, peer: Option<PeerId>, ) -> Result<Vec<SafeUrl>, ListGatewaysError>

Sends a request to each peer for their registered gateway list and returns a Vec<SafeUrl of all registered gateways to the client.

pub async fn routing_info( &self, gateway: &SafeUrl, ) -> Result<Option<RoutingInfo>, RoutingInfoError>

Requests the RoutingInfo, including fee information, from the gateway available at the SafeUrl.

pub async fn send( &self, invoice: Bolt11Invoice, gateway: Option<SafeUrl>, custom_meta: Value, ) -> Result<OperationId, SendPaymentError>

Pay an invoice. For testing you can optionally specify a gateway to route with, otherwise a gateway will be selected automatically. If the invoice was created by a gateway connected to our federation, the same gateway will be selected to allow for a direct ecash swap. Otherwise we select a random online gateway.

The fee for this payment may depend on the selected gateway but will be limited to one and a half percent plus one hundred satoshis. This fee accounts for the fee charged by the gateway as well as the additional fee required to reliably route this payment over lightning if necessary. Since the gateway has been vetted by at least one guardian we trust it to set a reasonable fee and only enforce a rather high limit.

The absolute fee for a payment can be calculated from the operation meta to be shown to the user in the transaction history.

pub async fn send_with_terms( &self, invoice: Bolt11Invoice, gateway: SafeUrl, send_fee: PaymentFee, expiration_delta: u64, custom_meta: Value, ) -> Result<OperationId, SendWithTermsError>

Pays invoice through gateway at the terms the caller already checked.

Self::send reads the gateway’s terms itself, so a caller that showed the user a fee and asked for approval has no guarantee the funded contract carries that fee: the gateway may change its schedule between the two reads. This variant takes the send_fee and expiration_delta the caller obtained from RoutingInfo::send_parameters and refuses with SendWithTermsError::TermsChanged, before funding anything, if the gateway currently reports different terms. A cheaper fee counts as changed too, so the funded contract always matches what was approved. This binds the funded contract to the approved terms, not the gateway’s acceptance: a gateway that raises its schedule after the check can still refuse the contract, in which case the payment is refunded. The error carries the current terms for re-quoting.

pub(crate) async fn validate_send_invoice( &self, invoice: &Bolt11Invoice, ) -> Result<(u64, OperationId), SendPaymentError>

Checks that invoice is payable by this client and has not been attempted before, returning its amount in millisatoshis and the operation id a payment of it uses.

pub(crate) async fn resolve_send_gateway( &self, invoice: &Bolt11Invoice, gateway: Option<SafeUrl>, ) -> Result<(SafeUrl, RoutingInfo), SendPaymentError>

Resolves the gateway to pay invoice through and its current routing info: the given one, or an automatically selected one when None.

pub(crate) async fn fund_outgoing_contract( &self, invoice: Bolt11Invoice, amount: u64, operation_id: OperationId, gateway_api: SafeUrl, routing_info: RoutingInfo, custom_meta: Value, ) -> Result<OperationId, SendPaymentError>

Funds an outgoing contract for invoice at the terms in routing_info and starts the state machine that hands it to gateway_api.

pub async fn get_invoice_send_status( &self, invoice: &Bolt11Invoice, ) -> Result<InvoiceSendStatus, OperationLookupError>

The status of a previous Self::send for this invoice.

Callers deciding whether an invoice is safe to pay through another mechanism must treat anything but InvoiceSendStatus::NotAttempted as a potential double payment.

pub async fn subscribe_send_operation_state_updates( &self, operation_id: OperationId, ) -> Result<UpdateStreamOrOutcome<SendOperationState>, OperationLookupError>

Subscribe to all state updates of the send operation.

pub async fn await_final_send_operation_state( &self, operation_id: OperationId, ) -> Result<FinalSendOperationState, OperationLookupError>

Await the final state of the send operation.

pub async fn receive( &self, amount: Amount, expiry_secs: u32, description: Bolt11InvoiceDescription, gateway: Option<SafeUrl>, custom_meta: Value, ) -> Result<(Bolt11Invoice, OperationId), ReceiveError>

Request an invoice. For testing you can optionally specify a gateway to generate the invoice, otherwise a random online gateway will be selected automatically.

The total fee for this payment may depend on the chosen gateway but will be limited to half of one percent plus fifty satoshis. Since the selected gateway has been vetted by at least one guardian we trust it to set a reasonable fee and only enforce a rather high limit.

The absolute fee for a payment can be calculated from the operation meta to be shown to the user in the transaction history.

pub async fn receive_with_terms( &self, amount: Amount, expiry_secs: u32, description: Bolt11InvoiceDescription, gateway: SafeUrl, receive_fee: PaymentFee, custom_meta: Value, ) -> Result<(Bolt11Invoice, OperationId), ReceiveWithTermsError>

Requests an invoice from gateway at the receive fee the caller already checked.

Self::receive reads the gateway’s fee itself, so a caller that showed the user a fee has no guarantee the incoming contract is created at that fee: the gateway may change its schedule between the two reads. This variant takes the receive_fee the caller obtained from RoutingInfo::receive_fee and refuses with ReceiveWithTermsError::TermsChanged, before creating anything, if the gateway currently reports a different fee. A cheaper fee counts as changed too, so the contract always matches what was approved; the error carries the current fee for re-quoting.

pub(crate) async fn resolve_receive_gateway( &self, gateway: Option<SafeUrl>, ) -> Result<(SafeUrl, RoutingInfo), ReceiveError>

Resolves the gateway to request an invoice from and its current routing info: the given one, or an automatically selected one when None.

pub(crate) async fn select_receive_gateway( &self, ) -> Result<(SafeUrl, RoutingInfo), SelectGatewayError>

Selects the first registered gateway that is online and currently accepts incoming payments for this federation. A gateway that answers but has turned receives off is skipped rather than handed an invoice request it would refuse.

pub(crate) async fn receive_with_routing_info( &self, amount: Amount, expiry_secs: u32, description: Bolt11InvoiceDescription, gateway: SafeUrl, routing_info: RoutingInfo, custom_meta: Value, ) -> Result<(Bolt11Invoice, OperationId), ReceiveError>

Creates the incoming contract locked to a public key derived from our static module public key, fetches its invoice from gateway at the terms in routing_info, then starts the receive operation.

pub async fn receive_fee_quote( &self, amount: Amount, ) -> Result<FeeQuote, TransactionSubmitError>

Computes the federation fee a receive of amount would incur, without submitting anything.

When the incoming contract is claimed, the client submits a transaction with a single Lightning input worth the contract amount; the primary module balances it by minting the change credited to the wallet. This quotes the fee of that transaction — the Lightning input fee, the mint output fees, and any sub-denomination dust — via the shared, module-agnostic fee quote.

The gateway’s off-chain Lightning fee is deliberately excluded: this is only the fee of the on-federation transaction. For that reason the quote is taken on amount directly (rather than the gateway-reduced contract amount), and no gateway round-trip is needed.

pub(crate) async fn is_worth_claiming(&self, amount: Amount) -> bool

Whether an incoming contract worth amount is worth claiming, i.e. whether claiming it would leave the wallet better off than leaving it.

This is the computed counterpart of a fixed dust limit: it prices the actual claim - the lightning input fee at this federation’s fee consensus, the change the primary module has to mint, and the sub-denomination remainder that cannot be minted at all - rather than assuming a floor. A quote that fails outright is the same verdict: the claim spends the contract as the transaction’s only input, so a fee larger than the contract leaves a transaction that cannot be balanced.

pub async fn send_fee_quote( &self, amount: Amount, ) -> Result<FeeQuote, TransactionSubmitError>

Computes the federation fee a send funding an outgoing contract worth amount would incur, without submitting anything.

When a payment is sent, the client submits a transaction with a single Lightning output (the outgoing contract) worth amount; the primary module balances it by spending ecash to fund the contract and minting any change. This quotes the fee of that transaction — the Lightning output fee, the mint input fees on the funding notes, any mint change output fees, and sub-denomination dust — via the shared, module-agnostic fee quote.

The gateway’s off-chain Lightning fee is deliberately excluded: it is part of the contract amount the gateway claims, not the on-federation transaction fee. So amount is the full outgoing contract value (send_fee.add_to(invoice_amount)).

pub async fn spendable_amount( &self, balance: Amount, gateway: Option<SafeUrl>, ) -> Result<Amount, SpendableAmountError>

Computes the largest invoice amount the client can pay in full out of balance, i.e. the amount to request an invoice for in order to spend (close to) the entire balance.

Paying an invoice deducts two kinds of fee from the balance:

• the gateway fee, which is added on top of the invoice amount to form the outgoing contract (send_fee.add_to(invoice_amount)), and
• the federation fee of funding that contract — the Lightning output fee, the mint input fees on the funding notes, the mint output fees on any change, and sub-denomination dust — as quoted by Self::send_fee_quote.

balance is the client’s current Bitcoin balance (e.g. from Client::get_balance_for_btc). gateway optionally pins the gateway whose fee schedule to use; if None one is selected automatically, the same way Self::send does when no gateway is given. The gateway’s default send fee is used — the higher of its two send fees, applied to a Lightning swap rather than a direct fedimint-to-fedimint swap — so the returned amount stays payable even when the eventual invoice is routed over Lightning.

The maximum payable amount is found by binary search over the real fee quote (see [max_affordable_send_amount]) rather than a closed form, because the federation fee is stepwise in the amount. The quote is point-in-time and moves with the balance, exactly like Self::send_fee_quote; the eventual Self::send remains the source of truth and may still fail if balance or gateway state changes in between.

Returns SpendableAmountError::BalanceTooLow if the balance cannot cover even the smallest payable amount plus fees, and SpendableAmountError::Quote if the fee probe itself failed; only the first of the two says the wallet is short. Any LNURL minSendable/maxSendable bounds are the caller’s responsibility to apply. The remaining variants of SpendableAmountError are gateway-side, and none of them means the wallet is short.

pub(crate) async fn receive_incoming_contract( &self, sk: SecretKey, contract: IncomingContract, operation_meta: LightningOperationMeta, ) -> Option<OperationId>

pub(crate) fn recover_contract_keys( &self, sk: SecretKey, contract: &IncomingContract, ) -> Option<(Keypair, AggregateDecryptionKey)>

pub async fn subscribe_receive_operation_state_updates( &self, operation_id: OperationId, ) -> Result<UpdateStreamOrOutcome<ReceiveOperationState>, OperationLookupError>

Subscribe to all state updates of the receive operation.

pub async fn await_final_receive_operation_state( &self, operation_id: OperationId, ) -> Result<FinalReceiveOperationState, OperationLookupError>

Await the final state of the receive operation.

pub async fn generate_lnurl( &self, recurringd: SafeUrl, gateway: Option<SafeUrl>, ) -> Result<String, GenerateLnurlError>

Generate an lnurl for the client. You can optionally specify a gateway to use for testing purposes.

pub(crate) fn spawn_receive_lnurl_task( &self, custom_meta_fn: Arc<dyn Fn() -> Value + Send + Sync>, task_group: &TaskGroup, client_span: &Span, )

pub(crate) async fn receive_lnurl(&self, custom_meta: Value)

Trait Implementations

impl ClientModule for LightningClientModule

type Init = LightningClientInit

type Common = LightningModuleTypes

Common module types shared between client and server

type Backup = NoModuleBackup

Data stored in regular backups so that restoring doesn’t have to start from epoch 0

type ModuleStateMachineContext = LightningClientContext

Data and API clients available to state machine transitions of this module

type States = LightningClientStateMachines

All possible states this client can submit to the executor

fn context(&self) -> Self::ModuleStateMachineContext

fn input_fee( &self, amounts: &Amounts, _input: &<Self::Common as ModuleCommon>::Input, ) -> Option<Amounts>

Returns the fee the processing of this input requires.

fn output_fee( &self, amounts: &Amounts, _output: &<Self::Common as ModuleCommon>::Output, ) -> Option<Amounts>

Returns the fee the processing of this output requires.

fn handle_cli_command<'life0, 'life1, 'async_trait>( &'life0 self, args: &'life1 [OsString], ) -> Pin<Box<dyn Future<Output = Result<Value, ClientModuleError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Runs a fedimint-cli module command, given as its arguments.

fn decoder() -> Decoder

fn kind() -> ModuleKind

fn start<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: Sync + 'async_trait,

Initialize client.

fn handle_rpc<'life0, 'async_trait>( &'life0 self, _method: String, _request: Value, ) -> Pin<Box<dyn Future<Output = Pin<Box<dyn Stream<Item = Result<Value, ClientModuleError>> + Send + 'life0>>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: Sync + 'async_trait,

Serves a JSON request, such as one fedimint-client-rpc forwards.

fn supports_backup(&self) -> bool

fn backup<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Self::Backup, ClientModuleError>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: Sync + 'async_trait,

The module’s part of a client backup.

fn supports_being_primary(&self) -> PrimaryModuleSupport

Does this module support being a primary module

fn create_final_inputs_and_outputs<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _dbtx: &'life1 mut DatabaseTransaction<'life2>, _operation_id: OperationId, _unit: AmountUnit, _input_amount: Amount, _output_amount: Amount, ) -> Pin<Box<dyn Future<Output = Result<(ClientInputBundle<<Self::Common as ModuleCommon>::Input, Self::States>, ClientOutputBundle<<Self::Common as ModuleCommon>::Output, Self::States>), ClientModuleError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: Sync + 'async_trait,

Creates all inputs and outputs necessary to balance the transaction.

fn await_primary_module_output<'life0, 'async_trait>( &'life0 self, _operation_id: OperationId, _out_point: OutPoint, ) -> Pin<Box<dyn Future<Output = Result<(), ClientModuleError>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: Sync + 'async_trait,

Waits for the funds from an output created by [Self::create_final_inputs_and_outputs] to become available. This function returning typically implies a change in the output of [Self::get_balance].

fn get_balance<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _dbtx: &'life1 mut DatabaseTransaction<'life2>, _unit: AmountUnit, ) -> Pin<Box<dyn Future<Output = Amount> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: Sync + 'async_trait,

Returns the balance held by this module and available for funding transactions.

fn get_balances<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _dbtx: &'life1 mut DatabaseTransaction<'life2>, ) -> Pin<Box<dyn Future<Output = Amounts> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: Sync + 'async_trait,

Returns the balance held by this module and available for funding transactions.

fn subscribe_balance_changes<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Pin<Box<dyn Stream<Item = ()> + Send>>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: Sync + 'async_trait,

Returns a stream that will output the updated module balance each time it changes.

fn leave<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _dbtx: &'life1 mut DatabaseTransaction<'life2>, ) -> Pin<Box<dyn Future<Output = Result<(), ClientModuleError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: Sync + 'async_trait,

Leave the federation

impl Clone for LightningClientModule

fn clone(&self) -> LightningClientModule

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LightningClientModule

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.