Let the wallet save more scanned block headers by spare headers beyond a day

[SWvheerden]

Bounty: Wallet Sparse Scanned Block Header Storage

Tier: M — 60,000 XTM

Description

The wallet currently saves only the last 720 scanned block headers. If the wallet needs to rescan beyond that window, it falls back to scanning from the wallet birthday, which is slow. Implement a sparse storage strategy that keeps all headers for recent blocks and progressively fewer headers for older blocks, so the wallet almost always has a recent-enough starting point for rescans.

Acceptance Criteria

• tip - 720 to tip: all block headers are saved
• tip - 10,000 to tip - 720: 1 header per 100 blocks is saved
• tip - 100,000 to tip - 10,000: 1 header per 1,000 blocks is saved
• genesis to tip - 100,000: 1 header per 5,000 blocks is saved
• When the wallet initiates a scan, it finds the most recent saved header and starts from there instead of the birthday

Context

• Issue opened by @SWvheerden
• Related to Wallet UTXO scanner wipes scan progress when connecting to a node with a lower tip #7685 (wallet UTXO scanner wipes scan progress when connecting to a node with a lower tip)
• Relevant code: wallet scanning logic in base_layer/wallet/

How to Claim

1. Comment on this issue to signal intent (courtesy, not a lock)
2. Fork the repo and do the work
3. Submit a PR that meets the acceptance criteria
4. First PR that passes review and gets merged wins the bounty
5. On acceptance, XTM payment is processed

Notes

• AI-assisted development is expected and encouraged
• If you get stuck, ask in Discord
• If you can't complete it within 14 days of claiming, let us know so someone else can pick it up

[metalaureate]

Original issue description (preserved before bounty rewrite)

Description

The wallet saves the list of scanned block headers, but it only saves the last 720. We need to save more using a sparse storage strategy beyond the most recent 720 blocks. This reduces the chance of having to rescan from the wallet birthday, since we only need to reorg back to the last scanned height.

Proposed sparse schedule:

• tip - 720 → tip: all blocks
• tip - 10,000 → tip - 720: save every 1 header out of 100
• tip - 100,000 → tip - 10,000: save every 1 header out of 1,000
• genesis → tip - 100,000: save 1 header every 5,000 blocks

When the wallet wants to do a scan, it searches the database for the last block scanned. By saving a sparsely populated list of headers beyond 720, we reduce the chance of having to scan from the birthday again.

Acceptance criteria

• The wallet saves a sparsely populated list of headers beyond the last 720 blocks using the schedule described above

Size: M

[Ltbltbltbltb]

The sparse block header storage strategy you've outlined—maintaining 100% density for recent blocks while progressively reducing to 1-per-5000 for genesis-era headers—solves the rescan bottleneck by ensuring the wallet almost always has a recent checkpoint. I'll implement this tiered retention model directly into the wallet scanning logic.

Technical approach:

1. Extend header storage in base_layer/wallet/ with a density-aware pruning mechanism enforcing your four tiers
2. Update rescan initialization to find the most recent stored header and start from there, eliminating birthday fallback
3. Integrate pruning logic into the block arrival handler to maintain tier compliance without performance impact
4. Validate all acceptance criteria under edge cases (long gaps, chain reorgs, rescan scenarios)

This keeps the solution focused—pure storage policy enforcement, no architectural changes to scanning logic.

Time estimate: 2-3 days including comprehensive testing.

One technical question: Should the sparse storage policy apply retroactively to existing headers during upgrade, or only to newly-arrived blocks?

[0xPepeSilvia]

Claiming this bounty. Will have a PR up within the 14-day window.