Struct LightningClientModule

pub struct LightningClientModule {
    pub cfg: LightningClientConfig,
    pub(crate) notifier: ModuleNotifier<LightningClientStateMachines>,
    pub(crate) redeem_key: KeyPair,
    pub(crate) secp: Secp256k1<All>,
    pub(crate) module_api: DynModuleApi,
    pub(crate) preimage_auth: KeyPair,
    pub(crate) client_ctx: ClientContext<Self>,
    pub(crate) update_gateway_cache_merge: UpdateMerge,
    pub(crate) gateway_conn: Arc<dyn GatewayConnection + Send + Sync>,
}

Client side lightning module

Note that lightning gateways use a different version of client side module.

Fields

cfg: LightningClientConfig

notifier: ModuleNotifier<LightningClientStateMachines>

redeem_key: KeyPair

secp: Secp256k1<All>

module_api: DynModuleApi

preimage_auth: KeyPair

client_ctx: ClientContext<Self>

update_gateway_cache_merge: UpdateMerge

gateway_conn: Arc<dyn GatewayConnection + Send + Sync>

Implementations

impl LightningClientModule

pub(crate) fn new( args: &ClientModuleInitArgs<LightningClientInit>, gateway_conn: Arc<dyn GatewayConnection + Send + Sync>, ) -> Self

pub(crate) async fn get_prev_payment_result( &self, payment_hash: &Hash, dbtx: &mut DatabaseTransaction<'_>, ) -> PaymentResult

pub(crate) fn get_payment_operation_id( payment_hash: &Hash, index: u16, ) -> OperationId

pub(crate) fn get_preimage_authentication(&self, payment_hash: &Hash) -> Hash

Hashes the client’s preimage authentication secret with the provided payment_hash. The resulting hash is used when contacting the gateway to determine if this client is allowed to be shown the preimage.

pub(crate) async fn create_outgoing_output<'a, 'b>( &'a self, operation_id: OperationId, invoice: Bolt11Invoice, gateway: LightningGateway, fed_id: FederationId, rng: impl RngCore + CryptoRng + 'a, ) -> Result<(ClientOutput<LightningOutputV0, LightningClientStateMachines>, ContractId)>

Create an output that incentivizes a Lightning gateway to pay an invoice for us. It has time till the block height defined by timelock, after that we can claim our money back.

pub(crate) async fn create_incoming_output( &self, operation_id: OperationId, invoice: Bolt11Invoice, ) -> Result<(ClientOutput<LightningOutputV0, LightningClientStateMachines>, ContractId)>

Create an output that funds an incoming contract within the federation This directly completes a transaction between users, without involving a gateway

pub(crate) async fn await_receive_success( &self, operation_id: OperationId, ) -> Result<bool, LightningReceiveError>

Returns a bool indicating if it was an external receive

pub(crate) async fn await_claim_acceptance( &self, operation_id: OperationId, ) -> Result<Vec<OutPoint>, LightningReceiveError>

pub(crate) fn create_lightning_receive_output<'a>( &'a self, amount: Amount, description: Bolt11InvoiceDescription<'a>, receiving_key: ReceivingKey, rng: impl RngCore + CryptoRng + 'a, expiry_time: Option<u64>, src_node_id: PublicKey, short_channel_id: u64, route_hints: &[RouteHint], network: Network, ) -> Result<(OperationId, Bolt11Invoice, ClientOutput<LightningOutput, LightningClientStateMachines>, [u8; 32])>

pub async fn select_gateway( &self, gateway_id: &PublicKey, ) -> Option<LightningGateway>

Selects a Lightning Gateway from a given gateway_id from the gateway cache.

pub async fn update_gateway_cache(&self) -> Result<()>

Updates the gateway cache by fetching the latest registered gateways from the federation.

See also Self::update_gateway_cache_continuously.

pub async fn update_gateway_cache_continuously<Fut>( &self, gateways_filter: impl Fn(Vec<LightningGatewayAnnouncement>) -> Fut, ) -> !

where Fut: Future<Output = Vec<LightningGatewayAnnouncement>>,

Continuously update the gateway cache whenever a gateway expires.

The gateways returned by gateway_filters are checked for expiry. Client integrators are expected to call this function in a spawned task.

pub async fn list_gateways(&self) -> Vec<LightningGatewayAnnouncement>

Returns all gateways that are currently in the gateway cache.

pub async fn pay_bolt11_invoice<M: Serialize + MaybeSend + MaybeSync>( &self, maybe_gateway: Option<LightningGateway>, invoice: Bolt11Invoice, extra_meta: M, ) -> Result<OutgoingLightningPayment>

Pays a LN invoice with our available funds using the supplied gateway if one was provided and the invoice is not an internal one. If none is supplied only internal payments are possible.

The gateway can be acquired by calling LightningClientModule::select_gateway.

Can return error of type PayBolt11InvoiceError

pub async fn get_ln_pay_details_for( &self, operation_id: OperationId, ) -> Result<LightningOperationMetaPay>

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

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

Subscribes to a stream of updates about a particular external Lightning payment operation specified by the operation_id.

pub async fn scan_receive_for_user_tweaked<M: Serialize + Send + Sync + Clone>( &self, key_pair: KeyPair, indices: Vec<u64>, extra_meta: M, ) -> Vec<OperationId>

Scan unspent incoming contracts for a payment hash that matches a tweaked keys in the indices vector

pub async fn scan_receive_for_user<M: Serialize + Send + Sync>( &self, key_pair: KeyPair, extra_meta: M, ) -> Result<OperationId>

Scan unspent incoming contracts for a payment hash that matches a public key and claim the incoming contract

pub async fn claim_funded_incoming_contract<M: Serialize + Send + Sync>( &self, key_pair: KeyPair, contract_id: ContractId, extra_meta: M, ) -> Result<OperationId>

Claim the funded, unspent incoming contract by submitting a transaction to the federation and awaiting the primary module’s outputs

pub async fn create_bolt11_invoice<M: Serialize + Send + Sync>( &self, amount: Amount, description: Bolt11InvoiceDescription<'_>, expiry_time: Option<u64>, extra_meta: M, gateway: Option<LightningGateway>, ) -> Result<(OperationId, Bolt11Invoice, [u8; 32])>

Receive over LN with a new invoice

pub async fn create_bolt11_invoice_for_user_tweaked<M: Serialize + Send + Sync>( &self, amount: Amount, description: Bolt11InvoiceDescription<'_>, expiry_time: Option<u64>, user_key: PublicKey, index: u64, extra_meta: M, gateway: Option<LightningGateway>, ) -> Result<(OperationId, Bolt11Invoice, [u8; 32])>

Receive over LN with a new invoice for another user, tweaking their key by the given index

pub async fn create_bolt11_invoice_for_user<M: Serialize + Send + Sync>( &self, amount: Amount, description: Bolt11InvoiceDescription<'_>, expiry_time: Option<u64>, user_key: PublicKey, extra_meta: M, gateway: Option<LightningGateway>, ) -> Result<(OperationId, Bolt11Invoice, [u8; 32])>

Receive over LN with a new invoice for another user

pub(crate) async fn create_bolt11_invoice_internal<M: Serialize + Send + Sync>( &self, amount: Amount, description: Bolt11InvoiceDescription<'_>, expiry_time: Option<u64>, receiving_key: ReceivingKey, extra_meta: M, gateway: Option<LightningGateway>, ) -> Result<(OperationId, Bolt11Invoice, [u8; 32])>

Receive over LN with a new invoice

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

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

pub async fn get_gateway( &self, gateway_id: Option<PublicKey>, force_internal: bool, ) -> Result<Option<LightningGateway>>

Returns a gateway to be used for a lightning operation. If force_internal is true and no gateway_id is specified, no gateway will be selected.

pub async fn wait_for_ln_payment( &self, payment_type: PayType, contract_id: ContractId, return_on_funding: bool, ) -> Result<Option<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, _amount: Amount, _input: &<Self::Common as ModuleCommon>::Input, ) -> Option<Amount>

Returns the fee the processing of this input requires.

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

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>> + Send + 'async_trait>>

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

fn handle_rpc<'life0, 'async_trait>( &'life0 self, method: String, payload: Value, ) -> Pin<Box<dyn Future<Output = BoxStream<'_, Result<Value>>> + Send + 'async_trait>>

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

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 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) -> bool

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, _input_amount: Amount, _output_amount: Amount, ) -> Pin<Box<dyn Future<Output = Result<(ClientInputBundle<<Self::Common as ModuleCommon>::Input, Self::States>, Vec<ClientOutput<<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<Amount, 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>, ) -> 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 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 LightningClientModule

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

Formats the value using the given formatter.