Skip to main content

fedimint_lightning/
lnd.rs

1use std::collections::BTreeMap;
2use std::fmt::{self, Display};
3use std::str::FromStr;
4use std::sync::Arc;
5use std::time::{Duration, UNIX_EPOCH};
6
7use async_trait::async_trait;
8use bitcoin::OutPoint;
9use bitcoin::hashes::{Hash, sha256};
10use fedimint_core::encoding::Encodable;
11use fedimint_core::task::{TaskGroup, sleep};
12use fedimint_core::util::FmtCompact;
13use fedimint_core::{Amount, BitcoinAmountOrAll, crit, secp256k1};
14use fedimint_gateway_common::{
15    ConnectPeerRequest, ListTransactionsResponse, PaymentDetails, PaymentDirection, PaymentKind,
16};
17use fedimint_ln_common::PrunedInvoice;
18use fedimint_ln_common::contracts::Preimage;
19use fedimint_ln_common::route_hints::{RouteHint, RouteHintHop};
20use fedimint_logging::LOG_LIGHTNING;
21use hex::ToHex;
22use secp256k1::PublicKey;
23use tokio::sync::mpsc;
24use tokio_stream::wrappers::ReceiverStream;
25use tonic_lnd::invoicesrpc::lookup_invoice_msg::InvoiceRef;
26use tonic_lnd::invoicesrpc::{
27    AddHoldInvoiceRequest, CancelInvoiceMsg, LookupInvoiceMsg, SettleInvoiceMsg,
28    SubscribeSingleInvoiceRequest,
29};
30use tonic_lnd::lnrpc::channel_point::FundingTxid;
31use tonic_lnd::lnrpc::failure::FailureCode;
32use tonic_lnd::lnrpc::invoice::InvoiceState;
33use tonic_lnd::lnrpc::payment::PaymentStatus;
34use tonic_lnd::lnrpc::policy_update_request::Scope as PolicyUpdateScope;
35use tonic_lnd::lnrpc::{
36    ChanInfoRequest, ChannelBalanceRequest, ChannelPoint, CloseChannelRequest,
37    ConnectPeerRequest as LndConnectPeerRequest, FeeReportRequest, GetInfoRequest, Invoice,
38    InvoiceHtlc, InvoiceHtlcState, InvoiceSubscription, LightningAddress, ListChannelsRequest,
39    ListInvoiceRequest, ListPaymentsRequest, ListPeersRequest, OpenChannelRequest,
40    PolicyUpdateRequest, SendCoinsRequest, UpdateFailure, WalletBalanceRequest,
41};
42use tonic_lnd::routerrpc::{
43    CircuitKey, ForwardHtlcInterceptResponse, ResolveHoldForwardAction, SendPaymentRequest,
44    TrackPaymentRequest,
45};
46use tonic_lnd::tonic::Code;
47use tonic_lnd::walletrpc::AddrRequest;
48use tonic_lnd::{Client as LndClient, connect};
49use tracing::{debug, info, trace, warn};
50
51use super::{
52    ChannelInfo, ILnRpcClient, LightningRpcError, ListChannelsResponse, Lnv2HoldInvoiceFilter,
53    MAX_LIGHTNING_RETRIES, RouteHtlcStream,
54};
55use crate::{
56    CloseChannelsWithPeerRequest, CloseChannelsWithPeerResponse, CreateInvoiceRequest,
57    CreateInvoiceResponse, GetBalancesResponse, GetInvoiceRequest, GetInvoiceResponse,
58    GetLnOnchainAddressResponse, GetNodeInfoResponse, GetRouteHintsResponse,
59    InterceptPaymentRequest, InterceptPaymentResponse, InvoiceDescription, NO_INCOMING_CIRCUIT,
60    OpenChannelResponse, PayInvoiceResponse, PaymentAction, SendOnchainRequest,
61    SendOnchainResponse, SetChannelFeesRequest,
62};
63
64type HtlcSubscriptionSender = mpsc::Sender<InterceptPaymentRequest>;
65
66/// Final CLTV delta of the HOLD invoices created for LNv2 receives. Left unset,
67/// LND would use its routing `bitcoin.timelockdelta`, which operators may lower
68/// to 24 (18 before v0.21), leaving only a few blocks between accepting a
69/// payment and LND cancelling it by itself `invoices.holdexpirydelta` blocks
70/// before expiry. LND rejects any HTLC expiring sooner than this many blocks
71/// after it arrives, so it bounds every accepted HTLC, not just honest payers.
72const LNV2_HOLD_INVOICE_CLTV_EXPIRY: u64 = 144;
73
74/// How many blocks before its earliest HTLC expiry LND is assumed to cancel an
75/// accepted HOLD invoice by itself. LND's `invoices.holdexpirydelta` defaults
76/// to 18 since v0.21 (16 + 2) and 12 before, has no upper bound, and cannot be
77/// read cheaply before v0.21 (`GetDebugInfo` returns the whole log), so this
78/// assumes twice the current default. The excess also absorbs blocks found
79/// between the deadline check and settlement. It costs nothing for a payment
80/// handled promptly, which still has about 108 blocks left under
81/// `LNV2_HOLD_INVOICE_CLTV_EXPIRY`.
82const LND_ASSUMED_HOLD_EXPIRY_DELTA: u32 = 36;
83
84/// Whether a HOLD invoice accepted an HTLC without an MPP total. For the
85/// non-blinded HOLD invoices the gateway creates, standard LND builds require
86/// the payment address, which travels in the MPP record, from every HTLC
87/// except one carrying a keysend record. Since LND v0.20.3 and v0.21.2 that
88/// record must hold the invoice's preimage; before, any value passes unless
89/// `accept-keysend` is on.
90fn has_accepted_keysend_htlc(htlcs: &[InvoiceHtlc]) -> bool {
91    htlcs
92        .iter()
93        .any(|htlc| htlc.state() == InvoiceHtlcState::Accepted && htlc.mpp_total_amt_msat == 0)
94}
95
96/// Block height at which LND is assumed to cancel an accepted HOLD invoice by
97/// itself, `LND_ASSUMED_HOLD_EXPIRY_DELTA` blocks before its earliest accepted
98/// HTLC expires, after which the gateway can no longer settle it. Without an
99/// accepted HTLC there is no deadline to trust, so it is `0`.
100///
101/// The same holds once a keysend HTLC is accepted (see
102/// [`has_accepted_keysend_htlc`]): the invoice then keeps accepting further
103/// keysend HTLCs, and until it restarts LND neither reports them nor moves its
104/// cancel height for them.
105fn hold_invoice_claim_deadline(htlcs: &[InvoiceHtlc]) -> u32 {
106    if has_accepted_keysend_htlc(htlcs) {
107        return 0;
108    }
109
110    htlcs
111        .iter()
112        .filter(|htlc| htlc.state() == InvoiceHtlcState::Accepted)
113        .map(|htlc| (htlc.expiry_height as u32).saturating_sub(LND_ASSUMED_HOLD_EXPIRY_DELTA))
114        .min()
115        .unwrap_or_default()
116}
117
118/// The hex preimage of an LND invoice, if LND knows it. A HOLD invoice has no
119/// preimage until it is settled, so `r_preimage` is empty while one is pending
120/// or after it was canceled.
121fn invoice_preimage_hex(invoice: &Invoice) -> Option<String> {
122    <[u8; 32]>::try_from(invoice.r_preimage.as_slice())
123        .ok()
124        .map(|preimage| preimage.consensus_encode_to_hex())
125}
126
127#[derive(Debug, Clone, Copy, Eq, PartialEq)]
128enum HoldInvoiceAction {
129    Complete,
130    AlreadyComplete,
131}
132
133#[derive(Debug, Clone, Copy, Eq, PartialEq)]
134struct HoldInvoiceStateError {
135    failure_reason: &'static str,
136    permanent: bool,
137}
138
139fn hold_invoice_action(
140    requested_action: PaymentActionKind,
141    invoice_state: Option<InvoiceState>,
142) -> Result<HoldInvoiceAction, HoldInvoiceStateError> {
143    match (requested_action, invoice_state) {
144        (PaymentActionKind::Settle, Some(InvoiceState::Accepted))
145        | (PaymentActionKind::Cancel, Some(InvoiceState::Open | InvoiceState::Accepted)) => {
146            Ok(HoldInvoiceAction::Complete)
147        }
148        (PaymentActionKind::Settle, Some(InvoiceState::Settled))
149        | (PaymentActionKind::Cancel, Some(InvoiceState::Canceled)) => {
150            Ok(HoldInvoiceAction::AlreadyComplete)
151        }
152        (PaymentActionKind::Settle, Some(InvoiceState::Canceled)) => Err(HoldInvoiceStateError {
153            failure_reason: "HOLD invoice was canceled instead of settled",
154            permanent: true,
155        }),
156        (PaymentActionKind::Cancel, Some(InvoiceState::Settled)) => Err(HoldInvoiceStateError {
157            failure_reason: "HOLD invoice was settled instead of canceled",
158            permanent: true,
159        }),
160        (PaymentActionKind::Settle, Some(InvoiceState::Open)) => Err(HoldInvoiceStateError {
161            failure_reason: "HOLD invoice is open and has no accepted HTLC to settle",
162            permanent: false,
163        }),
164        (_, None) => Err(HoldInvoiceStateError {
165            failure_reason: "HOLD invoice does not exist",
166            permanent: true,
167        }),
168    }
169}
170
171#[derive(Debug, Clone, Copy, Eq, PartialEq)]
172enum PaymentActionKind {
173    Settle,
174    Cancel,
175}
176
177fn channel_amounts_to_lnd(
178    channel_size_sats: u64,
179    push_amount_sats: u64,
180) -> Result<(i64, i64), LightningRpcError> {
181    let channel_size =
182        i64::try_from(channel_size_sats).map_err(|_| LightningRpcError::FailedToOpenChannel {
183            failure_reason: format!(
184                "channel_size_sats {channel_size_sats} does not fit in i64 (LND limit)"
185            ),
186        })?;
187    let push_amount =
188        i64::try_from(push_amount_sats).map_err(|_| LightningRpcError::FailedToOpenChannel {
189            failure_reason: format!(
190                "push_amount_sats {push_amount_sats} does not fit in i64 (LND limit)"
191            ),
192        })?;
193    Ok((channel_size, push_amount))
194}
195
196#[derive(Clone)]
197pub struct GatewayLndClient {
198    /// LND client
199    address: String,
200    tls_cert: String,
201    macaroon: String,
202    time_pref: f64,
203    /// How long (in seconds) LND keeps trying to route an outgoing payment
204    /// before giving up. Passed as `timeout_seconds` in `SendPaymentRequest`.
205    payment_timeout_secs: i32,
206    lnd_sender: Option<mpsc::Sender<ForwardHtlcInterceptResponse>>,
207    /// Predicate used to distinguish HOLD invoices the gateway created
208    /// (federation-bound) from unrelated HOLD invoices on the same LND node.
209    /// Without this, every HOLD invoice on a shared LND would be intercepted
210    /// as if it were federation-bound, producing invalid LNv1 responses that
211    /// crash LND's htlc_interceptor stream.
212    lnv2_filter: Lnv2HoldInvoiceFilter,
213}
214
215impl GatewayLndClient {
216    pub fn new(
217        address: String,
218        tls_cert: String,
219        macaroon: String,
220        time_pref: f64,
221        payment_timeout_secs: i32,
222        lnd_sender: Option<mpsc::Sender<ForwardHtlcInterceptResponse>>,
223        lnv2_filter: Lnv2HoldInvoiceFilter,
224    ) -> Self {
225        info!(
226            target: LOG_LIGHTNING,
227            address = %address,
228            tls_cert_path = %tls_cert,
229            macaroon = %macaroon,
230            time_pref,
231            payment_timeout_secs,
232            "Gateway configured to connect to LND LnRpcClient",
233        );
234        GatewayLndClient {
235            address,
236            tls_cert,
237            macaroon,
238            time_pref,
239            payment_timeout_secs,
240            lnd_sender,
241            lnv2_filter,
242        }
243    }
244
245    async fn connect(&self) -> Result<LndClient, LightningRpcError> {
246        let mut retries = 0;
247        let client = loop {
248            if MAX_LIGHTNING_RETRIES <= retries {
249                return Err(LightningRpcError::FailedToConnect);
250            }
251
252            retries += 1;
253
254            match connect(
255                self.address.clone(),
256                self.tls_cert.clone(),
257                self.macaroon.clone(),
258            )
259            .await
260            {
261                Ok(client) => break client,
262                Err(err) => {
263                    debug!(target: LOG_LIGHTNING, err = %err.fmt_compact(), "Couldn't connect to LND, retrying in 1 second...");
264                    sleep(Duration::from_secs(1)).await;
265                }
266            }
267        };
268
269        Ok(client)
270    }
271
272    async fn connect_peer_if_needed(
273        &self,
274        client: &mut LndClient,
275        pubkey: PublicKey,
276        host: String,
277    ) -> Result<(), LightningRpcError> {
278        let peers = client
279            .lightning()
280            .list_peers(ListPeersRequest { latest_error: true })
281            .await
282            .map_err(|e| LightningRpcError::FailedToConnectToPeer {
283                failure_reason: format!("Could not list peers: {e:?}"),
284            })?
285            .into_inner();
286
287        if peers.peers.into_iter().any(|peer| {
288            PublicKey::from_str(&peer.pub_key).expect("LND returned invalid peer public key")
289                == pubkey
290        }) {
291            return Ok(());
292        }
293
294        client
295            .lightning()
296            .connect_peer(LndConnectPeerRequest {
297                addr: Some(LightningAddress {
298                    pubkey: pubkey.to_string(),
299                    host,
300                }),
301                perm: false,
302                timeout: 10,
303            })
304            .await
305            .map_err(|e| LightningRpcError::FailedToConnectToPeer {
306                failure_reason: format!("Failed to connect to peer {e:?}"),
307            })?;
308
309        Ok(())
310    }
311
312    /// Spawns a new background task that subscribes to updates of a specific
313    /// HOLD invoice. When the HOLD invoice is ACCEPTED, we can request the
314    /// preimage from the Gateway. A new task is necessary because LND's
315    /// global `subscribe_invoices` does not currently emit updates for HOLD invoices: <https://github.com/lightningnetwork/lnd/issues/3120>
316    async fn spawn_lnv2_hold_invoice_subscription(
317        &self,
318        task_group: &TaskGroup,
319        payment_stream_group: TaskGroup,
320        gateway_sender: HtlcSubscriptionSender,
321        payment_hash: Vec<u8>,
322    ) -> Result<(), LightningRpcError> {
323        let mut client = self.connect().await?;
324
325        let self_copy = self.clone();
326        let r_hash = payment_hash.clone();
327        task_group.spawn("LND HOLD Invoice Subscription", |handle| async move {
328            let future_stream =
329                client
330                    .invoices()
331                    .subscribe_single_invoice(SubscribeSingleInvoiceRequest {
332                        r_hash: r_hash.clone(),
333                    });
334
335            let mut hold_stream = tokio::select! {
336                stream = future_stream => {
337                    match stream {
338                        Ok(stream) => stream.into_inner(),
339                        Err(err) => {
340                            crit!(target: LOG_LIGHTNING, err = %err.fmt_compact(), "Failed to subscribe to hold invoice updates, shutting down payment-stream subgroup to trigger gateway reconnect");
341                            payment_stream_group.shutdown();
342                            return;
343                        }
344                    }
345                },
346                () = handle.make_shutdown_rx() => {
347                    info!(target: LOG_LIGHTNING, "LND HOLD Invoice Subscription received shutdown signal");
348                    return;
349                }
350            };
351
352            loop {
353                let hold = tokio::select! {
354                    () = handle.make_shutdown_rx() => {
355                        info!(target: LOG_LIGHTNING, "LND HOLD Invoice Subscription received shutdown signal");
356                        break;
357                    }
358                    hold_update = hold_stream.message() => {
359                        match hold_update {
360                            Ok(Some(hold)) => hold,
361                            Ok(None) => {
362                                // LND closed the stream because the invoice
363                                // reached a terminal state (settled, canceled,
364                                // or expired).
365                                break;
366                            }
367                            Err(err) => {
368                                crit!(target: LOG_LIGHTNING, err = %err.fmt_compact(), "Error received over hold invoice update stream, shutting down payment-stream subgroup to trigger gateway reconnect");
369                                payment_stream_group.shutdown();
370                                break;
371                            }
372                        }
373                    }
374                };
375
376                debug!(
377                    target: LOG_LIGHTNING,
378                    payment_hash = %PrettyPaymentHash(&r_hash),
379                    state = %hold.state,
380                    "LND HOLD Invoice Update",
381                );
382
383                if hold.state() == InvoiceState::Accepted {
384                    // Only forward HOLD invoices that the gateway created on
385                    // behalf of a federation. We check here (rather than at
386                    // the new-invoice add-event) because the contract is
387                    // saved to gateway_db *after* the HOLD invoice is created
388                    // on LND, so the add-event races registration. By the
389                    // time `Accepted` fires the HTLC has arrived, which means
390                    // the BOLT11 invoice was published and the contract is
391                    // committed.
392                    let hash = sha256::Hash::from_slice(&hold.r_hash)
393                        .expect("LND payment hashes are 32 bytes");
394                    if !(self_copy.lnv2_filter)(hash).await {
395                        trace!(
396                            target: LOG_LIGHTNING,
397                            payment_hash = %PrettyPaymentHash(&hold.r_hash),
398                            "Ignoring HOLD invoice not created by this gateway",
399                        );
400                        continue;
401                    }
402
403                    if has_accepted_keysend_htlc(&hold.htlcs) {
404                        warn!(
405                            target: LOG_LIGHTNING,
406                            payment_hash = %PrettyPaymentHash(&hold.r_hash),
407                            "LNv2 HOLD invoice accepted a keysend HTLC, its claim deadline is not trusted",
408                        );
409                    }
410
411                    let (incoming_chan_id, htlc_id) = NO_INCOMING_CIRCUIT;
412                    let intercept = InterceptPaymentRequest {
413                        payment_hash: Hash::from_slice(&hold.r_hash.clone())
414                            .expect("Failed to convert to Hash"),
415                        // A HOLD invoice reports the real paid amount, so the
416                        // two amounts coincide here.
417                        amount_msat: hold.amt_paid_msat as u64,
418                        incoming_amount_msat: hold.amt_paid_msat as u64,
419                        expiry: hold_invoice_claim_deadline(&hold.htlcs),
420                        short_channel_id: Some(0),
421                        // The payment is held by a HOLD invoice on our own
422                        // node rather than by an intercepted forward, which is
423                        // how `complete_htlc` knows to resolve it by settling
424                        // or canceling that invoice.
425                        incoming_chan_id,
426                        htlc_id,
427                    };
428
429                    match gateway_sender.send(intercept).await {
430                        Ok(()) => {}
431                        Err(err) => {
432                            warn!(
433                                target: LOG_LIGHTNING,
434                                err = %err.fmt_compact(),
435                                "Hold Invoice Subscription failed to send Intercept to gateway"
436                            );
437                            let _ = self_copy.cancel_hold_invoice(hold.r_hash).await;
438                        }
439                    }
440                }
441            }
442        });
443
444        Ok(())
445    }
446
447    /// Spawns a new background task that subscribes to "add" updates for all
448    /// invoices. This is used to detect when a new invoice has been
449    /// created. If this invoice is a HOLD invoice, it is potentially destined
450    /// for a federation. At this point, we spawn a separate task to monitor the
451    /// status of the HOLD invoice.
452    async fn spawn_lnv2_invoice_subscription(
453        &self,
454        task_group: &TaskGroup,
455        gateway_sender: HtlcSubscriptionSender,
456    ) -> Result<(), LightningRpcError> {
457        let mut client = self.connect().await?;
458
459        let list_response = client
460            .lightning()
461            .list_invoices(ListInvoiceRequest {
462                pending_only: true,
463                index_offset: 0,
464                num_max_invoices: u64::MAX,
465                reversed: false,
466                ..Default::default()
467            })
468            .await
469            .map_err(|status| {
470                warn!(target: LOG_LIGHTNING, status = %status, "Failed to list all invoices");
471                LightningRpcError::FailedToRouteHtlcs {
472                    failure_reason: "Failed to list all invoices".to_string(),
473                }
474            })?
475            .into_inner();
476
477        let self_copy = self.clone();
478        let hold_group = task_group.make_subgroup();
479        // See the matching comment in `spawn_lnv1_htlc_interceptor`: if this
480        // task exits unexpectedly we shut down the payment-stream subgroup so
481        // the gateway transitions to `Disconnected` and reconnects.
482        let subgroup = task_group.clone();
483
484        // The `SubscribeInvoices` backlog cannot replay pre-existing pending
485        // HOLD invoices reliably: an `add_index` of 0 means "no backlog" to
486        // LND, so the oldest pending invoice is skipped whenever it is the
487        // first invoice ever created on the node (`add_index == 1`), and
488        // invoices already in the `Accepted` state are never delivered to
489        // all-invoice subscribers at all. Instead, spawn a monitor task for
490        // every pending HOLD invoice (`r_preimage` empty) from the listing
491        // directly. Invoices not created by this gateway are filtered out by
492        // the monitor task once they reach the `Accepted` state.
493        for invoice in &list_response.invoices {
494            if invoice.r_preimage.is_empty() {
495                info!(
496                    target: LOG_LIGHTNING,
497                    payment_hash = %PrettyPaymentHash(&invoice.r_hash),
498                    "Monitoring pre-existing pending LNv2 invoice",
499                );
500                self.spawn_lnv2_hold_invoice_subscription(
501                    &hold_group,
502                    subgroup.clone(),
503                    gateway_sender.clone(),
504                    invoice.r_hash.clone(),
505                )
506                .await?;
507            }
508        }
509
510        // The listing above covers all pending invoices, so the subscription
511        // only needs to replay invoices added after the listing was taken.
512        // Add indices increase monotonically, so any such invoice has an
513        // `add_index` strictly greater than the listing's `last_index_offset`
514        // (0 when no invoices were listed) and `SubscribeInvoices` replays
515        // exactly those, without duplicating the invoices handled above.
516        let add_index = list_response.last_index_offset;
517        task_group.spawn("LND Invoice Subscription", move |handle| async move {
518            let future_stream = client.lightning().subscribe_invoices(InvoiceSubscription {
519                add_index,
520                settle_index: u64::MAX, // we do not need settle invoice events
521            });
522            let mut invoice_stream = tokio::select! {
523                stream = future_stream => {
524                    match stream {
525                        Ok(stream) => stream.into_inner(),
526                        Err(err) => {
527                            warn!(target: LOG_LIGHTNING, err = %err.fmt_compact(), "Failed to subscribe to all invoice updates");
528                            subgroup.shutdown();
529                            return;
530                        }
531                    }
532                },
533                () = handle.make_shutdown_rx() => {
534                    info!(target: LOG_LIGHTNING, "LND Invoice Subscription received shutdown signal");
535                    return;
536                }
537            };
538
539            info!(target: LOG_LIGHTNING, "LND Invoice Subscription: starting to process invoice updates");
540            while let Some(invoice) = tokio::select! {
541                () = handle.make_shutdown_rx() => {
542                    info!(target: LOG_LIGHTNING, "LND Invoice Subscription task received shutdown signal");
543                    None
544                }
545                invoice_update = invoice_stream.message() => {
546                    match invoice_update {
547                        Ok(invoice) => invoice,
548                        Err(err) => {
549                            warn!(target: LOG_LIGHTNING, err = %err.fmt_compact(), "Error received over invoice update stream");
550                            None
551                        }
552                    }
553                }
554            } {
555                // If the `r_preimage` is empty and the invoice is OPEN, this means a new HOLD
556                // invoice has been created, which is potentially an invoice destined for a
557                // federation. We will spawn a new task to monitor the status of
558                // the HOLD invoice.
559                let payment_hash = invoice.r_hash.clone();
560
561                debug!(
562                    target: LOG_LIGHTNING,
563                    payment_hash = %PrettyPaymentHash(&payment_hash),
564                    state = %invoice.state,
565                    "LND HOLD Invoice Update",
566                );
567
568                if invoice.r_preimage.is_empty() && invoice.state() == InvoiceState::Open {
569                    info!(
570                        target: LOG_LIGHTNING,
571                        payment_hash = %PrettyPaymentHash(&payment_hash),
572                        "Monitoring new LNv2 invoice",
573                    );
574                    if let Err(err) = self_copy
575                        .spawn_lnv2_hold_invoice_subscription(
576                            &hold_group,
577                            subgroup.clone(),
578                            gateway_sender.clone(),
579                            payment_hash.clone(),
580                        )
581                        .await
582                    {
583                        // Spawning failed because `connect()` exhausted its
584                        // retries, a strong signal that LND is unreachable. We
585                        // can no longer observe this invoice's `Accepted`
586                        // update, so shut down the payment-stream subgroup to
587                        // force a gateway reconnect.
588                        warn!(
589                            target: LOG_LIGHTNING,
590                            err = %err.fmt_compact(),
591                            payment_hash = %PrettyPaymentHash(&payment_hash),
592                            "Failed to spawn HOLD invoice subscription task, shutting down payment-stream subgroup to trigger gateway reconnect",
593                        );
594                        subgroup.shutdown();
595                    }
596                }
597            }
598
599            if !handle.is_shutting_down() {
600                warn!(target: LOG_LIGHTNING, "LND Invoice Subscription exited unexpectedly, shutting down payment-stream subgroup to trigger gateway reconnect");
601                subgroup.shutdown();
602            }
603        });
604
605        Ok(())
606    }
607
608    /// Spawns a new background task that intercepts HTLCs from the LND node. In
609    /// the LNv1 protocol, this is used as a trigger mechanism for
610    /// requesting the Gateway to retrieve the preimage for a payment.
611    async fn spawn_lnv1_htlc_interceptor(
612        &self,
613        task_group: &TaskGroup,
614        lnd_sender: mpsc::Sender<ForwardHtlcInterceptResponse>,
615        lnd_rx: mpsc::Receiver<ForwardHtlcInterceptResponse>,
616        gateway_sender: HtlcSubscriptionSender,
617    ) -> Result<(), LightningRpcError> {
618        let mut client = self.connect().await?;
619
620        // Verify that LND is reachable via RPC before attempting to spawn a new thread
621        // that will intercept HTLCs.
622        client
623            .lightning()
624            .get_info(GetInfoRequest {})
625            .await
626            .map_err(|status| LightningRpcError::FailedToGetNodeInfo {
627                failure_reason: format!("Failed to get node info {status:?}"),
628            })?;
629
630        // If the HTLC interceptor exits unexpectedly we shut down the
631        // payment-stream subgroup. That cascades to the lnv2 invoice
632        // subscription (and its hold-invoice subtasks), which drop their
633        // `gateway_sender` clones, closing the gateway's HTLC stream and
634        // driving the gateway back to `Disconnected` so it reconnects.
635        let subgroup = task_group.clone();
636        task_group.spawn("LND HTLC Subscription", |handle| async move {
637                let future_stream = client
638                    .router()
639                    .htlc_interceptor(ReceiverStream::new(lnd_rx));
640                let mut htlc_stream = tokio::select! {
641                    stream = future_stream => {
642                        match stream {
643                            Ok(stream) => stream.into_inner(),
644                            Err(e) => {
645                                crit!(target: LOG_LIGHTNING, err = %e.fmt_compact(), "Failed to establish htlc stream");
646                                subgroup.shutdown();
647                                return;
648                            }
649                        }
650                    },
651                    () = handle.make_shutdown_rx() => {
652                        info!(target: LOG_LIGHTNING, "LND HTLC Subscription received shutdown signal while trying to intercept HTLC stream, exiting...");
653                        return;
654                    }
655                };
656
657                debug!(target: LOG_LIGHTNING, "LND HTLC Subscription: starting to process stream");
658                // To gracefully handle shutdown signals, we need to be able to receive signals
659                // while waiting for the next message from the HTLC stream.
660                //
661                // If we're in the middle of processing a message from the stream, we need to
662                // finish before stopping the spawned task. Checking if the task group is
663                // shutting down at the start of each iteration will cause shutdown signals to
664                // not process until another message arrives from the HTLC stream, which may
665                // take a long time, or never.
666                while let Some(htlc) = tokio::select! {
667                    () = handle.make_shutdown_rx() => {
668                        info!(target: LOG_LIGHTNING, "LND HTLC Subscription task received shutdown signal");
669                        None
670                    }
671                    htlc_message = htlc_stream.message() => {
672                        match htlc_message {
673                            Ok(htlc) => htlc,
674                            Err(err) => {
675                                warn!(target: LOG_LIGHTNING, err = %err.fmt_compact(), "Error received over HTLC stream");
676                                None
677                            }
678                    }}
679                } {
680                    trace!(target: LOG_LIGHTNING, ?htlc, "LND Handling HTLC");
681
682                    let Some(incoming_circuit_key) = htlc.incoming_circuit_key else {
683                        // We have no circuit key, so the HTLC cannot be cancelled
684                        // either; it will time out at LND. Log enough context to
685                        // correlate with the sender's invoice and the target
686                        // federation.
687                        warn!(
688                            target: LOG_LIGHTNING,
689                            payment_hash = %PrettyPaymentHash(&htlc.payment_hash),
690                            scid = htlc.outgoing_requested_chan_id,
691                            amount_msat = htlc.outgoing_amount_msat,
692                            "Cannot route HTLC: incoming_circuit_key is None"
693                        );
694                        continue;
695                    };
696
697                    let chan_id = incoming_circuit_key.chan_id;
698                    let htlc_id = incoming_circuit_key.htlc_id;
699
700                    // Forward all HTLCs to gatewayd, gatewayd will filter them based on scid
701                    let intercept = InterceptPaymentRequest {
702                        payment_hash: Hash::from_slice(&htlc.payment_hash).expect("Failed to convert payment Hash"),
703                        // `outgoing_amount_msat` is the sender-written onion
704                        // `amt_to_forward`; `incoming_amount_msat` is the amount
705                        // actually locked in the incoming HTLC. Carry both so
706                        // downstream funding is decided against the real value.
707                        amount_msat: htlc.outgoing_amount_msat,
708                        incoming_amount_msat: htlc.incoming_amount_msat,
709                        expiry: htlc.incoming_expiry,
710                        short_channel_id: Some(htlc.outgoing_requested_chan_id),
711                        incoming_chan_id: chan_id,
712                        htlc_id,
713                    };
714
715                    match gateway_sender.send(intercept).await {
716                        Ok(()) => {}
717                        Err(err) => {
718                            warn!(
719                                target: LOG_LIGHTNING,
720                                err = %err.fmt_compact(),
721                                payment_hash = %PrettyPaymentHash(&htlc.payment_hash),
722                                scid = htlc.outgoing_requested_chan_id,
723                                amount_msat = htlc.outgoing_amount_msat,
724                                "Failed to send HTLC to gatewayd for processing"
725                            );
726                            let _ = Self::cancel_htlc(incoming_circuit_key, lnd_sender.clone())
727                                .await
728                                .map_err(|err| {
729                                    warn!(
730                                        target: LOG_LIGHTNING,
731                                        err = %err.fmt_compact(),
732                                        payment_hash = %PrettyPaymentHash(&htlc.payment_hash),
733                                        chan_id,
734                                        htlc_id,
735                                        "Failed to cancel HTLC"
736                                    );
737                                });
738                        }
739                    }
740                }
741
742                // Loop exited because of an HTLC stream error or end-of-stream
743                // (the expected-shutdown case is handled above).
744                if !handle.is_shutting_down() {
745                    warn!(target: LOG_LIGHTNING, "LND HTLC Subscription exited unexpectedly, shutting down payment-stream subgroup to trigger gateway reconnect");
746                    subgroup.shutdown();
747                }
748            });
749
750        Ok(())
751    }
752
753    /// Spawns background tasks for monitoring the status of incoming payments.
754    async fn spawn_interceptor(
755        &self,
756        task_group: &TaskGroup,
757        lnd_sender: mpsc::Sender<ForwardHtlcInterceptResponse>,
758        lnd_rx: mpsc::Receiver<ForwardHtlcInterceptResponse>,
759        gateway_sender: HtlcSubscriptionSender,
760    ) -> Result<(), LightningRpcError> {
761        self.spawn_lnv1_htlc_interceptor(task_group, lnd_sender, lnd_rx, gateway_sender.clone())
762            .await?;
763
764        self.spawn_lnv2_invoice_subscription(task_group, gateway_sender)
765            .await?;
766
767        Ok(())
768    }
769
770    async fn cancel_htlc(
771        key: CircuitKey,
772        lnd_sender: mpsc::Sender<ForwardHtlcInterceptResponse>,
773    ) -> Result<(), LightningRpcError> {
774        // TODO: Specify a failure code and message
775        let response = ForwardHtlcInterceptResponse {
776            incoming_circuit_key: Some(key),
777            action: ResolveHoldForwardAction::Fail.into(),
778            preimage: vec![],
779            failure_message: vec![],
780            failure_code: FailureCode::TemporaryChannelFailure.into(),
781            ..Default::default()
782        };
783        Self::send_lnd_response(lnd_sender, response).await
784    }
785
786    async fn send_lnd_response(
787        lnd_sender: mpsc::Sender<ForwardHtlcInterceptResponse>,
788        response: ForwardHtlcInterceptResponse,
789    ) -> Result<(), LightningRpcError> {
790        // TODO: Consider retrying this if the send fails
791        lnd_sender.send(response).await.map_err(|send_error| {
792            LightningRpcError::FailedToCompleteHtlc {
793                failure_reason: format!(
794                    "Failed to send ForwardHtlcInterceptResponse to LND {send_error:?}"
795                ),
796            }
797        })
798    }
799
800    async fn lookup_payment(
801        &self,
802        payment_hash: Vec<u8>,
803        client: &mut LndClient,
804    ) -> Result<Option<String>, LightningRpcError> {
805        // Loop until we successfully get the status of the payment, or determine that
806        // the payment has not been made yet.
807        loop {
808            let payments = client
809                .router()
810                .track_payment_v2(TrackPaymentRequest {
811                    payment_hash: payment_hash.clone(),
812                    no_inflight_updates: true,
813                })
814                .await;
815
816            match payments {
817                Ok(payments) => {
818                    let mut updates = payments.into_inner();
819
820                    // Block until LND reports a terminal status. `no_inflight_updates`
821                    // asks LND to hold back everything else, but a payment still in
822                    // flight must never be read as failed, so only `Failed` counts as
823                    // a failure here: `InFlight`, `Initiated` (with
824                    // `routerrpc.usestatusinitiated`) and any status this build does
825                    // not know, which prost decodes as `Unknown`, keep us waiting.
826                    let outcome = loop {
827                        match updates.message().await {
828                            Ok(Some(payment)) if payment.status() == PaymentStatus::Succeeded => {
829                                return Ok(Some(payment.payment_preimage));
830                            }
831                            Ok(Some(payment)) if payment.status() == PaymentStatus::Failed => {
832                                let failure_reason = payment.failure_reason();
833                                return Err(LightningRpcError::FailedPayment {
834                                    failure_reason: format!("{failure_reason:?}"),
835                                });
836                            }
837                            Ok(Some(payment)) => {
838                                debug!(
839                                    target: LOG_LIGHTNING,
840                                    payment_hash = %PrettyPaymentHash(&payment_hash),
841                                    status = ?payment.status(),
842                                    "Tracked payment is not terminal yet, waiting",
843                                );
844                            }
845                            outcome => break outcome,
846                        }
847                    };
848
849                    // A premature end of stream (`Ok(None)`) or a transport fault
850                    // (`Err`) is not a payment outcome. Retry rather than reporting a
851                    // failure the node never produced.
852                    warn!(
853                        target: LOG_LIGHTNING,
854                        payment_hash = %PrettyPaymentHash(&payment_hash),
855                        outcome = ?outcome,
856                        "Payment tracking stream ended or faulted. Trying again in 5 seconds"
857                    );
858                    sleep(Duration::from_secs(5)).await;
859                }
860                Err(err) => {
861                    // Break if we got a response back from the LND node that indicates the payment
862                    // hash was not found.
863                    if err.code() == Code::NotFound {
864                        return Ok(None);
865                    }
866
867                    warn!(
868                        target: LOG_LIGHTNING,
869                        payment_hash = %PrettyPaymentHash(&payment_hash),
870                        err = %err.fmt_compact(),
871                        "Could not get the status of payment. Trying again in 5 seconds"
872                    );
873                    sleep(Duration::from_secs(5)).await;
874                }
875            }
876        }
877    }
878
879    /// Looks up the invoice carrying `payment_hash`, returning `None` if the
880    /// node has no such invoice.
881    ///
882    /// Any other lookup failure is reported as an error, since callers retry on
883    /// error and an unreachable node is a condition a retry can clear.
884    async fn lookup_invoice(
885        client: &mut LndClient,
886        payment_hash: &[u8],
887    ) -> Result<Option<Invoice>, LightningRpcError> {
888        match client
889            .invoices()
890            .lookup_invoice_v2(LookupInvoiceMsg {
891                invoice_ref: Some(InvoiceRef::PaymentHash(payment_hash.to_vec())),
892                lookup_modifier: 0,
893            })
894            .await
895        {
896            Ok(invoice) => Ok(Some(invoice.into_inner())),
897            Err(err) if err.code() == Code::NotFound => Ok(None),
898            Err(err) => Err(LightningRpcError::FailedToCompleteHtlc {
899                failure_reason: format!("Failed to look up invoice: {}", err.fmt_compact()),
900            }),
901        }
902    }
903
904    /// Settles the LNv2 HOLD invoice carrying `payment_hash` with `preimage`.
905    ///
906    /// Only an already-settled invoice is an idempotent success. Missing,
907    /// nonterminal, and canceled invoices fail so callers cannot record a
908    /// settle outcome that Lightning did not produce.
909    async fn settle_hold_invoice(
910        &self,
911        payment_hash: Vec<u8>,
912        preimage: Preimage,
913    ) -> Result<(), LightningRpcError> {
914        let mut client = self.connect().await?;
915        let invoice = Self::lookup_invoice(&mut client, &payment_hash).await?;
916        match hold_invoice_action(
917            PaymentActionKind::Settle,
918            invoice.as_ref().map(Invoice::state),
919        ) {
920            Ok(HoldInvoiceAction::Complete) => {}
921            Ok(HoldInvoiceAction::AlreadyComplete) => {
922                info!(
923                    target: LOG_LIGHTNING,
924                    payment_hash = %PrettyPaymentHash(&payment_hash),
925                    "HOLD invoice was already settled",
926                );
927                return Ok(());
928            }
929            Err(error) => {
930                warn!(
931                    target: LOG_LIGHTNING,
932                    state = ?invoice.as_ref().map(Invoice::state),
933                    payment_hash = %PrettyPaymentHash(&payment_hash),
934                    failure_reason = error.failure_reason,
935                    "Cannot settle HOLD invoice",
936                );
937                return Err(if error.permanent {
938                    LightningRpcError::HtlcCompletionRejected {
939                        failure_reason: error.failure_reason.to_owned(),
940                    }
941                } else {
942                    LightningRpcError::FailedToCompleteHtlc {
943                        failure_reason: error.failure_reason.to_owned(),
944                    }
945                });
946            }
947        }
948
949        client
950            .invoices()
951            .settle_invoice(SettleInvoiceMsg {
952                preimage: preimage.0.to_vec(),
953            })
954            .await
955            .map_err(|err| {
956                warn!(
957                    target: LOG_LIGHTNING,
958                    err = %err.fmt_compact(),
959                    payment_hash = %PrettyPaymentHash(&payment_hash),
960                    "Failed to settle HOLD invoice",
961                );
962                LightningRpcError::FailedToCompleteHtlc {
963                    failure_reason: "Failed to settle HOLD invoice".to_string(),
964                }
965            })?;
966
967        info!(
968            target: LOG_LIGHTNING,
969            payment_hash = %PrettyPaymentHash(&payment_hash),
970            "Successfully settled HOLD invoice",
971        );
972
973        Ok(())
974    }
975
976    /// Cancels the LNv2 HOLD invoice carrying `payment_hash`, failing back any
977    /// HTLC it holds.
978    ///
979    /// Only an already-canceled invoice is an idempotent success. A settled
980    /// invoice fails so callers cannot record a cancel outcome after a racing
981    /// settle won.
982    async fn cancel_hold_invoice(&self, payment_hash: Vec<u8>) -> Result<(), LightningRpcError> {
983        let mut client = self.connect().await?;
984        let invoice = Self::lookup_invoice(&mut client, &payment_hash).await?;
985        match hold_invoice_action(
986            PaymentActionKind::Cancel,
987            invoice.as_ref().map(Invoice::state),
988        ) {
989            Ok(HoldInvoiceAction::Complete) => {}
990            Ok(HoldInvoiceAction::AlreadyComplete) => {
991                info!(
992                    target: LOG_LIGHTNING,
993                    payment_hash = %PrettyPaymentHash(&payment_hash),
994                    "HOLD invoice was already canceled",
995                );
996                return Ok(());
997            }
998            Err(error) => {
999                warn!(
1000                    target: LOG_LIGHTNING,
1001                    state = ?invoice.as_ref().map(Invoice::state),
1002                    payment_hash = %PrettyPaymentHash(&payment_hash),
1003                    failure_reason = error.failure_reason,
1004                    "Cannot cancel HOLD invoice",
1005                );
1006                return Err(LightningRpcError::HtlcCompletionRejected {
1007                    failure_reason: error.failure_reason.to_owned(),
1008                });
1009            }
1010        }
1011
1012        client
1013            .invoices()
1014            .cancel_invoice(CancelInvoiceMsg {
1015                payment_hash: payment_hash.clone(),
1016            })
1017            .await
1018            .map_err(|err| {
1019                warn!(
1020                    target: LOG_LIGHTNING,
1021                    err = %err.fmt_compact(),
1022                    payment_hash = %PrettyPaymentHash(&payment_hash),
1023                    "Failed to cancel HOLD invoice",
1024                );
1025                LightningRpcError::FailedToCompleteHtlc {
1026                    failure_reason: "Failed to cancel HOLD invoice".to_string(),
1027                }
1028            })?;
1029
1030        info!(
1031            target: LOG_LIGHTNING,
1032            payment_hash = %PrettyPaymentHash(&payment_hash),
1033            "Successfully canceled HOLD invoice",
1034        );
1035
1036        Ok(())
1037    }
1038}
1039
1040impl fmt::Debug for GatewayLndClient {
1041    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1042        write!(f, "LndClient")
1043    }
1044}
1045
1046#[async_trait]
1047impl ILnRpcClient for GatewayLndClient {
1048    async fn info(&self) -> Result<GetNodeInfoResponse, LightningRpcError> {
1049        let mut client = self.connect().await?;
1050        let info = client
1051            .lightning()
1052            .get_info(GetInfoRequest {})
1053            .await
1054            .map_err(|status| LightningRpcError::FailedToGetNodeInfo {
1055                failure_reason: format!("Failed to get node info {status:?}"),
1056            })?
1057            .into_inner();
1058
1059        let pub_key: PublicKey =
1060            info.identity_pubkey
1061                .parse()
1062                .map_err(|e| LightningRpcError::FailedToGetNodeInfo {
1063                    failure_reason: format!("Failed to parse public key {e:?}"),
1064                })?;
1065
1066        let network = match info
1067            .chains
1068            .first()
1069            .ok_or_else(|| LightningRpcError::FailedToGetNodeInfo {
1070                failure_reason: "Failed to parse node network".to_string(),
1071            })?
1072            .network
1073            .as_str()
1074        {
1075            // LND uses "mainnet", but rust-bitcoin uses "bitcoin".
1076            // TODO: create a fedimint `Network` type that understands "mainnet"
1077            "mainnet" => "bitcoin",
1078            other => other,
1079        }
1080        .to_string();
1081
1082        return Ok(GetNodeInfoResponse {
1083            pub_key,
1084            alias: info.alias,
1085            network,
1086            block_height: info.block_height,
1087            synced_to_chain: info.synced_to_chain,
1088        });
1089    }
1090
1091    async fn routehints(
1092        &self,
1093        num_route_hints: usize,
1094    ) -> Result<GetRouteHintsResponse, LightningRpcError> {
1095        let mut client = self.connect().await?;
1096        let mut channels = client
1097            .lightning()
1098            .list_channels(ListChannelsRequest {
1099                active_only: true,
1100                inactive_only: false,
1101                public_only: false,
1102                private_only: false,
1103                peer: vec![],
1104                peer_alias_lookup: false,
1105            })
1106            .await
1107            .map_err(|status| LightningRpcError::FailedToGetRouteHints {
1108                failure_reason: format!("Failed to list channels {status:?}"),
1109            })?
1110            .into_inner()
1111            .channels;
1112
1113        // Take the channels with the largest incoming capacity
1114        channels.sort_by_key(|b| std::cmp::Reverse(b.remote_balance));
1115        channels.truncate(num_route_hints);
1116
1117        let mut route_hints: Vec<RouteHint> = vec![];
1118        for chan in &channels {
1119            let info = client
1120                .lightning()
1121                .get_chan_info(ChanInfoRequest {
1122                    chan_id: chan.chan_id,
1123                    ..Default::default()
1124                })
1125                .await
1126                .map_err(|status| LightningRpcError::FailedToGetRouteHints {
1127                    failure_reason: format!("Failed to get channel info {status:?}"),
1128                })?
1129                .into_inner();
1130
1131            // The route hint hop describes the remote peer forwarding a payment
1132            // *into* the gateway, so it must carry that peer's advertised channel
1133            // policy. `node1`/`node2` are ordered by pubkey (BOLT 7), not by which
1134            // side is the gateway, so select the policy belonging to the remote
1135            // peer rather than always taking node1's.
1136            let policy = if info.node1_pub == chan.remote_pubkey {
1137                info.node1_policy
1138            } else {
1139                info.node2_policy
1140            };
1141            let Some(policy) = policy else {
1142                continue;
1143            };
1144            let src_node_id =
1145                PublicKey::from_str(&chan.remote_pubkey).expect("Failed to parse pubkey");
1146            let short_channel_id = chan.chan_id;
1147            let base_msat = policy.fee_base_msat as u32;
1148            let proportional_millionths = policy.fee_rate_milli_msat as u32;
1149            let cltv_expiry_delta = policy.time_lock_delta;
1150            let htlc_maximum_msat = Some(policy.max_htlc_msat);
1151            let htlc_minimum_msat = Some(policy.min_htlc as u64);
1152
1153            let route_hint_hop = RouteHintHop {
1154                src_node_id,
1155                short_channel_id,
1156                base_msat,
1157                proportional_millionths,
1158                cltv_expiry_delta: cltv_expiry_delta as u16,
1159                htlc_minimum_msat,
1160                htlc_maximum_msat,
1161            };
1162            route_hints.push(RouteHint(vec![route_hint_hop]));
1163        }
1164
1165        Ok(GetRouteHintsResponse { route_hints })
1166    }
1167
1168    async fn pay_private(
1169        &self,
1170        invoice: PrunedInvoice,
1171        max_delay: u64,
1172        max_fee: Amount,
1173    ) -> Result<PayInvoiceResponse, LightningRpcError> {
1174        let payment_hash = invoice.payment_hash.to_byte_array().to_vec();
1175        info!(
1176            target: LOG_LIGHTNING,
1177            payment_hash = %PrettyPaymentHash(&payment_hash),
1178            "LND Paying invoice",
1179        );
1180        let mut client = self.connect().await?;
1181
1182        debug!(
1183            target: LOG_LIGHTNING,
1184            payment_hash = %PrettyPaymentHash(&payment_hash),
1185            "pay_private checking if payment for invoice exists"
1186        );
1187
1188        // If the payment exists, that means we've already tried to pay the invoice
1189        let preimage: Vec<u8> = match self
1190            .lookup_payment(invoice.payment_hash.to_byte_array().to_vec(), &mut client)
1191            .await?
1192        {
1193            Some(preimage) => {
1194                info!(
1195                    target: LOG_LIGHTNING,
1196                    payment_hash = %PrettyPaymentHash(&payment_hash),
1197                    "LND payment already exists for invoice",
1198                );
1199                hex::FromHex::from_hex(preimage.as_str()).map_err(|error| {
1200                    LightningRpcError::FailedPayment {
1201                        failure_reason: format!("Failed to convert preimage {error:?}"),
1202                    }
1203                })?
1204            }
1205            _ => 'dispatch: {
1206                // LND API allows fee limits in the `i64` range, but we use `u64` for
1207                // max_fee_msat. This means we can only set an enforceable fee limit
1208                // between 0 and i64::MAX
1209                let fee_limit_msat: i64 =
1210                    max_fee
1211                        .msats
1212                        .try_into()
1213                        .map_err(|error| LightningRpcError::FailedPayment {
1214                            failure_reason: format!(
1215                                "max_fee_msat exceeds valid LND fee limit ranges {error:?}"
1216                            ),
1217                        })?;
1218
1219                let amt_msat = invoice.amount.msats.try_into().map_err(|error| {
1220                    LightningRpcError::FailedPayment {
1221                        failure_reason: format!("amount exceeds valid LND amount ranges {error:?}"),
1222                    }
1223                })?;
1224                let final_cltv_delta =
1225                    invoice.min_final_cltv_delta.try_into().map_err(|error| {
1226                        LightningRpcError::FailedPayment {
1227                            failure_reason: format!(
1228                                "final cltv delta exceeds valid LND range {error:?}"
1229                            ),
1230                        }
1231                    })?;
1232                // LND reads a `cltv_limit` of zero as "no limit set" and
1233                // enforces its `--max-cltv-expiry` default instead, silently
1234                // lifting the caller's timelock cap.
1235                if max_delay == 0 {
1236                    return Err(LightningRpcError::FailedPayment {
1237                        failure_reason: "a max delay of zero would disable LND's CLTV limit"
1238                            .to_string(),
1239                    });
1240                }
1241                let cltv_limit =
1242                    max_delay
1243                        .try_into()
1244                        .map_err(|error| LightningRpcError::FailedPayment {
1245                            failure_reason: format!("max delay exceeds valid LND range {error:?}"),
1246                        })?;
1247
1248                let dest_features = wire_features_to_lnd_feature_vec(&invoice.destination_features)
1249                    .map_err(|e| LightningRpcError::FailedPayment {
1250                        failure_reason: e.to_string(),
1251                    })?;
1252
1253                debug!(
1254                    target: LOG_LIGHTNING,
1255                    payment_hash = %PrettyPaymentHash(&payment_hash),
1256                    "LND payment does not exist, will attempt to pay",
1257                );
1258                let payments = match client
1259                    .router()
1260                    .send_payment_v2(SendPaymentRequest {
1261                        amt_msat,
1262                        dest: invoice.destination.serialize().to_vec(),
1263                        dest_features,
1264                        payment_hash: invoice.payment_hash.to_byte_array().to_vec(),
1265                        payment_addr: invoice.payment_secret.to_vec(),
1266                        route_hints: route_hints_to_lnd(&invoice.route_hints),
1267                        final_cltv_delta,
1268                        cltv_limit,
1269                        no_inflight_updates: false,
1270                        timeout_seconds: self.payment_timeout_secs,
1271                        fee_limit_msat,
1272                        time_pref: self.time_pref,
1273                        ..Default::default()
1274                    })
1275                    .await
1276                {
1277                    Ok(payments) => payments,
1278                    // An error here is not proof that nothing was paid. LND
1279                    // registers the payment before its first status update,
1280                    // so a transport fault on the way back can surface as an
1281                    // error for a payment that is now in flight. Reporting
1282                    // failure would forfeit the outgoing contract while the
1283                    // payment may still settle, so only the node's own record
1284                    // decides.
1285                    Err(status) => {
1286                        warn!(
1287                            target: LOG_LIGHTNING,
1288                            status = %status,
1289                            payment_hash = %PrettyPaymentHash(&payment_hash),
1290                            "LND payment request failed, checking whether LND registered the payment",
1291                        );
1292
1293                        let Some(preimage) = self
1294                            .lookup_payment(payment_hash.clone(), &mut client)
1295                            .await?
1296                        else {
1297                            return Err(LightningRpcError::FailedPayment {
1298                                failure_reason: format!(
1299                                    "Failed to make outgoing payment {status:?}"
1300                                ),
1301                            });
1302                        };
1303
1304                        break 'dispatch hex::FromHex::from_hex(preimage.as_str()).map_err(
1305                            |error| LightningRpcError::FailedPayment {
1306                                failure_reason: format!("Failed to convert preimage {error:?}"),
1307                            },
1308                        )?;
1309                    }
1310                };
1311
1312                debug!(
1313                    target: LOG_LIGHTNING,
1314                    payment_hash = %PrettyPaymentHash(&payment_hash),
1315                    "LND payment request sent, waiting for payment status...",
1316                );
1317                let mut messages = payments.into_inner();
1318                loop {
1319                    match messages.message().await {
1320                        Ok(Some(payment)) if payment.status() == PaymentStatus::Succeeded => {
1321                            info!(
1322                                target: LOG_LIGHTNING,
1323                                payment_hash = %PrettyPaymentHash(&payment_hash),
1324                                "LND payment succeeded for invoice",
1325                            );
1326                            break hex::FromHex::from_hex(payment.payment_preimage.as_str())
1327                                .map_err(|error| LightningRpcError::FailedPayment {
1328                                    failure_reason: format!("Failed to convert preimage {error:?}"),
1329                                })?;
1330                        }
1331                        Ok(Some(payment)) if payment.status() == PaymentStatus::Failed => {
1332                            // The one terminal status besides `Succeeded`: a
1333                            // definitive failure that is safe to report.
1334                            warn!(
1335                                target: LOG_LIGHTNING,
1336                                payment_hash = %PrettyPaymentHash(&payment_hash),
1337                                status = ?payment.status(),
1338                                "LND payment failed",
1339                            );
1340                            let failure_reason = payment.failure_reason();
1341                            return Err(LightningRpcError::FailedPayment {
1342                                failure_reason: format!("{failure_reason:?}"),
1343                            });
1344                        }
1345                        // `InFlight`, `Initiated` (delivered before the first HTLC
1346                        // when `routerrpc.usestatusinitiated` is set) and any status
1347                        // this build does not know, which prost decodes as `Unknown`,
1348                        // are not outcomes. Keep waiting; a stream that ends without
1349                        // a terminal status resumes through `lookup_payment` below.
1350                        Ok(Some(payment)) => {
1351                            debug!(
1352                                target: LOG_LIGHTNING,
1353                                payment_hash = %PrettyPaymentHash(&payment_hash),
1354                                status = ?payment.status(),
1355                                "LND payment is in flight",
1356                            );
1357                            continue;
1358                        }
1359                        // `Ok(None)` is a premature end of the update stream and `Err`
1360                        // is a tonic/HTTP2 transport fault. Neither is a payment
1361                        // outcome: the HTLC may still settle, so reporting failure here
1362                        // would forfeit the outgoing contract for a payment that is
1363                        // still in flight, violating the idempotency contract on
1364                        // `ILnRpcClient::pay`. Resume tracking with `track_payment_v2`
1365                        // to await the real terminal result instead.
1366                        stream_end_or_fault => {
1367                            warn!(
1368                                target: LOG_LIGHTNING,
1369                                payment_hash = %PrettyPaymentHash(&payment_hash),
1370                                outcome = ?stream_end_or_fault,
1371                                "LND payment status stream ended or faulted before a terminal status; resuming tracking",
1372                            );
1373                            match self
1374                                .lookup_payment(payment_hash.clone(), &mut client)
1375                                .await?
1376                            {
1377                                Some(preimage) => {
1378                                    break hex::FromHex::from_hex(preimage.as_str()).map_err(
1379                                        |error| LightningRpcError::FailedPayment {
1380                                            failure_reason: format!(
1381                                                "Failed to convert preimage {error:?}"
1382                                            ),
1383                                        },
1384                                    )?;
1385                                }
1386                                None => {
1387                                    return Err(LightningRpcError::FailedPayment {
1388                                        failure_reason: format!(
1389                                            "LND has no record of dispatched payment for hash {:?}",
1390                                            invoice.payment_hash
1391                                        ),
1392                                    });
1393                                }
1394                            }
1395                        }
1396                    }
1397                }
1398            }
1399        };
1400        Ok(PayInvoiceResponse {
1401            preimage: Preimage(preimage.try_into().expect("Failed to create preimage")),
1402        })
1403    }
1404
1405    /// Returns true if the lightning backend supports payments without full
1406    /// invoices
1407    fn supports_private_payments(&self) -> bool {
1408        true
1409    }
1410
1411    async fn outbound_payment_exists(
1412        &self,
1413        payment_hash: sha256::Hash,
1414    ) -> Result<bool, LightningRpcError> {
1415        let payment_hash_bytes = payment_hash.to_byte_array().to_vec();
1416        let mut client = self.connect().await?;
1417
1418        // Subscribe with in-flight updates enabled so any known payment,
1419        // pending or terminal, yields an immediate first message instead of
1420        // blocking until the payment resolves; an unknown hash fails with
1421        // `NotFound`.
1422        let stream = match client
1423            .router()
1424            .track_payment_v2(TrackPaymentRequest {
1425                payment_hash: payment_hash_bytes.clone(),
1426                no_inflight_updates: false,
1427            })
1428            .await
1429        {
1430            Ok(stream) => stream,
1431            Err(status) if status.code() == Code::NotFound => return Ok(false),
1432            Err(status) => {
1433                return Err(LightningRpcError::FailedPayment {
1434                    failure_reason: format!(
1435                        "Failed to look up payment {}: {status:?}",
1436                        PrettyPaymentHash(&payment_hash_bytes),
1437                    ),
1438                });
1439            }
1440        };
1441
1442        match stream.into_inner().message().await {
1443            Ok(Some(_)) => Ok(true),
1444            Err(status) if status.code() == Code::NotFound => Ok(false),
1445            // A premature end of stream or a transport fault is not an
1446            // answer. Report an error so the caller retries, rather than
1447            // letting it mistake the payment for never having been
1448            // dispatched.
1449            outcome => Err(LightningRpcError::FailedPayment {
1450                failure_reason: format!(
1451                    "Payment lookup stream gave no answer for {}: {outcome:?}",
1452                    PrettyPaymentHash(&payment_hash_bytes),
1453                ),
1454            }),
1455        }
1456    }
1457
1458    async fn route_htlcs<'a>(
1459        self: Box<Self>,
1460        task_group: &TaskGroup,
1461    ) -> Result<(RouteHtlcStream<'a>, Arc<dyn ILnRpcClient>), LightningRpcError> {
1462        const CHANNEL_SIZE: usize = 100;
1463
1464        // Channel to send intercepted htlc to the gateway for processing
1465        let (gateway_sender, gateway_receiver) =
1466            mpsc::channel::<InterceptPaymentRequest>(CHANNEL_SIZE);
1467
1468        let (lnd_sender, lnd_rx) = mpsc::channel::<ForwardHtlcInterceptResponse>(CHANNEL_SIZE);
1469
1470        self.spawn_interceptor(
1471            task_group,
1472            lnd_sender.clone(),
1473            lnd_rx,
1474            gateway_sender.clone(),
1475        )
1476        .await?;
1477        let new_client = Arc::new(Self {
1478            address: self.address.clone(),
1479            tls_cert: self.tls_cert.clone(),
1480            macaroon: self.macaroon.clone(),
1481            time_pref: self.time_pref,
1482            payment_timeout_secs: self.payment_timeout_secs,
1483            lnd_sender: Some(lnd_sender.clone()),
1484            lnv2_filter: self.lnv2_filter.clone(),
1485        });
1486        Ok((Box::pin(ReceiverStream::new(gateway_receiver)), new_client))
1487    }
1488
1489    async fn complete_htlc(&self, htlc: InterceptPaymentResponse) -> Result<(), LightningRpcError> {
1490        let incoming_circuit = htlc.incoming_circuit();
1491        let InterceptPaymentResponse {
1492            action,
1493            payment_hash,
1494            incoming_chan_id: _,
1495            htlc_id: _,
1496        } = htlc;
1497
1498        let (action, preimage) = match action {
1499            PaymentAction::Settle(preimage) => (ResolveHoldForwardAction::Settle, preimage),
1500            PaymentAction::Cancel => (ResolveHoldForwardAction::Fail, Preimage([0; 32])),
1501            PaymentAction::Forward => (ResolveHoldForwardAction::Resume, Preimage([0; 32])),
1502        };
1503
1504        // Resolve the payment the way it arrived. Deciding instead by probing
1505        // LND for a HOLD invoice carrying the payment hash would conflate the
1506        // two ways, because the hash is chosen by whoever is being paid: an
1507        // attacker can register an LNv2 receive and an LNv1 offer for the same
1508        // hash, and the completion for the intercepted LNv1 HTLC would then
1509        // settle or cancel the unrelated LNv2 HOLD invoice.
1510        let Some((chan_id, htlc_id)) = incoming_circuit else {
1511            // LNv2: the payment is held by a HOLD invoice on our own node, so
1512            // there is no forward to resolve.
1513            return match action {
1514                ResolveHoldForwardAction::Settle => {
1515                    self.settle_hold_invoice(payment_hash.to_byte_array().to_vec(), preimage)
1516                        .await
1517                }
1518                // Neither `Fail` nor `Resume` has a meaning for a HOLD invoice
1519                // beyond "the gateway could not claim this payment": there is
1520                // no next hop to resume towards, so fail it back to the payer.
1521                _ => {
1522                    self.cancel_hold_invoice(payment_hash.to_byte_array().to_vec())
1523                        .await
1524                }
1525            };
1526        };
1527
1528        // LNv1: hand the interceptor its response for this exact circuit.
1529        let Some(lnd_sender) = self.lnd_sender.clone() else {
1530            crit!("Gatewayd has not started to route HTLCs");
1531            return Err(LightningRpcError::FailedToCompleteHtlc {
1532                failure_reason: "Gatewayd has not started to route HTLCs".to_string(),
1533            });
1534        };
1535
1536        let response = ForwardHtlcInterceptResponse {
1537            incoming_circuit_key: Some(CircuitKey { chan_id, htlc_id }),
1538            action: action.into(),
1539            preimage: preimage.0.to_vec(),
1540            failure_message: vec![],
1541            failure_code: FailureCode::TemporaryChannelFailure.into(),
1542            ..Default::default()
1543        };
1544
1545        Self::send_lnd_response(lnd_sender, response).await
1546    }
1547
1548    async fn create_invoice(
1549        &self,
1550        create_invoice_request: CreateInvoiceRequest,
1551    ) -> Result<CreateInvoiceResponse, LightningRpcError> {
1552        let mut client = self.connect().await?;
1553        let description = create_invoice_request
1554            .description
1555            .unwrap_or(InvoiceDescription::Direct(String::new()));
1556
1557        if let Some(payment_hash_value) = create_invoice_request.payment_hash {
1558            let payment_hash = payment_hash_value.to_byte_array().to_vec();
1559            let hold_invoice_request = match description {
1560                InvoiceDescription::Direct(description) => AddHoldInvoiceRequest {
1561                    memo: description,
1562                    hash: payment_hash.clone(),
1563                    value_msat: create_invoice_request.amount_msat as i64,
1564                    expiry: i64::from(create_invoice_request.expiry_secs),
1565                    cltv_expiry: LNV2_HOLD_INVOICE_CLTV_EXPIRY,
1566                    ..Default::default()
1567                },
1568                InvoiceDescription::Hash(desc_hash) => AddHoldInvoiceRequest {
1569                    description_hash: desc_hash.to_byte_array().to_vec(),
1570                    hash: payment_hash.clone(),
1571                    value_msat: create_invoice_request.amount_msat as i64,
1572                    expiry: i64::from(create_invoice_request.expiry_secs),
1573                    cltv_expiry: LNV2_HOLD_INVOICE_CLTV_EXPIRY,
1574                    ..Default::default()
1575                },
1576            };
1577
1578            let hold_invoice_response = client
1579                .invoices()
1580                .add_hold_invoice(hold_invoice_request)
1581                .await
1582                .map_err(|e| LightningRpcError::FailedToGetInvoice {
1583                    failure_reason: e.to_string(),
1584                })?;
1585
1586            let invoice = hold_invoice_response.into_inner().payment_request;
1587            Ok(CreateInvoiceResponse { invoice })
1588        } else {
1589            let invoice = match description {
1590                InvoiceDescription::Direct(description) => Invoice {
1591                    memo: description,
1592                    value_msat: create_invoice_request.amount_msat as i64,
1593                    expiry: i64::from(create_invoice_request.expiry_secs),
1594                    ..Default::default()
1595                },
1596                InvoiceDescription::Hash(desc_hash) => Invoice {
1597                    description_hash: desc_hash.to_byte_array().to_vec(),
1598                    value_msat: create_invoice_request.amount_msat as i64,
1599                    expiry: i64::from(create_invoice_request.expiry_secs),
1600                    ..Default::default()
1601                },
1602            };
1603
1604            let add_invoice_response =
1605                client.lightning().add_invoice(invoice).await.map_err(|e| {
1606                    LightningRpcError::FailedToGetInvoice {
1607                        failure_reason: e.to_string(),
1608                    }
1609                })?;
1610
1611            let invoice = add_invoice_response.into_inner().payment_request;
1612            Ok(CreateInvoiceResponse { invoice })
1613        }
1614    }
1615
1616    async fn get_ln_onchain_address(
1617        &self,
1618    ) -> Result<GetLnOnchainAddressResponse, LightningRpcError> {
1619        let mut client = self.connect().await?;
1620
1621        match client
1622            .wallet()
1623            .next_addr(AddrRequest {
1624                account: String::new(), // Default wallet account.
1625                r#type: 4,              // Taproot address.
1626                change: false,
1627            })
1628            .await
1629        {
1630            Ok(response) => Ok(GetLnOnchainAddressResponse {
1631                address: response.into_inner().addr,
1632            }),
1633            Err(e) => Err(LightningRpcError::FailedToGetLnOnchainAddress {
1634                failure_reason: format!("Failed to get funding address {e:?}"),
1635            }),
1636        }
1637    }
1638
1639    async fn send_onchain(
1640        &self,
1641        SendOnchainRequest {
1642            address,
1643            amount,
1644            fee_rate_sats_per_vbyte,
1645        }: SendOnchainRequest,
1646    ) -> Result<SendOnchainResponse, LightningRpcError> {
1647        #[allow(deprecated)]
1648        let request = match amount {
1649            BitcoinAmountOrAll::All => SendCoinsRequest {
1650                addr: address.assume_checked().to_string(),
1651                amount: 0,
1652                target_conf: 0,
1653                sat_per_vbyte: fee_rate_sats_per_vbyte,
1654                sat_per_byte: 0,
1655                send_all: true,
1656                label: String::new(),
1657                min_confs: 0,
1658                spend_unconfirmed: true,
1659                ..Default::default()
1660            },
1661            BitcoinAmountOrAll::Amount(amount) => SendCoinsRequest {
1662                addr: address.assume_checked().to_string(),
1663                amount: amount.to_sat() as i64,
1664                target_conf: 0,
1665                sat_per_vbyte: fee_rate_sats_per_vbyte,
1666                sat_per_byte: 0,
1667                send_all: false,
1668                label: String::new(),
1669                min_confs: 0,
1670                spend_unconfirmed: true,
1671                ..Default::default()
1672            },
1673        };
1674
1675        match self.connect().await?.lightning().send_coins(request).await {
1676            Ok(res) => Ok(SendOnchainResponse {
1677                txid: res.into_inner().txid,
1678            }),
1679            Err(e) => Err(LightningRpcError::FailedToWithdrawOnchain {
1680                failure_reason: format!("Failed to withdraw funds on-chain {e:?}"),
1681            }),
1682        }
1683    }
1684
1685    async fn open_channel(
1686        &self,
1687        crate::OpenChannelRequest {
1688            pubkey,
1689            host,
1690            channel_size_sats,
1691            push_amount_sats,
1692            fee_rate_sats_per_vbyte,
1693            base_fee_msat,
1694            parts_per_million,
1695        }: crate::OpenChannelRequest,
1696    ) -> Result<OpenChannelResponse, LightningRpcError> {
1697        let (local_funding_amount, push_sat) =
1698            channel_amounts_to_lnd(channel_size_sats, push_amount_sats)?;
1699
1700        let mut client = self.connect().await?;
1701
1702        self.connect_peer_if_needed(&mut client, pubkey, host)
1703            .await?;
1704
1705        // Build the request, leaving unspecified fee fields at their
1706        // protobuf defaults so LND falls back to its own configuration.
1707        let mut open_request = OpenChannelRequest {
1708            node_pubkey: pubkey.serialize().to_vec(),
1709            local_funding_amount,
1710            push_sat,
1711            ..Default::default()
1712        };
1713        if let Some(rate) = fee_rate_sats_per_vbyte {
1714            open_request.sat_per_vbyte = rate;
1715        }
1716        if let Some(base_fee) = base_fee_msat {
1717            open_request.base_fee = base_fee;
1718            open_request.use_base_fee = true;
1719        }
1720        if let Some(ppm) = parts_per_million {
1721            open_request.fee_rate = ppm;
1722            open_request.use_fee_rate = true;
1723        }
1724
1725        // Open the channel
1726        match client.lightning().open_channel_sync(open_request).await {
1727            Ok(res) => Ok(OpenChannelResponse {
1728                funding_txid: match res.into_inner().funding_txid {
1729                    Some(txid) => match txid {
1730                        FundingTxid::FundingTxidBytes(mut bytes) => {
1731                            bytes.reverse();
1732                            hex::encode(bytes)
1733                        }
1734                        FundingTxid::FundingTxidStr(str) => str,
1735                    },
1736                    None => String::new(),
1737                },
1738            }),
1739            Err(e) => Err(LightningRpcError::FailedToOpenChannel {
1740                failure_reason: format!("Failed to open channel {e:?}"),
1741            }),
1742        }
1743    }
1744
1745    async fn connect_peer(&self, payload: ConnectPeerRequest) -> Result<(), LightningRpcError> {
1746        let mut client = self.connect().await?;
1747        self.connect_peer_if_needed(
1748            &mut client,
1749            payload.node_address.pubkey,
1750            payload.node_address.host_with_port(),
1751        )
1752        .await
1753    }
1754
1755    async fn close_channels_with_peer(
1756        &self,
1757        CloseChannelsWithPeerRequest {
1758            pubkey,
1759            force,
1760            sats_per_vbyte,
1761        }: CloseChannelsWithPeerRequest,
1762    ) -> Result<CloseChannelsWithPeerResponse, LightningRpcError> {
1763        let mut client = self.connect().await?;
1764
1765        let channels_with_peer = client
1766            .lightning()
1767            .list_channels(ListChannelsRequest {
1768                active_only: false,
1769                inactive_only: false,
1770                public_only: false,
1771                private_only: false,
1772                peer: pubkey.serialize().to_vec(),
1773                peer_alias_lookup: false,
1774            })
1775            .await
1776            .map_err(|e| LightningRpcError::FailedToCloseChannelsWithPeer {
1777                failure_reason: format!("Failed to list channels {e:?}"),
1778            })?
1779            .into_inner()
1780            .channels;
1781
1782        for channel in &channels_with_peer {
1783            let channel_point =
1784                bitcoin::OutPoint::from_str(&channel.channel_point).map_err(|e| {
1785                    LightningRpcError::FailedToCloseChannelsWithPeer {
1786                        failure_reason: format!("Failed to parse channel point {e:?}"),
1787                    }
1788                })?;
1789
1790            if force {
1791                client
1792                    .lightning()
1793                    .close_channel(CloseChannelRequest {
1794                        channel_point: Some(ChannelPoint {
1795                            funding_txid: Some(
1796                                tonic_lnd::lnrpc::channel_point::FundingTxid::FundingTxidBytes(
1797                                    <bitcoin::Txid as AsRef<[u8]>>::as_ref(&channel_point.txid)
1798                                        .to_vec(),
1799                                ),
1800                            ),
1801                            output_index: channel_point.vout,
1802                        }),
1803                        force,
1804                        ..Default::default()
1805                    })
1806                    .await
1807                    .map_err(|e| LightningRpcError::FailedToCloseChannelsWithPeer {
1808                        failure_reason: format!("Failed to close channel {e:?}"),
1809                    })?;
1810            } else {
1811                client
1812                    .lightning()
1813                    .close_channel(CloseChannelRequest {
1814                        channel_point: Some(ChannelPoint {
1815                            funding_txid: Some(
1816                                tonic_lnd::lnrpc::channel_point::FundingTxid::FundingTxidBytes(
1817                                    <bitcoin::Txid as AsRef<[u8]>>::as_ref(&channel_point.txid)
1818                                        .to_vec(),
1819                                ),
1820                            ),
1821                            output_index: channel_point.vout,
1822                        }),
1823                        force,
1824                        sat_per_vbyte: sats_per_vbyte.unwrap_or_default(),
1825                        ..Default::default()
1826                    })
1827                    .await
1828                    .map_err(|e| LightningRpcError::FailedToCloseChannelsWithPeer {
1829                        failure_reason: format!("Failed to close channel {e:?}"),
1830                    })?;
1831            }
1832        }
1833
1834        Ok(CloseChannelsWithPeerResponse {
1835            num_channels_closed: channels_with_peer.len() as u32,
1836        })
1837    }
1838
1839    async fn list_channels(&self) -> Result<ListChannelsResponse, LightningRpcError> {
1840        let mut client = self.connect().await?;
1841
1842        // Fetch peer addresses so we can populate remote_address on each channel
1843        let peer_addresses: BTreeMap<String, String> = client
1844            .lightning()
1845            .list_peers(ListPeersRequest {
1846                latest_error: false,
1847            })
1848            .await
1849            .map(|resp| {
1850                resp.into_inner()
1851                    .peers
1852                    .into_iter()
1853                    .filter_map(|peer| {
1854                        if peer.address.is_empty() {
1855                            None
1856                        } else {
1857                            Some((peer.pub_key, peer.address))
1858                        }
1859                    })
1860                    .collect()
1861            })
1862            .unwrap_or_default();
1863
1864        // Fetch the local fee policy for every channel in one call so we can
1865        // join it onto each ChannelInfo below.
1866        let fee_report: BTreeMap<u64, (u64, u64)> = client
1867            .lightning()
1868            .fee_report(FeeReportRequest {})
1869            .await
1870            .map(|resp| {
1871                resp.into_inner()
1872                    .channel_fees
1873                    .into_iter()
1874                    .map(|report| {
1875                        let base_fee_msat = u64::try_from(report.base_fee_msat).unwrap_or_default();
1876                        let parts_per_million =
1877                            u64::try_from(report.fee_per_mil).unwrap_or_default();
1878                        (report.chan_id, (base_fee_msat, parts_per_million))
1879                    })
1880                    .collect()
1881            })
1882            .unwrap_or_default();
1883
1884        match client
1885            .lightning()
1886            .list_channels(ListChannelsRequest {
1887                active_only: false,
1888                inactive_only: false,
1889                public_only: false,
1890                private_only: false,
1891                peer: vec![],
1892                peer_alias_lookup: true,
1893            })
1894            .await
1895        {
1896            Ok(response) => Ok(ListChannelsResponse {
1897                channels: response
1898                    .into_inner()
1899                    .channels
1900                    .into_iter()
1901                    .map(|channel| {
1902                        let channel_size_sats = channel.capacity.try_into().expect("i64 -> u64");
1903
1904                        let local_balance_sats: u64 =
1905                            channel.local_balance.try_into().expect("i64 -> u64");
1906                        let local_channel_reserve_sats: u64 = match channel.local_constraints {
1907                            Some(constraints) => constraints.chan_reserve_sat,
1908                            None => 0,
1909                        };
1910
1911                        let outbound_liquidity_sats =
1912                            local_balance_sats.saturating_sub(local_channel_reserve_sats);
1913
1914                        let remote_balance_sats: u64 =
1915                            channel.remote_balance.try_into().expect("i64 -> u64");
1916                        let remote_channel_reserve_sats: u64 = match channel.remote_constraints {
1917                            Some(constraints) => constraints.chan_reserve_sat,
1918                            None => 0,
1919                        };
1920
1921                        let inbound_liquidity_sats =
1922                            remote_balance_sats.saturating_sub(remote_channel_reserve_sats);
1923
1924                        let funding_outpoint = OutPoint::from_str(&channel.channel_point).ok();
1925
1926                        let remote_address = peer_addresses.get(&channel.remote_pubkey).cloned();
1927
1928                        let (base_fee_msat, parts_per_million) =
1929                            match fee_report.get(&channel.chan_id) {
1930                                Some((base, ppm)) => (Some(*base), Some(*ppm)),
1931                                None => (None, None),
1932                            };
1933
1934                        ChannelInfo {
1935                            remote_pubkey: PublicKey::from_str(&channel.remote_pubkey)
1936                                .expect("Lightning node returned invalid remote channel pubkey"),
1937                            channel_size_sats,
1938                            outbound_liquidity_sats,
1939                            inbound_liquidity_sats,
1940                            is_active: channel.active,
1941                            funding_outpoint,
1942                            remote_node_alias: if channel.peer_alias.is_empty() {
1943                                None
1944                            } else {
1945                                Some(channel.peer_alias.clone())
1946                            },
1947                            remote_address,
1948                            base_fee_msat,
1949                            parts_per_million,
1950                        }
1951                    })
1952                    .collect(),
1953            }),
1954            Err(e) => Err(LightningRpcError::FailedToListChannels {
1955                failure_reason: format!("Failed to list active channels {e:?}"),
1956            }),
1957        }
1958    }
1959
1960    async fn set_channel_fees(
1961        &self,
1962        payload: SetChannelFeesRequest,
1963    ) -> Result<(), LightningRpcError> {
1964        let mut client = self.connect().await?;
1965
1966        // LND's `PolicyUpdateRequest` applies every field it receives, so we
1967        // need the channel's current `time_lock_delta` (and htlc min/max) to
1968        // avoid clobbering them when only base + ppm are being changed. To
1969        // look those up we first resolve the funding outpoint to LND's
1970        // numeric `chan_id`, then call `get_chan_info`.
1971        let target = format!(
1972            "{}:{}",
1973            payload.funding_outpoint.txid, payload.funding_outpoint.vout
1974        );
1975        let channel = client
1976            .lightning()
1977            .list_channels(ListChannelsRequest::default())
1978            .await
1979            .map_err(|e| LightningRpcError::FailedToSetChannelFees {
1980                failure_reason: format!("Failed to list channels: {e:?}"),
1981            })?
1982            .into_inner()
1983            .channels
1984            .into_iter()
1985            .find(|c| c.channel_point == target)
1986            .ok_or_else(|| LightningRpcError::FailedToSetChannelFees {
1987                failure_reason: format!("No channel found with funding outpoint {target}"),
1988            })?;
1989
1990        let our_pubkey = client
1991            .lightning()
1992            .get_info(GetInfoRequest {})
1993            .await
1994            .map_err(|e| LightningRpcError::FailedToSetChannelFees {
1995                failure_reason: format!("Failed to get node info: {e:?}"),
1996            })?
1997            .into_inner()
1998            .identity_pubkey;
1999
2000        let edge = client
2001            .lightning()
2002            .get_chan_info(ChanInfoRequest {
2003                chan_id: channel.chan_id,
2004                ..Default::default()
2005            })
2006            .await
2007            .map_err(|e| LightningRpcError::FailedToSetChannelFees {
2008                failure_reason: format!("Failed to get channel info: {e:?}"),
2009            })?
2010            .into_inner();
2011
2012        // Pick the policy advertised by our node (the local side); fall back
2013        // to node1_policy when neither pubkey matches, which only happens if
2014        // the gossip data has not propagated yet.
2015        let current_policy = if edge.node1_pub == our_pubkey {
2016            edge.node1_policy
2017        } else if edge.node2_pub == our_pubkey {
2018            edge.node2_policy
2019        } else {
2020            edge.node1_policy
2021        };
2022
2023        let fee_rate_ppm = u32::try_from(payload.parts_per_million).map_err(|_| {
2024            LightningRpcError::FailedToSetChannelFees {
2025                failure_reason: format!(
2026                    "parts_per_million {} does not fit in u32",
2027                    payload.parts_per_million,
2028                ),
2029            }
2030        })?;
2031
2032        let base_fee_msat = i64::try_from(payload.base_fee_msat).map_err(|_| {
2033            LightningRpcError::FailedToSetChannelFees {
2034                failure_reason: format!(
2035                    "base_fee_msat {} does not fit in i64",
2036                    payload.base_fee_msat,
2037                ),
2038            }
2039        })?;
2040
2041        // Default time_lock_delta of 40 matches LND's CLI default for
2042        // `lncli updatechanpolicy` when the channel's existing CLTV is not
2043        // discoverable. max_htlc_msat == 0 means "no max" in LND.
2044        let time_lock_delta = current_policy
2045            .as_ref()
2046            .map(|p| p.time_lock_delta)
2047            .unwrap_or(40);
2048        let max_htlc_msat = current_policy
2049            .as_ref()
2050            .map(|p| p.max_htlc_msat)
2051            .unwrap_or(0);
2052        let min_htlc_msat = current_policy
2053            .as_ref()
2054            .map(|p| p.min_htlc as u64)
2055            .unwrap_or(0);
2056
2057        let chan_point = ChannelPoint {
2058            funding_txid: Some(FundingTxid::FundingTxidBytes(
2059                <bitcoin::Txid as AsRef<[u8]>>::as_ref(&payload.funding_outpoint.txid).to_vec(),
2060            )),
2061            output_index: payload.funding_outpoint.vout,
2062        };
2063
2064        let request = PolicyUpdateRequest {
2065            base_fee_msat,
2066            fee_rate_ppm,
2067            time_lock_delta,
2068            max_htlc_msat,
2069            min_htlc_msat,
2070            min_htlc_msat_specified: false,
2071            scope: Some(PolicyUpdateScope::ChanPoint(chan_point)),
2072            ..Default::default()
2073        };
2074
2075        let response = client
2076            .lightning()
2077            .update_channel_policy(request)
2078            .await
2079            .map_err(|e| LightningRpcError::FailedToSetChannelFees {
2080                failure_reason: format!("update_channel_policy failed: {e:?}"),
2081            })?
2082            .into_inner();
2083
2084        if !response.failed_updates.is_empty() {
2085            let details = response
2086                .failed_updates
2087                .iter()
2088                .map(|f| {
2089                    let outpoint = f
2090                        .outpoint
2091                        .as_ref()
2092                        .map(|op| format!("{}:{}", op.txid_str, op.output_index))
2093                        .unwrap_or_else(|| "<unknown outpoint>".to_string());
2094                    let reason = UpdateFailure::try_from(f.reason)
2095                        .map(|r| r.as_str_name())
2096                        .unwrap_or("UPDATE_FAILURE_UNKNOWN");
2097                    format!("{outpoint}: {reason} ({})", f.update_error)
2098                })
2099                .collect::<Vec<_>>()
2100                .join("; ");
2101            return Err(LightningRpcError::FailedToSetChannelFees {
2102                failure_reason: format!("update_channel_policy reported failures: {details}"),
2103            });
2104        }
2105
2106        Ok(())
2107    }
2108
2109    async fn get_balances(&self) -> Result<GetBalancesResponse, LightningRpcError> {
2110        let mut client = self.connect().await?;
2111
2112        let wallet_balance_response = client
2113            .lightning()
2114            .wallet_balance(WalletBalanceRequest {
2115                ..Default::default()
2116            })
2117            .await
2118            .map_err(|e| LightningRpcError::FailedToGetBalances {
2119                failure_reason: format!("Failed to get on-chain balance {e:?}"),
2120            })?
2121            .into_inner();
2122
2123        let channel_balance_response = client
2124            .lightning()
2125            .channel_balance(ChannelBalanceRequest {})
2126            .await
2127            .map_err(|e| LightningRpcError::FailedToGetBalances {
2128                failure_reason: format!("Failed to get lightning balance {e:?}"),
2129            })?
2130            .into_inner();
2131        let total_outbound = channel_balance_response.local_balance.unwrap_or_default();
2132        let unsettled_outbound = channel_balance_response
2133            .unsettled_local_balance
2134            .unwrap_or_default();
2135        let pending_outbound = channel_balance_response
2136            .pending_open_local_balance
2137            .unwrap_or_default();
2138        let lightning_balance_msats = total_outbound
2139            .msat
2140            .saturating_sub(unsettled_outbound.msat)
2141            .saturating_sub(pending_outbound.msat);
2142
2143        let total_inbound = channel_balance_response.remote_balance.unwrap_or_default();
2144        let unsettled_inbound = channel_balance_response
2145            .unsettled_remote_balance
2146            .unwrap_or_default();
2147        let pending_inbound = channel_balance_response
2148            .pending_open_remote_balance
2149            .unwrap_or_default();
2150        let inbound_lightning_liquidity_msats = total_inbound
2151            .msat
2152            .saturating_sub(unsettled_inbound.msat)
2153            .saturating_sub(pending_inbound.msat);
2154
2155        Ok(GetBalancesResponse {
2156            onchain_balance_sats: (wallet_balance_response.total_balance
2157                + wallet_balance_response.reserved_balance_anchor_chan)
2158                as u64,
2159            // `send_onchain` spends unconfirmed outputs, and LND refuses a send
2160            // that would leave less than the anchor-channel reserve.
2161            spendable_onchain_balance_sats: wallet_balance_response
2162                .total_balance
2163                .saturating_sub(wallet_balance_response.reserved_balance_anchor_chan)
2164                .max(0) as u64,
2165            lightning_balance_msats,
2166            inbound_lightning_liquidity_msats,
2167        })
2168    }
2169
2170    async fn get_invoice(
2171        &self,
2172        get_invoice_request: GetInvoiceRequest,
2173    ) -> Result<Option<GetInvoiceResponse>, LightningRpcError> {
2174        let mut client = self.connect().await?;
2175        let invoice = client
2176            .invoices()
2177            .lookup_invoice_v2(LookupInvoiceMsg {
2178                invoice_ref: Some(InvoiceRef::PaymentHash(
2179                    get_invoice_request.payment_hash.consensus_encode_to_vec(),
2180                )),
2181                ..Default::default()
2182            })
2183            .await;
2184        let invoice = match invoice {
2185            Ok(invoice) => invoice.into_inner(),
2186            Err(_) => return Ok(None),
2187        };
2188        let status = match &invoice.state() {
2189            InvoiceState::Settled => fedimint_gateway_common::PaymentStatus::Succeeded,
2190            InvoiceState::Canceled => fedimint_gateway_common::PaymentStatus::Failed,
2191            _ => fedimint_gateway_common::PaymentStatus::Pending,
2192        };
2193
2194        Ok(Some(GetInvoiceResponse {
2195            preimage: invoice_preimage_hex(&invoice),
2196            payment_hash: Some(
2197                sha256::Hash::from_slice(&invoice.r_hash).expect("Could not convert payment hash"),
2198            ),
2199            amount: Amount::from_msats(invoice.value_msat as u64),
2200            created_at: UNIX_EPOCH + Duration::from_secs(invoice.creation_date as u64),
2201            status,
2202        }))
2203    }
2204
2205    async fn list_transactions(
2206        &self,
2207        start_secs: u64,
2208        end_secs: u64,
2209    ) -> Result<ListTransactionsResponse, LightningRpcError> {
2210        let mut client = self.connect().await?;
2211        let payments = client
2212            .lightning()
2213            .list_payments(ListPaymentsRequest {
2214                // On higher versions on LND, we can filter on the time range directly in the query
2215                ..Default::default()
2216            })
2217            .await
2218            .map_err(|err| LightningRpcError::FailedToListTransactions {
2219                failure_reason: err.to_string(),
2220            })?
2221            .into_inner();
2222
2223        let mut payments = payments
2224            .payments
2225            .iter()
2226            .filter_map(|payment| {
2227                let timestamp_secs = (payment.creation_time_ns / 1_000_000_000) as u64;
2228                if timestamp_secs < start_secs || end_secs <= timestamp_secs {
2229                    return None;
2230                }
2231                let payment_hash = sha256::Hash::from_str(&payment.payment_hash).ok();
2232                let preimage = (!payment.payment_preimage.is_empty())
2233                    .then_some(payment.payment_preimage.clone());
2234                let status = match &payment.status() {
2235                    PaymentStatus::Succeeded => fedimint_gateway_common::PaymentStatus::Succeeded,
2236                    PaymentStatus::Failed => fedimint_gateway_common::PaymentStatus::Failed,
2237                    _ => fedimint_gateway_common::PaymentStatus::Pending,
2238                };
2239                Some(PaymentDetails {
2240                    payment_hash,
2241                    preimage,
2242                    payment_kind: PaymentKind::Bolt11,
2243                    amount: Amount::from_msats(payment.value_msat as u64),
2244                    direction: PaymentDirection::Outbound,
2245                    status,
2246                    timestamp_secs,
2247                })
2248            })
2249            .collect::<Vec<_>>();
2250
2251        let invoices = client
2252            .lightning()
2253            .list_invoices(ListInvoiceRequest {
2254                pending_only: false,
2255                // On higher versions on LND, we can filter on the time range directly in the query
2256                ..Default::default()
2257            })
2258            .await
2259            .map_err(|err| LightningRpcError::FailedToListTransactions {
2260                failure_reason: err.to_string(),
2261            })?
2262            .into_inner();
2263
2264        let mut incoming_payments = invoices
2265            .invoices
2266            .iter()
2267            .filter_map(|invoice| {
2268                let timestamp_secs = invoice.settle_date as u64;
2269                if timestamp_secs < start_secs || end_secs <= timestamp_secs {
2270                    return None;
2271                }
2272                let status = match &invoice.state() {
2273                    InvoiceState::Settled => fedimint_gateway_common::PaymentStatus::Succeeded,
2274                    InvoiceState::Canceled => fedimint_gateway_common::PaymentStatus::Failed,
2275                    _ => return None,
2276                };
2277                let preimage = (!invoice.r_preimage.is_empty())
2278                    .then_some(invoice.r_preimage.encode_hex::<String>());
2279                Some(PaymentDetails {
2280                    payment_hash: Some(
2281                        sha256::Hash::from_slice(&invoice.r_hash)
2282                            .expect("Could not convert payment hash"),
2283                    ),
2284                    preimage,
2285                    payment_kind: PaymentKind::Bolt11,
2286                    amount: Amount::from_msats(invoice.value_msat as u64),
2287                    direction: PaymentDirection::Inbound,
2288                    status,
2289                    timestamp_secs,
2290                })
2291            })
2292            .collect::<Vec<_>>();
2293
2294        payments.append(&mut incoming_payments);
2295        payments.sort_by_key(|p| p.timestamp_secs);
2296
2297        Ok(ListTransactionsResponse {
2298            transactions: payments,
2299        })
2300    }
2301
2302    fn create_offer(
2303        &self,
2304        _amount_msat: Option<Amount>,
2305        _description: Option<String>,
2306        _expiry_secs: Option<u32>,
2307        _quantity: Option<u64>,
2308    ) -> Result<String, LightningRpcError> {
2309        Err(LightningRpcError::Bolt12Error {
2310            failure_reason: "LND Does not support Bolt12".to_string(),
2311        })
2312    }
2313
2314    async fn pay_offer(
2315        &self,
2316        _offer: String,
2317        _quantity: Option<u64>,
2318        _amount: Option<Amount>,
2319        _payer_note: Option<String>,
2320    ) -> Result<Preimage, LightningRpcError> {
2321        Err(LightningRpcError::Bolt12Error {
2322            failure_reason: "LND Does not support Bolt12".to_string(),
2323        })
2324    }
2325
2326    fn sync_wallet(&self) -> Result<(), LightningRpcError> {
2327        // There is nothing explicit needed to do for syncing an LND node
2328        Ok(())
2329    }
2330}
2331
2332fn route_hints_to_lnd(
2333    route_hints: &[fedimint_ln_common::route_hints::RouteHint],
2334) -> Vec<tonic_lnd::lnrpc::RouteHint> {
2335    route_hints
2336        .iter()
2337        .map(|hint| tonic_lnd::lnrpc::RouteHint {
2338            hop_hints: hint
2339                .0
2340                .iter()
2341                .map(|hop| tonic_lnd::lnrpc::HopHint {
2342                    node_id: hop.src_node_id.serialize().encode_hex(),
2343                    chan_id: hop.short_channel_id,
2344                    fee_base_msat: hop.base_msat,
2345                    fee_proportional_millionths: hop.proportional_millionths,
2346                    cltv_expiry_delta: u32::from(hop.cltv_expiry_delta),
2347                })
2348                .collect(),
2349        })
2350        .collect()
2351}
2352
2353fn wire_features_to_lnd_feature_vec(
2354    features_wire_encoded: &[u8],
2355) -> Result<Vec<i32>, FeatureVectorTooLargeError> {
2356    if features_wire_encoded.len() > 1_000 {
2357        return Err(FeatureVectorTooLargeError);
2358    }
2359
2360    let lnd_features = features_wire_encoded
2361        .iter()
2362        .rev()
2363        .enumerate()
2364        .flat_map(|(byte_idx, &feature_byte)| {
2365            (0..8).filter_map(move |bit_idx| {
2366                if (feature_byte & (1u8 << bit_idx)) != 0 {
2367                    Some(
2368                        i32::try_from(byte_idx * 8 + bit_idx)
2369                            .expect("Index will never exceed i32::MAX for feature vectors <8MB"),
2370                    )
2371                } else {
2372                    None
2373                }
2374            })
2375        })
2376        .collect::<Vec<_>>();
2377
2378    Ok(lnd_features)
2379}
2380
2381/// Utility struct for logging payment hashes. Useful for debugging.
2382struct PrettyPaymentHash<'a>(&'a Vec<u8>);
2383
2384impl Display for PrettyPaymentHash<'_> {
2385    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2386        write!(f, "payment_hash={}", self.0.encode_hex::<String>())
2387    }
2388}
2389
2390/// An invoice's destination feature bits are too long to convert for LND.
2391#[derive(Debug, thiserror::Error)]
2392#[error("Will not process feature bit vectors larger than 1000 byte")]
2393struct FeatureVectorTooLargeError;
2394
2395#[cfg(test)]
2396mod tests;