Skip to content

feat: end-to-end dust protection (classification, restrictions, donation, report)#6989

Open
Parsh wants to merge 44 commits into
sprintfrom
feat/dust-limit-protection
Open

feat: end-to-end dust protection (classification, restrictions, donation, report)#6989
Parsh wants to merge 44 commits into
sprintfrom
feat/dust-limit-protection

Conversation

@Parsh
Copy link
Copy Markdown
Collaborator

@Parsh Parsh commented May 26, 2026

Summary

This PR delivers the complete dust-protection feature set for Keeper across wallet sync, coin selection, UTXO management, send flow, transaction history, and wallet settings.

It combines five related OpenSpec changes into one cohesive rollout:

  • dust-utxo-classification
  • dust-spend-restrictions
  • dust-donation
  • dust-descendant-classification
  • dust-analysis-report

Problem

Dust attacks can reduce user privacy by encouraging linkage when suspicious small UTXOs are spent. Prior behavior lacked end-to-end protection and clear user actions.

What’s Included

1) Automatic dust detection + manual spendability control

  • Adds UTXO spendability state and manual override support.
  • Classifies suspicious dust outputs during wallet refresh.
  • Preserves manual overrides across refresh/hard refresh.
  • Adds user action to mark UTXO as Do Not Spend / Spendable.
  • Surfaces a one-time toast when new suspicious dust is detected.

2) Spend restrictions in send flow

  • Excludes Do Not Spend UTXOs from automatic coin selection.
  • Uses spendable-only balance in send amount flow.
  • Adds manual-selection warning modal before selecting a Do Not Spend coin.

3) Dust donation flow

  • Adds contextual Donate Dust CTA in Manage Coins.
  • Builds donation tx using only Do Not Spend UTXOs at low fee tier.
  • Handles eligibility check and too-small-to-donate path.
  • Reuses SendConfirmation in locked donation mode.

4) Address-level taint + descendant propagation

  • Moves from per-UTXO-only logic to address-level tainting.
  • Introduces transaction wallet-output data and hard-refresh backfill.
  • Propagates taint forward through transaction graph (BFS) with manual-override chain break.
  • Marks transactions as Potential dust spend when tainted senders are involved.
  • Adds nuanced dust reasons for UTXOs (initial, adjacent, descendant).

5) Dust Report (wallet/vault settings)

  • Adds Dust Report entry point from Wallet/Vault Settings.
  • Implements phases: start, scanning, result, empty, error.
  • Shows summary + sections for Active Dust, Linked Coins, and Past Dust Spends.
  • Persists last-scanned timestamp in MMKV.
  • Includes inline Donate Dust confirmation from report results.

Architecture / Data Changes

  • Realm schema updates for UTXO spendability fields and transaction wallet outputs.
  • Dust classification utility refactor to address-taint model.
  • Saga updates for snapshot restore, scan-mode behavior, backfill, and tagging.
  • UI updates across Home wallet card, Wallet Details/More options, UTXO screens, Send, and Dust Report.
  • Localization updates (EN/ES).

Testing

Automated tests added/updated

  • Dust classification logic (including descendant/address-taint scenarios).
  • Donation flow eligibility and send-confirmation donation mode.
  • UTXO footer Donate Dust visibility.
  • Dust report derivation and screen behavior.
  • UTXO spendability hook logic.

Maestro flows added

  • flows/dustUTXOClassification.yaml
  • flows/dustSpendRestrictions.yaml
  • flows/dustDonation.yaml
  • flows/dustDescendantClassification.yaml
  • flows/dustAnalysisReport.yaml
  • flows/dustSanity.yaml

Notes

  • This PR is intentionally broad because these features are tightly coupled and designed to ship as one privacy-protection experience.
  • Existing open-spec artifacts for all five changes are included for traceability and implementation parity.

Parsh added 25 commits May 19, 2026 10:05
…nt and toast notifications for new dust UTXOs
…on capabilities

- Implemented dust report UI and logic in DustReportScreen
- Added useDustReport hook for handling dust report data
- Enhanced localization files for English and Spanish
- Integrated dust report navigation in WalletSettings
- Created unit tests for dust report logic
…assification

Implement address-level taint model and enhance dust UTXO management
Implement Donate Dust feature for clearing Do Not Spend UTXOs
Implement Do Not Spend UTXO restrictions and enhance UI warnings
@Parsh Parsh requested a review from cakesoft-vaibhav May 26, 2026 15:38
@cakesoft-vaibhav cakesoft-vaibhav requested review from ben-kaufman and removed request for cakesoft-vaibhav May 27, 2026 05:23
@Parsh Parsh marked this pull request as draft May 27, 2026 05:54
@Parsh Parsh marked this pull request as ready for review May 27, 2026 11:37
ben-kaufman
ben-kaufman previously approved these changes May 29, 2026
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.

3 participants