Struct GatewayClientModule 

pub struct GatewayClientModule {
    pub(crate) cfg: LightningClientConfig,
    pub notifier: ModuleNotifier<GatewayClientStateMachines>,
    pub redeem_key: Keypair,
    pub(crate) federation_index: u64,
    pub(crate) module_api: DynModuleApi,
    pub(crate) client_ctx: ClientContext<Self>,
    pub lightning_manager: Arc<dyn IGatewayClientV1>,
    pub(crate) connector_registry: ConnectorRegistry,
    pub(crate) intercepted_htlc_lock_pool: LockPool<HtlcCircuitKey>,
}

Client side Lightning module for the gateway.

For the client side Lightning module for normal clients, see fedimint_ln_client::LightningClientModule

Fields

cfg: LightningClientConfig

notifier: ModuleNotifier<GatewayClientStateMachines>

redeem_key: Keypair

federation_index: u64

module_api: DynModuleApi

client_ctx: ClientContext<Self>

lightning_manager: Arc<dyn IGatewayClientV1>

connector_registry: ConnectorRegistry

intercepted_htlc_lock_pool: LockPool<HtlcCircuitKey>

Implementations

impl GatewayClientModule

pub(crate) fn to_gateway_registration_info( &self, route_hints: Vec<RouteHint>, ttl: Duration, fees: RoutingFees, lightning_context: LightningContext, api: SafeUrl, gateway_keypair: Keypair, ) -> LightningGatewayAnnouncement

pub(crate) async fn create_funding_incoming_contract_output_from_htlc( &self, htlc: Htlc, ) -> Result<(OperationId, Amount, ClientOutput<LightningOutputV0>, ClientOutputSM<GatewayClientStateMachines>, ContractId), IncomingSmError>

pub(crate) async fn create_funding_incoming_contract_output_from_swap( &self, swap: SwapParameters, ) -> Result<(OperationId, ClientOutput<LightningOutputV0>, ClientOutputSM<GatewayClientStateMachines>), IncomingSmError>

pub async fn try_register_with_federation( &self, route_hints: Vec<RouteHint>, time_to_live: Duration, fees: RoutingFees, lightning_context: LightningContext, api: SafeUrl, gateway_keypair: Keypair, ) -> bool

Registers the gateway with a federation and reports whether it succeeded.

Detailed errors remain in gateway logs; callers can retain the boolean result without exposing federation internals.

pub async fn remove_from_federation(&self, gateway_keypair: Keypair)

Attempts to remove a gateway’s registration from the federation. Since removing gateway registrations is best effort, this does not return an error and simply emits a warning when the registration cannot be removed.

pub(crate) async fn remove_from_federation_inner( &self, gateway_keypair: Keypair, ) -> Result<()>

Retrieves the signing challenge from each federation peer. Since each peer maintains their own list of registered gateways, the gateway needs to provide a signature that is signed by the private key of the gateway id to remove the registration.

pub async fn gateway_handle_intercepted_htlc( &self, htlc: Htlc, current_block_height: impl Future<Output = Result<u32>>, ) -> Result<OperationId>

Attempt to fulfill an HTLC by buying its preimage from the federation.

LND can replay a still-pending HTLC after interceptor reconnect or gatewayd restart. Since the operation id is deterministic from the payment hash, the replay must not re-fetch the consumed federation offer or submit the same funding transaction again.

We only short-circuit if a GatewayCompleteStateMachine is or was handling the exact same LND circuit. Direct swaps with the same payment hash and different circuits fall through to the normal failure/cancel path. Exact-circuit replays bypass fresh-funding expiry validation so an already-funded operation can still settle after reconnect or restart.

current_block_height resolves to the Lightning backend’s absolute best Bitcoin block height. It is awaited only after replay detection, before any fresh funding.

pub async fn gateway_handle_direct_swap( &self, swap_params: SwapParameters, ) -> Result<OperationId>

Attempt buying preimage from this federation in order to fulfill a pay request in another federation served by this gateway. In direct swap scenario, the gateway DOES NOT send payment over the lightning network

The operation is keyed on the payment hash, so an existing one means the incoming contract for this swap is already funded and only ever pays out one preimage. A second call therefore has nothing to fund; it wants the preimage the first call is buying, and gets it by being handed the operation already in progress for pay::GatewayPayWaitForSwapPreimage to follow. Reporting a failure instead would cancel the outgoing contract that this swap is the other half of, refunding the sender while the recipient still gets paid out of the gateway’s own funds.

pub async fn gateway_subscribe_ln_receive( &self, operation_id: OperationId, ) -> Result<UpdateStreamOrOutcome<GatewayExtReceiveStates>>

Subscribe to updates when the gateway is handling an intercepted HTLC, or direct swap between federations

pub async fn await_completion(&self, operation_id: OperationId)

For the given OperationId, this function will wait until the Complete state machine has finished or failed.

pub async fn gateway_pay_bolt11_invoice( &self, pay_invoice_payload: PayInvoicePayload, ) -> Result<OperationId>

Pay lightning invoice on behalf of federation user

pub async fn gateway_subscribe_ln_pay( &self, operation_id: OperationId, ) -> Result<UpdateStreamOrOutcome<GatewayExtPayStates>>

Trait Implementations

impl ClientModule for GatewayClientModule

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 = GatewayClientContext

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

type States = GatewayClientStateMachines

All possible states this client can submit to the executor

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

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

Returns the fee the processing of this input requires.

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

Returns the fee the processing of this output requires.

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_cli_command<'life0, 'life1, 'async_trait>( &'life0 self, _args: &'life1 [OsString], ) -> Pin<Box<dyn Future<Output = Result<Value, Error>> + Send + 'async_trait>>

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

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

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

fn supports_backup(&self) -> bool

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

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

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>), Error>> + 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. The function returns an error if and only if the client’s funds are not sufficient to create the inputs necessary to fully fund the transaction.

fn await_primary_module_output<'life0, 'async_trait>( &'life0 self, _operation_id: OperationId, _out_point: OutPoint, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + 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<(), Error>> + Send + 'async_trait>>

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

Leave the federation

impl Debug for GatewayClientModule

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

Formats the value using the given formatter.