Struct breez_sdk_core::BreezServices

pub struct BreezServices { /* private fields */ }

BreezServices is a facade and the single entry point for the SDK.

Implementations

impl BreezServices

pub async fn connect( req: ConnectRequest, event_listener: Box<dyn EventListener> ) -> Result<Arc<BreezServices>, ConnectError>

connect initializes the SDK services, schedules the node to run in the cloud and runs the signer. This must be called in order to start communicating with the node.

Arguments

• req - The connect request containing the config SDK configuration and seed node private key, typically derived from the mnemonic. When using a new invite_code, the seed should be derived from a new random mnemonic. When re-using an invite_code, the same mnemonic should be used as when the invite_code was first used.
• event_listener - Listener to SDK events

pub async fn disconnect(&self) -> SdkResult<()>

Trigger the stopping of BreezServices background threads for this instance.

pub async fn configure_node(&self, req: ConfigureNodeRequest) -> SdkResult<()>

Configure the node

This calls [NodeAPI::configure_node] to make changes to the active node’s configuration. Configuring the ConfigureNodeRequest::close_to_address only needs to be done one time when registering the node or when the close to address need to be changed. Otherwise it is stored by the node and used when neccessary.

pub async fn send_payment( &self, req: SendPaymentRequest ) -> Result<SendPaymentResponse, SendPaymentError>

Pay a bolt11 invoice

Calling send_payment ensures that the payment is not already completed, if so it will result in an error. If the invoice doesn’t specify an amount, the amount is taken from the amount_msat arg.

pub async fn send_spontaneous_payment( &self, req: SendSpontaneousPaymentRequest ) -> Result<SendPaymentResponse, SendPaymentError>

Pay directly to a node id using keysend

pub async fn lnurl_pay( &self, req: LnUrlPayRequest ) -> Result<LnUrlPayResult, LnUrlPayError>

Second step of LNURL-pay. The first step is parse(), which also validates the LNURL destination and generates the LnUrlPayRequest payload needed here.

This call will validate the amount_msat and comment parameters of req against the parameters of the LNURL endpoint (req_data). If they match the endpoint requirements, the LNURL payment is made.

This method will return an anyhow::Error when any validation check fails.

pub async fn lnurl_withdraw( &self, req: LnUrlWithdrawRequest ) -> Result<LnUrlWithdrawResult, LnUrlWithdrawError>

Second step of LNURL-withdraw. The first step is parse(), which also validates the LNURL destination and generates the LnUrlWithdrawRequest payload needed here.

This call will validate the given amount_msat against the parameters of the LNURL endpoint (data). If they match the endpoint requirements, the LNURL withdraw request is made. A successful result here means the endpoint started the payment.

pub async fn lnurl_auth( &self, req_data: LnUrlAuthRequestData ) -> Result<LnUrlCallbackStatus, LnUrlAuthError>

Third and last step of LNURL-auth. The first step is parse(), which also validates the LNURL destination and generates the LnUrlAuthRequestData payload needed here. The second step is user approval of auth action.

This call will sign k1 of the LNURL endpoint (req_data) on secp256k1 using linkingPrivKey and DER-encodes the signature. If they match the endpoint requirements, the LNURL auth request is made. A successful result here means the client signature is verified.

pub async fn receive_payment( &self, req: ReceivePaymentRequest ) -> Result<ReceivePaymentResponse, ReceivePaymentError>

Creates an bolt11 payment request. This also works when the node doesn’t have any channels and need inbound liquidity. In such case when the invoice is paid a new zero-conf channel will be open by the LSP, providing inbound liquidity and the payment will be routed via this new channel.

pub async fn report_issue(&self, req: ReportIssueRequest) -> SdkResult<()>

Report an issue.

Calling report_issue with a ReportIssueRequest enum param sends an issue report using the Support API.

• ReportIssueRequest::PaymentFailure sends a payment failure report to the Support API using the provided payment_hash to lookup the failed payment and the current NodeState.

pub fn node_credentials(&self) -> SdkResult<Option<NodeCredentials>>

Retrieve the decrypted credentials from the node.

pub fn node_info(&self) -> SdkResult<NodeState>

Retrieve the node state from the persistent storage.

Fail if it could not be retrieved or if None was found.

pub async fn sign_message( &self, req: SignMessageRequest ) -> SdkResult<SignMessageResponse>

Sign given message with the private key of the node id. Returns a zbase encoded signature.

pub async fn check_message( &self, req: CheckMessageRequest ) -> SdkResult<CheckMessageResponse>

Check whether given message was signed by the private key or the given pubkey and the signature (zbase encoded) is valid.

pub fn backup_status(&self) -> SdkResult<BackupStatus>

Retrieve the node up to date BackupStatus

pub async fn backup(&self) -> SdkResult<()>

Force running backup

pub async fn list_payments( &self, req: ListPaymentsRequest ) -> SdkResult<Vec<Payment>>

List payments matching the given filters, as retrieved from persistent storage

pub async fn payment_by_hash(&self, hash: String) -> SdkResult<Option<Payment>>

Fetch a specific payment by its hash.

pub async fn set_payment_metadata( &self, hash: String, metadata: String ) -> SdkResult<()>

Set the external metadata of a payment as a valid JSON string

pub async fn redeem_onchain_funds( &self, req: RedeemOnchainFundsRequest ) -> SdkResult<RedeemOnchainFundsResponse>

Redeem on-chain funds from closed channels to the specified on-chain address, with the given feerate

pub async fn prepare_redeem_onchain_funds( &self, req: PrepareRedeemOnchainFundsRequest ) -> SdkResult<PrepareRedeemOnchainFundsResponse>

pub async fn fetch_fiat_rates(&self) -> SdkResult<Vec<Rate>>

Fetch live rates of fiat currencies, sorted by name

pub async fn list_fiat_currencies(&self) -> SdkResult<Vec<FiatCurrency>>

List all supported fiat currencies for which there is a known exchange rate. List is sorted by the canonical name of the currency

pub async fn list_lsps(&self) -> SdkResult<Vec<LspInformation>>

List available LSPs that can be selected by the user

pub async fn connect_lsp(&self, lsp_id: String) -> SdkResult<()>

Select the LSP to be used and provide inbound liquidity

pub async fn lsp_id(&self) -> SdkResult<Option<String>>

Get the current LSP’s ID

pub async fn fetch_lsp_info( &self, id: String ) -> SdkResult<Option<LspInformation>>

Convenience method to look up LspInformation for a given LSP ID

pub async fn open_channel_fee( &self, req: OpenChannelFeeRequest ) -> SdkResult<OpenChannelFeeResponse>

Gets the fees required to open a channel for a given amount. If no channel is needed, returns 0. If a channel is needed, returns the required opening fees.

pub async fn close_lsp_channels(&self) -> SdkResult<Vec<String>>

Close all channels with the current LSP.

Should be called when the user wants to close all the channels.

pub async fn receive_onchain( &self, req: ReceiveOnchainRequest ) -> ReceiveOnchainResult<SwapInfo>

Onchain receive swap API

Create and start a new swap. A user-selected OpeningFeeParams can be optionally set in the argument. If set, and the operation requires a new channel, the SDK will try to use the given fee params.

Since we only allow one in-progress swap this method will return error if there is currently a swap waiting for confirmation to be redeemed and by that complete the swap. In such case the BreezServices::in_progress_swap can be used to query the live swap status.

The returned SwapInfo contains the created swap details. The channel opening fees are available at SwapInfo::channel_opening_fees.

pub async fn in_progress_swap(&self) -> SdkResult<Option<SwapInfo>>

Returns an optional in-progress SwapInfo. A SwapInfo is in-progress if it is waiting for confirmation to be redeemed and complete the swap.

pub async fn rescan_swaps(&self) -> SdkResult<()>

Iterate all historical swap addresses and fetch their current status from the blockchain. The status is then updated in the persistent storage.

pub async fn redeem_swap(&self, swap_address: String) -> SdkResult<()>

Redeems an individual swap.

To be used only in the context of mobile notifications, where the notification triggers an individual redeem.

This is taken care of automatically in the context of typical SDK usage.

pub async fn fetch_reverse_swap_fees( &self, req: ReverseSwapFeesRequest ) -> SdkResult<ReverseSwapPairInfo>

Lookup the reverse swap fees (see [ReverseSwapServiceAPI::fetch_reverse_swap_fees]).

If the request has the send_amount_sat set, the returned ReverseSwapPairInfo will have the total estimated fees for the reverse swap in its total_estimated_fees.

If, in addition to that, the request has the claim_tx_feerate set as well, then

• fees_claim will have the actual claim transaction fees, instead of an estimate, and
• total_estimated_fees will have the actual total fees for the given parameters

Errors

If a send_amount_sat is specified in the req, but is outside the min and max, this will result in an error. If you are not sure what are the min and max, please call this with send_amount_sat as None first, then repeat the call with the desired amount.

pub async fn max_reverse_swap_amount( &self ) -> SdkResult<MaxReverseSwapAmountResponse>

Returns the max amount that can be sent on-chain using the send_onchain method. The returned amount is the sum of the max amount that can be sent on each channel minus the expected fees. This is possible since the route to the swapper node is known in advance and is expected to consist of maximum 3 hops.

Deprecated. Please use BreezServices::onchain_payment_limits instead.

pub async fn send_onchain( &self, req: SendOnchainRequest ) -> Result<SendOnchainResponse, SendOnchainError>

Creates a reverse swap and attempts to pay the HODL invoice

Deprecated. Please use BreezServices::pay_onchain instead.

pub async fn in_progress_reverse_swaps(&self) -> SdkResult<Vec<ReverseSwapInfo>>

Returns the blocking ReverseSwapInfos that are in progress

Deprecated. Please use BreezServices::in_progress_onchain_payments instead.

pub async fn list_refundables(&self) -> SdkResult<Vec<SwapInfo>>

list non-completed expired swaps that should be refunded by calling BreezServices::refund

pub async fn prepare_refund( &self, req: PrepareRefundRequest ) -> SdkResult<PrepareRefundResponse>

Prepares a refund transaction for a failed/expired swap.

Can optionally be used before BreezServices::refund to know how much fees will be paid to perform the refund.

pub async fn refund(&self, req: RefundRequest) -> SdkResult<RefundResponse>

Construct and broadcast a refund transaction for a failed/expired swap

Returns the txid of the refund transaction.

pub async fn onchain_payment_limits( &self ) -> SdkResult<OnchainPaymentLimitsResponse>

pub async fn prepare_onchain_payment( &self, req: PrepareOnchainPaymentRequest ) -> Result<PrepareOnchainPaymentResponse, SendOnchainError>

Supersedes BreezServices::fetch_reverse_swap_fees

Errors

• OutOfRange: This indicates the send amount is outside the range of minimum and maximum values returned by BreezServices::onchain_payment_limits. When you get this error, please first call BreezServices::onchain_payment_limits to get the new limits, before calling this method again.

pub async fn pay_onchain( &self, req: PayOnchainRequest ) -> Result<PayOnchainResponse, SendOnchainError>

Creates a reverse swap and attempts to pay the HODL invoice

Supersedes BreezServices::send_onchain

pub async fn in_progress_onchain_payments( &self ) -> SdkResult<Vec<ReverseSwapInfo>>

Returns the blocking ReverseSwapInfos that are in progress.

Supersedes BreezServices::in_progress_reverse_swaps

pub async fn execute_dev_command(&self, command: String) -> SdkResult<String>

Execute a command directly on the NodeAPI interface. Mainly used to debugging.

pub async fn generate_diagnostic_data(&self) -> SdkResult<String>

pub async fn sync(&self) -> SdkResult<()>

This method sync the local state with the remote node state. The synced items are as follows:

• node state - General information about the node and its liquidity status
• channels - The list of channels and their status
• payments - The incoming/outgoing payments

pub async fn lsp_info(&self) -> SdkResult<LspInformation>

Convenience method to look up LSP info based on current LSP ID

pub async fn recommended_fees(&self) -> SdkResult<RecommendedFees>

Get the recommended fees for onchain transactions

pub fn default_config( env_type: EnvironmentType, api_key: String, node_config: NodeConfig ) -> Config

Get the full default config for a specific environment type

pub fn static_backup( req: StaticBackupRequest ) -> SdkResult<StaticBackupResponse>

Get the static backup data from the persistent storage. This data enables the user to recover the node in an external core ligntning node. See here for instructions on how to recover using this data: https://docs.corelightning.org/docs/backup-and-recovery#backing-up-using-static-channel-backup

pub async fn service_health_check( api_key: String ) -> SdkResult<ServiceHealthCheckResponse>

Fetches the service health check from the support API.

pub async fn buy_bitcoin( &self, req: BuyBitcoinRequest ) -> Result<BuyBitcoinResponse, ReceiveOnchainError>

Generates an url that can be used by a third part provider to buy Bitcoin with fiat currency.

A user-selected OpeningFeeParams can be optionally set in the argument. If set, and the operation requires a new channel, the SDK will try to use the given fee params.

pub fn init_logging( log_dir: &str, app_logger: Option<Box<dyn Log>> ) -> Result<()>

Configures a global SDK logger that will log to file and will forward log events to an optional application-specific logger.

If called, it should be called before any SDK methods (for example, before connect).

It must be called only once in the application lifecycle. Alternatively, If the application already uses a globally-registered logger, this method shouldn’t be called at all.

Arguments

• log_dir: Location where the the SDK log file will be created. The directory must already exist.

• app_logger: Optional application logger.

If the application is to use it’s own logger, but would also like the SDK to log SDK-specific log output to a file in the configured log_dir, then do not register the app-specific logger as a global logger and instead call this method with the app logger as an arg.

Logging Configuration

Setting breez_sdk_core::input_parser=debug will include in the logs the raw payloads received when interacting with JSON endpoints, for example those used during all LNURL workflows.

Errors

An error is thrown if the log file cannot be created in the working directory.

An error is thrown if a global logger is already configured.

pub async fn register_webhook(&self, webhook_url: String) -> SdkResult<()>

Register for webhook callbacks at the given webhook_url.

More specifically, it registers for the following types of callbacks:

• a payment is received
• a swap tx is confirmed

This method should be called every time the application is started and when the webhook_url changes. For example, if the webhook_url contains a push notification token and the token changes after the application was started, then this method should be called to register for callbacks at the new correct webhook_url. To unregister a webhook call BreezServices::unregister_webhook.

pub async fn unregister_webhook(&self, webhook_url: String) -> SdkResult<()>

Unregister webhook callbacks for the given webhook_url.

When called, it unregisters for the following types of callbacks:

• a payment is received
• a swap tx is confirmed

This can be called when callbacks are no longer needed or the webhook_url has changed such that it needs unregistering. For example, the token is valid but the locale changes. To register a webhook call BreezServices::register_webhook.