Skip to content

Add FastSync scanning mode for rapid wallet balance recovery#101

Draft
Copilot wants to merge 2 commits intomainfrom
copilot/add-fast-sync-support
Draft

Add FastSync scanning mode for rapid wallet balance recovery#101
Copilot wants to merge 2 commits intomainfrom
copilot/add-fast-sync-support

Conversation

Copy link
Contributor

Copilot AI commented Mar 16, 2026

Normal wallet scanning must traverse every block from birthday to tip to build the UTXO set, which is slow for wallets with long history. This adds a three-phase FastSync mode that delivers an accurate current balance quickly, then fills in complete history as a second pass.

Scan phases

  1. Phase 1+2 – Quick balance (birthday → tip): Single continuous scan establishing the unspent UTXO set up to tip - safety_buffer, then the recent blocks to tip. After this phase the balance is accurate.
  2. Phase 3 – History fill (birthday → tip): Full rescan from birthday to ensure complete transaction/spending history.

New ScanMode::FastSync

// Default safety buffer: 720 blocks (~12h on mainnet)
let scanner = Scanner::new(password, base_url, db_path, batch_size, confirmations)
    .mode(ScanMode::FastSync { safety_buffer: 720 });

CLI

minotari scan --password mypassword --fast-sync
minotari scan --password mypassword --fast-sync --fast-sync-safety-buffer 360

Config

[wallet]
# fast_sync_safety_buffer = 720

Key changes

  • scan/config.rs: New ScanMode::FastSync { safety_buffer: u64 } variant; DEFAULT_FAST_SYNC_SAFETY_BUFFER = 720
  • scan/coordinator.rs: run_fast_sync() captures Phase 3 target data (account, key manager, birthday height) before Phase 1+2 consumes the targets, then reconstructs fresh targets for the history pass
  • db/accounts.rs: Added Clone to AccountRow (required to snapshot target metadata before consuming sync_targets)
  • cli.rs / main.rs: --fast-sync / --fast-sync-safety-buffer flags; fast_sync_scan() helper
  • config/defaults.rs: fast_sync_safety_buffer: Option<u64> in WalletConfig; CLI flag takes precedence over config, config over the compiled default
Original prompt

This section details on the original issue you should resolve

<issue_title>support for fast sync</issue_title>
<issue_description>The normal scanning method for the wallet would be to start at the wallet birthday and then scan output for output till we reach the tip saving all outptus that belong to this wallet, and as we progress on in the scan we update all spent utxos.

Add a new scanning method for grpc and http that will do the following:

  • Calculate a new fast_sync_target_height as tip - fast_sync_safety_buffer. Default to 720 blocks
  • Scan the wallet from birthday to fast_sync_target_height asking the base node for unspent utxos only at fast_sync_target_height.
  • Scan the wallet from fast_sync_target_height to tip using full scan,
  • Do a full scan from birthday to tip to allow the wallet to fill in the history of the wallet </issue_description>

Comments on the Issue (you are @copilot in this section)


📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

Co-authored-by: SWvheerden <2579813+SWvheerden@users.noreply.github.com>
Copilot AI changed the title [WIP] Add support for fast sync method in wallet Add FastSync scanning mode for rapid wallet balance recovery Mar 16, 2026
Copilot AI requested a review from SWvheerden March 16, 2026 09:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

support for fast sync

2 participants