ln_gateway/rpc/
mod.rs

1pub mod rpc_client;
2pub mod rpc_server;
3
4use std::collections::BTreeMap;
5
6use bitcoin::address::NetworkUnchecked;
7use bitcoin::{Address, Network};
8use fedimint_core::config::{FederationId, JsonClientConfig};
9use fedimint_core::core::{ModuleInstanceId, ModuleKind, OperationId};
10use fedimint_core::{secp256k1, Amount, BitcoinAmountOrAll};
11use fedimint_eventlog::{EventKind, EventLogId};
12use fedimint_mint_client::OOBNotes;
13use fedimint_wallet_client::PegOutFees;
14use lightning_invoice::Bolt11Invoice;
15use serde::{Deserialize, Serialize};
16
17use crate::config::LightningMode;
18use crate::db::FederationConfig;
19use crate::SafeUrl;
20
21pub const V1_API_ENDPOINT: &str = "v1";
22
23pub const ADDRESS_ENDPOINT: &str = "/address";
24pub const ADDRESS_RECHECK_ENDPOINT: &str = "/address_recheck";
25pub const BACKUP_ENDPOINT: &str = "/backup";
26pub const CONFIGURATION_ENDPOINT: &str = "/config";
27pub const CONNECT_FED_ENDPOINT: &str = "/connect_fed";
28pub const CREATE_BOLT11_INVOICE_FOR_OPERATOR_ENDPOINT: &str = "/create_bolt11_invoice_for_operator";
29pub const GATEWAY_INFO_ENDPOINT: &str = "/info";
30pub const GET_BALANCES_ENDPOINT: &str = "/balances";
31pub const GATEWAY_INFO_POST_ENDPOINT: &str = "/info";
32pub const GET_LN_ONCHAIN_ADDRESS_ENDPOINT: &str = "/get_ln_onchain_address";
33pub const LEAVE_FED_ENDPOINT: &str = "/leave_fed";
34pub const LIST_ACTIVE_CHANNELS_ENDPOINT: &str = "/list_active_channels";
35pub const MNEMONIC_ENDPOINT: &str = "/mnemonic";
36pub const OPEN_CHANNEL_ENDPOINT: &str = "/open_channel";
37pub const CLOSE_CHANNELS_WITH_PEER_ENDPOINT: &str = "/close_channels_with_peer";
38pub const PAY_INVOICE_FOR_OPERATOR_ENDPOINT: &str = "/pay_invoice_for_operator";
39pub const PAYMENT_LOG_ENDPOINT: &str = "/payment_log";
40pub const RECEIVE_ECASH_ENDPOINT: &str = "/receive_ecash";
41pub const SET_FEES_ENDPOINT: &str = "/set_fees";
42pub const STOP_ENDPOINT: &str = "/stop";
43pub const SEND_ONCHAIN_ENDPOINT: &str = "/send_onchain";
44pub const SPEND_ECASH_ENDPOINT: &str = "/spend_ecash";
45pub const WITHDRAW_ENDPOINT: &str = "/withdraw";
46
47type GatewayTransactionEvent = (
48    EventLogId,
49    EventKind,
50    Option<(ModuleKind, ModuleInstanceId)>,
51    u64,
52    serde_json::Value,
53);
54
55#[derive(Debug, Serialize, Deserialize, Clone)]
56pub struct ConnectFedPayload {
57    pub invite_code: String,
58    #[serde(default)]
59    #[cfg(feature = "tor")]
60    pub use_tor: Option<bool>,
61    pub recover: Option<bool>,
62}
63
64#[derive(Debug, Serialize, Deserialize, Clone)]
65pub struct LeaveFedPayload {
66    pub federation_id: FederationId,
67}
68
69#[derive(Debug, Serialize, Deserialize)]
70pub struct InfoPayload;
71
72#[derive(Debug, Serialize, Deserialize)]
73pub struct BackupPayload {
74    pub federation_id: FederationId,
75}
76
77#[derive(Debug, Serialize, Deserialize, Clone)]
78pub struct ConfigPayload {
79    pub federation_id: Option<FederationId>,
80}
81
82#[derive(Debug, Serialize, Deserialize, Clone)]
83pub struct DepositAddressPayload {
84    pub federation_id: FederationId,
85}
86
87#[derive(Debug, Serialize, Deserialize, Clone)]
88pub struct DepositAddressRecheckPayload {
89    pub address: Address<NetworkUnchecked>,
90    pub federation_id: FederationId,
91}
92
93#[derive(Debug, Serialize, Deserialize, Clone)]
94pub struct WithdrawPayload {
95    pub federation_id: FederationId,
96    pub amount: BitcoinAmountOrAll,
97    pub address: Address<NetworkUnchecked>,
98}
99
100#[derive(Debug, Serialize, Deserialize, Clone)]
101pub struct WithdrawResponse {
102    pub txid: bitcoin::Txid,
103    pub fees: PegOutFees,
104}
105
106/// Information about one of the feds we are connected to
107#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
108pub struct FederationInfo {
109    pub federation_id: FederationId,
110    pub federation_name: Option<String>,
111    pub balance_msat: Amount,
112    pub config: FederationConfig,
113}
114
115#[derive(Debug, Serialize, Deserialize, PartialEq)]
116pub struct GatewayInfo {
117    pub version_hash: String,
118    pub federations: Vec<FederationInfo>,
119    /// Mapping from short channel id to the federation id that it belongs to.
120    // TODO: Remove this alias once it no longer breaks backwards compatibility.
121    #[serde(alias = "channels")]
122    pub federation_fake_scids: Option<BTreeMap<u64, FederationId>>,
123    pub lightning_pub_key: Option<String>,
124    pub lightning_alias: Option<String>,
125    pub gateway_id: secp256k1::PublicKey,
126    pub gateway_state: String,
127    pub network: Network,
128    // TODO: This is here to allow for backwards compatibility with old versions of this struct. We
129    // should be able to remove it once 0.4.0 is released.
130    #[serde(default)]
131    pub block_height: Option<u32>,
132    // TODO: This is here to allow for backwards compatibility with old versions of this struct. We
133    // should be able to remove it once 0.4.0 is released.
134    #[serde(default)]
135    pub synced_to_chain: bool,
136    pub api: SafeUrl,
137    pub lightning_mode: LightningMode,
138}
139
140#[derive(Debug, Serialize, Deserialize, PartialEq)]
141pub struct GatewayFedConfig {
142    pub federations: BTreeMap<FederationId, JsonClientConfig>,
143}
144
145#[derive(Debug, Serialize, Deserialize, Clone)]
146pub struct SetFeesPayload {
147    pub federation_id: Option<FederationId>,
148    pub lightning_base: Option<Amount>,
149    pub lightning_parts_per_million: Option<u64>,
150    pub transaction_base: Option<Amount>,
151    pub transaction_parts_per_million: Option<u64>,
152}
153
154#[derive(Debug, Serialize, Deserialize, Clone)]
155pub struct CreateInvoiceForOperatorPayload {
156    pub amount_msats: u64,
157    pub expiry_secs: Option<u32>,
158    pub description: Option<String>,
159}
160
161#[derive(Debug, Serialize, Deserialize, Clone)]
162pub struct PayInvoiceForOperatorPayload {
163    pub invoice: Bolt11Invoice,
164}
165
166#[derive(Debug, Serialize, Deserialize, Clone)]
167pub struct SpendEcashPayload {
168    /// Federation id of the e-cash to spend
169    pub federation_id: FederationId,
170    /// The amount of e-cash to spend
171    pub amount: Amount,
172    /// If the exact amount cannot be represented, return e-cash of a higher
173    /// value instead of failing
174    #[serde(default)]
175    pub allow_overpay: bool,
176    /// After how many seconds we will try to reclaim the e-cash if it
177    /// hasn't been redeemed by the recipient. Defaults to one week.
178    #[serde(default = "default_timeout")]
179    pub timeout: u64,
180    /// If the necessary information to join the federation the e-cash
181    /// belongs to should be included in the serialized notes
182    #[serde(default)]
183    pub include_invite: bool,
184}
185
186/// Default timeout for e-cash redemption of one week in seconds
187fn default_timeout() -> u64 {
188    604_800
189}
190
191#[derive(Debug, Serialize, Deserialize, Clone)]
192pub struct SpendEcashResponse {
193    pub operation_id: OperationId,
194    pub notes: OOBNotes,
195}
196
197#[derive(Debug, Serialize, Deserialize, Clone)]
198pub struct ReceiveEcashPayload {
199    pub notes: OOBNotes,
200    #[serde(default)]
201    pub wait: bool,
202}
203
204#[derive(Debug, Serialize, Deserialize, Clone)]
205pub struct ReceiveEcashResponse {
206    pub amount: Amount,
207}
208
209#[derive(serde::Serialize, serde::Deserialize)]
210pub struct GatewayBalances {
211    pub onchain_balance_sats: u64,
212    pub lightning_balance_msats: u64,
213    pub ecash_balances: Vec<FederationBalanceInfo>,
214    pub inbound_lightning_liquidity_msats: u64,
215}
216
217#[derive(serde::Serialize, serde::Deserialize)]
218pub struct FederationBalanceInfo {
219    pub federation_id: FederationId,
220    pub ecash_balance_msats: Amount,
221}
222
223#[derive(Debug, Serialize, Deserialize, Clone)]
224pub struct MnemonicResponse {
225    pub mnemonic: Vec<String>,
226
227    // Legacy federations are federations that the gateway joined prior to v0.5.0
228    // and do not derive their secrets from the gateway's mnemonic. They also use
229    // a separate database from the gateway's db.
230    pub legacy_federations: Vec<FederationId>,
231}
232
233#[derive(Debug, Serialize, Deserialize, Clone)]
234pub struct PaymentLogPayload {
235    // The position in the log to stop querying. No events will be returned from after
236    // this `EventLogId`. If it is `None`, the last `EventLogId` is used.
237    pub end_position: Option<EventLogId>,
238
239    // The number of events to return
240    pub pagination_size: usize,
241
242    pub federation_id: FederationId,
243    pub event_kinds: Vec<EventKind>,
244}
245
246#[derive(Debug, Serialize, Deserialize, Clone)]
247pub struct PaymentLogResponse(pub Vec<GatewayTransactionEvent>);
ln_gateway/rpc/mod.rs

ln_gateway/rpc/
mod.rs
