fedimint_gateway_client/
lib.rs

1use std::collections::BTreeMap;
2
3use bitcoin::address::NetworkUnchecked;
4use bitcoin::{Address, Txid};
5use fedimint_connectors::ServerResult;
6use fedimint_connectors::error::ServerError;
7use fedimint_core::PeerId;
8use fedimint_core::config::FederationId;
9use fedimint_core::invite_code::InviteCode;
10use fedimint_core::util::SafeUrl;
11use fedimint_gateway_common::{
12    ADDRESS_ENDPOINT, ADDRESS_RECHECK_ENDPOINT, BACKUP_ENDPOINT, BackupPayload,
13    CLOSE_CHANNELS_WITH_PEER_ENDPOINT, CONFIGURATION_ENDPOINT, CONNECT_FED_ENDPOINT,
14    CONNECT_PEER_ENDPOINT, CREATE_BOLT11_INVOICE_FOR_OPERATOR_ENDPOINT,
15    CREATE_BOLT12_OFFER_FOR_OPERATOR_ENDPOINT, ChannelInfo, CloseChannelsWithPeerRequest,
16    CloseChannelsWithPeerResponse, ConfigPayload, ConnectFedPayload, ConnectPeerRequest,
17    CreateInvoiceForOperatorPayload, CreateOfferPayload, CreateOfferResponse,
18    DepositAddressPayload, DepositAddressRecheckPayload, FEDERATION_STATUS_ENDPOINT,
19    FederationInfo, FederationStatusRequest, FederationStatusResponse, GATEWAY_INFO_ENDPOINT,
20    GET_BALANCES_ENDPOINT, GET_INVOICE_ENDPOINT, GET_LN_ONCHAIN_ADDRESS_ENDPOINT, GatewayBalances,
21    GatewayFedConfig, GatewayInfo, GetInvoiceRequest, GetInvoiceResponse, INVITE_CODES_ENDPOINT,
22    LEAVE_FED_ENDPOINT, LIST_CHANNELS_ENDPOINT, LIST_TRANSACTIONS_ENDPOINT, LeaveFedPayload,
23    ListTransactionsPayload, ListTransactionsResponse, MNEMONIC_ENDPOINT, MnemonicResponse,
24    OPEN_CHANNEL_ENDPOINT, OPEN_CHANNEL_WITH_PUSH_ENDPOINT, OpenChannelRequest,
25    PAY_INVOICE_FOR_OPERATOR_ENDPOINT, PAY_OFFER_FOR_OPERATOR_ENDPOINT, PAYMENT_LOG_ENDPOINT,
26    PAYMENT_SUMMARY_ENDPOINT, PEGIN_FROM_ONCHAIN_ENDPOINT, PayInvoiceForOperatorPayload,
27    PayOfferPayload, PayOfferResponse, PaymentLogPayload, PaymentLogResponse,
28    PaymentSummaryPayload, PaymentSummaryResponse, PeginFromOnchainPayload, RECEIVE_ECASH_ENDPOINT,
29    ReceiveEcashPayload, ReceiveEcashResponse, SEND_ONCHAIN_ENDPOINT, SET_CHANNEL_FEES_ENDPOINT,
30    SET_FEES_ENDPOINT, SPEND_ECASH_ENDPOINT, STOP_ENDPOINT, SendOnchainRequest,
31    SetChannelFeesRequest, SetFeesPayload, SetMnemonicPayload, SpendEcashPayload,
32    SpendEcashResponse, WITHDRAW_ENDPOINT, WITHDRAW_TO_ONCHAIN_ENDPOINT, WithdrawPayload,
33    WithdrawResponse, WithdrawToOnchainPayload,
34};
35use fedimint_ln_common::Method;
36use fedimint_ln_common::client::GatewayApi;
37use lightning_invoice::Bolt11Invoice;
38
39pub async fn get_info(client: &GatewayApi, base_url: &SafeUrl) -> ServerResult<GatewayInfo> {
40    client
41        .request::<(), GatewayInfo>(base_url, Method::GET, GATEWAY_INFO_ENDPOINT, None)
42        .await
43}
44
45/// Queries one federation's public, sanitized gateway capability and
46/// registration status.
47///
48/// Gateway UI, CLI, and server use one release, so the request does not
49/// negotiate endpoint versions. Transport failures, malformed responses, and
50/// non-success statuses remain errors.
51pub async fn get_federation_status(
52    client: &GatewayApi,
53    base_url: &SafeUrl,
54    federation_id: FederationId,
55) -> ServerResult<FederationStatusResponse> {
56    let status = client
57        .request::<_, FederationStatusResponse>(
58            base_url,
59            Method::POST,
60            FEDERATION_STATUS_ENDPOINT,
61            Some(FederationStatusRequest { federation_id }),
62        )
63        .await?;
64    validate_federation_status(status, federation_id)
65}
66
67fn validate_federation_status(
68    status: FederationStatusResponse,
69    federation_id: FederationId,
70) -> ServerResult<FederationStatusResponse> {
71    if status.federation_id() != federation_id {
72        return Err(ServerError::InvalidResponse(anyhow::anyhow!(
73            "Gateway federation status response names a different federation"
74        )));
75    }
76    Ok(status)
77}
78
79pub async fn get_config(
80    client: &GatewayApi,
81    base_url: &SafeUrl,
82    payload: ConfigPayload,
83) -> ServerResult<GatewayFedConfig> {
84    client
85        .request(
86            base_url,
87            Method::POST,
88            CONFIGURATION_ENDPOINT,
89            Some(payload),
90        )
91        .await
92}
93
94pub async fn get_deposit_address(
95    client: &GatewayApi,
96    base_url: &SafeUrl,
97    payload: DepositAddressPayload,
98) -> ServerResult<Address<NetworkUnchecked>> {
99    client
100        .request(base_url, Method::POST, ADDRESS_ENDPOINT, Some(payload))
101        .await
102}
103
104pub async fn pegin_from_onchain(
105    client: &GatewayApi,
106    base_url: &SafeUrl,
107    payload: PeginFromOnchainPayload,
108) -> ServerResult<Txid> {
109    client
110        .request(
111            base_url,
112            Method::POST,
113            PEGIN_FROM_ONCHAIN_ENDPOINT,
114            Some(payload),
115        )
116        .await
117}
118
119pub async fn withdraw(
120    client: &GatewayApi,
121    base_url: &SafeUrl,
122    payload: WithdrawPayload,
123) -> ServerResult<WithdrawResponse> {
124    client
125        .request(base_url, Method::POST, WITHDRAW_ENDPOINT, Some(payload))
126        .await
127}
128
129pub async fn withdraw_to_onchain(
130    client: &GatewayApi,
131    base_url: &SafeUrl,
132    payload: WithdrawToOnchainPayload,
133) -> ServerResult<WithdrawResponse> {
134    client
135        .request(
136            base_url,
137            Method::POST,
138            WITHDRAW_TO_ONCHAIN_ENDPOINT,
139            Some(payload),
140        )
141        .await
142}
143
144pub async fn connect_federation(
145    client: &GatewayApi,
146    base_url: &SafeUrl,
147    payload: ConnectFedPayload,
148) -> ServerResult<FederationInfo> {
149    client
150        .request(base_url, Method::POST, CONNECT_FED_ENDPOINT, Some(payload))
151        .await
152}
153
154pub async fn leave_federation(
155    client: &GatewayApi,
156    base_url: &SafeUrl,
157    payload: LeaveFedPayload,
158) -> ServerResult<FederationInfo> {
159    client
160        .request(base_url, Method::POST, LEAVE_FED_ENDPOINT, Some(payload))
161        .await
162}
163
164pub async fn backup(
165    client: &GatewayApi,
166    base_url: &SafeUrl,
167    payload: BackupPayload,
168) -> ServerResult<()> {
169    client
170        .request(base_url, Method::POST, BACKUP_ENDPOINT, Some(payload))
171        .await
172}
173
174pub async fn set_fees(
175    client: &GatewayApi,
176    base_url: &SafeUrl,
177    payload: SetFeesPayload,
178) -> ServerResult<()> {
179    client
180        .request(base_url, Method::POST, SET_FEES_ENDPOINT, Some(payload))
181        .await
182}
183
184pub async fn create_invoice_for_self(
185    client: &GatewayApi,
186    base_url: &SafeUrl,
187    payload: CreateInvoiceForOperatorPayload,
188) -> ServerResult<Bolt11Invoice> {
189    client
190        .request(
191            base_url,
192            Method::POST,
193            CREATE_BOLT11_INVOICE_FOR_OPERATOR_ENDPOINT,
194            Some(payload),
195        )
196        .await
197}
198
199pub async fn pay_invoice(
200    client: &GatewayApi,
201    base_url: &SafeUrl,
202    payload: PayInvoiceForOperatorPayload,
203) -> ServerResult<String> {
204    client
205        .request(
206            base_url,
207            Method::POST,
208            PAY_INVOICE_FOR_OPERATOR_ENDPOINT,
209            Some(payload),
210        )
211        .await
212}
213
214pub async fn get_ln_onchain_address(
215    client: &GatewayApi,
216    base_url: &SafeUrl,
217) -> ServerResult<Address<NetworkUnchecked>> {
218    client
219        .request::<(), Address<NetworkUnchecked>>(
220            base_url,
221            Method::GET,
222            GET_LN_ONCHAIN_ADDRESS_ENDPOINT,
223            None,
224        )
225        .await
226}
227
228pub async fn open_channel(
229    client: &GatewayApi,
230    base_url: &SafeUrl,
231    payload: OpenChannelRequest,
232) -> ServerResult<Txid> {
233    client
234        .request(base_url, Method::POST, OPEN_CHANNEL_ENDPOINT, Some(payload))
235        .await
236}
237
238pub async fn connect_peer(
239    client: &GatewayApi,
240    base_url: &SafeUrl,
241    payload: ConnectPeerRequest,
242) -> ServerResult<()> {
243    client
244        .request(base_url, Method::POST, CONNECT_PEER_ENDPOINT, Some(payload))
245        .await
246}
247
248pub async fn open_channel_with_push(
249    client: &GatewayApi,
250    base_url: &SafeUrl,
251    payload: OpenChannelRequest,
252) -> ServerResult<Txid> {
253    client
254        .request(
255            base_url,
256            Method::POST,
257            OPEN_CHANNEL_WITH_PUSH_ENDPOINT,
258            Some(payload),
259        )
260        .await
261}
262
263pub async fn close_channels_with_peer(
264    client: &GatewayApi,
265    base_url: &SafeUrl,
266    payload: CloseChannelsWithPeerRequest,
267) -> ServerResult<CloseChannelsWithPeerResponse> {
268    client
269        .request(
270            base_url,
271            Method::POST,
272            CLOSE_CHANNELS_WITH_PEER_ENDPOINT,
273            Some(payload),
274        )
275        .await
276}
277
278pub async fn list_channels(
279    client: &GatewayApi,
280    base_url: &SafeUrl,
281) -> ServerResult<Vec<ChannelInfo>> {
282    client
283        .request::<(), Vec<ChannelInfo>>(base_url, Method::GET, LIST_CHANNELS_ENDPOINT, None)
284        .await
285}
286
287pub async fn set_channel_fees(
288    client: &GatewayApi,
289    base_url: &SafeUrl,
290    payload: SetChannelFeesRequest,
291) -> ServerResult<()> {
292    client
293        .request(
294            base_url,
295            Method::POST,
296            SET_CHANNEL_FEES_ENDPOINT,
297            Some(payload),
298        )
299        .await
300}
301
302pub async fn send_onchain(
303    client: &GatewayApi,
304    base_url: &SafeUrl,
305    payload: SendOnchainRequest,
306) -> ServerResult<Txid> {
307    client
308        .request(base_url, Method::POST, SEND_ONCHAIN_ENDPOINT, Some(payload))
309        .await
310}
311
312pub async fn recheck_address(
313    client: &GatewayApi,
314    base_url: &SafeUrl,
315    payload: DepositAddressRecheckPayload,
316) -> ServerResult<serde_json::Value> {
317    client
318        .request(
319            base_url,
320            Method::POST,
321            ADDRESS_RECHECK_ENDPOINT,
322            Some(payload),
323        )
324        .await
325}
326
327pub async fn spend_ecash(
328    client: &GatewayApi,
329    base_url: &SafeUrl,
330    payload: SpendEcashPayload,
331) -> ServerResult<SpendEcashResponse> {
332    client
333        .request(base_url, Method::POST, SPEND_ECASH_ENDPOINT, Some(payload))
334        .await
335}
336
337pub async fn receive_ecash(
338    client: &GatewayApi,
339    base_url: &SafeUrl,
340    payload: ReceiveEcashPayload,
341) -> ServerResult<ReceiveEcashResponse> {
342    client
343        .request(
344            base_url,
345            Method::POST,
346            RECEIVE_ECASH_ENDPOINT,
347            Some(payload),
348        )
349        .await
350}
351
352pub async fn get_balances(
353    client: &GatewayApi,
354    base_url: &SafeUrl,
355) -> ServerResult<GatewayBalances> {
356    client
357        .request::<(), GatewayBalances>(base_url, Method::GET, GET_BALANCES_ENDPOINT, None)
358        .await
359}
360
361pub async fn get_mnemonic(
362    client: &GatewayApi,
363    base_url: &SafeUrl,
364) -> ServerResult<MnemonicResponse> {
365    client
366        .request::<(), MnemonicResponse>(base_url, Method::GET, MNEMONIC_ENDPOINT, None)
367        .await
368}
369
370pub async fn stop(client: &GatewayApi, base_url: &SafeUrl) -> ServerResult<()> {
371    client
372        .request::<(), ()>(base_url, Method::GET, STOP_ENDPOINT, None)
373        .await
374}
375
376pub async fn payment_log(
377    client: &GatewayApi,
378    base_url: &SafeUrl,
379    payload: PaymentLogPayload,
380) -> ServerResult<PaymentLogResponse> {
381    client
382        .request(base_url, Method::POST, PAYMENT_LOG_ENDPOINT, Some(payload))
383        .await
384}
385
386pub async fn payment_summary(
387    client: &GatewayApi,
388    base_url: &SafeUrl,
389    payload: PaymentSummaryPayload,
390) -> ServerResult<PaymentSummaryResponse> {
391    client
392        .request(
393            base_url,
394            Method::POST,
395            PAYMENT_SUMMARY_ENDPOINT,
396            Some(payload),
397        )
398        .await
399}
400
401pub async fn get_invoice(
402    client: &GatewayApi,
403    base_url: &SafeUrl,
404    payload: GetInvoiceRequest,
405) -> ServerResult<Option<GetInvoiceResponse>> {
406    client
407        .request(base_url, Method::POST, GET_INVOICE_ENDPOINT, Some(payload))
408        .await
409}
410
411pub async fn list_transactions(
412    client: &GatewayApi,
413    base_url: &SafeUrl,
414    payload: ListTransactionsPayload,
415) -> ServerResult<ListTransactionsResponse> {
416    client
417        .request(
418            base_url,
419            Method::POST,
420            LIST_TRANSACTIONS_ENDPOINT,
421            Some(payload),
422        )
423        .await
424}
425
426pub async fn create_offer(
427    client: &GatewayApi,
428    base_url: &SafeUrl,
429    payload: CreateOfferPayload,
430) -> ServerResult<CreateOfferResponse> {
431    client
432        .request(
433            base_url,
434            Method::POST,
435            CREATE_BOLT12_OFFER_FOR_OPERATOR_ENDPOINT,
436            Some(payload),
437        )
438        .await
439}
440
441pub async fn pay_offer(
442    client: &GatewayApi,
443    base_url: &SafeUrl,
444    payload: PayOfferPayload,
445) -> ServerResult<PayOfferResponse> {
446    client
447        .request(
448            base_url,
449            Method::POST,
450            PAY_OFFER_FOR_OPERATOR_ENDPOINT,
451            Some(payload),
452        )
453        .await
454}
455
456pub async fn set_mnemonic(
457    client: &GatewayApi,
458    base_url: &SafeUrl,
459    payload: SetMnemonicPayload,
460) -> ServerResult<()> {
461    client
462        .request(base_url, Method::POST, MNEMONIC_ENDPOINT, Some(payload))
463        .await
464}
465
466pub async fn get_invite_codes(
467    client: &GatewayApi,
468    base_url: &SafeUrl,
469) -> ServerResult<BTreeMap<FederationId, BTreeMap<PeerId, (String, InviteCode)>>> {
470    client
471        .request::<(), BTreeMap<FederationId, BTreeMap<PeerId, (String, InviteCode)>>>(
472            base_url,
473            Method::GET,
474            INVITE_CODES_ENDPOINT,
475            None,
476        )
477        .await
478}
479
480#[cfg(test)]
481mod tests;
fedimint_gateway_client/lib.rs

fedimint_gateway_client/
lib.rs
