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
69const FEDERATION_LIVENESS_TIMEOUT: Duration = Duration::from_secs(10);
73
74const LNV2_CLAIM_DEADLINE_MARGIN: u32 = 2;
77
78pub 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#[derive(Debug, Clone, Serialize, Deserialize)]
150#[serde(untagged)]
151pub enum GatewayOperationMetaV2 {
152 Legacy(()),
154 Role {
156 role: GatewayOperationRoleV2,
158 },
159}
160
161#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
163#[serde(rename_all = "snake_case")]
164pub enum GatewayOperationRoleV2 {
165 Send,
167 Receive,
169 CircuitCompletion,
171}
172
173impl GatewayOperationMetaV2 {
174 pub fn role(role: GatewayOperationRoleV2) -> Self {
176 Self::Role { role }
177 }
178
179 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 Complete(CompleteStateMachine),
307 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 pub async fn send_payment(
411 &self,
412 payload: SendPaymentPayload,
413 ) -> Result<Result<[u8; 32], Signature>, GatewaySendPaymentError> {
414 let operation_start = now();
415
416 let operation_id = OperationId::from_encodable(&payload.contract.clone());
422
423 if payload.contract.claim_pk != self.keypair.public_key() {
427 return Err(GatewaySendPaymentError::NotOurContract);
428 }
429
430 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 if self.client_ctx.operation_exists(operation_id).await {
446 return Ok(self.subscribe_send(operation_id).await);
447 }
448
449 if !self.gateway.is_lightning_connected().await {
455 return Err(GatewaySendPaymentError::LightningNotConnected);
456 }
457
458 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 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 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 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 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 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 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 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 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 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 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 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 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#[derive(Debug, Error)]
994#[non_exhaustive]
995pub enum GatewaySendPaymentError {
996 #[error("The gateway is not connected to its lightning node")]
999 LightningNotConnected,
1000
1001 #[error("The outgoing contract is keyed to another gateway")]
1004 NotOurContract,
1005
1006 #[error("Invalid auth signature for the invoice data")]
1009 InvalidAuthSignature,
1010
1011 #[error("The gateway can not reach the federation")]
1013 Federation(#[source] Box<FederationError>),
1014
1015 #[error("The outgoing contract has not yet been confirmed")]
1017 ContractNotConfirmed,
1018
1019 #[error("Contract Id returned by the federation does not match contract in request")]
1022 ContractIdMismatch,
1023
1024 #[error("Invoice is missing amount")]
1026 MissingInvoiceAmount,
1027
1028 #[error("The invoices payment hash does not match the contracts payment hash")]
1030 PaymentHashMismatch,
1031
1032 #[error("The minimum contract amount could not be computed")]
1035 MinContractAmount(#[source] GatewayClientV2Error),
1036
1037 #[error("Another contract for this payment image was already accepted")]
1040 PaymentImageAlreadyClaimed,
1041}
1042
1043#[derive(Debug, Error)]
1045pub enum RelayIncomingHtlcError {
1046 #[error("The federation did not answer the liveness probe")]
1049 FederationUnreachable(#[source] Box<FederationError>),
1050
1051 #[error("The federation did not answer the liveness probe within {timeout_secs}s")]
1054 FederationTimeout {
1055 timeout_secs: u64,
1057 },
1058
1059 #[error("Receiving payments is disabled for federation {federation_id}")]
1062 ReceiveDisabled {
1063 federation_id: FederationId,
1065 },
1066
1067 #[error("HTLC claim deadline is only {blocks_to_claim_deadline} blocks away")]
1070 ClaimDeadlineTooClose {
1071 blocks_to_claim_deadline: u32,
1073 },
1074
1075 #[error("The incoming contract could not be funded")]
1078 Transaction(#[from] TransactionSubmitError),
1079}
1080
1081#[derive(Debug, Error)]
1083#[non_exhaustive]
1084pub enum RelayDirectSwapError {
1085 #[error("Receiving payments is disabled for federation {federation_id}")]
1088 ReceiveDisabled {
1089 federation_id: FederationId,
1091 },
1092
1093 #[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#[async_trait]
1110pub trait IGatewayClientV2: Debug + Send + Sync {
1111 async fn complete_htlc(
1120 &self,
1121 htlc_response: InterceptPaymentResponse,
1122 ) -> Result<(), LightningRpcError>;
1123
1124 async fn is_direct_swap(
1139 &self,
1140 invoice: &Bolt11Invoice,
1141 ) -> Result<Option<(IncomingContract, ClientHandleArc)>, GatewayClientV2Error>;
1142
1143 async fn pay(
1145 &self,
1146 invoice: Bolt11Invoice,
1147 max_delay: u64,
1148 max_fee: Amount,
1149 ) -> Result<[u8; 32], LightningRpcError>;
1150
1151 async fn outbound_payment_exists(&self, payment_hash: sha256::Hash) -> bool;
1162
1163 async fn begin_fresh_receive(
1172 &self,
1173 federation_id: &FederationId,
1174 ) -> Option<fedimint_gateway_common::PaymentPolicyGuard>;
1175
1176 async fn min_contract_amount(
1189 &self,
1190 federation_id: &FederationId,
1191 amount: u64,
1192 ) -> Result<Amount, GatewayClientV2Error>;
1193
1194 async fn is_lnv1_invoice(&self, invoice: &Bolt11Invoice) -> Option<Spanned<ClientHandleArc>>;
1197
1198 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 async fn claim_payment_image(
1230 &self,
1231 payment_image: &PaymentImage,
1232 operation_id: OperationId,
1233 ) -> bool;
1234
1235 async fn is_lightning_connected(&self) -> bool;
1239
1240 async fn await_lightning_connected(&self);
1242}
1243
1244#[derive(Debug, Error)]
1250#[error(transparent)]
1251pub struct GatewayClientV2Error(Box<dyn std::error::Error + Send + Sync>);
1252
1253impl GatewayClientV2Error {
1254 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;