Struct breez_sdk_core::BreezServices

source ·
pub struct BreezServices { /* private fields */ }
Expand description

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

Implementations§

source§

impl BreezServices

source

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
source

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

Trigger the stopping of BreezServices background threads for this instance.

source

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.

source

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.

source

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

Pay directly to a node id using keysend

source

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.

source

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.

source

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.

source

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.

source

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.

source

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

Retrieve the decrypted credentials from the node.

source

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.

source

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.

source

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.

source

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

Retrieve the node up to date BackupStatus

source

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

Force running backup

source

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

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

source

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

Fetch a specific payment by its hash.

source

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

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

source

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

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

source

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

source

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

Fetch live rates of fiat currencies, sorted by name

source

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

source

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

List available LSPs that can be selected by the user

source

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

Select the LSP to be used and provide inbound liquidity

source

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

Get the current LSP’s ID

source

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

Convenience method to look up LspInformation for a given LSP ID

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

pub async fn list_swaps( &self, req: ListSwapsRequest, ) -> SdkResult<Vec<SwapInfo>>

Lists current and historical swaps.

Swaps can be filtered based on creation time and status.

source

pub async fn claim_reverse_swap(&self, lockup_address: String) -> SdkResult<()>

Claims an individual reverse swap.

To be used only in the context of mobile notifications, where the notification triggers an individual reverse swap to be claimed.

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

source

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.

source

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

👎Deprecated: use onchain_payment_limits instead

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.

source

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

👎Deprecated: use pay_onchain instead

Creates a reverse swap and attempts to pay the HODL invoice

source

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

👎Deprecated: use in_progress_onchain_payments instead

Returns the blocking ReverseSwapInfos that are in progress

source

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

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

source

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.

source

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.

source

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

source

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

Supersedes BreezServices::fetch_reverse_swap_fees

§Errors
source

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

source

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

source

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

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

source

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

source

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
source

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

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

source

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

Get the recommended fees for onchain transactions

source

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

Get the full default config for a specific environment type

source

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

source

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

Fetches the service health check from the support API.

source

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.

source

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.

source

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.

source

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.

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
§

impl<T> Any for T
where T: Any,

§

fn into_any(self: Box<T>) -> Box<dyn Any>

§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

§

fn type_name(&self) -> &'static str

§

impl<T> AnySync for T
where T: Any + Send + Sync,

§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

§

impl<T> AsAny for T
where T: Any,

§

fn as_any(&self) -> &(dyn Any + 'static)

§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

§

fn type_name(&self) -> &'static str

Gets the type name of self
§

impl<'a, T, E> AsTaggedExplicit<'a, E> for T
where T: 'a,

§

fn explicit(self, class: Class, tag: u32) -> TaggedParser<'a, Explicit, Self, E>

§

impl<'a, T, E> AsTaggedImplicit<'a, E> for T
where T: 'a,

§

fn implicit( self, class: Class, constructed: bool, tag: u32, ) -> TaggedParser<'a, Implicit, Self, E>

source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> Downcast for T
where T: AsAny + ?Sized,

§

fn is<T>(&self) -> bool
where T: AsAny,

Returns true if the boxed type is the same as T. Read more
§

fn downcast_ref<T>(&self) -> Option<&T>
where T: AsAny,

Forward to the method defined on the type Any.
§

fn downcast_mut<T>(&mut self) -> Option<&mut T>
where T: AsAny,

Forward to the method defined on the type Any.
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoRequest<T> for T

source§

fn into_request(self) -> Request<T>

Wrap the input message T in a tonic::Request
source§

impl<T> Same for T

source§

type Output = T

Should always be Self
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more