Dust Attack Protection: Classification of Unspent UTXOs (Automatic & Manual)

[Parsh]

Context

Part of #6965 — Dust Attack Protection and Donate Dust.

This issue covers automatic detection and manual classification of current wallet-owned UTXOs that have not yet been spent. See also:

• Dust Spend Restrictions (UTXO management during send)
• Dust Donation
• Dust Classification: Already-Spent UTXOs & Descendant Marking

---

Goal

Every current wallet-owned UTXO should have a persisted spendability state:

• Spendable
• Do Not Spend

Keeper should automatically classify UTXOs during wallet scans and allow users to manually override the state from UTXO Details.

---

Detection Rule

Mark a UTXO Do Not Spend when:

Amount is under 5,000 sats, and either:

Receive address rule

• the receive address has already received before, OR
• the receive address index is lower than the highest receive address index that has already received

Change address rule

• the change address has already received before

Do not apply out-of-order detection to change addresses.
Do not use fiat value. Use sats only.
Do not detect mass-dusting transaction patterns in this version.

---

Address Metadata

Store lightweight address metadata per wallet to make detection efficient:

• address
• addressIndex
• addressType (receive / change)
• hasReceivedBefore
• highestReceivedReceiveAddressIndex
• previousReceiveCount

Avoid scanning full history repeatedly when stored state can answer the rule.

---

Scan Points

Run classification during:

• wallet creation
• wallet import / restore
• wallet opened after app update (classify UTXOs without state)
• normal wallet refresh
• pull-to-refresh
• new incoming transaction scan

No separate global upgrade script is required.

---

Classification Logic

When wallet scan runs:

• check current wallet-owned UTXOs
• if UTXO already has state, keep it (preserve user overrides)
• if UTXO has no state, classify it
• persist the result

---

New Incoming Dust Toast

Show a one-time toast when a new potential dust payment is detected during wallet refresh:

Potential dust payment found

• Show once per newly detected UTXO
• Do not repeat for already-known Do Not Spend coins
• Do not show during import/restore to avoid noise

---

UI Indicators

Wallet Home List

• Show customary red dot on wallet card/item if any current Do Not Spend UTXO exists

Wallet Details

• Show non-tappable line below wallet name/subtitle when wallet has any current Do Not Spend coin:

  Includes Do Not Spend coins

More Options Bottom Sheet

• Show customary red dot on View All Coins if wallet has any current Do Not Spend UTXO

Manage Coins

• Show all wallet-owned UTXOs
• Show Do Not Spend label clearly on affected coins using warning-style label treatment
• Existing labels (Change, Self) continue to work alongside it
• Do Not Spend coins remain visible

UTXO Details — Spendable Coin

• Show button: Mark Do Not Spend
• On action, update state and stay on UTXO Details
• Success feedback: Coin marked Do Not Spend

UTXO Details — Do Not Spend Coin

• Show reason line (one of):
  • Potential dust payment
  • Marked manually
• Show explanation: Keeper marked this coin Do Not Spend to help protect wallet privacy.
• Show button: Mark Spendable
• On action, persist override and stay on UTXO Details
• Success feedback: Coin marked spendable
• System-marked Do Not Spend must not be removable like a normal label/tag — user must use the explicit CTA

---

Manual Override Rules

• Manual Do Not Spend state persists across refreshes
• Manual state is not removed by automatic classification
• Once user marks it spendable, do not automatically re-mark on the next scan

---

Acceptance Criteria

• Every current wallet-owned UTXO has either Spendable or Do Not Spend state after scan
• UTXO under 5,000 sats on reused receive address is marked Do Not Spend
• UTXO under 5,000 sats on earlier receive address (after a later receive address has already received) is marked Do Not Spend
• UTXO under 5,000 sats on reused change address is marked Do Not Spend
• UTXO under 5,000 sats on normal fresh receive address is marked Spendable
• UTXO under 5,000 sats on non-reused change address is marked Spendable
• UTXO above 5,000 sats on reused or out-of-order address is marked Spendable
• Dust classification runs after wallet creation scan
• Dust classification runs after wallet import / restore scan
• Existing wallet after app update classifies UTXOs without spendability state
• New potential dust detected during refresh is marked Do Not Spend with toast
• Toast does not repeat for already-known Do Not Spend coins
• User override persists after refresh
• Red dot appears on wallet card when current Do Not Spend coins exist
• Includes Do Not Spend coins appears in Wallet Details when relevant
• Red dot appears on View All Coins in More Options when relevant
• Do Not Spend label appears on affected coins in Manage Coins
• Spendable coin in UTXO Details shows Mark Do Not Spend
• Do Not Spend coin in UTXO Details shows Mark Spendable and correct reason
• Mark Spendable persists after refresh
• System-marked Do Not Spend cannot be removed like a normal label

---

Copy Requirements

Use these exact labels:

• Spendable
• Do Not Spend
• Mark Do Not Spend
• Mark Spendable
• Includes Do Not Spend coins
• Potential dust payment found (toast)
• Potential dust payment (reason)
• Marked manually (reason)

Use these exact explanation lines:

• Keeper marked this coin Do Not Spend to help protect wallet privacy.

Do not use: crypto, cryptocurrency, vault, infected, quarantine, low/medium/high risk, economic dust, clean coins, dust score.

---

Design Requirements

• Reuse existing Keeper screens and patterns
• Use existing red dot indicator
• Use existing UTXO label/chip component
• Use warning-style treatment for Do Not Spend
• Do not create a new dust dashboard
• No new assets required