Skip to main content

fedimint_mint_client/
output.rs

1use std::collections::BTreeMap;
2use std::future::ready;
3use std::hash;
4use std::time::Duration;
5
6use assert_matches::assert_matches;
7use fedimint_api_client::api::{
8    FederationApiExt, SerdeOutputOutcome, ServerError,
9    VERSION_THAT_INTRODUCED_AWAIT_OUTPUTS_OUTCOMES, deserialize_outcome,
10};
11use fedimint_api_client::query::FilterMapThreshold;
12use fedimint_client_module::DynGlobalClientContext;
13use fedimint_client_module::module::{ClientContext, OutPointRange};
14use fedimint_client_module::sm::{ClientSMDatabaseTransaction, State, StateTransition};
15use fedimint_core::core::{Decoder, OperationId};
16use fedimint_core::db::IDatabaseTransactionOpsCoreTyped;
17use fedimint_core::encoding::{Decodable, Encodable};
18use fedimint_core::endpoint_constants::AWAIT_OUTPUTS_OUTCOMES_ENDPOINT;
19use fedimint_core::module::ApiRequestErased;
20use fedimint_core::secp256k1::{Keypair, Secp256k1, Signing};
21use fedimint_core::util::FmtCompact as _;
22use fedimint_core::util::backoff_util::custom_backoff;
23use fedimint_core::{Amount, NumPeersExt, OutPoint, PeerId, Tiered, TransactionId, crit};
24use fedimint_derive_secret::{ChildId, DerivableSecret};
25use fedimint_logging::LOG_CLIENT_MODULE_MINT;
26use fedimint_mint_common::endpoint_constants::AWAIT_OUTPUT_OUTCOME_ENDPOINT;
27use fedimint_mint_common::{BlindNonce, MintOutputOutcome, Nonce};
28use futures::future::join_all;
29use rayon::iter::{IndexedParallelIterator, IntoParallelIterator as _, ParallelIterator as _};
30use serde::{Deserialize, Serialize};
31use tbs::{
32    AggregatePublicKey, BlindedMessage, BlindedSignature, BlindedSignatureShare, BlindingKey,
33    PublicKeyShare, aggregate_signature_shares, blind_message, unblind_signature,
34};
35use tracing::{debug, warn};
36
37use crate::api::MintFederationApi as _;
38use crate::client_db::NoteKey;
39use crate::error::VerifyBlindShareError;
40use crate::events::{NoteCreated, ReceivePaymentStatus, ReceivePaymentUpdateEvent};
41use crate::{MintClientContext, MintClientModule, SpendableNote};
42
43/// Child ID used to derive the spend key from a note's [`DerivableSecret`]
44const SPEND_KEY_CHILD_ID: ChildId = ChildId(0);
45
46/// Child ID used to derive the blinding key from a note's [`DerivableSecret`]
47const BLINDING_KEY_CHILD_ID: ChildId = ChildId(1);
48
49/// State machine managing the e-cash issuance process related to a mint output.
50///
51/// ```mermaid
52/// graph LR
53///     classDef virtual fill:#fff,stroke-dasharray: 5 5
54///
55///     Created -- containing tx rejected --> Aborted
56///     Created -- tx accepted, await output outcome --> Outcome["Outcome Received"]:::virtual
57///     subgraph Await Outcome
58///     Outcome -- valid blind signatures  --> Succeeded
59///     Outcome -- invalid blind signatures  --> Failed
60///     end
61/// ```
62#[derive(Debug, Clone, Eq, PartialEq, Hash, Decodable, Encodable)]
63pub enum MintOutputStates {
64    /// Issuance request was created, we are waiting for blind signatures
65    Created(MintOutputStatesCreated),
66    /// The transaction containing the issuance was rejected, we can stop
67    /// looking for decryption shares
68    Aborted(MintOutputStatesAborted),
69    // FIXME: handle offline federation failure mode more gracefully
70    /// The transaction containing the issuance was accepted but an unexpected
71    /// error occurred, this should never happen with a honest federation and
72    /// bug-free code.
73    Failed(MintOutputStatesFailed),
74    /// The issuance was completed successfully and the e-cash notes added to
75    /// our wallet
76    Succeeded(MintOutputStatesSucceeded),
77    /// Issuance request was created, we are waiting for blind signatures
78    CreatedMulti(MintOutputStatesCreatedMulti),
79}
80
81#[derive(Debug, Clone, Eq, PartialEq, Hash, Decodable, Encodable)]
82pub struct MintOutputCommonV0 {
83    pub(crate) operation_id: OperationId,
84    pub(crate) out_point: OutPoint,
85}
86
87#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Decodable, Encodable)]
88pub struct MintOutputCommon {
89    pub(crate) operation_id: OperationId,
90    pub(crate) out_point_range: OutPointRange,
91}
92
93impl MintOutputCommon {
94    pub fn txid(self) -> TransactionId {
95        self.out_point_range.txid()
96    }
97}
98
99#[derive(Debug, Clone, Eq, PartialEq, Hash, Decodable, Encodable)]
100pub struct MintOutputStateMachineV0 {
101    pub(crate) common: MintOutputCommonV0,
102    pub(crate) state: MintOutputStates,
103}
104
105#[derive(Debug, Clone, Eq, PartialEq, Hash, Decodable, Encodable)]
106pub struct MintOutputStateMachine {
107    pub(crate) common: MintOutputCommon,
108    pub(crate) state: MintOutputStates,
109}
110
111impl MintOutputStateMachine {
112    /// Transaction ID this output belongs to
113    pub fn txid(&self) -> TransactionId {
114        self.common.out_point_range.txid()
115    }
116
117    /// Returns `(out_idx, amount, nonce, blind_nonce)` for each note being
118    /// created.
119    ///
120    /// Only available when the state machine is in a `Created` or
121    /// `CreatedMulti` state (i.e. before the blind signature is finalized).
122    /// Returns an empty vec for terminal states.
123    pub fn created_nonces(&self) -> Vec<(u64, Amount, Nonce, BlindNonce)> {
124        match &self.state {
125            MintOutputStates::Created(c) => {
126                vec![(
127                    self.common.out_point_range.start_idx(),
128                    c.amount,
129                    c.issuance_request.nonce(),
130                    BlindNonce(c.issuance_request.blinded_message()),
131                )]
132            }
133            MintOutputStates::CreatedMulti(c) => c
134                .issuance_requests
135                .iter()
136                .map(|(idx, (amount, req))| {
137                    (
138                        *idx,
139                        *amount,
140                        req.nonce(),
141                        BlindNonce(req.blinded_message()),
142                    )
143                })
144                .collect(),
145            _ => vec![],
146        }
147    }
148}
149
150impl State for MintOutputStateMachine {
151    type ModuleContext = MintClientContext;
152
153    fn transitions(
154        &self,
155        context: &Self::ModuleContext,
156        global_context: &DynGlobalClientContext,
157    ) -> Vec<StateTransition<Self>> {
158        match &self.state {
159            MintOutputStates::Created(created) => {
160                created.transitions(context, global_context, self.common)
161            }
162            MintOutputStates::CreatedMulti(created) => {
163                created.transitions(context, global_context, self.common)
164            }
165            MintOutputStates::Aborted(_)
166            | MintOutputStates::Failed(_)
167            | MintOutputStates::Succeeded(_) => {
168                vec![]
169            }
170        }
171    }
172
173    fn operation_id(&self) -> OperationId {
174        self.common.operation_id
175    }
176
177    fn fmt_visualization(&self, f: &mut dyn std::fmt::Write, indent: &str) -> std::fmt::Result {
178        let txid = self.common.out_point_range.txid();
179        let start = self.common.out_point_range.start_idx();
180        let count = self.common.out_point_range.count();
181        match &self.state {
182            MintOutputStates::Created(c) => {
183                let nonce = c.issuance_request.nonce();
184                let blind_nonce = BlindNonce(c.issuance_request.blinded_message());
185                write!(
186                    f,
187                    "{indent}MintOutputStateMachine\n\
188                     {indent}  state: Created  tx={}:[{start},{end})\n\
189                     {indent}  note: amount={}  nonce={}  blind_nonce={}",
190                    txid.fmt_short(),
191                    c.amount,
192                    nonce.fmt_short(),
193                    blind_nonce.fmt_short(),
194                    end = start + count as u64,
195                )
196            }
197            MintOutputStates::CreatedMulti(c) => {
198                let total: Amount = c.issuance_requests.values().map(|(a, _)| *a).sum();
199                write!(
200                    f,
201                    "{indent}MintOutputStateMachine\n\
202                     {indent}  state: CreatedMulti  tx={}:[{start},{end})  {} notes, total={total}",
203                    txid.fmt_short(),
204                    c.issuance_requests.len(),
205                    end = start + count as u64,
206                )?;
207                for (idx, (amount, req)) in &c.issuance_requests {
208                    let nonce = req.nonce();
209                    let blind_nonce = BlindNonce(req.blinded_message());
210                    write!(
211                        f,
212                        "\n{indent}  [{idx}] amount={amount}  nonce={}  blind_nonce={}",
213                        nonce.fmt_short(),
214                        blind_nonce.fmt_short(),
215                    )?;
216                }
217                Ok(())
218            }
219            MintOutputStates::Succeeded(s) => {
220                write!(
221                    f,
222                    "{indent}MintOutputStateMachine\n{indent}  state: Succeeded  amount={}",
223                    s.amount,
224                )
225            }
226            MintOutputStates::Aborted(_) => {
227                write!(
228                    f,
229                    "{indent}MintOutputStateMachine\n{indent}  state: Aborted  tx={}",
230                    txid.fmt_short(),
231                )
232            }
233            MintOutputStates::Failed(fail) => {
234                write!(
235                    f,
236                    "{indent}MintOutputStateMachine\n{indent}  state: Failed  error={}",
237                    fail.error,
238                )
239            }
240        }
241    }
242}
243
244/// See [`MintOutputStates`]
245#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Decodable, Encodable)]
246pub struct MintOutputStatesCreated {
247    pub(crate) amount: Amount,
248    pub(crate) issuance_request: NoteIssuanceRequest,
249}
250
251impl MintOutputStatesCreated {
252    fn transitions(
253        &self,
254        // TODO: make cheaper to clone (Arc?)
255        context: &MintClientContext,
256        global_context: &DynGlobalClientContext,
257        common: MintOutputCommon,
258    ) -> Vec<StateTransition<MintOutputStateMachine>> {
259        let tbs_pks = context.tbs_pks.clone();
260        let client_ctx = context.client_ctx.clone();
261        let balance_update_sender = context.balance_update_sender.clone();
262
263        vec![
264            // Check if transaction was rejected
265            StateTransition::new(
266                Self::await_tx_rejected(global_context.clone(), common),
267                |_dbtx, (), state| Box::pin(async move { Self::transition_tx_rejected(&state) }),
268            ),
269            // Check for output outcome
270            StateTransition::new(
271                Self::await_outcome_ready(
272                    global_context.clone(),
273                    common,
274                    context.mint_decoder.clone(),
275                    self.amount,
276                    self.issuance_request.blinded_message(),
277                    context.peer_tbs_pks.clone(),
278                ),
279                move |dbtx, blinded_signature_shares, old_state| {
280                    Box::pin(Self::transition_outcome_ready(
281                        client_ctx.clone(),
282                        dbtx,
283                        blinded_signature_shares,
284                        old_state,
285                        tbs_pks.clone(),
286                        balance_update_sender.clone(),
287                    ))
288                },
289            ),
290        ]
291    }
292
293    async fn await_tx_rejected(global_context: DynGlobalClientContext, common: MintOutputCommon) {
294        let txid = common.txid();
295        debug!(target: LOG_CLIENT_MODULE_MINT, %txid, "Awaiting tx rejection");
296        let accept_fut = global_context.await_tx_accepted(common.txid());
297        tokio::pin!(accept_fut);
298        let result = tokio::select! {
299            result = &mut accept_fut => result,
300            () = fedimint_core::runtime::sleep(Duration::from_secs(300)) => {
301                warn!(
302                    target: LOG_CLIENT_MODULE_MINT,
303                    %txid,
304                    "Transaction not accepted or rejected after 5 minutes, possibly stuck or never submitted",
305                );
306                accept_fut.await
307            }
308        };
309        if result.is_err() {
310            return;
311        }
312        std::future::pending::<()>().await;
313    }
314
315    fn transition_tx_rejected(old_state: &MintOutputStateMachine) -> MintOutputStateMachine {
316        assert_matches!(old_state.state, MintOutputStates::Created(_));
317
318        MintOutputStateMachine {
319            common: old_state.common,
320            state: MintOutputStates::Aborted(MintOutputStatesAborted),
321        }
322    }
323
324    async fn await_outcome_ready(
325        global_context: DynGlobalClientContext,
326        common: MintOutputCommon,
327        module_decoder: Decoder,
328        amount: Amount,
329        message: BlindedMessage,
330        tbs_pks: BTreeMap<PeerId, Tiered<PublicKeyShare>>,
331    ) -> BTreeMap<PeerId, BlindedSignatureShare> {
332        let txid = common.txid();
333        let out_idx = common.out_point_range.start_idx();
334        await_tx_accepted_before_polling(&global_context, txid, BlindNonce(message)).await;
335        debug!(target: LOG_CLIENT_MODULE_MINT, %txid, %out_idx, "Awaiting output outcome");
336        global_context
337            .api()
338            .request_with_strategy_retry(
339                // this query collects a threshold of 2f + 1 valid blind signature shares
340                FilterMapThreshold::new(
341                    move |peer, outcome| {
342                        ready(
343                            verify_blind_share(
344                                peer,
345                                &outcome,
346                                amount,
347                                message,
348                                &module_decoder,
349                                &tbs_pks,
350                            )
351                            .map_err(|err| {
352                                ServerError::InvalidResponse(err.fmt_compact().to_string())
353                            }),
354                        )
355                    },
356                    global_context.api().all_peers().to_num_peers(),
357                ),
358                AWAIT_OUTPUT_OUTCOME_ENDPOINT.to_owned(),
359                ApiRequestErased::new(OutPoint {
360                    txid: common.txid(),
361                    out_idx: common.out_point_range.start_idx(),
362                }),
363            )
364            .await
365    }
366
367    async fn transition_outcome_ready(
368        client_ctx: ClientContext<MintClientModule>,
369        dbtx: &mut ClientSMDatabaseTransaction<'_, '_>,
370        blinded_signature_shares: BTreeMap<PeerId, BlindedSignatureShare>,
371        old_state: MintOutputStateMachine,
372        tbs_pks: Tiered<AggregatePublicKey>,
373        balance_update_sender: tokio::sync::watch::Sender<()>,
374    ) -> MintOutputStateMachine {
375        // we combine the shares, finalize the issuance request with the blind signature
376        // and store the resulting note in the database
377
378        let MintOutputStates::Created(created) = old_state.state else {
379            panic!("Unexpected prior state")
380        };
381
382        let agg_blind_signature = aggregate_signature_shares(
383            &blinded_signature_shares
384                .into_iter()
385                .map(|(peer, share)| (peer.to_usize() as u64, share))
386                .collect(),
387        );
388
389        let amount_key = tbs_pks
390            .tier(&created.amount)
391            .expect("We obtained this amount from tbs_pks when we created the output");
392
393        // this implies that the mint client config's public keys are inconsistent
394        if !tbs::verify_blinded_signature(
395            created.issuance_request.blinded_message(),
396            agg_blind_signature,
397            *amount_key,
398        ) {
399            return MintOutputStateMachine {
400                common: old_state.common,
401                state: MintOutputStates::Failed(MintOutputStatesFailed {
402                    error: "Invalid blind signature".to_string(),
403                }),
404            };
405        }
406
407        let spendable_note = created.issuance_request.finalize(agg_blind_signature);
408
409        assert!(spendable_note.note().verify(*amount_key));
410
411        debug!(target: LOG_CLIENT_MODULE_MINT, amount = %created.amount, note=%spendable_note, "Adding new note from transaction output");
412
413        client_ctx
414            .log_event(
415                &mut dbtx.module_tx(),
416                NoteCreated {
417                    nonce: spendable_note.nonce(),
418                },
419            )
420            .await;
421        if let Some(note) = dbtx
422            .module_tx()
423            .insert_entry(
424                &NoteKey {
425                    amount: created.amount,
426                    nonce: spendable_note.nonce(),
427                },
428                &spendable_note.to_undecoded(),
429            )
430            .await
431        {
432            crit!(target: LOG_CLIENT_MODULE_MINT, %note, "E-cash note was replaced in DB");
433        }
434
435        dbtx.module_tx()
436            .on_commit(move || balance_update_sender.send_replace(()));
437
438        MintOutputStateMachine {
439            common: old_state.common,
440            state: MintOutputStates::Succeeded(MintOutputStatesSucceeded {
441                amount: created.amount,
442            }),
443        }
444    }
445}
446
447/// See [`MintOutputStates`]
448#[derive(Debug, Clone, Eq, PartialEq, Hash, Decodable, Encodable)]
449pub struct MintOutputStatesCreatedMulti {
450    pub(crate) issuance_requests: BTreeMap<u64, (Amount, NoteIssuanceRequest)>,
451}
452
453impl MintOutputStatesCreatedMulti {
454    fn transitions(
455        &self,
456        // TODO: make cheaper to clone (Arc?)
457        context: &MintClientContext,
458        global_context: &DynGlobalClientContext,
459        common: MintOutputCommon,
460    ) -> Vec<StateTransition<MintOutputStateMachine>> {
461        let tbs_pks = context.tbs_pks.clone();
462        let client_ctx = context.client_ctx.clone();
463        let client_ctx_rejected = context.client_ctx.clone();
464        let balance_update_sender = context.balance_update_sender.clone();
465
466        vec![
467            // Check if transaction was rejected
468            StateTransition::new(
469                Self::await_tx_rejected(global_context.clone(), common),
470                move |dbtx, (), state| {
471                    Box::pin(Self::transition_tx_rejected(
472                        client_ctx_rejected.clone(),
473                        dbtx,
474                        state,
475                    ))
476                },
477            ),
478            // Check for output outcome
479            StateTransition::new(
480                Self::await_outcome_ready(
481                    global_context.clone(),
482                    common,
483                    context.mint_decoder.clone(),
484                    self.issuance_requests.clone(),
485                    context.peer_tbs_pks.clone(),
486                ),
487                move |dbtx, blinded_signature_shares, old_state| {
488                    Box::pin(Self::transition_outcome_ready(
489                        client_ctx.clone(),
490                        dbtx,
491                        blinded_signature_shares,
492                        old_state,
493                        tbs_pks.clone(),
494                        balance_update_sender.clone(),
495                    ))
496                },
497            ),
498        ]
499    }
500
501    async fn await_tx_rejected(global_context: DynGlobalClientContext, common: MintOutputCommon) {
502        let txid = common.txid();
503        debug!(target: LOG_CLIENT_MODULE_MINT, %txid, "Awaiting tx rejection");
504        let accept_fut = global_context.await_tx_accepted(common.txid());
505        tokio::pin!(accept_fut);
506        let result = tokio::select! {
507            result = &mut accept_fut => result,
508            () = fedimint_core::runtime::sleep(Duration::from_secs(300)) => {
509                warn!(
510                    target: LOG_CLIENT_MODULE_MINT,
511                    %txid,
512                    "Transaction not accepted or rejected after 5 minutes, possibly stuck or never submitted",
513                );
514                accept_fut.await
515            }
516        };
517        if result.is_err() {
518            return;
519        }
520        std::future::pending::<()>().await;
521    }
522
523    async fn transition_tx_rejected(
524        client_ctx: ClientContext<MintClientModule>,
525        dbtx: &mut ClientSMDatabaseTransaction<'_, '_>,
526        old_state: MintOutputStateMachine,
527    ) -> MintOutputStateMachine {
528        assert_matches!(old_state.state, MintOutputStates::CreatedMulti(_));
529
530        client_ctx
531            .log_event(
532                &mut dbtx.module_tx(),
533                ReceivePaymentUpdateEvent {
534                    operation_id: old_state.common.operation_id,
535                    status: ReceivePaymentStatus::Rejected,
536                },
537            )
538            .await;
539
540        MintOutputStateMachine {
541            common: old_state.common,
542            state: MintOutputStates::Aborted(MintOutputStatesAborted),
543        }
544    }
545
546    async fn await_outcome_ready(
547        global_context: DynGlobalClientContext,
548        common: MintOutputCommon,
549        module_decoder: Decoder,
550        issuance_requests: BTreeMap<u64, (Amount, NoteIssuanceRequest)>,
551        tbs_pks: BTreeMap<PeerId, Tiered<PublicKeyShare>>,
552    ) -> Vec<(u64, BTreeMap<PeerId, BlindedSignatureShare>)> {
553        let txid = common.txid();
554        let out_idx = common.out_point_range.start_idx();
555        let (_, first_request) = issuance_requests
556            .values()
557            .next()
558            .expect("A mint output state machine has at least one output");
559        await_tx_accepted_before_polling(
560            &global_context,
561            txid,
562            BlindNonce(first_request.blinded_message()),
563        )
564        .await;
565        debug!(target: LOG_CLIENT_MODULE_MINT, %txid, %out_idx, "Awaiting output outcome");
566        let api = global_context.api();
567        let core_api_version = global_context.core_api_version().await;
568
569        // Use the new efficient batch endpoint if the server supports it
570        if VERSION_THAT_INTRODUCED_AWAIT_OUTPUTS_OUTCOMES <= core_api_version {
571            Self::await_outcome_ready_batch(api, common, module_decoder, issuance_requests, tbs_pks)
572                .await
573        } else {
574            // Fall back to the old sequential approach for older servers
575            Self::await_outcome_ready_legacy(
576                api,
577                common,
578                module_decoder,
579                issuance_requests,
580                tbs_pks,
581            )
582            .await
583        }
584    }
585
586    /// Efficient batch version using `AWAIT_OUTPUTS_OUTCOMES_ENDPOINT`
587    async fn await_outcome_ready_batch(
588        api: &fedimint_api_client::api::DynGlobalApi,
589        common: MintOutputCommon,
590        module_decoder: Decoder,
591        issuance_requests: BTreeMap<u64, (Amount, NoteIssuanceRequest)>,
592        tbs_pks: BTreeMap<PeerId, Tiered<PublicKeyShare>>,
593    ) -> Vec<(u64, BTreeMap<PeerId, BlindedSignatureShare>)> {
594        if issuance_requests.is_empty() {
595            return vec![];
596        }
597
598        // Use custom query strategy to collect and verify outcomes from all guardians
599        let issuance_requests_clone = issuance_requests.clone();
600        // The verification is synchronous; the strategy awaits it.
601        let verify = move |peer: PeerId, outcomes: Vec<Option<SerdeOutputOutcome>>| {
602            // Verify the response has the expected length
603            if outcomes.len() != common.out_point_range.count() {
604                return Err(ServerError::InvalidResponse(format!(
605                    "Peer {peer} returned {} outcomes but expected {}",
606                    outcomes.len(),
607                    common.out_point_range.count()
608                )));
609            }
610
611            // Verify each outcome and extract valid blind signature shares
612            // If ANY share is invalid, reject the ENTIRE response from this guardian
613            let mut verified_shares = Vec::with_capacity(outcomes.len());
614            for (relative_idx, outcome_opt) in outcomes.into_iter().enumerate() {
615                let out_idx = common.out_point_range.start_idx() + relative_idx as u64;
616
617                // We should have an issuance request for every output in the range
618                let (amount, issuance_request) = issuance_requests_clone
619                    .get(&out_idx)
620                    .expect("issuance_request must exist for every output in range");
621
622                let share = if let Some(outcome) = outcome_opt {
623                    match verify_blind_share(
624                        peer,
625                        &outcome,
626                        *amount,
627                        issuance_request.blinded_message(),
628                        &module_decoder,
629                        &tbs_pks,
630                    ) {
631                        Ok(share) => Some(share),
632                        Err(err) => {
633                            // Invalid share - reject entire response from this guardian
634                            tracing::warn!(
635                                target: LOG_CLIENT_MODULE_MINT,
636                                %peer,
637                                err = %err.fmt_compact(),
638                                out_point = %OutPoint { txid: common.txid(), out_idx},
639                                "Invalid signature share from peer"
640                            );
641                            return Err(ServerError::InvalidResponse(
642                                err.fmt_compact().to_string(),
643                            ));
644                        }
645                    }
646                } else {
647                    None
648                };
649
650                verified_shares.push(share);
651            }
652
653            Ok(verified_shares)
654        };
655
656        let verified_shares_per_output: BTreeMap<PeerId, Vec<Option<BlindedSignatureShare>>> = api
657            .request_with_strategy_retry(
658                FilterMapThreshold::new(
659                    move |peer, outcomes| ready(verify(peer, outcomes)),
660                    api.all_peers().to_num_peers(),
661                ),
662                AWAIT_OUTPUTS_OUTCOMES_ENDPOINT.to_owned(),
663                ApiRequestErased::new(common.out_point_range),
664            )
665            .await;
666
667        // Reorganize from per-peer to per-output
668        let threshold = api.all_peers().to_num_peers().threshold();
669        let mut ret = vec![];
670
671        for (out_idx, (_amount, _issuance_request)) in issuance_requests {
672            let relative_idx = (out_idx - common.out_point_range.start_idx()) as usize;
673            let mut blinded_sig_shares = BTreeMap::new();
674
675            // Collect verified shares from all peers for this output
676            for (peer_id, shares) in &verified_shares_per_output {
677                if let Some(Some(share)) = shares.get(relative_idx) {
678                    blinded_sig_shares.insert(*peer_id, *share);
679                }
680            }
681
682            assert!(threshold <= blinded_sig_shares.len());
683            ret.push((out_idx, blinded_sig_shares));
684        }
685
686        ret
687    }
688
689    /// Legacy sequential version for backwards compatibility
690    async fn await_outcome_ready_legacy(
691        api: &fedimint_api_client::api::DynGlobalApi,
692        common: MintOutputCommon,
693        module_decoder: Decoder,
694        issuance_requests: BTreeMap<u64, (Amount, NoteIssuanceRequest)>,
695        tbs_pks: BTreeMap<PeerId, Tiered<PublicKeyShare>>,
696    ) -> Vec<(u64, BTreeMap<PeerId, BlindedSignatureShare>)> {
697        let mut ret = vec![];
698        let mut issuance_requests_iter = issuance_requests.into_iter();
699
700        // Wait for the result of the first output only, to save server side
701        // resources
702        if let Some((out_idx, (amount, issuance_request))) = issuance_requests_iter.next() {
703            let module_decoder = module_decoder.clone();
704            let tbs_pks = tbs_pks.clone();
705
706            let blinded_sig_share = api
707                .request_with_strategy_retry(
708                    FilterMapThreshold::new(
709                        move |peer, outcome| {
710                            ready(
711                                verify_blind_share(
712                                    peer,
713                                    &outcome,
714                                    amount,
715                                    issuance_request.blinded_message(),
716                                    &module_decoder,
717                                    &tbs_pks,
718                                )
719                                .map_err(|err| {
720                                    ServerError::InvalidResponse(err.fmt_compact().to_string())
721                                }),
722                            )
723                        },
724                        api.all_peers().to_num_peers(),
725                    ),
726                    AWAIT_OUTPUT_OUTCOME_ENDPOINT.to_owned(),
727                    ApiRequestErased::new(OutPoint {
728                        txid: common.txid(),
729                        out_idx,
730                    }),
731                )
732                .await;
733
734            ret.push((out_idx, blinded_sig_share));
735        } else {
736            return vec![];
737        }
738
739        // We know the tx outcomes are ready, get all of them at once
740        ret.extend(
741            join_all(
742                issuance_requests_iter.map(|(out_idx, (amount, issuance_request))| {
743                    let module_decoder = module_decoder.clone();
744                    let tbs_pks = tbs_pks.clone();
745                    async move {
746                        let blinded_sig_share = api
747                            .request_with_strategy_retry(
748                                FilterMapThreshold::new(
749                                    move |peer, outcome| {
750                                        ready(
751                                            verify_blind_share(
752                                                peer,
753                                                &outcome,
754                                                amount,
755                                                issuance_request.blinded_message(),
756                                                &module_decoder,
757                                                &tbs_pks,
758                                            )
759                                            .map_err(
760                                                |err| {
761                                                    ServerError::InvalidResponse(
762                                                        err.fmt_compact().to_string(),
763                                                    )
764                                                },
765                                            ),
766                                        )
767                                    },
768                                    api.all_peers().to_num_peers(),
769                                ),
770                                AWAIT_OUTPUT_OUTCOME_ENDPOINT.to_owned(),
771                                ApiRequestErased::new(OutPoint {
772                                    txid: common.txid(),
773                                    out_idx,
774                                }),
775                            )
776                            .await;
777
778                        (out_idx, blinded_sig_share)
779                    }
780                }),
781            )
782            .await,
783        );
784
785        ret
786    }
787
788    async fn transition_outcome_ready(
789        client_ctx: ClientContext<MintClientModule>,
790        dbtx: &mut ClientSMDatabaseTransaction<'_, '_>,
791        blinded_signature_shares: Vec<(u64, BTreeMap<PeerId, BlindedSignatureShare>)>,
792        old_state: MintOutputStateMachine,
793        tbs_pks: Tiered<AggregatePublicKey>,
794        balance_update_sender: tokio::sync::watch::Sender<()>,
795    ) -> MintOutputStateMachine {
796        // we combine the shares, finalize the issuance request with the blind signature
797        // and store the resulting note in the database
798
799        let mut amount_total = Amount::ZERO;
800        let MintOutputStates::CreatedMulti(created) = old_state.state else {
801            panic!("Unexpected prior state")
802        };
803
804        let mut spendable_notes: Vec<(Amount, SpendableNote)> = vec![];
805
806        // Note verification is relatively slow and CPU-bound, so parallelize them
807        blinded_signature_shares
808            .into_par_iter()
809            .map(|(out_idx, blinded_signature_shares)| {
810                let agg_blind_signature = aggregate_signature_shares(
811                    &blinded_signature_shares
812                        .into_iter()
813                        .map(|(peer, share)| (peer.to_usize() as u64, share))
814                        .collect(),
815                );
816
817                // this implies that the mint client config's public keys are inconsistent
818                let (amount, issuance_request) =
819                    created.issuance_requests.get(&out_idx).expect("Must have");
820
821                let amount_key = tbs_pks.tier(amount).expect("Must have keys for any amount");
822
823                let spendable_note = issuance_request.finalize(agg_blind_signature);
824
825                assert!(spendable_note.note().verify(*amount_key), "We checked all signature shares in the trigger future, so the combined signature has to be valid");
826
827                (*amount, spendable_note)
828            })
829            .collect_into_vec(&mut spendable_notes);
830
831        for (amount, spendable_note) in spendable_notes {
832            debug!(target: LOG_CLIENT_MODULE_MINT, amount = %amount, note=%spendable_note, "Adding new note from transaction output");
833
834            client_ctx
835                .log_event(
836                    &mut dbtx.module_tx(),
837                    NoteCreated {
838                        nonce: spendable_note.nonce(),
839                    },
840                )
841                .await;
842
843            amount_total += amount;
844            if let Some(note) = dbtx
845                .module_tx()
846                .insert_entry(
847                    &NoteKey {
848                        amount,
849                        nonce: spendable_note.nonce(),
850                    },
851                    &spendable_note.to_undecoded(),
852                )
853                .await
854            {
855                crit!(target: LOG_CLIENT_MODULE_MINT, %note, "E-cash note was replaced in DB");
856            }
857        }
858
859        client_ctx
860            .log_event(
861                &mut dbtx.module_tx(),
862                ReceivePaymentUpdateEvent {
863                    operation_id: old_state.common.operation_id,
864                    status: ReceivePaymentStatus::Success,
865                },
866            )
867            .await;
868
869        dbtx.module_tx()
870            .on_commit(move || balance_update_sender.send_replace(()));
871
872        MintOutputStateMachine {
873            common: old_state.common,
874            state: MintOutputStates::Succeeded(MintOutputStatesSucceeded {
875                amount: amount_total,
876            }),
877        }
878    }
879}
880
881/// # Panics
882/// If the given `outcome` is not a [`MintOutputOutcome::V0`] outcome.
883/// Longest wait between two checks of whether an output's blind nonce was
884/// used, see [`await_tx_accepted_before_polling`]
885const BLIND_NONCE_USED_CHECK_MAX_DELAY: Duration = Duration::from_hours(1);
886
887/// Waits until the transaction `txid` is known to be accepted
888///
889/// Long-polling a peer for the outcome of an output never returns while its
890/// transaction is not accepted, and occupies one of the peer's request slots
891/// on the client's connection for as long as it waits. So output state
892/// machines must not start long-polling for a transaction that may never get
893/// accepted.
894///
895/// The client learns of the acceptance from the transaction's submission
896/// state machine. Output state machines restored by recovery have none, so
897/// this also polls whether the federation has used `blind_nonce`, which it
898/// does exactly when it accepts a transaction issuing the output. That check
899/// answers immediately, and is repeated with a backoff of up to
900/// [`BLIND_NONCE_USED_CHECK_MAX_DELAY`].
901///
902/// If the transaction gets rejected this never returns, and the state
903/// machine's rejection transition fires instead.
904async fn await_tx_accepted_before_polling(
905    global_context: &DynGlobalClientContext,
906    txid: TransactionId,
907    blind_nonce: BlindNonce,
908) {
909    let submission_accepted = async {
910        if global_context.await_tx_accepted(txid).await.is_err() {
911            std::future::pending::<()>().await;
912        }
913    };
914
915    let blind_nonce_used = async {
916        let module_api = global_context.module_api();
917        let mut backoff = custom_backoff(
918            Duration::from_secs(1),
919            BLIND_NONCE_USED_CHECK_MAX_DELAY,
920            None,
921        );
922        loop {
923            match module_api.check_blind_nonce_used(blind_nonce).await {
924                Ok(true) => return,
925                Ok(false) => {
926                    debug!(target: LOG_CLIENT_MODULE_MINT, %txid, "Output's blind nonce not used yet");
927                }
928                Err(err) => {
929                    debug!(target: LOG_CLIENT_MODULE_MINT, %txid, err = %err.fmt_compact(), "Failed to check whether output's blind nonce was used");
930                }
931            }
932            fedimint_core::runtime::sleep(
933                backoff
934                    .next()
935                    .expect("Backoff without a retry limit never ends"),
936            )
937            .await;
938        }
939    };
940
941    tokio::select! {
942        () = submission_accepted => {},
943        () = blind_nonce_used => {},
944    }
945}
946
947pub fn verify_blind_share(
948    peer: PeerId,
949    outcome: &SerdeOutputOutcome,
950    amount: Amount,
951    blinded_message: BlindedMessage,
952    decoder: &Decoder,
953    peer_tbs_pks: &BTreeMap<PeerId, Tiered<PublicKeyShare>>,
954) -> Result<BlindedSignatureShare, VerifyBlindShareError> {
955    let outcome = deserialize_outcome::<MintOutputOutcome>(outcome, decoder)?;
956
957    let blinded_signature_share = outcome
958        .ensure_v0_ref()
959        .expect("We only process output outcome versions created by ourselves")
960        .0;
961
962    let amount_key = peer_tbs_pks
963        .get(&peer)
964        .ok_or(VerifyBlindShareError::UnknownPeer { peer })?
965        .tier(&amount)
966        .map_err(|_| VerifyBlindShareError::InvalidAmountTier { amount })?;
967
968    if !tbs::verify_signature_share(blinded_message, blinded_signature_share, *amount_key) {
969        return Err(VerifyBlindShareError::InvalidSignature);
970    }
971
972    Ok(blinded_signature_share)
973}
974
975/// See [`MintOutputStates`]
976#[derive(Debug, Clone, Eq, PartialEq, Hash, Decodable, Encodable)]
977pub struct MintOutputStatesAborted;
978
979/// See [`MintOutputStates`]
980#[derive(Debug, Clone, Eq, PartialEq, Hash, Decodable, Encodable)]
981pub struct MintOutputStatesFailed {
982    pub error: String,
983}
984
985/// See [`MintOutputStates`]
986#[derive(Debug, Clone, Eq, PartialEq, Hash, Decodable, Encodable)]
987pub struct MintOutputStatesSucceeded {
988    pub amount: Amount,
989}
990
991/// Keeps the data to generate [`SpendableNote`] once the
992/// mint successfully processed the transaction signing the corresponding
993/// [`BlindNonce`].
994#[derive(Debug, Copy, Clone, PartialEq, Eq, Deserialize, Serialize, Encodable, Decodable)]
995pub struct NoteIssuanceRequest {
996    /// Spend key from which the note nonce (corresponding public key) is
997    /// derived
998    spend_key: Keypair,
999    /// Key to unblind the blind signature supplied by the mint for this note
1000    blinding_key: BlindingKey,
1001}
1002
1003impl hash::Hash for NoteIssuanceRequest {
1004    fn hash<H: hash::Hasher>(&self, state: &mut H) {
1005        self.spend_key.hash(state);
1006        // ignore `blinding_key` as it doesn't impl Hash; `spend_key` has enough
1007        // entropy anyway
1008    }
1009}
1010impl NoteIssuanceRequest {
1011    /// Generate a request session for a single note and returns it plus the
1012    /// corresponding blinded message
1013    pub fn new<C>(ctx: &Secp256k1<C>, secret: &DerivableSecret) -> (NoteIssuanceRequest, BlindNonce)
1014    where
1015        C: Signing,
1016    {
1017        let spend_key = secret.child_key(SPEND_KEY_CHILD_ID).to_secp_key(ctx);
1018        let nonce = Nonce(spend_key.public_key());
1019        let blinding_key = BlindingKey(secret.child_key(BLINDING_KEY_CHILD_ID).to_bls12_381_key());
1020        let blinded_nonce = blind_message(nonce.to_message(), blinding_key);
1021
1022        let cr = NoteIssuanceRequest {
1023            spend_key,
1024            blinding_key,
1025        };
1026
1027        (cr, BlindNonce(blinded_nonce))
1028    }
1029
1030    /// Return nonce of the e-cash note being requested
1031    pub fn nonce(&self) -> Nonce {
1032        Nonce(self.spend_key.public_key())
1033    }
1034
1035    pub fn blinded_message(&self) -> BlindedMessage {
1036        blind_message(self.nonce().to_message(), self.blinding_key)
1037    }
1038
1039    /// Use the blind signature to create spendable e-cash notes
1040    pub fn finalize(&self, blinded_signature: BlindedSignature) -> SpendableNote {
1041        SpendableNote {
1042            signature: unblind_signature(self.blinding_key, blinded_signature),
1043            spend_key: self.spend_key,
1044        }
1045    }
1046
1047    pub fn blinding_key(&self) -> &BlindingKey {
1048        &self.blinding_key
1049    }
1050
1051    pub fn spend_key(&self) -> &Keypair {
1052        &self.spend_key
1053    }
1054}