Struct uniffi_lipalightninglib::LightningNode

pub struct LightningNode { /* private fields */ }

The main class/struct of this library. Constructing an instance will initiate the Lightning node and run it in the background. As long as an instance of LightningNode is held, the node will continue to run in the background. Dropping the instance will start a deinit process.

Implementations

impl LightningNode

pub fn new( config: Config, events_callback: Box<dyn EventsCallback> ) -> Result<Self>

Create a new instance of LightningNode.

Parameters:

• config - configuration parameters
• events_callback - a callbacks interface for the consumer of this library to be notified of certain events.

Requires network: yes

pub fn get_node_info(&self) -> Result<NodeInfo>

Request some basic info about the node

Requires network: no

pub fn query_lsp_fee(&self) -> Result<LspFee>

When receiving payments, a new channel MAY be required. A fee will be charged to the user. This does NOT impact sending payments. Get information about the fee charged by the LSP for opening new channels

Requires network: no

pub fn calculate_lsp_fee( &self, amount_sat: u64 ) -> Result<CalculateLspFeeResponse>

Calculate the actual LSP fee for the given amount of an incoming payment. If the already existing inbound capacity is enough, no new channel is required.

Parameters:

• amount_sat - amount in sats to compute LSP fee for

For the returned fees to be guaranteed to be accurate, the returned lsp_fee_params must be provided to LightningNode::create_invoice

Requires network: yes

pub fn get_payment_amount_limits(&self) -> Result<PaymentAmountLimits>

Get the current limits for the amount that can be transferred in a single payment. Currently there are only limits for receiving payments. The limits (partly) depend on the channel situation of the node, so it should be called again every time the user is about to receive a payment. The limits stay the same regardless of what amount wants to receive (= no changes while he’s typing the amount)

Requires network: no

pub fn create_invoice( &self, amount_sat: u64, lsp_fee_params: Option<OpeningFeeParams>, description: String, metadata: InvoiceCreationMetadata ) -> Result<InvoiceDetails>

Create an invoice to receive a payment with.

Parameters:

• amount_sat - the smallest amount of sats required for the node to accept the incoming payment (sender will have to pay fees on top of that amount)
• lsp_fee_params - the params that will be used to determine the lsp fee. Can be obtained from LightningNode::calculate_lsp_fee to guarantee predicted fees are the ones charged.
• description - a description to be embedded into the created invoice
• metadata - additional data about the invoice creation used for analytics purposes, used to improve the user experience

Requires network: yes

pub fn parse_phone_number_prefix( &self, phone_number_prefix: String ) -> Result<(), ParsePhoneNumberPrefixError>

Parse a phone number prefix, check against the list of allowed countries (set in Config::phone_number_allowed_countries_iso_3166_1_alpha_2). The parser is not strict, it parses some invalid prefixes as valid.

Requires network: no

pub fn parse_phone_number_to_lightning_address( &self, phone_number: String ) -> Result<String, ParsePhoneNumberError>

Parse a phone number, check against the list of allowed countries (set in Config::phone_number_allowed_countries_iso_3166_1_alpha_2).

Returns a possible lightning address, which can be checked for existence with LightningNode::decode_data.

Requires network: no

pub fn decode_data(&self, data: String) -> Result<DecodedData, DecodeDataError>

Decode a user-provided string (usually obtained from QR-code or pasted).

Requires network: yes

pub fn get_payment_max_routing_fee_mode( &self, amount_sat: u64 ) -> MaxRoutingFeeMode

Get the max routing fee mode that will be employed to restrict the fees for paying a given amount in sats

Requires network: no

pub fn get_invoice_affordability( &self, amount_sat: u64 ) -> Result<InvoiceAffordability>

Checks if the given amount could be spent on an invoice.

Parameters:

• amount - The to be spent amount.

Requires network: no

pub fn pay_invoice( &self, invoice_details: InvoiceDetails, metadata: PaymentMetadata ) -> PayResult<()>

Start an attempt to pay an invoice. Can immediately fail, meaning that the payment couldn’t be started. If successful, it doesn’t mean that the payment itself was successful (funds received by the payee). After this method returns, the consumer of this library will learn about a successful/failed payment through the callbacks EventsCallback::payment_sent and EventsCallback::payment_failed.

Parameters:

• invoice_details - details of an invoice decode by LightningNode::decode_data
• metadata - additional meta information about the payment, used by analytics to improve the user experience.

Requires network: yes

pub fn pay_open_invoice( &self, invoice_details: InvoiceDetails, amount_sat: u64, metadata: PaymentMetadata ) -> PayResult<()>

Similar to LightningNode::pay_invoice with the difference that the passed in invoice does not have any payment amount specified, and allows the caller of the method to specify an amount instead.

Additional Parameters:

• amount_sat - amount in sats to be paid

Requires network: yes

pub fn pay_lnurlp( &self, lnurl_pay_request_data: LnUrlPayRequestData, amount_sat: u64, comment: Option<String> ) -> LnUrlPayResult<String>

Pay an LNURL-pay the provided amount.

Parameters:

• lnurl_pay_request_data - LNURL-pay request data as obtained from LightningNode::decode_data
• amount_sat - amount to be paid
• comment - optional comment to be sent to payee (max_comment_length in LnUrlPayDetails must be respected)

Returns the payment hash of the payment.

Requires network: yes

pub fn list_recipients(&self) -> Result<Vec<Recipient>>

List recipients from the most recent used.

Returns a list of recipients (lightning addresses or phone numbers for now).

Requires network: no

pub fn withdraw_lnurlw( &self, lnurl_withdraw_request_data: LnUrlWithdrawRequestData, amount_sat: u64 ) -> Result<String, Error<LnUrlWithdrawErrorCode>>

Withdraw an LNURL-withdraw the provided amount.

A successful return means the LNURL-withdraw service has started a payment. Only after the event EventsCallback::payment_received can the payment be considered received.

Parameters:

• lnurl_withdraw_request_data - LNURL-withdraw request data as obtained from LightningNode::decode_data
• amount_sat - amount to be withdraw

Returns the payment hash of the payment.

Requires network: yes

pub fn get_latest_activities( &self, number_of_completed_activities: u32 ) -> Result<ListActivitiesResponse>

Get a list of the latest activities

Parameters:

• number_of_completed_activities - the maximum number of completed activities that will be returned

Requires network: no

pub fn get_incoming_payment(&self, hash: String) -> Result<IncomingPaymentInfo>

Get an incoming payment by its payment hash.

Parameters:

• hash - hex representation of payment hash

Requires network: no

pub fn get_outgoing_payment(&self, hash: String) -> Result<OutgoingPaymentInfo>

Get an outgoing payment by its payment hash.

Parameters:

• hash - hex representation of payment hash

Requires network: no

pub fn get_activity(&self, hash: String) -> Result<Activity>

Get an activity by its payment hash.

Parameters:

• hash - hex representation of payment hash

Requires network: no

pub fn set_payment_personal_note( &self, payment_hash: String, note: String ) -> Result<()>

Set a personal note on a specific payment.

Parameters:

• payment_hash - The hash of the payment for which a personal note will be set.
• note - The personal note.

Requires network: no

pub fn foreground(&self)

Call the method when the app goes to foreground, such that the user can interact with it. The library starts running the background tasks more frequently to improve user experience.

Requires network: no

pub fn background(&self)

Call the method when the app goes to background, such that the user can not interact with it. The library stops running some unnecessary tasks and runs necessary tasks less frequently. It should save battery and internet traffic.

Requires network: no

pub fn list_currency_codes(&self) -> Vec<String>

List codes of supported fiat currencies. Please keep in mind that this method doesn’t make any network calls. It simply retrieves previously fetched values that are frequently updated by a background task.

The fetched list will be persisted across restarts to alleviate the consequences of a slow or unresponsive exchange rate service. The method will return an empty list if there is nothing persisted yet and the values are not yet fetched from the service.

Requires network: no

pub fn get_exchange_rate(&self) -> Option<ExchangeRate>

Get exchange rate on the BTC/default currency pair Please keep in mind that this method doesn’t make any network calls. It simply retrieves previously fetched values that are frequently updated by a background task.

The fetched exchange rates will be persisted across restarts to alleviate the consequences of a slow or unresponsive exchange rate service.

The return value is an optional to deal with the possibility of no exchange rate values being known.

Requires network: no

pub fn change_fiat_currency(&self, fiat_currency: String)

Change the fiat currency (ISO 4217 currency code) - not all are supported The method LightningNode::list_currency_codes can used to list supported codes.

Requires network: no

pub fn change_timezone_config(&self, timezone_config: TzConfig)

Change the timezone config.

Parameters:

• timezone_config - the user’s current timezone

Requires network: no

pub fn accept_pocket_terms_and_conditions( &self, version: i64, fingerprint: String ) -> Result<()>

Accepts Pocket’s T&C.

Parameters:

• version - the version number being accepted.
• fingerprint - the fingerprint of the version being accepted.

Requires network: yes

pub fn get_terms_and_conditions_status( &self, terms_and_conditions: TermsAndConditions ) -> Result<TermsAndConditionsStatus>

Similar to get_terms_and_conditions_status with the difference that this method is pre-filling the environment and seed based on the node configuration.

Requires network: yes

pub fn register_fiat_topup( &self, email: Option<String>, user_iban: String, user_currency: String ) -> Result<FiatTopupInfo>

Register for fiat topups. Returns information that can be used by the user to transfer fiat to the 3rd party exchange service. Once the 3rd party exchange receives funds, the user will be able to withdraw sats using LNURL-w.

Parameters:

• email - this email will be used to send status information about different topups
• user_iban - the user will send fiat from this iban
• user_currency - the fiat currency (ISO 4217 currency code) that will be sent for exchange. Not all are supported. A consumer of this library should find out about available ones using other sources.

Requires network: yes

pub fn reset_fiat_topup(&self) -> Result<()>

Resets a previous fiat topups registration.

Requires network: no

pub fn hide_topup(&self, id: String) -> Result<()>

Hides the topup with the given id. Can be called on expired topups so that they stop being returned by LightningNode::query_uncompleted_offers.

Topup id can be obtained from OfferKind::Pocket.

Requires network: yes

pub fn list_action_required_items(&self) -> Result<Vec<ActionRequiredItem>>

List action required items.

Returns a list of actionable items. They can be:

• Uncompleted offers (either available for collection or failed).
• Unresolved failed swaps.
• Available funds resulting from channel closes.

Requires network: yes

pub fn hide_channel_closes_funds_available_action_required_item( &self ) -> Result<()>

Hides the channel close action required item in case the amount cannot be recovered due to it being too small. The item will reappear once the amount of funds changes or onchain-fees go down enough to make the amount recoverable.

Requires network: no

pub fn hide_unresolved_failed_swap_action_required_item( &self, failed_swap_info: FailedSwapInfo ) -> Result<()>

Hides the unresolved failed swap action required item in case the amount cannot be recovered due to it being too small. The item will reappear once the onchain-fees go down enough to make the amount recoverable.

Requires network: no

pub fn query_uncompleted_offers(&self) -> Result<Vec<OfferInfo>>

Get a list of unclaimed fund offers

Requires network: yes

pub fn calculate_lightning_payout_fee(&self, offer: OfferInfo) -> Result<Amount>

Calculates the lightning payout fee for an uncompleted offer.

Parameters:

• offer - An uncompleted offer for which the lightning payout fee should get calculated.

Requires network: yes

pub fn request_offer_collection(&self, offer: OfferInfo) -> Result<String>

Request to collect the offer (e.g. a Pocket topup). A payment hash will be returned to track incoming payment. The offer collection might be considered successful once EventsCallback::payment_received is called, or the PaymentState of the respective payment becomes PaymentState::Succeeded.

Parameters:

• offer - An offer that is still valid for collection. Must have its lnurlw field filled in.

Requires network: yes

pub fn register_notification_token( &self, notification_token: String, language_iso_639_1: String, country_iso_3166_1_alpha_2: String ) -> Result<()>

Registers a new notification token. If a token has already been registered, it will be updated.

Requires network: yes

pub fn get_wallet_pubkey_id(&self) -> Result<String>

Get the wallet UUID v5 from the wallet pubkey

If the auth flow has never succeeded in this Auth instance, this method will require network access.

Requires network: yes

pub fn get_payment_uuid(&self, payment_hash: String) -> Result<String>

Get the payment UUID v5 from the payment hash

Returns a UUID v5 derived from the payment hash. This will always return the same output given the same input.

Parameters:

• payment_hash - a payment hash represented in hex

Requires network: no

pub fn query_onchain_fee_rate(&self) -> Result<u32>

Query the current recommended on-chain fee rate.

This is useful to obtain a fee rate to be used for LightningNode::sweep_funds_from_channel_closes.

Requires network: yes

pub fn prepare_sweep_funds_from_channel_closes( &self, address: String, onchain_fee_rate: u32 ) -> Result<SweepInfo, RedeemOnchainError>

Prepares a sweep of all available on-chain funds to the provided on-chain address.

Parameters:

• address - the funds will be sweeped to this address
• onchain_fee_rate - the fee rate that should be applied for the transaction. The recommended on-chain fee rate can be queried using LightningNode::query_onchain_fee_rate

Returns information on the prepared sweep, including the exact fee that results from using the provided fee rate. The method LightningNode::sweep_funds_from_channel_closes can be used to broadcast the sweep transaction.

Requires network: yes

pub fn sweep_funds_from_channel_closes( &self, sweep_info: SweepInfo ) -> Result<String>

Sweeps all available on-chain funds to the specified on-chain address.

Parameters:

• sweep_info - a prepared sweep info that can be obtained using LightningNode::prepare_sweep_funds_from_channel_closes

Returns the txid of the sweep transaction.

Requires network: yes

pub fn generate_swap_address( &self, lsp_fee_params: Option<OpeningFeeParams> ) -> Result<SwapAddressInfo, ReceiveOnchainError>

Generates a Bitcoin on-chain address that can be used to topup the local LN wallet from an external on-chain wallet.

Funds sent to this address should conform to the min and max values provided within SwapAddressInfo.

If a swap is in progress, this method will return an error.

Parameters:

• lsp_fee_params - the lsp fee parameters to be used if a new channel needs to be opened. Can be obtained using LightningNode::calculate_lsp_fee.

Requires network: yes

pub fn get_unresolved_failed_swaps(&self) -> Result<Vec<FailedSwapInfo>>

Lists all unresolved failed swaps. Each individual failed swap can be recovered using LightningNode::resolve_failed_swap.

Requires network: yes

pub fn get_failed_swap_resolving_fees( &self, failed_swap_info: FailedSwapInfo ) -> Result<Option<OnchainResolvingFees>>

Returns the fees for resolving a failed swap if there are enough funds to pay for fees.

Must only be called when the failed swap is unresolved.

Returns the fee information for the available resolving options.

Requires network: yes

pub fn prepare_resolve_failed_swap( &self, failed_swap_info: FailedSwapInfo, to_address: String, onchain_fee_rate: u32 ) -> Result<ResolveFailedSwapInfo>

Prepares the resolution of a failed swap in order to know how much will be recovered and how much will be paid in on-chain fees.

Parameters:

• failed_swap_info - the failed swap that will be prepared
• to_address - the destination address to which funds will be sent
• onchain_fee_rate - the fee rate that will be applied. The recommended one can be fetched using LightningNode::query_onchain_fee_rate

Requires network: yes

pub fn resolve_failed_swap( &self, resolve_failed_swap_info: ResolveFailedSwapInfo ) -> Result<String>

Creates and broadcasts a resolving transaction to recover funds from a failed swap. Existing failed swaps can be listed using LightningNode::get_unresolved_failed_swaps and preparing the resolution of a failed swap can be done using LightningNode::prepare_resolve_failed_swap.

Parameters:

• resolve_failed_swap_info - Information needed to resolve the failed swap. Can be obtained using LightningNode::prepare_resolve_failed_swap.

Returns the txid of the resolving transaction.

Paid on-chain fees can be known in advance using LightningNode::prepare_resolve_failed_swap.

Requires network: yes

pub fn swap_failed_swap_funds_to_lightning( &self, failed_swap_info: FailedSwapInfo, sat_per_vbyte: u32, lsp_fee_param: Option<OpeningFeeParams> ) -> Result<String>

pub fn get_channel_close_resolving_fees( &self ) -> Result<Option<OnchainResolvingFees>>

Returns the fees for resolving channel closes if there are enough funds to pay for fees.

Must only be called when there are onchain funds to resolve.

Returns the fee information for the available resolving options.

Requires network: yes

pub fn swap_channel_close_funds_to_lightning( &self, sat_per_vbyte: u32, lsp_fee_params: Option<OpeningFeeParams> ) -> Result<String, RedeemOnchainError>

Automatically swaps on-chain funds back to lightning.

If a swap is in progress, this method will return an error.

If the current balance doesn’t fulfill the limits, this method will return an error. Before using this method use LightningNode::get_channel_close_resolving_fees to validate a swap is available.

Parameters:

• sat_per_vbyte - the fee rate to use for the on-chain transaction. Can be obtained with LightningNode::get_channel_close_resolving_fees.
• lsp_fee_params - the lsp fee params for opening a new channel if necessary. Can be obtained with LightningNode::get_channel_close_resolving_fees.

Returns the txid of the sweeping tx.

Requires network: yes

pub fn log_debug_info(&self) -> Result<()>

Prints additional debug information to the logs.

Throws an error in case that the necessary information can’t be retrieved.

Requires network: yes

pub fn retrieve_latest_fiat_topup_info(&self) -> Result<Option<FiatTopupInfo>>

Returns the latest FiatTopupInfo if the user has registered for the fiat topup.

Requires network: no

pub fn get_health_status(&self) -> Result<BreezHealthCheckStatus>

Returns the health check status of Breez and Greenlight services.

Requires network: yes

pub fn check_clear_wallet_feasibility(&self) -> Result<RangeHit>

Check if clearing the wallet is feasible.

Meaning that the balance is within the range of what can be reverse-swapped.

Requires network: yes

pub fn prepare_clear_wallet(&self) -> Result<ClearWalletInfo>

Prepares a reverse swap that sends all funds in LN channels. This is possible because the route to the swap service is known, so fees can be known in advance.

This can fail if the balance is either too low or too high for it to be reverse-swapped. The method LightningNode::check_clear_wallet_feasibility can be used to check if the balance is within the required range.

Requires network: yes

pub fn clear_wallet( &self, clear_wallet_info: ClearWalletInfo, destination_onchain_address_data: BitcoinAddressData ) -> Result<()>

Starts a reverse swap that sends all funds in LN channels to the provided on-chain address.

Parameters:

• clear_wallet_info - An instance of ClearWalletInfo obtained using LightningNode::prepare_clear_wallet.
• destination_onchain_address_data - An on-chain address data instance. Can be obtained using LightningNode::decode_data.

Requires network: yes

pub fn set_analytics_config(&self, config: AnalyticsConfig) -> Result<()>

Set the analytics configuration.

This can be used to completely prevent any analytics data from being reported.

Requires network: no

pub fn get_analytics_config(&self) -> Result<AnalyticsConfig>

Get the currently configured analytics configuration.

Requires network: no

pub fn register_lightning_address(&self) -> Result<String>

Register a human-readable lightning address or return the previously registered one.

Requires network: yes

pub fn query_lightning_address(&self) -> Result<Option<String>>

Query the registered lightning address.

Requires network: no

pub fn query_verified_phone_number(&self) -> Result<Option<String>>

Query for a previously verified phone number.

Requires network: no

pub fn request_phone_number_verification( &self, phone_number: String ) -> Result<()>

Start the verification process for a new phone number. This will trigger an SMS containing an OTP to be sent to the provided phone_number. To conclude the verification process, the method LightningNode::verify_phone_number should be called next.

Parameters:

• phone_number - the phone number to be registered. Needs to be checked for validity using LightningNode::parse_phone_number_to_lightning_address.

Requires network: yes

pub fn verify_phone_number( &self, phone_number: String, otp: String ) -> Result<()>

Finish the verification process for a new phone number.

Parameters:

• phone_number - the phone number to be verified.
• otp - the OTP code sent as an SMS to the phone number.

Requires network: yes

pub fn set_feature_flag( &self, feature: FeatureFlag, flag_enabled: bool ) -> Result<()>

Set value of a feature flag. The method will report the change to the backend and update the local database.

Parameters:

• feature - feature flag to be set.
• enable - enable or disable the feature.

Requires network: yes