Skip to main content

fedimint_gwv2_client/
lib.rs

1mod api;
2mod complete_sm;
3pub mod events;
4mod receive_sm;
5mod send_sm;
6
7use std::collections::BTreeMap;
8use std::fmt;
9use std::fmt::Debug;
10use std::sync::Arc;
11use std::time::Duration;
12
13use async_trait::async_trait;
14use bitcoin::hashes::sha256;
15use bitcoin::secp256k1::Message;
16use events::{IncomingPaymentStarted, OutgoingPaymentStarted};
17use fedimint_api_client::api::{DynModuleApi, FederationError};
18use fedimint_client::ClientHandleArc;
19use fedimint_client_module::error::ClientModuleError;
20use fedimint_client_module::module::init::{ClientModuleInit, ClientModuleInitArgs};
21use fedimint_client_module::module::recovery::NoModuleBackup;
22use fedimint_client_module::module::{ClientContext, ClientModule, IClientModule, OutPointRange};
23use fedimint_client_module::sm::{Context, DynState, ModuleNotifier, State, StateTransition};
24use fedimint_client_module::transaction::{
25    ClientOutput, ClientOutputBundle, ClientOutputSM, TransactionBuilder,
26};
27use fedimint_client_module::{
28    DynGlobalClientContext, TransactionSubmitError, sm_enum_variant_translation,
29};
30use fedimint_core::config::FederationId;
31use fedimint_core::core::{
32    Account, Decoder, IntoDynInstance, ModuleInstanceId, ModuleKind, OperationId,
33};
34use fedimint_core::db::DatabaseTransaction;
35use fedimint_core::encoding::{Decodable, Encodable};
36use fedimint_core::module::{
37    Amounts, ApiVersion, CommonModuleInit, ModuleCommon, ModuleInit, MultiApiVersion,
38};
39use fedimint_core::secp256k1::Keypair;
40use fedimint_core::task::timeout;
41use fedimint_core::time::now;
42use fedimint_core::util::{FmtCompact, Spanned, backoff_util, retry};
43use fedimint_core::{Amount, OutPoint, PeerId, apply, async_trait_maybe_send, secp256k1};
44use fedimint_lightning::{InterceptPaymentResponse, LightningRpcError};
45use fedimint_lnv2_common::config::LightningClientConfig;
46use fedimint_lnv2_common::contracts::{IncomingContract, PaymentImage};
47use fedimint_lnv2_common::gateway_api::SendPaymentPayload;
48use fedimint_lnv2_common::{
49    LightningCommonInit, LightningInvoice, LightningModuleTypes, LightningOutput, LightningOutputV0,
50};
51use futures::StreamExt;
52use lightning_invoice::Bolt11Invoice;
53use receive_sm::{ReceiveSMState, ReceiveStateMachine};
54use secp256k1::schnorr::Signature;
55use send_sm::{SendSMState, SendStateMachine};
56use serde::{Deserialize, Serialize};
57use thiserror::Error;
58use tpe::{AggregatePublicKey, PublicKeyShare};
59use tracing::{info, warn};
60
61use crate::api::GatewayFederationApi;
62pub use crate::complete_sm::IncomingCircuitKey;
63use crate::complete_sm::{
64    CircuitCompleteSMCommon, CircuitCompleteStateMachine, CompleteSMState, CompleteStateMachine,
65};
66use crate::receive_sm::ReceiveSMCommon;
67use crate::send_sm::SendSMCommon;
68
69/// Bound on the federation liveness probe that gates funding a fresh incoming
70/// contract. A healthy federation answers well within this; the bound only
71/// decides how quickly an unreachable one fails the HTLC back.
72const FEDERATION_LIVENESS_TIMEOUT: Duration = Duration::from_secs(10);
73
74/// Minimum number of blocks between the current height and an incoming HTLC's
75/// claim deadline for the gateway to fund its incoming contract.
76const LNV2_CLAIM_DEADLINE_MARGIN: u32 = 2;
77
78/// LNv2 CLTV Delta in blocks
79pub const EXPIRATION_DELTA_MINIMUM_V2: u64 = 144;
80
81fn incoming_circuit_operation_id(
82    receive_operation_id: OperationId,
83    circuit: IncomingCircuitKey,
84) -> OperationId {
85    OperationId::from_encodable(&(
86        "gateway-lnv2-incoming-circuit",
87        receive_operation_id,
88        circuit,
89    ))
90}
91
92fn is_legacy_completion_for_circuit(
93    state: &GatewayClientStateMachinesV2,
94    circuit: IncomingCircuitKey,
95) -> bool {
96    let IncomingCircuitKey {
97        incoming_chan_id,
98        htlc_id,
99    } = circuit;
100    matches!(
101        state,
102        GatewayClientStateMachinesV2::Complete(CompleteStateMachine {
103            common,
104            ..
105        }) if common.incoming_chan_id == incoming_chan_id && common.htlc_id == htlc_id
106    )
107}
108
109fn legacy_completion_in_states(
110    active: &[GatewayClientStateMachinesV2],
111    inactive: &[GatewayClientStateMachinesV2],
112    circuit: IncomingCircuitKey,
113) -> bool {
114    active
115        .iter()
116        .chain(inactive)
117        .any(|state| is_legacy_completion_for_circuit(state, circuit))
118}
119
120#[derive(Debug, Clone, Copy, Eq, PartialEq)]
121enum IncomingRelayPlan {
122    Replay,
123    AddCompletion,
124    CreateReceiveAndCompletion,
125}
126
127fn incoming_relay_plan(
128    receive_exists: bool,
129    completion_exists: bool,
130    legacy_completion_exists: bool,
131) -> IncomingRelayPlan {
132    if completion_exists || legacy_completion_exists {
133        IncomingRelayPlan::Replay
134    } else if receive_exists {
135        IncomingRelayPlan::AddCompletion
136    } else {
137        IncomingRelayPlan::CreateReceiveAndCompletion
138    }
139}
140
141fn operation_creation_failed_permanently(
142    creation_failed: bool,
143    operation_exists_after_failure: bool,
144) -> bool {
145    creation_failed && !operation_exists_after_failure
146}
147
148/// Identifies the role of an LNv2 gateway operation.
149#[derive(Debug, Clone, Serialize, Deserialize)]
150#[serde(untagged)]
151pub enum GatewayOperationMetaV2 {
152    /// Metadata written before operation roles were distinguished.
153    Legacy(()),
154    /// Metadata written for a role-specific operation.
155    Role {
156        /// Role used when recovering active operations.
157        role: GatewayOperationRoleV2,
158    },
159}
160
161/// Role of an LNv2 gateway operation.
162#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
163#[serde(rename_all = "snake_case")]
164pub enum GatewayOperationRoleV2 {
165    /// An outgoing payment operation.
166    Send,
167    /// A federation receive operation.
168    Receive,
169    /// An incoming Lightning circuit completion operation.
170    CircuitCompletion,
171}
172
173impl GatewayOperationMetaV2 {
174    /// Constructs metadata for `role`.
175    pub fn role(role: GatewayOperationRoleV2) -> Self {
176        Self::Role { role }
177    }
178
179    /// Returns whether shutdown must await Lightning circuit completion.
180    pub fn waits_for_completion(&self) -> bool {
181        matches!(
182            self,
183            Self::Legacy(())
184                | Self::Role {
185                    role: GatewayOperationRoleV2::CircuitCompletion
186                }
187        )
188    }
189}
190
191#[derive(Debug, Clone)]
192pub struct GatewayClientInitV2 {
193    pub gateway: Arc<dyn IGatewayClientV2>,
194}
195
196impl ModuleInit for GatewayClientInitV2 {
197    type Common = LightningCommonInit;
198
199    async fn dump_database(
200        &self,
201        _dbtx: &mut DatabaseTransaction<'_>,
202        _prefix_names: Vec<String>,
203    ) -> Box<dyn Iterator<Item = (String, Box<dyn erased_serde::Serialize + Send>)> + '_> {
204        Box::new(vec![].into_iter())
205    }
206}
207
208#[apply(async_trait_maybe_send!)]
209impl ClientModuleInit for GatewayClientInitV2 {
210    type Module = GatewayClientModuleV2;
211
212    fn supported_api_versions(&self) -> MultiApiVersion {
213        MultiApiVersion::try_from_iter([ApiVersion { major: 0, minor: 0 }])
214            .expect("no version conflicts")
215    }
216
217    async fn init(
218        &self,
219        args: &ClientModuleInitArgs<Self>,
220    ) -> Result<Self::Module, ClientModuleError> {
221        Ok(GatewayClientModuleV2 {
222            federation_id: *args.federation_id(),
223            cfg: args.cfg().clone(),
224            notifier: args.notifier().clone(),
225            client_ctx: args.context(),
226            module_api: args.module_api().clone(),
227            keypair: args
228                .module_root_secret()
229                .clone()
230                .to_secp_key(fedimint_core::secp256k1::SECP256K1),
231            gateway: self.gateway.clone(),
232        })
233    }
234}
235
236#[derive(Debug, Clone)]
237pub struct GatewayClientModuleV2 {
238    pub federation_id: FederationId,
239    pub cfg: LightningClientConfig,
240    pub notifier: ModuleNotifier<GatewayClientStateMachinesV2>,
241    pub client_ctx: ClientContext<Self>,
242    pub module_api: DynModuleApi,
243    pub keypair: Keypair,
244    pub gateway: Arc<dyn IGatewayClientV2>,
245}
246
247#[derive(Debug, Clone)]
248pub struct GatewayClientContextV2 {
249    pub module: GatewayClientModuleV2,
250    pub decoder: Decoder,
251    pub tpe_agg_pk: AggregatePublicKey,
252    pub tpe_pks: BTreeMap<PeerId, PublicKeyShare>,
253    pub gateway: Arc<dyn IGatewayClientV2>,
254}
255
256impl Context for GatewayClientContextV2 {
257    const KIND: Option<ModuleKind> = Some(fedimint_lnv2_common::KIND);
258}
259
260impl ClientModule for GatewayClientModuleV2 {
261    type Init = GatewayClientInitV2;
262    type Common = LightningModuleTypes;
263    type Backup = NoModuleBackup;
264    type ModuleStateMachineContext = GatewayClientContextV2;
265    type States = GatewayClientStateMachinesV2;
266
267    fn context(&self) -> Self::ModuleStateMachineContext {
268        GatewayClientContextV2 {
269            module: self.clone(),
270            decoder: self.decoder(),
271            tpe_agg_pk: self.cfg.tpe_agg_pk,
272            tpe_pks: self.cfg.tpe_pks.clone(),
273            gateway: self.gateway.clone(),
274        }
275    }
276    fn input_fee(
277        &self,
278        amount: &Amounts,
279        _input: &<Self::Common as ModuleCommon>::Input,
280    ) -> Option<Amounts> {
281        Some(Amounts::new_bitcoin(
282            self.cfg.fee_consensus.fee(amount.expect_only_bitcoin()),
283        ))
284    }
285
286    fn output_fee(
287        &self,
288        _amount: &Amounts,
289        output: &<Self::Common as ModuleCommon>::Output,
290    ) -> Option<Amounts> {
291        let amount = match output.ensure_v0_ref().ok()? {
292            LightningOutputV0::Outgoing(contract) => contract.amount,
293            LightningOutputV0::Incoming(contract) => contract.commitment.amount,
294        };
295
296        Some(Amounts::new_bitcoin(self.cfg.fee_consensus.fee(amount)))
297    }
298}
299
300#[derive(Debug, Clone, Eq, PartialEq, Hash, Decodable, Encodable)]
301pub enum GatewayClientStateMachinesV2 {
302    Send(SendStateMachine),
303    Receive(ReceiveStateMachine),
304    /// Legacy completion state retained to decode and resume combined receive
305    /// operations created by older clients.
306    Complete(CompleteStateMachine),
307    /// Completes one incoming circuit independently of other circuits carrying
308    /// the same payment hash and amount.
309    CircuitComplete(CircuitCompleteStateMachine),
310}
311
312impl fmt::Display for GatewayClientStateMachinesV2 {
313    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
314        match self {
315            GatewayClientStateMachinesV2::Send(send) => {
316                write!(f, "{send}")
317            }
318            GatewayClientStateMachinesV2::Receive(receive) => {
319                write!(f, "{receive}")
320            }
321            GatewayClientStateMachinesV2::Complete(complete) => {
322                write!(f, "{complete}")
323            }
324            GatewayClientStateMachinesV2::CircuitComplete(complete) => {
325                write!(f, "{complete}")
326            }
327        }
328    }
329}
330
331impl IntoDynInstance for GatewayClientStateMachinesV2 {
332    type DynType = DynState;
333
334    fn into_dyn(self, instance_id: ModuleInstanceId) -> Self::DynType {
335        DynState::from_typed(instance_id, self)
336    }
337}
338
339impl State for GatewayClientStateMachinesV2 {
340    type ModuleContext = GatewayClientContextV2;
341
342    fn transitions(
343        &self,
344        context: &Self::ModuleContext,
345        global_context: &DynGlobalClientContext,
346    ) -> Vec<StateTransition<Self>> {
347        match self {
348            GatewayClientStateMachinesV2::Send(state) => {
349                sm_enum_variant_translation!(
350                    state.transitions(context, global_context),
351                    GatewayClientStateMachinesV2::Send
352                )
353            }
354            GatewayClientStateMachinesV2::Receive(state) => {
355                sm_enum_variant_translation!(
356                    state.transitions(context, global_context),
357                    GatewayClientStateMachinesV2::Receive
358                )
359            }
360            GatewayClientStateMachinesV2::Complete(state) => {
361                sm_enum_variant_translation!(
362                    state.transitions(context, global_context),
363                    GatewayClientStateMachinesV2::Complete
364                )
365            }
366            GatewayClientStateMachinesV2::CircuitComplete(state) => {
367                sm_enum_variant_translation!(
368                    state.transitions(context, global_context),
369                    GatewayClientStateMachinesV2::CircuitComplete
370                )
371            }
372        }
373    }
374
375    fn operation_id(&self) -> OperationId {
376        match self {
377            GatewayClientStateMachinesV2::Send(state) => state.operation_id(),
378            GatewayClientStateMachinesV2::Receive(state) => state.operation_id(),
379            GatewayClientStateMachinesV2::Complete(state) => state.operation_id(),
380            GatewayClientStateMachinesV2::CircuitComplete(state) => state.operation_id(),
381        }
382    }
383}
384
385#[derive(Debug, Clone, Eq, PartialEq, Hash, Serialize, Deserialize, Decodable, Encodable)]
386pub enum FinalReceiveState {
387    Rejected,
388    Success([u8; 32]),
389    Refunded,
390    Failure,
391}
392
393impl GatewayClientModuleV2 {
394    /// Starts paying the invoice of an LNv2 outgoing contract, or joins the
395    /// payment already under way for it, and waits for its outcome.
396    ///
397    /// The `Ok` value is that outcome: the preimage if the payment succeeded,
398    /// or the gateway's forfeit signature, which lets the sender reclaim the
399    /// contract, if it was cancelled.
400    ///
401    /// # Errors
402    ///
403    /// Fails with a [`GatewaySendPaymentError`] if the request is refused
404    /// before any payment starts: the gateway is not connected to its
405    /// lightning node, the contract is another gateway's, the
406    /// request's signature does not verify, the federation has not confirmed
407    /// this contract at that outpoint or cannot be asked, the invoice has no
408    /// amount or does not match the contract, the gateway cannot price the
409    /// payment, or another contract already claimed the payment image.
410    pub async fn send_payment(
411        &self,
412        payload: SendPaymentPayload,
413    ) -> Result<Result<[u8; 32], Signature>, GatewaySendPaymentError> {
414        let operation_start = now();
415
416        // The operation id is equal to the contract id which also doubles as the
417        // message signed by the gateway via the forfeit signature to forfeit
418        // the gateways claim to a contract in case of cancellation. We only create a
419        // forfeit signature after we have started the send state machine to
420        // prevent replay attacks with a previously cancelled outgoing contract
421        let operation_id = OperationId::from_encodable(&payload.contract.clone());
422
423        // Since the following checks may only fail due to client side
424        // programming error we do not have to enable cancellation and can check
425        // them before we start the state machine.
426        if payload.contract.claim_pk != self.keypair.public_key() {
427            return Err(GatewaySendPaymentError::NotOurContract);
428        }
429
430        // This prevents DOS attacks where an attacker submits a different invoice.
431        if secp256k1::SECP256K1
432            .verify_schnorr(
433                &payload.auth,
434                &Message::from_digest(*payload.invoice.consensus_hash::<sha256::Hash>().as_ref()),
435                &payload.contract.refund_pk.x_only_public_key().0,
436            )
437            .is_err()
438        {
439            return Err(GatewaySendPaymentError::InvalidAuthSignature);
440        }
441
442        // The operation id is derived from the contract, which is public in the
443        // funding transaction, and joining the operation yields its preimage. So
444        // the join belongs behind the signature above.
445        if self.client_ctx.operation_exists(operation_id).await {
446            return Ok(self.subscribe_send(operation_id).await);
447        }
448
449        // A send accepted while the lightning node is unreachable would sit
450        // waiting for it, and nothing about the payment is known until then.
451        // Refusing up front keeps the sender free to use another gateway. Only
452        // new sends are refused: joining an existing operation above resumes
453        // one already started.
454        if !self.gateway.is_lightning_connected().await {
455            return Err(GatewaySendPaymentError::LightningNotConnected);
456        }
457
458        // We need to check that the contract has been confirmed by the federation
459        // before we start the state machine to prevent DOS attacks.
460        let (contract_id, expiration) = self
461            .module_api
462            .outgoing_contract_expiration(payload.outpoint)
463            .await?
464            .ok_or(GatewaySendPaymentError::ContractNotConfirmed)?;
465
466        if contract_id != payload.contract.contract_id() {
467            return Err(GatewaySendPaymentError::ContractIdMismatch);
468        }
469
470        let (payment_hash, amount) = match &payload.invoice {
471            LightningInvoice::Bolt11(invoice) => (
472                invoice.payment_hash(),
473                invoice
474                    .amount_milli_satoshis()
475                    .ok_or(GatewaySendPaymentError::MissingInvoiceAmount)?,
476            ),
477        };
478
479        if PaymentImage::Hash(*payment_hash) != payload.contract.payment_image {
480            return Err(GatewaySendPaymentError::PaymentHashMismatch);
481        }
482
483        let min_contract_amount = self
484            .gateway
485            .min_contract_amount(&payload.federation_id, amount)
486            .await
487            .map_err(GatewaySendPaymentError::MinContractAmount)?;
488
489        // Contracts for different invoices, on LNv1 or in other federations, can
490        // share a payment image, and paying one pays them all. So only the first
491        // operation to claim the image may ever pay it out; the claim is never
492        // released. It is taken before the state machine exists, so a refused
493        // contract has not been paid for. A retry of this operation finds its own
494        // claim.
495        //
496        // TODO(joschisan): review whether answering with a forfeit signature is
497        // safe here, so the sender is refunded immediately instead of at the
498        // contract's expiration. It should be: a refused contract can never take
499        // the claim later, so we never pay out on it.
500        if !self
501            .gateway
502            .claim_payment_image(&payload.contract.payment_image, operation_id)
503            .await
504        {
505            return Err(GatewaySendPaymentError::PaymentImageAlreadyClaimed);
506        }
507
508        let send_sm = GatewayClientStateMachinesV2::Send(SendStateMachine {
509            common: SendSMCommon {
510                operation_id,
511                outpoint: payload.outpoint,
512                contract: payload.contract.clone(),
513                max_delay: expiration.saturating_sub(EXPIRATION_DELTA_MINIMUM_V2),
514                min_contract_amount,
515                invoice: payload.invoice,
516                claim_keypair: self.keypair,
517            },
518            state: SendSMState::Sending,
519        });
520
521        let mut dbtx = self.client_ctx.module_db().begin_transaction().await;
522        // If the operation already exists, join it instead of starting another payment.
523        let _ = self
524            .client_ctx
525            .manual_operation_start_dbtx(
526                &mut dbtx.to_ref_nc(),
527                operation_id,
528                Account::Primary,
529                LightningCommonInit::KIND.as_str(),
530                GatewayOperationMetaV2::role(GatewayOperationRoleV2::Send),
531                vec![self.client_ctx.make_dyn_state(send_sm)],
532            )
533            .await;
534
535        self.client_ctx
536            .log_event(
537                &mut dbtx,
538                OutgoingPaymentStarted {
539                    operation_start,
540                    outgoing_contract: payload.contract.clone(),
541                    min_contract_amount,
542                    invoice_amount: Amount::from_msats(amount),
543                    max_delay: expiration.saturating_sub(EXPIRATION_DELTA_MINIMUM_V2),
544                },
545            )
546            .await;
547        dbtx.commit_tx().await;
548
549        Ok(self.subscribe_send(operation_id).await)
550    }
551
552    /// Returns the timelock budget, in blocks, that the outgoing contract at
553    /// `outpoint` leaves for a payment dispatched now, retrying until the
554    /// federation answers. A contract the federation no longer knows leaves
555    /// no budget.
556    async fn await_outgoing_contract_max_delay(&self, outpoint: OutPoint) -> u64 {
557        let expiration = retry(
558            "outgoing contract expiration",
559            backoff_util::background_backoff(),
560            || self.module_api.outgoing_contract_expiration(outpoint),
561        )
562        .await
563        .expect("Retries until the federation answers");
564
565        expiration.map_or(0, |(_, expiration)| {
566            expiration.saturating_sub(EXPIRATION_DELTA_MINIMUM_V2)
567        })
568    }
569
570    pub async fn subscribe_send(&self, operation_id: OperationId) -> Result<[u8; 32], Signature> {
571        let mut stream = self.notifier.subscribe(operation_id).await;
572
573        loop {
574            if let Some(GatewayClientStateMachinesV2::Send(state)) = stream.next().await {
575                match state.state {
576                    SendSMState::Sending => {}
577                    SendSMState::Claiming(claiming) => {
578                        // The preimage is proof the payment succeeded, so return it to
579                        // the sender as soon as it is available rather than waiting for
580                        // an additional ordering. The gateway's claim of the outgoing
581                        // contract has already been submitted by the send state machine
582                        // and finalizes in the background.
583                        return Ok(claiming.preimage);
584                    }
585                    SendSMState::Cancelled(cancelled) => {
586                        warn!("Outgoing lightning payment is cancelled {:?}", cancelled);
587
588                        let signature = self
589                            .keypair
590                            .sign_schnorr(state.common.contract.forfeit_message());
591
592                        assert!(state.common.contract.verify_forfeit_signature(&signature));
593
594                        return Err(signature);
595                    }
596                }
597            }
598        }
599    }
600
601    async fn legacy_completion_exists(
602        &self,
603        operation_id: OperationId,
604        circuit: IncomingCircuitKey,
605    ) -> bool {
606        let active = self
607            .client_ctx
608            .get_own_operation_active_states(operation_id)
609            .await
610            .into_iter()
611            .map(|(state, _)| state)
612            .collect::<Vec<_>>();
613        let inactive = self
614            .client_ctx
615            .get_own_operation_inactive_states(operation_id)
616            .await
617            .into_iter()
618            .map(|(state, _)| state)
619            .collect::<Vec<_>>();
620
621        legacy_completion_in_states(&active, &inactive, circuit)
622    }
623
624    /// Refuses to fund a fresh incoming contract unless a threshold of
625    /// guardians is answering. LNv1 gets this check implicitly by fetching the
626    /// offer from the federation first; LNv2 reads the contract from the
627    /// gateway's own database, so it has to probe explicitly.
628    async fn ensure_federation_responsive(
629        &self,
630        payment_hash: sha256::Hash,
631    ) -> Result<(), RelayIncomingHtlcError> {
632        match timeout(
633            FEDERATION_LIVENESS_TIMEOUT,
634            self.module_api.consensus_block_count(),
635        )
636        .await
637        {
638            Ok(Ok(_consensus_block_count)) => Ok(()),
639            Ok(Err(err)) => {
640                warn!(
641                    %payment_hash,
642                    err = %err.fmt_compact(),
643                    "Federation liveness probe failed, refusing to fund incoming contract"
644                );
645                Err(RelayIncomingHtlcError::FederationUnreachable(Box::new(err)))
646            }
647            Err(_elapsed) => {
648                warn!(
649                    %payment_hash,
650                    timeout_secs = FEDERATION_LIVENESS_TIMEOUT.as_secs(),
651                    "Federation liveness probe timed out, refusing to fund incoming contract"
652                );
653                Err(RelayIncomingHtlcError::FederationTimeout {
654                    timeout_secs: FEDERATION_LIVENESS_TIMEOUT.as_secs(),
655                })
656            }
657        }
658    }
659
660    /// Funds the incoming contract of an intercepted LNv2 HTLC and starts the
661    /// operation that completes the HTLC's circuit.
662    ///
663    /// A contract or circuit that is already being handled is joined rather
664    /// than started twice.
665    ///
666    /// # Errors
667    ///
668    /// Fails with a [`RelayIncomingHtlcError`] if a fresh contract is not
669    /// funded because the HTLC's claim deadline is too close or the federation
670    /// does not answer, or if the funding
671    /// transaction or the completion operation could not be started and no
672    /// earlier attempt had started it.
673    pub async fn relay_incoming_htlc(
674        &self,
675        payment_hash: sha256::Hash,
676        incoming_chan_id: u64,
677        htlc_id: u64,
678        contract: IncomingContract,
679        amount_msat: u64,
680        blocks_to_claim_deadline: u32,
681    ) -> Result<(), RelayIncomingHtlcError> {
682        let operation_start = now();
683        let receive_operation_id = OperationId::from_encodable(&contract);
684        let circuit = IncomingCircuitKey {
685            incoming_chan_id,
686            htlc_id,
687        };
688        let completion_operation_id = incoming_circuit_operation_id(receive_operation_id, circuit);
689        let receive_exists = self.client_ctx.operation_exists(receive_operation_id).await;
690        let completion_exists = self
691            .client_ctx
692            .operation_exists(completion_operation_id)
693            .await;
694        let legacy_completion_exists = self
695            .legacy_completion_exists(receive_operation_id, circuit)
696            .await;
697        let plan = incoming_relay_plan(receive_exists, completion_exists, legacy_completion_exists);
698        if plan == IncomingRelayPlan::Replay {
699            return Ok(());
700        }
701
702        let commitment = contract.commitment.clone();
703        if plan == IncomingRelayPlan::CreateReceiveAndCompletion {
704            // Only gate fresh funding: the other plans resume an already
705            // funded contract and must not be cancelled.
706            //
707            // Funding is irreversible, and the gateway is only reimbursed by
708            // settling the HTLC before its claim deadline, so do not fund an
709            // HTLC that is about to expire. The margin is small because LDK's
710            // default invoices leave only 3 blocks before the claim deadline.
711            if blocks_to_claim_deadline < LNV2_CLAIM_DEADLINE_MARGIN {
712                return Err(RelayIncomingHtlcError::ClaimDeadlineTooClose {
713                    blocks_to_claim_deadline,
714                });
715            }
716            self.ensure_federation_responsive(payment_hash).await?;
717
718            // Only a fresh receive funds an incoming contract, so only it is
719            // subject to the operator's receive policy. `AddCompletion` joins a
720            // receive operation that already exists, and dropping it would
721            // strand a contract the gateway has already funded. The guard is
722            // held until the funding write below has happened.
723            let _policy_guard = self
724                .gateway
725                .begin_fresh_receive(&self.federation_id)
726                .await
727                .ok_or(RelayIncomingHtlcError::ReceiveDisabled {
728                    federation_id: self.federation_id,
729                })?;
730
731            let refund_keypair = self.keypair;
732            let client_output = ClientOutput::<LightningOutput> {
733                output: LightningOutput::V0(LightningOutputV0::Incoming(contract.clone())),
734                amounts: Amounts::new_bitcoin(contract.commitment.amount),
735            };
736            let client_output_sm = ClientOutputSM::<GatewayClientStateMachinesV2> {
737                state_machines: Arc::new(move |range: OutPointRange| {
738                    assert_eq!(range.count(), 1);
739
740                    vec![GatewayClientStateMachinesV2::Receive(ReceiveStateMachine {
741                        common: ReceiveSMCommon {
742                            operation_id: receive_operation_id,
743                            contract: contract.clone(),
744                            outpoint: range.into_iter().next().unwrap(),
745                            refund_keypair,
746                        },
747                        state: ReceiveSMState::Funding,
748                    })]
749                }),
750            };
751
752            let client_output = self.client_ctx.make_client_outputs(ClientOutputBundle::new(
753                vec![client_output],
754                vec![client_output_sm],
755            ));
756            let transaction = TransactionBuilder::new(Account::Primary).with_outputs(client_output);
757
758            let creation_result = self
759                .client_ctx
760                .finalize_and_submit_transaction_with_events(
761                    receive_operation_id,
762                    LightningCommonInit::KIND.as_str(),
763                    |_| GatewayOperationMetaV2::role(GatewayOperationRoleV2::Receive),
764                    transaction,
765                    vec![self.client_ctx.make_event(IncomingPaymentStarted {
766                        operation_start,
767                        incoming_contract_commitment: commitment,
768                        invoice_amount: Amount::from_msats(amount_msat),
769                    })],
770                )
771                .await;
772            if let Err(error) = creation_result {
773                let operation_exists = self.client_ctx.operation_exists(receive_operation_id).await;
774                if operation_creation_failed_permanently(true, operation_exists) {
775                    return Err(error.into());
776                }
777            }
778        }
779
780        let completion =
781            GatewayClientStateMachinesV2::CircuitComplete(CircuitCompleteStateMachine {
782                common: CircuitCompleteSMCommon {
783                    operation_id: completion_operation_id,
784                    receive_operation_id,
785                    payment_hash,
786                    circuit,
787                },
788                state: CompleteSMState::Pending,
789            });
790        let creation_result = self
791            .client_ctx
792            .manual_operation_start(
793                completion_operation_id,
794                Account::Primary,
795                LightningCommonInit::KIND.as_str(),
796                GatewayOperationMetaV2::role(GatewayOperationRoleV2::CircuitCompletion),
797                vec![self.client_ctx.make_dyn_state(completion)],
798            )
799            .await;
800        if let Err(error) = creation_result {
801            let operation_exists = self
802                .client_ctx
803                .operation_exists(completion_operation_id)
804                .await;
805            if operation_creation_failed_permanently(true, operation_exists) {
806                return Err(error.into());
807            }
808        }
809
810        Ok(())
811    }
812
813    /// Funds the incoming contract of a direct swap and waits for its final
814    /// state.
815    ///
816    /// A swap that was already started resumes unconditionally: its operation
817    /// is keyed on the contract, so a re-entrant call — a restarted state
818    /// machine, or a concurrent payer — joins the operation in progress
819    /// instead of funding twice. `allow_fresh_dispatch` is consulted only
820    /// when no such operation exists: callers pass `false` when a wall-clock
821    /// gate such as invoice expiry forbids starting a new swap, and receive
822    /// `Ok(None)` to signal that nothing was started.
823    ///
824    /// # Errors
825    ///
826    /// Fails with [`RelayDirectSwapError::ReceiveDisabled`] if the operator
827    /// has disabled receives, and [`RelayDirectSwapError::Transaction`] if
828    /// the funding transaction of a fresh swap could not be submitted.
829    pub async fn relay_direct_swap(
830        &self,
831        contract: IncomingContract,
832        amount_msat: u64,
833        allow_fresh_dispatch: bool,
834    ) -> Result<Option<FinalReceiveState>, RelayDirectSwapError> {
835        let operation_start = now();
836
837        let operation_id = OperationId::from_encodable(&contract);
838
839        if self.client_ctx.operation_exists(operation_id).await {
840            return Ok(Some(self.await_receive(operation_id).await));
841        }
842
843        if !allow_fresh_dispatch {
844            return Ok(None);
845        }
846
847        // A swap funds an incoming contract in this federation, so it is
848        // admitted only while receives are on. That happens below the resume
849        // path: a swap already funded must still be joined, or the gateway
850        // forfeits the payer's contract after having paid the recipient.
851        let policy_guard = self
852            .gateway
853            .begin_fresh_receive(&self.federation_id)
854            .await
855            .ok_or(RelayDirectSwapError::ReceiveDisabled {
856                federation_id: self.federation_id,
857            })?;
858
859        let refund_keypair = self.keypair;
860
861        let client_output = ClientOutput::<LightningOutput> {
862            output: LightningOutput::V0(LightningOutputV0::Incoming(contract.clone())),
863            amounts: Amounts::new_bitcoin(contract.commitment.amount),
864        };
865        let commitment = contract.commitment.clone();
866        let client_output_sm = ClientOutputSM::<GatewayClientStateMachinesV2> {
867            state_machines: Arc::new(move |range| {
868                assert_eq!(range.count(), 1);
869
870                vec![GatewayClientStateMachinesV2::Receive(ReceiveStateMachine {
871                    common: ReceiveSMCommon {
872                        operation_id,
873                        contract: contract.clone(),
874                        outpoint: range.into_iter().next().unwrap(),
875                        refund_keypair,
876                    },
877                    state: ReceiveSMState::Funding,
878                })]
879            }),
880        };
881
882        let client_output = self.client_ctx.make_client_outputs(ClientOutputBundle::new(
883            vec![client_output],
884            vec![client_output_sm],
885        ));
886
887        let transaction = TransactionBuilder::new(Account::Primary).with_outputs(client_output);
888
889        self.client_ctx
890            .finalize_and_submit_transaction_with_events(
891                operation_id,
892                LightningCommonInit::KIND.as_str(),
893                |_| GatewayOperationMetaV2::role(GatewayOperationRoleV2::Receive),
894                transaction,
895                vec![self.client_ctx.make_event(IncomingPaymentStarted {
896                    operation_start,
897                    incoming_contract_commitment: commitment,
898                    invoice_amount: Amount::from_msats(amount_msat),
899                })],
900            )
901            .await?;
902
903        // The operation exists, so the policy may change again: what follows
904        // waits for the swap to finish and must not block an operator.
905        drop(policy_guard);
906
907        Ok(Some(self.await_receive(operation_id).await))
908    }
909
910    pub async fn await_receive(&self, operation_id: OperationId) -> FinalReceiveState {
911        let mut stream = self.notifier.subscribe(operation_id).await;
912
913        loop {
914            if let Some(GatewayClientStateMachinesV2::Receive(state)) = stream.next().await {
915                match state.state {
916                    ReceiveSMState::Funding => {}
917                    ReceiveSMState::Rejected(..) => return FinalReceiveState::Rejected,
918                    ReceiveSMState::Success(preimage) => {
919                        return FinalReceiveState::Success(preimage);
920                    }
921                    ReceiveSMState::Refunding(out_points) => {
922                        if self
923                            .client_ctx
924                            .await_primary_module_outputs(operation_id, out_points)
925                            .await
926                            .is_err()
927                        {
928                            return FinalReceiveState::Failure;
929                        }
930
931                        return FinalReceiveState::Refunded;
932                    }
933                    ReceiveSMState::Failure => return FinalReceiveState::Failure,
934                }
935            }
936        }
937    }
938
939    /// Waits for a legacy combined receive operation or a circuit-completion
940    /// operation to finish.
941    ///
942    /// `operation_id` must identify either a legacy operation containing
943    /// [`GatewayClientStateMachinesV2::Complete`] or a role-specific operation
944    /// containing [`GatewayClientStateMachinesV2::CircuitComplete`]. Both
945    /// successful completion and a durable permanent outcome conflict terminate
946    /// the wait.
947    pub async fn await_completion(&self, operation_id: OperationId) {
948        let mut stream = self.notifier.subscribe(operation_id).await;
949
950        loop {
951            match stream.next().await {
952                Some(GatewayClientStateMachinesV2::Complete(state)) => {
953                    if matches!(
954                        state.state,
955                        CompleteSMState::Completed | CompleteSMState::CompletionFailed(_)
956                    ) {
957                        info!(%state, "LNv2 completion state machine finished");
958                        return;
959                    }
960
961                    info!(%state, "Waiting for LNv2 completion state machine");
962                }
963                Some(GatewayClientStateMachinesV2::Receive(state)) => {
964                    info!(%state, "Waiting for LNv2 completion state machine");
965                    continue;
966                }
967                Some(GatewayClientStateMachinesV2::CircuitComplete(state)) => {
968                    if matches!(
969                        state.state,
970                        CompleteSMState::Completed | CompleteSMState::CompletionFailed(_)
971                    ) {
972                        info!(%state, "LNv2 circuit completion state machine finished");
973                        return;
974                    }
975
976                    info!(%state, "Waiting for LNv2 circuit completion state machine");
977                }
978                Some(state) => {
979                    warn!(%state, "Operation is not an LNv2 completion state machine");
980                    return;
981                }
982                None => return,
983            }
984        }
985    }
986}
987
988/// A refusal to pay an invoice for an LNv2 client.
989///
990/// These are the checks the gateway makes before it starts paying. A payment
991/// that starts and is later cancelled is not a failure: it is reported as the
992/// forfeit signature in the `Ok` value.
993#[derive(Debug, Error)]
994#[non_exhaustive]
995pub enum GatewaySendPaymentError {
996    /// The gateway is not connected to its lightning node, so a new send
997    /// would sit waiting for it.
998    #[error("The gateway is not connected to its lightning node")]
999    LightningNotConnected,
1000
1001    /// The outgoing contract names another gateway's key, so this gateway
1002    /// could never claim it.
1003    #[error("The outgoing contract is keyed to another gateway")]
1004    NotOurContract,
1005
1006    /// The request's signature over the invoice does not verify against the
1007    /// contract's refund key.
1008    #[error("Invalid auth signature for the invoice data")]
1009    InvalidAuthSignature,
1010
1011    /// The federation could not be asked about the outgoing contract.
1012    #[error("The gateway can not reach the federation")]
1013    Federation(#[source] Box<FederationError>),
1014
1015    /// The federation has not confirmed the outgoing contract yet.
1016    #[error("The outgoing contract has not yet been confirmed")]
1017    ContractNotConfirmed,
1018
1019    /// The contract the federation confirmed at the request's outpoint is not
1020    /// the one in the request.
1021    #[error("Contract Id returned by the federation does not match contract in request")]
1022    ContractIdMismatch,
1023
1024    /// The invoice carries no amount.
1025    #[error("Invoice is missing amount")]
1026    MissingInvoiceAmount,
1027
1028    /// The invoice's payment hash is not the one the contract is locked to.
1029    #[error("The invoices payment hash does not match the contracts payment hash")]
1030    PaymentHashMismatch,
1031
1032    /// The gateway could not work out the smallest contract amount it accepts
1033    /// for this payment.
1034    #[error("The minimum contract amount could not be computed")]
1035    MinContractAmount(#[source] GatewayClientV2Error),
1036
1037    /// Another operation already claimed the contract's payment image, so this
1038    /// gateway will never pay it out for this contract.
1039    #[error("Another contract for this payment image was already accepted")]
1040    PaymentImageAlreadyClaimed,
1041}
1042
1043/// Why the gateway did not relay an intercepted LNv2 HTLC.
1044#[derive(Debug, Error)]
1045pub enum RelayIncomingHtlcError {
1046    /// The federation liveness probe failed, so a fresh incoming contract is
1047    /// not funded.
1048    #[error("The federation did not answer the liveness probe")]
1049    FederationUnreachable(#[source] Box<FederationError>),
1050
1051    /// The federation liveness probe did not complete in time, so a fresh
1052    /// incoming contract is not funded.
1053    #[error("The federation did not answer the liveness probe within {timeout_secs}s")]
1054    FederationTimeout {
1055        /// How long the probe waited.
1056        timeout_secs: u64,
1057    },
1058
1059    /// The operator has disabled receives for this federation, so no fresh
1060    /// incoming contract is funded.
1061    #[error("Receiving payments is disabled for federation {federation_id}")]
1062    ReceiveDisabled {
1063        /// The federation the payment was refused for.
1064        federation_id: FederationId,
1065    },
1066
1067    /// The HTLC's claim deadline is too close to fund a fresh incoming
1068    /// contract and still settle the HTLC in time.
1069    #[error("HTLC claim deadline is only {blocks_to_claim_deadline} blocks away")]
1070    ClaimDeadlineTooClose {
1071        /// Blocks left until the HTLC's claim deadline.
1072        blocks_to_claim_deadline: u32,
1073    },
1074
1075    /// The funding transaction or the completion operation could not be
1076    /// started.
1077    #[error("The incoming contract could not be funded")]
1078    Transaction(#[from] TransactionSubmitError),
1079}
1080
1081/// A failure to fund the incoming contract of a direct swap.
1082#[derive(Debug, Error)]
1083#[non_exhaustive]
1084pub enum RelayDirectSwapError {
1085    /// The operator has disabled receives for this federation, so no fresh
1086    /// swap is funded.
1087    #[error("Receiving payments is disabled for federation {federation_id}")]
1088    ReceiveDisabled {
1089        /// The federation the swap was refused for.
1090        federation_id: FederationId,
1091    },
1092
1093    /// The funding transaction could not be submitted.
1094    #[error("The incoming contract could not be funded")]
1095    Transaction(#[from] TransactionSubmitError),
1096}
1097
1098impl From<FederationError> for GatewaySendPaymentError {
1099    fn from(source: FederationError) -> Self {
1100        Self::Federation(Box::new(source))
1101    }
1102}
1103
1104/// An interface between module implementation and the general `Gateway`
1105///
1106/// To abstract away and decouple the core gateway from the modules, the
1107/// interface between the is expressed as a trait. The core gateway handles
1108/// LNv2 operations that require access to the database or lightning node.
1109#[async_trait]
1110pub trait IGatewayClientV2: Debug + Send + Sync {
1111    /// Uses the gateway's Lightning node to complete a payment.
1112    ///
1113    /// Implementations must absorb and retry every transient node or
1114    /// connectivity failure. They return `Err` only when Lightning has reached
1115    /// a permanent state that makes the requested outcome impossible. The
1116    /// future may block while retrying and must remain cancellation-safe.
1117    /// Completion state machines persist any returned error as terminal
1118    /// `CompletionFailed`.
1119    async fn complete_htlc(
1120        &self,
1121        htlc_response: InterceptPaymentResponse,
1122    ) -> Result<(), LightningRpcError>;
1123
1124    /// Determines if the payment can be completed using a direct swap to
1125    /// another federation.
1126    ///
1127    /// A direct swap is determined by checking the gateway's connected
1128    /// lightning node against the invoice's payee lightning node. If they
1129    /// are the same, then the gateway can use another client to complete
1130    /// the payment be swapping ecash instead of a payment over the
1131    /// Lightning network.
1132    ///
1133    /// # Errors
1134    ///
1135    /// Fails with a [`GatewayClientV2Error`] if the invoice is payable by a
1136    /// direct swap but the gateway holds no incoming contract it can use for
1137    /// it. The send state machine cancels the payment on a failure.
1138    async fn is_direct_swap(
1139        &self,
1140        invoice: &Bolt11Invoice,
1141    ) -> Result<Option<(IncomingContract, ClientHandleArc)>, GatewayClientV2Error>;
1142
1143    /// Initiates a payment over the Lightning network.
1144    async fn pay(
1145        &self,
1146        invoice: Bolt11Invoice,
1147        max_delay: u64,
1148        max_fee: Amount,
1149    ) -> Result<[u8; 32], LightningRpcError>;
1150
1151    /// Returns whether the gateway's Lightning node has any record of an
1152    /// outbound payment for `payment_hash`, whatever its state.
1153    ///
1154    /// The send state machine consults this when it resumes after a restart:
1155    /// a payment the node already knows was dispatched before the crash and
1156    /// must be resolved through [`IGatewayClientV2::pay`]'s idempotent resume
1157    /// path rather than cancelled by pre-dispatch checks. A wrong `false`
1158    /// forfeits a contract whose payment may still settle, so implementations
1159    /// must absorb transient node failures and only answer once the node's
1160    /// payment store could actually be consulted.
1161    async fn outbound_payment_exists(&self, payment_hash: sha256::Hash) -> bool;
1162
1163    /// Admits a fresh incoming payment for the clients of `federation_id` when
1164    /// the operator's receive policy allows one, or answers `None` when
1165    /// receives are disabled.
1166    ///
1167    /// The returned guard must be held until the funding operation exists, so
1168    /// a payment admitted here always funds and none is admitted once
1169    /// disabling has returned. Work already funded must finish regardless, or
1170    /// the gateway abandons a contract it has paid for.
1171    async fn begin_fresh_receive(
1172        &self,
1173        federation_id: &FederationId,
1174    ) -> Option<fedimint_gateway_common::PaymentPolicyGuard>;
1175
1176    /// Computes the minimum contract amount necessary for making an outgoing
1177    /// payment.
1178    ///
1179    /// The minimum contract amount must contain transaction fees to cover the
1180    /// gateway's transaction fee and optionally additional fee to cover the
1181    /// gateway's Lightning fee if the payment goes over the Lightning
1182    /// network.
1183    ///
1184    /// # Errors
1185    ///
1186    /// Fails with a [`GatewayClientV2Error`] if the gateway cannot price a
1187    /// payment for this federation.
1188    async fn min_contract_amount(
1189        &self,
1190        federation_id: &FederationId,
1191        amount: u64,
1192    ) -> Result<Amount, GatewayClientV2Error>;
1193
1194    /// Check if this invoice was created using LNv1 and if the gateway is
1195    /// connected to the target federation.
1196    async fn is_lnv1_invoice(&self, invoice: &Bolt11Invoice) -> Option<Spanned<ClientHandleArc>>;
1197
1198    /// Perform a swap from an LNv2 `OutgoingContract` to an LNv1
1199    /// `IncomingContract`.
1200    ///
1201    /// A swap that was already started resumes unconditionally;
1202    /// `allow_fresh_dispatch` is consulted only when no operation for this
1203    /// swap exists yet. Callers pass `false` when a wall-clock gate such as
1204    /// invoice expiry forbids starting a new swap, and receive `Ok(None)` to
1205    /// signal that nothing was started.
1206    ///
1207    /// # Errors
1208    ///
1209    /// Fails with a [`GatewayClientV2Error`] if the swap could not be started
1210    /// or followed. The send state machine cancels the payment on a failure.
1211    async fn relay_lnv1_swap(
1212        &self,
1213        client: &ClientHandleArc,
1214        invoice: &Bolt11Invoice,
1215        allow_fresh_dispatch: bool,
1216    ) -> Result<Option<FinalReceiveState>, GatewayClientV2Error>;
1217
1218    /// Claims the given payment image for `operation_id` in the gateway's
1219    /// global database, returning `true` if this operation may claim the
1220    /// outgoing contract (the image was unclaimed, or already claimed by
1221    /// this same operation) and `false` if another operation already
1222    /// claimed it.
1223    ///
1224    /// A single Lightning payment yields a single preimage, so the gateway may
1225    /// claim at most one outgoing contract per payment image. Unlike the
1226    /// per-federation module database, this spans all of the gateway's
1227    /// federations, so two clients in different federations paying the same
1228    /// invoice cannot both be claimed.
1229    async fn claim_payment_image(
1230        &self,
1231        payment_image: &PaymentImage,
1232        operation_id: OperationId,
1233    ) -> bool;
1234
1235    /// Returns whether the gateway currently holds a connection to its
1236    /// lightning node. Only suitable for refusing new work: the answer is
1237    /// local, so it must not decide the fate of a payment already started.
1238    async fn is_lightning_connected(&self) -> bool;
1239
1240    /// Waits until the gateway holds a connection to its lightning node.
1241    async fn await_lightning_connected(&self);
1242}
1243
1244/// A failure reported by the gateway behind [`IGatewayClientV2`].
1245///
1246/// The trait is implemented by the gateway, not by this module, so the causes
1247/// are the gateway's own. This type carries them unchanged: its `Display` and
1248/// its `source()` are the cause's.
1249#[derive(Debug, Error)]
1250#[error(transparent)]
1251pub struct GatewayClientV2Error(Box<dyn std::error::Error + Send + Sync>);
1252
1253impl GatewayClientV2Error {
1254    /// Wraps a failure of the gateway's [`IGatewayClientV2`] implementation,
1255    /// which may be any error value or a plain message.
1256    pub fn new<E>(source: E) -> Self
1257    where
1258        E: Into<Box<dyn std::error::Error + Send + Sync>>,
1259    {
1260        Self(source.into())
1261    }
1262}
1263
1264#[cfg(test)]
1265mod tests;