Struct LiquidSdk

pub struct LiquidSdk { /* private fields */ }

Implementations

impl 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 mnemonic
  • config - the SDK Config

pub async fn connect_with_signer( req: ConnectWithSignerRequest, signer: Box<dyn Signer>, ) -> Result<Arc<LiquidSdk>>

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

Disconnects the LiquidSdk instance and stops the background tasks.

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

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

pub async fn get_info(&self) -> SdkResult<GetInfoResponse>

Get the wallet info from persistant storage

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

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

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.

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, a BOLT11 invoice or a BOLT12 offer
  • amount - The optional amount of type PayAmount. Should only be specified when paying directly onchain or via amount-less BIP21.
    • PayAmount::Drain which uses all funds
    • PayAmount::Receiver which sets the amount the receiver should receive

Returns

Returns a PrepareSendResponse containing: * destination - the parsed destination, of type SendDestination * fees_sat - the additional fees which will be paid by the sender

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

pub async fn fetch_lightning_limits( &self, ) -> Result<LightningPaymentLimitsResponse, PaymentError>

Fetch the current payment limits for LiquidSdk::send_payment and LiquidSdk::receive_payment.

pub async fn fetch_onchain_limits( &self, ) -> Result<OnchainPaymentLimitsResponse, PaymentError>

Fetch the current payment limits for LiquidSdk::pay_onchain and LiquidSdk::receive_onchain.

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: PayAmount::Drain, which uses all funds, and PayAmount::Receiver, which sets the amount the receiver should receive
  • fee_rate_sat_per_vbyte - the optional fee rate of the Bitcoin claim transaction. Defaults to the swapper estimated claim fee

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 to
  • prepare_response - the PreparePayOnchainResponse from calling LiquidSdk::prepare_pay_onchain

Errors

• PaymentError::PaymentTimeout - if the payment could not be initiated in this time

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 payer
  • payment_method - the supported payment methods; either an invoice, a Liquid address or a Bitcoin address

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_payment
  • description - the optional payment description
  • use_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

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.

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_address
  • refund_address - the Bitcoin address to refund to
  • fee_rate_sat_per_vbyte - the fee rate at which to broadcast the refund transaction

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_address
  • refund_address - the Bitcoin address to refund to
  • fee_rate_sat_per_vbyte - the fee rate at which to broadcast the refund transaction

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

Rescans all expired chain swaps created from calling LiquidSdk::receive_onchain to check if there are any confirmed funds available to refund.

Since it bypasses the monitoring period, this should be called rarely or when the caller expects there is a very old refundable chain swap. Otherwise, for relatively recent swaps (within last CHAIN_SWAP_MONITORING_PERIOD_BITCOIN_BLOCKS blocks = ~30 days), calling this is not necessary as it happens automatically in the background.

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 use
  • amount_sat - the amount in satoshis to buy from the provider

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_bitcoin
  • redirect_url - the optional redirect URL the provider should redirect to after purchase

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.

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

Returns

Returns an Option<Payment> if found, or None if no payment matches the given request.

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

Empties the Liquid Wallet cache for the Config::network.

pub async fn sync(&self, partial_sync: bool) -> SdkResult<()>

Synchronizes the local state with the mempool and onchain data.

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

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

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 parse
  • amount_msat - the amount in millisatoshis for this payment
  • comment - an optional comment for this payment
  • validate_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

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

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 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.

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.

pub async fn fetch_fiat_rates(&self) -> Result<Vec<Rate>, SdkError>

Fetch live rates of fiat currencies, sorted by name.

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.

pub async fn recommended_fees(&self) -> Result<RecommendedFees, SdkError>

Get the recommended BTC fees based on the configured mempool.space instance.

pub fn default_config( network: LiquidNetwork, breez_api_key: Option<String>, ) -> Result<Config, SdkError>

Get the full default Config for specific LiquidNetwork.

pub async fn parse(&self, input: &str) -> Result<InputType, PaymentError>

Parses a string into an InputType. See input_parser::parse.

Can optionally be configured to use external input parsers by providing external_input_parsers in Config.

pub fn parse_invoice(input: &str) -> Result<LNInvoice, PaymentError>

Parses a string into an LNInvoice. See invoice::parse_invoice.

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.