1mod recovery_history_tracker;
2
3use std::collections::BTreeSet;
4use std::sync::{Arc, Mutex};
5
6use fedimint_bitcoind::{DynBitcoindRpc, create_esplora_rpc};
7use fedimint_client_module::module::ClientContext;
8use fedimint_client_module::module::init::ClientModuleRecoverArgs;
9use fedimint_client_module::module::init::recovery::{
10 RecoveryFromHistory, RecoveryFromHistoryCommon,
11};
12use fedimint_client_module::module::recovery::{DynModuleBackup, ModuleBackup};
13use fedimint_core::core::{IntoDynInstance, ModuleInstanceId, ModuleKind};
14use fedimint_core::db::{DatabaseTransaction, IDatabaseTransactionOpsCoreTyped as _};
15use fedimint_core::encoding::{Decodable, Encodable};
16use fedimint_core::util::{backoff_util, retry};
17use fedimint_core::{apply, async_trait_maybe_send};
18use fedimint_logging::{LOG_CLIENT_MODULE_WALLET, LOG_CLIENT_RECOVERY};
19use fedimint_wallet_common::{KIND, WalletInput, WalletInputV0};
20use futures::Future;
21use tracing::{debug, trace, warn};
22
23use self::recovery_history_tracker::ConsensusPegInTweakIdxesUsedTracker;
24use crate::client_db::{
25 NextPegInTweakIndexKey, PegInTweakIndexData, PegInTweakIndexKey, RecoveryFinalizedKey,
26 RecoveryStateKey, TweakIdx,
27};
28use crate::{WalletClientInit, WalletClientModule, WalletClientModuleData};
29
30#[derive(Clone, PartialEq, Eq, Debug, Encodable, Decodable)]
31pub enum WalletModuleBackup {
32 V0(WalletModuleBackupV0),
33 V1(WalletModuleBackupV1),
34 #[encodable_default]
35 Default {
36 variant: u64,
37 bytes: Vec<u8>,
38 },
39}
40
41impl IntoDynInstance for WalletModuleBackup {
42 type DynType = DynModuleBackup;
43
44 fn into_dyn(self, instance_id: ModuleInstanceId) -> Self::DynType {
45 DynModuleBackup::from_typed(instance_id, self)
46 }
47}
48
49impl ModuleBackup for WalletModuleBackup {
50 const KIND: Option<ModuleKind> = Some(KIND);
51}
52
53impl WalletModuleBackup {
54 pub fn new_v1(
55 session_count: u64,
56 next_tweak_idx: TweakIdx,
57 already_claimed_tweak_idxes: BTreeSet<TweakIdx>,
58 ) -> WalletModuleBackup {
59 WalletModuleBackup::V1(WalletModuleBackupV1 {
60 session_count,
61 next_tweak_idx,
62 already_claimed_tweak_idxes,
63 })
64 }
65}
66
67#[derive(Clone, PartialEq, Eq, Debug, Encodable, Decodable)]
68pub struct WalletModuleBackupV0 {
69 pub session_count: u64,
70 pub next_tweak_idx: TweakIdx,
71}
72
73#[derive(Clone, PartialEq, Eq, Debug, Encodable, Decodable)]
74pub struct WalletModuleBackupV1 {
75 pub session_count: u64,
76 pub next_tweak_idx: TweakIdx,
77 pub already_claimed_tweak_idxes: BTreeSet<TweakIdx>,
78}
79
80#[derive(Debug, Clone, Decodable, Encodable)]
81pub struct WalletRecoveryStateV0 {
82 snapshot: Option<WalletModuleBackup>,
83 next_unused_idx_from_backup: TweakIdx,
84 new_start_idx: Option<TweakIdx>,
85 tweak_idxes_with_pegins: Option<BTreeSet<TweakIdx>>,
86 tracker: ConsensusPegInTweakIdxesUsedTracker,
87}
88
89#[derive(Debug, Clone, Decodable, Encodable)]
90pub struct WalletRecoveryStateV1 {
91 snapshot: Option<WalletModuleBackup>,
92 next_unused_idx_from_backup: TweakIdx,
93 already_claimed_tweak_idxes_from_backup: Option<BTreeSet<TweakIdx>>,
96 new_start_idx: Option<TweakIdx>,
97 tweak_idxes_with_pegins: Option<BTreeSet<TweakIdx>>,
98 tracker: ConsensusPegInTweakIdxesUsedTracker,
99}
100
101#[derive(Debug, Clone, Decodable, Encodable)]
102pub enum WalletRecoveryState {
103 V0(WalletRecoveryStateV0),
104 V1(WalletRecoveryStateV1),
105 #[encodable_default]
106 Default {
107 variant: u64,
108 bytes: Vec<u8>,
109 },
110}
111
112#[derive(Clone, Debug)]
124pub struct WalletRecovery {
125 state: WalletRecoveryStateV1,
126 data: WalletClientModuleData,
127 btc_rpc: DynBitcoindRpc,
128}
129
130#[apply(async_trait_maybe_send!)]
131impl RecoveryFromHistory for WalletRecovery {
132 type Init = WalletClientInit;
133
134 async fn new(
135 init: &WalletClientInit,
136 args: &ClientModuleRecoverArgs<Self::Init>,
137 snapshot: Option<&WalletModuleBackup>,
138 ) -> anyhow::Result<(Self, u64)> {
139 trace!(target: LOG_CLIENT_MODULE_WALLET, "Starting new recovery");
140 let btc_rpc = init.0.clone().unwrap_or(create_esplora_rpc(
141 &WalletClientModule::get_rpc_config(args.cfg()).url,
142 )?);
143
144 let data = WalletClientModuleData {
145 cfg: args.cfg().clone(),
146 module_root_secret: args.module_root_secret().clone(),
147 };
148
149 #[allow(clippy::single_match_else)]
150 let (
151 next_unused_idx_from_backup,
152 start_session_idx,
153 already_claimed_tweak_idxes_from_backup,
154 ) = match snapshot.as_ref() {
155 Some(WalletModuleBackup::V0(backup)) => {
156 debug!(target: LOG_CLIENT_MODULE_WALLET, ?backup, "Restoring starting from an existing backup (v0)");
157
158 (
159 backup.next_tweak_idx,
160 backup.session_count.saturating_sub(1),
161 None,
162 )
163 }
164 Some(WalletModuleBackup::V1(backup)) => {
165 debug!(target: LOG_CLIENT_MODULE_WALLET, ?backup, "Restoring starting from an existing backup (v1)");
166
167 (
168 backup.next_tweak_idx,
169 backup.session_count.saturating_sub(1),
170 Some(backup.already_claimed_tweak_idxes.clone()),
171 )
172 }
173 _ => {
174 debug!(target: LOG_CLIENT_MODULE_WALLET, "Restoring without an existing backup");
175 (TweakIdx(0), 0, None)
176 }
177 };
178
179 let session_count = args
181 .context()
182 .global_api()
183 .session_count()
184 .await?
185 .max(start_session_idx);
187
188 debug!(target: LOG_CLIENT_MODULE_WALLET, next_unused_tweak_idx = ?next_unused_idx_from_backup, "Scanning federation history for used peg-in addresses");
189
190 Ok((
191 WalletRecovery {
192 state: WalletRecoveryStateV1 {
193 snapshot: snapshot.cloned(),
194 new_start_idx: None,
195 tweak_idxes_with_pegins: None,
196 next_unused_idx_from_backup,
197 already_claimed_tweak_idxes_from_backup,
198 tracker: ConsensusPegInTweakIdxesUsedTracker::new(
199 next_unused_idx_from_backup,
200 start_session_idx,
201 session_count,
202 &data,
203 ),
204 },
205 data,
206 btc_rpc,
207 },
208 start_session_idx,
209 ))
210 }
211
212 async fn load_dbtx(
213 init: &WalletClientInit,
214 dbtx: &mut DatabaseTransaction<'_>,
215 args: &ClientModuleRecoverArgs<Self::Init>,
216 ) -> anyhow::Result<Option<(Self, RecoveryFromHistoryCommon)>> {
217 trace!(target: LOG_CLIENT_MODULE_WALLET, "Loading recovery state");
218 let btc_rpc = init.0.clone().unwrap_or(create_esplora_rpc(
219 &WalletClientModule::get_rpc_config(args.cfg()).url,
220 )?);
221
222 let data = WalletClientModuleData {
223 cfg: args.cfg().clone(),
224 module_root_secret: args.module_root_secret().clone(),
225 };
226 Ok(dbtx.get_value(&RecoveryStateKey)
227 .await
228 .and_then(|(state, common)| {
229 if let WalletRecoveryState::V1(state) = state {
230 Some((state, common))
231 } else {
232 warn!(target: LOG_CLIENT_RECOVERY, "Found unknown version recovery state. Ignoring");
233 None
234 }
235 })
236 .map(|(state, common)| {
237 (
238 WalletRecovery {
239 state,
240 data,
241 btc_rpc,
242 },
243 common,
244 )
245 }))
246 }
247
248 async fn store_dbtx(
249 &self,
250 dbtx: &mut DatabaseTransaction<'_>,
251 common: &RecoveryFromHistoryCommon,
252 ) {
253 trace!(target: LOG_CLIENT_MODULE_WALLET, "Storing recovery state");
254 dbtx.insert_entry(
255 &RecoveryStateKey,
256 &(WalletRecoveryState::V1(self.state.clone()), common.clone()),
257 )
258 .await;
259 }
260
261 async fn delete_dbtx(&self, dbtx: &mut DatabaseTransaction<'_>) {
262 dbtx.remove_entry(&RecoveryStateKey).await;
263 }
264
265 async fn load_finalized(dbtx: &mut DatabaseTransaction<'_>) -> Option<bool> {
266 dbtx.get_value(&RecoveryFinalizedKey).await
267 }
268
269 async fn store_finalized(dbtx: &mut DatabaseTransaction<'_>, state: bool) {
270 dbtx.insert_entry(&RecoveryFinalizedKey, &state).await;
271 }
272
273 async fn handle_input(
274 &mut self,
275 _client_ctx: &ClientContext<WalletClientModule>,
276 _idx: usize,
277 input: &WalletInput,
278 session_idx: u64,
279 ) -> anyhow::Result<()> {
280 let script_pubkey = match input {
281 WalletInput::V0(WalletInputV0(input)) => &input.tx_output().script_pubkey,
282 WalletInput::V1(input) => &input.tx_out.script_pubkey,
283 WalletInput::Default {
284 variant: _,
285 bytes: _,
286 } => {
287 return Ok(());
288 }
289 };
290
291 self.state
292 .tracker
293 .handle_script(&self.data, script_pubkey, session_idx);
294
295 Ok(())
296 }
297
298 async fn pre_finalize(&mut self) -> anyhow::Result<()> {
299 let data = &self.data;
300 let btc_rpc = &self.btc_rpc;
301 let tracker = &Arc::new(Mutex::new(self.state.tracker.clone()));
304
305 debug!(target: LOG_CLIENT_MODULE_WALLET,
306 next_unused_tweak_idx = ?self.state.next_unused_idx_from_backup,
307 "Scanning blockchain for used peg-in addresses");
308 let RecoverScanOutcome { last_used_idx: _, new_start_idx, tweak_idxes_with_pegins}
309 = recover_scan_idxes_for_activity(
310 if self.state.already_claimed_tweak_idxes_from_backup.is_some() {
311 TweakIdx(0)
315 } else {
316 self.state.next_unused_idx_from_backup
318 },
319 &self.state.tracker.used_tweak_idxes()
320 .union(&self.state.already_claimed_tweak_idxes_from_backup.clone().unwrap_or_default())
321 .copied().collect(),
322 |cur_tweak_idx: TweakIdx|
323 async move {
324
325 let (script, address, _tweak_key, _operation_id) =
326 data.derive_peg_in_script(cur_tweak_idx);
327
328 let use_decoy_before_real_query : bool = rand::random();
330 let decoy = tracker.lock().expect("locking failed").pop_decoy();
331
332 let use_decoy = || async {
333 if let Some(decoy) = decoy.as_ref() {
334 btc_rpc.watch_script_history(decoy).await?;
335 let _ = btc_rpc.get_script_history(decoy).await?;
336 }
337 Ok::<_, anyhow::Error>(())
338 };
339
340 if use_decoy_before_real_query {
341 use_decoy().await?;
342 }
343 btc_rpc.watch_script_history(&script).await?;
344 let history = btc_rpc.get_script_history(&script).await?;
345
346 if !use_decoy_before_real_query {
347 use_decoy().await?;
348 }
349
350 debug!(target: LOG_CLIENT_MODULE_WALLET, %cur_tweak_idx, %address, history_len=history.len(), "Checked address");
351
352 Ok(history)
353 }).await?;
354
355 self.state.new_start_idx = Some(new_start_idx);
356 self.state.tweak_idxes_with_pegins = Some(tweak_idxes_with_pegins);
357
358 Ok(())
359 }
360
361 async fn finalize_dbtx(&self, dbtx: &mut DatabaseTransaction<'_>) -> anyhow::Result<()> {
362 let now = fedimint_core::time::now();
363
364 let mut tweak_idx = TweakIdx(0);
365
366 let new_start_idx = self
367 .state
368 .new_start_idx
369 .expect("Must have new_star_idx already set by previous steps");
370
371 let tweak_idxes_with_pegins = self
372 .state
373 .tweak_idxes_with_pegins
374 .clone()
375 .expect("Must be set by previous steps");
376
377 debug!(target: LOG_CLIENT_MODULE_WALLET, ?new_start_idx, "Finalizing recovery");
378
379 while tweak_idx < new_start_idx {
380 let (_script, _address, _tweak_key, operation_id) =
381 self.data.derive_peg_in_script(tweak_idx);
382 dbtx.insert_new_entry(
383 &PegInTweakIndexKey(tweak_idx),
384 &PegInTweakIndexData {
385 creation_time: now,
386 next_check_time: if tweak_idxes_with_pegins.contains(&tweak_idx) {
387 Some(now)
392 } else {
393 None
394 },
395 last_check_time: None,
396 operation_id,
397 claimed: vec![],
398 },
399 )
400 .await;
401 tweak_idx = tweak_idx.next();
402 }
403
404 dbtx.insert_new_entry(&NextPegInTweakIndexKey, &new_start_idx)
405 .await;
406 Ok(())
407 }
408}
409
410pub(crate) const ONCHAIN_RECOVER_MAX_GAP: u64 = 10;
413
414pub(crate) const FEDERATION_RECOVER_MAX_GAP: u64 = 50;
418
419pub(crate) const RECOVER_NUM_IDX_ADD_TO_LAST_USED: u64 = 8;
425
426#[derive(Clone, PartialEq, Eq, Debug)]
427pub(crate) struct RecoverScanOutcome {
428 pub(crate) last_used_idx: Option<TweakIdx>,
429 pub(crate) new_start_idx: TweakIdx,
430 pub(crate) tweak_idxes_with_pegins: BTreeSet<TweakIdx>,
431}
432
433pub(crate) async fn recover_scan_idxes_for_activity<F, FF, T>(
436 scan_from_idx: TweakIdx,
437 used_tweak_idxes: &BTreeSet<TweakIdx>,
438 check_addr_history: F,
439) -> anyhow::Result<RecoverScanOutcome>
440where
441 F: Fn(TweakIdx) -> FF,
442 FF: Future<Output = anyhow::Result<Vec<T>>>,
443{
444 let tweak_indexes_to_scan = (scan_from_idx.0..).map(TweakIdx).filter(|tweak_idx| {
445 let already_used = used_tweak_idxes.contains(tweak_idx);
446
447 if already_used {
448 debug!(target: LOG_CLIENT_MODULE_WALLET,
449 %tweak_idx,
450 "Skipping checking history of an address, as it was previously used"
451 );
452 }
453
454 !already_used
455 });
456
457 let mut last_used_idx = used_tweak_idxes.last().copied();
461 let fallback_last_used_idx = scan_from_idx.prev().unwrap_or_default();
464 let mut tweak_idxes_with_pegins = BTreeSet::new();
465
466 for cur_tweak_idx in tweak_indexes_to_scan {
467 if ONCHAIN_RECOVER_MAX_GAP
468 <= cur_tweak_idx.saturating_sub(last_used_idx.unwrap_or(fallback_last_used_idx))
469 {
470 break;
471 }
472
473 let history = retry(
474 "Check address history",
475 backoff_util::background_backoff(),
476 || async { check_addr_history(cur_tweak_idx).await },
477 )
478 .await?;
479
480 if !history.is_empty() {
481 tweak_idxes_with_pegins.insert(cur_tweak_idx);
482 last_used_idx = Some(cur_tweak_idx);
483 }
484 }
485
486 let new_start_idx = last_used_idx
487 .unwrap_or(fallback_last_used_idx)
488 .advance(RECOVER_NUM_IDX_ADD_TO_LAST_USED);
489
490 Ok(RecoverScanOutcome {
491 last_used_idx,
492 new_start_idx,
493 tweak_idxes_with_pegins,
494 })
495}