Struct breez_sdk_liquid::sdk::LiquidSdk
source · pub struct LiquidSdk { /* private fields */ }
Implementations§
source§impl LiquidSdk
impl LiquidSdk
sourcepub async fn connect(req: ConnectRequest) -> Result<Arc<LiquidSdk>>
pub async fn connect(req: ConnectRequest) -> Result<Arc<LiquidSdk>>
Initializes the SDK services and starts the background tasks. This must be called to create the LiquidSdk instance.
§Arguments
req
- the ConnectRequest containing:mnemonic
- the Liquid wallet mnemonicconfig
- the SDK Config
sourcepub async fn disconnect(&self) -> SdkResult<()>
pub async fn disconnect(&self) -> SdkResult<()>
Disconnects the LiquidSdk instance and stops the background tasks.
sourcepub async fn add_event_listener(
&self,
listener: Box<dyn EventListener>,
) -> SdkResult<String>
pub async fn add_event_listener( &self, listener: Box<dyn EventListener>, ) -> SdkResult<String>
Adds an event listener to the LiquidSdk instance, where all SdkEvent’s will be emitted to. The event listener can be removed be calling LiquidSdk::remove_event_listener.
§Arguments
listener
- The listener which is an implementation of the EventListener trait
sourcepub async fn remove_event_listener(&self, id: String) -> SdkResult<()>
pub async fn remove_event_listener(&self, id: String) -> SdkResult<()>
Removes an event listener from the LiquidSdk instance.
§Arguments
id
- the event listener id returned by LiquidSdk::add_event_listener
sourcepub async fn get_info(&self) -> Result<GetInfoResponse>
pub async fn get_info(&self) -> Result<GetInfoResponse>
Get the wallet info, calculating the current pending and confirmed balances.
sourcepub fn sign_message(
&self,
req: &SignMessageRequest,
) -> SdkResult<SignMessageResponse>
pub fn sign_message( &self, req: &SignMessageRequest, ) -> SdkResult<SignMessageResponse>
Sign given message with the private key. Returns a zbase encoded signature.
sourcepub fn check_message(
&self,
req: &CheckMessageRequest,
) -> SdkResult<CheckMessageResponse>
pub fn check_message( &self, req: &CheckMessageRequest, ) -> SdkResult<CheckMessageResponse>
Check whether given message was signed by the given pubkey and the signature (zbase encoded) is valid.
sourcepub async fn prepare_send_payment(
&self,
req: &PrepareSendRequest,
) -> Result<PrepareSendResponse, PaymentError>
pub async fn prepare_send_payment( &self, req: &PrepareSendRequest, ) -> Result<PrepareSendResponse, PaymentError>
Prepares to pay a Lightning invoice via a submarine swap.
§Arguments
req
- the PrepareSendRequest containing:destination
- Either a Liquid BIP21 URI/address or a BOLT11 invoiceamount_sat
- Should only be specified when paying directly onchain or via amount-less BIP21
§Returns
Returns a PrepareSendResponse containing:
* destination
- the parsed destination, of type SendDestination
* fees_sat
- the additional fees which will be paid by the sender
sourcepub async fn send_payment(
&self,
req: &SendPaymentRequest,
) -> Result<SendPaymentResponse, PaymentError>
pub async fn send_payment( &self, req: &SendPaymentRequest, ) -> Result<SendPaymentResponse, PaymentError>
Either pays a Lightning invoice via a submarine swap or sends funds directly to an address.
Depending on Config’s payment_timeout_sec
, this function will return:
- PaymentState::Pending payment - if the payment could be initiated but didn’t yet complete in this time
- PaymentState::Complete payment - if the payment was successfully completed in this time
§Arguments
req
- A SendPaymentRequest, containing:prepare_response
- the PrepareSendResponse returned by LiquidSdk::prepare_send_payment
§Errors
- PaymentError::PaymentTimeout - if the payment could not be initiated in this time
sourcepub async fn fetch_lightning_limits(
&self,
) -> Result<LightningPaymentLimitsResponse, PaymentError>
pub async fn fetch_lightning_limits( &self, ) -> Result<LightningPaymentLimitsResponse, PaymentError>
Fetch the current payment limits for LiquidSdk::send_payment and LiquidSdk::receive_payment.
sourcepub async fn fetch_onchain_limits(
&self,
) -> Result<OnchainPaymentLimitsResponse, PaymentError>
pub async fn fetch_onchain_limits( &self, ) -> Result<OnchainPaymentLimitsResponse, PaymentError>
Fetch the current payment limits for LiquidSdk::pay_onchain and LiquidSdk::receive_onchain.
sourcepub async fn prepare_pay_onchain(
&self,
req: &PreparePayOnchainRequest,
) -> Result<PreparePayOnchainResponse, PaymentError>
pub async fn prepare_pay_onchain( &self, req: &PreparePayOnchainRequest, ) -> Result<PreparePayOnchainResponse, PaymentError>
Prepares to pay to a Bitcoin address via a chain swap.
§Arguments
req
- the PreparePayOnchainRequest containing:amount
- which can be of two types: PayOnchainAmount::Drain, which uses all funds, and PayOnchainAmount::Receiver, which sets the amount the receiver should receivefee_rate_sat_per_vbyte
- the optional fee rate of the Bitcoin claim transaction. Defaults to the swapper estimated claim fee
sourcepub async fn pay_onchain(
&self,
req: &PayOnchainRequest,
) -> Result<SendPaymentResponse, PaymentError>
pub async fn pay_onchain( &self, req: &PayOnchainRequest, ) -> Result<SendPaymentResponse, PaymentError>
Pays to a Bitcoin address via a chain swap.
Depending on Config’s payment_timeout_sec
, this function will return:
- PaymentState::Pending payment - if the payment could be initiated but didn’t yet complete in this time
- PaymentState::Complete payment - if the payment was successfully completed in this time
§Arguments
req
- the PayOnchainRequest containing:address
- the Bitcoin address to pay toprepare_response
- the PreparePayOnchainResponse from calling LiquidSdk::prepare_pay_onchain
§Errors
- PaymentError::PaymentTimeout - if the payment could not be initiated in this time
sourcepub async fn prepare_receive_payment(
&self,
req: &PrepareReceiveRequest,
) -> Result<PrepareReceiveResponse, PaymentError>
pub async fn prepare_receive_payment( &self, req: &PrepareReceiveRequest, ) -> Result<PrepareReceiveResponse, PaymentError>
Prepares to receive a Lightning payment via a reverse submarine swap.
§Arguments
req
- the PrepareReceiveRequest containing:payer_amount_sat
- the amount in satoshis to be paid by the payerpayment_method
- the supported payment methods; either an invoice, a Liquid address or a Bitcoin address
sourcepub async fn receive_payment(
&self,
req: &ReceivePaymentRequest,
) -> Result<ReceivePaymentResponse, PaymentError>
pub async fn receive_payment( &self, req: &ReceivePaymentRequest, ) -> Result<ReceivePaymentResponse, PaymentError>
Receive a Lightning payment via a reverse submarine swap, a chain swap or via direct Liquid payment.
§Arguments
req
- the ReceivePaymentRequest containing:prepare_response
- the PrepareReceiveResponse from calling LiquidSdk::prepare_receive_paymentdescription
- the optional payment descriptionuse_description_hash
- optional if true uses the hash of the description
§Returns
- A ReceivePaymentResponse containing:
destination
- the final destination to be paid by the payer, either a BIP21 URI (Liquid or Bitcoin), a Liquid address or an invoice
sourcepub async fn list_refundables(&self) -> SdkResult<Vec<RefundableSwap>>
pub async fn list_refundables(&self) -> SdkResult<Vec<RefundableSwap>>
List all failed chain swaps that need to be refunded. They can be refunded by calling LiquidSdk::prepare_refund then LiquidSdk::refund.
sourcepub async fn prepare_refund(
&self,
req: &PrepareRefundRequest,
) -> SdkResult<PrepareRefundResponse>
pub async fn prepare_refund( &self, req: &PrepareRefundRequest, ) -> SdkResult<PrepareRefundResponse>
Prepares to refund a failed chain swap by calculating the refund transaction size and absolute fee.
§Arguments
req
- the PrepareRefundRequest containing:swap_address
- the swap address to refund from RefundableSwap::swap_addressrefund_address
- the Bitcoin address to refund tofee_rate_sat_per_vbyte
- the fee rate at which to broadcast the refund transaction
sourcepub async fn refund(
&self,
req: &RefundRequest,
) -> Result<RefundResponse, PaymentError>
pub async fn refund( &self, req: &RefundRequest, ) -> Result<RefundResponse, PaymentError>
Refund a failed chain swap.
§Arguments
req
- the RefundRequest containing:swap_address
- the swap address to refund from RefundableSwap::swap_addressrefund_address
- the Bitcoin address to refund tofee_rate_sat_per_vbyte
- the fee rate at which to broadcast the refund transaction
sourcepub async fn rescan_onchain_swaps(&self) -> SdkResult<()>
pub async fn rescan_onchain_swaps(&self) -> SdkResult<()>
Rescans all expired chain swaps created from calling LiquidSdk::receive_onchain within the monitoring period to check if there are any confirmed funds available to refund.
sourcepub async fn prepare_buy_bitcoin(
&self,
req: &PrepareBuyBitcoinRequest,
) -> Result<PrepareBuyBitcoinResponse, PaymentError>
pub async fn prepare_buy_bitcoin( &self, req: &PrepareBuyBitcoinRequest, ) -> Result<PrepareBuyBitcoinResponse, PaymentError>
Prepares to buy Bitcoin via a chain swap.
§Arguments
req
- the PrepareBuyBitcoinRequest containing:provider
- the BuyBitcoinProvider to useamount_sat
- the amount in satoshis to buy from the provider
sourcepub async fn buy_bitcoin(
&self,
req: &BuyBitcoinRequest,
) -> Result<String, PaymentError>
pub async fn buy_bitcoin( &self, req: &BuyBitcoinRequest, ) -> Result<String, PaymentError>
Generate a URL to a third party provider used to buy Bitcoin via a chain swap.
§Arguments
req
- the BuyBitcoinRequest containing:prepare_response
- the PrepareBuyBitcoinResponse from calling LiquidSdk::prepare_buy_bitcoinredirect_url
- the optional redirect URL the provider should redirect to after purchase
sourcepub async fn list_payments(
&self,
req: &ListPaymentsRequest,
) -> Result<Vec<Payment>, PaymentError>
pub async fn list_payments( &self, req: &ListPaymentsRequest, ) -> Result<Vec<Payment>, PaymentError>
Lists the SDK payments in reverse chronological order, from newest to oldest. The payments are determined based on onchain transactions and swaps.
sourcepub async fn get_payment(
&self,
req: &GetPaymentRequest,
) -> Result<Option<Payment>, PaymentError>
pub async fn get_payment( &self, req: &GetPaymentRequest, ) -> Result<Option<Payment>, PaymentError>
Retrieves a payment.
§Arguments
req
- the GetPaymentRequest containing:- GetPaymentRequest::Lightning - the
payment_hash
of the lightning invoice
- GetPaymentRequest::Lightning - the
§Returns
Returns an Option<Payment>
if found, or None
if no payment matches the given request.
sourcepub fn empty_wallet_cache(&self) -> Result<()>
pub fn empty_wallet_cache(&self) -> Result<()>
Empties the Liquid Wallet cache for the Config::network.
sourcepub async fn sync(&self) -> SdkResult<()>
pub async fn sync(&self) -> SdkResult<()>
Synchronizes the local state with the mempool and onchain data.
sourcepub fn backup(&self, req: BackupRequest) -> Result<()>
pub fn backup(&self, req: BackupRequest) -> Result<()>
Backup the local state to the provided backup path.
§Arguments
req
- the BackupRequest containing:backup_path
- the optional backup path. Defaults to Config::working_dir
sourcepub fn restore(&self, req: RestoreRequest) -> Result<()>
pub fn restore(&self, req: RestoreRequest) -> Result<()>
Restores the local state from the provided backup path.
§Arguments
req
- the RestoreRequest containing:backup_path
- the optional backup path. Defaults to Config::working_dir
sourcepub async fn prepare_lnurl_pay(
&self,
req: PrepareLnUrlPayRequest,
) -> Result<PrepareLnUrlPayResponse, LnUrlPayError>
pub async fn prepare_lnurl_pay( &self, req: PrepareLnUrlPayRequest, ) -> Result<PrepareLnUrlPayResponse, LnUrlPayError>
Prepares to pay to an LNURL encoded pay request or lightning address.
This is the second step of LNURL-pay flow. 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, a PrepareSendResponse is
prepared for the invoice. If the receiver has encoded a Magic Routing Hint in the invoice, the
PrepareSendResponse’s fees_sat
will reflect this.
§Arguments
req
- the PrepareLnUrlPayRequest containing:data
- the LnUrlPayRequestData returned by parseamount_msat
- the amount in millisatoshis for this paymentcomment
- an optional comment for this paymentvalidate_success_action_url
- validates that, if there is a URL success action, the URL domain matches the LNURL callback domain. Defaults to ‘true’
§Returns
Returns a PrepareLnUrlPayResponse containing:
* prepare_send_response
- the prepared PrepareSendResponse for the retreived invoice
* success_action
- the optional unprocessed LUD-09 success action
sourcepub async fn lnurl_pay(
&self,
req: LnUrlPayRequest,
) -> Result<LnUrlPayResult, LnUrlPayError>
pub async fn lnurl_pay( &self, req: LnUrlPayRequest, ) -> Result<LnUrlPayResult, LnUrlPayError>
Pay to an LNURL encoded pay request or lightning address.
The final step of LNURL-pay flow, called after preparing the payment with LiquidSdk::prepare_lnurl_pay.
This call sends the payment using the PrepareLnUrlPayResponse’s prepare_send_response
either via
Lightning or directly to a Liquid address if a Magic Routing Hint is included in the invoice.
Once the payment is made, the PrepareLnUrlPayResponse’s success_action
is processed decrypting
the AES data if needed.
§Arguments
req
- the LnUrlPayRequest containing:prepare_response
- the PrepareLnUrlPayResponse returned by LiquidSdk::prepare_lnurl_pay
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 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
. Each created swap after registering the
webhook will include the webhook_url
.
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 LiquidSdk::unregister_webhook.
sourcepub async fn unregister_webhook(&self) -> SdkResult<()>
pub async fn unregister_webhook(&self) -> SdkResult<()>
Unregister webhook callbacks. Each swap already created will continue to use the registered
webhook_url
until complete.
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 LiquidSdk::register_webhook.
sourcepub async fn fetch_fiat_rates(&self) -> Result<Vec<Rate>, SdkError>
pub async fn fetch_fiat_rates(&self) -> Result<Vec<Rate>, SdkError>
Fetch live rates of fiat currencies, sorted by name.
sourcepub async fn list_fiat_currencies(&self) -> Result<Vec<FiatCurrency>, SdkError>
pub async fn list_fiat_currencies(&self) -> Result<Vec<FiatCurrency>, SdkError>
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 recommended_fees(&self) -> Result<RecommendedFees, SdkError>
pub async fn recommended_fees(&self) -> Result<RecommendedFees, SdkError>
Get the recommended BTC fees based on the configured mempool.space instance.
sourcepub fn default_config(
network: LiquidNetwork,
breez_api_key: Option<String>,
) -> Result<Config, SdkError>
pub fn default_config( network: LiquidNetwork, breez_api_key: Option<String>, ) -> Result<Config, SdkError>
Get the full default Config for specific LiquidNetwork.
sourcepub async fn parse(input: &str) -> Result<InputType, PaymentError>
pub async fn parse(input: &str) -> Result<InputType, PaymentError>
Parses a string into an InputType. See input_parser::parse.
sourcepub fn parse_invoice(input: &str) -> Result<LNInvoice, PaymentError>
pub fn parse_invoice(input: &str) -> Result<LNInvoice, PaymentError>
Parses a string into an LNInvoice. See invoice::parse_invoice.
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.
§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.
Auto Trait Implementations§
impl !Freeze for LiquidSdk
impl !RefUnwindSafe for LiquidSdk
impl Send for LiquidSdk
impl Sync for LiquidSdk
impl Unpin for LiquidSdk
impl !UnwindSafe for LiquidSdk
Blanket Implementations§
§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> 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