breez_sdk.udl

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;
 };

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

[Error]
enum ConnectError {
    "Generic",
    "RestoreOnly",
    "ServiceConnectivity",
};

[Error]
enum LnUrlAuthError {
    "Generic",
    "InvalidUri",
    "ServiceConnectivity",
};

[Error]
enum LnUrlPayError {
    "AlreadyPaid",
    "Generic",
    "InvalidAmount",
    "InvalidInvoice",
    "InvalidNetwork",
    "InvalidUri",
    "InvoiceExpired",
    "PaymentFailed",
    "PaymentTimeout",
    "RouteNotFound",
    "RouteTooExpensive",
    "ServiceConnectivity",
};

[Error]
enum LnUrlWithdrawError {
    "Generic",
    "InvalidAmount",
    "InvalidInvoice",
    "InvalidUri",
    "ServiceConnectivity",
    "InvoiceNoRoutingHints",
};

[Error]
enum ReceiveOnchainError {
    "Generic",
    "ServiceConnectivity",
    "SwapInProgress",
};

[Error]
enum ReceivePaymentError {
    "Generic",
    "InvalidAmount",
    "InvalidInvoice",
    "InvoiceExpired",
    "InvoiceNoDescription",
    "InvoicePreimageAlreadyExists",
    "ServiceConnectivity",
    "InvoiceNoRoutingHints",
};

[Error]
enum SendOnchainError {
    "Generic",
    "InvalidDestinationAddress",
    "OutOfRange",
    "PaymentFailed",
    "PaymentTimeout",
    "ServiceConnectivity",
};

[Error]
enum SendPaymentError {
    "AlreadyPaid",
    "Generic",
    "InvalidAmount",
    "InvalidInvoice",
    "InvoiceExpired",
    "InvalidNetwork",
    "PaymentFailed",
    "PaymentTimeout",
    "RouteNotFound",
    "RouteTooExpensive",
    "ServiceConnectivity",
};

[Error]
enum RedeemOnchainError {    
    "Generic",    
    "ServiceConnectivity",
    "InsufficientFunds",
};

enum EnvironmentType {
    "Production",
    "Staging",
};

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

dictionary GreenlightCredentials {
    sequence<u8> developer_key;
    sequence<u8> developer_cert;
};

dictionary GreenlightDeviceCredentials {
    sequence<u8> device;
};

[Enum]
interface NodeCredentials {
    Greenlight(GreenlightDeviceCredentials credentials);
};

dictionary GreenlightNodeConfig {
    GreenlightCredentials? partner_credentials;
    string? invite_code;
};

[Enum]
interface NodeConfig {
    Greenlight(GreenlightNodeConfig config);
};

dictionary Config {
    string breezserver;
    string chainnotifier_url;
    string? mempoolspace_url;
    string working_dir;
    Network network;
    u32 payment_timeout_sec;
    string? default_lsp_id;
    string? api_key;
    f64 maxfee_percent;
    u64 exemptfee_msat;
    NodeConfig node_config;
};

dictionary RouteHint {
    sequence<RouteHintHop> hops;
};

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;
};

dictionary UnspentTransactionOutput {
    sequence<u8> txid;
    u32 outnum;
    u64 amount_millisatoshi;
    string address;
    boolean reserved;
};

dictionary NodeState {
    string id;
    u32 block_height;
    u64 channels_balance_msat;
    u64 onchain_balance_msat;
    u64 pending_onchain_balance_msat;
    sequence<UnspentTransactionOutput> utxos;
    u64 max_payable_msat;
    u64 max_receivable_msat;
    u64 max_single_payment_amount_msat;
    u64 max_chan_reserve_msats;
    sequence<string> connected_peers;
    u64 max_receivable_single_payment_amount_msat;
    u64 total_inbound_liquidity_msats;
};

dictionary ConfigureNodeRequest {
    string? close_to_address;
};

dictionary ConnectRequest {
    Config config;
    sequence<u8> seed;
    boolean? restore_only = null;
};

dictionary SignMessageRequest {
    string message;
};

dictionary SignMessageResponse {
    string signature;
};

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

dictionary CheckMessageResponse {
    boolean is_valid;
};

enum PaymentTypeFilter {
    "Sent",
    "Received",
    "ClosedChannel",
};

dictionary MetadataFilter {
    string json_path;
    string json_value;
};

enum PaymentStatus {
    "Pending",
    "Complete",
    "Failed",
};

enum PaymentType {
    "Sent",
    "Received",
    "ClosedChannel"
};

dictionary Payment {
    string id;
    PaymentType payment_type;
    i64 payment_time;
    u64 amount_msat;
    u64 fee_msat;
    PaymentStatus status;
    string? error;
    string? description;
    PaymentDetails details;
    string? metadata;
};

dictionary ListPaymentsRequest {
    sequence<PaymentTypeFilter>? filters = null;
    sequence<MetadataFilter>? metadata_filters = null;
    i64? from_timestamp = null;
    i64? to_timestamp = null;
    boolean? include_failures = null;
    u32? offset = null;
    u32? limit = null;
};

[Enum]
interface PaymentDetails {
    Ln(LnPaymentDetails data);
    ClosedChannel(ClosedChannelPaymentDetails data);
};

dictionary TlvEntry {
    u64 field_number;
    sequence<u8> value;
};

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

dictionary AesSuccessActionDataDecrypted {
    string description;
    string plaintext;
};

dictionary MessageSuccessActionData {
    string message;
};

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

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

dictionary LnPaymentDetails {
    string payment_hash;
    string label;
    string destination_pubkey;
    string payment_preimage;
    boolean keysend;
    string bolt11;
    string? open_channel_bolt11;
    SuccessActionProcessed? lnurl_success_action;
    string? lnurl_pay_domain;
    string? lnurl_pay_comment;
    string? lnurl_metadata;
    string? ln_address;
    string? lnurl_withdraw_endpoint;
    SwapInfo? swap_info;
    ReverseSwapInfo? reverse_swap_info;
    u32? pending_expiration_block;
};

dictionary ClosedChannelPaymentDetails {
    ChannelState state;
    string funding_txid;
    string? short_channel_id;
    string? closing_txid;
};

enum ChannelState {
    "PendingOpen",
    "Opened",
    "PendingClose",
    "Closed",
};

dictionary Rate {
    string coin;
    f64 value;
};

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;
};

dictionary FiatCurrency {
    string id;
    CurrencyInfo info;
};

enum FeeratePreset {
    "Regular",
    "Economy",
    "Priority",
};

dictionary LogEntry {
    string line;
    string level;
};

dictionary InvoicePaidDetails {
    string payment_hash;
    string bolt11;
    Payment? payment;
};

dictionary PaymentFailedData {
    string error;
    string node_id;
    LNInvoice? invoice;
    string? label;
};

dictionary BackupFailedData {
    string error;
};

[Enum]
interface BreezEvent {
    NewBlock(u32 block);
    InvoicePaid(InvoicePaidDetails details);
    Synced();
    PaymentSucceed(Payment details);
    PaymentFailed(PaymentFailedData details);
    BackupStarted();
    BackupSucceeded();
    BackupFailed(BackupFailedData details);
    ReverseSwapUpdated(ReverseSwapInfo details);
    SwapUpdated(SwapInfo details);
};

dictionary BackupStatus {
    boolean backed_up;
    u64? last_backup_time;
};

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

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

dictionary OpeningFeeParams {
    u64 min_msat;
    u32 proportional;
    string valid_until;
    u32 max_idle_time;
    u32 max_client_to_self_delay;
    string promise;
};

dictionary ReverseSwapFeesRequest {
    u64? send_amount_sat = null;
    u32? claim_tx_feerate = null;
};

dictionary OnchainPaymentLimitsResponse {
    u64 min_sat;
    u64 max_sat;
    u64 max_payable_sat;
};

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

dictionary PrepareOnchainPaymentRequest {
    u64 amount_sat;
    SwapAmountType amount_type;
    u32 claim_tx_feerate;
};

dictionary ReceivePaymentRequest {
    u64 amount_msat;
    string description;
    sequence<u8>? preimage = null;
    OpeningFeeParams? opening_fee_params = null;
    boolean? use_description_hash = null;
    u32? expiry = null;
    u32? cltv = null;
};

dictionary ReceivePaymentResponse {
    LNInvoice ln_invoice;
    OpeningFeeParams? opening_fee_params;
    u64? opening_fee_msat;
};

dictionary StaticBackupRequest {
    string working_dir;
};

dictionary StaticBackupResponse {
    sequence<string>? backup;
};

dictionary ReceiveOnchainRequest {
    OpeningFeeParams? opening_fee_params = null;
};

dictionary BuyBitcoinRequest {
    BuyBitcoinProvider provider;
    OpeningFeeParams? opening_fee_params = null;
    string? redirect_url = null;
};

dictionary BuyBitcoinResponse {
    string url;
    OpeningFeeParams? opening_fee_params;
};

dictionary OpeningFeeParamsMenu {
    sequence<OpeningFeeParams> values;
};

dictionary LspInformation {
    string id;
    string name;
    string widget_url;
    string pubkey;
    string host;
    i64 base_fee_msat;
    f64 fee_rate;
    u32 time_lock_delta;
    i64 min_htlc_msat;
    sequence<u8> lsp_pubkey;
    OpeningFeeParamsMenu opening_fee_params_list;
};

dictionary OpenChannelFeeRequest {
    u64? amount_msat;
    u32? expiry = null;
};

dictionary OpenChannelFeeResponse {
    u64? fee_msat;
    OpeningFeeParams fee_params;
};

enum SwapStatus {
    "Initial",
    "WaitingConfirmation",
    "Redeemable",
    "Redeemed",
    "Refundable",
    "Completed",
};

enum ReverseSwapStatus {
    "Initial",
    "InProgress",
    "Cancelled",
    "CompletedSeen",
    "CompletedConfirmed",
};

dictionary SwapInfo {
    string bitcoin_address;
    i64 created_at;
    i64 lock_height;
    sequence<u8> payment_hash;
    sequence<u8> preimage;
    sequence<u8> private_key;
    sequence<u8> public_key;
    sequence<u8> swapper_public_key;
    sequence<u8> script;
    string? bolt11;
    u64 paid_msat;
    u64 unconfirmed_sats;
    u64 confirmed_sats;
    u64 total_incoming_txs;
    SwapStatus status;
    sequence<string> refund_tx_ids;
    sequence<string> unconfirmed_tx_ids;
    sequence<string> confirmed_tx_ids;
    i64 min_allowed_deposit;
    i64 max_allowed_deposit;
    i64 max_swapper_payable;
    string? last_redeem_error;
    OpeningFeeParams? channel_opening_fees;
    u32? confirmed_at;
};

dictionary ListSwapsRequest {
    sequence<SwapStatus>? status = null;
    i64? from_timestamp = null;
    i64? to_timestamp = null;
    u32? offset = null;
    u32? limit = null;
};

dictionary ReverseSwapPairInfo {
    u64 min;
    u64 max;
    string fees_hash;
    f64 fees_percentage;
    u64 fees_lockup;
    u64 fees_claim;
    u64? total_fees;
};

dictionary PrepareOnchainPaymentResponse {
    string fees_hash;
    f64 fees_percentage;
    u64 fees_lockup;
    u64 fees_claim;

    u64 sender_amount_sat;
    u64 recipient_amount_sat;
    u64 total_fees;
};

dictionary ReverseSwapInfo {
    string id;
    string claim_pubkey;
    string? lockup_txid;
    string? claim_txid;
    u64 onchain_amount_sat;
    ReverseSwapStatus status;
};

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

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

dictionary LnUrlErrorData {
    string reason;
};

dictionary LnUrlPayErrorData {
    string payment_hash;
    string reason;
};

dictionary LnUrlPayRequest {
    LnUrlPayRequestData data;
    u64 amount_msat;
    boolean use_trampoline;
    string? comment = null;
    string? payment_label = null;
    boolean? validate_success_action_url = null;
};

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;
};

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

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

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

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

dictionary LnUrlWithdrawSuccessData {
    LNInvoice invoice;
};

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

dictionary ReportPaymentFailureDetails {
    string payment_hash;
    string? comment = null;
};

[Enum]
interface ReportIssueRequest {
    PaymentFailure(ReportPaymentFailureDetails data);
};

enum HealthCheckStatus {
    "Operational",
    "Maintenance",
    "ServiceDisruption",
};

dictionary ServiceHealthCheckResponse {
    HealthCheckStatus status;
};

dictionary MetadataItem {
    string key;
    string value;
};

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

[Enum]
interface InputType {
    BitcoinAddress(BitcoinAddressData address);
    Bolt11(LNInvoice invoice);
    NodeId(string node_id);
    Url(string url);
    LnUrlPay(LnUrlPayRequestData data);
    LnUrlWithdraw(LnUrlWithdrawRequestData data);
    LnUrlAuth(LnUrlAuthRequestData data);
    LnUrlError(LnUrlErrorData data);
};

enum BuyBitcoinProvider {
    "Moonpay",
};

dictionary PrepareRedeemOnchainFundsRequest {
    string to_address;
    u32 sat_per_vbyte;
};

dictionary PrepareRedeemOnchainFundsResponse {
    u64 tx_weight;
    u64 tx_fee_sat;
};

dictionary RedeemOnchainFundsRequest {
    string to_address;
    u32 sat_per_vbyte;
};

dictionary RedeemOnchainFundsResponse {
    sequence<u8> txid;
};

dictionary SendPaymentRequest {
    string bolt11;
    boolean use_trampoline;
    u64? amount_msat = null;
    string? label = null;
};

dictionary SendSpontaneousPaymentRequest {
    string node_id;
    u64 amount_msat;
    sequence<TlvEntry>? extra_tlvs = null;
    string? label = null;
};

dictionary SendPaymentResponse {
    Payment payment;
};

dictionary PayOnchainRequest {
    string recipient_address;
    PrepareOnchainPaymentResponse prepare_res;
};

dictionary PayOnchainResponse {
    ReverseSwapInfo reverse_swap_info;
};

dictionary PrepareRefundRequest {
    string swap_address;
    string to_address;
    u32 sat_per_vbyte;
};

dictionary PrepareRefundResponse {
    u32 refund_tx_weight;
    u64 refund_tx_fee_sat;
};

dictionary RefundRequest {
    string swap_address;
    string to_address;
    u32 sat_per_vbyte;
};

dictionary RefundResponse {
    string refund_tx_id;
};

interface BlockingBreezServices {

   [Throws=SdkError]
   void disconnect();

   [Throws=SdkError]
   void configure_node(ConfigureNodeRequest req);

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

   [Throws=SendPaymentError]
   SendPaymentResponse send_spontaneous_payment(SendSpontaneousPaymentRequest req);

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

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

   [Throws=LnUrlWithdrawError]
   LnUrlWithdrawResult withdraw_lnurl(LnUrlWithdrawRequest request);

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

   [Throws=SdkError]
   void report_issue(ReportIssueRequest req);

   [Throws=SdkError]
   NodeCredentials? node_credentials();

   [Throws=SdkError]
   NodeState node_info();

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

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

   [Throws=SdkError]
   BackupStatus backup_status();

   [Throws=SdkError]
   void backup();

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

   [Throws=SdkError]
   Payment? payment_by_hash(string hash);

   [Throws=SdkError]
   void set_payment_metadata(string hash, string metadata);

   [Throws=RedeemOnchainError]
   RedeemOnchainFundsResponse redeem_onchain_funds(RedeemOnchainFundsRequest req);

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

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

   [Throws=SdkError]
   sequence<LspInformation> list_lsps();

   [Throws=SdkError]
   void connect_lsp(string lsp_id);

   [Throws=SdkError]
   LspInformation? fetch_lsp_info(string lsp_id);

   [Throws=SdkError]
   OpenChannelFeeResponse open_channel_fee(OpenChannelFeeRequest req);

   [Throws=SdkError]
   string? lsp_id();

   [Throws=SdkError]
   LspInformation lsp_info();

   [Throws=SdkError]
   void close_lsp_channels();

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

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

   [Throws=ReceiveOnchainError]
   SwapInfo receive_onchain(ReceiveOnchainRequest req);

   [Throws=SdkError]
   SwapInfo? in_progress_swap();
  
   [Throws=SdkError]
   void rescan_swaps();

   [Throws=SdkError]
   void redeem_swap(string swap_address);

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

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

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

   [Throws=SdkError]
   sequence<SwapInfo> list_swaps(ListSwapsRequest req);

   [Throws=SdkError]
   ReverseSwapPairInfo fetch_reverse_swap_fees(ReverseSwapFeesRequest req);

   [Throws=SdkError]
   OnchainPaymentLimitsResponse onchain_payment_limits();

   [Throws=SendOnchainError]
   PrepareOnchainPaymentResponse prepare_onchain_payment(PrepareOnchainPaymentRequest req);

   [Throws=SdkError]
   sequence<ReverseSwapInfo> in_progress_onchain_payments();

   [Throws=SdkError]
   void claim_reverse_swap(string lockup_address);

   [Throws=SendOnchainError]
   PayOnchainResponse pay_onchain(PayOnchainRequest req);

   [Throws=SdkError]
   string execute_dev_command(string command);

   [Throws=SdkError]
   string generate_diagnostic_data();

   [Throws=SdkError]
   void sync();

   [Throws=SdkError]
   RecommendedFees recommended_fees();

   [Throws=ReceiveOnchainError]
   BuyBitcoinResponse buy_bitcoin(BuyBitcoinRequest req);

   [Throws=RedeemOnchainError]
   PrepareRedeemOnchainFundsResponse prepare_redeem_onchain_funds(PrepareRedeemOnchainFundsRequest req);
};

namespace breez_sdk {  

 [Throws=ConnectError]
 BlockingBreezServices connect(ConnectRequest req, EventListener listener);

 [Throws=SdkError]
 void set_log_stream(LogStream log_stream);

 [Throws=SdkError]
 LNInvoice parse_invoice(string invoice);

 [Throws=SdkError]
 InputType parse_input(string s);

 [Throws=SdkError]
 sequence<u8> mnemonic_to_seed(string phrase);

 Config default_config(EnvironmentType env_type, string api_key, NodeConfig node_config);

 [Throws=SdkError]
 StaticBackupResponse static_backup(StaticBackupRequest req);

 [Throws=SdkError]
 ServiceHealthCheckResponse service_health_check(string api_key);
};