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
impl BreezServices
sourcepub async fn connect(
req: ConnectRequest,
event_listener: Box<dyn EventListener>,
) -> Result<Arc<BreezServices>, ConnectError>
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 theconfig
SDK configuration andseed
node private key, typically derived from the mnemonic. When using a newinvite_code
, the seed should be derived from a new random mnemonic. When re-using aninvite_code
, the same mnemonic should be used as when theinvite_code
was first used.event_listener
- Listener to SDK events
sourcepub async fn disconnect(&self) -> SdkResult<()>
pub async fn disconnect(&self) -> SdkResult<()>
Trigger the stopping of BreezServices background threads for this instance.
sourcepub async fn configure_node(&self, req: ConfigureNodeRequest) -> SdkResult<()>
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.
sourcepub async fn send_payment(
&self,
req: SendPaymentRequest,
) -> Result<SendPaymentResponse, SendPaymentError>
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.
sourcepub async fn send_spontaneous_payment(
&self,
req: SendSpontaneousPaymentRequest,
) -> Result<SendPaymentResponse, SendPaymentError>
pub async fn send_spontaneous_payment( &self, req: SendSpontaneousPaymentRequest, ) -> Result<SendPaymentResponse, SendPaymentError>
Pay directly to a node id using keysend
sourcepub async fn lnurl_pay(
&self,
req: LnUrlPayRequest,
) -> Result<LnUrlPayResult, LnUrlPayError>
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.
sourcepub async fn lnurl_withdraw(
&self,
req: LnUrlWithdrawRequest,
) -> Result<LnUrlWithdrawResult, LnUrlWithdrawError>
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.
sourcepub async fn lnurl_auth(
&self,
req_data: LnUrlAuthRequestData,
) -> Result<LnUrlCallbackStatus, LnUrlAuthError>
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.
sourcepub async fn receive_payment(
&self,
req: ReceivePaymentRequest,
) -> Result<ReceivePaymentResponse, ReceivePaymentError>
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.
sourcepub async fn report_issue(&self, req: ReportIssueRequest) -> SdkResult<()>
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.
sourcepub async fn node_credentials(&self) -> SdkResult<Option<NodeCredentials>>
pub async fn node_credentials(&self) -> SdkResult<Option<NodeCredentials>>
Retrieve the decrypted credentials from the node.
sourcepub fn node_info(&self) -> SdkResult<NodeState>
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.
sourcepub async fn sign_message(
&self,
req: SignMessageRequest,
) -> SdkResult<SignMessageResponse>
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.
sourcepub async fn check_message(
&self,
req: CheckMessageRequest,
) -> SdkResult<CheckMessageResponse>
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.
sourcepub fn backup_status(&self) -> SdkResult<BackupStatus>
pub fn backup_status(&self) -> SdkResult<BackupStatus>
Retrieve the node up to date BackupStatus
sourcepub async fn list_payments(
&self,
req: ListPaymentsRequest,
) -> SdkResult<Vec<Payment>>
pub async fn list_payments( &self, req: ListPaymentsRequest, ) -> SdkResult<Vec<Payment>>
List payments matching the given filters, as retrieved from persistent storage
sourcepub async fn payment_by_hash(&self, hash: String) -> SdkResult<Option<Payment>>
pub async fn payment_by_hash(&self, hash: String) -> SdkResult<Option<Payment>>
Fetch a specific payment by its hash.
sourcepub async fn set_payment_metadata(
&self,
hash: String,
metadata: String,
) -> SdkResult<()>
pub async fn set_payment_metadata( &self, hash: String, metadata: String, ) -> SdkResult<()>
Set the external metadata of a payment as a valid JSON string
sourcepub async fn redeem_onchain_funds(
&self,
req: RedeemOnchainFundsRequest,
) -> RedeemOnchainResult<RedeemOnchainFundsResponse>
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
pub async fn prepare_redeem_onchain_funds( &self, req: PrepareRedeemOnchainFundsRequest, ) -> RedeemOnchainResult<PrepareRedeemOnchainFundsResponse>
sourcepub async fn fetch_fiat_rates(&self) -> SdkResult<Vec<Rate>>
pub async fn fetch_fiat_rates(&self) -> SdkResult<Vec<Rate>>
Fetch live rates of fiat currencies, sorted by name
sourcepub async fn list_fiat_currencies(&self) -> SdkResult<Vec<FiatCurrency>>
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
sourcepub async fn list_lsps(&self) -> SdkResult<Vec<LspInformation>>
pub async fn list_lsps(&self) -> SdkResult<Vec<LspInformation>>
List available LSPs that can be selected by the user
sourcepub async fn connect_lsp(&self, lsp_id: String) -> SdkResult<()>
pub async fn connect_lsp(&self, lsp_id: String) -> SdkResult<()>
Select the LSP to be used and provide inbound liquidity
sourcepub async fn fetch_lsp_info(
&self,
id: String,
) -> SdkResult<Option<LspInformation>>
pub async fn fetch_lsp_info( &self, id: String, ) -> SdkResult<Option<LspInformation>>
Convenience method to look up LspInformation for a given LSP ID
sourcepub async fn open_channel_fee(
&self,
req: OpenChannelFeeRequest,
) -> SdkResult<OpenChannelFeeResponse>
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.
sourcepub async fn close_lsp_channels(&self) -> SdkResult<Vec<String>>
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.
sourcepub async fn receive_onchain(
&self,
req: ReceiveOnchainRequest,
) -> ReceiveOnchainResult<SwapInfo>
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.
sourcepub async fn in_progress_swap(&self) -> SdkResult<Option<SwapInfo>>
pub async fn in_progress_swap(&self) -> SdkResult<Option<SwapInfo>>
sourcepub async fn rescan_swaps(&self) -> SdkResult<()>
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.
sourcepub async fn redeem_swap(&self, swap_address: String) -> SdkResult<()>
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.
sourcepub async fn list_swaps(
&self,
req: ListSwapsRequest,
) -> SdkResult<Vec<SwapInfo>>
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.
sourcepub async fn claim_reverse_swap(&self, lockup_address: String) -> SdkResult<()>
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.
sourcepub async fn fetch_reverse_swap_fees(
&self,
req: ReverseSwapFeesRequest,
) -> SdkResult<ReverseSwapPairInfo>
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, andtotal_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.
sourcepub async fn max_reverse_swap_amount(
&self,
) -> SdkResult<MaxReverseSwapAmountResponse>
👎Deprecated: use onchain_payment_limits instead
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.
sourcepub async fn send_onchain(
&self,
req: SendOnchainRequest,
) -> Result<SendOnchainResponse, SendOnchainError>
👎Deprecated: use pay_onchain instead
pub async fn send_onchain( &self, req: SendOnchainRequest, ) -> Result<SendOnchainResponse, SendOnchainError>
Creates a reverse swap and attempts to pay the HODL invoice
sourcepub async fn in_progress_reverse_swaps(&self) -> SdkResult<Vec<ReverseSwapInfo>>
👎Deprecated: use in_progress_onchain_payments instead
pub async fn in_progress_reverse_swaps(&self) -> SdkResult<Vec<ReverseSwapInfo>>
Returns the blocking ReverseSwapInfos that are in progress
sourcepub async fn list_refundables(&self) -> SdkResult<Vec<SwapInfo>>
pub async fn list_refundables(&self) -> SdkResult<Vec<SwapInfo>>
list non-completed expired swaps that should be refunded by calling BreezServices::refund
sourcepub async fn prepare_refund(
&self,
req: PrepareRefundRequest,
) -> SdkResult<PrepareRefundResponse>
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.
sourcepub async fn refund(&self, req: RefundRequest) -> SdkResult<RefundResponse>
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>
sourcepub async fn prepare_onchain_payment(
&self,
req: PrepareOnchainPaymentRequest,
) -> Result<PrepareOnchainPaymentResponse, SendOnchainError>
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.
sourcepub async fn pay_onchain(
&self,
req: PayOnchainRequest,
) -> Result<PayOnchainResponse, SendOnchainError>
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
sourcepub async fn in_progress_onchain_payments(
&self,
) -> SdkResult<Vec<ReverseSwapInfo>>
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
sourcepub async fn execute_dev_command(&self, command: String) -> SdkResult<String>
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>
sourcepub async fn sync(&self) -> SdkResult<()>
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
sourcepub async fn lsp_info(&self) -> SdkResult<LspInformation>
pub async fn lsp_info(&self) -> SdkResult<LspInformation>
Convenience method to look up LSP info based on current LSP ID
sourcepub async fn recommended_fees(&self) -> SdkResult<RecommendedFees>
pub async fn recommended_fees(&self) -> SdkResult<RecommendedFees>
Get the recommended fees for onchain transactions
sourcepub fn default_config(
env_type: EnvironmentType,
api_key: String,
node_config: NodeConfig,
) -> Config
pub fn default_config( env_type: EnvironmentType, api_key: String, node_config: NodeConfig, ) -> Config
Get the full default config for a specific environment type
sourcepub fn static_backup(
req: StaticBackupRequest,
) -> SdkResult<StaticBackupResponse>
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
sourcepub async fn service_health_check(
api_key: String,
) -> SdkResult<ServiceHealthCheckResponse>
pub async fn service_health_check( api_key: String, ) -> SdkResult<ServiceHealthCheckResponse>
Fetches the service health check from the support API.
sourcepub async fn buy_bitcoin(
&self,
req: BuyBitcoinRequest,
) -> Result<BuyBitcoinResponse, ReceiveOnchainError>
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.
sourcepub fn init_logging(
log_dir: &str,
app_logger: Option<Box<dyn Log>>,
) -> Result<()>
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.
sourcepub async fn register_webhook(&self, webhook_url: String) -> SdkResult<()>
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.
sourcepub async fn unregister_webhook(&self, webhook_url: String) -> SdkResult<()>
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§
impl !Freeze for BreezServices
impl !RefUnwindSafe for BreezServices
impl Send for BreezServices
impl Sync for BreezServices
impl Unpin for BreezServices
impl !UnwindSafe for BreezServices
Blanket Implementations§
§impl<T> AnySync for T
impl<T> AnySync for T
§impl<'a, T, E> AsTaggedExplicit<'a, E> for Twhere
T: 'a,
impl<'a, T, E> AsTaggedExplicit<'a, E> for Twhere
T: 'a,
§impl<'a, T, E> AsTaggedImplicit<'a, E> for Twhere
T: 'a,
impl<'a, T, E> AsTaggedImplicit<'a, E> for Twhere
T: 'a,
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<T> Downcast for Twhere
T: AsAny + ?Sized,
impl<T> Downcast for Twhere
T: AsAny + ?Sized,
§fn downcast_ref<T>(&self) -> Option<&T>where
T: AsAny,
fn downcast_ref<T>(&self) -> Option<&T>where
T: AsAny,
Any
.§fn downcast_mut<T>(&mut self) -> Option<&mut T>where
T: AsAny,
fn downcast_mut<T>(&mut self) -> Option<&mut T>where
T: AsAny,
Any
.§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
source§impl<T> IntoRequest<T> for T
impl<T> IntoRequest<T> for T
source§fn into_request(self) -> Request<T>
fn into_request(self) -> Request<T>
T
in a tonic::Request