breez_sdk_liquid.udl

//////////////////////////////////
// BEGIN sdk-common mirror imports
// These are structs defined in sdk-common, which we want to make available in this project's UDL bindings

dictionary LNInvoice {
    string bolt11;
    Network network;
    string payee_pubkey;
    string payment_hash;
    string? description;
    string? description_hash;
    u64? amount_msat;
    u64 timestamp;
    u64 expiry;
    sequence<RouteHint> routing_hints;
    sequence<u8> payment_secret;
    u64 min_final_cltv_expiry_delta;
};

enum Network {
    "Bitcoin",
    "Testnet",
    "Signet",
    "Regtest",
};

dictionary RouteHint {
    sequence<RouteHintHop> hops;
};

dictionary RouteHintHop {
     string src_node_id;
     string short_channel_id;
     u32 fees_base_msat;
     u32 fees_proportional_millionths;
     u64 cltv_expiry_delta;
     u64? htlc_minimum_msat;
     u64? htlc_maximum_msat;
};

[Enum]
interface Amount {
    Bitcoin(u64 amount_msat);
    Currency(string iso4217_code, u64 fractional_amount);
};

dictionary LnOfferBlindedPath {
    sequence<string> blinded_hops;
};

dictionary LNOffer {
    string offer;
    sequence<string> chains;
    sequence<LnOfferBlindedPath> paths;
    string? description;
    string? signing_pubkey;
    Amount? min_amount;
    u64? absolute_expiry;
    string? issuer;
};

[Enum]
interface InputType {
    BitcoinAddress(BitcoinAddressData address);
    LiquidAddress(LiquidAddressData address);
    Bolt11(LNInvoice invoice);
    Bolt12Offer(LNOffer offer, string? bip353_address);
    NodeId(string node_id);
    Url(string url);
    LnUrlPay(LnUrlPayRequestData data, string? bip353_address);
    LnUrlWithdraw(LnUrlWithdrawRequestData data);
    LnUrlAuth(LnUrlAuthRequestData data);
    LnUrlError(LnUrlErrorData data);
};

dictionary BitcoinAddressData {
    string address;
    Network network;
    u64? amount_sat;
    string? label;
    string? message;
};

dictionary LiquidAddressData {
    string address;
    Network network;
    string? asset_id;
    f64? amount;
    u64? amount_sat;
    string? label;
    string? message;
};

dictionary LnUrlPayRequestData {
    string callback;
    u64 min_sendable;
    u64 max_sendable;
    string metadata_str;
    u16 comment_allowed;
    string domain;
    boolean allows_nostr;
    string? nostr_pubkey;
    string? ln_address;
};

dictionary LnUrlWithdrawRequestData {
    string callback;
    string k1;
    string default_description;
    u64 min_withdrawable;
    u64 max_withdrawable;
};

dictionary LnUrlAuthRequestData {
    string k1;
    string domain;
    string url;
    string? action = null;
};

dictionary LnUrlErrorData {
    string reason;
};

[Enum]
interface SuccessAction {
    Aes(AesSuccessActionData data);
    Message(MessageSuccessActionData data);
    Url(UrlSuccessActionData data);
};

[Enum]
interface SuccessActionProcessed {
    Aes(AesSuccessActionDataResult result);
    Message(MessageSuccessActionData data);
    Url(UrlSuccessActionData data);
};

[Enum]
interface AesSuccessActionDataResult {
    Decrypted(AesSuccessActionDataDecrypted data);
    ErrorStatus(string reason);
};

dictionary AesSuccessActionData {
    string description;
    string ciphertext;
    string iv;
};

dictionary AesSuccessActionDataDecrypted {
    string description;
    string plaintext;
};

dictionary MessageSuccessActionData {
    string message;
};

dictionary UrlSuccessActionData {
    string description;
    string url;
    boolean matches_callback_domain;
};

dictionary LnUrlPayErrorData {
    string payment_hash;
    string reason;
};

[Error]
interface LnUrlPayError {
    AlreadyPaid();
    Generic(string err);
    InvalidAmount(string err);
    InvalidInvoice(string err);
    InvalidNetwork(string err);
    InvalidUri(string err);
    InvoiceExpired(string err);
    PaymentFailed(string err);
    PaymentTimeout(string err);
    RouteNotFound(string err);
    RouteTooExpensive(string err);
    ServiceConnectivity(string err);
};

[Error]
interface LnUrlWithdrawError {
    Generic(string err);
    InvalidAmount(string err);
    InvalidInvoice(string err);
    InvalidUri(string err);
    ServiceConnectivity(string err);
    InvoiceNoRoutingHints(string err);
};

[Enum]
interface LnUrlWithdrawResult {
    Ok(LnUrlWithdrawSuccessData data);
    Timeout(LnUrlWithdrawSuccessData data);
    ErrorStatus(LnUrlErrorData data);
};

dictionary LnUrlWithdrawSuccessData {
    LNInvoice invoice;
};

dictionary LnUrlWithdrawRequestData {
    string callback;
    string k1;
    string default_description;
    u64 min_withdrawable;
    u64 max_withdrawable;
};

dictionary LnUrlWithdrawRequest {
    LnUrlWithdrawRequestData data;
    u64 amount_msat;
    string? description = null;
};

[Enum]
interface LnUrlCallbackStatus {
    Ok();
    ErrorStatus(LnUrlErrorData data);
};

[Error]
interface LnUrlAuthError {
    Generic(string err);
    InvalidUri(string err);
    ServiceConnectivity(string err);
};

dictionary Rate {
    string coin;
    f64 value;
};

dictionary FiatCurrency {
    string id;
    CurrencyInfo info;
};

dictionary Symbol {
    string? grapheme;
    string? template;
    boolean? rtl;
    u32? position;
};

dictionary LocaleOverrides {
    string locale;
    u32? spacing;
    Symbol symbol;
};

dictionary LocalizedName {
    string locale;
    string name;
};

dictionary CurrencyInfo {
    string name;
    u32 fraction_size;
    u32? spacing;
    Symbol? symbol;
    Symbol? uniq_symbol;
    sequence<LocalizedName> localized_name;
    sequence<LocaleOverrides> locale_overrides;
};

// END sdk-common mirror imports
////////////////////////////////

//////////////////////////////////
// BEGIN sdk-common wrappers
// These are connecting structures that glue relevant sdk-common structs to the SDK

[Enum]
interface LnUrlPayResult {
    EndpointSuccess(LnUrlPaySuccessData data);
    EndpointError(LnUrlErrorData data);
    PayError(LnUrlPayErrorData data);
};

dictionary LnUrlPaySuccessData {
    SuccessActionProcessed? success_action;
    Payment payment;
};

// END sdk-common wrappers
////////////////////////////////

[Error]
enum SdkError {
    "AlreadyStarted",
    "Generic",
    "NotStarted",
    "ServiceConnectivity",
};

[Error]
enum PaymentError {
    "AlreadyClaimed",
    "AlreadyPaid",
    "PaymentInProgress",
    "AmountOutOfRange",
    "AmountMissing",
    "AssetError",
    "Generic",
    "InvalidOrExpiredFees",
    "InsufficientFunds",
    "InvalidDescription",
    "InvalidInvoice",
    "InvalidNetwork",
    "InvalidPreimage",
    "LwkError",
    "PairsNotFound",
    "PaymentTimeout",
    "PersistError",
    "ReceiveError",
    "Refunded",
    "SelfTransferNotSupported",
    "SendError",
    "SignerError",
};

dictionary Config {
    string liquid_electrum_url;
    string bitcoin_electrum_url;
    string mempoolspace_url;
    string working_dir;
    LiquidNetwork network;
    u64 payment_timeout_sec;
    string? sync_service_url;
    string? breez_api_key;
    string? cache_dir;
    u64? zero_conf_max_amount_sat;
    boolean use_default_external_input_parsers = true;
    sequence<ExternalInputParser>? external_input_parsers = null;
    u32? onchain_fee_rate_leeway_sat_per_vbyte = null;
    sequence<AssetMetadata>? asset_metadata = null;
};

enum LiquidNetwork {
    "Mainnet",
    "Testnet",
    "Regtest",
};

dictionary ConnectRequest {
    Config config;    
    string? mnemonic = null;
    string? passphrase = null;
    sequence<u8>? seed = null;
};

dictionary ConnectWithSignerRequest {
  Config config;  
};

dictionary AssetBalance {
    string asset_id;
    u64 balance_sat;
    string? name;
    string? ticker;
    f64? balance;
};

dictionary BlockchainInfo {
    u32 liquid_tip;
    u32 bitcoin_tip;
};

dictionary WalletInfo {
    u64 balance_sat;
    u64 pending_send_sat;
    u64 pending_receive_sat;
    string fingerprint;
    string pubkey;
    sequence<AssetBalance> asset_balances;
};

dictionary GetInfoResponse {
    WalletInfo wallet_info;
    BlockchainInfo blockchain_info;
};

dictionary SignMessageRequest {
    string message;
};

dictionary SignMessageResponse {
    string signature;
};

dictionary CheckMessageRequest {
    string message;
    string pubkey;
    string signature;
};

dictionary CheckMessageResponse {
    boolean is_valid;
};

dictionary PrepareLnUrlPayRequest {
    LnUrlPayRequestData data;
    PayAmount amount;
    string? bip353_address = null;
    string? comment = null;
    boolean? validate_success_action_url = null;
};

dictionary PrepareLnUrlPayResponse {
    SendDestination destination;
    u64 fees_sat;
    LnUrlPayRequestData data;
    string? comment = null;
    SuccessAction? success_action = null;
};

dictionary LnUrlPayRequest {
    PrepareLnUrlPayResponse prepare_response;
};

dictionary PrepareSendRequest {
    string destination;
    PayAmount? amount = null;
};

[Enum]
interface SendDestination {
    LiquidAddress(LiquidAddressData address_data);
    Bolt11(LNInvoice invoice, string? bip353_address);
    Bolt12(LNOffer offer, u64 receiver_amount_sat, string? bip353_address);
};

dictionary PrepareSendResponse {
    SendDestination destination;
    u64 fees_sat;
};

dictionary SendPaymentRequest {
    PrepareSendResponse prepare_response;
};

dictionary SendPaymentResponse {
    Payment payment;
};

enum PaymentMethod {
    "Lightning",
    "BitcoinAddress",
    "LiquidAddress",
};

[Enum]
interface ReceiveAmount {
    Bitcoin(u64 payer_amount_sat);
    Asset(string asset_id, f64? payer_amount);
};

dictionary PrepareReceiveRequest {
    PaymentMethod payment_method;
    ReceiveAmount? amount = null;
};

dictionary PrepareReceiveResponse {
    PaymentMethod payment_method;
    u64 fees_sat;
    ReceiveAmount? amount;
    u64? min_payer_amount_sat;
    u64? max_payer_amount_sat;
    f64? swapper_feerate;
};

dictionary ReceivePaymentRequest {
    PrepareReceiveResponse prepare_response;
    string? description = null;
    boolean? use_description_hash = null;
};

dictionary ReceivePaymentResponse {
    string destination;
};

dictionary Limits {
    u64 min_sat;
    u64 max_sat;
    u64 max_zero_conf_sat;
};

dictionary LightningPaymentLimitsResponse {
    Limits send;
    Limits receive;
};

dictionary OnchainPaymentLimitsResponse {
    Limits send;
    Limits receive;
};

[Enum]
interface PayAmount {
    Bitcoin(u64 receiver_amount_sat);
    Asset(string asset_id, f64 receiver_amount);
    Drain();
};

dictionary PreparePayOnchainRequest {
    PayAmount amount;
    u32? fee_rate_sat_per_vbyte = null;
};

dictionary PreparePayOnchainResponse {
    u64 receiver_amount_sat;
    u64 claim_fees_sat;
    u64 total_fees_sat;
};

dictionary PayOnchainRequest {
    string address;
    PreparePayOnchainResponse prepare_response;
};

enum BuyBitcoinProvider {
    "Moonpay",
};

dictionary PrepareBuyBitcoinRequest {
    BuyBitcoinProvider provider;
    u64 amount_sat;
};

dictionary PrepareBuyBitcoinResponse {
    BuyBitcoinProvider provider;
    u64 amount_sat;
    u64 fees_sat;
};

dictionary BuyBitcoinRequest {
    PrepareBuyBitcoinResponse prepare_response;
    string? redirect_url = null;
};

dictionary BackupRequest {
    string? backup_path = null;
};

dictionary RestoreRequest {
    string? backup_path = null;
};

dictionary ListPaymentsRequest {
    sequence<PaymentType>? filters = null;
    sequence<PaymentState>? states = null;
    i64? from_timestamp = null;
    i64? to_timestamp = null;
    u32? offset = null;
    u32? limit = null;
    ListPaymentDetails? details = null;
    boolean? sort_ascending = null;
};

[Enum]
interface ListPaymentDetails {
    Liquid(string? asset_id, string? destination);
    Bitcoin(string? address);
};

[Enum]
interface GetPaymentRequest {
    PaymentHash(string payment_hash);
    SwapId(string swap_id);
};

dictionary FetchPaymentProposedFeesRequest {
    string swap_id;
};

dictionary FetchPaymentProposedFeesResponse {
    string swap_id;
    u64 fees_sat;
    u64 payer_amount_sat;
    u64 receiver_amount_sat;
};

dictionary AcceptPaymentProposedFeesRequest {
    FetchPaymentProposedFeesResponse response;
};

dictionary LnUrlInfo {
    string? ln_address;
    string? lnurl_pay_comment;
    string? lnurl_pay_domain;
    string? lnurl_pay_metadata;
    SuccessActionProcessed? lnurl_pay_success_action;
    SuccessAction? lnurl_pay_unprocessed_success_action;
    string? lnurl_withdraw_endpoint;
};

dictionary AssetInfo {
    string name;
    string ticker;
    f64 amount;
};

[Enum]
interface PaymentDetails {
    Lightning(string swap_id, string description, u32 liquid_expiration_blockheight, string? preimage, string? invoice, string? bolt12_offer, string? payment_hash, string? destination_pubkey, LnUrlInfo? lnurl_info, string? bip353_address, string? claim_tx_id, string? refund_tx_id, u64? refund_tx_amount_sat);
    Liquid(string asset_id, string destination, string description, AssetInfo? asset_info);
    Bitcoin(string swap_id, string description, boolean auto_accepted_fees, u32? bitcoin_expiration_blockheight, u32? liquid_expiration_blockheight, string? claim_tx_id, string? refund_tx_id, u64? refund_tx_amount_sat);
};

dictionary Payment {
    u32 timestamp;
    u64 amount_sat;
    u64 fees_sat;
    PaymentType payment_type;
    PaymentState status;
    PaymentDetails details;
    u64? swapper_fees_sat = null;
    string? destination = null;
    string? tx_id = null;
    string? unblinding_data = null;
};

enum PaymentType {
    "Receive",
    "Send",
};

enum PaymentState {
    "Created",
    "Pending",
    "Complete",
    "Failed",
    "TimedOut",
    "Refundable",
    "RefundPending",
    "WaitingFeeAcceptance",
};

dictionary RefundableSwap {
    string swap_address;
    u32 timestamp;
    u64 amount_sat;
    string? last_refund_tx_id;
};

dictionary RecommendedFees {
    u64 fastest_fee;
    u64 half_hour_fee;
    u64 hour_fee;
    u64 economy_fee;
    u64 minimum_fee;
};

dictionary PrepareRefundRequest {
    string swap_address;
    string refund_address;
    u32 fee_rate_sat_per_vbyte;
};

dictionary PrepareRefundResponse {
    u32 tx_vsize;
    u64 tx_fee_sat;
    string? last_refund_tx_id = null;
};

dictionary RefundRequest {
    string swap_address;
    string refund_address;
    u32 fee_rate_sat_per_vbyte;
};

dictionary RefundResponse {
    string refund_tx_id;
};

[Enum]
interface SdkEvent {
    PaymentFailed(Payment details);
    PaymentPending(Payment details);
    PaymentRefundable(Payment details);
    PaymentRefunded(Payment details);
    PaymentRefundPending(Payment details);
    PaymentSucceeded(Payment details);
    PaymentWaitingConfirmation(Payment details);
    PaymentWaitingFeeAcceptance(Payment details);
    Synced();
};

callback interface EventListener {    
    void on_event(SdkEvent e);
};

callback interface Logger {
    void log(LogEntry l);
};

dictionary LogEntry {
    string line;
    string level;
};

dictionary ExternalInputParser {
    string provider_id;
    string input_regex;
    string parser_url;
};

dictionary AssetMetadata {
    string asset_id;
    string name;
    string ticker;
    u8 precision;
};

namespace breez_sdk_liquid {
    [Throws=SdkError]
    BindingLiquidSdk connect(ConnectRequest req);

    [Throws=SdkError]
    BindingLiquidSdk connect_with_signer(ConnectWithSignerRequest req, Signer signer);

    [Throws=SdkError]
    void set_logger(Logger logger);
    
    [Throws=SdkError]
    Config default_config(LiquidNetwork network, string? breez_api_key);

    [Throws=PaymentError]
    LNInvoice parse_invoice(string input);
};

[Error]
interface SignerError { 
    Generic(string err);
};

callback interface Signer {
    [Throws=SignerError]
    sequence<u8> xpub();

    [Throws=SignerError]
    sequence<u8> derive_xpub(string derivation_path);

    [Throws=SignerError]
    sequence<u8> sign_ecdsa(sequence<u8> msg, string derivation_path);

    [Throws=SignerError]
    sequence<u8> sign_ecdsa_recoverable(sequence<u8> msg);

    [Throws=SignerError]
    sequence<u8> slip77_master_blinding_key();

    [Throws=SignerError]
    sequence<u8> hmac_sha256(sequence<u8> msg, string derivation_path);

    [Throws=SignerError]
    sequence<u8> ecies_encrypt(sequence<u8> msg);

    [Throws=SignerError]
    sequence<u8> ecies_decrypt(sequence<u8> msg);
};

interface BindingLiquidSdk {
    [Throws=SdkError]
    string add_event_listener(EventListener listener);

    [Throws=SdkError]
    void remove_event_listener(string id);

    [Throws=SdkError]
    GetInfoResponse get_info();

    [Throws=SdkError]
    SignMessageResponse sign_message(SignMessageRequest req);

    [Throws=SdkError]
    CheckMessageResponse check_message(CheckMessageRequest req);

    [Throws=PaymentError]
    InputType parse(string input);

    [Throws=PaymentError]
    PrepareSendResponse prepare_send_payment(PrepareSendRequest req);

    [Throws=PaymentError]
    SendPaymentResponse send_payment(SendPaymentRequest req);

    [Throws=PaymentError]
    PrepareReceiveResponse prepare_receive_payment(PrepareReceiveRequest req);

    [Throws=PaymentError]
    ReceivePaymentResponse receive_payment(ReceivePaymentRequest req);

    [Throws=PaymentError]
    LightningPaymentLimitsResponse fetch_lightning_limits();

    [Throws=PaymentError]
    OnchainPaymentLimitsResponse fetch_onchain_limits();

    [Throws=PaymentError]
    PreparePayOnchainResponse prepare_pay_onchain(PreparePayOnchainRequest req);

    [Throws=PaymentError]
    SendPaymentResponse pay_onchain(PayOnchainRequest req);

    [Throws=PaymentError]
    PrepareBuyBitcoinResponse prepare_buy_bitcoin(PrepareBuyBitcoinRequest req);

    [Throws=PaymentError]
    string buy_bitcoin(BuyBitcoinRequest req);

    [Throws=PaymentError]
    sequence<Payment> list_payments(ListPaymentsRequest req);

    [Throws=PaymentError]
    Payment? get_payment(GetPaymentRequest req);

    [Throws=SdkError]
    FetchPaymentProposedFeesResponse fetch_payment_proposed_fees(FetchPaymentProposedFeesRequest req);

    [Throws=PaymentError]
    void accept_payment_proposed_fees(AcceptPaymentProposedFeesRequest req);

    [Throws=SdkError]
    sequence<RefundableSwap> list_refundables();

    [Throws=SdkError]
    PrepareRefundResponse prepare_refund(PrepareRefundRequest req);

    [Throws=PaymentError]
    RefundResponse refund(RefundRequest req);

    [Throws=SdkError]
    void rescan_onchain_swaps();

    [Throws=SdkError]
    void sync();

    [Throws=SdkError]
    RecommendedFees recommended_fees();

    [Throws=SdkError]
    void backup(BackupRequest req);

    [Throws=SdkError]
    void restore(RestoreRequest req);

    [Throws=SdkError]
    void disconnect();

    [Throws=LnUrlPayError]
    PrepareLnUrlPayResponse prepare_lnurl_pay(PrepareLnUrlPayRequest req);

    [Throws=LnUrlPayError]
    LnUrlPayResult lnurl_pay(LnUrlPayRequest req);

    [Throws=LnUrlWithdrawError]
    LnUrlWithdrawResult lnurl_withdraw(LnUrlWithdrawRequest req);

    [Throws=LnUrlAuthError]
    LnUrlCallbackStatus lnurl_auth(LnUrlAuthRequestData req_data);

    [Throws=SdkError]
    void register_webhook(string webhook_url);

    [Throws=SdkError]
    void unregister_webhook();

    [Throws=SdkError]
    sequence<Rate> fetch_fiat_rates();

    [Throws=SdkError]
    sequence<FiatCurrency> list_fiat_currencies();
};